@procedures/collections 0.7.0 → 0.8.1

package/dist/storage/interface.d.ts

@@ -1,15 +1,18 @@
 /**
- * Collection Storage Interface
+ * The interface of the collection storages. These storages implement it:
+ * - `InMemoryStorage` (this package): a fast storage in a `Map`, in memory only.
+ * - `ApiStorage` (`@procedures/store`): a remote collection through a `Client`.
+ * - `HybridStorage` (`@procedures/store`): a local copy that syncs with a remote, with a
+ *   conflict policy and a queue of the local writes.
+ * - `MongoStorage` (`@procedures/mongo`).
  *
- * Abstract storage layer for collections, enabling different backends:
- * - InMemoryStorage: Fast, volatile storage using Map
- * - ApiStorage: Remote persistence via universal client
- * - HybridStorage: Local cache + remote sync with conflict resolution
- * - SyncedStorage: Periodic background sync with offline support
+ * `@procedures/client` declares a copy of this interface with the same shape, so that the core
+ * does not depend on this package. `SqliteStorage` (`@procedures/sqlite`) implements that copy.
  *
- * IMPORTANT: All methods return Promise to ensure client code is
- * transport-agnostic (cannot distinguish local from remote storage).
+ * Each method gives a `Promise`. Thus the code of a caller cannot tell a local storage from a
+ * remote storage.
  */
+import type { StoragePatch, StorageQueryOptions, StorageQueryPolicy, StorageSelector } from "@procedures/client/query";
 /**
  * Storage backend interface for collections.
  *
@@ -25,6 +28,11 @@
  * - A delta of `getChangesSince` follows the order of the last change of each id.
  * - After `close()`, each operation rejects with an error whose message says "closed". A second
  *   `close()` does nothing.
+ * - `query()` gives the result of `queryEntries()` for the entries of the storage.
+ * - `observe()` gives one batch for each write that changes the storage, before the write resolves.
+ * - `patch()` changes the item in one step: two patches at the same time keep each field.
+ *
+ * The optional methods are features: a caller tests for each one before it uses it.
  */
 export interface CollectionStorage<T> {
     /**
@@ -71,6 +79,35 @@ export interface CollectionStorage<T> {
      * @returns Promise resolving to array of matching items
      */
     find(predicate: (item: T) => boolean): Promise<T[]>;
+    /**
+     * The entries whose items match a selector, with an order, a skip and a limit. The selector is
+     * JSON, so a remote storage sends it to its server, and a database can run it itself. The result
+     * is the result of `queryEntries()` for the entries of the storage. A storage without this method
+     * does not run selectors: a caller uses `queryEntries()` on the entries.
+     *
+     * @param selector - The selector. `{}` matches each item.
+     * @param options - The order, the skip and the limit
+     * @param policy - The query policy of the caller: the procedure `find` gives the policy of the
+     *   host. Without it, the storage uses its own policy. The default policy does not permit `$regex`.
+     * @returns Promise resolving to the [id, item] pairs, with copies of the items. A selector or
+     *   options with a problem, or that the policy does not permit, reject with a `TypeError`.
+     */
+    query?(selector: StorageSelector, options?: StorageQueryOptions, policy?: StorageQueryPolicy): Promise<Array<[string, T]>>;
+    /**
+     * This method starts to send the changes of the storage to an observer. Each write that changes
+     * the storage gives one batch, before the write resolves. A write that changes nothing gives no
+     * batch. A storage without this method does not tell its changes.
+     *
+     * - A set gives a `set` change with a copy of the value. A patch gives a `set` change with the new item.
+     * - A delete gives a `delete` change for each id that existed.
+     * - A clear of a storage with items gives one `clear` change.
+     * - Each change has the `origin` of the write options, or no origin.
+     *
+     * @param observer - The function that gets each batch. Its error does not change the write.
+     * @returns The function that stops the batches. A second use of it does nothing.
+     * @throws Error after `close()`
+     */
+    observe?(observer: StorageObserver<T>): () => void;
     /**
      * Check if item exists.
      *
@@ -89,36 +126,55 @@ export interface CollectionStorage<T> {
      *
      * @param id - Item identifier
      * @param value - Item to store
+     * @param options - The origin of the write, for the observers
      * @returns Promise resolving when operation completes
      */
-    set(id: string, value: T): Promise<void>;
+    set(id: string, value: T, options?: StorageWriteOptions): Promise<void>;
     /**
      * Delete item by ID.
      *
      * @param id - Item identifier
+     * @param options - The origin of the write, for the observers
      * @returns Promise resolving to true if item was deleted, false if not found
      */
-    delete(id: string): Promise<boolean>;
+    delete(id: string, options?: StorageWriteOptions): Promise<boolean>;
     /**
      * Clear all items from collection.
      *
+     * @param options - The origin of the write, for the observers
      * @returns Promise resolving when operation completes
      */
-    clear(): Promise<void>;
+    clear(options?: StorageWriteOptions): Promise<void>;
+    /**
+     * This method changes one item in one step. The fields are a JSON Merge Patch (RFC 7386): each
+     * field replaces the field of the item, an object field merges into an object field, and `null`
+     * removes the field. Or they are the operations `{ $set, $unset }`: `$set` can set `null` and
+     * nested field paths. Two patches of one item at the same time keep the fields of each. A storage
+     * without this method cannot change an item in one step.
+     *
+     * @param id - Item identifier
+     * @param fields - The fields: an object of one form. Another value rejects with a `TypeError`.
+     * @param options - The origin of the write, for the observers
+     * @returns Promise resolving to a copy of the new item, or undefined when the id has no item. A
+     *   missing id stays missing.
+     */
+    patch?(id: string, fields: StoragePatch, options?: StorageWriteOptions): Promise<T | undefined>;
     /**
      * Set multiple items at once (more efficient than individual sets).
      *
      * @param items - Array of [id, value] tuples
+     * @param options - The origin of the write, for the observers
      * @returns Promise resolving when operation completes
      */
-    setBatch(items: Array<[string, T]>): Promise<void>;
+    setBatch(items: Array<[string, T]>, options?: StorageWriteOptions): Promise<void>;
     /**
      * Delete multiple items at once.
      *
      * @param ids - Array of item identifiers
+     * @param options - The origin of the write, for the observers
      * @returns Promise resolving to number of items actually deleted
      */
-    deleteBatch(ids: string[]): Promise<number>;
+    deleteBatch(ids: string[], options?: StorageWriteOptions): Promise<number>;
     /**
      * Get multiple items by ID at once.
      *
@@ -149,6 +205,42 @@ export interface CollectionStorage<T> {
      */
     getMetadata?(): Promise<StorageMetadata>;
 }
