shelving 1.66.0 → 1.68.1

package/db/Database.d.ts

@@ -1,9 +1,7 @@
 import type { Validators, ValidatorType } from "../util/validate.js";
-import type { Key, Datas } from "../util/data.js";
+import type { Key, Datas, Entity } from "../util/data.js";
 import type { Provider } from "../provider/Provider.js";
-import type { SortKeys } from "../query/Sort.js";
-import type { FilterProps } from "../query/Filter.js";
-import { Entity } from "../util/data.js";
+import type { QueryProps } from "../query/Query.js";
 import { DocumentReference, QueryReference } from "./Reference.js";
 /**
  * Combines a database model and a provider.
@@ -17,7 +15,7 @@ export declare class Database<V extends Validators<Datas> = Validators<Datas>> {
     readonly provider: Provider;
     constructor(validators: V, provider: Provider);
     /** Create a query on a collection in this model. */
-    query<K extends Key<V>>(collection: K, filters?: FilterProps<Entity<ValidatorType<V[K]>>>, sorts?: SortKeys<Entity<ValidatorType<V[K]>>>, limit?: number | null): QueryReference<ValidatorType<V[K]>>;
+    query<K extends Key<V>>(collection: K, query?: QueryProps<Entity<ValidatorType<V[K]>>>): QueryReference<ValidatorType<V[K]>>;
     /** Reference a document in a collection in this model. */
     doc<K extends Key<V>>(collection: K, id: string): DocumentReference<ValidatorType<V[K]>>;
     /**

package/db/Database.js

@@ -1,5 +1,3 @@
-import { Filters } from "../query/Filters.js";
-import { Sorts } from "../query/Sorts.js";
 import { DocumentReference, QueryReference } from "./Reference.js";
 /**
  * Combines a database model and a provider.
@@ -15,8 +13,9 @@ export class Database {
         this.provider = provider;
     }
     /** Create a query on a collection in this model. */
