shelving 1.179.0 → 1.179.2

package/api/endpoint/util.d.ts

@@ -3,8 +3,13 @@ import { type PossibleURL } from "../../util/url.js";
 import type { Endpoint } from "./Endpoint.js";
 /**
  * A function that handles an endpoint request, with a payload and returns a result.
- * - `payload` has already been validated against the endpoint payload schema before the callback is invoked.
- * - `request` is always the original incoming request object.
+ *
+ * @param payload The payload for the callback combining the `{placeholders}`, `?search` params, and body content (this has been validated against the Endpoint's payload schema).
+ * @param request The original incoming request object.
+ * @param args Any additional arguments to pass into the endpoint callback
+ *
+ * @returns {Response} Returning a `Response` object (this will pass back to the client without validation).
+ * @returns {R} Returning the return type of the handler (this will be validated against the Endpoint's result schema).
  */
 export type EndpointCallback<P, R, A extends Arguments = []> = (payload: P, request: Request, ...args: A) => R | Response | Promise<R | Response>;
 /** A typed endpoint definition paired with its implementation callback. */
@@ -12,6 +17,7 @@ export interface EndpointHandler<P = unknown, R = unknown, A extends Arguments =
     readonly endpoint: Endpoint<P, R>;
     readonly callback: EndpointCallback<P, R, A>;
 }
+/** Any endpoint handler. */
 export type AnyEndpointHandler<A extends Arguments = []> = EndpointHandler<any, any, A>;
 /** A collection of endpoint handlers that can be matched and invoked by `handleEndpoints()`. */
 export type EndpointHandlers<A extends Arguments = []> = Iterable<AnyEndpointHandler<A>>;
@@ -19,6 +25,10 @@ export type EndpointHandlers<A extends Arguments = []> = Iterable<AnyEndpointHan
  * Handle a `Request` with the first matching endpoint handler after stripping any base-path prefix from the request pathname.
  * - The original `Request` object is passed through to the callback unchanged.
  * - Path params and query params are merged before payload validation.
- * @param base The base URL for the API, e.g. `https://myapi.com/`
+ *
+ * @param request The input request to handle.
+ *
+ * @param base The base URL for the API, e.g. `https://myapi.com/a/b`
+ * - `pathname` of this URL gets trimmed from `request.path` to form the target path when matching against endpoints, e.g. `/a/b/c/d` will produce `/c/d` for matching.
  */
 export declare function handleEndpoints<A extends Arguments = []>(request: Request, base: PossibleURL, handlers: EndpointHandlers<A>, ...args: A): Promise<Response>;

package/api/endpoint/util.js

@@ -8,7 +8,11 @@ import { requireURL } from "../../util/url.js";
  * Handle a `Request` with the first matching endpoint handler after stripping any base-path prefix from the request pathname.
  * - The original `Request` object is passed through to the callback unchanged.
  * - Path params and query params are merged before payload validation.
