aberdeen 0.0.10 → 0.0.11

package/dist/aberdeen.js

@@ -1,74 +1,79 @@
-/*
- * 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,6 +148,7 @@ class Scope {
         for (let cleaner of this.cleaners) {
             cleaner._clean(this);
         }
+        this.cleaners.length = 0;
     }
     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);
@@ -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);
@@ -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,7 +504,9 @@ 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) {
@@ -480,7 +519,10 @@ class ObsArray extends ObsCollection {
             if (index.length && num == index)
                 return index;
         }
-        throw new Error(`Invalid index ${JSON.stringify(index)} for array`);
+        throw new Error(`Invalid array index ${JSON.stringify(index)}`);
+    }
+    getCount() {
+        return this.data.length;
     }
 }
 class ObsMap extends ObsCollection {
@@ -538,6 +580,9 @@ class ObsMap extends ObsCollection {
     normalizeIndex(index) {
         return index;
     }
+    getCount() {
+        return this.data.size;
+    }
 }
 class ObsObject extends ObsMap {
     getType() {
@@ -577,7 +622,13 @@ class ObsObject extends ObsMap {
             return index;
         if (type === 'number')
             return '' + index;
-        throw new Error(`Invalid index ${JSON.stringify(index)} for object`);
+        throw new Error(`Invalid object index ${JSON.stringify(index)}`);
+    }
+    getCount() {
+        let cnt = 0;
+        for (let key of this.data)
+            cnt++;
+        return cnt;
     }
 }
 /*
@@ -607,34 +658,85 @@ 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);
     }
     /**
-     * Resolves `path` using `ref` and then retrieves the value that is there, subscribing
-     * to all read Store values. If `path` does not exist, `undefined` is returned.
+     * @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(...path) {
         return this.query({ path });
     }
-    /** Like `get()`, but throw an exception if the resulting value is not of the named type.
-     * Using these instead of `query()` directly is especially useful when using TypeScript.
+    /**
+     * @returns The same as [[`get`]], but doesn't subscribe to changes.
+     */
+    peek(...path) {
+        return this.query({ path, peek: true });
+    }
+    /**
+     * @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(...path) { return this.query({ path, type: 'number' }); }
+    /**
+     * @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(...path) { return this.query({ path, type: 'string' }); }
+    /**
+     * @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(...path) { return this.query({ path, type: 'boolean' }); }
+    /**
+     * @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.
+     */
     getFunction(...path) { return this.query({ path, type: 'function' }); }
+    /**
+     * @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.
+     */
     getArray(...path) { return this.query({ path, type: 'array' }); }
+    /**
+     * @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.
+     */
     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' }); }
-    /** The first parameter is the default value (returned when the Store contains `undefined`).
-     * This default value is also used to determine the expected time, and to throw otherwise.
+    /**
+     * @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;
@@ -646,31 +748,77 @@ export class Store {
         }
         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;
+        }
         let store = opts.path && opts.path.length ? this.ref(...opts.path) : this;
-        let value = store ? store._observe() : undefined;
+        let value = store._observe();
         if (opts.type && (value !== undefined || opts.defaultValue === undefined)) {
-            let type = (value instanceof ObsCollection) ? value.getType() : typeof value;
+            let type = (value instanceof ObsCollection) ? value.getType() : (value === null ? "null" : typeof value);
             if (type !== opts.type)
-                throw new Error(`Expecting ${opts.type} but got ${type}`);
+                throw new TypeError(`Expecting ${opts.type} but got ${type}`);
         }
         if (value instanceof ObsCollection) {
-            return value.getRecursive(opts.depth == null ? -1 : opts.depth);
+            return value.getRecursive(opts.depth == null ? -1 : opts.depth - 1);
         }
         return value === undefined ? opts.defaultValue : value;
     }
+    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 {
+            throw new Error(`count() expects a collection or undefined, but got ${JSON.stringify(value)}`);
+        }
+    }
     /**
      * Returns "undefined", "null", "boolean", "number", "string", "function", "array", "map" or "object"
      */
     getType(...path) {
         let store = this.ref(...path);
-        if (!store)
-            return "undefined";
         let value = store._observe();
-        return (value instanceof ObsCollection) ? value.getType() : typeof value;
+        return (value instanceof ObsCollection) ? value.getType() : (value === null ? "null" : typeof value);
     }
     /**
-     * Sets the Store value to the last given argument. And earlier argument are a Store-path that is first
+     * 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) {
@@ -679,57 +827,94 @@ export class Store {
         store.collection.setIndex(store.idx, newValue, true);
     }
     /**
-     * Does the same as set, but in case of a top-level collection, 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(...pathAndValue) {
-        let newValue = pathAndValue.pop();
-        let store = this.makeRef(...pathAndValue);
-        store.collection.setIndex(store.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(...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.
+     */
+    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.
      */
-    ref(...indexes) {
+    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)})`);
-                return;
+                    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;
     }
-    makeRef(...indexes) {
+    /**
+     * 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 < indexes.length; i++) {
+        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(indexes)})`);
+                    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(indexes[i]));
+            store = new Store(value, value.normalizeIndex(path[i]));
         }
         return store;
     }
+    /** @Internal */
     _observe() {
         if (currentScope) {
             if (this.collection.addObserver(this.idx, currentScope)) {
@@ -738,29 +923,6 @@ 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(...pathAndValue) {
-        let newValue = pathAndValue.pop();
-        let store = this.makeRef(...pathAndValue);
-        let obsArray = store.collection.rawGet(store.idx);
-        if (obsArray === undefined) {
-            obsArray = new ObsArray();
-            store.collection.setIndex(store.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;
-    }
     onEach(...pathAndFuncs) {
         let makeSortKey = defaultMakeSortKey;
         let renderer = pathAndFuncs.pop();
@@ -772,10 +934,8 @@ export class Store {
         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");
+            throw new ScopeError(false);
         let store = this.ref(...pathAndFuncs);
-        if (!store)
-            return;
         let val = store._observe();
         if (val instanceof ObsCollection) {
             // Subscribe to changes using the specialized OnEachScope
@@ -789,33 +949,123 @@ export class Store {
             throw new Error(`onEach() attempted on a value that is neither a collection nor undefined`);
         }
     }
+    /**
+     * 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 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);
+            }
+            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) {
@@ -835,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]);
@@ -863,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;
@@ -925,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
@@ -995,11 +1390,26 @@ function valueToData(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); };