Computed / Reaction comparer

src/api/autorun.ts

@@ -1,8 +1,9 @@
-import {Lambda, getNextId, invariant, valueDidChange, fail} from "../utils/utils";
+import {Lambda, getNextId, invariant, fail} from "../utils/utils";
 import {isModifierDescriptor} from "../types/modifiers";
 import {Reaction, IReactionPublic, IReactionDisposer} from "../core/reaction";
 import {untrackedStart, untrackedEnd} from "../core/derivation";
 import {action, isAction} from "../api/action";
+import {IEqualsComparer, defaultComparer, structuralComparer} from "../types/comparer";
 import {getMessage} from "../utils/messages";
 
 /**
@@ -156,6 +157,7 @@ export interface IReactionOptions {
 	compareStructural?: boolean;
 	/** alias for compareStructural */
 	struct?: boolean;
+	equals?: IEqualsComparer<any>;
 	name?: string;
 }
 
@@ -194,8 +196,9 @@ export function reaction<T>(expression: (r: IReactionPublic) => T, effect: (arg:
 
 	let firstTime = true;
 	let isScheduled = false;
-	let nextValue: T;
+	let value: T;
 
+	const equals = opts.equals ? opts.equals : (opts.compareStructural || opts.struct) ? structuralComparer : defaultComparer;
 	const r = new Reaction(opts.name, () => {
 		if (firstTime || (opts.delay as any) < 1) {
 			reactionRunner();
@@ -213,14 +216,14 @@ export function reaction<T>(expression: (r: IReactionPublic) => T, effect: (arg:
 			return;
 		let changed = false;
 		r.track(() => {
-			const v = expression(r);
-			changed = valueDidChange(opts.compareStructural!, nextValue, v);
-			nextValue = v;
+			const nextValue = expression(r);
+			changed = firstTime || !equals(value, nextValue);
+			value = nextValue;
 		});
 		if (firstTime && opts.fireImmediately!)
-			effect(nextValue, r);
+			effect(value, r);
 		if (!firstTime && (changed as boolean) === true)
-			effect(nextValue, r);
+			effect(value, r);
 		if (firstTime)
 			firstTime = false;
 	}

src/api/computed.ts

@@ -1,3 +1,4 @@
+import {IEqualsComparer, defaultComparer, structuralComparer} from "../types/comparer";
 import {asObservableObject, defineComputedProperty} from "../types/observableobject";
 import {invariant} from "../utils/utils";
 import {createClassPropertyDecorator} from "../utils/decorators";
@@ -7,6 +8,7 @@ import {getMessage} from "../utils/messages";
 export interface IComputedValueOptions<T> {
 	compareStructural?: boolean;
 	struct?: boolean;
+	equals?: IEqualsComparer<T>;
 	name?: string;
 	setter?: (value: T) => void;
 	context?: any;
@@ -17,17 +19,17 @@ export interface IComputed {
 	<T>(func: () => T, options: IComputedValueOptions<T>): IComputedValue<T>;
 	(target: Object, key: string | symbol, baseDescriptor?: PropertyDescriptor): void;
 	struct(target: Object, key: string | symbol, baseDescriptor?: PropertyDescriptor): void;
+	equals(equals: IEqualsComparer<any>): PropertyDecorator;
 }
 
-
-function createComputedDecorator(compareStructural) {
+function createComputedDecorator(equals: IEqualsComparer<any>) {
 	return createClassPropertyDecorator(
 		(target, name, _, __, originalDescriptor) => {
 			invariant(typeof originalDescriptor !== "undefined", getMessage("m009"));
 			invariant(typeof originalDescriptor.get === "function", getMessage("m010"));
 
 			const adm = asObservableObject(target, "");
-			defineComputedProperty(adm, name, originalDescriptor.get, originalDescriptor.set, compareStructural, false);
+			defineComputedProperty(adm, name, originalDescriptor.get, originalDescriptor.set, equals, false);
 		},
 		function (name) {
 			const observable = this.$mobx.values[name];
@@ -43,8 +45,8 @@ function createComputedDecorator(compareStructural) {
 	);
 }
 
-const computedDecorator = createComputedDecorator(false);
-const computedStructDecorator = createComputedDecorator(true);
+const computedDecorator = createComputedDecorator(defaultComparer);
+const computedStructDecorator = createComputedDecorator(structuralComparer);
 
 /**
  * Decorator for class properties: @computed get value() { return expr; }.
@@ -59,8 +61,11 @@ export var computed: IComputed = (
 		invariant(arguments.length < 3, getMessage("m012"));
 		const opts: IComputedValueOptions<any> = typeof arg2 === "object" ? arg2 : {};
 		opts.setter = typeof arg2 === "function" ? arg2 : opts.setter;
-		return new ComputedValue(arg1, opts.context, opts.compareStructural || opts.struct || false, opts.name || arg1.name || "", opts.setter);
+
+		const equals = opts.equals ? opts.equals : (opts.compareStructural || opts.struct) ? structuralComparer : defaultComparer;
+		return new ComputedValue(arg1, opts.context, equals, opts.name || arg1.name || "", opts.setter);
 	}
 ) as any;
 
 computed.struct = computedStructDecorator;
+computed.equals = createComputedDecorator;

src/api/createtransformer.ts

@@ -1,6 +1,7 @@
 import {ComputedValue} from "../core/computedvalue";
-import {invariant, getNextId, addHiddenProp} from "../utils/utils";
 import {globalState} from "../core/globalstate";
+import {defaultComparer} from "../types/comparer";
+import {invariant, getNextId, addHiddenProp} from "../utils/utils";
 
 export type ITransformer<A, B> = (object: A) => B;
 
@@ -17,7 +18,7 @@ export function createTransformer<A, B>(transformer: ITransformer<A, B>, onClean
 	// Local transformer class specifically for this transformer
 	class Transformer extends ComputedValue<B> {
 		constructor(private sourceIdentifier: string, private sourceObject: A) {
-			super(() => transformer(sourceObject), undefined, false, `Transformer-${(<any>transformer).name}-${sourceIdentifier}`, undefined);
+			super(() => transformer(sourceObject), undefined, defaultComparer, `Transformer-${(<any>transformer).name}-${sourceIdentifier}`, undefined);
 		}
 		onBecomeUnobserved() {
 			const lastValue = this.value;

src/core/computedvalue.ts

@@ -2,9 +2,10 @@ import {IObservable, reportObserved, propagateMaybeChanged, propagateChangeConfi
 import {IDerivation, IDerivationState, trackDerivedFunction, clearObserving, untrackedStart, untrackedEnd, shouldCompute, CaughtException, isCaughtException} from "./derivation";
 import {globalState} from "./globalstate";
 import {createAction} from "./action";
-import {createInstanceofPredicate, getNextId, valueDidChange, invariant, Lambda, unique, joinStrings, primitiveSymbol, toPrimitive} from "../utils/utils";
+import {createInstanceofPredicate, getNextId, invariant, Lambda, unique, joinStrings, primitiveSymbol, toPrimitive} from "../utils/utils";
 import {isSpyEnabled, spyReport} from "../core/spy";
 import {autorun} from "../api/autorun";
+import {IEqualsComparer} from "../types/comparer";
 import {IValueDidChange} from "../types/observablevalue";
 import {getMessage} from "../utils/messages";
 
@@ -46,7 +47,7 @@ export class ComputedValue<T> implements IObservable, IComputedValue<T>, IDeriva
 	lowestObserverState = IDerivationState.UP_TO_DATE;
 	unboundDepsCount = 0;
 	__mapid = "#" + getNextId();
-	protected value: T | undefined | CaughtException = undefined;
+	protected value: T | undefined | CaughtException = new CaughtException(null);
 	name: string;
 	isComputing: boolean = false; // to check for cycles
 	isRunningSetter: boolean = false;
@@ -57,12 +58,14 @@ export class ComputedValue<T> implements IObservable, IComputedValue<T>, IDeriva
 	 *
 	 * The `name` property is for debug purposes only.
 	 *
-	 * The `compareStructural` property indicates whether the return values should be compared structurally.
-	 * Normally, a computed value will not notify an upstream observer if a newly produced value is strictly equal to the previously produced value.
-	 * However, enabling compareStructural can be convenient if you always produce an new aggregated object and don't want to notify observers if it is structurally the same.
+	 * The `equals` property specifies the comparer function to use to determine if a newly produced
+	 * value differs from the previous value. Two comparers are provided in the library; `defaultComparer`
+	 * compares based on identity comparison (===), and `structualComparer` deeply compares the structure.
+	 * Structural comparison can be convenient if you always produce an new aggregated object and
+	 * don't want to notify observers if it is structurally the same.
 	 * This is useful for working with vectors, mouse coordinates etc.
 	 */
-	constructor(public derivation: () => T, public scope: Object | undefined, private compareStructural: boolean, name: string, setter?: (v: T) => void) {
+	constructor(public derivation: () => T, public scope: Object | undefined, private equals: IEqualsComparer<any>, name: string, setter?: (v: T) => void) {
 		this.name  = name || "ComputedValue@" + getNextId();
 		if (setter)
 			this.setter = createAction(name + "-setter", setter) as any;
@@ -135,7 +138,11 @@ export class ComputedValue<T> implements IObservable, IComputedValue<T>, IDeriva
 		}
 		const oldValue = this.value;
 		const newValue = this.value = this.computeValue(true);
-		return isCaughtException(newValue) || valueDidChange(this.compareStructural, newValue, oldValue);
+		return (
+			isCaughtException(oldValue) ||
+			isCaughtException(newValue) ||
+			!this.equals(oldValue, newValue)
+		);
 	}
 
 	computeValue(track: boolean) {

src/mobx.ts

@@ -16,9 +16,11 @@
  *
  */
 
+import { IEqualsComparer, defaultComparer, structuralComparer } from "./types/comparer";
 import {registerGlobals} from "./core/globalstate";
 registerGlobals();
 
+export { IEqualsComparer, defaultComparer, structuralComparer } from "./types/comparer";
 export { IAtom, Atom, BaseAtom                                } from "./core/atom";
 export { IObservable, IDepTreeNode                            } from "./core/observable";
 export { Reaction, IReactionPublic, IReactionDisposer         } from "./core/reaction";

src/types/comparer.ts

@@ -0,0 +1,23 @@
+import { deepEqual } from '../utils/utils';
+
+export interface IEqualsComparer<T> {
+    (a: T, b: T): boolean;
+}
+
+export function identityComparer(a: any, b: any): boolean {
+    return a === b;
+}
+
+export function structuralComparer(a: any, b: any): boolean {
+	if (typeof a === 'number' && typeof b === 'number' && isNaN(a) && isNaN(b)) {
+        return true;
+	}
+    return deepEqual(a, b);
+}
+
+export function defaultComparer(a: any, b: any): boolean {
+	if (typeof a === 'number' && typeof b === 'number' && isNaN(a) && isNaN(b)) {
+        return true;
+	}
+    return identityComparer(a, b);
+}

src/types/observableobject.ts

@@ -5,6 +5,7 @@ import {runLazyInitializers} from "../utils/decorators";
 import {hasInterceptors, IInterceptable, registerInterceptor, interceptChange} from "./intercept-utils";
 import {IListenable, registerListener, hasListeners, notifyListeners} from "./listen-utils";
 import {isSpyEnabled, spyReportStart, spyReportEnd} from "../core/spy";
+import {IEqualsComparer, defaultComparer} from "../types/comparer";
 import {IEnhancer, isModifierDescriptor, IModifierDescriptor} from "../types/modifiers";
 import {isAction, defineBoundAction} from "../api/action";
 import {getMessage} from "../utils/messages";
@@ -100,7 +101,7 @@ export function defineObservablePropertyFromDescriptor(adm: ObservableObjectAdmi
 		}
 	} else {
 		// get x() { return 3 } set x(v) { }
-		defineComputedProperty(adm, propName, descriptor.get, descriptor.set, false, true);
+		defineComputedProperty(adm, propName, descriptor.get, descriptor.set, defaultComparer, true);
 	}
 }
 
@@ -135,13 +136,13 @@ export function defineComputedProperty(
 	propName: string,
 	getter,
 	setter,
-	compareStructural: boolean,
+	equals: IEqualsComparer<any>,
 	asInstanceProperty: boolean
 ) {
 	if (asInstanceProperty)
 		assertPropertyConfigurable(adm.target, propName);
 
-	adm.values[propName] = new ComputedValue(getter, adm.target, compareStructural, `${adm.name}.${propName}`, setter);
+	adm.values[propName] = new ComputedValue(getter, adm.target, equals, `${adm.name}.${propName}`, setter);
 	if (asInstanceProperty) {
 		Object.defineProperty(adm.target, propName, generateComputedPropConfig(propName));
 	}

src/utils/utils.ts

@@ -94,15 +94,6 @@ export function objectAssign() {
 	return res;
 }
 
-export function valueDidChange(compareStructural: boolean, oldValue, newValue): boolean {
-	if (typeof oldValue === 'number' && isNaN(oldValue)) {
-		return typeof newValue !== 'number' || !isNaN(newValue);
-	}
-	return compareStructural
-		? !deepEqual(oldValue, newValue)
-		: oldValue !== newValue;
-}
-
 const prototypeHasOwnProperty = Object.prototype.hasOwnProperty;
 export function hasOwnProperty(object: Object, propName: string) {
 	return prototypeHasOwnProperty.call(object, propName);
@@ -242,5 +233,6 @@ export function toPrimitive(value) {
 
 import {globalState} from "../core/globalstate";
 import {IObservableArray, isObservableArray} from "../types/observablearray";
+import {IEqualsComparer, defaultComparer} from "../types/comparer";
 import {isObservableMap} from "../types/observablemap";
 import {observable} from "../api/observable";

test/api.js

@@ -19,6 +19,7 @@ test('correct api should be exposed', function(t) {
 		'computed',
 		'createTransformer',
 		'default',
+		'defaultComparer',
 		'expr',
 		'extendObservable',
 		'extendShallowObservable',
@@ -40,6 +41,7 @@ test('correct api should be exposed', function(t) {
 		'reaction',
 		'runInAction',
 		'spy',
+		'structuralComparer',
 		'toJS',
 		'transaction',
 		'untracked',

test/babel/babel-tests.js

@@ -873,3 +873,38 @@ test("action.bound binds (Babel)", t=> {
 
 	t.end();
 })
+
+test("@computed.equals (Babel)", t => {
+	const sameTime = (from, to) => from.hour === to.hour && from.minute === to.minute;
+	class Time {
+		constructor(hour, minute) {
+			this.hour = hour;
+			this.minute = minute;
+		}
+
+		@observable hour: number;
+		@observable minute: number;
+
+		@computed.equals(sameTime) get time() {
+			return { hour: this.hour, minute: this.minute };
+		}
+	}
+	const time = new Time(9, 0);
+
+	const changes = [];
+	const disposeAutorun = autorun(() => changes.push(time.time));
+
+	t.deepEqual(changes, [ { hour: 9, minute: 0 }]);
+	time.hour = 9;
+	t.deepEqual(changes, [ { hour: 9, minute: 0 }]);
+	time.minute = 0;
+	t.deepEqual(changes, [ { hour: 9, minute: 0 }]);
+	time.hour = 10;
+	t.deepEqual(changes, [ { hour: 9, minute: 0 }, { hour: 10, minute: 0 }]);
+	time.minute = 30;
+	t.deepEqual(changes, [ { hour: 9, minute: 0 }, { hour: 10, minute: 0 }, { hour: 10, minute: 30 }]);
+
+	disposeAutorun();
+
+	t.end();
+});

test/observables.js

@@ -1730,3 +1730,51 @@ test('observables should not fail when ES6 Map is missing', t => {
     global.Map = globalMapFunction;
     t.end();
 })
+
+test("computed equals function only invoked when necessary", t => {
+	const comparisons = [];
+	const loggingComparer = (from, to) => {
+		comparisons.push({ from, to });
+		return from === to;
+	};
+
+	const left = mobx.observable("A");
+	const right = mobx.observable("B");
+	const combinedToLowerCase = mobx.computed(
+		() => left.get().toLowerCase() + right.get().toLowerCase(),
+		{ equals: loggingComparer }
+	);
+
+	const values = [];
+	const disposeAutorun = mobx.autorun(() => values.push(combinedToLowerCase.get()));
+
+	// No comparison should be made on the first value
+	t.deepEqual(comparisons, []);
+
+	// First change will cause a comparison
+	left.set("C");
+	t.deepEqual(comparisons, [{ from: "ab", to: "cb" }]);
+
+	// Transition *to* CaughtException in the computed won't cause a comparison
+	left.set(null);
+	t.deepEqual(comparisons, [{ from: "ab", to: "cb" }]);
+
+	// Transition *between* CaughtException-s in the computed won't cause a comparison
+	right.set(null);
+	t.deepEqual(comparisons, [{ from: "ab", to: "cb" }]);
+
+	// Transition *from* CaughtException in the computed won't cause a comparison
+	left.set("D");
+	right.set("E");
+	t.deepEqual(comparisons, [{ from: "ab", to: "cb" }]);
+
+	// Another value change will cause a comparison
+	right.set("F");
+	t.deepEqual(comparisons, [{ from: "ab", to: "cb" }, { from: "de", to: "df" }]);
+
+	t.deepEqual(values, ["ab", "cb", "de", "df"]);
+
+	disposeAutorun();
+
+	t.end();
+});