aberdeen 0.1.2 → 0.2.1

package/src/prediction.ts

@@ -0,0 +1,117 @@
+import {withEmitHandler} from 'aberdeen'
+
+type ObsCollection = any
+type Patch = Map<ObsCollection, Map<any, [any, any]>>;
+
+
+function recordPatch(func: () => void): Patch {
+	const recordingPatch = new Map()
+	withEmitHandler(function(index, newData, oldData) {
+		addToPatch(recordingPatch, this, index, newData, oldData)
+	}, func)
+	return recordingPatch
+}
+
+function addToPatch(patch: Patch, collection: ObsCollection, index: any, newData: any, oldData: any) {
+	let collectionMap = patch.get(collection)
+	if (!collectionMap) {
+		collectionMap = new Map()
+		patch.set(collection, collectionMap)
+	}
+	let prev = collectionMap.get(index)
+	if (prev) oldData = prev[1]
+	if (newData === oldData) collectionMap.delete(index)
+	else collectionMap.set(index, [newData, oldData])
+}
+
+function emitPatch(patch: Patch) {
+	for(let [collection, collectionMap] of patch) {
+		for(let [index, [newData, oldData]] of collectionMap) {
+			collection.emitChange(index, newData, oldData)
+		}
+	}
+}
+
+function mergePatch(target: Patch, source: Patch, reverse: boolean = false) {
+	for(let [collection, collectionMap] of source) {
+		for(let [index, [newData, oldData]] of collectionMap) {
+			addToPatch(target, collection, index, reverse ? oldData : newData, reverse ? newData : oldData)
+		}
+	}
+}
+
+function silentlyApplyPatch(patch: Patch, force: boolean = false): boolean {
+	for(let [collection, collectionMap] of patch) {
+		for(let [index, [newData, oldData]] of collectionMap) {
+			let actualData = collection.rawGet(index)
+			if (actualData !== oldData) {
+				if (force) setTimeout(() => { throw new Error(`Applying invalid patch: data ${actualData} is unequal to expected old data ${oldData} for index ${index}`)}, 0)
+				else return false
+			}
+		}
+	}
+	for(let [collection, collectionMap] of patch) {
+		for(let [index, [newData, oldData]] of collectionMap) {
+			collection.rawSet(index, newData)
+		}
+	}
+	return true
+}
+
+
+const appliedPredictions: Array<Patch> = []
+
+/**
+ * Run the provided function, while treating all changes to Observables as predictions,
+ * meaning they will be reverted when changes come back from the server (or some other
+ * async source).
+ * @param predictFunc The function to run. It will generally modify some Observables
+ * 	to immediately reflect state (as closely as possible) that we expect the server
+ *  to communicate back to us later on.
+ * @returns A `Patch` object. Don't modify it. This is only meant to be passed to `applyCanon`.
+ */
+export function applyPrediction(predictFunc: () => void): Patch {
+	let patch = recordPatch(predictFunc)
+	appliedPredictions.push(patch)
+	emitPatch(patch)
+	return patch
+}
+
+/**
+ * Temporarily revert all outstanding predictions, optionally run the provided function
+ * (which will generally make authoritative changes to the data based on a server response),
+ * and then attempt to reapply the predictions on top of the new canonical state, dropping 
+ * any predictions that can no longer be applied cleanly (the data has been modified) or
+ * that were specified in `dropPredictions`.
+ * 
+ * All of this is done such that redraws are only triggered if the overall effect is an
+ * actual change to an `Observable`.
+ * @param canonFunc The function to run without any predictions applied. This will typically
+ *  make authoritative changes to the data, based on a server response.
+ * @param dropPredictions An optional list of predictions (as returned by `applyPrediction`)
+ *  to undo. Typically, when a server response for a certain request is being handled,
+ *  you'd want to drop the prediction that was done for that request.
+ */
+export function applyCanon(canonFunc?: (() => void), dropPredictions: Array<Patch> = []) {
+	
+	let resultPatch = new Map()
+	for(let prediction of appliedPredictions) mergePatch(resultPatch, prediction, true)
+	silentlyApplyPatch(resultPatch, true)
+
+	for(let prediction of dropPredictions) {
+		let pos = appliedPredictions.indexOf(prediction)
+		if (pos >= 0) appliedPredictions.splice(pos, 1)
+	}
+	if (canonFunc) mergePatch(resultPatch, recordPatch(canonFunc))
+
+	for(let idx=0; idx<appliedPredictions.length; idx++) {
+		if (silentlyApplyPatch(appliedPredictions[idx])) {
+			mergePatch(resultPatch, appliedPredictions[idx])
+		} else {
+			appliedPredictions.splice(idx, 1)
+			idx--
+		}
+	}
+
+	emitPatch(resultPatch)
+}

