feat(core): Allow comparator to return a number

Author: Airblader

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

@@ -1,4 +1,4 @@
-import { isMissing } from './util';
+import { areEqualUsing, isMissing } from './util';
 import { Comparator, ParamDeserializer, ParamSerializer } from './types';
 
 /**
@@ -13,7 +13,7 @@ import { Comparator, ParamDeserializer, ParamSerializer } from './types';
  * @param compareWith The comparator function to compare two values.
  */
 export function createEmptyOnSerializer<T>(serializer: ParamSerializer<T>, emptyOn: T, compareWith: Comparator<T>): ParamSerializer<T> {
-    return model => compareWith(model, emptyOn) ? null : serializer(model);
+    return model => areEqualUsing(model, emptyOn, compareWith) ? null : serializer(model);
 }
 
 /**

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

@@ -25,13 +25,14 @@ export type OnChangeFunction<T> = (value: T | null) => void;
 
 /**
  * A function which compares two values of the same type to determine
- * if they are equal.
+ * if they are equal. To support traditional comparator functions, you
+ * can also return a number where "0" means equality.
  *
  * @param a First value to compare.
  * @param b Second value to compare.
- * @returns `true` if and only if `a` and `b` should be considered equal.
+ * @returns `true` or `0` if and only if `a` and `b` should be considered equal.
  */
-export type Comparator<T> = (a: T | undefined | null, b: T | undefined | null) => boolean;
+export type Comparator<T> = (a: T | undefined | null, b: T | undefined | null) => boolean | number;
 
 /**
  * Unpacks an array type.

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

@@ -1,4 +1,5 @@
-import { isFunction, isMissing, LOOSE_IDENTITY_COMPARATOR, wrapTryCatch } from './util';
+import { areEqualUsing, isFunction, isMissing, LOOSE_IDENTITY_COMPARATOR, wrapTryCatch } from './util';
+import { Comparator } from './types';
 
 describe(isMissing.name, () => {
     it('returns true for undefined', () => expect(isMissing(undefined)).toBe(true));
@@ -73,4 +74,24 @@ describe(LOOSE_IDENTITY_COMPARATOR.name, () => {
         it(`returns false for ${a} / ${b}`,
             () => expect(LOOSE_IDENTITY_COMPARATOR(a, b)).toBe(false));
     });
+});
+
+describe(areEqualUsing.name, () => {
+    const numericComparator: Comparator<number> = (a, b) => b - a;
+
+    it('returns true if a boolean comparator returns true', () =>
+        expect(areEqualUsing(42, 42, LOOSE_IDENTITY_COMPARATOR)).toBe(true)
+    );
+
+    it('returns false if a boolean comparator returns false', () =>
+        expect(areEqualUsing(42, 1337, LOOSE_IDENTITY_COMPARATOR)).toBe(false)
+    );
+
+    it('returns true if a numeric comparator returns 0', () =>
+        expect(areEqualUsing(42, 42, numericComparator)).toBe(true)
+    );
+
+    it('returns false if a numeric comparator returns a non-zero value', () =>
+        expect(areEqualUsing(42, 1337, numericComparator)).toBe(false)
+    );
 });

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

@@ -1,3 +1,5 @@
+import { Comparator } from './types';
+
 /** @internal */
 // tslint:disable-next-line:triple-equals
 export const LOOSE_IDENTITY_COMPARATOR = <T>(a: T, b: T) => a == b;
@@ -22,4 +24,14 @@ export function wrapTryCatch<T extends Function>(fn: T, msg: string): T {
             return null;
         }
     };
+}
+
+/** @internal */
+export function areEqualUsing<T>(first: T, second: T, comparator: Comparator<T>): boolean {
+    const comparison = comparator(first, second);
+    if (typeof comparison === 'boolean') {
+        return comparison;
+    }
+
+    return comparison === 0;
 }

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

@@ -1,4 +1,6 @@
 /** See https://github.com/angular/angular/issues/25837 */
+import { Comparator } from '../lib/types';
+
 export function setupNavigationWarnStub() {
     const warn = console.warn;