@procedures/signaldb 0.0.0-stage → 0.24.1

package/dist/storage.d.ts

@@ -0,0 +1,224 @@
+/**
+ * A collection storage over the SignalDB collection of an app (roadmap CLI-23, server stack D9).
+ *
+ * The app owns the SignalDB `Collection`: its persistence, its indexes, its cursors and its
+ * reactivity. `SignalDbStorage` reads and writes the items of that collection through the
+ * `CollectionStorage` contract. Thus the collection is the local copy of a `HybridStorage`, and
+ * the `HybridStorage` owns the sync: the queue, the sync state and the remote.
+ *
+ * The rules:
+ * - Each operation waits for the load of the persistence of the collection (`isReady()`). A failed
+ *   load does not stop the storage: the collection then keeps its items in memory, as SignalDB does.
+ * - A write of SignalDB is synchronous. Each write of the storage reads, tests and writes in one
+ *   synchronous step. Thus two writes do not mix, and a patch and a precondition are atomic.
+ * - A write of several items is one `batch()` of the collection: the indexes and the cursors update
+ *   one time. The validators of the collection examine each item before the first write. Thus an
+ *   item that a validator refuses changes nothing.
+ * - Each write takes a copy of its value, and each read gives a new copy. A cursor of SignalDB gives
+ *   copies (`structuredClone`) of the items, and the storage reads only through cursors.
+ * - `observe()` gives the batches of the writes of the storage, with their origins. It also gives
+ *   each change that the app makes directly on the collection: one batch for each change, with no
+ *   origin. Thus a `HybridStorage` with `capture: "observe"` sends the writes of the app.
+ * - `query()` applies `queryEntries()` to the values. It does not give the selector to SignalDB.
+ *   SignalDB applies Mongo selectors to the items with `mingo`. The contract needs the query
+ *   language of the client on the values.
+ * - `close()` stops the storage. The collection stays open, with its items: the app disposes it.
+ *
+ * The limits:
+ * - A load of the persistence (`persistence.received`) changes the items without the events of a
+ *   change. `observe()` thus does not tell it. The order of the entries after a load is the order of
+ *   the persistence adapter.
+ * - The collection must not have a `transform`: the storage reads the items through cursors.
+ * - Each id is a string. An item of the collection whose `id` is not a string is an error.
+ * - The storage keeps no change log, so it has no `getChangesSince()`. A cursor copies each item,
+ *   so the storage has no cheap `getIds()` either.
+ * - A listener of the app that throws in a write of the storage stops the write, and the write
+ *   rejects. SignalDB keeps the changes before the error. The observers get the changes that the
+ *   storage knows.
+ */
+import type { Collection } from "@signaldb/core";
+import type { CollectionStorage, StorageBatchWriteOptions, StorageItemWriteOptions, StorageMetadata, StorageObserver, StorageWriteOptions } from "@procedures/collections";
+import { type ListenerErrorHandler } from "@procedures/collections";
+import { type StoragePatch, type StorageQueryOptions, type StorageQueryPolicy, type StorageSelector } from "@procedures/client/query";
+import { type SignalDbItemCodec } from "./codec.js";
+/**
+ * A SignalDB collection of any item type. The storage reads the items as they are in memory, so the
+ * collection must not have a `transform`.
+ */
+export type SignalDbCollection = Collection<any, any, any, any>;
+/** The options of a `SignalDbStorage`. */
+export interface SignalDbStorageOptions<T = unknown> {
+    /**
+     * The change of a value to an item of the collection and back.
+     * @default documentCodec(): a document whose `id` is its key is the item, and each other value goes into an envelope
+     */
+    codec?: SignalDbItemCodec<T> | undefined;
+    /**
+     * The query policy of `query()` for a call without a policy: the operators and the limits. The
+     * procedure `find` gives the policy of its host.
+     * @default DEFAULT_QUERY_POLICY: no `$regex`
+     */
+    queryPolicy?: StorageQueryPolicy | undefined;
+    /**
+     * The version of a value, for example `(item) => item.rev` (roadmap CLI-16). With it, `set`,
+     * `delete` and `setBatch` take an expected version: a write whose current value has another
+     * version changes nothing and rejects with `VersionConflictError`. Without it, a write with an
+     * expected version rejects with a `TypeError`. Give the `versionOf` of the `HybridStorage` to its
+     * local copy.
+     */
+    versionOf?: ((item: T) => string | undefined) | undefined;
+    /**
+     * The function that gets the error of an observer of `observe()`, and the error of a change of
+     * the app that the storage cannot read. The default throws the error again in a microtask
+     * (`reportListenerError`). The write and the other observers do not fail.
+     */
+    onObserverError?: ListenerErrorHandler | undefined;
+}
+/**
+ * A collection storage over the SignalDB collection of an app (roadmap CLI-23).
+ *
+ * - The collection keeps the items. The storage keeps nothing of its own, and a new storage of the
+ *   same collection reads the same items.
+ * - `observe()` tells the writes of the storage and the changes that the app makes on the collection.
+ * - `query()` applies a selector, and `patch()` changes an item in one step.
+ * - After `close()`, each operation rejects, and a second `close()` does nothing.
+ *
+ * @example
+ * ```typescript
+ * import { Collection } from "@signaldb/core";
+ * import { ApiStorage, HybridStorage } from "@procedures/store/browser";
+ * import { SignalDbStorage } from "@procedures/signaldb";
+ *
+ * const todos = new Collection<Todo>({ persistence: createIndexedDBAdapter("todos") });
+ * const storage = new HybridStorage<Todo>(new ApiStorage(client, { collection: "todos" }), {
+ *   mode: "write-back",
+ *   local: new SignalDbStorage<Todo>(todos),
+ *   capture: "observe",
+ * });
+ * todos.insert({ id: "t1", title: "Write the docs" }); // the storage sends it to the server
+ * ```
+ */
+export declare class SignalDbStorage<T> implements CollectionStorage<T> {
+    private readonly collection;
+    private readonly codec;
+    /** The query policy of a call without a policy */
+    private readonly queryPolicy;
+    /** The version of a value, for the preconditions of the writes (roadmap CLI-16) */
+    private readonly versionOf;
+    private readonly onObserverError;
+    /** The observers of `observe()` */
+    private readonly observers;
+    /** The load of the persistence of the collection. A failed load also resolves. */
+    private readonly ready;
+    /** True while a write of this storage runs: its events are not changes of the app */
+    private writing;
+    /** True while the storage listens to the events of the collection */
+    private listening;
+    private closed;
+    /**
+     * @param collection - The SignalDB collection of the app. The app owns it, and `close()` does not dispose it.
+     * @param options - The codec, the query policy, `versionOf` and the handler of the errors of the observers.
+     */
+    constructor(collection: SignalDbCollection, options?: SignalDbStorageOptions<T>);
+    /** The name of the collection. */
+    get name(): string;
+    get(id: string): Promise<T | undefined>;
+    getAll(): Promise<T[]>;
+    /** Every item with its id, in the order of the collection: the order of the first set of each id. */
+    getEntries(): Promise<Array<[string, T]>>;
+    /** The items for which the predicate gives true, in the order of the entries. The predicate gets a copy of each item. */
+    find(predicate: (item: T) => boolean): Promise<T[]>;
+    /**
+     * The entries whose values match the selector, with the order, the skip and the limit of
+     * `queryEntries()`. The policy is the policy of the call, or else of the options. A query that is
+     * not correct rejects with a `TypeError` before the storage reads the collection.
+     */
+    query(selector: StorageSelector, options?: StorageQueryOptions, policy?: StorageQueryPolicy): Promise<Array<[string, T]>>;
+    /**
+     * This method starts to send the changes of the collection to the observer.
+     *
+     * - A write of this storage gives one batch, with the origin of its options, before the write resolves.
+     * - A change that the app makes directly on the collection gives one batch with one change and no
+     *   origin, at once. Examples are `insert`, `updateOne`, `replaceOne` and `removeOne`.
+     * - The observers share each batch. A load of the persistence gives no batch.
+     *
+     * @returns The function that stops the batches. A second use of it does nothing.
+     * @throws Error after `close()`
+     */
+    observe(observer: StorageObserver<T>): () => void;
+    has(id: string): Promise<boolean>;
+    size(): Promise<number>;
+    set(id: string, value: T, options?: StorageItemWriteOptions): Promise<void>;
+    delete(id: string, options?: StorageItemWriteOptions): Promise<boolean>;
+    /** This method deletes each item of the collection in one batch. A collection with items gives one `clear` change. */
+    clear(options?: StorageWriteOptions): Promise<void>;
+    /**
+     * This method changes the item of the id in one step (a JSON Merge Patch, or the operations
+     * `$set`, `$unset`, `$remove` and `$insert`), and gives a copy of the new item. A missing id stays
+     * missing, and the result is undefined.
+     */
+    patch(id: string, fields: StoragePatch, options?: StorageWriteOptions): Promise<T | undefined>;
+    /**
+     * This method sets several items in one batch of the collection. When one expected version has a
+     * conflict, or a validator of the collection refuses one item, nothing changes.
+     */
+    setBatch(items: Array<[string, T]>, options?: StorageBatchWriteOptions): Promise<void>;
+    /** This method deletes several items in one batch of the collection. */
+    deleteBatch(ids: string[], options?: StorageWriteOptions): Promise<number>;
+    getBatch(ids: string[]): Promise<Map<string, T>>;
+    /**
+     * This method stops the storage. The collection stays open, with its items: a new storage of the
+     * collection reads them. After `close()`, each operation rejects, and a second `close()` does nothing.
+     */
+    close(): Promise<void>;
+    getMetadata(): Promise<StorageMetadata>;
+    /** This method throws after `close()`. In an async method, the throw rejects the promise. */
+    private checkOpen;
+    /** This method waits for the load of the persistence. A close during the wait rejects. */
+    private whenReady;
+    private problem;
+    /** The id and the value of an item that a cursor gave. An item without a string id throws. */
+    private entryOf;
+    /** The current value of an id: a copy. */
+    private current;
+    /** The item of a value. The codec must give a plain object with the id. */
+    private itemOf;
+    /** A write of a value: a copy of the value, and its item. */
+    private prepare;
+    /** This method writes an item. An existing id keeps its place in the order of the entries. */
+    private put;
+    /** This method deletes the item of an id. True when the item existed. */
+    private remove;
+    /**
+     * One write of the storage: `body` reads, tests and writes in one synchronous step. The events of
+     * the collection during the step are not changes of the app. The observers get the changes of the
+     * step after it, also when it fails after a change, with copies of the values.
+     */
+    private write;
+    /**
+     * One batch of the collection. `Collection.batch()` of SignalDB does not end its batch when the
+     * callback throws, so the error leaves the batch first, and the batch ends.
+     */
+    private batch;
+    /**
+     * The preconditions of a write. A storage without `versionOf` throws a `TypeError` before the
+     * write starts (roadmap CLI-16).
+     */
+    private preconditions;
+    /** This method tests the expected versions in the step of the write. A conflict throws `VersionConflictError`. */
+    private checkVersions;
+    private readonly onAdded;
+    private readonly onChanged;
+    private readonly onRemoved;
+    /** This method starts to listen to the changes of the collection. */
+    private listen;
+    /** This method stops to listen to the changes of the collection. */
+    private unlisten;
+    /**
+     * This method gives a change that the app made on the collection to the observers. It does not
+     * throw, because it operates in the write of the app. An item that the storage cannot read goes to
+     * `onObserverError`.
+     */
+    private appChange;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

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