package/src/route.ts

@@ -0,0 +1,121 @@
+import {Store, observe, immediateObserve, inhibitEffects} from 'aberdeen'
+
+/**
+ * A `Store` object that holds the following keys:
+ * - `path`: The current path of the URL split into components. For instance `/` or `/users/123/feed`. Updates will be reflected in the URL and will *push* a new entry to the browser history.
+ * - `p`: Array containing the path segments. For instance `[]` or `['users', 123, 'feed']`. Updates will be reflected in the URL and will *push* a new entry to the browser history. Also, the values of `p` and `path` will be synced.
+ * - `search`: An observable object containing search parameters (a split up query string). For instance `{order: "date", title: "something"}` or just `{}`. Updates will be reflected in the URL, modifying the current history state. 
+ * - `hash`: The document hash part of the URL. For instance `"#section-title"`. It can also be an empty string. Updates will be reflected in the URL, modifying the current history state.
+ * - `state`: The browser history *state* object for the current page. Creating or removing top-level keys will cause *pushing* a new entry to the browser history.
+ * 
+ * The following key may also be written to `route` but will be immediately and silently removed: 
+ * - `mode`: As described above, this library takes a best guess about whether pushing an item to the browser history makes sense or not. When `mode` is...
+ * 	  	- `"push"`: Force creation of a new browser history entry. 
+ * 	  	- `"replace"`: Update the current history entry, even when updates to other keys would normally cause a *push*.
+ * 		- `"back"`: Unwind the history (like repeatedly pressing the *back* button) until we find a page that matches the given `path`, `search` and top-level `state` keys, and then *replace* that state by the full given state.
+ */
+export const route = new Store()
+
+// Contains url (path+search) and state for all history entries for this session, with the current
+// entry on top. It is used for `mode: "back"`, to know how many entries to go back.
+let stack: Array<{url: string, state: object}> = []
+
+// Keep track of the initial history length, so we'll always know how long our `stack` should be.
+const initialHistoryLength = history.length;
+
+// Keep a copy of the last known history state, so we can tell if the user changed one of its
+// top-level keys, so we can decide between push/replace when `mode` is not set.
+let prevHistoryState: any
+
+// Reflect changes to the browser URL (back/forward navigation) in the `route` and `stack`.
+function handleLocationUpdate(event?: PopStateEvent) {
+	const search: any= {}
+	for(let [k, v] of new URLSearchParams(location.search)) {
+		search[k] = v
+	}
+	prevHistoryState = event ? (event.state || {}) : {}
+	stack.length = Math.max(1, history.length - initialHistoryLength + 1)
+	stack[stack.length-1] = {url: location.pathname + location.search, state: prevHistoryState}
+	route.set({
+		path: location.pathname,
+		p: location.pathname.slice(1).split('/'),
+		search: search,
+		hash: location.hash,
+		state: prevHistoryState,
+	})
+}
+handleLocationUpdate()
+window.addEventListener("popstate", handleLocationUpdate);
+
+// These immediate-mode observers will rewrite the data in `route` to its canonical form.
+// We want to to this immediately, so that user-code running immediately after a user-code
+// initiated `set` will see the canonical form (instead of doing a rerender shortly after,
+// or crashing due to non-canonical data).
+immediateObserve(() => {
+	let path = ''+route.get('path')
+	if (!path.startsWith('/')) path = '/'+path
+	route.set('path', path)
+	route.set('p', path.slice(1).split('/'))
+})
+
+immediateObserve(() => {
+	const p = route.get('p')
+	if (!(p instanceof Array)) {
+		console.error(`aberdeen route: 'p' must be a non-empty array, not ${JSON.stringify(p)}`)
+		route.set('p', ['']) // This will cause a recursive call this observer.
+	} else if (p.length == 0) {
+		route.set('p', ['']) // This will cause a recursive call this observer.
+	} else {
+		route.set('path', '/' + p.join('/'))
+	}
+})
+
+immediateObserve(() => {
+	if (route.getType('search') !== 'object') route.set('search', {})
+})
+
+immediateObserve(() => {
+	if (route.getType('state') !== 'object') route.set('state', {})
+})
+
+immediateObserve(() => {
+	let hash = ''+(route.get('hash') || '')
+	if (hash && !hash.startsWith('#')) hash = '#'+hash
+	route.set('hash', hash)
+})
+
+// This deferred-mode observer will update the URL and history based on `route` changes.
+observe(() => {
+	// Get and delete mode without triggering anything.
+	const mode = route.get('mode')
+	if (mode) inhibitEffects(() => route.delete('mode'))
+	const state = route.get('state')
+	
+	// Construct the URL.
+	const path = route.get('path')
+	const search = new URLSearchParams(route.get('search')).toString()
+	const url = (search ? path+'?'+search : path) + route.get('hash')
+
+	// Change browser state, according to `mode`.
+	if (mode === 'back') {
+		let goDelta = 0
+		while(stack.length > 1) {
+			const item = stack[stack.length-1]
+			if (item.url === url && JSON.stringify(Object.keys(state||{})) === JSON.stringify(Object.keys(item.state||{}))) break // Found it!
+			goDelta--
+			stack.pop()
+		}
+		if (goDelta) history.go(goDelta)
+		// We'll replace the state async, to give the history.go the time to take affect first.
+		setTimeout(() => history.replaceState(state, '', url), 0)
+		stack[stack.length-1] = {url,state}
+	} else if (mode === 'push' || (!mode && (location.pathname !== path || JSON.stringify(Object.keys(state||{})) !== JSON.stringify(Object.keys(prevHistoryState||{}))))) {
+		history.pushState(state, '', url)
+		stack.push({url,state})
+	} else {
+		history.replaceState(state, '', url)
+		stack[stack.length-1] = {url,state}
+	}
+	prevHistoryState = state
+})
+

