aberdeen 0.0.8 → 0.0.11

package/dist/aberdeen.js

@@ -1,73 +1,78 @@
-/*
- * QueueRunner
- *
- * `queue()`d runners are executed on the next timer tick, by order of their
- * `queueOrder` values.
- */
-let queued = new Set();
+let queueArray = [];
+let queueSet = new Set();
+let queueOrdered = true;
+let runQueueDepth = 0;
 function queue(runner) {
-    if (!queued.size) {
+    if (queueSet.has(runner))
+        return;
+    if (runQueueDepth > 42) {
+        throw new Error("Too many recursive updates from observes");
+    }
+    if (!queueArray.length) {
         setTimeout(runQueue, 0);
     }
-    queued.add(runner);
+    else if (runner.queueOrder < queueArray[queueArray.length - 1].queueOrder) {
+        queueOrdered = false;
+    }
+    queueArray.push(runner);
+    queueSet.add(runner);
 }
 function runQueue() {
-    // Order queued observers by depth, lowest first
-    let ordered;
-    if (Array.from) {
-        ordered = Array.from(queued);
-    }
-    else { // IE 11
-        ordered = [];
-        queued.forEach(item => ordered.push(item));
-    }
-    ordered.sort((a, b) => a.queueOrder - b.queueOrder);
-    for (let runner of ordered) {
-        queued.delete(runner);
-        let size = queued.size;
-        runner.queueRun();
-        if (queued.size !== size) {
-            // The queue was modified. We'll need to sort it again.
-            return runQueue();
-        }
-    }
+    for (let index = 0; index < queueArray.length;) {
+        if (!queueOrdered) {
+            queueArray.splice(0, index);
+            index = 0;
+            // Order queued observers by depth, lowest first
+            queueArray.sort((a, b) => a.queueOrder - b.queueOrder);
+            queueOrdered = true;
+        }
+        let batchEndIndex = queueArray.length;
+        for (; index < batchEndIndex && queueOrdered; index++) {
+            let runner = queueArray[index];
+            queueSet.delete(runner);
+            runner.queueRun();
+        }
+        runQueueDepth++;
+    }
+    queueArray.length = 0;
+    runQueueDepth = 0;
 }
 /**
  * Given an integer number, a string or an array of these, this function returns a string that can be used
  * to compare items in a natural sorting order. So `[3, 'ab']` should be smaller than `[3, 'ac']`.
  * The resulting string is guaranteed to never be empty.
  */
-export function sortKeyToString(key) {
+function sortKeyToString(key) {
     if (key instanceof Array) {
         return key.map(partToStr).join('');
     }
     else {
         return partToStr(key);
     }
-    function partToStr(part) {
-        if (typeof part === 'string') {
-            return part + '\x01';
-        }
-        else {
-            let result = numToString(Math.abs(Math.round(part)), part < 0);
-            // Prefix the number of digits, counting down from 128 for negative and up for positive
-            return String.fromCharCode(128 + (part > 0 ? result.length : -result.length)) + result;
-        }
-    }
-    function numToString(num, neg) {
-        let result = '';
-        while (num > 0) {
-            /*
-            * We're reserving a few character codes:
-            * 0 - for compatibility
-            * 1 - separator between array items
-            * 65535 - for compatibility
-            */
-            result += String.fromCharCode(neg ? 65535 - (num % 65533) : 2 + (num % 65533));
-            num = Math.floor(num / 65533);
-        }
-        return result;
+}
+function partToStr(part) {
+    if (typeof part === 'string') {
+        return part + '\x01';
     }
+    else {
+        let result = numToString(Math.abs(Math.round(part)), part < 0);
+        // Prefix the number of digits, counting down from 128 for negative and up for positive
+        return String.fromCharCode(128 + (part > 0 ? result.length : -result.length)) + result;
+    }
+}
+function numToString(num, neg) {
+    let result = '';
+    while (num > 0) {
+        /*
+        * We're reserving a few character codes:
+        * 0 - for compatibility
+        * 1 - separator between array items
+        * 65535 - for compatibility
+        */
+        result += String.fromCharCode(neg ? 65535 - (num % 65533) : 2 + (num % 65533));
+        num = Math.floor(num / 65533);
+    }
+    return result;
 }
 /*
  * Scope
@@ -109,28 +114,32 @@ class Scope {
             return this.lastChild.findLastNode() || this.lastChild.findPrecedingNode();
     }
     addNode(node) {
+        if (!this.parentElement)
+            throw new ScopeError(true);
         let prevNode = this.findLastNode() || this.findPrecedingNode();
         this.parentElement.insertBefore(node, prevNode ? prevNode.nextSibling : this.parentElement.firstChild);
         this.lastChild = node;
     }
     remove() {
-        let lastNode = this.findLastNode();
-        if (lastNode) {
-            // at least one DOM node to be removed
-            let precedingNode = this.findPrecedingNode();
-            // Keep removing DOM nodes starting at our last node, until we encounter the preceding node
-            // (which can be undefined)
-            while (lastNode !== precedingNode) {
-                /* istanbul ignore next */
-                if (!lastNode) {
-                    return internalError(1);
+        if (this.parentElement) {
+            let lastNode = this.findLastNode();
+            if (lastNode) {
+                // at least one DOM node to be removed
+                let precedingNode = this.findPrecedingNode();
+                // Keep removing DOM nodes starting at our last node, until we encounter the preceding node
+                // (which can be undefined)
+                while (lastNode !== precedingNode) {
+                    /* istanbul ignore next */
+                    if (!lastNode) {
+                        return internalError(1);
+                    }
+                    let nextLastNode = lastNode.previousSibling || undefined;
+                    this.parentElement.removeChild(lastNode);
+                    lastNode = nextLastNode;
                 }
-                let nextLastNode = lastNode.previousSibling || undefined;
-                this.parentElement.removeChild(lastNode);
-                lastNode = nextLastNode;
             }
+            this.lastChild = undefined;
         }
-        this.lastChild = undefined;
         // run cleaners
         this._clean();
     }
@@ -139,8 +148,9 @@ class Scope {
         for (let cleaner of this.cleaners) {
             cleaner._clean(this);
         }
+        this.cleaners.length = 0;
     }
-    onChange(collection, index, newData, oldData) {
+    onChange(index, newData, oldData) {
         queue(this);
     }
 }
@@ -173,6 +183,30 @@ class SimpleScope extends Scope {
         currentScope = savedScope;
     }
 }
+class IsEmptyObserver {
+    constructor(scope, collection, triggerCount) {
+        this.scope = scope;
+        this.collection = collection;
+        this.triggerCount = triggerCount;
+        this.count = collection.getCount();
+        collection.addObserver(ANY_INDEX, this);
+        scope.cleaners.push(this);
+    }
+    onChange(index, newData, oldData) {
+        if (newData === undefined) {
+            // oldData is guaranteed not to be undefined
+            if (this.triggerCount || !--this.count)
+                queue(this.scope);
+        }
+        else if (oldData === undefined) {
+            if (this.triggerCount || !this.count++)
+                queue(this.scope);
+        }
+    }
+    _clean() {
+        this.collection.removeObserver(ANY_INDEX, this);
+    }
+}
 class OnEachScope extends Scope {
     constructor(parentElement, precedingSibling, queueOrder, collection, renderer, makeSortKey) {
         super(parentElement, precedingSibling, queueOrder);
@@ -187,7 +221,7 @@ class OnEachScope extends Scope {
         this.renderer = renderer;
         this.makeSortKey = makeSortKey;
     }
-    onChange(collection, index, newData, oldData) {
+    onChange(index, newData, oldData) {
         if (oldData === undefined) {
             if (this.removedIndexes.has(index)) {
                 this.removedIndexes.delete(index);
@@ -224,8 +258,8 @@ class OnEachScope extends Scope {
     _clean() {
         super._clean();
         this.collection.observers.delete(this);
-        for (let item of this.byPosition) {
-            item._clean();
+        for (const [index, scope] of this.byIndex) {
+            scope._clean();
         }
         // Help garbage collection:
         this.byPosition.length = 0;
@@ -257,12 +291,13 @@ class OnEachScope extends Scope {
         scope.remove();
     }
     findPosition(sortStr) {
+        // In case of duplicate `sortStr`s, this will return the first match.
         let items = this.byPosition;
-        let min = 0, max = this.byPosition.length;
+        let min = 0, max = items.length;
         // Fast-path for elements that are already ordered (as is the case when working with arrays ordered by index)
         if (!max || sortStr > items[max - 1].sortStr)
             return max;
-        // Binary search for the insert position        
+        // Binary search for the insert position		
         while (min < max) {
             let mid = (min + max) >> 1;
             if (items[mid].sortStr < sortStr) {
@@ -288,6 +323,8 @@ class OnEachScope extends Scope {
         }
     }
     removeFromPosition(child) {
+        if (child.sortStr === '')
+            return;
         let pos = this.findPosition(child.sortStr);
         while (true) {
             if (this.byPosition[pos] === child) {
@@ -335,7 +372,7 @@ class OnEachItemScope extends Scope {
         let itemStore = new Store(this.parent.collection, this.itemIndex);
         let sortKey;
         try {
-            sortKey = this.parent.makeSortKey(itemStore); // TODO: catch
+            sortKey = this.parent.makeSortKey(itemStore);
         }
         catch (e) {
             handleError(e);
@@ -393,10 +430,10 @@ class ObsCollection {
     emitChange(index, newData, oldData) {
         let obsSet = this.observers.get(index);
         if (obsSet)
-            obsSet.forEach(observer => observer.onChange(this, index, newData, oldData));
+            obsSet.forEach(observer => observer.onChange(index, newData, oldData));
         obsSet = this.observers.get(ANY_INDEX);
         if (obsSet)
-            obsSet.forEach(observer => observer.onChange(this, index, newData, oldData));
+            obsSet.forEach(observer => observer.onChange(index, newData, oldData));
     }
     _clean(observer) {
         this.removeObserver(ANY_INDEX, observer);
@@ -404,7 +441,7 @@ class ObsCollection {
     setIndex(index, newValue, deleteMissing) {
         const curData = this.rawGet(index);
         if (!(curData instanceof ObsCollection) || newValue instanceof Store || !curData.merge(newValue, deleteMissing)) {
-            let newData = Store._valueToData(newValue);
+            let newData = valueToData(newValue);
             if (newData !== curData) {
                 this.rawSet(index, newData);
                 this.emitChange(index, newData, curData);
@@ -437,7 +474,7 @@ class ObsArray extends ObsCollection {
         return this.data[index];
     }
     rawSet(index, newData) {
-        if (index !== (0 | index) || index < 0 || index > 99999) {
+        if (index !== (0 | index) || index < 0 || index > 999999) {
             throw new Error(`Invalid array index ${JSON.stringify(index)}`);
         }
         this.data[index] = newData;
@@ -467,11 +504,25 @@ class ObsArray extends ObsCollection {
     }
     iterateIndexes(scope) {
         for (let i = 0; i < this.data.length; i++) {
-            scope.addChild(i);
+            if (this.data[i] !== undefined) {
+                scope.addChild(i);
+            }
         }
     }
     normalizeIndex(index) {
-        return 0 | index;
+        if (typeof index === 'number')
+            return index;
+        if (typeof index === 'string') {
+            // Convert to int
+            let num = 0 | index;
+            // Check if the number is still the same after conversion
+            if (index.length && num == index)
+                return index;
+        }
+        throw new Error(`Invalid array index ${JSON.stringify(index)}`);
+    }
+    getCount() {
+        return this.data.length;
     }
 }
 class ObsMap extends ObsCollection {
@@ -529,6 +580,9 @@ class ObsMap extends ObsCollection {
     normalizeIndex(index) {
         return index;
     }
+    getCount() {
+        return this.data.size;
+    }
 }
 class ObsObject extends ObsMap {
     getType() {
@@ -563,40 +617,18 @@ class ObsObject extends ObsMap {
         return true;
     }
     normalizeIndex(index) {
-        return '' + index;
-    }
-}
-class ObsDetached extends ObsCollection {
-    getType() {
-        return "obect";
-    }
-    getRecursive(depth) {
-        return {};
-    }
-    rawGet(index) {
-        return undefined;
-    }
-    rawSet(index) {
-        throw new Error("Updating a detached Store does not make sense");
-    }
-    merge(newValue, deleteMissing) {
-        throw new Error("Updating a detached Store does not make sense");
-    }
-    iterateIndexes(scope) {
-    }
-    normalizeIndex(index) {
-        return index;
-    }
-}
-const obsDetached = new ObsDetached();
-class StoreAttacher {
-    constructor(source, target) {
-        this.sourceStore = source;
-        this.targetData = target;
-    }
-    onChange(collection, index, newData, oldData) {
-        this.sourceStore.set(this.targetData);
-        collection.removeObserver(index, this);
+        let type = typeof index;
+        if (type === 'string')
+            return index;
+        if (type === 'number')
+            return '' + index;
+        throw new Error(`Invalid object index ${JSON.stringify(index)}`);
+    }
+    getCount() {
+        let cnt = 0;
+        for (let key of this.data)
+            cnt++;
+        return cnt;
     }
 }
 /*
@@ -615,7 +647,7 @@ export class Store {
             this.collection = new ObsArray();
             this.idx = 0;
             if (value !== undefined) {
-                this.collection.rawSet(0, Store._valueToData(value));
+                this.collection.rawSet(0, valueToData(value));
             }
         }
         else {
@@ -626,172 +658,263 @@ export class Store {
             this.idx = index;
         }
     }
+    /**
+     *
+     * @returns The index for this Store within its parent collection. This will be a `number`
+     * when the parent collection is an array, a `string` when it's an object, or any data type
+     * when it's a `Map`.
+     *
+     * @example
+     * ```
+     * let store = new Store({x: 123})
+     * let subStore = store.ref('x')
+     * assert(subStore.get() === 123)
+     * assert(subStore.index() === 'x') // <----
+     * ```
+     */
     index() {
         return this.idx;
     }
-    _read() {
-        return this.collection.rawGet(this.idx);
-    }
+    /** @internal */
     _clean(scope) {
         this.collection.removeObserver(this.idx, scope);
     }
     /**
-     * Return the value for this store, subscribing to the store and any nested sub-stores.
-     *
-     * @param defaultValue -
-     * @param useMaps - When this argument is `true`, objects are represented as Maps. By default, they are plain old JavaScript objects.
-     *
-     * options:
-     * - path
-     * - peek
-     * - throw if not type
-     * - default value (if undefined)
-     * - depth
+     * @returns Resolves `path` and then retrieves the value that is there, subscribing
+     * to all read `Store` values. If `path` does not exist, `undefined` is returned.
+     * @param path - Any path terms to resolve before retrieving the value.
+     * @example
+     * ```
+     * let store = new Store({a: {b: {c: {d: 42}}}})
+     * assert(store.get('a', 'b') === {c: {d: 42}})
+     * ```
      */
-    get(defaultValue, depth) {
-        let value = this._observe();
-        if (value instanceof ObsCollection) {
-            return value.getRecursive(depth == null ? -1 : depth);
-        }
-        return value === undefined ? defaultValue : value;
+    get(...path) {
+        return this.query({ path });
     }
     /**
-     * Returns "undefined", "null", "boolean", "number", "string", "function", "array", "map" or "object"
+     * @returns The same as [[`get`]], but doesn't subscribe to changes.
      */
-    getType() {
-        let value = this._observe();
-        return (value instanceof ObsCollection) ? value.getType() : typeof value;
+    peek(...path) {
+        return this.query({ path, peek: true });
     }
     /**
-     * Return the value of this Store as a number. If is has a different type, an error is thrown.
-     * If the Store contains `undefined` and a defaultValue is given, it is returned instead.
+     * @returns Like [[`get`]], but throws a `TypeError` if the resulting value is not of type `number`.
+     * Using this instead of just [[`get`]] is especially useful from within TypeScript.
      */
-    getNumber(defaultValue) {
-        let value = this._observe();
-        if (typeof value === 'number')
-            return value;
-        if (value === undefined && defaultValue !== undefined)
-            return defaultValue;
-        throw this.getTypeError('number', value);
-    }
+    getNumber(...path) { return this.query({ path, type: 'number' }); }
     /**
-     * Return the value of this Store as a string. If is has a different type, an error is thrown.
-     * If the Store contains `undefined` and a defaultValue is given, it is returned instead.
+     * @returns Like [[`get`]], but throws a `TypeError` if the resulting value is not of type `string`.
+     * Using this instead of just [[`get`]] is especially useful from within TypeScript.
      */
-    getString(defaultValue) {
-        let value = this._observe();
-        if (typeof value === 'string')
-            return value;
-        if (value === undefined && defaultValue !== undefined)
-            return defaultValue;
-        throw this.getTypeError('string', value);
-    }
+    getString(...path) { return this.query({ path, type: 'string' }); }
     /**
-     * Return the value of this Store as a boolean. If is has a different type, an error is thrown.
-     * If the Store contains `undefined` and a defaultValue is given, it is returned instead.
+     * @returns Like [[`get`]], but throws a `TypeError` if the resulting value is not of type `boolean`.
+     * Using this instead of just [[`get`]] is especially useful from within TypeScript.
      */
-    getBoolean(defaultValue) {
-        let value = this._observe();
-        if (typeof value === 'boolean')
-            return value;
-        if (value === undefined && defaultValue !== undefined)
-            return defaultValue;
-        throw this.getTypeError('boolean', value);
-    }
+    getBoolean(...path) { return this.query({ path, type: 'boolean' }); }
     /**
-     * Return the values of this Store as an Array. If is has a different type, an error is thrown.
-     * If the Store contains `undefined` and a defaultValue is given, it is returned instead.
+     * @returns Like [[`get`]], but throws a `TypeError` if the resulting value is not of type `function`.
+     * Using this instead of just [[`get`]] is especially useful from within TypeScript.
      */
-    getArray(defaultValue, depth) {
-        let value = this._observe();
-        if (value instanceof ObsArray) {
-            return value.getRecursive(depth == null ? -1 : depth);
-        }
-        if (value === undefined && defaultValue !== undefined)
-            return defaultValue;
-        throw this.getTypeError('array', value);
-    }
+    getFunction(...path) { return this.query({ path, type: 'function' }); }
     /**
-     * Return the values of this Store as an Object. If is has a different type, an error is thrown.
-     * If the Store contains `undefined` and a defaultValue is given, it is returned instead.
+     * @returns Like [[`get`]], but throws a `TypeError` if the resulting value is not of type `array`.
+     * Using this instead of just [[`get`]] is especially useful from within TypeScript.
      */
-    getObject(defaultValue, depth) {
-        let value = this._observe();
-        if (value instanceof ObsObject) {
-            return value.getRecursive(depth == null ? -1 : depth);
-        }
-        if (value === undefined && defaultValue !== undefined)
-            return defaultValue;
-        throw this.getTypeError('object', value);
-    }
+    getArray(...path) { return this.query({ path, type: 'array' }); }
     /**
-     * Return the values of this Store as an Object. If is has a different type, an error is thrown.
-     * If the Store contains `undefined` and a defaultValue is given, it is returned instead.
+     * @returns Like [[`get`]], but throws a `TypeError` if the resulting value is not of type `object`.
+     * Using this instead of just [[`get`]] is especially useful from within TypeScript.
      */
-    getMap(defaultValue, depth) {
-        let value = this._observe();
-        if (value instanceof ObsMap) {
-            return value.getRecursive(depth == null ? -1 : depth);
+    getObject(...path) { return this.query({ path, type: 'object' }); }
+    /**
+     * @returns Like [[`get`]], but throws a `TypeError` if the resulting value is not of type `map`.
+     * Using this instead of just [[`get`]] is especially useful from within TypeScript.
+     */
+    getMap(...path) { return this.query({ path, type: 'map' }); }
+    /**
+     * @returns Like [[`get`]], but the first parameter is the default value (returned when the Store
+     * contains `undefined`). This default value is also used to determine the expected type,
+     * and to throw otherwise.
+     */
+    getOr(defaultValue, ...path) {
+        let type = typeof defaultValue;
+        if (type === 'object') {
+            if (defaultValue instanceof Map)
+                type = 'map';
+            else if (defaultValue instanceof Array)
+                type = 'array';
+        }
+        return this.query({ type, defaultValue, path });
+    }
+    /** Retrieve a value. This is a more flexible form of the [[`get`]] and [[`peek`]] methods.
+     * @returns The resulting value, or `undefined` if the `path` does not exist.
+     */
+    query(opts) {
+        if (opts.peek && currentScope) {
+            let savedScope = currentScope;
+            currentScope = undefined;
+            let result = this.query(opts);
+            currentScope = savedScope;
+            return result;
         }
-        if (value === undefined && defaultValue !== undefined)
-            return defaultValue;
-        throw this.getTypeError('map', value);
+        let store = opts.path && opts.path.length ? this.ref(...opts.path) : this;
+        let value = store._observe();
+        if (opts.type && (value !== undefined || opts.defaultValue === undefined)) {
+            let type = (value instanceof ObsCollection) ? value.getType() : (value === null ? "null" : typeof value);
+            if (type !== opts.type)
+                throw new TypeError(`Expecting ${opts.type} but got ${type}`);
+        }
+        if (value instanceof ObsCollection) {
+            return value.getRecursive(opts.depth == null ? -1 : opts.depth - 1);
+        }
+        return value === undefined ? opts.defaultValue : value;
     }
-    getTypeError(type, value) {
-        if (value === undefined) {
-            return new Error(`Expecting ${type} but got undefined, and no default value was given`);
+    isEmpty(...path) {
+        let store = this.ref(...path);
+        let value = store._observe();
+        if (value instanceof ObsCollection) {
+            if (currentScope) {
+                let observer = new IsEmptyObserver(currentScope, value, false);
+                return !observer.count;
+            }
+            else {
+                return !value.getCount();
+            }
+        }
+        else if (value === undefined) {
+            return true;
+        }
+        else {
+            throw new Error(`isEmpty() expects a collection or undefined, but got ${JSON.stringify(value)}`);
+        }
+    }
+    count(...path) {
+        let store = this.ref(...path);
+        let value = store._observe();
+        if (value instanceof ObsCollection) {
+            if (currentScope) {
+                let observer = new IsEmptyObserver(currentScope, value, true);
+                return observer.count;
+            }
+            else {
+                return value.getCount();
+            }
+        }
+        else if (value === undefined) {
+            return 0;
         }
         else {
-            return new Error(`Expecting ${type} but got ${value instanceof ObsCollection ? value.getRecursive(-1) : JSON.stringify(value)}`);
+            throw new Error(`count() expects a collection or undefined, but got ${JSON.stringify(value)}`);
         }
     }
-    set(newValue) {
-        this.collection.setIndex(this.idx, newValue, true);
+    /**
+     * Returns "undefined", "null", "boolean", "number", "string", "function", "array", "map" or "object"
+     */
+    getType(...path) {
+        let store = this.ref(...path);
+        let value = store._observe();
+        return (value instanceof ObsCollection) ? value.getType() : (value === null ? "null" : typeof value);
+    }
+    /**
+     * Sets the Store value to the last given argument. Any earlier argument are a Store-path that is first
+     * resolved/created using `makeRef`.
+     */
+    set(...pathAndValue) {
+        let newValue = pathAndValue.pop();
+        let store = this.makeRef(...pathAndValue);
+        store.collection.setIndex(store.idx, newValue, true);
     }
     /**
-     * Does the same as merge, but in case of a top-level map, it doesn't
-     * delete keys that don't exist in `value`.
+     * Sets the `Store` to the given `mergeValue`, but without deleting any pre-existing
+     * items when a collection overwrites a similarly typed collection. This results in
+     * a deep merge.
      */
-    merge(newValue) {
-        this.collection.setIndex(this.idx, newValue, false);
+    merge(mergeValue) {
+        this.collection.setIndex(this.idx, mergeValue, false);
     }
     /**
-     * Sets the value for the store to `undefined`, which causes it to be ommitted from the map (or array, if it's at the end)
+     * Sets the value for the store to `undefined`, which causes it to be omitted from the map (or array, if it's at the end)
      */
-    delete() {
-        this.collection.setIndex(this.idx, undefined, true);
+    delete(...path) {
+        let store = this.makeRef(...path);
+        store.collection.setIndex(store.idx, undefined, true);
     }
     /**
-     * Return an store deeper within the tree by resolving each of the
-     * arguments as Map indexes, while subscribing to each level.
-     * If any level does not exist, a detached Store object is returned,
-     * that will be automatically attached if it is written to.
+     * Pushes a value to the end of the Array that is at the specified path in the store.
+     * If that Store path is `undefined`, and Array is created first.
+     * The last argument is the value to be added, any earlier arguments indicate the path.
      */
-    ref(...indexes) {
+    push(newValue) {
+        let obsArray = this.collection.rawGet(this.idx);
+        if (obsArray === undefined) {
+            obsArray = new ObsArray();
+            this.collection.setIndex(this.idx, obsArray, true);
+        }
+        else if (!(obsArray instanceof ObsArray)) {
+            throw new Error(`push() is only allowed for an array or undefined (which would become an array)`);
+        }
+        let newData = valueToData(newValue);
+        let pos = obsArray.data.length;
+        obsArray.data.push(newData);
+        obsArray.emitChange(pos, newData, undefined);
+        return pos;
+    }
+    /**
+     * [[`peek`]] the current value, pass it through `func`, and [[`set`]] the resulting
+     * value.
+     * @param func The function transforming the value.
+     */
+    modify(func) {
+        this.set(func(this.query({ peek: true })));
+    }
+    /**
+     * Return a `Store` deeper within the tree by resolving the given `path`,
+     * subscribing to every level.
+     * In case `undefined` is encountered while resolving the path, a newly
+     * created `Store` containing `undefined` is returned. In that case, the
+     * `Store`'s [[`isDetached`]] method will return `true`.
+     * In case something other than a collection is encountered, an error is thrown.
+     */
+    ref(...path) {
         let store = this;
-        for (let i = 0; i < indexes.length; i++) {
+        for (let i = 0; i < path.length; i++) {
             let value = store._observe();
             if (value instanceof ObsCollection) {
-                store = new Store(value, value.normalizeIndex(indexes[i]));
+                store = new Store(value, value.normalizeIndex(path[i]));
             }
             else {
                 if (value !== undefined)
-                    throw new Error(`Value ${JSON.stringify(value)} is not a collection (nor undefined) in step ${i} of $(${JSON.stringify(indexes)})`);
-                // The rest of the path will be created in a detached state
-                let detachedObject = new ObsObject();
-                let object = detachedObject;
-                for (; i < indexes.length - 1; i++) {
-                    let newObject = new ObsObject();
-                    object.data.set("" + indexes[i], newObject);
-                    object = newObject;
-                }
-                let index = "" + indexes[indexes.length - 1];
-                object.addObserver(index, new StoreAttacher(store, detachedObject));
-                return new Store(object, index);
+                    throw new Error(`Value ${JSON.stringify(value)} is not a collection (nor undefined) in step ${i} of $(${JSON.stringify(path)})`);
+                return new DetachedStore();
             }
         }
         return store;
     }
+    /**
+     * Similar to `ref()`, but instead of returning `undefined`, new objects are created when
+     * a path does not exist yet. An error is still thrown when the path tries to index an invalid
+     * type.
+     * Unlike `ref`, `makeRef` does *not* subscribe to the path levels, as it is intended to be
+     * a write-only operation.
+     */
+    makeRef(...path) {
+        let store = this;
+        for (let i = 0; i < path.length; i++) {
+            let value = store.collection.rawGet(store.idx);
+            if (!(value instanceof ObsCollection)) {
+                if (value !== undefined)
+                    throw new Error(`Value ${JSON.stringify(value)} is not a collection (nor undefined) in step ${i} of $(${JSON.stringify(path)})`);
+                value = new ObsObject();
+                store.collection.rawSet(store.idx, value);
+                store.collection.emitChange(store.idx, value, undefined);
+            }
+            store = new Store(value, value.normalizeIndex(path[i]));
+        }
+        return store;
+    }
+    /** @Internal */
     _observe() {
         if (currentScope) {
             if (this.collection.addObserver(this.idx, currentScope)) {
@@ -800,31 +923,20 @@ export class Store {
         }
         return this.collection.rawGet(this.idx);
     }
-    /**
-     * Adds `newValue` as a value to a Map, indexed by the old `size()` of the Map. An
-     * error is thrown if that index already exists.
-     * In case the Store does not refers to `undefined`, the Array is created first.
-     * @param newValue
-     */
-    push(newValue) {
-        let obsArray = this.collection.rawGet(this.idx);
-        if (obsArray === undefined) {
-            obsArray = new ObsArray();
-            this.collection.setIndex(this.idx, obsArray, true);
+    onEach(...pathAndFuncs) {
+        let makeSortKey = defaultMakeSortKey;
+        let renderer = pathAndFuncs.pop();
+        if (typeof pathAndFuncs[pathAndFuncs.length - 1] === 'function' && (typeof renderer === 'function' || renderer == null)) {
+            if (renderer != null)
+                makeSortKey = renderer;
+            renderer = pathAndFuncs.pop();
         }
-        else if (!(obsArray instanceof ObsArray)) {
-            throw new Error(`push() is only allowed for an array or undefined (which would become an array)`);
-        }
-        let newData = Store._valueToData(newValue);
-        let pos = obsArray.data.length;
-        obsArray.data.push(newData);
-        obsArray.emitChange(pos, newData, undefined);
-        return pos;
-    }
-    onEach(renderer, makeSortKey = Store._makeDefaultSortKey) {
+        if (typeof renderer !== 'function')
+            throw new Error(`onEach() expects a render function as its last argument but got ${JSON.stringify(renderer)}`);
         if (!currentScope)
-            throw new Error("onEach() is only allowed from a render scope");
-        let val = this._observe();
+            throw new ScopeError(false);
+        let store = this.ref(...pathAndFuncs);
+        let val = store._observe();
         if (val instanceof ObsCollection) {
             // Subscribe to changes using the specialized OnEachScope
             let onEachScope = new OnEachScope(currentScope.parentElement, currentScope.lastChild || currentScope.precedingSibling, currentScope.queueOrder + 1, val, renderer, makeSortKey);
@@ -837,79 +949,123 @@ export class Store {
             throw new Error(`onEach() attempted on a value that is neither a collection nor undefined`);
         }
     }
-    static _valueToData(value) {
-        if (typeof value !== "object" || !value) {
-            // Simple data types
-            return value;
-        }
-        else if (value instanceof Store) {
-            // When a Store is passed pointing at a collection, a reference
-            // is made to that collection.
-            return value._observe();
-        }
-        else if (value instanceof Map) {
-            let result = new ObsMap();
-            value.forEach((v, k) => {
-                let d = Store._valueToData(v);
-                if (d !== undefined)
-                    result.rawSet(k, d);
-            });
-            return result;
-        }
-        else if (value instanceof Array) {
-            let result = new ObsArray();
-            for (let i = 0; i < value.length; i++) {
-                let d = Store._valueToData(value[i]);
-                if (d !== undefined)
-                    result.rawSet(i, d);
+    /**
+     * Applies a filter/map function on each item within the `Store`'s collection,
+     * and reactively manages the returned `Map` `Store` to hold any results.
+     *
+     * @param func - Function that transform the given store into an output value or
+     * `undefined` in case this value should be skipped:
+     *
+     * @returns - A map `Store` with the values returned by `func` and the corresponding
+     * keys from the original map, array or object `Store`.
+     *
+     * When items disappear from the `Store` or are changed in a way that `func` depends
+     * upon, the resulting items are removed from the output `Store` as well. When multiple
+     * input items produce the same output keys, this may lead to unexpected results.
+     */
+    map(func) {
+        let out = new Store(new Map());
+        this.onEach((item) => {
+            let value = func(item);
+            if (value !== undefined) {
+                let key = item.index();
+                out.set(key, value);
+                clean(() => {
+                    out.delete(key);
+                });
             }
-            return result;
-        }
-        else if (value.constructor === Object) {
-            // A plain (literal) object
-            let result = new ObsObject();
-            for (let k in value) {
-                let d = Store._valueToData(value[k]);
-                if (d !== undefined)
-                    result.rawSet(k, d);
+        });
+        return out;
+    }
+    /*
+    * Applies a filter/map function on each item within the `Store`'s collection,
+    * each of which can deliver any number of key/value pairs, and reactively manages the
+    * returned map `Store` to hold any results.
+    *
+    * @param func - Function that transform the given store into output values
+    * that can take one of the following forms:
+    * - an `Object` or a `Map`: Each key/value pair will be added to the output `Store`.
+    * - anything else: No key/value pairs are added to the output `Store`.
+    *
+    * @returns - A map `Store` with the key/value pairs returned by all `func` invocations.
+    *
+    * When items disappear from the `Store` or are changed in a way that `func` depends
+    * upon, the resulting items are removed from the output `Store` as well. When multiple
+    * input items produce the same output keys, this may lead to unexpected results.
+    */
+    multiMap(func) {
+        let out = new Store(new Map());
+        this.onEach((item) => {
+            let result = func(item);
+            let keys;
+            if (result.constructor === Object) {
+                for (let key in result) {
+                    out.set(key, result[key]);
+                }
+                keys = Object.keys(result);
             }
-            return result;
-        }
-        else {
-            // Any other type of object (including ObsCollection)
-            return value;
-        }
-    }
-    static _makeDefaultSortKey(store) {
-        return store.index();
+            else if (result instanceof Map) {
+                result.forEach((value, key) => {
+                    out.set(key, value);
+                });
+                keys = Array.from(result.keys());
+            }
+            else {
+                return;
+            }
+            if (keys.length) {
+                clean(() => {
+                    for (let key of keys) {
+                        out.delete(key);
+                    }
+                });
+            }
+        });
+        return out;
     }
+    /**
+     * @returns Returns `true` when the `Store` was created by [[`ref`]]ing a path that
+     * does not exist.
+     */
+    isDetached() { return false; }
+}
+class DetachedStore extends Store {
+    isDetached() { return true; }
 }
 /**
  * Create a new DOM element.
- * @param tagClass - The tag of the element to be created and optionally dot-seperated class names. For example: `h1` or `p.intro.has_avatar`.
+ * @param tag - The tag of the element to be created and optionally dot-separated class names. For example: `h1` or `p.intro.has_avatar`.
  * @param rest - The other arguments are flexible and interpreted based on their types:
  *   - `string`: Used as textContent for the element.
  *   - `object`: Used as attributes/properties for the element. See `applyProp` on how the distinction is made.
  *   - `function`: The render function used to draw the scope of the element. This function gets its own `Scope`, so that if any `Store` it reads changes, it will redraw by itself.
+ *   - `Store`: Presuming `tag` is `"input"`, `"textarea"` or `"select"`, create a two-way binding between this `Store` value and the input element. The initial value of the input will be set to the initial value of the `Store`. After that, the `Store` will be updated when the input changes.
  * @example
  * node('aside.editorial', 'Yada yada yada....', () => {
- *     node('a', {href: '/bio'}, () => {
- *         node('img.author', {src: '/me.jpg', alt: 'The author'})
- *     })
+ *	 node('a', {href: '/bio'}, () => {
+ *		 node('img.author', {src: '/me.jpg', alt: 'The author'})
+ *	 })
  * })
  */
-export function node(tagClass, ...rest) {
+export function node(tag = "", ...rest) {
     if (!currentScope)
-        throw new Error(`node() outside of a render scope`);
+        throw new ScopeError(true);
     let el;
-    if (tagClass.indexOf('.') >= 0) {
-        let classes = tagClass.split('.');
-        let tag = classes.shift();
-        el = document.createElement(tag);
-        el.className = classes.join(' ');
+    if (tag instanceof Element) {
+        el = tag;
     }
     else {
-        el = document.createElement(tagClass);
+        let pos = tag.indexOf('.');
+        let classes;
+        if (pos >= 0) {
+            classes = tag.substr(pos + 1);
+            tag = tag.substr(0, pos);
+        }
+        el = document.createElement(tag || 'div');
+        if (classes) {
+            // @ts-ignore (replaceAll is polyfilled)
+            el.className = classes.replaceAll('.', ' ');
+        }
     }
     currentScope.addNode(el);
     for (let item of rest) {
@@ -929,24 +1085,62 @@ export function node(tagClass, ...rest) {
                 applyProp(el, k, item[k]);
             }
         }
+        else if (item instanceof Store) {
+            bindInput(el, item);
+        }
         else if (item != null) {
             throw new Error(`Unexpected argument ${JSON.stringify(item)}`);
         }
     }
 }
+function bindInput(el, store) {
+    let updater;
+    let type = el.getAttribute('type');
+    let value = store.query({ peek: true });
+    if (type === 'checkbox') {
+        if (value === undefined)
+            store.set(el.checked);
+        else
+            el.checked = value;
+        updater = () => store.set(el.checked);
+    }
+    else if (type === 'radio') {
+        if (value === undefined) {
+            if (el.checked)
+                store.set(el.value);
+        }
+        else
+            el.checked = value === el.value;
+        updater = () => {
+            if (el.checked)
+                store.set(el.value);
+        };
+    }
+    else {
+        if (value === undefined)
+            store.set(el.value);
+        else
+            el.value = value;
+        updater = () => store.set(el.value);
+    }
+    el.addEventListener('input', updater);
+    clean(() => {
+        el.removeEventListener('input', updater);
+    });
+}
 /**
  * Add a text node at the current Scope position.
  */
 export function text(text) {
     if (!currentScope)
-        throw new Error(`text() outside of a render scope`);
-    if (!text)
+        throw new ScopeError(true);
+    if (text == null)
         return;
     currentScope.addNode(document.createTextNode(text));
 }
 export function prop(prop, value = undefined) {
-    if (!currentScope)
-        throw new Error(`prop() outside of a render scope`);
+    if (!currentScope || !currentScope.parentElement)
+        throw new ScopeError(true);
     if (typeof prop === 'object') {
         for (let k in prop) {
             applyProp(currentScope.parentElement, k, prop[k]);
@@ -957,54 +1151,153 @@ export function prop(prop, value = undefined) {
     }
 }
 /**
- * Register a `clean` function that is executed when the current `Scope` disappears or redraws.
+ * Return the browser Element that `node()`s would be rendered to at this point.
+ * NOTE: Manually changing the DOM is not recommended in most cases. There is
+ * usually a better, declarative way. Although there are no hard guarantees on
+ * how your changes interact with Aberdeen, in most cases results will not be
+ * terribly surprising. Be careful within the parent element of onEach() though.
+ */
+export function getParentElement() {
+    if (!currentScope || !currentScope.parentElement)
+        throw new ScopeError(true);
+    return currentScope.parentElement;
+}
+/**
+ * Register a function that is to be executed right before the current reactive scope
+ * disappears or redraws.
+ * @param clean - The function to be executed.
  */
 export function clean(clean) {
     if (!currentScope)
-        throw new Error(`clean() outside of a render scope`);
+        throw new ScopeError(false);
     currentScope.cleaners.push({ _clean: clean });
 }
 /**
- * Create a new Scope and execute the `renderer` within that Scope. When
- * `Store`s that the `renderer` reads are updated, only this Scope will
- * need to be refreshed, leaving the parent Scope untouched.
+ * Create a new reactive scope and execute the `func` within that scope. When
+ * `Store`s that the `func` reads are updated, only this scope will need to be refreshed,
+ * leaving the parent scope untouched.
+ *
+ * In case this function is called outside of a an existing scope, it will create a new
+ * top-level scope (a [[`Mount`]]) without a `parentElement`, meaning that aberdeen operations
+ * that create/modify DOM elements are not permitted.
+ * @param func - The function to be (repeatedly) executed within the newly created scope.
+ * @returns The newly created `Mount` object in case this is a top-level reactive scope.
+ * @example
+ * ```
+ * let store = new Store('John Doe')
+ * mount(document.body, () => {
+ *     node('div.card', () => {
+ * 	       node('input', {placeholder: 'Name'}, store)
+ *         observe(() => {
+ * 		       prop('class', {correct: store.get().length > 5})
+ * 		   })
+ * 	   })
+ * })
+ * ```
  */
-export function scope(renderer) {
-    if (!currentScope)
-        throw new Error(`scope() outside of a render scope`);
-    let scope = new SimpleScope(currentScope.parentElement, currentScope.lastChild || currentScope.precedingSibling, currentScope.queueOrder + 1, renderer);
-    currentScope.lastChild = scope;
-    scope.update();
-    // Add it to our list of cleaners. Even if `scope` currently has
-    // no cleaners, it may get them in a future refresh.
-    currentScope.cleaners.push(scope);
+/**
+ * Reactively run a function, meaning the function will rerun when any `Store` that was read
+ * during its execution is updated.
+ * Calls to `observe` can be nested, such that changes to `Store`s read by the inner function do
+ * no cause the outer function to rerun.
+ *
+ * @param func - The function to be (repeatedly) executed.
+ * @example
+ * ```
+ * let number = new Store(0)
+ * let doubled = new Store()
+ * setInterval(() => number.set(0|Math.random()*100)), 1000)
+ *
+ * observe(() => {
+ *   doubled.set(number.get() * 2)
+ * })
+ *
+ * observe(() => {
+ *   console.log(doubled.get())
+ * })
+ */
+export function observe(func) {
+    mount(undefined, func);
 }
 /**
- * Main entry point for using aberdeen. The elements created by the given `render` function are appended to `parentElement` (and updated when read `Store`s change).
- * @param parentElement - The DOM element to append to.
- * @param renderer - The function that does the rendering.
+ * Like [[`observe`]], but allow the function to create DOM elements using [[`node`]].
+
+ * @param func - The function to be (repeatedly) executed, possibly adding DOM elements to `parentElement`.
+ * @param parentElement - A DOM element that will be used as the parent element for calls to `node`.
+ *
  * @example
+ * ```
+ * let store = new Store(0)
+ * setInterval(() => store.modify(v => v+1), 1000)
+ *
  * mount(document.body, () => {
- *     node('h1', 'Hello world!', () => {
- *         node('img.logo', {src: '/logo.png'})
- *     })
+ * 	   node('h2', `${store.get()} seconds have passed`)
  * })
- */
-class Mount {
-    constructor(scope) {
-        this.scope = scope;
+ * ```
+ *
+ * An example nesting [[`observe`]] within `mount`:
+ * ```
+ * let selected = new Store(0)
+ * let colors = new Store(new Map())
+ *
+ * mount(document.body, () => {
+ * 	// This function will never rerun (as it does not read any `Store`s)
+ * 	node('button', '<<', {click: () => selected.modify(n => n-1)})
+ * 	node('button', '>>', {click: () => selected.modify(n => n+1)})
+ *
+ * 	observe(() => {
+ * 		// This will rerun whenever `selected` changes, recreating the <h2> and <input>.
+ * 		node('h2', '#'+selected.get())
+ * 		node('input', {type: 'color', value: '#ffffff'}, colors.ref(selected.get()))
+ * 	})
+ *
+ * 	observe(() => {
+ * 		// This function will rerun when `selected` or the selected color changes.
+ * 		// It will change the <body> background-color.
+ * 		prop({style: {backgroundColor: colors.get(selected.get()) || 'white'}})
+ * 	})
+ * })
+ * ```
+*/
+export function mount(parentElement, func) {
+    let scope;
+    if (parentElement || !currentScope) {
+        scope = new SimpleScope(parentElement, undefined, 0, func);
     }
-    unmount() {
-        this.scope.remove();
+    else {
+        scope = new SimpleScope(currentScope.parentElement, currentScope.lastChild || currentScope.precedingSibling, currentScope.queueOrder + 1, func);
+        currentScope.lastChild = scope;
     }
-}
-export function mount(parentElement, renderer) {
-    if (currentScope)
-        throw new Error('mount() from within a render scope');
-    let scope = new SimpleScope(parentElement, undefined, 0, renderer);
+    // Do the initial run
     scope.update();
-    return new Mount(scope);
+    // Add it to our list of cleaners. Even if `scope` currently has
+    // no cleaners, it may get them in a future refresh.
+    if (currentScope) {
+        currentScope.cleaners.push(scope);
+    }
 }
+/** Runs the given function, while not subscribing the current scope when reading [[`Store`]] values.
+ *
+ * @param func Function to be executed immediately.
+ * @returns Whatever `func()` returns.
+ * @example
+ * ```
+ * import {Store, peek, text} from aberdeen
+ *
+ * let store = new Store(['a', 'b', 'c'])
+ *
+ * mount(document.body, () => {
+ *     // Prevent rerender when store changes
+ *     peek(() => {
+ *         text(`Store has ${store.count()} elements, and the first is ${store.get(0)}`)
+ *     })
+ * })
+ * ```
+ *
+ * In the above example `store.get(0)` could be replaced with `store.peek(0)` to achieve the
+ * same result without `peek()` wrapping everything. There is no non-subscribing equivalent
+ * for `count()` however.
+ */
 export function peek(func) {
     let savedScope = currentScope;
     currentScope = undefined;
@@ -1019,16 +1312,24 @@ export function peek(func) {
  * Helper functions
  */
 function applyProp(el, prop, value) {
-    if (prop === 'value' || prop === 'className' || prop === 'selectedIndex' || value === true || value === false) {
+    if ((prop === 'class' || prop === 'className') && typeof value === 'object') {
+        // Allow setting classes using an object where the keys are the names and
+        // the values are booleans stating whether to set or remove.
+        for (let name in value) {
+            if (value[name])
+                el.classList.add(name);
+            else
+                el.classList.remove(name);
+        }
+    }
+    else if (prop === 'value' || prop === 'className' || prop === 'selectedIndex' || value === true || value === false) {
         // All boolean values and a few specific keys should be set as a property
         el[prop] = value;
     }
     else if (typeof value === 'function') {
         // Set an event listener; remove it again on clean.
         el.addEventListener(prop, value);
-        if (currentScope) {
-            clean(() => el.removeEventListener(prop, value));
-        }
+        clean(() => el.removeEventListener(prop, value));
     }
     else if (prop === 'style' && typeof value === 'object') {
         // `style` can receive an object
@@ -1043,11 +1344,72 @@ function applyProp(el, prop, value) {
         el.setAttribute(prop, value);
     }
 }
+function valueToData(value) {
+    if (typeof value !== "object" || !value) {
+        // Simple data types
+        return value;
+    }
+    else if (value instanceof Store) {
+        // When a Store is passed pointing at a collection, a reference
+        // is made to that collection.
+        return value._observe();
+    }
+    else if (value instanceof Map) {
+        let result = new ObsMap();
+        value.forEach((v, k) => {
+            let d = valueToData(v);
+            if (d !== undefined)
+                result.rawSet(k, d);
+        });
+        return result;
+    }
+    else if (value instanceof Array) {
+        let result = new ObsArray();
+        for (let i = 0; i < value.length; i++) {
+            let d = valueToData(value[i]);
+            if (d !== undefined)
+                result.rawSet(i, d);
+        }
+        return result;
+    }
+    else if (value.constructor === Object) {
+        // A plain (literal) object
+        let result = new ObsObject();
+        for (let k in value) {
+            let d = valueToData(value[k]);
+            if (d !== undefined)
+                result.rawSet(k, d);
+        }
+        return result;
+    }
+    else {
+        // Any other type of object (including ObsCollection)
+        return value;
+    }
+}
+function defaultMakeSortKey(store) {
+    return store.index();
+}
+/* istanbul ignore next */
 function internalError(code) {
-    console.error(new Error("internal error " + code));
+    let error = new Error("internal error " + code);
+    setTimeout(() => { throw error; }, 0);
 }
 function handleError(e) {
-    console.error(e);
     // Throw the error async, so the rest of the rendering can continue
     setTimeout(() => { throw e; }, 0);
 }
+class ScopeError extends Error {
+    constructor(mount) {
+        super(`Operation not permitted outside of ${mount ? "a mount" : "an observe"}() scope`);
+    }
+}
+let arrayFromSet = Array.from || /* istanbul ignore next */ ((set) => {
+    let array = [];
+    set.forEach(item => array.push(item));
+    return array;
+});
+// @ts-ignore
+// istanbul ignore next
+if (!String.prototype.replaceAll)
+    String.prototype.replaceAll = function (from, to) { return this.split(from).join(to); };