mobx-computedtree.js

/* jshint esversion: 6 */
/* globals mobx, __mobxGlobals, patch */
(function(window, mobx, globalState, patchBoxed, undefined) {
"use strict";

// UTILITIES FUNCTIONS:

var $mobx = mobx.$mobx,
	observable = mobx.observable,
	computed = mobx.computed,
	action = mobx.action,
	set = mobx.set,
	intercept = mobx.intercept,
	onBecomeUnobserved = mobx.onBecomeUnobserved,
	getAtom = mobx.getAtom,
	getDebugName = mobx.getDebugName,
	
	allowStateChangesInsideComputed = function(func) {	// See: https://github.com/mobxjs/mobx/blob/5.6.0/src/core/action.ts#108
		return function() {
			var prev = globalState.computationDepth;
			globalState.computationDepth = 0;
			var res;
			try {
				res = func.apply(this, arguments);
			} finally {
				globalState.computationDepth = prev;
			}
			return res;
		};
	},
	
	// We need to use the same type checks as MobX:
	isPlainObject = function(value) {	// See: https://github.com/mobxjs/mobx/blob/5.6.0/src/utils/utils.ts#L85
		if (value === null || typeof value !== "object") return false;
		var proto = Object.getPrototypeOf(value);
		return proto === Object.prototype || proto === null;
	},
	isMap = function(thing) {	// See: https://github.com/mobxjs/mobx/blob/5.6.0/src/utils/utils.ts#L145
		return thing instanceof Map;
	},
	
	isObservable = mobx.isObservable,
	isObservableMap = mobx.isObservableMap,
	isComputedProp = mobx.isComputedProp,
	
	invariant = function(check, message) {
		if (!check) throw new Error("[computedTree] " + message);
	};


// COMPUTEDTREE FUNCTIONS:

// Note that MobX decorators may change in the future:
// https://github.com/mobxjs/mobx/labels/waiting-for-standardized-decorators

// Conceptually, this is how it works:
// - computedTree is a decorator that has to be run before other MobX decorators.
// - It injects a custom get() function before calling the computed() decorator
//   to create a normal computed value property.
// - The custom get() function is the one that updates/patches the tree.
// - While patching the tree, we need special interceptor and enhancer functions to
//   prevent modification of any generated observable.

// Additional constraints:
// - Prevent outside modification of the generated observables in the trees.
//   => Done using:
//      - a global property `globalState.cT_patchingTree_id` which indicates which tree is being
//        patched. This works because only 1 computedTree can be patched at a time.
//      - `intercept()` every generated observable of the tree. It throws an error when modification
//        is not allowed.
// - The patching must only reuse observables that were previously generated by the
//   same computedTree, to prevent accidental modification of unrelated observables.
//   => Done using a different id for each computedTree, named `cT_id`. In the tree, every generated
//      observable is assigned the same id so we can recognize to which tree they are belong.


// A string or undefined: the cT_id of the computedTree being patched
globalState.cT_patchingTree_id = undefined;

// Function that launches the patching. It ensures that modifications of the tree are allowed,
// and that they are executed in a transaction (batch):
var patchComputedTreeBox = action(allowStateChangesInsideComputed(function(computedTreeBox, newValue, _patchBoxed, replaceValue) {
	globalState.cT_patchingTree_id = computedTreeBox.cT_id;
	_patchBoxed(computedTreeBox, newValue, replaceValue);
	globalState.cT_patchingTree_id = undefined;
}));



// Creates a computedTree decorator for the given parameters:
var createComputedTreeDecorator = function(_patchBoxed, _treeDecorator, _patch_replaceValue) {
	// The decorator.
	// See:
	// - https://github.com/mobxjs/mobx/blob/5.6.0/src/utils/decorators.ts#74
	// - https://github.com/mobxjs/mobx/blob/5.6.0/src/api/decorate.ts#39
	return function(target, prop, descriptor, applyImmediately) {
		// The boxed observable that contains all data for the current computedTree:
		var computedTreeBox = observable.box(undefined, {
			name: getDebugName(target) + "." + prop,
			defaultDecorator: _treeDecorator
		});
		computedTreeBox.cT_computeFn = descriptor.get || descriptor.value;
		
		if ("value" in descriptor) delete descriptor.value;
		descriptor.get = function() {
			// Update and patch the computedTree:
			var newValue = computedTreeBox.cT_computeFn.call(this);
			patchComputedTreeBox(computedTreeBox, newValue, _patchBoxed, _patch_replaceValue);
			newValue = computedTreeBox.value;	// computedTreeBox might have changed it, so we need to get it back. Also, we need to bypass reportObserved(), because if we want to dispose the value without triggering a recomputation.
			
			// May need to stay suspended:
			if (!computedTreeBox.cT_computedValue.isBeingObserved) computedTreeBox.set(undefined);
			return newValue;
		};
		
		// Execute the computed decorator on the current property:
		computed(target, prop, descriptor, applyImmediately);
		var computedValue = getAtom(target, prop);
		
		computedValue.computedTreeBox = computedTreeBox;
		computedTreeBox.cT_computedValue = computedValue;
		computedTreeBox.cT_id = computedValue.__mapid;
		
		onBecomeUnobserved(target, prop, function() {
			// Suspend:
			computedTreeBox.set(undefined);
		});
	};
};

var isComputedTreeProp = function(thing, property) {
	return isComputedProp(thing, property) && getAtom(thing, property).computedTreeBox !== undefined;
};


// TREE FUNCTIONS:

// While building the tree, we need a few functions to manage the generated observables:
// - a decorator: `treeDecorator` (this is just an empty container to pass treeEnhancer into MobX).
// - an enhancer: `treeEnhancer`, that generates the observables of the tree.
// - an interceptor: `modificationInterceptor`, that intercepts modifications to the tree.
// - a hook into the patch function: `patch_replaceValue`, which allows us to choose
//   which observable can be reused.


// Interceptor that prevents outside modification of the tree:
var modificationInterceptor = function(change) {
	var object = change.object,
		cT_id = isObservableMap(object) ? object.cT_id : object[$mobx].cT_id;
	if (cT_id !== globalState.cT_patchingTree_id) {
		var objName = getDebugName(object);
		var propName = name in change ? change.name : change.index;
		throw new Error("[computedTree] It is not possible to modify a computedTree. Trying to modify property '" + propName + "' of '" + objName + "'.");
	}
	return change;
};

// An improved `mobx.observer.deep.enhancer`, which also:
// - uses `treeDecorator` as default decorator for generated observables.
// - assigns the tree id `cT_id` to the generated observables.
// - sets up the `modificationInterceptor` to intercept changes in the generated observables.
// See: https://github.com/mobxjs/mobx/blob/5.6.0/src/types/modifiers.ts#L17
var treeEnhancer = function(v, oldValue, name) {	// TODO: use oldValue to patch here instead of using the `patch()` function ?
	if (isObservable(v)) return v;
	
	var admin;
	if (Array.isArray(v)) {
		v = observable.array(v, { name: name , defaultDecorator: treeDecorator});
		admin = v[$mobx];
	}
	else if (isPlainObject(v)) {
		v = observable.object(v, undefined, { name: name , defaultDecorator: treeDecorator});
		admin = v[$mobx];
	}
	else if (isMap(v)) {
		v = observable.map(v, { name: name , defaultDecorator: treeDecorator});
		admin = v;
	}
	else return v;
	
	invariant(globalState.cT_patchingTree_id !== undefined, "globalState.cT_patchingTree_id is undefined");
	admin.cT_id = globalState.cT_patchingTree_id;
	
	intercept(v, modificationInterceptor);
	
	return v;
};

var treeDecorator = function(target, propertyName, descriptor, _decoratorTarget, decoratorArgs) {
	// This decorator is only called for new observables created from extenders because new
	// observable objects are always created empty (before being filled with mobx.set()).
	// Thus we know that target will always be a normal plain object, which means that the
	// implementation can be simpler than the original mobx implementation.
	// See: createDecoratorForEnhancer()  (https://github.com/mobxjs/mobx/blob/5.6.0/src/api/observabledecorator.ts#L15)
	// Note: descriptor can be undefined (how ?)
	if (descriptor && descriptor.get) {
		computed(target, propertyName, descriptor, true);
	}
	else {
		set(target, propertyName, descriptor && descriptor.value);
	}
};
// Required to pass the enhancer deeper in the tree:
// (See: `IObservableDecorator`   https://github.com/mobxjs/mobx/blob/5.6.0/src/api/observabledecorator.ts#12)
treeDecorator.enhancer = treeEnhancer;

// Hook into `patch` which prevents reusing observables that don't belong to the tree:
// See function `defaultReplaceValue()` in MobX-patch.
var patch_replaceValue = function(oldValue_OT, newValue_T, oldValue, newValue, _defaultReplaceValue) {
	// Constants from mobx-patch.js:
	var OT_OTHER = 0,
		OT_OBJECT = 1,
		OT_ARRAY = 2,
		OT_MAP = 3,
		OT_EXTENDEDOBJECT = 4;
	
	invariant(globalState.cT_patchingTree_id !== undefined, "globalState.cT_patchingTree_id is undefined");
	
	// Check if the observable oldValue was generated by the same tree:
	if (oldValue_OT !== OT_OTHER) {
		if (oldValue_OT === OT_OBJECT && oldValue[$mobx].cT_id !== globalState.cT_patchingTree_id
		||  oldValue_OT === OT_ARRAY && oldValue[$mobx].cT_id !== globalState.cT_patchingTree_id
		||  oldValue_OT === OT_MAP && oldValue.cT_id !== globalState.cT_patchingTree_id
		||  oldValue_OT === OT_EXTENDEDOBJECT && oldValue[$mobx].cT_id !== globalState.cT_patchingTree_id) {
			oldValue_OT = OT_OTHER;	// Setting to OT_OTHER will force the use of a new value.
		}
	}
	// Now execute the default replaceValue:
	return _defaultReplaceValue(oldValue_OT, newValue_T, oldValue, newValue);
};


// ES6 SYMBOLS FOR DEFINING COMPUTEDTREES

var $computedTree = Symbol("mobx-computedTree: $computedTree"),
	$decorators = Symbol("mobx-computedTree: $decorators"),
	$defaultDecorator = Symbol("mobx-computedTree: $defaultDecorator");

// Extends an observable with the computedTree definitions from the properties's symbol $computedTree.
var extendFromComputedTreeSymbols = function(target, properties) {
	// This is not wrapped in a batch like in mobx.extendObservable(). But as there should
	// only be computedValues, it shouldn't matter.
	var props = properties[$computedTree];
	if (props) {
		var decorators = props[$decorators] || undefined;
		var defaultDecorator = props[$defaultDecorator] || computedTreeDecorator;
		Object.keys(props).forEach(function(key) {
			var descriptor = Object.getOwnPropertyDescriptor(props, key);
			var decorator = ( decorators && decorators[key] ) || defaultDecorator;
			decorator(target, key, descriptor, true);
		});
	}
	return target;
};

// Adding support for $computedTree in mobx.extendObservable().
// We just wrap the original function in a new custom function:
mobx.extendObservable = (function(extendObservable) {	// See: https://github.com/mobxjs/mobx/blob/5.6.0/src/api/extendobservable.ts#19
	return function(target, properties, decorators, options) {
		return extendFromComputedTreeSymbols(extendObservable(target, properties, decorators, options), properties);
	};
})(mobx.extendObservable);

// Adding support for $computedTree in mobx.observable.object().
// We just wrap the original function in a new custom function:
mobx.observable.object = (function(observable_object) {	// See: https://github.com/mobxjs/mobx/blob/5.6.0/src/api/observable.ts#160
	return function(props, decorators, options) {
		return extendFromComputedTreeSymbols(observable_object(props, decorators, options), props);
	};
})(mobx.observable.object);

// Adding support for $computedTree in patch.extender().
// We just wrap the original function in a new custom function:
window.patch.extender = (function(extender) {
	return function(base) {
		if (base[$computedTree]) {
			if (base[$computedTree][$decorators]) Object.freeze(base[$computedTree][$decorators]);
			Object.freeze(base[$computedTree]);
		}
		return extender(base);
	};
})(window.patch.extender);


// EXPORTING:

var computedTreeDecorator = createComputedTreeDecorator(patchBoxed, treeDecorator, patch_replaceValue);
var computedTreeDecoratorObjectAsMap = createComputedTreeDecorator(patchBoxed.objToMap, treeDecorator, patch_replaceValue);

window.computedTree = computedTreeDecorator;
computedTreeDecorator.objToMap = computedTreeDecoratorObjectAsMap;
computedTreeDecorator.isComputedTreeProp = isComputedTreeProp;

computedTreeDecorator.$computedTree = $computedTree;
computedTreeDecorator.$decorators = $decorators;
computedTreeDecorator.$defaultDecorator = $defaultDecorator;


computedTreeDecorator._createComputedTreeDecorator = createComputedTreeDecorator;
computedTreeDecorator._patchComputedTreeBox = patchComputedTreeBox;
computedTreeDecorator._extendFromComputedTreeSymbols = extendFromComputedTreeSymbols;
})(window, mobx, __mobxGlobals, patch.boxed);