package/src/transitions.ts

@@ -0,0 +1,73 @@
+import {scheduleDomReader, scheduleDomWriter} from 'aberdeen'
+
+const FADE_TIME = 400
+const GROW_SHRINK_TRANSITION = `margin ${FADE_TIME}ms ease-out, transform ${FADE_TIME}ms ease-out`
+
+function getGrowShrinkProps(el: HTMLElement) {
+	const parentStyle: any = el.parentElement ? getComputedStyle(el.parentElement) : {}
+	const isHorizontal = parentStyle.display === 'flex' && (parentStyle.flexDirection||'').startsWith('row')
+	return isHorizontal ?
+		{marginLeft: `-${el.offsetWidth/2}px`, marginRight: `-${el.offsetWidth/2}px`, transform: "scaleX(0)"} :
+		{marginBottom: `-${el.offsetHeight/2}px`, marginTop: `-${el.offsetHeight/2}px`, transform: "scaleY(0)"}
+
+}
+
+/** Do a grow transition for the given element. This is meant to be used as a
+* handler for the `create` property.
+*
+* @param el The element to transition.
+*
+* The transition doesn't look great for table elements, and may have problems
+* for other specific cases as well.
+*/
+export function grow(el: HTMLElement): void {
+	// This timeout is to await all other elements having been added to the Dom
+	scheduleDomReader(() => {
+		// Make the element size 0 using transforms and negative margins.
+		// This causes a browser layout, as we're querying el.offset<>.
+		let props = getGrowShrinkProps(el)
+		
+		// The timeout is in order to batch all reads and then all writes when there
+		// are multiple simultaneous grow transitions.
+		scheduleDomWriter(() => {
+			Object.assign(el.style, props)
+			
+			// This timeout is to combine multiple transitions into a single browser layout
+			scheduleDomReader(() => {
+				// Make sure the layouting has been performed, to cause transitions to trigger
+				el.offsetHeight
+				scheduleDomWriter(() => {
+					// Do the transitions
+					el.style.transition = GROW_SHRINK_TRANSITION
+					for(let prop in props) el.style[prop as any] = ""
+					setTimeout(() => {
+						// Reset the element to a clean state
+						el.style.transition = ""
+					}, FADE_TIME)
+				})
+			})
+		})
+	})
+}
+
+/** Do a shrink transition for the given element, and remove it from the DOM
+* afterwards. This is meant to be used as a handler for the `destroy` property.
+*
+* @param el The element to transition and remove.
+*
+* The transition doesn't look great for table elements, and may have problems
+* for other specific cases as well.
+*/
+export function shrink(el: HTMLElement): void {
+	scheduleDomReader(() => {
+		const props = getGrowShrinkProps(el)
+		// The timeout is in order to batch all reads and then all writes when there
+		// are multiple simultaneous shrink transitions.
+		scheduleDomWriter(() => {
+			el.style.transition = GROW_SHRINK_TRANSITION
+			Object.assign(el.style, props)
+			
+			setTimeout(() => el.remove(), FADE_TIME)
+		})
+	})
+}

