shelving 1.181.2 → 1.182.0

package/firestore/lite/FirestoreLiteProvider.d.ts

@@ -2,8 +2,8 @@ import type { Firestore } from "firebase/firestore/lite";
 import type { Collection } from "../../db/collection/Collection.js";
 import { DBProvider } from "../../db/provider/DBProvider.js";
 import type { Data } from "../../util/data.js";
-import type { Items, OptionalItem } from "../../util/item.js";
-import type { ItemQuery } from "../../util/query.js";
+import type { Item, Items, OptionalItem } from "../../util/item.js";
+import { type Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 /**
  * Firestore Lite client database provider.
@@ -11,19 +11,25 @@ import type { Updates } from "../../util/update.js";
  * - Does not support offline mode.
  * - Does not support realtime subscriptions.
  */
-export declare class FirestoreLiteProvider extends DBProvider<string> {
+export declare class FirestoreLiteProvider<I extends string = string, T extends Data = Data> extends DBProvider<I, T> {
     private readonly _firestore;
     constructor(firestore: Firestore);
-    getItem<T extends Data>({ name }: Collection<string, string, T>, id: string): Promise<OptionalItem<string, T>>;
-    getItemSequence<T extends Data>(_c: Collection<string, string, T>, _id: string): AsyncIterableIterator<OptionalItem<string, T>>;
-    addItem<T extends Data>({ name }: Collection<string, string, T>, data: T): Promise<string>;
-    setItem<T extends Data>({ name }: Collection<string, string, T>, id: string, data: T): Promise<void>;
-    updateItem<T extends Data>({ name }: Collection<string, string, T>, id: string, updates: Updates<T>): Promise<void>;
-    deleteItem<T extends Data>({ name }: Collection<string, string, T>, id: string): Promise<void>;
-    countQuery<T extends Data>({ name }: Collection<string, string, T>, q?: ItemQuery<string, T>): Promise<number>;
-    getQuery<T extends Data>({ name }: Collection<string, string, T>, q?: ItemQuery<string, T>): Promise<Items<string, T>>;
-    getQuerySequence<T extends Data>(_c: Collection<string, string, T>, _q?: ItemQuery<string, T>): AsyncIterableIterator<Items<string, T>>;
-    setQuery<T extends Data>({ name }: Collection<string, string, T>, q: ItemQuery<string, T>, data: T): Promise<void>;
-    updateQuery<T extends Data>({ name }: Collection<string, string, T>, q: ItemQuery<string, T>, updates: Updates<T>): Promise<void>;
-    deleteQuery<T extends Data>({ name }: Collection<string, string, T>, q: ItemQuery<string, T>): Promise<void>;
+    /** Get a Firestore CollectionReference for a given collection. */
+    private _collection;
+    /** Get a Firestore DocumentReference for a given document. */
+    private _doc;
+    /** Get a Firestore QueryReference for a given query. */
+    private _query;
+    getItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    getItemSequence<II extends I, TT extends T>(_c: Collection<string, II, TT>, _id: II): AsyncIterable<OptionalItem<II, TT>>;
+    addItem<II extends I, TT extends T>(c: Collection<string, II, TT>, data: TT): Promise<II>;
+    setItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    updateItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    deleteItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): Promise<void>;
+    countQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): Promise<number>;
+    getQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    getQuerySequence<II extends I, TT extends T>(_c: Collection<string, II, TT>, _q?: Query<Item<II, TT>>): AsyncIterable<Items<II, TT>>;
+    setQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>, data: TT): Promise<void>;
+    updateQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    deleteQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>): Promise<void>;
 }

package/firestore/lite/FirestoreLiteProvider.js

@@ -21,10 +21,6 @@ const OPERATORS = {
     lt: "<",
     lte: "<=",
 };
