shelving 1.54.0 → 1.57.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.54.0",
+	"version": "1.57.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -60,23 +60,23 @@
 	},
 	"devDependencies": {
 		"@google-cloud/firestore": "^5.0.2",
-		"@types/jest": "^27.4.0",
-		"@types/react": "^17.0.39",
-		"@types/react-dom": "^17.0.11",
-		"@typescript-eslint/eslint-plugin": "^5.12.0",
-		"@typescript-eslint/parser": "^5.12.0",
-		"eslint": "^8.9.0",
-		"eslint-config-prettier": "^8.4.0",
-		"eslint-plugin-import": "^2.25.4",
+		"@types/jest": "^27.4.1",
+		"@types/react": "^17.0.44",
+		"@types/react-dom": "^17.0.15",
+		"@typescript-eslint/eslint-plugin": "^5.20.0",
+		"@typescript-eslint/parser": "^5.20.0",
+		"eslint": "^8.14.0",
+		"eslint-config-prettier": "^8.5.0",
+		"eslint-plugin-import": "^2.26.0",
 		"eslint-plugin-prettier": "^4.0.0",
-		"firebase": "^9.6.7",
+		"firebase": "^9.6.11",
 		"jest": "^27.5.1",
 		"jest-ts-webcompat-resolver": "^1.0.0",
-		"prettier": "^2.5.1",
+		"prettier": "^2.6.2",
 		"react": "^17.0.2",
 		"react-dom": "^17.0.2",
-		"ts-jest": "^27.1.3",
-		"typescript": "^4.5.5"
+		"ts-jest": "^27.1.4",
+		"typescript": "^4.6.3"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=4.0.0",

package/react/index.d.ts

@@ -1,4 +1,5 @@
-export * from "./usePureMemo.js";
+export * from "./useLazy.js";
+export * from "./useInstance.js";
 export * from "./usePureEffect.js";
 export * from "./usePureState.js";
 export * from "./useSubscribe.js";

package/react/index.js

@@ -1,4 +1,5 @@
-export * from "./usePureMemo.js";
+export * from "./useLazy.js";
+export * from "./useInstance.js";
 export * from "./usePureEffect.js";
 export * from "./usePureState.js";
 export * from "./useSubscribe.js";

package/react/useDocument.js

@@ -1,16 +1,16 @@
 import { useState } from "react";
 import { CacheProvider, throwAsync, NOERROR, findSourceProvider, NOVALUE, callAsync, getDocumentData, isAsync } from "../index.js";
 import { usePureEffect } from "./usePureEffect.js";
-import { usePureMemo } from "./usePureMemo.js";
+import { useLazy } from "./useLazy.js";
 import { usePureState } from "./usePureState.js";
 export function useAsyncDocument(ref, maxAge = 1000) {
     // Create a memoed version of `ref`
-    const memoRef = usePureMemo(ref, ref === null || ref === void 0 ? void 0 : ref.toString());
+    const memoRef = useLazy(ref, ref === null || ref === void 0 ? void 0 : ref.toString());
     // Create two states to hold the value and error.
-    const [value, setNext] = usePureState(getCachedResult, memoRef);
+    const [value, setNext] = usePureState(_getCachedResult, memoRef);
     const [error, setError] = useState(NOERROR);
     // Register effect.
-    usePureEffect(subscribeEffect, memoRef, maxAge, setNext, setError);
+    usePureEffect(_subscribeEffect, memoRef, maxAge, setNext, setError);
     // Always return undefined if there's no ref.
     if (!ref)
         return undefined;
@@ -31,14 +31,14 @@ export function useAsyncDocument(ref, maxAge = 1000) {
     return result;
 }
 /** Get the initial result for a reference from the cache. */
-function getCachedResult(ref) {
+function _getCachedResult(ref) {
     if (!ref)
         return undefined;
     const provider = findSourceProvider(ref.db.provider, CacheProvider);
     return provider.isCached(ref) ? provider.cache.get(ref) : NOVALUE;
 }
 /** Effect that subscribes a component to the cache for a reference. */
-function subscribeEffect(ref, maxAge, setNext, setError) {
+function _subscribeEffect(ref, maxAge, setNext, setError) {
     if (ref) {
         const provider = findSourceProvider(ref.db.provider, CacheProvider);
         const stopCache = provider.cache.subscribe(ref, { next: setNext, error: setError });

package/react/useInstance.d.ts

@@ -0,0 +1,10 @@
+import { Arguments } from "../index.js";
+/**
+ * Use a (memoized) class instance.
+ *
+ * @param Class The class constructor to create an instance of.
+ *
+ * @param ...args Set of arguments that specify whether the returned value is refreshed or not.
+ * - This array of values is passed into the class constructor as its parameters.
+ */
+export declare function useInstance<T, A extends Arguments>(Class: new (...a: A) => T, ...args: A): T;

package/react/useInstance.js

@@ -0,0 +1,22 @@
+import { useRef } from "react";
+import { isArrayEqual } from "../index.js";
+/**
+ * Use a (memoized) class instance.
+ *
+ * @param Class The class constructor to create an instance of.
+ *
+ * @param ...args Set of arguments that specify whether the returned value is refreshed or not.
+ * - This array of values is passed into the class constructor as its parameters.
+ */
+export function useInstance(Class, ...args) {
+    var _a;
+    const internals = ((_a = useRef()).current || (_a.current = {
+        value: new Class(...args),
+        args,
+    }));
+    if (!isArrayEqual(args, internals.args)) {
+        internals.value = new Class(...args);
+        internals.args = args;
+    }
+    return internals.value;
+}

package/react/useLazy.d.ts

@@ -0,0 +1,14 @@
+import { Arguments } from "../index.js";
+/**
+ * Use a lazy value.
+ *
+ * Similar to React's `useMemo()` except...
+ * - Calls the initialiser function with `args` as its parameters.
+ * - Allows `initial` to be an initialiser function _or_ a plain value.
+ *
+ * @param value The plain value to memoise, or an initialiser function that returns that value.
+ * @param ...args Set of arguments that specify whether the returned value is refreshed or not.
+ * - This array of values is passed into the initialiser function as its parameters.
+ */
+export declare function useLazy<T, A extends Arguments>(value: (...args: A) => T, ...args: A): T;
+export declare function useLazy<T>(value: T, ...args: Arguments): T;

package/react/{usePureMemo.js → useLazy.js}

@@ -1,6 +1,6 @@
 import { useRef } from "react";
 import { isArrayEqual, getLazy } from "../index.js";
-export function usePureMemo(value, ...args) {
+export function useLazy(value, ...args) {
     var _a;
     const internals = ((_a = useRef()).current || (_a.current = {
         value: getLazy(value, ...args),

package/react/usePagination.js

@@ -1,16 +1,16 @@
 import { Pagination } from "../index.js";
 import { useSubscribe } from "./useSubscribe.js";
-import { usePureMemo } from "./usePureMemo.js";
+import { useLazy } from "./useLazy.js";
 /**
  * Use a `Pagination` for a collection.
  * - Doesn't persist the state, so if the component or anything beneath it throws the currently paginated results will be lost.
  */
 export function usePagination(ref, initial) {
-    const pagination = usePureMemo(createPagination, usePureMemo(ref, [ref.toString()]), initial);
+    const pagination = useLazy(_createPagination, useLazy(ref, [ref.toString()]), initial);
     useSubscribe(pagination);
     return pagination;
 }
-function createPagination(ref, initial) {
+function _createPagination(ref, initial) {
     const pagination = new Pagination(ref);
     if (initial)
         pagination.next(initial);

package/react/usePureEffect.d.ts

@@ -3,11 +3,7 @@ import { Arguments, Unsubscriber } from "../index.js";
  * Version of React's `useEffect()` that allows the use of a pure (side-effect free) function.
  *
  * @param effect The function that powers the effect.
- * - When called, receives the set of `args` as its arguments.
- *
  * @param ...args Set of arguments that specify whether the effect is re-run or not.
- * - This array of values is passed _into_ the function as its parameters.
- * - This means you can create the function once (outside the component) rather than creating it on every render.
- * - This improves performance (though probably only noticeable on functions that render 1,000s of times).
+ * - This array of values is passed into the effect function as its parameters.
  */
 export declare function usePureEffect<A extends Arguments>(effect: (...a: A) => Unsubscriber | void, ...args: A): void;

package/react/usePureEffect.js

@@ -1,14 +1,10 @@
-import { useRef, useEffect as useReactEffect } from "react";
+import { useRef, useEffect } from "react";
 /**
  * Version of React's `useEffect()` that allows the use of a pure (side-effect free) function.
  *
  * @param effect The function that powers the effect.
- * - When called, receives the set of `args` as its arguments.
- *
  * @param ...args Set of arguments that specify whether the effect is re-run or not.
- * - This array of values is passed _into_ the function as its parameters.
- * - This means you can create the function once (outside the component) rather than creating it on every render.
- * - This improves performance (though probably only noticeable on functions that render 1,000s of times).
+ * - This array of values is passed into the effect function as its parameters.
  */
 export function usePureEffect(effect, ...args) {
     var _a;
@@ -19,5 +15,5 @@ export function usePureEffect(effect, ...args) {
     }));
     internals.args = args;
     internals.effect = effect;
-    useReactEffect(internals.memoed, args);
+    useEffect(internals.memoed, args);
 }

package/react/usePureState.d.ts

@@ -3,16 +3,9 @@ import { Arguments } from "../index.js";
  * Version of React's `useState()` that allows the use of a pure (side-effect free) function.
  * - Unlike `useState()` the initialiser will be re-run and the state will be regenerated if `args` changes.
  *
- * @param initial The initial value of the state, or an initialiser function or class constructor that returns that value.
- * - If this is a plain value, that value is returned.
- * - If this is a function, it is called and its returned value is returned.
- * - If this is a class constructor, a new instance of that class is instantiated and returned.
- *
+ * @param initial The initial value of the state, or an initialiser function that returns that value.
  * @param ...args Set of arguments that specify whether the returned value is refreshed or not.
- * - This array of values is passed into the function or class constructor as its parameters.
- * - This means you can create the function once (outside the component) rather than creating it on every render.
- * - This improves performance (though probably only noticeable on functions that render 1,000s of times).
+ * - This array of values is passed into the initialiser function as its parameters.
  */
 export declare function usePureState<T, A extends Arguments>(initial: (...args: A) => T, ...args: A): readonly [T, (next: T) => void];
-export declare function usePureState<T, A extends Arguments>(initial: new (...args: A) => T, ...args: A): readonly [T, (next: T) => void];
 export declare function usePureState<T>(initial: T, ...args: Arguments): readonly [T, (next: T) => void];

package/react/usePureState.js

@@ -8,8 +8,8 @@ export function usePureState(initial, ...args) {
             getLazy(initial, ...args),
             (v) => {
                 if (internals.state[0] !== v) {
+                    internals.state = [v, internals.state[1]];
                     setState(v);
-                    internals.state[0] = v;
                 }
             },
         ],

package/react/useQuery.js

@@ -1,18 +1,18 @@
 import { useState } from "react";
 import { CacheProvider, NOERROR, findSourceProvider, NOVALUE, getMap, callAsync, getQueryData, throwAsync, ResultsObserver, getQueryResult, isAsync, } from "../index.js";
 import { usePureEffect } from "./usePureEffect.js";
-import { usePureMemo } from "./usePureMemo.js";
+import { useLazy } from "./useLazy.js";
 import { usePureState } from "./usePureState.js";
 export function useAsyncQuery(ref, maxAge = 1000) {
     // Create a memoed version of `ref`
-    const memoRef = usePureMemo(ref, ref === null || ref === void 0 ? void 0 : ref.toString());
+    const memoRef = useLazy(ref, ref === null || ref === void 0 ? void 0 : ref.toString());
     // Create two states to hold the value and error.
-    const [value, setNext] = usePureState(getCachedResults, memoRef);
+    const [value, setNext] = usePureState(_getCachedResults, memoRef);
     const [error, setError] = useState(NOERROR);
     if (error !== NOERROR)
         throw error; // If there's an error throw it.
     // Register effects.
-    usePureEffect(subscribeEffect, memoRef, maxAge, setNext, setError);
+    usePureEffect(_subscribeEffect, memoRef, maxAge, setNext, setError);
     // Always return undefined if there's no ref.
     if (!ref)
         return undefined;
@@ -30,14 +30,14 @@ export function useAsyncQuery(ref, maxAge = 1000) {
     return results;
 }
 /** Get the initial results for a reference from the cache. */
-function getCachedResults(ref) {
+function _getCachedResults(ref) {
     if (!ref)
         return undefined;
     const provider = findSourceProvider(ref.db.provider, CacheProvider);
     return provider.isCached(ref) ? getMap(provider.cache.getQuery(ref)) : NOVALUE;
 }
 /** Effect that subscribes a component to the cache for a reference. */
-function subscribeEffect(ref, maxAge, setNext, setError) {
+function _subscribeEffect(ref, maxAge, setNext, setError) {
     if (ref) {
         const provider = findSourceProvider(ref.db.provider, CacheProvider);
         const observer = new ResultsObserver({ next: setNext, error: setError });

package/stream/ArrayState.js

@@ -9,26 +9,26 @@ export class ArrayState extends State {
     }
     /** Get the length of the current value of this state. */
     get length() {
-        return this.value.length;
+        return this._value.length;
     }
     /** Add an item to this array. */
     add(item) {
-        this.next(withItem(this.value, item));
+        this.next(withItem(this._value, item));
     }
     /** Remove an item from this array. */
     delete(item) {
-        this.next(withoutItem(this.value, item));
+        this.next(withoutItem(this._value, item));
     }
     /** Swap an item in this array with a different item. */
     swap(oldItem, newItem) {
-        this.next(swapItem(this.value, oldItem, newItem));
+        this.next(swapItem(this._value, oldItem, newItem));
     }
     /** Toggle an item in this array. */
     toggle(item) {
-        this.next(toggleItem(this.value, item));
+        this.next(toggleItem(this._value, item));
     }
     /** Iterate over the items. */
     [Symbol.iterator]() {
-        return this.value.values();
+        return this._value.values();
     }
 }

package/stream/BooleanState.d.ts

@@ -0,0 +1,7 @@
+import { State } from "./State.js";
+/** State that stores a boolean and has additional methods to help with that. */
+export declare class BooleanState extends State<boolean> {
+    _value: boolean;
+    /** Toggle the current boolean value. */
+    toggle(): void;
+}

package/stream/BooleanState.js

@@ -0,0 +1,13 @@
+import { State } from "./State.js";
+/** State that stores a boolean and has additional methods to help with that. */
+export class BooleanState extends State {
+    constructor() {
+        super(...arguments);
+        // Set default value to be false.
+        this._value = false;
+    }
+    /** Toggle the current boolean value. */
+    toggle() {
+        this.next(this._value ? false : true);
+    }
+}

package/stream/LazyState.d.ts

@@ -1,12 +1,11 @@
-import type { Observer } from "../util/index.js";
+import { Observer } from "../util/index.js";
 import { State } from "./State.js";
 /**
  * State that tidies up after itself by completing itself after all its subscribers unsubscribe.
  * @param delay How long to wait (in ms) before the source subscription is stopped.
  */
 export declare class LazyState<T> extends State<T> {
-    private _delay;
-    private _timeout?;
-    constructor(delay?: number);
+    private _timeout;
+    constructor(delay?: number | null);
     _removeObserver(observer: Observer<T>): void;
 }

package/stream/LazyState.js

@@ -1,24 +1,23 @@
+import { Timeout } from "../util/index.js";
 import { State } from "./State.js";
 /**
  * State that tidies up after itself by completing itself after all its subscribers unsubscribe.
  * @param delay How long to wait (in ms) before the source subscription is stopped.
  */
 export class LazyState extends State {
-    constructor(delay = 0) {
+    constructor(delay = null) {
         super();
-        this._delay = delay;
+        this._timeout = delay ? new Timeout(delay) : null;
     }
     // Override to stop the source subscription when the last subscriber unsubscribes.
     _removeObserver(observer) {
         super._removeObserver(observer);
-        if (this._delay) {
+        if (this._timeout) {
             // Maybe stop in a bit (if there are still no subscribers).
-            if (this._timeout)
-                clearTimeout(this._timeout);
-            this._timeout = setTimeout(() => {
+            this._timeout.set(() => {
                 if (!this._observers.size && !this.closed)
                     this.complete();
-            }, this._delay);
+            });
         }
         else {
             // Stop now.

package/stream/ObjectState.d.ts

@@ -0,0 +1,14 @@
+import { Entry, ImmutableObject } from "../util/index.js";
+import { State } from "./State.js";
+/** State that stores a map-like object and has additional methods to help with that. */
+export declare class ObjectState<T> extends State<ImmutableObject<T>> implements Iterable<Entry<T>> {
+    _value: {};
+    /** Get the length of the current value of this state. */
+    get length(): number;
+    /** Remove a named entry from this object. */
+    delete(key: string): void;
+    /** Set a named entry in this object with a different value. */
+    set(key: string, value: T): void;
+    /** Iterate over the items. */
+    [Symbol.iterator](): Iterator<Entry<T>, void>;
+}

package/stream/ObjectState.js

@@ -0,0 +1,26 @@
+import { withEntry, withoutEntry } from "../util/index.js";
+import { State } from "./State.js";
+/** State that stores a map-like object and has additional methods to help with that. */
+export class ObjectState extends State {
+    constructor() {
+        super(...arguments);
+        // Set default value to be empty object.
+        this._value = {};
+    }
+    /** Get the length of the current value of this state. */
+    get length() {
+        return Object.keys(this._value).length;
+    }
+    /** Remove a named entry from this object. */
+    delete(key) {
+        this.next(withoutEntry(this._value, key));
+    }
+    /** Set a named entry in this object with a different value. */
+    set(key, value) {
+        this.next(withEntry(this._value, key, value));
+    }
+    /** Iterate over the items. */
+    [Symbol.iterator]() {
+        return Object.entries(this._value)[Symbol.iterator]();
+    }
+}

package/stream/index.d.ts

@@ -3,5 +3,7 @@ export * from "./LazyStream.js";
 export * from "./LastStream.js";
 export * from "./State.js";
 export * from "./LazyState.js";
+export * from "./BooleanState.js";
 export * from "./ArrayState.js";
+export * from "./ObjectState.js";
 export * from "./DataState.js";

package/stream/index.js

@@ -3,5 +3,7 @@ export * from "./LazyStream.js";
 export * from "./LastStream.js";
 export * from "./State.js";
 export * from "./LazyState.js";
+export * from "./BooleanState.js";
 export * from "./ArrayState.js";
+export * from "./ObjectState.js";
 export * from "./DataState.js";

package/util/async.d.ts

@@ -59,7 +59,3 @@ export declare class Signal extends AbstractPromise<typeof DONE> {
     /** Send this signal now. */
     done(): void;
 }
-/** Resolve to `DONE` after a specified delay. */
-export declare class Timeout extends AbstractPromise<typeof DONE> {
-    constructor(ms: number);
-}

package/util/async.js

@@ -95,10 +95,3 @@ export class Signal extends AbstractPromise {
         this._resolve(DONE);
     }
 }
-/** Resolve to `DONE` after a specified delay. */
-export class Timeout extends AbstractPromise {
-    constructor(ms) {
-        super();
-        setTimeout(this._resolve, ms, DONE);
-    }
-}

package/util/index.d.ts

@@ -31,6 +31,7 @@ export * from "./serialise.js";
 export * from "./sort.js";
 export * from "./string.js";
 export * from "./template.js";
+export * from "./timeout.js";
 export * from "./transform.js";
 export * from "./undefined.js";
 export * from "./units.js";

package/util/index.js

@@ -31,6 +31,7 @@ export * from "./serialise.js";
 export * from "./sort.js";
 export * from "./string.js";
 export * from "./template.js";
+export * from "./timeout.js";
 export * from "./transform.js";
 export * from "./undefined.js";
 export * from "./units.js";

package/util/lazy.d.ts

@@ -1,21 +1,18 @@
 import { Arguments } from "./function.js";
-import { Constructor } from "./class.js";
 /**
  * Lazy value: a plain value, or an initialiser function that returns that value.
  * @param ...args Any arguments the lazy value needs if it's a function.
  */
-export declare type Lazy<T, A extends Arguments = []> = ((...args: A) => T) | Constructor<T, A> | T;
+export declare type Lazy<T, A extends Arguments = []> = ((...args: A) => T) | T;
 /**
  * Initialise a lazy value.
  *
  * @param value The lazy value to resolve.
  * - If this is a plain value, that value is returned.
  * - If this is a function, it is called and its returned value is returned.
- * - If this is a class constructor, a new instance of that class is instantiated and returned.
  *
  * @param ...args Any additional arguments the initialiser needs.
  * - This array of values is passed into the function or class constructor as its parameters.
  */
 export declare function getLazy<T, A extends Arguments>(value: (...args: A) => T, ...args: A): T;
-export declare function getLazy<T, A extends Arguments>(value: new (...args: A) => T, ...args: A): T;
 export declare function getLazy<T, A extends Arguments>(value: Lazy<T, A>, ...args: A): T;

package/util/lazy.js

@@ -1,5 +1,4 @@
 import { isFunction } from "./function.js";
-import { isConstructor } from "./class.js";
 export function getLazy(value, ...args) {
-    return isConstructor(value) ? new value(...args) : isFunction(value) ? value(...args) : value;
+    return isFunction(value) ? value(...args) : value;
 }

package/util/template.d.ts

@@ -1,7 +1,7 @@
 import { Lazy } from "./lazy.js";
 import { ImmutableObject } from "./object.js";
 /** Template values in `{ placeholder: value }` format. */
-export declare type TemplateValues = ImmutableObject<string>;
+declare type TemplateValues = ImmutableObject<string>;
 /** Things that can be converted to the value for a named placeholder. */
 declare type PlaceholderValues = string | ((name: string) => string) | string[] | TemplateValues;
 /**
@@ -14,14 +14,12 @@ export declare const getPlaceholders: (template: string) => readonly string[];
 /**
  * Turn ":year-:month" and "2016-06..." etc into `{ year: "2016"... }`
  *
- * @param lazyTemplates Either a single template string, or an arr../function of template strings.
+ * @param lazyTemplates Either a single template string, or an iterator that returns multiple template template strings.
  * - Template strings can include placeholders (e.g. `:name-${country}/{city}`).
  * @param target The string containing values, e.g. `Dave-UK/Manchester`
  * @return An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`, or undefined if target didn't match the template.
  */
-export declare const matchTemplate: (lazyTemplates: Lazy<string | string[] | Iterable<string> | Generator<string>, [
-    string
-]>, target: string) => TemplateValues | undefined;
+export declare function matchTemplate(lazyTemplates: Lazy<string | Iterable<string>, [string]>, target: string): TemplateValues | undefined;
 /**
  * Turn ":year-:month" and `{ year: "2016"... }` etc into "2016-06..." etc.
  *

package/util/template.js

@@ -1,3 +1,4 @@
+import { getNameProp } from "./data.js";
 import { getLazy } from "./lazy.js";
 import { isObject } from "./object.js";
 // RegExp to find named variables in several formats e.g. `:a`, `${b}`, `{{c}}` or `{d}`
@@ -7,7 +8,7 @@ const R_NAME = /[a-z0-9]+/i;
 // Empty template.
 const EMPTY_TEMPLATE = Object.create(null);
 // Cache of templates.
-const cache = Object.create(null);
+const TEMPLATE_CACHE = Object.create(null);
 /**
  * Split up a template into an array of separator → placeholder → separator → placeholder → separator
  * - Odd numbered chunks are separators.
@@ -16,8 +17,8 @@ const cache = Object.create(null);
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @returns Array of strings alternating separator and placeholder.
  */
-const splitTemplate = (template) => (cache[template] || (cache[template] = _splitTemplate(template)));
-const _splitTemplate = (template) => {
+const splitTemplate = (template) => (TEMPLATE_CACHE[template] || (TEMPLATE_CACHE[template] = _split(template)));
+const _split = (template) => {
     var _a;
     const matches = template.split(R_PLACEHOLDERS);
     let asterisks = 0;
@@ -39,34 +40,32 @@ const _splitTemplate = (template) => {
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @returns Array of clean string names of found placeholders, e.g. `["name", "country", "city"]`
  */
-export const getPlaceholders = (template) => splitTemplate(template).map(getTemplateName);
-const getTemplateName = (chunk) => chunk.name;
+export const getPlaceholders = (template) => splitTemplate(template).map(getNameProp);
 /**
  * Turn ":year-:month" and "2016-06..." etc into `{ year: "2016"... }`
  *
- * @param lazyTemplates Either a single template string, or an arr../function of template strings.
+ * @param lazyTemplates Either a single template string, or an iterator that returns multiple template template strings.
  * - Template strings can include placeholders (e.g. `:name-${country}/{city}`).
  * @param target The string containing values, e.g. `Dave-UK/Manchester`
  * @return An object containing values, e.g. `{ name: "Dave", country: "UK", city: "Manchester" }`, or undefined if target didn't match the template.
  */
-export const matchTemplate = (lazyTemplates, target) => {
+export function matchTemplate(lazyTemplates, target) {
     const templates = getLazy(lazyTemplates, target);
     if (typeof templates === "string") {
-        const values = matchInternal(templates, target);
+        const values = _match(templates, target);
         if (values)
             return values;
     }
     else {
         for (const template of templates) {
-            const values = matchInternal(template, target);
+            const values = _match(template, target);
             if (values)
                 return values;
         }
     }
     return undefined;
-};
-// Internal match function (called several times).
-const matchInternal = (template, target) => {
+}
+function _match(template, target) {
     // Get separators and placeholders from template.
     const chunks = splitTemplate(template);
     const firstChunk = chunks[0];
@@ -92,7 +91,7 @@ const matchInternal = (template, target) => {
     if (startIndex < target.length)
         return undefined; // Target doesn't match template because last chunk post didn't reach the end.
     return values;
-};
+}
 /**
  * Turn ":year-:month" and `{ year: "2016"... }` etc into "2016-06..." etc.
  *
@@ -108,10 +107,10 @@ export const renderTemplate = (template, value) => {
         return template;
     let output = template;
     for (const { name, placeholder } of chunks)
-        output = output.replace(placeholder, getValue(name, value));
+        output = output.replace(placeholder, _replace(name, value));
     return output;
 };
-const getValue = (name, value) => {
+const _replace = (name, value) => {
     if (typeof value === "string")
         return value;
     if (typeof value === "function")
@@ -121,5 +120,5 @@ const getValue = (name, value) => {
         if (typeof v === "string")
             return v;
     }
-    throw new ReferenceError(`shelving/template: values.${name}: Must be defined`);
+    throw new ReferenceError(`renderTemplate(): values.${name}: Must be defined`);
 };

package/util/timeout.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Create a new Timeout.
+ *
+ * Wrapper for `setTimeout()` that...
+ * - Keeps track of the reference returned from `setTimeout()`
+ * - Clears the any existing timeout when a new timeout is set.
+ * - Allows a default delay to be set that is applied to all new timeouts that don't have a delay set.
+ *
+ * @param ms The default delay for any created timeouts (in ms).
+ */
+export declare class Timeout {
+    private _ms;
+    private _timeout;
+    constructor(ms?: number);
+    /**
+     * Cancel any existing timeout and set a new one.
+     * @param callback
+     * @param ms The delay for this timeout (in ms).
+     */
+    set(callback: () => void, ms?: number): void;
+    /** Cancel any existing timeout.. */
+    clear(): void;
+}

package/util/timeout.js

@@ -0,0 +1,30 @@
+/**
+ * Create a new Timeout.
+ *
+ * Wrapper for `setTimeout()` that...
+ * - Keeps track of the reference returned from `setTimeout()`
+ * - Clears the any existing timeout when a new timeout is set.
+ * - Allows a default delay to be set that is applied to all new timeouts that don't have a delay set.
+ *
+ * @param ms The default delay for any created timeouts (in ms).
+ */
+export class Timeout {
+    constructor(ms = 0) {
+        this._timeout = undefined;
+        this._ms = ms;
+    }
+    /**
+     * Cancel any existing timeout and set a new one.
+     * @param callback
+     * @param ms The delay for this timeout (in ms).
+     */
+    set(callback, ms = this._ms) {
+        this.clear();
+        this._timeout = setTimeout(callback, ms);
+    }
+    /** Cancel any existing timeout.. */
+    clear() {
+        if (this._timeout)
+            this._timeout = void clearTimeout(this._timeout);
+    }
+}

package/react/usePureMemo.d.ts

@@ -1,19 +0,0 @@
-import { Arguments } from "../index.js";
-/**
- * Version of React's `useMemo()` that allows the use of a pure (side-effect free) function.
- * - Also allows the first parameter to be a plain value that is memoised as long as `args` doesn't change.
- * - Also allows the first parameter to be a class constructor that will create a new instance of that class.
- *
- * @param value The value to memoise, or an initialiser function or class constructor that returns that value.
- * - If this is a plain value, that value is returned.
- * - If this is a function, it is called and its returned value is returned.
- * - If this is a class constructor, a new instance of that class is instantiated and returned.
- *
- * @param ...args Set of arguments that specify whether the returned value is refreshed or not.
- * - This array of values is passed into the function or class constructor as its parameters.
- * - This means you can create the function once (outside the component) rather than creating it on every render.
- * - This improves performance (though probably only noticeable on functions that render 1,000s of times).
- */
-export declare function usePureMemo<T, A extends Arguments>(value: (...args: A) => T, ...args: A): T;
-export declare function usePureMemo<T, A extends Arguments>(value: new (...args: A) => T, ...args: A): T;
-export declare function usePureMemo<T>(value: T, ...args: Arguments): T;