-    query(collection, filters, sorts, limit) {
-        return new QueryReference(this, this.validators[collection], collection, filters && Filters.on(filters), sorts && Sorts.on(sorts), limit);
+    query(collection, query) {
+        const validator = this.validators[collection];
+        return new QueryReference(this, validator, collection, query);
     }
     /** Reference a document in a collection in this model. */
     doc(collection, id) {

package/db/Reference.d.ts

@@ -1,15 +1,11 @@
 import type { Data, OptionalData, Entity, OptionalEntity, Entities } from "../util/data.js";
 import type { Dispatch } from "../util/function.js";
-import type { SortKeys } from "../query/Sort.js";
 import { ImmutableArray } from "../util/array.js";
 import type { PartialObserver } from "../observe/Observer.js";
 import type { Validator } from "../util/validate.js";
-import { Query } from "../query/Query.js";
-import { Filters } from "../query/Filters.js";
-import { Sorts } from "../query/Sorts.js";
+import { Query, QueryProps } from "../query/Query.js";
 import { DataUpdate, PropUpdates } from "../update/DataUpdate.js";
-import { FilterProps } from "../query/Filter.js";
-import { Observable, Unsubscribe } from "../observe/Observable.js";
+import type { Observable, Unsubscribe } from "../observe/Observable.js";
 import type { Database } from "./Database.js";
 /** A refence to a location in a database. */
 export interface Reference {
@@ -21,7 +17,7 @@ export declare class QueryReference<T extends Data = Data> extends Query<Entity<
     readonly db: Database;
     readonly validator: Validator<T>;
     readonly collection: string;
-    constructor(db: Database, validator: Validator<T>, collection: string, filters?: Filters<Entity<T>>, sorts?: Sorts<Entity<T>>, limit?: number | null);
+    constructor(db: Database, validator: Validator<T>, collection: string, { sort, limit, ...filters }?: QueryProps<Entity<T>>);
     /** Reference a document in this query's collection. */
     doc(id: string): DocumentReference<T>;
     /**
@@ -104,7 +100,7 @@ export declare class DocumentReference<T extends Data = Data> implements Observa
     readonly id: string;
     constructor(db: Database, validator: Validator<T>, collection: string, id: string);
     /** Create a query on this document's collection. */
-    query(filters?: FilterProps<Entity<T>>, sorts?: SortKeys<Entity<T>>, limit?: number | null): QueryReference<T>;
+    query(query?: QueryProps<Entity<T>>): QueryReference<T>;
     /** Get an 'optional' reference to this document (uses a `ModelQuery` with an `id` filter). */
     get optional(): QueryReference<T>;
     /**

package/db/Reference.js

@@ -5,12 +5,11 @@ import { Sorts } from "../query/Sorts.js";
 import { callAsync } from "../util/async.js";
 import { countItems, hasItems } from "../util/iterate.js";
 import { DataUpdate } from "../update/DataUpdate.js";
-import { Filter } from "../query/Filter.js";
 import { RequiredError } from "../error/RequiredError.js";
 /** A query reference within a specific database. */
 export class QueryReference extends Query {
-    constructor(db, validator, collection, filters, sorts, limit) {
-        super(filters, sorts, limit);
+    constructor(db, validator, collection, { sort, limit, ...filters } = {}) {
+        super(Filters.on(filters), sort && Sorts.on(sort), limit);
         this.db = db;
         this.validator = validator;
         this.collection = collection;
@@ -127,12 +126,12 @@ export class DocumentReference {
         this.id = id;
     }
     /** Create a query on this document's collection. */
-    query(filters, sorts, limit) {
-        return new QueryReference(this.db, this.validator, this.collection, filters && Filters.on(filters), sorts && Sorts.on(sorts), limit);
+    query(query) {
+        return new QueryReference(this.db, this.validator, this.collection, query);
     }
     /** Get an 'optional' reference to this document (uses a `ModelQuery` with an `id` filter). */
     get optional() {
-        return new QueryReference(this.db, this.validator, this.collection, new Filters(new Filter("id", "IS", this.id)));
+        return new QueryReference(this.db, this.validator, this.collection, { id: this.id, limit: 1 });
     }
     /**
      * Does this document exist?

package/index.js

@@ -19,5 +19,8 @@ export * from "./update/index.js";
 export * from "./util/index.js";
 // Integrations.
 // export * from "./react/index.js"; // Not exported.
+// export * from "./firestore/client/index.js"; // Not exported.
+// export * from "./firestore/lite/index.js"; // Not exported.
+// export * from "./firestore/server/index.js"; // Not exported.
 // Testing.
 // export * from "./test/index.js"; // Not exported.

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.66.0",
+	"version": "1.68.1",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -29,11 +29,12 @@
 		"./firestore/lite": "./firestore/lite/index.js",
 		"./firestore/server": "./firestore/server/index.js",
 		"./markup": "./markup/index.js",
+		"./observe": "./observe/index.js",
 		"./provider": "./provider/index.js",
 		"./query": "./query/index.js",
 		"./react": "./react/index.js",
 		"./schema": "./schema/index.js",
-		"./stream": "./stream/index.js",
+		"./state": "./state/index.js",
 		"./test": "./test/index.js",
 		"./update": "./update/index.js",
 		"./util": "./util/index.js"

package/provider/MemoryProvider.d.ts

@@ -16,14 +16,14 @@ export declare class MemoryProvider extends Provider implements SynchronousProvi
     /** List of tables in `{ path: Table }` format. */
     private _tables;
     getTable<T extends Data>({ collection }: DocumentReference<T> | QueryReference<T>): MemoryTable<T>;
-    getDocumentTime<T extends Data>(ref: DocumentReference<T>): number | undefined;
+    getDocumentTime<T extends Data>(ref: DocumentReference<T>): number | null;
     getDocument<T extends Data>(ref: DocumentReference<T>): OptionalEntity<T>;
     subscribeDocument<T extends Data>(ref: DocumentReference<T>, observer: PartialObserver<OptionalEntity<T>>): Unsubscribe;
     addDocument<T extends Data>(ref: QueryReference<T>, data: T): string;
     setDocument<T extends Data>(ref: DocumentReference<T>, data: T): void;
     updateDocument<T extends Data>(ref: DocumentReference<T>, update: DataUpdate<T>): void;
     deleteDocument<T extends Data>(ref: DocumentReference<T>): void;
-    getQueryTime<T extends Data>(ref: QueryReference<T>): number | undefined;
+    getQueryTime<T extends Data>(ref: QueryReference<T>): number | null;
     getQuery<T extends Data>(ref: QueryReference<T>): Entities<T>;
     subscribeQuery<T extends Data>(ref: QueryReference<T>, observer: PartialObserver<Entities<T>>): Unsubscribe;
     setQuery<T extends Data>(ref: QueryReference<T>, data: T): number;
@@ -39,17 +39,21 @@ export declare class MemoryTable<T extends Data> extends Subject<void> {
     protected _times: Map<string, number>;
     protected _listeners: Set<Dispatch<[]>>;
     protected _firing: boolean;
-    getDocumentTime(id: string): number | undefined;
+    getDocumentTime(id: string): number | null;
     getDocument(id: string): OptionalEntity<T>;
     subscribeDocument(id: string, observer: PartialObserver<OptionalEntity<T>>): Unsubscribe;
+    /** Subscribe to a query in this table, but only if the query has been explicitly set (and has a time). */
+    subscribeCachedDocument(id: string, observer: PartialObserver<OptionalEntity<T>>): Unsubscribe;
     addDocument(data: T): string;
     setEntity(entity: Entity<T>): void;
     setDocument(id: string, data: T): void;
     updateDocument(id: string, update: DataUpdate<T>): void;
     deleteDocument(id: string): void;
-    getQueryTime(query: Query<Entity<T>>): number | undefined;
+    getQueryTime(query: Query<Entity<T>>): number | null;
     getQuery(query: Query<Entity<T>>): Entities<T>;
     subscribeQuery(query: Query<Entity<T>>, observer: PartialObserver<Entities<T>>): Unsubscribe;
+    /** Subscribe to a query in this table, but only if the query has been explicitly set (and has a time). */
+    subscribeCachedQuery(query: Query<Entity<T>>, observer: PartialObserver<Entities<T>>): Unsubscribe;
     protected _getWrites(query: Query<Entity<T>>): Iterable<Entity<T>>;
     setEntities(query: Query<Entity<T>>, entities: Entities<T>): number;
     setQuery(query: Query<Entity<T>>, data: T): number;

package/provider/MemoryProvider.js

@@ -76,7 +76,7 @@ export class MemoryTable extends Subject {
         this._firing = false;
     }
     getDocumentTime(id) {
-        return this._times.get(id);
+        return this._times.get(id) || null;
     }
     getDocument(id) {
         return this._data.get(id) || null;
@@ -94,6 +94,23 @@ export class MemoryTable extends Subject {
             }
         });
     }
+    /** Subscribe to a query in this table, but only if the query has been explicitly set (and has a time). */
+    subscribeCachedDocument(id, observer) {
+        // Call next() immediately with initial results.
+        let last = this.getDocument(id);
+        if (this._times.has(id))
+            dispatchNext(observer, last);
+        // Call next() every time the collection changes.
+        return this.subscribe(() => {
+            if (this._times.has(id)) {
+                const next = this.getDocument(id);
+                if (next !== last) {
+                    last = next;
+                    dispatchNext(observer, last);
+                }
+            }
+        });
+    }
     addDocument(data) {
         let id = getRandomKey();
         while (this._data.has(id))
@@ -122,7 +139,7 @@ export class MemoryTable extends Subject {
         this.next();
     }
     getQueryTime(query) {
-        return this._times.get(_getQueryReference(query));
+        return this._times.get(_getQueryReference(query)) || null;
     }
     getQuery(query) {
         return getArray(query.transform(this._data.values()));
@@ -140,6 +157,24 @@ export class MemoryTable extends Subject {
             }
         });
     }
+    /** Subscribe to a query in this table, but only if the query has been explicitly set (and has a time). */
+    subscribeCachedQuery(query, observer) {
+        // Call next() immediately with initial results.
+        const ref = _getQueryReference(query);
+        let last = this.getQuery(query);
+        if (this._times.has(ref))
+            dispatchNext(observer, last);
+        // Call next() every time the collection changes.
+        return this.subscribe(() => {
+            if (this._times.has(ref)) {
+                const next = this.getQuery(query);
+                if (next !== last) {
+                    last = next;
+                    dispatchNext(observer, last);
+                }
+            }
+        });
+    }
     _getWrites(query) {
         // Queries that have no limit don't care about sorting either.
         // So sorting can be skipped for performance.
@@ -196,5 +231,5 @@ export class MemoryTable extends Subject {
 }
 function _getQueryReference(query) {
     // Queries that have no limit don't care about sorting either.
-    return query.limit ? `filters=${query.filters.toString()}` : Query.prototype.toString.call(query);
+    return query.limit ? `{${query.filters.toString()}}` : Query.prototype.toString.call(query);
 }

package/provider/ThroughProvider.d.ts

@@ -32,4 +32,4 @@ export interface AsynchronousThroughProvider extends AsynchronousProvider {
     new (source: AsynchronousProvider): AsynchronousProvider;
 }
 /** Find a specific source provider in a database's provider stack. */
-export declare function findSourceProvider<P extends Provider>(provider: Provider, type: Class<P>): P;
+export declare function findSourceProvider<P extends Provider>(provider: Provider, type: Class<P>): P | undefined;

package/provider/ThroughProvider.js

@@ -1,4 +1,3 @@
-import { AssertionError } from "../error/AssertionError.js";
 import { Provider } from "./Provider.js";
 /**
  * Pass all reads and writes through to a source provider.
@@ -48,5 +47,4 @@ export function findSourceProvider(provider, type) {
         return provider;
     if (provider instanceof ThroughProvider)
         return findSourceProvider(provider.source, type);
-    throw new AssertionError(`Source provider ${type.name} not found`, provider);
 }

package/query/Filter.js

@@ -51,6 +51,26 @@ export class Filter extends Rule {
         return filterItems(items, this);
     }
     toString() {
-        return `${this.key}:${this.operator}:${JSON.stringify(this.value)}`;
+        return `"${_formatKey(this)}":${JSON.stringify(this.value)}`;
+    }
+}
+/** Convert a `Filter` */
+function _formatKey({ key, operator }) {
+    switch (operator) {
+        case "NOT":
+        case "OUT":
+            return `!${key}`;
+        case "CONTAINS":
+            return `${key}[]`;
+        case "LT":
+            return `${key}<`;
+        case "LTE":
+            return `${key}<=`;
+        case "GT":
+            return `${key}>`;
+        case "GTE":
+            return `${key}>=`;
+        default:
+            return key;
     }
 }

package/query/Query.d.ts

@@ -5,6 +5,11 @@ import { Sortable, Sorts } from "./Sorts.js";
 import { Rule } from "./Rule.js";
 import { FilterProps } from "./Filter.js";
 import { SortKey, SortKeys } from "./Sort.js";
+/** Set of props for a query defined as an object. */
+export declare type QueryProps<T extends Data> = FilterProps<T> & {
+    readonly sort?: SortKey<T> | ImmutableArray<SortKey<T>>;
+    readonly limit?: number | null;
+};
 /** Interface that combines Filterable, Sortable, Sliceable. */
 export interface Queryable<T extends Data> extends Filterable<T>, Sortable<T> {
     /**
@@ -26,11 +31,13 @@ export interface Queryable<T extends Data> extends Filterable<T>, Sortable<T> {
     readonly limit: number | null;
     /** Return a new instance of this class with a limit set. */
     max(max: number | null): this;
+    /** Return a new instance of this class with new filters, sorts, limits set. */
+    query(query: QueryProps<T>): this;
 }
 /** Allows filtering, sorting, and limiting on a set of results. */
 export declare class Query<T extends Data> extends Rule<T> implements Queryable<T> {
     /** Create a new `Query` object from a set of `QueryProps` */
-    static on<X extends Data>(filters?: FilterProps<X>, sorts?: SortKey<X> | ImmutableArray<SortKey<X>>, limit?: number | null): Query<X>;
+    static on<X extends Data>({ sort, limit, ...filters }: QueryProps<X>): Query<X>;
     readonly filters: Filters<T>;
     readonly sorts: Sorts<T>;
     readonly limit: number | null;
@@ -44,10 +51,10 @@ export declare class Query<T extends Data> extends Rule<T> implements Queryable<
     sort(...keys: SortKeys<T>[]): this;
     get unsort(): this;
     rank(left: T, right: T): number;
-    /** Return a new instance of this class with a limit defined. */
-    max(limit: number | null): this;
     after(item: T): this;
     before(item: T): this;
+    max(limit: number | null): this;
+    query({ sort, limit, ...filters }: QueryProps<T>): this;
     transform(items: Iterable<T>): Iterable<T>;
     toString(): string;
 }

package/query/Query.js

@@ -17,32 +17,44 @@ export class Query extends Rule {
         this.limit = limit;
     }
     /** Create a new `Query` object from a set of `QueryProps` */
-    static on(filters, sorts, limit) {
-        return new Query(filters && Filters.on(filters), sorts && Sorts.on(sorts), limit);
+    static on({ sort, limit, ...filters }) {
+        return new Query(filters && Filters.on(filters), sort && Sorts.on(sort), limit);
     }
     filter(input, value) {
-        return { __proto__: Object.getPrototypeOf(this), ...this, filters: this.filters.filter(input, value) }; // eslint-disable-line @typescript-eslint/no-explicit-any
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            filters: this.filters.filter(input, value), // eslint-disable-line @typescript-eslint/no-explicit-any
+        };
     }
     get unfilter() {
-        return { __proto__: Object.getPrototypeOf(this), ...this, filters: EMPTY_FILTERS };
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            filters: EMPTY_FILTERS,
+        };
     }
     match(item) {
         return this.filters.match(item);
     }
     // Implement `Sortable`
     sort(...keys) {
-        return { __proto__: Object.getPrototypeOf(this), ...this, sorts: this.sorts.sort(...keys) };
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            sorts: this.sorts.sort(...keys),
+        };
     }
     get unsort() {
-        return { __proto__: Object.getPrototypeOf(this), ...this, sorts: EMPTY_SORTS };
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            sorts: EMPTY_SORTS,
+        };
     }
     rank(left, right) {
         return this.sorts.rank(left, right);
     }
-    /** Return a new instance of this class with a limit defined. */
-    max(limit) {
-        return limit === this.limit ? this : { __proto__: Object.getPrototypeOf(this), ...this, limit };
-    }
     // Implement `Queryable`
     after(item) {
         const filters = [...this.filters];
@@ -52,7 +64,11 @@ export class Query extends Rule {
             const { key, direction } = sort;
             filters.push(new Filter(key, direction === "ASC" ? (sort === lastSort ? "GT" : "GTE") : sort === lastSort ? "LT" : "LTE", getProp(item, key)));
         }
-        return { __proto__: Object.getPrototypeOf(this), ...this, filters: new Filters(...filters) };
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            filters: new Filters(...filters),
+        };
     }
     before(item) {
         const filters = [...this.filters];
@@ -62,7 +78,27 @@ export class Query extends Rule {
             const { key, direction } = sort;
             filters.push(new Filter(key, direction === "ASC" ? (sort === lastSort ? "LT" : "LTE") : sort === lastSort ? "GT" : "GTE", getProp(item, key)));
         }
-        return { __proto__: Object.getPrototypeOf(this), ...this, filters: new Filters(...filters) };
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            filters: new Filters(...filters),
+        };
+    }
+    max(limit) {
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            limit,
+        };
+    }
+    query({ sort, limit, ...filters }) {
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            filters: this.filters.filter(filters),
+            sorts: sort ? this.sorts.sort(sort) : this.sorts,
+            limit: limit !== undefined ? limit : this.limit,
+        };
     }
     // Implement `Rule`
     transform(items) {
@@ -71,6 +107,8 @@ export class Query extends Rule {
     }
     // Implement toString()
     toString() {
-        return `filters=${this.filters}&sorts=${this.sorts}${this.limit ? `&limit=${this.limit}` : ""}`;
+        const filters = this.filters.toString();
+        const sorts = this.sorts.toString();
+        return `{${filters}${sorts ? `${filters ? "," : ""}"sort":[${sorts}]` : ""}${typeof this.limit === "number" ? `${filters || sorts ? "," : ""}"limit":${this.limit}` : ""}}`;
     }
 }