- * @param base The base URL for the API, e.g. `https://myapi.com/`
+ *
+ * @param request The input request to handle.
+ *
+ * @param base The base URL for the API, e.g. `https://myapi.com/a/b`
+ * - `pathname` of this URL gets trimmed from `request.path` to form the target path when matching against endpoints, e.g. `/a/b/c/d` will produce `/c/d` for matching.
  */
 export function handleEndpoints(request, base, handlers, ...args) {
     const caller = handleEndpoints;
@@ -18,27 +22,31 @@ export function handleEndpoints(request, base, handlers, ...args) {
     const { origin: baseOrigin, pathname: basePath } = requireURL(base, undefined, caller);
     const { origin: requestOrigin, pathname: requestPath, searchParams } = requireURL(url, base, caller);
     if (baseOrigin !== requestOrigin)
-        throw new NotFoundError("No matching origin", { expected: baseOrigin, received: requestOrigin, caller });
-    const targetPath = _stripPathPrefix(requestPath, basePath, caller);
+        throw new NotFoundError("No matching base origin", { expected: baseOrigin, received: requestOrigin, caller });
+    const targetPath = _stripPathPrefix(requestPath, basePath);
+    if (!targetPath)
+        throw new NotFoundError("No matching base path", { received: requestPath, expected: basePath, caller });
     for (const handler of handlers) {
         const pathParams = handler.endpoint.match(method, targetPath, caller);
         if (!pathParams)
             continue;
         const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
-        return handleEndpoint(handler, params, request, args, handleEndpoints);
+        return _handleEndpoint(handler, params, request, args, handleEndpoints);
     }
     throw new NotFoundError("No matching endpoint", { received: targetPath, caller });
 }
 /**
  * Validate and invoke an endpoint callback after the routing layer has already matched URL params.
  */
-async function handleEndpoint({ endpoint, callback }, 
+async function _handleEndpoint({ endpoint, callback }, 
 /** Params we already matched/parsed from the URL. */
-params, request, args, caller = handleEndpoint) {
+params, request, args, caller = _handleEndpoint) {
     const content = await getRequestContent(request, caller);
     const unsafePayload = content === undefined ? params : isPlainObject(content) ? { ...content, ...params } : content;
     const payload = endpoint.payload.validate(unsafePayload);
     const unsafeResult = await callback(payload, request, ...args);
+    if (unsafeResult instanceof Response)
+        return unsafeResult;
     try {
         return getResponse(endpoint.result.validate(unsafeResult));
     }
@@ -49,7 +57,7 @@ params, request, args, caller = handleEndpoint) {
     }
 }
 /** Strip a prefix like `/a/b` from a path like `/a/b/c/d` to produce a remainder path like `/c/d`. */
-function _stripPathPrefix(path, prefix, caller) {
+function _stripPathPrefix(path, prefix) {
     prefix = prefix === "/" ? "/" : prefix.replace(/\/$/, "");
     if (prefix === "/")
         return path;
@@ -57,5 +65,4 @@ function _stripPathPrefix(path, prefix, caller) {
         return "/";
     if (path.startsWith(`${prefix}/`))
         return path.slice(prefix.length);
-    throw new NotFoundError("No matching endpoint", { received: path, expected: prefix, caller });
 }

package/api/provider/MockAPIProvider.d.ts

@@ -12,19 +12,14 @@ export type MockAPICall = {
     readonly response: Response;
     readonly result: unknown;
 };
-/**
- * Construction options for a `MockAPIProvider`.
- * - Accepts the normal `APIProvider` options.
- */
+/** Construction options for a `MockAPIProvider`. */
 export interface MockAPIProviderOptions extends ClientAPIProviderOptions {
-    /** Implement this handler to mock the the request/response input/output. */
-    readonly handler: RequestHandler;
 }
 /** Provider that logs API calls without sending network requests. */
 export declare class MockAPIProvider extends ClientAPIProvider {
     readonly calls: MockAPICall[];
     readonly handler: RequestHandler;
-    constructor({ handler, ...options }: MockAPIProviderOptions);
+    constructor(handler: RequestHandler, options?: MockAPIProviderOptions);
     /**
      * Log a `fetch()` call without using the network.
      * - If `getResult` is configured, its return value is returned as-is (no schema validation).

package/api/provider/MockAPIProvider.js

@@ -4,7 +4,7 @@ import { ClientAPIProvider } from "./ClientAPIProvider.js";
 export class MockAPIProvider extends ClientAPIProvider {
     calls = [];
     handler;
-    constructor({ handler, ...options }) {
+    constructor(handler, options = { url: "https://api.mock.com" }) {
         super(options);
         this.handler = handler;
     }

package/cloudflare/CloudflareKVProvider.d.ts

@@ -11,17 +11,6 @@ export interface KVNamespace {
     }): Promise<unknown>;
     put(key: string, value: string): Promise<void>;
     delete(key: string): Promise<void>;
-    list(options?: {
-        prefix?: string;
-        limit?: number;
-        cursor?: string;
-    }): Promise<{
-        keys: readonly {
-            name: string;
-        }[];
-        list_complete: boolean;
-        cursor?: string;
-    }>;
 }
 /**
  * Cloudflare Workers KV database provider.
@@ -31,26 +20,21 @@ export interface KVNamespace {
  *
  * ### Supported
  * - Single item operations: `getItem`, `setItem`, `addItem`, `updateItem`, `deleteItem`.
- * - Query operations: `getQuery`, `setQuery`, `updateQuery`, `deleteQuery`, `countQuery`.
- * - All filter operators: equality, not, in, out, contains, gt, gte, lt, lte.
- * - Sorting (`$order`) and limiting (`$limit`).
  * - ID generation: `addItem()` generates a UUID v4 identifier automatically.
  *
  * ### Not supported
  * - **Realtime subscriptions:** `getItemSequence()` and `getQuerySequence()` throw `UnimplementedError`.
  *   KV has no change feed or push notification mechanism.
+ * - **Updates:** `updateItem()` and `updateQuery()` throw `UnimplementedError`.
+ * - **Collection queries:** `getQuery()`, `setQuery()`, `deleteQuery()`, and `countQuery()` are not supported.
+ *   KV does not expose efficient filtering, sorting, or collection scans, so this provider avoids
+ *   the old "read everything and filter in memory" behavior.
  *
  * ### Performance limitations
- * - **Querying is expensive:** KV has no native query support. Every `getQuery()` call lists all keys
- *   in the collection (paginated, 1000 keys per page), fetches each value individually, then applies
- *   filtering, sorting, and limiting in-memory. Avoid large collections where possible.
- * - **Non-atomic updates:** `updateItem()` performs a read-modify-write cycle. Concurrent writes to the
- *   same item may cause one write to be lost.
- * - **Eventual consistency:** KV is eventually consistent — reads may return stale data, particularly
- *   shortly after writes. This also affects `updateItem`, `setQuery`, `updateQuery`, and `deleteQuery`
- *   since they read before writing.
- * - **No bulk get:** Each item value must be fetched individually — there is no multi-get API.
- *   Query operations that match N items require N+1 KV requests (one `list` + N `get` calls per page).
+ * - **Single-key store only:** This provider is intentionally limited to direct key reads and writes.
+ *   If you need collection queries, filtering, sorting, or bulk mutations, use a different backend.
+ * - **Eventual consistency:** KV is eventually consistent, so reads may briefly return stale values
+ *   shortly after writes.
  */
 export declare class CloudflareKVProvider extends DBProvider<string> {
     private readonly _kv;
@@ -59,13 +43,11 @@ export declare class CloudflareKVProvider extends DBProvider<string> {
     getItemSequence<T extends Data>(_c: 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>(c: Collection<string, string, T>, id: string, updates: Updates<T>): Promise<void>;
+    updateItem<T extends Data>(_c: Collection<string, string, T>, _id: string, _updates: Updates<T>): Promise<void>;
     deleteItem<T extends Data>({ name }: Collection<string, string, T>, id: string): Promise<void>;
-    getQuery<T extends Data>({ name }: Collection<string, string, T>, q?: ItemQuery<string, T>): Promise<Items<string, T>>;
+    getQuery<T extends Data>(_c: 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>): AsyncIterable<Items<string, T>>;
-    setQuery<T extends Data>(c: Collection<string, string, T>, q: ItemQuery<string, T>, data: T): Promise<void>;
-    updateQuery<T extends Data>(c: Collection<string, string, T>, q: ItemQuery<string, T>, updates: Updates<T>): Promise<void>;
-    deleteQuery<T extends Data>(c: Collection<string, string, T>, q: ItemQuery<string, T>): Promise<void>;
-    /** Fetch all items in a collection, paginating through `kv.list()`. */
-    private _getAllItems;
+    setQuery<T extends Data>(_c: Collection<string, string, T>, _q: ItemQuery<string, T>, _data: T): Promise<void>;
+    updateQuery<T extends Data>(_c: Collection<string, string, T>, _q: ItemQuery<string, T>, _updates: Updates<T>): Promise<void>;
+    deleteQuery<T extends Data>(c: Collection<string, string, T>, _q: ItemQuery<string, T>): Promise<void>;
 }

package/cloudflare/CloudflareKVProvider.js

@@ -1,16 +1,7 @@
 import { DBProvider } from "../db/provider/DBProvider.js";
 import { UnimplementedError } from "../error/UnimplementedError.js";
-import { requireArray } from "../util/array.js";
 import { getItem } from "../util/item.js";
-import { queryItems } from "../util/query.js";
-import { updateData } from "../util/update.js";
 import { randomUUID } from "../util/uuid.js";
-function _getKey(collection, id) {
-    return `${collection}:${id}`;
-}
-function _getPrefix(collection) {
-    return `${collection}:`;
-}
 /**
  * Cloudflare Workers KV database provider.
  *
@@ -19,26 +10,21 @@ function _getPrefix(collection) {
  *
  * ### Supported
  * - Single item operations: `getItem`, `setItem`, `addItem`, `updateItem`, `deleteItem`.
- * - Query operations: `getQuery`, `setQuery`, `updateQuery`, `deleteQuery`, `countQuery`.
- * - All filter operators: equality, not, in, out, contains, gt, gte, lt, lte.
- * - Sorting (`$order`) and limiting (`$limit`).
  * - ID generation: `addItem()` generates a UUID v4 identifier automatically.
  *
  * ### Not supported
  * - **Realtime subscriptions:** `getItemSequence()` and `getQuerySequence()` throw `UnimplementedError`.
  *   KV has no change feed or push notification mechanism.
+ * - **Updates:** `updateItem()` and `updateQuery()` throw `UnimplementedError`.
+ * - **Collection queries:** `getQuery()`, `setQuery()`, `deleteQuery()`, and `countQuery()` are not supported.
+ *   KV does not expose efficient filtering, sorting, or collection scans, so this provider avoids
+ *   the old "read everything and filter in memory" behavior.
  *
  * ### Performance limitations
- * - **Querying is expensive:** KV has no native query support. Every `getQuery()` call lists all keys
- *   in the collection (paginated, 1000 keys per page), fetches each value individually, then applies
- *   filtering, sorting, and limiting in-memory. Avoid large collections where possible.
- * - **Non-atomic updates:** `updateItem()` performs a read-modify-write cycle. Concurrent writes to the
- *   same item may cause one write to be lost.
- * - **Eventual consistency:** KV is eventually consistent — reads may return stale data, particularly
- *   shortly after writes. This also affects `updateItem`, `setQuery`, `updateQuery`, and `deleteQuery`
- *   since they read before writing.
- * - **No bulk get:** Each item value must be fetched individually — there is no multi-get API.
- *   Query operations that match N items require N+1 KV requests (one `list` + N `get` calls per page).
+ * - **Single-key store only:** This provider is intentionally limited to direct key reads and writes.
+ *   If you need collection queries, filtering, sorting, or bulk mutations, use a different backend.
+ * - **Eventual consistency:** KV is eventually consistent, so reads may briefly return stale values
+ *   shortly after writes.
  */
 export class CloudflareKVProvider extends DBProvider {
     _kv;
@@ -62,52 +48,28 @@ export class CloudflareKVProvider extends DBProvider {
     async setItem({ name }, id, data) {
         await this._kv.put(_getKey(name, id), JSON.stringify(data));
     }
-    async updateItem(c, id, updates) {
-        const existing = await this.getItem(c, id);
-        if (existing)
-            await this.setItem(c, id, updateData(existing, updates));
+    async updateItem(_c, _id, _updates) {
+        throw new UnimplementedError("CloudflareKVProvider does not support updates to items");
     }
     async deleteItem({ name }, id) {
         await this._kv.delete(_getKey(name, id));
     }
-    async getQuery({ name }, q) {
-        const all = await this._getAllItems(name);
-        return q ? requireArray(queryItems(all, q)) : all;
+    async getQuery(_c, _q) {
+        throw new UnimplementedError("CloudflareKVProvider does not support querying items");
     }
     getQuerySequence(_c, _q) {
         throw new UnimplementedError("CloudflareKVProvider does not support realtime subscriptions");
     }
-    async setQuery(c, q, data) {
-        const items = await this.getQuery(c, q);
-        await Promise.all(items.map(item => this.setItem(c, item.id, data)));
+    async setQuery(_c, _q, _data) {
+        throw new UnimplementedError("CloudflareKVProvider does not support querying items");
     }
-    async updateQuery(c, q, updates) {
-        const items = await this.getQuery(c, q);
-        await Promise.all(items.map(item => this.setItem(c, item.id, updateData(item, updates))));
+    async updateQuery(_c, _q, _updates) {
+        throw new UnimplementedError("CloudflareKVProvider does not support updates to items");
     }
-    async deleteQuery(c, q) {
-        const items = await this.getQuery(c, q);
-        await Promise.all(items.map(item => this._kv.delete(_getKey(c.name, item.id))));
-    }
-    /** Fetch all items in a collection, paginating through `kv.list()`. */
-    async _getAllItems(collection) {
-        const prefix = _getPrefix(collection);
-        const items = [];
-        let cursor;
-        do {
-            const result = await this._kv.list(cursor ? { prefix, cursor } : { prefix });
-            const values = await Promise.all(result.keys.map(async (key) => {
-                const id = key.name.slice(prefix.length);
-                const data = (await this._kv.get(key.name, { type: "json" }));
-                if (data)
-                    return getItem(id, data);
-            }));
-            for (const item of values) {
-                if (item)
-                    items.push(item);
-            }
-            cursor = result.list_complete ? undefined : result.cursor;
-        } while (cursor);
-        return items;
+    async deleteQuery(c, _q) {
+        throw new UnimplementedError("CloudflareKVProvider does not support querying items");
     }
 }
+function _getKey(collection, id) {
+    return `${collection}:${id}`;
+}

package/db/provider/CacheDBProvider.js

@@ -11,51 +11,51 @@ export class CacheDBProvider extends DBProvider {
     }
     async getItem(collection, id) {
         const item = await this.source.getItem(collection, id);
-        const table = this.memory.getTable(collection.name);
+        const table = this.memory.getTable(collection);
         item ? table.setItem(id, item) : table.deleteItem(id);
         return item;
     }
     getItemSequence(collection, id) {
-        return this.memory.setItemSequence(collection, id, this.source.getItemSequence(collection, id));
+        return this.memory.getTable(collection).setItemSequence(id, this.source.getItemSequence(collection, id));
     }
     async addItem(collection, data) {
         const id = await this.source.addItem(collection, data);
-        this.memory.getTable(collection.name).setItem(id, data);
+        this.memory.getTable(collection).setItem(id, data);
         return id;
     }
     async setItem(collection, id, data) {
         await this.source.setItem(collection, id, data);
-        this.memory.getTable(collection.name).setItem(id, data);
+        this.memory.getTable(collection).setItem(id, data);
     }
     async updateItem(collection, id, updates) {
         await this.source.updateItem(collection, id, updates);
-        this.memory.getTable(collection.name).updateItem(id, updates);
+        this.memory.getTable(collection).updateItem(id, updates);
     }
     async deleteItem(collection, id) {
         await this.source.deleteItem(collection, id);
-        this.memory.getTable(collection.name).deleteItem(id);
+        this.memory.getTable(collection).deleteItem(id);
     }
     countQuery(collection, query) {
         return this.source.countQuery(collection, query);
     }
     async getQuery(collection, query) {
         const items = await this.source.getQuery(collection, query);
-        this.memory.getTable(collection.name).setItems(items, query);
+        this.memory.getTable(collection).setItems(items);
         return items;
     }
     getQuerySequence(collection, query) {
-        return this.memory.setItemsSequence(collection, this.source.getQuerySequence(collection, query), query);
+        return this.memory.getTable(collection).setItemsSequence(this.source.getQuerySequence(collection, query));
     }
     async setQuery(collection, query, data) {
         await this.source.setQuery(collection, query, data);
-        this.memory.getTable(collection.name).setQuery(query, data);
+        this.memory.getTable(collection).setQuery(query, data);
     }
     async updateQuery(collection, query, updates) {
         await this.source.updateQuery(collection, query, updates);
-        this.memory.getTable(collection.name).updateQuery(query, updates);
+        this.memory.getTable(collection).updateQuery(query, updates);
     }
     async deleteQuery(collection, query) {
         await this.source.deleteQuery(collection, query);
-        this.memory.getTable(collection.name).deleteQuery(query);
+        this.memory.getTable(collection).deleteQuery(query);
     }
 }

package/db/provider/ChangesDBProvider.js

@@ -7,7 +7,7 @@ export class ChangesDBProvider extends ThroughDBProvider {
     _changes = [];
     async addItem(collection, data) {
         const id = await super.addItem(collection, data);
-        this._changes.push({ action: "set", collection: collection.name, id, data });
+        this._changes.push({ action: "add", collection: collection.name, id, data });
         return id;
     }
     async setItem(collection, id, data) {

package/db/provider/MemoryDBProvider.d.ts

@@ -14,39 +14,34 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier> extends
     /** List of tables in `{ collection: Table }` format. */
     private _tables;
     /** Get a table for a collection. */
-    getTable<T extends Data>(collection: string): MemoryTable<I, T>;
-    getItemTime<T extends Data>(collection: Collection<string, I, T>, id: I): number | undefined;
+    getTable<T extends Data>({ name }: Collection<string, I, T>): MemoryTable<I, T>;
     getItem<T extends Data>(collection: Collection<string, I, T>, id: I): Promise<OptionalItem<I, T>>;
     getItemSequence<T extends Data>(collection: Collection<string, I, T>, id: I): AsyncIterable<OptionalItem<I, T>>;
-    getCachedItemSequence<T extends Data>(collection: Collection<string, I, T>, id: I): AsyncIterable<OptionalItem<I, T>>;
     addItem<T extends Data>(collection: Collection<string, I, T>, data: T): Promise<I>;
     setItem<T extends Data>(collection: Collection<string, I, T>, id: I, data: T): Promise<void>;
-    setItemSequence<T extends Data>(collection: Collection<string, I, T>, id: I, sequence: AsyncIterable<OptionalItem<I, T>>): AsyncIterable<OptionalItem<I, T>>;
     updateItem<T extends Data>(collection: Collection<string, I, T>, id: I, updates: Updates<T>): Promise<void>;
     deleteItem<T extends Data>(collection: Collection<string, I, T>, id: I): Promise<void>;
-    getQueryTime<T extends Data>(collection: Collection<string, I, T>, query?: ItemQuery<I, T>): number | undefined;
     countQuery<T extends Data>(collection: Collection<string, I, T>, query?: ItemQuery<I, T>): Promise<number>;
     getQuery<T extends Data>(collection: Collection<string, I, T>, query?: ItemQuery<I, T>): Promise<Items<I, T>>;
     getQuerySequence<T extends Data>(collection: Collection<string, I, T>, query?: ItemQuery<I, T>): AsyncIterable<Items<I, T>>;
-    getCachedQuerySequence<T extends Data>(collection: Collection<string, I, T>, query?: ItemQuery<I, T>): AsyncIterable<Items<I, T>>;
     setQuery<T extends Data>(collection: Collection<string, I, T>, query: ItemQuery<I, T>, data: T): Promise<void>;
     updateQuery<T extends Data>(collection: Collection<string, I, T>, query: ItemQuery<I, T>, updates: Updates<T>): Promise<void>;
     deleteQuery<T extends Data>(collection: Collection<string, I, T>, query: ItemQuery<I, T>): Promise<void>;
-    setItems<T extends Data>(collection: Collection<string, I, T>, items: Items<I, T>, query?: ItemQuery<I, T>): void;
-    setItemsSequence<T extends Data>(collection: Collection<string, I, T>, sequence: AsyncIterable<Items<I, T>>, query?: ItemQuery<I, T>): AsyncIterable<Items<I, T>>;
+    setItems<T extends Data>(collection: Collection<string, I, T>, items: Items<I, T>): void;
 }
 /** An individual table of data. */
 export declare class MemoryTable<I extends Identifier, T extends Data> {
     /** Actual data in this table. */
     protected readonly _data: Map<Identifier, Item<I, T>>;
-    /** Times data was last updated. */
-    protected readonly _times: Map<Identifier, number>;
     /** Deferred sequence of next values. */
     readonly next: DeferredSequence<void>;
-    getItemTime(id: I): number | undefined;
     getItem(id: I): OptionalItem<I, T>;
+    /**
+     * Subscribe to all changes for this item key.
+     * - Emits the current item immediately, including `undefined` when absent.
+     * - Wakes on every table change, but only yields when this item's value actually changed.
+     */
     getItemSequence(id: I): AsyncIterable<OptionalItem<I, T>>;
-    getCachedItemSequence(id: I): AsyncIterable<OptionalItem<I, T>>;
     /** Function to generate a random ID for this table. */
     generateUniqueID(): I;
     addItem(data: T): I;
@@ -54,14 +49,17 @@ export declare class MemoryTable<I extends Identifier, T extends Data> {
     setItemSequence(id: I, sequence: AsyncIterable<OptionalItem<I, T>>): AsyncIterable<OptionalItem<I, T>>;
     updateItem(id: I, updates: Updates<T>): void;
     deleteItem(id: I): void;
-    getQueryTime(query?: ItemQuery<I, T>): number | undefined;
     countQuery(query?: ItemQuery<I, T>): number;
     getQuery(query?: ItemQuery<I, T>): Items<I, T>;
+    /**
+     * Subscribe to the live result of a query.
+     * - Emits the current query result immediately, even if empty.
+     * - Wakes on every table change, but only yields when the computed query result changed.
+     */
     getQuerySequence(query?: ItemQuery<I, T>): AsyncIterable<Items<I, T>>;
-    getCachedQuerySequence(query?: ItemQuery<I, T>): AsyncIterable<Items<I, T>>;
     setQuery(query: ItemQuery<I, T>, data: T): void;
     updateQuery(query: ItemQuery<I, T>, updates: Updates<T>): void;
     deleteQuery(query: ItemQuery<I, T>): void;
-    setItems(items: Items<I, T>, query?: ItemQuery<I, T>): void;
-    setItemsSequence(sequence: AsyncIterable<Items<I, T>>, query?: ItemQuery<I, T>): AsyncIterable<Items<I, T>>;
+    setItems(items: Items<I, T>): void;
+    setItemsSequence(sequence: AsyncIterable<Items<I, T>>): AsyncIterable<Items<I, T>>;
 }

package/db/provider/MemoryDBProvider.js

@@ -17,82 +17,63 @@ export class MemoryDBProvider extends DBProvider {
     // biome-ignore lint/suspicious/noExplicitAny: Internal storage erases T; getTable<T> restores it per-call.
     _tables = {};
     /** Get a table for a collection. */
-    getTable(collection) {
-        // biome-ignore lint/suspicious/noAssignInExpressions: This is convenient.
-        return (this._tables[collection] ||= new MemoryTable());
-    }
-    getItemTime(collection, id) {
-        return this.getTable(collection.name).getItemTime(id);
+    getTable({ name }) {
+        return (this._tables[name] ||= new MemoryTable());
     }
     async getItem(collection, id) {
-        return this.getTable(collection.name).getItem(id);
+        return this.getTable(collection).getItem(id);
     }
     async *getItemSequence(collection, id) {
-        yield* this.getTable(collection.name).getItemSequence(id);
-    }
-    getCachedItemSequence(collection, id) {
-        return this.getTable(collection.name).getCachedItemSequence(id);
+        yield* this.getTable(collection).getItemSequence(id);
     }
     async addItem(collection, data) {
-        return this.getTable(collection.name).addItem(data);
+        return this.getTable(collection).addItem(data);
     }
     async setItem(collection, id, data) {
-        this.getTable(collection.name).setItem(id, data);
-    }
-    setItemSequence(collection, id, sequence) {
-        return this.getTable(collection.name).setItemSequence(id, sequence);
+        this.getTable(collection).setItem(id, data);
     }
     async updateItem(collection, id, updates) {
-        this.getTable(collection.name).updateItem(id, updates);
+        this.getTable(collection).updateItem(id, updates);
     }
     async deleteItem(collection, id) {
-        this.getTable(collection.name).deleteItem(id);
-    }
-    getQueryTime(collection, query) {
-        return this.getTable(collection.name).getQueryTime(query);
+        this.getTable(collection).deleteItem(id);
     }
     async countQuery(collection, query) {
-        return this.getTable(collection.name).countQuery(query);
+        return this.getTable(collection).countQuery(query);
     }
     async getQuery(collection, query) {
-        return this.getTable(collection.name).getQuery(query);
+        return this.getTable(collection).getQuery(query);
     }
     async *getQuerySequence(collection, query) {
-        yield* this.getTable(collection.name).getQuerySequence(query);
-    }
-    getCachedQuerySequence(collection, query) {
-        return this.getTable(collection.name).getCachedQuerySequence(query);
+        yield* this.getTable(collection).getQuerySequence(query);
     }
     async setQuery(collection, query, data) {
-        this.getTable(collection.name).setQuery(query, data);
+        this.getTable(collection).setQuery(query, data);
     }
     async updateQuery(collection, query, updates) {
-        this.getTable(collection.name).updateQuery(query, updates);
+        this.getTable(collection).updateQuery(query, updates);
     }
     async deleteQuery(collection, query) {
-        this.getTable(collection.name).deleteQuery(query);
-    }
-    setItems(collection, items, query) {
-        this.getTable(collection.name).setItems(items, query);
+        this.getTable(collection).deleteQuery(query);
     }
-    setItemsSequence(collection, sequence, query) {
-        return this.getTable(collection.name).setItemsSequence(sequence, query);
+    setItems(collection, items) {
+        this.getTable(collection).setItems(items);
     }
 }
 /** An individual table of data. */
 export class MemoryTable {
     /** Actual data in this table. */
     _data = new Map();
-    /** Times data was last updated. */
-    _times = new Map();
     /** Deferred sequence of next values. */
     next = new DeferredSequence();
-    getItemTime(id) {
-        return this._times.get(id);
-    }
     getItem(id) {
         return this._data.get(id);
     }
+    /**
+     * Subscribe to all changes for this item key.
+     * - Emits the current item immediately, including `undefined` when absent.
+     * - Wakes on every table change, but only yields when this item's value actually changed.
+     */
     async *getItemSequence(id) {
         let lastValue = this.getItem(id);
         yield lastValue;
@@ -105,20 +86,6 @@ export class MemoryTable {
             }
         }
     }
-    async *getCachedItemSequence(id) {
-        let lastTime = this._times.get(id);
-        if (typeof lastTime === "number")
-            yield this.getItem(id);
-        while (true) {
-            await this.next;
-            const nextTime = this._times.get(id);
-            if (nextTime !== lastTime) {
-                if (typeof nextTime === "number")
-                    yield this.getItem(id);
-                lastTime = nextTime;
-            }
-        }
-    }
     generateUniqueID() {
         const gen = typeof this._data.keys().next().value === "number" ? getRandom : getRandomKey;
         let id = gen();
@@ -135,7 +102,6 @@ export class MemoryTable {
         const item = getItem(id, data);
         if (this._data.get(id) !== item) {
             this._data.set(id, item);
-            this._times.set(id, Date.now());
             this.next.resolve();
         }
     }
@@ -147,25 +113,31 @@ export class MemoryTable {
     }
     updateItem(id, updates) {
         const oldItem = this._data.get(id);
-        if (oldItem)
-            this.setItem(id, updateData(oldItem, updates));
+        if (!oldItem)
+            return;
+        const nextItem = updateData(oldItem, updates);
+        if (this._data.get(id) !== nextItem) {
+            this._data.set(id, nextItem);
+            this.next.resolve();
+        }
     }
     deleteItem(id) {
         if (this._data.has(id)) {
             this._data.delete(id);
-            this._times.set(id, Date.now());
             this.next.resolve();
         }
     }
-    getQueryTime(query) {
-        return this._times.get(_getQueryKey(query));
-    }
     countQuery(query) {
         return query ? countItems(queryItems(this._data.values(), query)) : this._data.size;
     }
     getQuery(query) {
         return requireArray(query ? queryItems(this._data.values(), query) : this._data.values());
     }
+    /**
+     * Subscribe to the live result of a query.
+     * - Emits the current query result immediately, even if empty.
+     * - Wakes on every table change, but only yields when the computed query result changed.
+     */
     async *getQuerySequence(query) {
         let lastItems = this.getQuery(query);
         yield lastItems;
@@ -178,72 +150,59 @@ export class MemoryTable {
             }
         }
     }
-    async *getCachedQuerySequence(query) {
-        const key = _getQueryKey(query);
-        let lastTime = this._times.get(key);
-        if (typeof lastTime === "number")
-            yield this.getQuery(query);
-        while (true) {
-            await this.next;
-            const nextTime = this._times.get(key);
-            if (lastTime !== nextTime) {
-                if (typeof nextTime === "number")
-                    yield this.getQuery(query);
-                lastTime = nextTime;
-            }
-        }
-    }
     setQuery(query, data) {
-        let changed = 0;
+        let changed = false;
         for (const { id } of queryWritableItems(this._data.values(), query)) {
-            this.setItem(id, data);
-            changed++;
+            const item = getItem(id, data);
+            if (this._data.get(id) !== item) {
+                this._data.set(id, item);
+                changed = true;
+            }
         }
-        if (changed) {
-            const key = _getQueryKey(query);
-            this._times.set(key, Date.now());
+        if (changed)
             this.next.resolve();
-        }
     }
     updateQuery(query, updates) {
-        let count = 0;
+        let changed = false;
         for (const { id } of queryWritableItems(this._data.values(), query)) {
-            this.updateItem(id, updates);
-            count++;
+            const oldItem = this._data.get(id);
+            if (!oldItem)
+                continue;
+            const nextItem = updateData(oldItem, updates);
+            if (this._data.get(id) !== nextItem) {
+                this._data.set(id, nextItem);
+                changed = true;
+            }
         }
-        if (count) {
-            const key = _getQueryKey(query);
-            this._times.set(key, Date.now());
+        if (changed)
             this.next.resolve();
-        }
     }
     deleteQuery(query) {
-        let count = 0;
+        let changed = false;
         for (const { id } of queryWritableItems(this._data.values(), query)) {
-            this.deleteItem(id);
-            count++;
+            if (this._data.has(id)) {
+                this._data.delete(id);
+                changed = true;
+            }
         }
-        if (count) {
-            const key = _getQueryKey(query);
-            this._times.set(key, Date.now());
+        if (changed)
             this.next.resolve();
-        }
     }
-    setItems(items, query) {
-        for (const item of items)
-            this.setItem(item.id, item);
-        if (query) {
-            const key = _getQueryKey(query);
-            this._times.set(key, Date.now());
-            this.next.resolve();
+    setItems(items) {
+        let changed = false;
+        for (const item of items) {
+            if (this._data.get(item.id) !== item) {
+                this._data.set(item.id, item);
+                changed = true;
+            }
         }
+        if (changed)
+            this.next.resolve();
     }
-    async *setItemsSequence(sequence, query) {
+    async *setItemsSequence(sequence) {
         for await (const items of sequence) {
-            this.setItems(items, query);
+            this.setItems(items);
             yield items;
         }
     }
 }
-// Queries that have no limit don't care about sorting either.
-const _getQueryKey = (query) => (query ? JSON.stringify(query) : "{}");

package/db/store/ItemStore.js

@@ -29,17 +29,15 @@ export class ItemStore extends OptionalDataStore {
         this.value = getItem(this.id, data);
     }
     constructor(collection, id, provider, memory) {
-        const time = memory?.getItemTime(collection, id);
-        const item = memory?.getTable(collection.name).getItem(id);
-        super(typeof time === "number" || item ? item : NONE, time); // Use the cached value if it was definitely cached or is not undefined.
+        const item = memory?.getTable(collection).getItem(id);
+        super(item ?? NONE); // Use the current memory snapshot if available.
         if (memory)
-            this.starter = store => runSequence(store.through(memory.getCachedItemSequence(collection, id)));
+            this.starter = store => runSequence(store.through(memory.getItemSequence(collection, id)));
         this.provider = provider;
         this.collection = collection;
         this.id = id;
-        // Start loading the value from the provider if it wasn't cached.
-        if (typeof time !== "number")
-            this.refresh();
+        // Always refresh from source, even if memory supplied an initial value.
+        this.refresh();
     }
     /** Refresh this store from the source provider. */
     refresh(provider = this.provider) {

package/db/store/QueryStore.js

@@ -44,18 +44,16 @@ export class QueryStore extends ArrayStore {
         return last;
     }
     constructor(collection, query, provider, memory) {
-        const time = memory?.getQueryTime(collection, query);
-        const items = memory?.getTable(collection.name).getQuery(query) || [];
-        super(typeof time === "number" || items.length ? items : NONE, time); // Use the value if it was definitely cached or is not empty.
+        const items = memory?.getTable(collection).getQuery(query);
+        super(items ?? NONE); // Use the current memory snapshot if available.
         if (memory)
-            this.starter = store => runSequence(store.through(memory.getCachedQuerySequence(collection, query)));
+            this.starter = store => runSequence(store.through(memory.getQuerySequence(collection, query)));
         this.provider = provider;
         this.collection = collection;
         this.query = query;
         this.limit = getLimit(query) ?? Number.POSITIVE_INFINITY;
-        // Start loading the value from the provider if it is not definitely cached.
-        if (typeof time !== "number")
-            this.refresh();
+        // Always refresh from source, even if memory supplied an initial value.
+        this.refresh();
     }
     /** Refresh this store from the source provider. */
     refresh(provider = this.provider) {

package/package.json

@@ -1,27 +1,29 @@
 {
 	"name": "shelving",
-	"description": "Toolkit for using data in JavaScript.",
-	"keywords": [
-		"javascript",
-		"typescript",
-		"schema",
-		"validation",
-		"database",
-		"database-connector",
-		"state-management",
-		"query-builder"
-	],
-	"version": "1.179.0",
+	"version": "1.179.2",
+	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/dhoulb/shelving.git"
 	},
-	"author": "Dave Houlbrooke <dave@shax.com>",
-	"license": "0BSD",
-	"type": "module",
-	"module": "./index.js",
 	"main": "./index.js",
-	"types": "./index.d.ts",
+	"module": "./index.js",
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.9",
+		"@google-cloud/firestore": "^8.3.0",
+		"@types/bun": "^1.3.11",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"firebase": "^12.11.0",
+		"react": "^19.2.4",
+		"react-dom": "^19.2.4",
+		"typescript": "^5.9.3"
+	},
+	"peerDependencies": {
+		"@google-cloud/firestore": ">=7.0.0",
+		"firebase": ">=11.0.0",
+		"react": ">=19.0.0"
+	},
 	"exports": {
 		".": "./index.js",
 		"./api": "./api/index.js",
@@ -40,11 +42,22 @@
 		"./test": "./test/index.js",
 		"./util": "./util/index.js"
 	},
-	"sideEffects": false,
+	"description": "Toolkit for using data in JavaScript.",
 	"engineStrict": true,
 	"engines": {
 		"node": ">=16.0.0"
 	},
+	"keywords": [
+		"javascript",
+		"typescript",
+		"schema",
+		"validation",
+		"database",
+		"database-connector",
+		"state-management",
+		"query-builder"
+	],
+	"license": "0BSD",
 	"scripts": {
 		"test": "bun run --parallel test:*",
 		"test:lint": "biome check .",
@@ -59,20 +72,7 @@
 		"build:test:syntax": "bun run ./dist/index.js",
 		"build:test:unit": "bun test ./dist/**/*.test.js --bail"
 	},
-	"devDependencies": {
-		"@biomejs/biome": "^2.4.9",
-		"@google-cloud/firestore": "^8.3.0",
-		"@types/bun": "^1.3.11",
-		"@types/react": "^19.2.14",
-		"@types/react-dom": "^19.2.3",
-		"firebase": "^12.11.0",
-		"react": "^19.2.4",
-		"react-dom": "^19.2.4",
-		"typescript": "^5.9.3"
-	},
-	"peerDependencies": {
-		"@google-cloud/firestore": ">=7.0.0",
-		"firebase": ">=11.0.0",
-		"react": ">=19.0.0"
-	}
+	"sideEffects": false,
+	"type": "module",
+	"types": "./index.d.ts"
 }