+/** The options of a write. */
+export interface StorageWriteOptions {
+    /**
+     * The tag of the writer. Each change that the write gives has it, so an observer knows its own
+     * writes: a sync does not send back the changes that it wrote itself.
+     */
+    readonly origin?: string | undefined;
+}
+/** A change of `observe()`: an id got a value. */
+export interface StorageSetChange<T> {
+    readonly type: "set";
+    readonly id: string;
+    /** A copy of the new item. */
+    readonly value: T;
+    /** The origin of the write, or undefined when the write had none. */
+    readonly origin?: string | undefined;
+}
+/** A change of `observe()`: an id lost its item. */
+export interface StorageDeleteChange {
+    readonly type: "delete";
+    readonly id: string;
+    /** The origin of the write, or undefined when the write had none. */
+    readonly origin?: string | undefined;
+}
+/** A change of `observe()`: the storage lost each item. */
+export interface StorageClearChange {
+    readonly type: "clear";
+    /** The origin of the write, or undefined when the write had none. */
+    readonly origin?: string | undefined;
+}
+/** One change of `observe()`. */
+export type StorageChangeEvent<T> = StorageSetChange<T> | StorageDeleteChange | StorageClearChange;
+/** The changes of one write, in the order of the write. The observers share it: do not change it. */
+export type StorageChangeBatch<T> = readonly StorageChangeEvent<T>[];
+/** The function that gets each batch of `observe()`. */
+export type StorageObserver<T> = (changes: StorageChangeBatch<T>) => void;
 /**
  * The changes of a storage after a version (roadmap R28).
  *

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

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

package/dist/storage/interface.js

@@ -1,14 +1,16 @@
 /**
- * Collection Storage Interface
+ * The interface of the collection storages. These storages implement it:
+ * - `InMemoryStorage` (this package): a fast storage in a `Map`, in memory only.
+ * - `ApiStorage` (`@procedures/store`): a remote collection through a `Client`.
+ * - `HybridStorage` (`@procedures/store`): a local copy that syncs with a remote, with a
+ *   conflict policy and a queue of the local writes.
+ * - `MongoStorage` (`@procedures/mongo`).
  *
- * Abstract storage layer for collections, enabling different backends:
- * - InMemoryStorage: Fast, volatile storage using Map
- * - ApiStorage: Remote persistence via universal client
- * - HybridStorage: Local cache + remote sync with conflict resolution
- * - SyncedStorage: Periodic background sync with offline support
+ * `@procedures/client` declares a copy of this interface with the same shape, so that the core
+ * does not depend on this package. `SqliteStorage` (`@procedures/sqlite`) implements that copy.
  *
- * IMPORTANT: All methods return Promise to ensure client code is
- * transport-agnostic (cannot distinguish local from remote storage).
+ * Each method gives a `Promise`. Thus the code of a caller cannot tell a local storage from a
+ * remote storage.
  */
 /**
  * @deprecated All storage methods now return Promise.

package/dist/storage/interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/storage/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkOH;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAI,KAAiB;IACzD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/storage/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAwUH;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAI,KAAiB;IACzD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/storage/listeners.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A set of listeners for the events of a storage: the change batches of `observe()`, or the status
+ * of a sync. A storage package uses it, so each storage treats its listeners in the same way.
+ */
+/** The function that gets the error of a listener. */
+export type ListenerErrorHandler = (error: unknown) => void;
+/**
+ * The default handler of the error of a listener. It throws the error again in a microtask, as an
+ * `EventTarget` reports the error of a listener. Thus the error is not lost, and the write that
+ * sent the event does not fail.
+ */
+export declare const reportListenerError: ListenerErrorHandler;
+/**
+ * The listeners of one kind of event.
+ *
+ * - `emit()` gives the event to each listener, in the order of `add()`.
+ * - A listener that `add()` gets during an `emit()` gets the next event, not this one.
+ * - The error of a listener goes to the error handler. The other listeners get the event.
+ * - The same function can be added two times. Each `add()` gives its own function that removes it.
+ */
+export declare class StorageListeners<E> {
+    private readonly listeners;
+    private readonly onError;
+    /** @param onError - The function that gets the error of a listener. The default is `reportListenerError`. */
+    constructor(onError?: ListenerErrorHandler);
+    /** The number of listeners. */
+    get size(): number;
+    /**
+     * This method adds a listener.
+     *
+     * @returns The function that removes the listener. A second use of it does nothing.
+     */
+    add(listener: (event: E) => void): () => void;
+    /** This method gives the event to each listener. */
+    emit(event: E): void;
+    /** This method removes each listener. */
+    clear(): void;
+}
+//# sourceMappingURL=listeners.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../src/storage/listeners.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,sDAAsD;AACtD,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,oBAIjC,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,gBAAgB,CAAC,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwD;IAClF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAE/C,6GAA6G;IAC7G,YAAY,OAAO,GAAE,oBAA0C,EAE9D;IAED,+BAA+B;IAC/B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACH,GAAG,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAM5C;IAED,oDAAoD;IACpD,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAUnB;IAED,yCAAyC;IACzC,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/storage/listeners.js