package/query/Rules.js

@@ -18,8 +18,9 @@ export class Rules extends Rule {
     get size() {
         return this._rules.length;
     }
+    // Override to join the strings from the rules together with `,` commas.
     toString() {
-        return this._rules.map(toString).join(",");
+        return this._rules.map(String).join(",");
     }
     /** Clone this set of rules but add additional rules. */
     with(...rules) {

package/query/Sort.js

@@ -19,6 +19,6 @@ export class Sort extends Rule {
         return sortItems(items, this);
     }
     toString() {
-        return `${this.direction === "DESC" ? "!" : ""}${this.key}`;
+        return `"${this.direction === "DESC" ? "!" : ""}${this.key}"`;
     }
 }

package/react/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useInstance.js";
+export * from "./useCache.js";
 export * from "./useSubscribe.js";
 export * from "./useDocument.js";
 export * from "./useQuery.js";

package/react/index.js

@@ -2,6 +2,7 @@
 export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useInstance.js";
+export * from "./useCache.js";
 // Observables.
 export * from "./useSubscribe.js";
 // DB.

package/react/useCache.d.ts

@@ -0,0 +1,46 @@
+/// <reference types="react" />
+/**
+ * Controller that creates an independent cache.
+ * - The cache is a `Map` instance that stores indexed items.
+ */
+export declare class CacheController<T> {
+    protected _context: import("react").Context<Map<string, T> | undefined>;
+    /** Use this cache in a component. */
+    readonly useCache: () => Map<string, T>;
+    /** Component that provides a cache of this type to its children. */
+    readonly Cache: ({ children }: {
+        children: React.ReactNode;
+    }) => React.ReactElement | null;
+}
+/**
+ * Default cache
+ * - This is a flexible generic cache intended to be the default.
+ * - Use this cache unless you want to cache a completely independent set of items without interference.
+ */
+export declare const CACHE: CacheController<any>;
+/**
+ * Use a global cache in a component.
+ * - Throws an error if used outside of `<Cache>`
+ */
+export declare const useCache: () => Map<string, any>;
+/**
+ * Component that provides a global cache to its children.
+ *
+ * Note: If mounted globally this cache will bloat over time, so you need a strategy to clear or reset the cache occasionally.
+ *
+ * A good strategy is to wrap a separate `<Cache>` around each page of your app.
+ * This means the cache can only grow to the size of each page and the memory is released when the user navigates to a new page.
+ * You might need to use `<Cache key="something unique to the page">` to ensure the cache component is destroyed and remounted for each page.
+ *
+ * Put a `<Suspense>` boundary _inside_ `<Cache>`
+ * - This prevents promises being thrown up through the cache causing it to be destroyed.
+ * - When the promise resolves and the render is tried again the data would not exist (because the cache was destroyed).
+ * - This will cause an infinite loading loop.
+ *
+ * Put your error boundary _outside_ your `<Cache>`
+ * - The error being thrown up through the cache causes it to be destroyed.
+ * - This means when the uses tells the error boundary to try again (if supported) all data on the page will be retried.
+ */
+export declare const Cache: ({ children }: {
+    children: React.ReactNode;
+}) => React.ReactElement | null;

package/react/useCache.js

@@ -0,0 +1,56 @@
+import { useContext, createContext, createElement } from "react";
+import { ConditionError } from "../error/ConditionError.js";
+import { useReduce } from "./useReduce.js";
+/**
+ * Controller that creates an independent cache.
+ * - The cache is a `Map` instance that stores indexed items.
+ */
+export class CacheController {
+    constructor() {
+        this._context = createContext(undefined);
+        /** Use this cache in a component. */
+        this.useCache = () => {
+            const cache = useContext(this._context);
+            if (!cache)
+                throw new ConditionError("useCache() must be used inside <Cache>");
+            return cache;
+        };
+        /** Component that provides a cache of this type to its children. */
+        this.Cache = ({ children }) => {
+            const cache = useReduce(_reduceMap);
+            return createElement(this._context.Provider, { children, value: cache });
+        };
+    }
+}
+/** Reducer that gets an existing `Map` instance or creates a new one. */
+const _reduceMap = (previous) => previous || new Map();
+/**
+ * Default cache
+ * - This is a flexible generic cache intended to be the default.
+ * - Use this cache unless you want to cache a completely independent set of items without interference.
+ */
+export const CACHE = new CacheController(); // eslint-disable-line @typescript-eslint/no-explicit-any
+/**
+ * Use a global cache in a component.
+ * - Throws an error if used outside of `<Cache>`
+ */
+export const useCache = CACHE.useCache;
+/**
+ * Component that provides a global cache to its children.
+ *
+ * Note: If mounted globally this cache will bloat over time, so you need a strategy to clear or reset the cache occasionally.
+ *
+ * A good strategy is to wrap a separate `<Cache>` around each page of your app.
+ * This means the cache can only grow to the size of each page and the memory is released when the user navigates to a new page.
+ * You might need to use `<Cache key="something unique to the page">` to ensure the cache component is destroyed and remounted for each page.
+ *
+ * Put a `<Suspense>` boundary _inside_ `<Cache>`
+ * - This prevents promises being thrown up through the cache causing it to be destroyed.
+ * - When the promise resolves and the render is tried again the data would not exist (because the cache was destroyed).
+ * - This will cause an infinite loading loop.
+ *
+ * Put your error boundary _outside_ your `<Cache>`
+ * - The error being thrown up through the cache causes it to be destroyed.
+ * - This means when the uses tells the error boundary to try again (if supported) all data on the page will be retried.
+ */
+export const Cache = CACHE.Cache;

package/react/useDocument.d.ts

@@ -1,19 +1,12 @@
 import type { Unsubscribe } from "../observe/Observable.js";
 import type { DocumentReference } from "../db/Reference.js";
-import type { Data, OptionalEntity } from "../util/data.js";
-import { Entity } from "../util/data.js";
+import type { Data, OptionalEntity, Entity } from "../util/data.js";
 import { State } from "../state/State.js";
-import { MemoryTable } from "../provider/MemoryProvider.js";
 import { BooleanState } from "../state/BooleanState.js";
 /** Hold the current state of a document. */
 export declare class DocumentState<T extends Data> extends State<OptionalEntity<T>> {
     readonly ref: DocumentReference<T>;
     readonly busy: BooleanState;
-    protected readonly _table: MemoryTable<T>;
-    /** Time this state was last updated with a new value. */
-    get time(): number | undefined;
-    /** How old this state's value is (in milliseconds). */
-    get age(): number;
     /** Get the data of the document (throws `RequiredError` if document doesn't exist). */
     get data(): Entity<T>;
     /** Does the document exist (i.e. its value isn't `null`)? */
@@ -25,14 +18,14 @@ export declare class DocumentState<T extends Data> extends State<OptionalEntity<
     refreshStale(maxAge: number): void;
     /** Subscribe this state to the source provider. */
     connectSource(): Unsubscribe;
+    /** Subscribe this state to any `CacheProvider` that exists in the provider chain. */
+    connectCache(): Unsubscribe | void;
     protected _addFirstObserver(): void;
     protected _removeLastObserver(): void;
 }
 /**
  * Use a document in a React component.
- * - Use `useDocument(ref).data` to get the data of the document.
- * - Use `useDocument(ref).value` to get the data of the document or `null` if it doesn't exist.
- * - Use `useDocument(ref).exists` to check if the document is loaded before accessing `.data` or `.value`
+ * - Uses the default cache, so will error if not used inside `<Cache>`
  */
 export declare function useDocument<T extends Data>(ref: DocumentReference<T>): DocumentState<T>;
 export declare function useDocument<T extends Data>(ref?: DocumentReference<T>): DocumentState<T> | undefined;

package/react/useDocument.js

@@ -1,16 +1,21 @@
-import { getDocumentData, isSameReference } from "../db/Reference.js";
+import { reduceMapItem } from "../util/map.js";
+import { getDocumentData } from "../db/Reference.js";
 import { CacheProvider } from "../provider/CacheProvider.js";
 import { findSourceProvider } from "../provider/ThroughProvider.js";
 import { State } from "../state/State.js";
-import { MatchObserver } from "../observe/MatchObserver.js";
 import { BooleanState } from "../state/BooleanState.js";
 import { ConditionError } from "../error/ConditionError.js";
-import { useReduce } from "./useReduce.js";
+import { NOVALUE } from "../util/constants.js";
 import { useSubscribe } from "./useSubscribe.js";
+import { useCache } from "./useCache.js";
 /** Hold the current state of a document. */
 export class DocumentState extends State {
     constructor(ref) {
-        super();
+        var _a;
+        const table = (_a = findSourceProvider(ref.db.provider, CacheProvider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(ref);
+        const time = table ? table.getDocumentTime(ref.id) : null;
+        const isCached = typeof time === "number";
+        super(table && isCached ? table.getDocument(ref.id) : NOVALUE);
         this.busy = new BooleanState();
         /** Refresh this state from the source provider. */
         this.refresh = async () => {
@@ -30,23 +35,11 @@ export class DocumentState extends State {
                 }
             }
         };
-        this._table = findSourceProvider(ref.db.provider, CacheProvider).memory.getTable(ref);
+        this._time = time;
         this.ref = ref;
-        // If the result is cached use it as the initial value.
-        const isCached = typeof this._table.getDocumentTime(ref.id) === "number";
-        if (isCached)
-            this.next(this._table.getDocument(ref.id)); // Use the existing cached value.
-        else
-            void this.refresh(); // Queue a request to refresh the value.
-    }
-    /** Time this state was last updated with a new value. */
-    get time() {
-        return this._table.getDocumentTime(this.ref.id);
-    }
-    /** How old this state's value is (in milliseconds). */
-    get age() {
-        const time = this.time;
-        return typeof time === "number" ? Date.now() - time : Infinity;
+        // Queue a request to refresh the value if it doesn't exist.
+        if (this.loading)
+            void this.refresh();
     }
     /** Get the data of the document (throws `RequiredError` if document doesn't exist). */
     get data() {
@@ -65,11 +58,15 @@ export class DocumentState extends State {
     connectSource() {
         return this.connect(() => this.ref.subscribe({}));
     }
+    /** Subscribe this state to any `CacheProvider` that exists in the provider chain. */
+    connectCache() {
+        var _a;
+        const table = (_a = findSourceProvider(this.ref.db.provider, CacheProvider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(this.ref);
+        table && this.connect(() => table.subscribeCachedDocument(this.ref.id, this));
+    }
     // Override to subscribe to the cache when an observer is added.
     _addFirstObserver() {
-        // Connect this state to the source.
-        // Connect through a `MatchObserver` that only dispatches `next()` if the document is actually cached (it might just be `null` because no document has been cached yet).
-        this.connect(() => this._table.subscribeDocument(this.ref.id, new MatchObserver(() => this._table.getDocumentTime(this.ref.id) !== undefined, this)));
+        this.connectCache();
     }
     // Override to unsubscribe from the cache when an observer is removed.
     _removeLastObserver() {
@@ -78,9 +75,10 @@ export class DocumentState extends State {
     }
 }
 /** Reuse the previous `DocumentState` or create a new one. */
-const _getDocumentState = (previous, ref) => !ref ? undefined : previous && isSameReference(previous.ref, ref) ? previous : new DocumentState(ref);
+const _reduceDocumentState = (existing, ref) => existing || new DocumentState(ref);
 export function useDocument(ref) {
-    const state = useReduce(_getDocumentState, ref);
+    const cache = useCache();
+    const state = ref ? reduceMapItem(cache, ref.toString(), _reduceDocumentState, ref) : undefined;
     useSubscribe(state);
     return state;
 }

package/react/useQuery.d.ts

@@ -1,20 +1,13 @@
 import type { Unsubscribe } from "../observe/Observable.js";
 import type { QueryReference } from "../db/Reference.js";
-import type { Data, Entities, OptionalEntity } from "../util/data.js";
-import { Entity } from "../util/data.js";
+import type { Data, Entities, OptionalEntity, Entity } from "../util/data.js";
 import { State } from "../state/State.js";
-import { MemoryTable } from "../provider/MemoryProvider.js";
 import { BooleanState } from "../state/BooleanState.js";
 /** Hold the current state of a query. */
 export declare class QueryState<T extends Data> extends State<Entities<T>> {
     readonly ref: QueryReference<T>;
     readonly busy: BooleanState;
     readonly limit: number;
-    protected readonly _table: MemoryTable<T>;
-    /** Time this state was last updated with a new value. */
-    get time(): number | undefined;
-    /** How old this state's value is (in milliseconds). */
-    get age(): number;
     /** Can more items be loaded after the current result. */
     get hasMore(): boolean;
     protected _hasMore: boolean;
@@ -37,6 +30,8 @@ export declare class QueryState<T extends Data> extends State<Entities<T>> {
     refreshStale(maxAge: number): void;
     /** Subscribe this state to the source provider. */
     connectSource(): Unsubscribe;
+    /** Subscribe this state to any `CacheProvider` that exists in the provider chain. */
+    connectCache(): Unsubscribe | void;
     protected _addFirstObserver(): void;
     protected _removeLastObserver(): void;
     /**
@@ -47,9 +42,7 @@ export declare class QueryState<T extends Data> extends State<Entities<T>> {
 }
 /**
  * Use a query in a React component.
- * - Use `useQuery(ref).data` to get the data of the query.
- * - Use `useQuery(ref).value` to get the data of the query or `null` if it doesn't exist.
- * - Use `useQuery(ref).exists` to check if the query is loaded before accessing `.data` or `.value`
+ * - Uses the default cache, so will error if not used inside `<Cache>`
  */
 export declare function useQuery<T extends Data>(ref: QueryReference<T>): QueryState<T>;
 export declare function useQuery<T extends Data>(ref?: QueryReference<T>): QueryState<T> | undefined;

package/react/useQuery.js

@@ -1,17 +1,21 @@
-import { getQueryFirstData, getQueryFirstValue, isSameReference } from "../db/Reference.js";
+import { reduceMapItem } from "../util/map.js";
+import { getQueryFirstData, getQueryFirstValue } from "../db/Reference.js";
 import { CacheProvider } from "../provider/CacheProvider.js";
 import { findSourceProvider } from "../provider/ThroughProvider.js";
 import { State } from "../state/State.js";
-import { MatchObserver } from "../observe/MatchObserver.js";
 import { ConditionError } from "../error/ConditionError.js";
 import { BooleanState } from "../state/BooleanState.js";
-import { useReduce } from "./useReduce.js";
+import { NOVALUE } from "../util/constants.js";
 import { useSubscribe } from "./useSubscribe.js";
+import { useCache } from "./useCache.js";
 /** Hold the current state of a query. */
 export class QueryState extends State {
     constructor(ref) {
-        var _a;
-        super();
+        var _a, _b;
+        const table = (_a = findSourceProvider(ref.db.provider, CacheProvider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(ref);
+        const time = table ? table.getQueryTime(ref) : null;
+        const isCached = typeof time === "number";
+        super(table && isCached ? table.getQuery(ref) : NOVALUE);
         this.busy = new BooleanState();
         this._hasMore = false;
         /** Refresh this state from the source provider. */
@@ -55,24 +59,12 @@ export class QueryState extends State {
                 }
             }
         };
-        this._table = findSourceProvider(ref.db.provider, CacheProvider).memory.getTable(ref);
+        this._time = time;
         this.ref = ref;
-        this.limit = (_a = ref.limit) !== null && _a !== void 0 ? _a : Infinity;
-        // If the result is cached use it as the initial value.
-        const isCached = typeof this._table.getQueryTime(ref) === "number";
-        if (isCached)
-            this.next(this._table.getQuery(ref)); // Use the existing cached value.
-        else
-            void this.refresh(); // Queue a request to refresh the value.
-    }
-    /** Time this state was last updated with a new value. */
-    get time() {
-        return this._table.getQueryTime(this.ref);
-    }
-    /** How old this state's value is (in milliseconds). */
-    get age() {
-        const time = this.time;
-        return typeof time === "number" ? Date.now() - time : Infinity;
+        this.limit = (_b = ref.limit) !== null && _b !== void 0 ? _b : Infinity;
+        // Queue a request to refresh the value if it doesn't exist.
+        if (this.loading)
+            void this.refresh();
     }
     /** Can more items be loaded after the current result. */
     get hasMore() {
@@ -111,11 +103,15 @@ export class QueryState extends State {
     connectSource() {
         return this.connect(() => this.ref.subscribe({}));
     }
+    /** Subscribe this state to any `CacheProvider` that exists in the provider chain. */
+    connectCache() {
+        var _a;
+        const table = (_a = findSourceProvider(this.ref.db.provider, CacheProvider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(this.ref);
+        return table && this.connect(() => table.subscribeCachedQuery(this.ref, this));
+    }
     // Override to subscribe to the cache when an observer is added.
     _addFirstObserver() {
-        // Connect this state to the source.
-        // Connect through a `MatchObserver` that only dispatches `next()` if the query is actually cached (it might just be `[]` because no query has been cached yet).
-        this.connect(() => this._table.subscribeQuery(this.ref, new MatchObserver(() => this._table.getQueryTime(this.ref) !== undefined, this)));
+        this.connectCache();
     }
     // Override to unsubscribe from the cache when an observer is removed.
     _removeLastObserver() {
@@ -124,9 +120,10 @@ export class QueryState extends State {
     }
 }
 /** Reuse the previous `QueryState` or create a new one. */
-const _getQueryState = (previous, ref) => !ref ? undefined : previous && isSameReference(previous.ref, ref) ? previous : new QueryState(ref);
+const _reduceQueryState = (existing, ref) => existing || new QueryState(ref);
 export function useQuery(ref) {
-    const state = useReduce(_getQueryState, ref);
+    const cache = useCache();
+    const state = ref ? reduceMapItem(cache, ref.toString(), _reduceQueryState, ref) : undefined;
     useSubscribe(state);
     return state;
 }

package/state/State.d.ts

@@ -1,4 +1,4 @@
-import { NOERROR } from "../util/constants.js";
+import { NOVALUE, NOERROR } from "../util/constants.js";
 import { Matchable } from "../util/match.js";
 import { Subject } from "../observe/Subject.js";
 import { Observer } from "../observe/Observer.js";
@@ -20,7 +20,14 @@ export declare class State<T> extends Subject<T> implements Matchable<T, void> {
     /** Most recently dispatched value (or throw `Promise` that resolves to the next value). */
     get value(): T;
     private _value;
+    /** Time this state was last updated with a new value. */
+    get time(): number | null;
+    protected _time: number | null;
+    /** How old this state's value is (in milliseconds). */
+    get age(): number;
     /** State is initiated with an initial state. */
+    constructor(initial: T | typeof NOVALUE);
+    constructor();
     constructor(...args: [] | [T]);
     /** Is there a current value, or is it still loading. */
     get loading(): boolean;

package/state/State.js

@@ -14,12 +14,12 @@ import { dispatchComplete, dispatchError, dispatchNext } from "../observe/Observ
  * - To set the state to an explicit value, use that value or another `State` instance with a value.
  * */
 export class State extends Subject {
-    /** State is initiated with an initial state. */
     constructor(...args) {
         super();
         /** Cached reason this state errored. */
         this.reason = NOERROR;
         this._value = args.length ? args[0] : NOVALUE;
+        this._time = args.length ? Date.now() : null;
     }
     /** Most recently dispatched value (or throw `Promise` that resolves to the next value). */
     get value() {
@@ -29,6 +29,15 @@ export class State extends Subject {
             throw awaitNext(this);
         return this._value;
     }
+    /** Time this state was last updated with a new value. */
+    get time() {
+        return this._time;
+    }
+    /** How old this state's value is (in milliseconds). */
+    get age() {
+        const time = this.time;
+        return time !== null ? Date.now() - time : Infinity;
+    }
     /** Is there a current value, or is it still loading. */
     get loading() {
         return this._value === NOVALUE;
@@ -59,6 +68,7 @@ export class State extends Subject {
     // Override to save value that is dispatched.
     _dispatch(value) {
         this._value = value;
+        this._time = Date.now();
         super._dispatch(value);
     }
     // Implement Matchable to see if a value matches the current value of this state.

package/util/map.d.ts

@@ -1,4 +1,5 @@
 import type { Entry } from "./entry.js";
+import type { Arguments } from "./function.js";
 /**
  * `Map` with string keys that cannot be changed.
  * - Only allows keys to be `string`
@@ -20,3 +21,5 @@ export declare type PossibleMap<T> = ImmutableMap<T> | Iterable<Entry<T>>;
 /** Convert an iterable to a `Map` (if it's already a `Map` it passes through unchanged). */
 export declare function getMap<T>(iterable: ImmutableMap<T> | Iterable<Entry<T>>): ImmutableMap<T>;
 export declare function getMap<T>(iterable: PossibleMap<T>): ImmutableMap<T>;
+/** Function that lets new items in a map be created and updated by calling a `reduce()` callback that receives the existing value. */
+export declare function reduceMapItem<K, T, A extends Arguments = []>(map: Map<K, T>, key: K, reduce: (existing: T | undefined, ...a: A) => T, ...args: A): T;

package/util/map.js

@@ -8,3 +8,11 @@ export function limitMap(map, limit) {
 export function getMap(iterable) {
     return iterable instanceof Map ? iterable : new Map(iterable);
 }
+/** Function that lets new items in a map be created and updated by calling a `reduce()` callback that receives the existing value. */
+export function reduceMapItem(map, key, reduce, ...args) {
+    const existing = map.get(key);
+    const next = reduce(existing, ...args);
+    if (existing !== next)
+        map.set(key, next);
+    return next;
+}