package/tests/_fakedom.js

@@ -0,0 +1,255 @@
+let insertedCss = '';
+
+global.document = {
+	createElement: tag => new Element(tag),
+	createTextNode: text => new TextNode(text),
+	head: {
+		appendChild: function(el) {
+			if (el.tag!=='style') {
+				throw new Error("only <style> inserts in head can be emulated");
+			}
+			insertedCss += el.innerText;
+		}
+	}
+};
+global.window = {};
+
+
+let newCount = 0, changeCount = 0;
+global.resetCounts = function() { newCount = changeCount = 0; };
+global.getCounts = function() { return {new: newCount, change: changeCount}; };
+
+let timeouts = [];
+let currentTime = 0;
+
+global.setTimeout = function(func,time) {
+	timeouts.push({func, time: time+currentTime});
+};
+
+global.passTime = function(ms) {
+	let targetTime = ms==null ? undefined : currentTime + ms;
+	while(timeouts.length) {
+		// Find the timeout that should occur first
+		let smallestIdx = 0;
+		for(let idx=1; idx<timeouts.length; idx++) {
+			if (timeouts[idx].time < timeouts[smallestIdx].time) smallestIdx = idx;
+		}
+		let timeout = timeouts[smallestIdx];
+		// If this timeout is not due yet, we're done
+		if (targetTime!=null && timeout.time > targetTime) break;
+		// Timeout is due! Remove it from the list, update the currentTime, and fire the callback!
+		timeouts.splice(smallestIdx, 1);
+		currentTime = timeout.time;
+		timeout.func();
+	}
+	currentTime = targetTime==null ? 0 : targetTime
+}
+
+
+class Node {
+	get nextSibling() {
+		return this.getSibling(+1);
+	}
+	get previousSibling() {
+		return this.getSibling(-1);
+	}
+	getSibling(delta) {
+		if (!this.parentNode) return;
+		let siblings = this.parentNode.childNodes;
+		let idx = siblings.indexOf(this);
+		if (idx < 0) throw new Error("not part of siblings!?");
+		return siblings[idx+delta];
+	}
+}
+
+class Element extends Node {
+	constructor(tag) {
+		super();
+		this.tag = tag;
+		this.childNodes = [];
+		this._style = {};
+		this.attrs = {};
+		this.events = {};
+		newCount++;
+	}
+	appendChild(node) {
+		this.insertBefore(node, null);
+	}
+	insertBefore(node, ref) {
+		if (node.parentNode) node.parentNode.removeChild(node);
+		else changeCount++;
+		node.parentNode = this;
+		if (ref) {
+			let idx = this.childNodes.indexOf(ref);
+			if (idx<0) throw new Error("non-existing ref node");
+			this.childNodes.splice(idx, 0, node);
+		} else {
+			this.childNodes.push(node);
+		}
+	}
+	removeChild(node) {
+		let idx = this.childNodes.indexOf(node);
+		if (idx<0) throw new Error("no such child");
+		this.childNodes.splice(idx, 1);
+		node.parentNode = null;
+		changeCount++;
+	}
+	remove() {
+		this.parentNode.removeChild(this);
+	}
+	replaceChild(newNode, oldNode) {
+		this.insertBefore(newNode, oldNode);
+		this.removeChild(oldNode);
+	}
+	setAttribute(k, v) {
+		this.attrs[k] = ''+v;
+		changeCount++;
+	}
+	getAttribute(k) {
+		return this.attrs[k]
+	}
+	removeAttribute(k) {
+		delete this.attrs[k];
+		changeCount++;
+	}
+	get classList() {
+		return {
+			add: name => {
+				let set = this._getClassSet();
+				set.add(name);
+				this._setClassSet(set);
+				changeCount++;
+			},
+			remove: name => {
+				let set = this._getClassSet();
+				set.delete(name);
+				this._setClassSet(set);
+				changeCount++;
+			},
+		}
+	}
+	get parentElement() {
+		if (this.parentNode instanceof Element) return this.parentNode;
+	}
+	_getClassSet() {
+		return new Set(this.attrs.class ? this.attrs.class.split(' ') : []);
+	}
+	_setClassSet(map) {
+		this.attrs.class = Array.from(map).sort().join(' ');
+		if (!this.attrs.class) delete this.attrs.class;
+	}
+	get firstChild() {
+		return this.childNodes[0];
+	}
+	get lastChild() {
+		return this.childNodes[this.childNodes.length-1];
+	}
+	set style(val) {
+		if (val !== '') throw new Error("non-empty style string cannot be emulated");
+		this._style = {};
+		changeCount++;
+	}
+	set textContent(text) {
+		this.childNodes = [new TextNode(text)];
+	}
+	set innerHTML(html) {
+		this.childNodes = [];
+		if (html) {
+			let n = new Element('fake-emulated-html');
+			n.textContent = html;
+			this.appendChild(n);
+		}
+	}
+	get style() {
+		for(let k in this._style) {
+			if (this._style[k] === '') delete this._style[k];
+		}
+		return this._style;
+	}
+	set className(v) {
+		this.attrs.class = v;
+		changeCount++;
+	}
+	get offsetHeight() {
+		return 20;
+	}
+	get offsetWidth() {
+		return 200;
+	}
+	toString() {
+		let props = Object.assign({}, this);
+		for(let k in this.attrs) props['@'+k] = this.attrs[k];
+		for(let k in this.style) props[':'+k] = this._style[k];
+		delete props.tag;
+		delete props.attrs;
+		delete props._style;
+		delete props.events;
+		delete props.childNodes;
+		delete props.parentNode;
+
+		let arr = [];
+		for(let k in props) arr.push(k+'='+JSON.stringify(props[k]));
+		arr.sort();
+		for(let child of this.childNodes) arr.push(child.toString());
+
+		return this.tag + `{${arr.join(' ')}}`;
+	}
+
+	addEventListener(name, func) {
+		this.events[name] = this.events[name] || new Set();
+		this.events[name].add(func);
+		changeCount++;
+	}
+	removeEventListener(name, func) {
+		if (this.events[name]) {
+			if (this.events[name].delete(func)) {
+				changeCount++
+			}
+		}
+	}
+	event(info) {
+		if (typeof info === 'string') info = {type: info};
+		let type = info.type;
+		info.target = this;
+		info.preventDefault = function(){};
+		info.stopPropagation = function(){ info.stopped = true; };
+		let node = this;
+		while(node && !info.stopped) {
+			let funcs = node.events[type];
+			if (funcs) {
+				for(let func of funcs) {
+					func.call(node, info);
+				}
+			}
+			node = node.parentNode;
+		}
+	}
+	getElementById(id) {
+		if (this.attrs.id === id) return this;
+		for(let child of this.childNodes) {
+			let el = child.getElementById(id);
+			if (el) return el;
+		}
+	}
+}
+
+class TextNode extends Node {
+	constructor(textContent) {
+		super();
+		this.textContent = '' + textContent;
+		newCount++;
+	}
+	toString() {
+		return JSON.stringify(this.textContent);
+	}
+}
+
+function getComputedStyle(el) {
+	return el._style;
+}
+
+
+global.Node = Node;
+global.TextNode = TextNode;
+global.Element = Element;
+global.getComputedStyle = getComputedStyle;

