@procedures/store 0.8.0 → 0.9.0

package/dist/indexeddb/sync-state-store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A sync state store in IndexedDB, for the `HybridStorage` of a browser (roadmap CLI-21).
+ *
+ * The state is in the object store `state` of one database: one record for the cursor, and one
+ * record for the base version of each id. A change writes only the records that it names, in one
+ * transaction, so a reader never sees a part of it. Give each storage its own database.
+ */
+import type { SyncState, SyncStateChange, SyncStateStore } from "../storage/sync-state.js";
+import { type IndexedDbOptions } from "./idb.js";
+/**
+ * A sync state store in IndexedDB.
+ *
+ * @example
+ * ```typescript
+ * import { HybridStorage } from "@procedures/store";
+ * import { IndexedDbQueueStore, IndexedDbSyncStateStore } from "@procedures/store/indexeddb";
+ *
+ * const users = new HybridStorage(remote, {
+ *   local: durableLocalCopy,
+ *   queueStore: new IndexedDbQueueStore("users-queue"),
+ *   syncState: new IndexedDbSyncStateStore("users-sync"),
+ * });
+ * ```
+ */
+export declare class IndexedDbSyncStateStore implements SyncStateStore {
+    private readonly connection;
+    /**
+     * @param name - The name of the database: one database for each storage. The store makes it at the first operation.
+     * @param options - The IndexedDB factory. The default is the `indexedDB` of the global scope.
+     */
+    constructor(name: string, options?: IndexedDbOptions);
+    /** The name of the database. */
+    get name(): string;
+    load(): Promise<SyncState | undefined>;
+    write(change: SyncStateChange): Promise<void>;
+    clear(): Promise<void>;
+    /** This method closes the database. The state stays in it. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=sync-state-store.d.ts.map

package/dist/indexeddb/sync-state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-state-store.d.ts","sourceRoot":"","sources":["../../src/indexeddb/sync-state-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AA2BrE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,uBAAwB,YAAW,cAAc;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAEhD;;;OAGG;IACH,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,EAGvD;IAED,gCAAgC;IAChC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAKrC;IAEK,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAYlD;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAK3B;IAED,8DAA8D;IAC9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAErB;CACF"}

package/dist/indexeddb/sync-state-store.js

@@ -0,0 +1,94 @@
+/**
+ * A sync state store in IndexedDB, for the `HybridStorage` of a browser (roadmap CLI-21).
+ *
+ * The state is in the object store `state` of one database: one record for the cursor, and one
+ * record for the base version of each id. A change writes only the records that it names, in one
+ * transaction, so a reader never sees a part of it. Give each storage its own database.
+ */
+import { IdbStoreConnection } from "./idb.js";
+/** The key of the record of the cursor. The keys of the bases start with `BASE`. */
+const CURSOR_KEY = "cursor";
+const BASE = "base:";
+/** The state of the records, or an error for a record of another form. */
+function stateOf(records, name) {
+    if (records.length === 0)
+        return undefined;
+    let cursor;
+    const bases = [];
+    records.forEach((value, index) => {
+        const record = value;
+        if (record?.kind === "cursor" && (record.cursor === undefined || typeof record.cursor === "string")) {
+            cursor = record.cursor;
+        }
+        else if (record?.kind === "base" && typeof record.id === "string" && (record.version === null || typeof record.version === "string")) {
+            bases.push([record.id, record.version]);
+        }
+        else {
+            throw new Error(`The sync state database ${name} has a record that is not a sync state (record ${index + 1})`);
+        }
+    });
+    return { ...(cursor !== undefined && { cursor }), bases };
+}
+/**
+ * A sync state store in IndexedDB.
+ *
+ * @example
+ * ```typescript
+ * import { HybridStorage } from "@procedures/store";
+ * import { IndexedDbQueueStore, IndexedDbSyncStateStore } from "@procedures/store/indexeddb";
+ *
+ * const users = new HybridStorage(remote, {
+ *   local: durableLocalCopy,
+ *   queueStore: new IndexedDbQueueStore("users-queue"),
+ *   syncState: new IndexedDbSyncStateStore("users-sync"),
+ * });
+ * ```
+ */
+export class IndexedDbSyncStateStore {
+    connection;
+    /**
+     * @param name - The name of the database: one database for each storage. The store makes it at the first operation.
+     * @param options - The IndexedDB factory. The default is the `indexedDB` of the global scope.
+     */
+    constructor(name, options = {}) {
+        if (typeof name !== "string" || name === "")
+            throw new TypeError("IndexedDbSyncStateStore needs the name of a database");
+        this.connection = new IdbStoreConnection(name, "state", {}, options.indexedDB);
+    }
+    /** The name of the database. */
+    get name() {
+        return this.connection.database;
+    }
+    load() {
+        return this.connection.run("readonly", (store) => {
+            const request = store.getAll();
+            return () => stateOf(request.result, this.name);
+        });
+    }
+    async write(change) {
+        await this.connection.run("readwrite", (store) => {
+            if (change.reset)
+                store.clear();
+            const cursor = change.cursor === undefined ? { kind: "cursor" } : { kind: "cursor", cursor: change.cursor };
+            store.put(cursor, CURSOR_KEY);
+            for (const [id, version] of change.bases) {
+                const record = { kind: "base", id, version };
+                store.put(record, BASE + id);
+            }
+            for (const id of change.forgotten)
+                store.delete(BASE + id);
+            return () => undefined;
+        });
+    }
+    async clear() {
+        await this.connection.run("readwrite", (store) => {
+            store.clear();
+            return () => undefined;
+        });
+    }
+    /** This method closes the database. The state stays in it. */
+    close() {
+        return this.connection.close();
+    }
+}
+//# sourceMappingURL=sync-state-store.js.map

package/dist/indexeddb/sync-state-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-state-store.js","sourceRoot":"","sources":["../../src/indexeddb/sync-state-store.ts"],"names":[],"mappings":"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"}

package/dist/indexeddb.d.ts

@@ -3,17 +3,22 @@
  *
  * - `IndexedDbProgramStore` keeps programs in IndexedDB.
  * - `IndexedDbQueueStore` keeps the queue of a `HybridStorage` in IndexedDB.
- * - `MemoryProgramStore` and `MemoryQueueStore` are the fallbacks for a browser without
- *   IndexedDB. `hasIndexedDb()` tells which one to use.
+ * - `IndexedDbSyncStateStore` keeps the sync state of a `HybridStorage` in IndexedDB: the cursor
+ *   and the base versions (roadmap CLI-21).
+ * - `MemoryProgramStore`, `MemoryQueueStore` and `MemorySyncStateStore` are the fallbacks for a
+ *   browser without IndexedDB. `hasIndexedDb()` tells which one to use.
  *
  * The package root does not import this entry, and this entry does not import the client or zod:
  * a page that loads it gets only these stores.
  */
 export { IndexedDbProgramStore, DEFAULT_PROGRAM_DATABASE } from "./indexeddb/program-store.js";
 export { IndexedDbQueueStore } from "./indexeddb/queue-store.js";
+export { IndexedDbSyncStateStore } from "./indexeddb/sync-state-store.js";
 export { hasIndexedDb, type IdbFactoryLike, type IndexedDbOptions } from "./indexeddb/idb.js";
 export { MemoryProgramStore } from "./program-store/memory.js";
 export { MemoryQueueStore } from "./storage/queue.js";
+export { MemorySyncStateStore } from "./storage/sync-state.js";
+export type { SyncState, SyncStateChange, SyncStateStore } from "./storage/sync-state.js";
 export type { ProgramStore, StoredProgram } from "./program-store/types.js";
 export type { QueuedOperation, QueueStore } from "./storage/queue.js";
 //# sourceMappingURL=indexeddb.d.ts.map

package/dist/indexeddb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexeddb.d.ts","sourceRoot":"","sources":["../src/indexeddb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC5E,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"indexeddb.d.ts","sourceRoot":"","sources":["../src/indexeddb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC1F,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC5E,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/indexeddb.js

@@ -3,15 +3,19 @@
  *
  * - `IndexedDbProgramStore` keeps programs in IndexedDB.
  * - `IndexedDbQueueStore` keeps the queue of a `HybridStorage` in IndexedDB.
- * - `MemoryProgramStore` and `MemoryQueueStore` are the fallbacks for a browser without
- *   IndexedDB. `hasIndexedDb()` tells which one to use.
+ * - `IndexedDbSyncStateStore` keeps the sync state of a `HybridStorage` in IndexedDB: the cursor
+ *   and the base versions (roadmap CLI-21).
+ * - `MemoryProgramStore`, `MemoryQueueStore` and `MemorySyncStateStore` are the fallbacks for a
+ *   browser without IndexedDB. `hasIndexedDb()` tells which one to use.
  *
  * The package root does not import this entry, and this entry does not import the client or zod:
  * a page that loads it gets only these stores.
  */
 export { IndexedDbProgramStore, DEFAULT_PROGRAM_DATABASE } from "./indexeddb/program-store.js";
 export { IndexedDbQueueStore } from "./indexeddb/queue-store.js";
+export { IndexedDbSyncStateStore } from "./indexeddb/sync-state-store.js";
 export { hasIndexedDb } from "./indexeddb/idb.js";
 export { MemoryProgramStore } from "./program-store/memory.js";
 export { MemoryQueueStore } from "./storage/queue.js";
+export { MemorySyncStateStore } from "./storage/sync-state.js";
 //# sourceMappingURL=indexeddb.js.map

package/dist/indexeddb.js.map

@@ -1 +1 @@
-{"version":3,"file":"indexeddb.js","sourceRoot":"","sources":["../src/indexeddb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,YAAY,EAA8C,MAAM,oBAAoB,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"indexeddb.js","sourceRoot":"","sources":["../src/indexeddb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,YAAY,EAA8C,MAAM,oBAAoB,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/storage/api.d.ts

@@ -6,9 +6,10 @@
  *
  * This is the KEY integration between Collections and Universal Client!
  */
-import type { CollectionStorage, StorageChanges, StorageMetadata } from "@procedures/collections";
+import type { CollectionStorage, StorageChanges, StorageMetadata, StorageWriteOptions } from "@procedures/collections";
+import { type StoragePatch, type StorageQueryOptions, type StorageQueryPolicy, type StorageSelector } from "@procedures/client/query";
 import type { Client } from "@procedures/client";
-import { type Duration } from "@procedures/client";
+import { type Clock, type Duration } from "@procedures/client";
 /**
  * API storage configuration options.
  */
@@ -31,7 +32,7 @@ export interface ApiStorageOptions {
      */
     version?: string;
     /**
-     * Custom operation names (override defaults)
+     * Custom operation names (override defaults). `find` is the operation of `query()`.
      */
     operations?: {
         get?: string;
@@ -40,6 +41,7 @@ export interface ApiStorageOptions {
         ids?: string;
         changes?: string;
         find?: string;
+        patch?: string;
         has?: string;
         size?: string;
         set?: string;
@@ -56,15 +58,50 @@ export interface ApiStorageOptions {
     timeout?: Duration;
     /**
      * Retry a call that fails with a retryable error: true (3 attempts), false (1 attempt), or the
-     * number of attempts.
+     * number of attempts. Each collection procedure is idempotent, so a retry is safe.
      * @default true
      */
     retry?: boolean | number;
     /**
-     * The first delay between attempts. Each later delay is two times longer.
+     * The backoff of the first retry. Each later backoff is `retryFactor` times longer, at most
+     * `maxRetryDelay`. The wait is `backoffDelay` of `@mark1russell7/service/backoff`.
      * @default 100 milliseconds
      */
     retryDelay?: Duration;
+    /**
+     * The factor of the backoff from one retry to the next.
+     * @default 2
+     */
+    retryFactor?: number;
+    /**
+     * The longest backoff of a retry, before its random part.
+     * @default 30 seconds
+     */
+    maxRetryDelay?: Duration;
+    /**
+     * The random part of each wait, from 0 to 1. With 1 (full jitter), the wait is a random time from
+     * 0 to the backoff, so the clients that failed together do not retry together. 0 gives the
+     * backoff exactly. A server that asks for a wait (`retryAfterMs` of the error) gets at least it.
+     * @default 1
+     */
+    retryJitter?: number;
+    /**
+     * The clock of the timeout and of the waits between attempts. A test gives `fakeClock` of
+     * `@mark1russell7/service/testing`.
+     * @default the clock of the platform (`realClock` of `@procedures/client`)
+     */
+    clock?: Clock;
+    /**
+     * The random numbers of the jitter, from 0 up to 1. A test gives a fixed generator.
+     * @default Math.random
+     */
+    random?: () => number;
+    /**
+     * The query policy that `query()` applies before it sends a query, for a call without a policy.
+     * The server applies its own policy too. Without it, the storage examines only the form of a
+     * selector, and the server decides the rest.
+     */
+    queryPolicy?: StorageQueryPolicy;
     /**
      * AbortSignal for cancelling requests
      */
@@ -84,11 +121,16 @@ export interface ApiStorageOptions {
  * - set(id, value) → `collections.<collection>.set` with `{ id, value }`
  * - setBatch(items) → `collections.<collection>.setBatch` with `{ items: [{ id, value }] }`
  * - getIds() → `collections.<collection>.ids` with `{}`, or the entries of an older server
+ * - query(selector, options) → `collections.<collection>.find` with `{ selector, sort, skip, limit }`
+ * - patch(id, fields) → `collections.<collection>.patch` with `{ id, fields }`
  * - etc.
  *
  * Before, the class expected a `{ data }` envelope and called `<service>.get`: no core
  * procedure matched, and every read was undefined (deep dive CORE-9, DATA-9).
  *
+ * The retries wait with `backoffDelay` of `@mark1russell7/service/backoff` on the clock of the
+ * options, with full jitter by default. Before, the waits had no jitter, and they used the timers of the platform directly.
+ *
  * @example
  * ```typescript
  * // Create API storage
@@ -101,6 +143,7 @@ export interface ApiStorageOptions {
  * // Operations are automatically sent to server
  * await storage.set("123", { name: "John" });
  * const user = await storage.get("123"); // Fetched from server
+ * const admins = await storage.query({ role: "admin" }, { sort: { name: 1 }, limit: 50 }); // Runs on the server
  * ```
  */
 export declare class ApiStorage<T> implements CollectionStorage<T> {
@@ -109,6 +152,8 @@ export declare class ApiStorage<T> implements CollectionStorage<T> {
     private closed;
     /** True when the server does not know the procedure `ids`: `getIds()` reads the entries */
     private idsUnsupported;
+    /** True when the server does not know the procedure `find`: `query()` reads the entries */
+    private findUnsupported;
     constructor(client: Client, options: ApiStorageOptions);
     /**
      * The item of an id. For the core collection procedures, the call asks for `{ found, value }`,
@@ -131,14 +176,38 @@ export declare class ApiStorage<T> implements CollectionStorage<T> {
      * `getEntries()`.
      */
     getChangesSince(since?: string): Promise<StorageChanges<T>>;
+    /**
+     * The items for which the predicate gives true. A function cannot go over the network, so this
+     * method reads all items and filters here. `query()` sends a JSON selector to the server.
+     */
     find(predicate: (item: T) => boolean): Promise<T[]>;
+    /**
+     * The entries whose items match the selector, from the `find` procedure of the collection: the
+     * server runs the selector, the order, the skip and the limit (roadmap CLI-14), under its own
+     * query policy. An older server without the procedure answers `NOT_FOUND`. Then this call and
+     * each later call read the entries and run the query here, with the same result.
+     *
+     * @param policy - The policy that the storage applies before it sends the query. The default is
+     *   the option `queryPolicy`. The server applies its own policy too.
+     */
+    query(selector: StorageSelector, options?: StorageQueryOptions, policy?: StorageQueryPolicy): Promise<Array<[string, T]>>;
     has(id: string): Promise<boolean>;
     size(): Promise<number>;
-    set(id: string, value: T): Promise<void>;
-    delete(id: string): Promise<boolean>;
-    clear(): Promise<void>;
-    setBatch(items: Array<[string, T]>): Promise<void>;
-    deleteBatch(ids: string[]): Promise<number>;
+    /**
+     * This method sets an item on the server. The origin of the options goes to the procedure `set`,
+     * so the storage of the server and the change event of the write have it (roadmap CLI-15).
+     */
+    set(id: string, value: T, options?: StorageWriteOptions): Promise<void>;
+    delete(id: string, options?: StorageWriteOptions): Promise<boolean>;
+    clear(options?: StorageWriteOptions): Promise<void>;
+    /**
+     * This method changes an item on the server in one step: the `patch` procedure of the collection
+     * (roadmap CLI-14). The fields are a JSON Merge Patch, or the operations `$set` and `$unset`.
+     * It gives the new item, or undefined for a missing id.
+     */
+    patch(id: string, fields: StoragePatch, options?: StorageWriteOptions): Promise<T | undefined>;
+    setBatch(items: Array<[string, T]>, options?: StorageWriteOptions): Promise<void>;
+    deleteBatch(ids: string[], options?: StorageWriteOptions): Promise<number>;
     getBatch(ids: string[]): Promise<Map<string, T>>;
     /**
      * This method closes the storage. After it, each operation rejects, and a second `close()` does
@@ -147,8 +216,12 @@ export declare class ApiStorage<T> implements CollectionStorage<T> {
      */
     close(): Promise<void>;
     getMetadata(): Promise<StorageMetadata>;
+    /** The field `origin` of a write input, or no field: a custom service gets no origin. */
+    private originOf;
     /**
-     * Make an RPC call via the universal client, with the timeout, the signal and the retries.
+     * Make an RPC call via the universal client, with the timeout, the signal and the retries. The
+     * wait before retry `n` is `backoffDelay(backoff, n)`, or the wait that the error asks for when
+     * it is longer.
      */
     private call;
     /** One attempt: the call ends at the timeout, or when the signal of the options aborts. */

package/dist/storage/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/storage/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/storage/api.ts"],"names":[],"mappings":"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"}