-/** Create a corresponding `QueryReference` from a Query. */
-function _getQuery(firestore, c, q) {
-    return q ? query(collection(firestore, c), ..._getConstraints(q)) : collection(firestore, c);
-}
 function* _getConstraints(q) {
     for (const { key, direction } of getQueryOrders(q)) {
         const k = joinDataKey(key);
@@ -38,14 +34,16 @@ function* _getConstraints(q) {
     if (typeof l === "number")
         yield limit(l);
 }
+function _getItems(snapshot) {
+    return snapshot.docs.map(s => _getItem(s));
+}
 function _getItem(snapshot) {
-    const data = snapshot.data();
-    return getItem(snapshot.id, data);
+    return getItem(snapshot.id, snapshot.data()); // `as II` needed: Firestore snapshot.id is always string, not II.
 }
 function _getOptionalItem(snapshot) {
     const data = snapshot.data();
     if (data)
-        return getItem(snapshot.id, data);
+        return getItem(snapshot.id, data); // `as II` needed: Firestore snapshot.id is always string, not II.
 }
 /** Convert `Updates` object into corresponding Firestore `FieldValue` instances. */
 function _getFieldValues(updates) {
@@ -75,48 +73,59 @@ export class FirestoreLiteProvider extends DBProvider {
         super();
         this._firestore = firestore;
     }
-    async getItem({ name }, id) {
-        const snapshot = await getDoc(doc(this._firestore, name, id));
+    /** Get a Firestore CollectionReference for a given collection. */
+    _collection({ name }) {
+        return collection(this._firestore, name);
+    }
+    /** Get a Firestore DocumentReference for a given document. */
+    _doc(c, id) {
+        return doc(this._collection(c), id);
+    }
+    /** Get a Firestore QueryReference for a given query. */
+    _query(c, q) {
+        return q ? query(this._collection(c), ..._getConstraints(q)) : this._collection(c);
+    }
+    async getItem(c, id) {
+        const snapshot = await getDoc(this._doc(c, id));
         return _getOptionalItem(snapshot);
     }
     getItemSequence(_c, _id) {
         throw new UnimplementedError("FirestoreLiteProvider does not support realtime subscriptions");
     }
-    async addItem({ name }, data) {
-        const reference = await addDoc(collection(this._firestore, name), data);
-        return reference.id;
+    async addItem(c, data) {
+        const reference = await addDoc(this._collection(c), data);
+        return reference.id; // `as II` needed: Firestore returns string, not II.
     }
-    async setItem({ name }, id, data) {
-        await setDoc(doc(this._firestore, name, id), data);
+    async setItem(c, id, data) {
+        await setDoc(this._doc(c, id), data);
     }
-    async updateItem({ name }, id, updates) {
-        await updateDoc(doc(this._firestore, name, id), _getFieldValues(updates));
+    async updateItem(c, id, updates) {
+        await updateDoc(this._doc(c, id), _getFieldValues(updates));
     }
-    async deleteItem({ name }, id) {
-        await deleteDoc(doc(this._firestore, name, id));
+    async deleteItem(c, id) {
+        await deleteDoc(this._doc(c, id));
     }
-    async countQuery({ name }, q) {
-        const snapshot = await getCount(_getQuery(this._firestore, name, q));
+    async countQuery(c, q) {
+        const snapshot = await getCount(this._query(c, q));
         return snapshot.data().count;
     }
-    async getQuery({ name }, q) {
-        const snapshot = await getDocs(_getQuery(this._firestore, name, q));
-        return snapshot.docs.map(_getItem);
+    async getQuery(c, q) {
+        return _getItems(await getDocs(this._query(c, q)));
     }
     getQuerySequence(_c, _q) {
         throw new UnimplementedError("FirestoreLiteProvider does not support realtime subscriptions");
     }
-    async setQuery({ name }, q, data) {
-        const snapshot = await getDocs(_getQuery(this._firestore, name, q));
+    async setQuery(c, q, data) {
+        const snapshot = await getDocs(this._query(c, q));
         await Promise.all(snapshot.docs.map(s => setDoc(s.ref, data)));
     }
-    async updateQuery({ name }, q, updates) {
-        const snapshot = await getDocs(_getQuery(this._firestore, name, q));
+    async updateQuery(c, q, updates) {
+        const snapshot = await getDocs(this._query(c, q));
         const fieldValues = _getFieldValues(updates);
         await Promise.all(snapshot.docs.map(s => updateDoc(s.ref, fieldValues)));
     }
-    async deleteQuery({ name }, q) {
-        const snapshot = await getDocs(_getQuery(this._firestore, name, q));
+    async deleteQuery(c, q) {
+        const snapshot = await getDocs(this._query(c, q));
         await Promise.all(snapshot.docs.map(s => deleteDoc(s.ref)));
     }
 }

package/firestore/server/FirestoreServerProvider.d.ts

@@ -2,26 +2,32 @@ import { Firestore } from "@google-cloud/firestore";
 import type { Collection } from "../../db/collection/Collection.js";
 import { DBProvider } from "../../db/provider/DBProvider.js";
 import type { Data } from "../../util/data.js";
-import type { Items, OptionalItem } from "../../util/item.js";
-import type { ItemQuery } from "../../util/query.js";
+import type { Item, Items, OptionalItem } from "../../util/item.js";
+import { type Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 /**
  * Firestore server database provider.
  * - Works with the Firebase Admin SDK for Node.JS
  */
-export declare class FirestoreServerProvider extends DBProvider<string> {
+export declare class FirestoreServerProvider<I extends string = string, T extends Data = Data> extends DBProvider<I, T> {
     private readonly _firestore;
     constructor(firestore?: Firestore);
-    getItem<T extends Data>({ name }: Collection<string, string, T>, id: string): Promise<OptionalItem<string, T>>;
-    getItemSequence<T extends Data>({ name }: Collection<string, string, T>, id: string): AsyncIterable<OptionalItem<string, T>>;
-    addItem<T extends Data>({ name }: Collection<string, string, T>, data: T): Promise<string>;
-    setItem<T extends Data>({ name }: Collection<string, string, T>, id: string, data: T): Promise<void>;
-    updateItem<T extends Data>({ name }: Collection<string, string, T>, id: string, updates: Updates<T>): Promise<void>;
-    deleteItem<T extends Data>({ name }: Collection<string, string, T>, id: string): Promise<void>;
-    countQuery<T extends Data>({ name }: Collection<string, string, T>, q?: ItemQuery<string, T>): Promise<number>;
-    getQuery<T extends Data>({ name }: Collection<string, string, T>, q?: ItemQuery<string, T>): Promise<Items<string, T>>;
-    getQuerySequence<T extends Data>({ name }: Collection<string, string, T>, q?: ItemQuery<string, T>): AsyncIterable<Items<string, T>>;
-    setQuery<T extends Data>({ name }: Collection<string, string, T>, q: ItemQuery<string, T>, data: T): Promise<void>;
-    updateQuery<T extends Data>({ name }: Collection<string, string, T>, q: ItemQuery<string, T>, updates: Updates<T>): Promise<void>;
-    deleteQuery<T extends Data>({ name }: Collection<string, string, T>, q: ItemQuery<string, T>): Promise<void>;
+    /** Create a corresponding `FirestoreCollection` reference from a collection. */
+    private _getCollection;
+    /** Create a corresponding `FirestoreQuery` reference from a collection and query. */
+    private _getQuery;
+    /** Perform a bulk update on a set of documents using a `BulkWriter` */
+    private _bulkWrite;
+    getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    getItemSequence<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): AsyncIterable<OptionalItem<II, TT>>;
+    addItem<II extends I, TT extends T>(c: Collection<string, II, TT>, data: TT): Promise<II>;
+    setItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    updateItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    deleteItem<II extends I, TT extends T>(c: Collection<string, II, TT>, id: II): Promise<void>;
+    countQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): Promise<number>;
+    getQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    getQuerySequence<II extends I, TT extends T>(c: Collection<string, II, TT>, q?: Query<Item<II, TT>>): AsyncIterable<Items<II, TT>>;
+    setQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>, data: TT): Promise<void>;
+    updateQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    deleteQuery<II extends I, TT extends T>(c: Collection<string, II, TT>, q: Query<Item<II, TT>>): Promise<void>;
 }

package/firestore/server/FirestoreServerProvider.js

@@ -9,6 +9,7 @@ import { mapItems } from "../../util/transform.js";
 import { getUpdates } from "../../util/update.js";
 // Constants.
 const ID = FieldPath.documentId();
+const BATCH_SIZE = 1000;
 // Map `Filter.types` to `WhereFilterOp`
 const OPERATORS = {
     is: "==",
@@ -21,38 +22,16 @@ const OPERATORS = {
     lt: "<",
     lte: "<=",
 };
-function _getCollection(firestore, c) {
-    return firestore.collection(c);
-}
-/** Create a corresponding `QueryReference` from a Query. */
-function _getQuery(firestore, c, q) {
-    let ref = _getCollection(firestore, c);
-    if (q) {
-        for (const { key, direction } of getQueryOrders(q)) {
-            const k = joinDataKey(key);
-            ref = ref.orderBy(k === "id" ? ID : k, direction);
-        }
-        for (const { key, operator, value } of getQueryFilters(q)) {
-            const k = joinDataKey(key);
-            ref = ref.where(k === "id" ? ID : k, OPERATORS[operator], value);
-        }
-        const l = getQueryLimit(q);
-        if (typeof l === "number")
-            ref = ref.limit(l);
-    }
-    return ref;
-}
-function _getItemArray(snapshot) {
-    return snapshot.docs.map(_getItem);
+function _getItems(snapshot) {
+    return snapshot.docs.map(s => _getItem(s));
 }
 function _getItem(snapshot) {
-    const data = snapshot.data();
-    return getItem(snapshot.id, data);
+    return getItem(snapshot.id, snapshot.data()); // `as II` needed: Firestore snapshot.id is always string, not II.
 }
 function _getOptionalItem(snapshot) {
     const data = snapshot.data();
     if (data)
-        return getItem(snapshot.id, data);
+        return getItem(snapshot.id, data); // `as II` needed: Firestore snapshot.id is always string, not II.
 }
 /** Convert `Update` instances into corresponding Firestore `FieldValue` instances. */
 function _getFieldValues(updates) {
@@ -80,63 +59,80 @@ export class FirestoreServerProvider extends DBProvider {
         super();
         this._firestore = firestore;
     }
-    async getItem({ name }, id) {
-        return _getOptionalItem(await _getCollection(this._firestore, name).doc(id).get());
+    /** Create a corresponding `FirestoreCollection` reference from a collection. */
+    _getCollection(collection) {
+        return this._firestore.collection(collection.name);
     }
-    getItemSequence({ name }, id) {
-        const ref = _getCollection(this._firestore, name).doc(id);
-        return new LazyDeferredSequence(sequence => ref.onSnapshot(snapshot => sequence.resolve(_getOptionalItem(snapshot)), //
-        //
-        reason => sequence.reject(reason)));
+    /** Create a corresponding `FirestoreQuery` reference from a collection and query. */
+    _getQuery(c, q) {
+        let ref = this._getCollection(c);
+        if (q) {
+            for (const { key, direction } of getQueryOrders(q)) {
+                const k = joinDataKey(key);
+                ref = ref.orderBy(k === "id" ? ID : k, direction);
+            }
+            for (const { key, operator, value } of getQueryFilters(q)) {
+                const k = joinDataKey(key);
+                ref = ref.where(k === "id" ? ID : k, OPERATORS[operator], value);
+            }
+            const l = getQueryLimit(q);
+            if (typeof l === "number")
+                ref = ref.limit(l);
+        }
+        return ref;
+    }
+    /** Perform a bulk update on a set of documents using a `BulkWriter` */
+    async _bulkWrite(c, q, callback) {
+        const writer = this._firestore.bulkWriter();
+        const ref = this._getQuery(c, q).limit(BATCH_SIZE).select(); // `select()` turns the query into a field mask query (with no field masks) which saves data transfer and memory.
+        let current = ref;
+        while (current) {
+            const { docs, size } = await current.get();
+            for (const s of docs)
+                callback(writer, s);
+            current = size >= BATCH_SIZE && ref.startAfter(docs.pop()).select();
+            void writer.flush();
+        }
+        await writer.close();
+    }
+    async getItem(collection, id) {
+        return _getOptionalItem(await this._getCollection(collection).doc(id).get());
     }
-    async addItem({ name }, data) {
-        return (await _getCollection(this._firestore, name).add(data)).id;
+    getItemSequence(c, id) {
+        const ref = this._getCollection(c).doc(id);
+        return new LazyDeferredSequence(sequence => ref.onSnapshot(snapshot => sequence.resolve(_getOptionalItem(snapshot)), reason => sequence.reject(reason)));
     }
-    async setItem({ name }, id, data) {
-        await _getCollection(this._firestore, name).doc(id).set(data);
+    async addItem(c, data) {
+        return (await this._getCollection(c).add(data)).id; // `as II` needed: Firestore returns string, not II.
     }
-    async updateItem({ name }, id, updates) {
-        await _getCollection(this._firestore, name).doc(id).update(_getFieldValues(updates));
+    async setItem(c, id, data) {
+        await this._getCollection(c).doc(id).set(data);
     }
-    async deleteItem({ name }, id) {
-        await _getCollection(this._firestore, name).doc(id).delete();
+    async updateItem(c, id, updates) {
+        await this._getCollection(c).doc(id).update(_getFieldValues(updates));
     }
-    async countQuery({ name }, q) {
-        const snapshot = await _getQuery(this._firestore, name, q).count().get();
+    async deleteItem(c, id) {
+        await this._getCollection(c).doc(id).delete();
+    }
+    async countQuery(c, q) {
+        const snapshot = await this._getQuery(c, q).count().get();
         return snapshot.data().count;
     }
-    async getQuery({ name }, q) {
-        return _getItemArray(await _getQuery(this._firestore, name, q).get());
+    async getQuery(c, q) {
+        return _getItems(await this._getQuery(c, q).get());
     }
-    getQuerySequence({ name }, q) {
-        const ref = _getQuery(this._firestore, name, q);
-        return new LazyDeferredSequence(sequence => ref.onSnapshot(snapshot => sequence.resolve(_getItemArray(snapshot)), //
-        //
-        reason => sequence.reject(reason)));
+    getQuerySequence(c, q) {
+        const ref = this._getQuery(c, q);
+        return new LazyDeferredSequence(sequence => ref.onSnapshot(snapshot => sequence.resolve(_getItems(snapshot)), reason => sequence.reject(reason)));
     }
-    async setQuery({ name }, q, data) {
-        return await bulkWrite(this._firestore, name, q, (w, s) => void w.set(s.ref, data));
+    async setQuery(c, q, data) {
+        return await this._bulkWrite(c, q, (w, s) => void w.set(s.ref, data));
     }
-    async updateQuery({ name }, q, updates) {
+    async updateQuery(c, q, updates) {
         const fieldValues = _getFieldValues(updates);
-        return await bulkWrite(this._firestore, name, q, (w, s) => void w.update(s.ref, fieldValues));
+        return await this._bulkWrite(c, q, (w, s) => void w.update(s.ref, fieldValues));
     }
-    async deleteQuery({ name }, q) {
-        return await bulkWrite(this._firestore, name, q, (w, s) => void w.delete(s.ref));
+    async deleteQuery(c, q) {
+        return await this._bulkWrite(c, q, (w, s) => void w.delete(s.ref));
     }
 }
-/** Perform a bulk update on a set of documents using a `BulkWriter` */
-async function bulkWrite(firestore, c, q, callback) {
-    const writer = firestore.bulkWriter();
-    const ref = _getQuery(firestore, c, q).limit(BATCH_SIZE).select(); // `select()` turns the query into a field mask query (with no field masks) which saves data transfer and memory.
-    let current = ref;
-    while (current) {
-        const { docs, size } = await current.get();
-        for (const s of docs)
-            callback(writer, s);
-        current = size >= BATCH_SIZE && ref.startAfter(docs.pop()).select();
-        void writer.flush();
-    }
-    await writer.close();
-}
-const BATCH_SIZE = 1000;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.181.2",
+	"version": "1.182.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/react/createAPIContext.d.ts

@@ -1,7 +1,7 @@
-import type { ReactElement, ReactNode } from "react";
+import { type ReactElement, type ReactNode } from "react";
 import type { Endpoint } from "../api/endpoint/Endpoint.js";
 import type { APIProvider } from "../api/provider/APIProvider.js";
-import { EndpointStore } from "../api/store/EndpointStore.js";
+import type { EndpointStore } from "../api/store/EndpointStore.js";
 import type { Nullish } from "../util/null.js";
 export interface APIContext {
     /** Get an `EndpointStore` for the specified endpoint/payload in the current `APIProvider` context. */
@@ -15,5 +15,7 @@ export interface APIContext {
  * Create an API context.
  * - Allows React elements to call `useAPI()` to access endpoint stores in an API provider.
  * - Each mounted `APIContext` gets its own in-memory store cache.
+ *
+ * @todo Use and integreate our `EndpointCache` functionality and use it in this.
  */
 export declare function createAPIContext(provider: APIProvider): APIContext;

package/react/createAPIContext.js

@@ -1,25 +1,32 @@
-import { EndpointStore } from "../api/store/EndpointStore.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use } from "react";
+import { APICache } from "../api/index.js";
+import { RequiredError } from "../error/RequiredError.js";
 import { MINUTE } from "../util/constants.js";
-import { setMapItem } from "../util/map.js";
-import { createCacheContext } from "./createCacheContext.js";
+import { useInstance } from "./useInstance.js";
 import { useStore } from "./useStore.js";
 const DEFAULT_MAX_AGE = 5 * MINUTE;
 /**
  * Create an API context.
  * - Allows React elements to call `useAPI()` to access endpoint stores in an API provider.
  * - Each mounted `APIContext` gets its own in-memory store cache.
+ *
+ * @todo Use and integreate our `EndpointCache` functionality and use it in this.
  */
 export function createAPIContext(provider) {
-    const { CacheContext, useCache } = createCacheContext();
-    return {
-        useAPI: (endpoint, payload, maxAge = DEFAULT_MAX_AGE) => {
-            const cache = useCache();
-            const key = endpoint && `${endpoint.toString()}?${JSON.stringify(payload)}`;
-            const store = useStore(key && endpoint ? cache.get(key) || setMapItem(cache, key, new EndpointStore(endpoint, payload, provider)) : undefined);
-            if (store)
-                store.refreshStale(maxAge);
-            return store;
-        },
-        APIContext: CacheContext,
-    };
+    const CacheContext = createContext(undefined);
+    function useAPI(endpoint, payload, maxAge = DEFAULT_MAX_AGE) {
+        const cache = use(CacheContext);
+        if (!cache)
+            throw new RequiredError(`useAPI() can only be used inside <APIContext>`, { caller: useAPI });
+        const store = endpoint ? cache.get(endpoint).get(payload) : undefined;
+        if (store)
+            store.refreshStale(maxAge);
+        return useStore(store);
+    }
+    function APIContext({ children }) {
+        const cache = useInstance(APICache, provider);
+        return _jsx(CacheContext, { value: cache, children: children });
+    }
+    return { useAPI, APIContext };
 }

package/react/createDBContext.d.ts

@@ -0,0 +1,31 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { Collection } from "../db/collection/Collection.js";
+import type { DBProvider } from "../db/provider/DBProvider.js";
+import type { ItemStore } from "../db/store/ItemStore.js";
+import type { QueryStore } from "../db/store/QueryStore.js";
+import type { Data } from "../util/data.js";
+import type { Identifier, Item } from "../util/item.js";
+import type { Nullish } from "../util/null.js";
+import type { Query } from "../util/query.js";
+export interface DBContext<I extends Identifier, T extends Data> {
+    /** Get an `ItemStore` for the specified collection item in the current `DataProvider` context and subscribe to any changes in it. */
+    useItem<II extends I, TT extends T>(collection: Nullish<Collection<string, II, TT>>, //
+    id: Nullish<II>): ItemStore<II, TT> | undefined;
+    useItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, //
+    id: II): ItemStore<II, TT>;
+    /** Get an `QueryStore` for the specified collection query in the current `DataProvider` context and subscribe to any changes in it. */
+    useQuery<II extends I, TT extends T>(collection: Nullish<Collection<string, II, TT>>, //
+    query: Nullish<Query<Item<II, TT>>>): QueryStore<II, TT> | undefined;
+    useQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, //
+    query: Query<Item<II, TT>>): QueryStore<II, TT>;
+    /** The `<DataContext>` wrapper to give your React components access to this data. */
+    readonly DBContext: ({ children }: {
+        children: ReactNode;
+    }) => ReactElement;
+}
+/**
+ * Create a data context
+ * - Allows React elements to call `useItem()` and `useQuery()` to access items/queries in a database provider.
+ * - If the database has a `CacheDBProvider` in its chain then in-memory data will be used in the returned stores.
+ */
+export declare function createDBContext<I extends Identifier, T extends Data>(provider: DBProvider<I, T>): DBContext<I, T>;

package/react/createDBContext.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use } from "react";
+import { DBCache } from "../db/cache/DBCache.js";
+import { RequiredError } from "../error/RequiredError.js";
+import { useInstance } from "./useInstance.js";
+import { useStore } from "./useStore.js";
+/**
+ * Create a data context
+ * - Allows React elements to call `useItem()` and `useQuery()` to access items/queries in a database provider.
+ * - If the database has a `CacheDBProvider` in its chain then in-memory data will be used in the returned stores.
+ */
+export function createDBContext(provider) {
+    const CacheContext = createContext(undefined);
+    function useItem(collection, //
+    id) {
+        const cache = use(CacheContext);
+        if (!cache)
+            throw new RequiredError("useItem() can only be used inside <DBContext>", { caller: useItem });
+        const store = collection && id ? cache.getItem(collection, id) : undefined;
+        return useStore(store);
+    }
+    function useQuery(collection, //
+    query) {
+        const cache = use(CacheContext);
+        if (!cache)
+            throw new RequiredError("useQuery() can only be used inside <DBContext>", { caller: useQuery });
+        const store = collection && query ? cache.getQuery(collection, query) : undefined;
+        return useStore(store);
+    }
+    function DBContext({ children }) {
+        const cache = useInstance(DBCache, provider);
+        return _jsx(CacheContext, { value: cache, children: children });
+    }
+    return { useItem, useQuery, DBContext };
+}

package/react/index.d.ts

@@ -1,6 +1,5 @@
 export * from "./createAPIContext.js";
-export * from "./createCacheContext.js";
-export * from "./createDataContext.js";
+export * from "./createDBContext.js";
 export * from "./useInstance.js";
 export * from "./useLazy.js";
 export * from "./useMap.js";

package/react/index.js

@@ -1,6 +1,5 @@
 export * from "./createAPIContext.js";
-export * from "./createCacheContext.js";
-export * from "./createDataContext.js";
+export * from "./createDBContext.js";
 export * from "./useInstance.js";
 export * from "./useLazy.js";
 export * from "./useMap.js";

package/util/http.d.ts

@@ -3,6 +3,7 @@ import { ResponseError } from "../error/ResponseError.js";
 import { type Data } from "./data.js";
 import type { ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller, Arguments } from "./function.js";
+import { type Nullish } from "./null.js";
 import { type PossibleURL } from "./url.js";
 /** A handler function takes a `Request` and optional extra arguments and returns a `Response` (possibly asynchronously). */
 export type RequestHandler<A extends Arguments = []> = (request: Request, ...args: A) => Response | Promise<Response>;
@@ -95,5 +96,5 @@ export declare function mergeRequestOptions({ headers: aHeaders, ...a }?: Reques
  * @throws {RequiredError} if this is a `HEAD` or `GET` request but `body` is not a data object.
  */
 export declare function getRequest(method: RequestMethod, url: PossibleURL, payload: unknown, options?: RequestOptions, caller?: AnyCaller): Request;
-/** Assert that the payload for a HEAD or GET method is a data object. */
-export declare function assertHeadMethodPayload(payload: unknown, method: RequestHeadMethod, caller?: AnyCaller): asserts payload is Data;
+/** Assert that the payload for a HEAD or GET method is a data object, null, or undefined. */
+export declare function assertHeadMethodPayload(payload: unknown, method: RequestHeadMethod, caller?: AnyCaller): asserts payload is Nullish<Data>;

package/util/http.js

@@ -155,14 +155,14 @@ export function mergeRequestOptions({ headers: aHeaders, ...a } = {}, { headers:
  */
 export function getRequest(method, url, payload, options = {}, caller = getRequest) {
     url = requireURL(url, undefined, caller);
+    // `null` or `undefined` payloads send no body.
+    if (isNullish(payload))
+        return new Request(url, { ...options, method, body: null });
     // HEAD or GET have no body (but payload can only be data object).
     if (isArrayItem(HTTP_HEAD_METHODS, method)) {
         assertHeadMethodPayload(payload, method, caller);
         return new Request(withURIParams(url, payload), { ...options, method, body: null });
     }
-    // `null` or `undefined` payloads send no body.
-    if (isNullish(payload))
-        return new Request(url, { ...options, method, body: null });
     // `FormData` instances in body pass through unaltered and will set their own `Content-Type` with complex boundary information
     if (payload instanceof FormData)
         return new Request(url, { ...options, method, body: payload });
@@ -172,8 +172,8 @@ export function getRequest(method, url, payload, options = {}, caller = getReque
     // JSON is the default.
     return new Request(url, { ...mergeRequestOptions(REQUEST_JSON_OPTIONS, options), method, body: JSON.stringify(payload) });
 }
-/** Assert that the payload for a HEAD or GET method is a data object. */
+/** Assert that the payload for a HEAD or GET method is a data object, null, or undefined. */
 export function assertHeadMethodPayload(payload, method, caller = assertHeadMethodPayload) {
-    if (!isData(payload))
-        throw new RequiredError(`Payload for ${method} request must be data object`, { received: payload, caller });
+    if (!isData(payload) && !isNullish(payload))
+        throw new RequiredError(`Payload for ${method} request must be data object, null, or undefined`, { received: payload, caller });
 }

package/util/item.d.ts

@@ -3,11 +3,13 @@ import type { Data } from "./data.js";
 /** Allowed types for the "id" property (identifier) for an item. */
 export type Identifier = string | number;
 /** An item object is a data object that includes an "id" identifier property that is either a string or number. */
-export type Item<I extends Identifier, T extends Data> = {
+export type Item<I extends Identifier = Identifier, T extends Data = Data> = {
     id: I;
 } & T;
 /** Entity or `undefined` to indicate the item doesn't exist. */
-export type OptionalItem<I extends Identifier, T extends Data> = Item<I, T> | undefined;
+export type OptionalItem<I extends Identifier = Identifier, T extends Data = Data> = Item<I, T> | undefined;
+/** An array of item data. */
+export type Items<I extends Identifier = Identifier, T extends Data = Data> = ImmutableArray<Item<I, T>>;
 /** Get the identifier from an item object. */
 export declare function getIdentifier<I extends Identifier, T extends Data>({ id }: Item<I, T>): I;
 /** Get the identifiers from an iterable set item objects. */
@@ -16,5 +18,3 @@ export declare function getIdentifiers<I extends Identifier, T extends Data>(ent
 export declare function hasIdentifier<I extends Identifier, T extends Data>(item: T | Item<I, T>, id: I): item is Item<I, T>;
 /** Merge an ID into a set of data to make an `ItemData` */
 export declare function getItem<I extends Identifier, T extends Data>(id: I, data: T | Item<I, T>): Item<I, T>;
-/** An array of item data. */
-export type Items<I extends Identifier, T extends Data> = ImmutableArray<Item<I, T>>;