package/tests/_init.js

@@ -0,0 +1,81 @@
+import * as _ from './_fakedom.js';
+import mocha from 'mocha'
+import {deepEqual as equal} from 'fast-equals'
+
+import * as aberdeen from '../dist-min/aberdeen.js'
+import * as transitions from '../dist-min/transitions.js'
+import * as prediction from '../dist-min/prediction.js'
+Object.assign(global, aberdeen, transitions, prediction)
+
+let currentMountSeq = new Store(0)
+mocha.beforeEach(() => {
+	document.body = document.createElement('body')
+	resetCounts()
+})
+
+mocha.afterEach(() => {
+	unmount()
+	passTime(2001) // wait for deletion transitions
+	assertBody(``)
+})
+
+function toDisplay(value) {
+	if (value instanceof Map) {
+		let results = []
+		value.forEach((value,key) => results.push(JSON.stringify(key)+": "+JSON.stringify(value)))
+		return "map{" + results.join(", ") + "}"
+	} else {
+		return JSON.stringify(value)
+	}
+}
+
+global.AssertError = class extends Error {
+	constructor(text, actual, expected, expectLiteral) {
+		text += `
+		Actual:   ${toDisplay(actual)}
+		Expected: ${expectLiteral ? expected : toDisplay(expected)}`
+		super(text)
+	}
+}
+
+global.assert = function(bool, msg) {
+	if (!bool) throw new AssertError(`assert failed${msg ? ": "+msg : ""}`, bool, "something trueish", true)
+}
+
+global.assertEqual = function(actual, expected, msg) {
+	if (!equal(actual,expected)) throw new AssertError(`equal failed${msg ? ": "+msg : ""}`, actual, expected)
+}
+
+global.getBody = function() {
+	return document.body.toString().replace(/^body{/,'').replace(/}$/,'')
+}
+
+global.assertBody = function(expected) {
+	let actual = getBody()
+	if (actual !== expected) throw new AssertError(`assertBody failed`, actual, expected)
+}
+
+global.assertThrow = function(what, func) {
+	if (typeof what == 'function') {
+		func = what
+		what = undefined
+	}
+	try {
+		func()
+	} catch(e) {
+		if (what && e.toString().indexOf(what)<0) throw new AssertError(`wrong exception`, e.toString(), `something containing "${what}"`, true)
+		return
+	}
+	throw new AssertError(`exception expected`, undefined, `something containing "${what}"`, true)
+}
+
+global.objToMap = function(obj) {
+    if (typeof obj === 'object' && obj && obj.constructor===Object) {
+        let map = new Map()
+        for(let k in obj) {
+            map.set(k, objToMap(obj[k]))
+        }
+        return map
+    }
+    return obj
+}