@@ -0,0 +1,65 @@
+/**
+ * A set of listeners for the events of a storage: the change batches of `observe()`, or the status
+ * of a sync. A storage package uses it, so each storage treats its listeners in the same way.
+ */
+/**
+ * The default handler of the error of a listener. It throws the error again in a microtask, as an
+ * `EventTarget` reports the error of a listener. Thus the error is not lost, and the write that
+ * sent the event does not fail.
+ */
+export const reportListenerError = (error) => {
+    queueMicrotask(() => {
+        throw error;
+    });
+};
+/**
+ * The listeners of one kind of event.
+ *
+ * - `emit()` gives the event to each listener, in the order of `add()`.
+ * - A listener that `add()` gets during an `emit()` gets the next event, not this one.
+ * - The error of a listener goes to the error handler. The other listeners get the event.
+ * - The same function can be added two times. Each `add()` gives its own function that removes it.
+ */
+export class StorageListeners {
+    listeners = new Set();
+    onError;
+    /** @param onError - The function that gets the error of a listener. The default is `reportListenerError`. */
+    constructor(onError = reportListenerError) {
+        this.onError = onError;
+    }
+    /** The number of listeners. */
+    get size() {
+        return this.listeners.size;
+    }
+    /**
+     * This method adds a listener.
+     *
+     * @returns The function that removes the listener. A second use of it does nothing.
+     */
+    add(listener) {
+        const entry = { listener };
+        this.listeners.add(entry);
+        return () => {
+            this.listeners.delete(entry);
+        };
+    }
+    /** This method gives the event to each listener. */
+    emit(event) {
+        for (const entry of [...this.listeners]) {
+            // A listener that a listener before it removed gets no event
+            if (!this.listeners.has(entry))
+                continue;
+            try {
+                entry.listener(event);
+            }
+            catch (error) {
+                this.onError(error);
+            }
+        }
+    }
+    /** This method removes each listener. */
+    clear() {
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=listeners.js.map

package/dist/storage/listeners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.js","sourceRoot":"","sources":["../../src/storage/listeners.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAyB,CAAC,KAAK,EAAE,EAAE;IACjE,cAAc,CAAC,GAAG,EAAE;QAClB,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,OAAO,gBAAgB;IACV,SAAS,GAAG,IAAI,GAAG,EAA6C,CAAC;IACjE,OAAO,CAAuB;IAE/C,6GAA6G;IAC7G,YAAY,OAAO,GAAyB,mBAAmB;QAC7D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,+BAA+B;IAC/B,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,QAA4B;QAC9B,MAAM,KAAK,GAAG,EAAE,QAAQ,EAAE,CAAC;QAC3B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC,CAAC;IACJ,CAAC;IAED,oDAAoD;IACpD,IAAI,CAAC,KAAQ;QACX,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACxC,6DAA6D;YAC7D,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,SAAS;YACzC,IAAI,CAAC;gBACH,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAED,yCAAyC;IACzC,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/storage/memory.d.ts

@@ -4,9 +4,23 @@
  * Fast, volatile storage using JavaScript Map.
  * All operations return Promises for interface consistency.
  */
-import type { CollectionStorage, StorageChanges, StorageMetadata } from "./interface.js";
+import type { CollectionStorage, StorageChanges, StorageMetadata, StorageObserver, StorageWriteOptions } from "./interface.js";
+import { type ListenerErrorHandler } from "./listeners.js";
+import { type StoragePatch, type StorageQueryOptions, type StorageQueryPolicy, type StorageSelector } from "@procedures/client/query";
 /** Options of an in-memory storage. */
 export interface InMemoryStorageOptions {
+    /**
+     * The function that gets the error of an observer of `observe()`. The default throws the error
+     * again in a microtask (`reportListenerError`). The write and the other observers do not fail.
+     */
+    onObserverError?: ListenerErrorHandler | 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. A storage that gets selectors of callers that it
+     * does not trust keeps the default.
+     * @default DEFAULT_QUERY_POLICY: no `$regex`
+     */
+    queryPolicy?: StorageQueryPolicy | undefined;
     /**
      * The number of deletes that the change log keeps (roadmap R28). After more deletes, the log
      * drops the oldest ones, and `getChangesSince` of an older version gives all items.
@@ -37,6 +51,8 @@ export interface InMemoryStorageOptions {
  * - Copies: a change of a written or a read value does not change the stored item (the option
  *   `copies: false` turns this off)
  * - `getIds()` gives the ids without a copy of the values
+ * - `query()` runs a selector, `observe()` tells each change with the origin of its write, and
+ *   `patch()` merges fields into an item in one step
  * - After `close()`, each operation rejects, and a second `close()` does nothing
  *
  * @example
@@ -59,6 +75,10 @@ export declare class InMemoryStorage<T> implements CollectionStorage<T> {
     private readonly maxTombstones;
     private readonly copy;
     private closed;
+    /** The observers of `observe()` */
+    private readonly observers;
+    /** The query policy of a call without a policy */
+    private readonly queryPolicy;
     constructor(options?: InMemoryStorageOptions);
     get(id: string): Promise<T | undefined>;
     getAll(): Promise<T[]>;
@@ -73,14 +93,32 @@ export declare class InMemoryStorage<T> implements CollectionStorage<T> {
     getChangesSince(since?: string): Promise<StorageChanges<T>>;
     /** The items for which the predicate gives true. The predicate gets a copy of each item. */
     find(predicate: (item: T) => boolean): Promise<T[]>;
+    /**
+     * The entries whose items match the selector, with the order, the skip and the limit of
+     * `queryEntries()`, under the policy of the call or of the options. The result has copies of the
+     * items.
+     */
+    query(selector: StorageSelector, options?: StorageQueryOptions, policy?: StorageQueryPolicy): Promise<Array<[string, T]>>;
+    /**
+     * This method starts to send the changes of each write to the observer, before the write resolves.
+     * The values of the changes are copies, unless the option `copies` is false. The observers share
+     * each batch.
+     */
+    observe(observer: StorageObserver<T>): () => void;
     has(id: string): Promise<boolean>;
     size(): Promise<number>;
-    set(id: string, value: T): Promise<void>;
-    delete(id: string): Promise<boolean>;
-    clear(): Promise<void>;
+    set(id: string, value: T, options?: StorageWriteOptions): Promise<void>;
+    delete(id: string, options?: StorageWriteOptions): Promise<boolean>;
+    clear(options?: StorageWriteOptions): Promise<void>;
+    /**
+     * This method changes the item of the id in one step (a JSON Merge Patch, or the operations
+     * `$set` and `$unset`), and gives a copy of the new item. A missing id stays missing, and the
+     * result is undefined. A patch that cannot apply to the item changes nothing.
+     */
+    patch(id: string, fields: StoragePatch, options?: StorageWriteOptions): Promise<T | undefined>;
     /** This method sets several items. When one value has no copy, nothing changes. */
-    setBatch(items: Array<[string, T]>): Promise<void>;
-    deleteBatch(ids: string[]): Promise<number>;
+    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 and drops its items. After it, each operation rejects (and
@@ -121,6 +159,8 @@ export declare class InMemoryStorage<T> implements CollectionStorage<T> {
     private checkOpen;
     /** The entries with copies of the values. */
     private copiedEntries;
+    /** The `set` change of a stored value: a copy of it for the observers. */
+    private setChange;
     /** A set moves the id to the end of the order of the log: the order of the last change. */
     private noteSet;
     private noteDelete;

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

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

package/dist/storage/memory.js

@@ -4,12 +4,18 @@
  * Fast, volatile storage using JavaScript Map.
  * All operations return Promises for interface consistency.
  */
+import { StorageListeners } from "./listeners.js";
+import { applyPatch, patchProblems, queryEntries, } from "@procedures/client/query";
 /** A new epoch: a version of another storage does not match it. */
 function newEpoch() {
     return Math.random().toString(36).slice(2, 10);
 }
 const same = (value) => value;
 const clone = (value) => structuredClone(value);
+/** A change with the origin of the write, when the write has one. */
+function withOrigin(change, options) {
+    return options?.origin === undefined ? change : { ...change, origin: options.origin };
+}
 /**
  * In-memory storage backed by JavaScript Map.
  *
@@ -23,6 +29,8 @@ const clone = (value) => structuredClone(value);
  * - Copies: a change of a written or a read value does not change the stored item (the option
  *   `copies: false` turns this off)
  * - `getIds()` gives the ids without a copy of the values
+ * - `query()` runs a selector, `observe()` tells each change with the origin of its write, and
+ *   `patch()` merges fields into an item in one step
  * - After `close()`, each operation rejects, and a second `close()` does nothing
  *
  * @example
@@ -47,9 +55,15 @@ export class InMemoryStorage {
     maxTombstones;
     copy;
     closed = false;
+    /** The observers of `observe()` */
+    observers;
+    /** The query policy of a call without a policy */
+    queryPolicy;
     constructor(options = {}) {
         this.maxTombstones = Math.max(0, options.maxTombstones ?? 10_000);
         this.copy = options.copies === false ? same : clone;
+        this.observers = new StorageListeners(options.onObserverError);
+        this.queryPolicy = options.queryPolicy;
     }
     //
     // ═══ Read Operations ═══
@@ -107,6 +121,24 @@ export class InMemoryStorage {
         }
         return results;
     }
+    /**
+     * The entries whose items match the selector, with the order, the skip and the limit of
+     * `queryEntries()`, under the policy of the call or of the options. The result has copies of the
+     * items.
+     */
+    async query(selector, options, policy) {
+        this.checkOpen();
+        return queryEntries(this.data, selector, options, policy ?? this.queryPolicy).map(([id, value]) => [id, this.copy(value)]);
+    }
+    /**
+     * This method starts to send the changes of each write to the observer, before the write resolves.
+     * The values of the changes are copies, unless the option `copies` is false. The observers share
+     * each batch.
+     */
+    observe(observer) {
+        this.checkOpen();
+        return this.observers.add(observer);
+    }
     async has(id) {
         this.checkOpen();
         return this.data.has(id);
@@ -118,46 +150,80 @@ export class InMemoryStorage {
     //
     // ═══ Write Operations ═══
     //
-    async set(id, value) {
+    async set(id, value, options) {
         this.checkOpen();
-        this.data.set(id, this.copy(value));
+        const stored = this.copy(value);
+        this.data.set(id, stored);
         this.noteSet(id);
+        if (this.observers.size > 0)
+            this.observers.emit([this.setChange(id, stored, options)]);
     }
-    async delete(id) {
+    async delete(id, options) {
         this.checkOpen();
         const existed = this.data.delete(id);
-        if (existed)
+        if (existed) {
             this.noteDelete(id);
+            if (this.observers.size > 0)
+                this.observers.emit([withOrigin({ type: "delete", id }, options)]);
+        }
         return existed;
     }
-    async clear() {
+    async clear(options) {
         this.checkOpen();
+        const had = this.data.size > 0;
         for (const id of this.data.keys())
             this.noteDelete(id);
         this.data.clear();
+        if (had && this.observers.size > 0)
+            this.observers.emit([withOrigin({ type: "clear" }, options)]);
+    }
+    /**
+     * This method changes the item of the id in one step (a JSON Merge Patch, or the operations
+     * `$set` and `$unset`), and gives a copy of the new item. A missing id stays missing, and the
+     * result is undefined. A patch that cannot apply to the item changes nothing.
+     */
+    async patch(id, fields, options) {
+        this.checkOpen();
+        const [problem] = patchProblems(fields);
+        if (problem !== undefined)
+            throw new TypeError(`The patch of ${id} is not correct: ${problem}`);
+        if (!this.data.has(id))
+            return undefined;
+        const stored = this.copy(applyPatch(this.data.get(id), fields));
+        this.data.set(id, stored);
+        this.noteSet(id);
+        if (this.observers.size > 0)
+            this.observers.emit([this.setChange(id, stored, options)]);
+        return this.copy(stored);
     }
     //
     // ═══ Bulk Operations ═══
     //
     /** This method sets several items. When one value has no copy, nothing changes. */
-    async setBatch(items) {
+    async setBatch(items, options) {
         this.checkOpen();
         const copies = items.map(([id, value]) => [id, this.copy(value)]);
         for (const [id, value] of copies) {
             this.data.set(id, value);
             this.noteSet(id);
         }
+        if (copies.length > 0 && this.observers.size > 0) {
+            this.observers.emit(copies.map(([id, value]) => this.setChange(id, value, options)));
+        }
     }
-    async deleteBatch(ids) {
+    async deleteBatch(ids, options) {
         this.checkOpen();
-        let deleted = 0;
+        const deleted = [];
         for (const id of ids) {
             if (this.data.delete(id)) {
                 this.noteDelete(id);
-                deleted++;
+                deleted.push(id);
             }
         }
-        return deleted;
+        if (deleted.length > 0 && this.observers.size > 0) {
+            this.observers.emit(deleted.map((id) => withOrigin({ type: "delete", id }, options)));
+        }
+        return deleted.length;
     }
     async getBatch(ids) {
         this.checkOpen();
@@ -184,6 +250,7 @@ export class InMemoryStorage {
         this.data.clear();
         this.changedAt.clear();
         this.deletedAt.clear();
+        this.observers.clear();
     }
     async getMetadata() {
         this.checkOpen();
@@ -257,6 +324,10 @@ export class InMemoryStorage {
     copiedEntries() {
         return Array.from(this.data, ([id, value]) => [id, this.copy(value)]);
     }
+    /** The `set` change of a stored value: a copy of it for the observers. */
+    setChange(id, stored, options) {
+        return withOrigin({ type: "set", id, value: this.copy(stored) }, options);
+    }
     //
     // ═══ The change log ═══
     //