feat(locale): 🎸 improve strict mode types for pipes

Keep null and undefined intact and provide overloads with null and
undefined values for all pipes.

BREAKING CHANGE: 🧨 Pipes return null or undefined instead of an empty string if the input
is null or undefined

✅ Closes: #755

Author: Kaemmelot

libs/transloco-locale/src/lib/pipes/transloco-currency.pipe.ts

@@ -12,6 +12,8 @@ import {
 
 import { BaseLocalePipe } from './base-locale.pipe';
 
+type CurrencyDisplayType = 'code' | 'symbol' | 'narrowSymbol' | 'name';
+
 @Pipe({
   name: 'translocoCurrency',
   pure: false,
@@ -35,14 +37,37 @@ export class TranslocoCurrencyPipe
    * 1000000 | translocoCurrency: 'narrowSymbol' : {minimumFractionDigits: 0 } : CAD // $1,000,000
    *
    */
+  // overloads for strict mode
   transform(
     value: number | string,
-    display: 'code' | 'symbol' | 'narrowSymbol' | 'name' = 'symbol',
+    display?: CurrencyDisplayType,
+    numberFormatOptions?: NumberFormatOptions,
+    currencyCode?: Currency,
+    locale?: Locale
+  ): string;
+  transform<T extends null | undefined>(
+    value: T,
+    display?: CurrencyDisplayType,
+    numberFormatOptions?: NumberFormatOptions,
+    currencyCode?: Currency,
+    locale?: Locale
+  ): T;
+  transform<T extends null | undefined>(
+    value: number | string | T,
+    display?: CurrencyDisplayType,
+    numberFormatOptions?: NumberFormatOptions,
+    currencyCode?: Currency,
+    locale?: Locale
+  ): string | T;
+
+  transform(
+    value?: number | string | null,
+    display: CurrencyDisplayType = 'symbol',
     numberFormatOptions: NumberFormatOptions = {},
     currencyCode?: Currency,
     locale?: Locale
-  ): string {
-    if (isNil(value)) return '';
+  ): string | null | undefined {
+    if (isNil(value)) return value;
     locale = this.getLocale(locale);
 
     const options = {

libs/transloco-locale/src/lib/pipes/transloco-date.pipe.ts

@@ -34,8 +34,29 @@ export class TranslocoDatePipe extends BaseLocalePipe implements PipeTransform {
    * 1 | translocoDate: { dateStyle: 'medium' } // Jan 1, 1970
    * '2019-02-08' | translocoDate: { dateStyle: 'medium' } // Feb 8, 2019
    */
-  transform(date: ValidDate, options: DateFormatOptions = {}, locale?: Locale) {
-    if (isNil(date)) return '';
+  // overloads for strict mode
+  transform(
+    date: ValidDate,
+    options?: DateFormatOptions,
+    locale?: Locale
+  ): string;
+  transform<T extends null | undefined>(
+    date: T,
+    options?: DateFormatOptions,
+    locale?: Locale
+  ): T;
+  transform<T extends null | undefined>(
+    date: ValidDate | T,
+    options?: DateFormatOptions,
+    locale?: Locale
+  ): string | T;
+
+  transform(
+    date: ValidDate | null | undefined,
+    options: DateFormatOptions = {},
+    locale?: Locale
+  ): string | null | undefined {
+    if (isNil(date)) return date;
     locale = this.getLocale(locale);
 
     return this.localeService.localizeDate(date, locale, {

libs/transloco-locale/src/lib/pipes/transloco-decimal.pipe.ts

@@ -31,12 +31,29 @@ export class TranslocoDecimalPipe
    * 1234567890 | translocoDecimal: {useGrouping: false}: en-US // 1234567890
    *
    */
+  // overloads for strict mode
   transform(
-    value: string | number,
+    value: number | string,
+    numberFormatOptions?: NumberFormatOptions,
+    locale?: Locale
+  ): string;
+  transform<T extends null | undefined>(
+    value: T,
+    numberFormatOptions?: NumberFormatOptions,
+    locale?: Locale
+  ): T;
+  transform<T extends null | undefined>(
+    value: number | string | T,
+    numberFormatOptions?: NumberFormatOptions,
+    locale?: Locale
+  ): string | T;
+
+  transform(
+    value?: string | number | null,
     numberFormatOptions: NumberFormatOptions = {},
     locale?: Locale
-  ): string {
-    if (isNil(value)) return '';
+  ): string | null | undefined {
+    if (isNil(value)) return value;
     locale = this.getLocale(locale);
 
     const options = {

libs/transloco-locale/src/lib/pipes/transloco-percent.pipe.ts

@@ -31,12 +31,29 @@ export class TranslocoPercentPipe
    * "1" | translocoPercent : {} : en-US // 100%
    *
    */
+  // overloads for strict mode
   transform(
     value: number | string,
+    numberFormatOptions?: NumberFormatOptions,
+    locale?: Locale
+  ): string;
+  transform<T extends null | undefined>(
+    value: T,
+    numberFormatOptions?: NumberFormatOptions,
+    locale?: Locale
+  ): T;
+  transform<T extends null | undefined>(
+    value: number | string | T,
+    numberFormatOptions?: NumberFormatOptions,
+    locale?: Locale
+  ): string | T;
+
+  transform(
+    value?: number | string | null,
     numberFormatOptions: NumberFormatOptions = {},
     locale?: Locale
-  ): string {
-    if (isNil(value)) return '';
+  ): string | null | undefined {
+    if (isNil(value)) return value;
     locale = this.getLocale(locale);
 
     const options = {

libs/transloco-locale/src/lib/tests/pipes/transloco-currency.pipe.spec.ts

@@ -1,4 +1,7 @@
 import { SpectatorPipe } from '@ngneat/spectator';
+import { ChangeDetectorRef } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { Mock } from 'ts-mocks';
 
 import { TranslocoCurrencyPipe } from '../../pipes/transloco-currency.pipe';
 import { LOCALE_CONFIG_MOCK, provideTranslocoServiceMock } from '../mocks';
@@ -60,17 +63,30 @@ describe('TranslocoCurrencyPipe', () => {
   });
 
   describe('None transformable values', () => {
+    let pipe: TranslocoCurrencyPipe;
+    let cdrMock: ChangeDetectorRef;
+
+    beforeEach(() => {
+      cdrMock = new Mock<ChangeDetectorRef>({
+        markForCheck: () => {},
+      }).Object;
+
+      TestBed.configureTestingModule({
+        providers: [{ provide: ChangeDetectorRef, useValue: cdrMock }],
+      });
+      pipe = TestBed.runInInjectionContext(() => new TranslocoCurrencyPipe());
+    });
     it('should handle null', () => {
-      spectator = pipeFactory(`{{ null | translocoCurrency }}`);
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform(null)).toBeNull();
+    });
+    it('should handle undefined', () => {
+      expect(pipe.transform(undefined)).toBeUndefined();
     });
     it('should handle {}', () => {
-      spectator = pipeFactory(`{{ {} | translocoCurrency }}`);
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform({} as any)).toBe('');
     });
     it('should handle none number string', () => {
-      spectator = pipeFactory(`{{ 'none number string' | translocoCurrency }}`);
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform('none number string')).toBe('');
     });
   });
 

libs/transloco-locale/src/lib/tests/pipes/transloco-date.pipe.spec.ts

@@ -1,4 +1,7 @@
 import { SpectatorPipe } from '@ngneat/spectator';
+import { ChangeDetectorRef } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { Mock } from 'ts-mocks';
 
 import { TranslocoDatePipe } from '../../pipes';
 import {
@@ -88,17 +91,30 @@ describe('TranslocoDatePipe', () => {
   });
 
   describe('None date values', () => {
+    let pipe: TranslocoDatePipe;
+    let cdrMock: ChangeDetectorRef;
+
+    beforeEach(() => {
+      cdrMock = new Mock<ChangeDetectorRef>({
+        markForCheck: () => {},
+      }).Object;
+
+      TestBed.configureTestingModule({
+        providers: [{ provide: ChangeDetectorRef, useValue: cdrMock }],
+      });
+      pipe = TestBed.runInInjectionContext(() => new TranslocoDatePipe());
+    });
     it('should handle null', () => {
-      spectator = pipeFactory(`{{ null | translocoDate }}`);
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform(null)).toBeNull();
+    });
+    it('should handle undefined', () => {
+      expect(pipe.transform(undefined)).toBeUndefined();
     });
     it('should handle {}', () => {
-      spectator = pipeFactory(`{{ {} | translocoDate }}`);
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform({} as any)).toBe('');
     });
     it('should handle none number string', () => {
-      spectator = pipeFactory(`{{ 'none number string' | translocoDate }}`);
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform('none number string')).toBe('');
     });
   });
 

libs/transloco-locale/src/lib/tests/pipes/transloco-decimal.pipe.spec.ts

@@ -1,4 +1,7 @@
 import { SpectatorPipe } from '@ngneat/spectator';
+import { ChangeDetectorRef } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { Mock } from 'ts-mocks';
 
 import { TranslocoDecimalPipe } from '../../pipes';
 import {
@@ -66,17 +69,30 @@ describe('TranslocoDecimalPipe', () => {
   });
 
   describe('None transformable values', () => {
+    let pipe: TranslocoDecimalPipe;
+    let cdrMock: ChangeDetectorRef;
+
+    beforeEach(() => {
+      cdrMock = new Mock<ChangeDetectorRef>({
+        markForCheck: () => {},
+      }).Object;
+
+      TestBed.configureTestingModule({
+        providers: [{ provide: ChangeDetectorRef, useValue: cdrMock }],
+      });
+      pipe = TestBed.runInInjectionContext(() => new TranslocoDecimalPipe());
+    });
     it('should handle null', () => {
-      spectator = pipeFactory(`{{ null | translocoDecimal }}`);
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform(null)).toBeNull();
+    });
+    it('should handle undefined', () => {
+      expect(pipe.transform(undefined)).toBeUndefined();
     });
     it('should handle {}', () => {
-      spectator = pipeFactory(`{{ {} | translocoDecimal }}`);
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform({} as any)).toBe('');
     });
     it('should handle none number string', () => {
-      spectator = pipeFactory(`{{ 'none number string' | translocoDecimal }}`);
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform('none number string')).toBe('');
     });
   });
 });

libs/transloco-locale/src/lib/tests/pipes/transloco-percent.pipe.spec.ts

@@ -1,4 +1,7 @@
 import { SpectatorPipe } from '@ngneat/spectator';
+import { ChangeDetectorRef } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { Mock } from 'ts-mocks';
 
 import { TranslocoPercentPipe } from '../../pipes';
 import { LOCALE_CONFIG_MOCK, provideTranslocoLocaleConfigMock } from '../mocks';
@@ -31,17 +34,30 @@ describe('TranslocoPercentPipe', () => {
   });
 
   describe('None transformable values', () => {
+    let pipe: TranslocoPercentPipe;
+    let cdrMock: ChangeDetectorRef;
+
+    beforeEach(() => {
+      cdrMock = new Mock<ChangeDetectorRef>({
+        markForCheck: () => {},
+      }).Object;
+
+      TestBed.configureTestingModule({
+        providers: [{ provide: ChangeDetectorRef, useValue: cdrMock }],
+      });
+      pipe = TestBed.runInInjectionContext(() => new TranslocoPercentPipe());
+    });
     it('should handle null', () => {
-      spectator = pipeFactory(getPipeTpl(null));
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform(null)).toBeNull();
+    });
+    it('should handle undefined', () => {
+      expect(pipe.transform(undefined)).toBeUndefined();
     });
     it('should handle {}', () => {
-      spectator = pipeFactory(getPipeTpl({}));
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform({} as any)).toBe('');
     });
     it('should handle none number string', () => {
-      spectator = pipeFactory(getPipeTpl('none number string'));
-      expect(spectator.element).toHaveText('');
+      expect(pipe.transform('none number string')).toBe('');
     });
   });