shelving 1.54.0 → 1.55.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.54.0",
+	"version": "1.55.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/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/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;