feat(core): Added emptyOn and compareWith options

This allows defining a non-null "default value" for which the query
parameter should be removed.

We now also use compareWith to determine whether to ignore a route update
or not.

Author: Airblader

projects/ngqp-demo/src/app/playground/playground.component.ts

@@ -12,16 +12,20 @@ export class PlaygroundComponent {
         this.paramGroup = queryParamBuilder.group({
             searchText: queryParamBuilder.param({
                 name: 'q',
-                debounceTime: 1000,
+                debounceTime: 250,
+                emptyOn: 'foo'
             }),
             checker: queryParamBuilder.booleanParam({
                 name: 'yesOrNo',
+                emptyOn: true,
             }),
             counter: queryParamBuilder.numericParam({
                 name: 'ctr',
+                emptyOn: 5,
             }),
             range: queryParamBuilder.numericParam({
                 name: 'range',
+                emptyOn: 5,
             }),
         });
     }

projects/ngqp/core/src/lib/core.ts

@@ -5,6 +5,7 @@ export { QueryParamBuilder } from './query-param-builder.service';
 export { QueryParamModule } from './query-param.module';
 
 export {
+    createEmptyOnSerializer,
     createStringSerializer,
     createStringDeserializer,
     createNumberSerializer,

projects/ngqp/core/src/lib/model.ts

@@ -1,4 +1,5 @@
-import { isOptionalFunction, wrapTryCatch } from './util';
+import { Comparator, isOptionalFunction, wrapTryCatch } from './util';
+import { createEmptyOnDeserializer, createEmptyOnSerializer } from './serializers';
 
 /** TODO Documentation */
 export type ParamSerializer<T> = (model: T | null) => string | null;
@@ -10,10 +11,18 @@ export type ParamDeserializer<T> = (value: string | null) => T | null;
  * TODO Documentation
  */
 export interface QueryParamControlOpts<T> {
+    /** TODO Documentation */
     name: string;
+    /** TODO Documentation */
     serialize: ParamSerializer<T>;
+    /** TODO Documentation */
     deserialize: ParamDeserializer<T>;
+    /** TODO Documentation */
+    compareWith: Comparator<T>;
+    /** TODO Documentation */
     debounceTime?: number | null;
+    /** TODO Documentation */
+    emptyOn?: T | null;
 }
 
 /**
@@ -35,23 +44,26 @@ export class QueryParamGroup {
  */
 export class QueryParamControl<T> {
 
-    /** TODO Documentation */
-    public name: string | null = null;
+    /** TODO Documentation See QueryParamControlOpts */
+    public name: string | null;
 
-    /** TODO Documentation */
+    /** TODO Documentation See QueryParamControlOpts */
     public serialize: ParamSerializer<T>;
 
-    /** TODO Documentation */
+    /** TODO Documentation See QueryParamControlOpts */
     public deserialize: ParamDeserializer<T>;
 
-    /** TODO Documentation */
-    public debounceTime: number | null = null;
+    /** TODO Documentation See QueryParamControlOpts */
+    public compareWith: Comparator<T>;
+
+    /** TODO Documentation See QueryParamControlOpts */
+    public debounceTime: number | null;
 
     /** TODO Documentation */
     public value: T = null;
 
     constructor(opts: QueryParamControlOpts<T>) {
-        const { name, serialize, deserialize, debounceTime } = opts;
+        const { name, serialize, deserialize, debounceTime, emptyOn, compareWith } = opts;
 
         if (!isOptionalFunction(serialize)) {
             throw new Error(`serialize must be a function, but received ${serialize}`);
@@ -61,9 +73,20 @@ export class QueryParamControl<T> {
             throw new Error(`deserialize must be a function, but received ${deserialize}`);
         }
 
+        if (!isOptionalFunction(compareWith)) {
+            throw new Error(`compareWith must be a function, but received ${compareWith}`);
+        }
+
         this.name = name;
-        this.serialize = wrapTryCatch(serialize, `Error while serializing value for ${name || 'control'}`);
-        this.deserialize = wrapTryCatch(deserialize, `Error while deserializing value for ${name || 'control'}`);
+        this.serialize = wrapTryCatch(
+            createEmptyOnSerializer(serialize, emptyOn, compareWith),
+            `Error while serializing value for ${name || 'control'}`
+        );
+        this.deserialize = wrapTryCatch(
+            createEmptyOnDeserializer(deserialize, emptyOn),
+            `Error while deserializing value for ${name || 'control'}`
+        );
+        this.compareWith = compareWith;
         this.debounceTime = debounceTime;
     }
 

projects/ngqp/core/src/lib/query-param-builder.service.ts

@@ -8,9 +8,10 @@ import {
     DEFAULT_STRING_DESERIALIZER,
     DEFAULT_STRING_SERIALIZER
 } from './serializers';
+import { LOOSE_IDENTITY_COMPARATOR } from './util';
 
 type OverwritePartial<T1, T2 extends keyof T1> = Pick<T1, Exclude<keyof T1, T2>> & Partial<Pick<T1, T2>>;
-export type QueryParamControlOptsInput<T> = OverwritePartial<QueryParamControlOpts<T>, 'serialize' | 'deserialize'>;
+export type QueryParamControlOptsInput<T> = OverwritePartial<QueryParamControlOpts<T>, 'serialize' | 'deserialize' | 'compareWith'>;
 
 /**
  * TODO Documentation
@@ -48,6 +49,7 @@ export class QueryParamBuilder {
         return new QueryParamControl({
             serialize: DEFAULT_STRING_SERIALIZER,
             deserialize: DEFAULT_STRING_DESERIALIZER,
+            compareWith: LOOSE_IDENTITY_COMPARATOR,
             ...opts,
         });
     }
@@ -59,6 +61,7 @@ export class QueryParamBuilder {
         return new QueryParamControl({
             serialize: DEFAULT_NUMBER_SERIALIZER,
             deserialize: DEFAULT_NUMBER_DESERIALIZER,
+            compareWith: LOOSE_IDENTITY_COMPARATOR,
             ...opts,
         });
     }
@@ -70,6 +73,7 @@ export class QueryParamBuilder {
         return new QueryParamControl({
             serialize: DEFAULT_BOOLEAN_SERIALIZER,
             deserialize: DEFAULT_BOOLEAN_DESERIALIZER,
+            compareWith: LOOSE_IDENTITY_COMPARATOR,
             ...opts,
         });
     }
@@ -88,8 +92,6 @@ export class QueryParamBuilder {
 
         return this.param({
             name: controlName,
-            serialize: DEFAULT_STRING_SERIALIZER,
-            deserialize: DEFAULT_STRING_DESERIALIZER,
         });
     }
 

projects/ngqp/core/src/lib/query-param-group.directive.ts

@@ -69,7 +69,7 @@ export class QueryParamGroupDirective implements OnDestroy {
             distinctUntilChanged(),
             map(param => control.deserialize(param)),
         ).subscribe(newModel => {
-            if (control.serialize(newModel) === control.serialize(control.value)) {
+            if (control.compareWith(newModel, control.value)) {
                 return;
             }
 

projects/ngqp/core/src/lib/serializers.ts

@@ -1,5 +1,19 @@
 import { ParamDeserializer, ParamSerializer } from './model';
-import { isMissing } from './util';
+import { Comparator, isMissing } from './util';
+
+/**
+ * TODO Documentation
+ */
+export function createEmptyOnSerializer<T>(serializer: ParamSerializer<T>, emptyOn: T, compareWith: Comparator<T>): ParamSerializer<T> {
+    return (model: T | null) => compareWith(model, emptyOn) ? null : serializer(model);
+}
+
+/**
+ * TODO Documentation
+ */
+export function createEmptyOnDeserializer<T>(deserializer: ParamDeserializer<T>, emptyOn: T): ParamDeserializer<T> {
+    return (value: string | null) => isMissing(value) ? emptyOn : deserializer(value);
+}
 
 /**
  * TODO Documentation

projects/ngqp/core/src/lib/util.ts

@@ -1,3 +1,10 @@
+/** TODO Documentation */
+export type Comparator<T> = (a: T, b: T) => boolean;
+
+/** TODO Documentation */
+// tslint:disable-next-line:triple-equals
+export const LOOSE_IDENTITY_COMPARATOR = <T>(a: T, b: T) => a == b;
+
 /**
  * TODO Documentation
  */