@procedures/store 0.47.2 → 0.48.0

package/src/indexeddb/idb.ts

@@ -142,18 +142,28 @@ export type IdbWork<R> = (transaction: IdbTransactionLike, fail: (error: unknown
  * and a failed open tries again at the next operation.
  */
 export class IdbConnection {
+  /** The name of the database. */
+  readonly database: string;
+  /** The object stores of the database. */
+  private readonly stores: readonly IdbStoreSchema[];
+  private readonly factory: IdbFactoryLike | undefined;
+  /** The function that writes the first records when the open makes the object stores. */
+  private readonly onCreate?: ((store: (name: string) => IdbObjectStoreLike) => void) | undefined;
+
   private connection: Promise<IdbDatabaseLike> | undefined;
   private closed = false;
 
   constructor(
-    /** The name of the database. */
-    readonly database: string,
-    /** The object stores of the database. */
-    private readonly stores: readonly IdbStoreSchema[],
-    private readonly factory: IdbFactoryLike | undefined,
-    /** The function that writes the first records when the open makes the object stores. */
-    private readonly onCreate?: (store: (name: string) => IdbObjectStoreLike) => void,
-  ) {}
+    database: string,
+    stores: readonly IdbStoreSchema[],
+    factory: IdbFactoryLike | undefined,
+    onCreate?: (store: (name: string) => IdbObjectStoreLike) => void,
+  ) {
+    this.database = database;
+    this.stores = stores;
+    this.factory = factory;
+    this.onCreate = onCreate;
+  }
 
   /**
    * This method runs work in one transaction over the object stores of `names`. The promise resolves
@@ -276,16 +286,21 @@ export class IdbConnection {
 
 /** One object store in its own database, version 1. The stores of programs, queues and sync states use it. */
 export class IdbStoreConnection {
+  /** The name of the database. */
+  readonly database: string;
+  /** The name of the object store. */
+  readonly store: string;
+
   private readonly connection: IdbConnection;
 
   constructor(
-    /** The name of the database. */
-    readonly database: string,
-    /** The name of the object store. */
-    readonly store: string,
+    database: string,
+    store: string,
     storeOptions: { keyPath?: string; autoIncrement?: boolean },
     factory: IdbFactoryLike | undefined,
   ) {
+    this.database = database;
+    this.store = store;
     this.connection = new IdbConnection(database, [{ name: store, options: storeOptions }], factory);
   }
 

package/src/program-store/collection.ts

@@ -33,13 +33,17 @@ function nextRevision(version: string | number | null | undefined): string {
 }
 
 export class CollectionProgramStore implements ProgramStore {
+  private readonly storage: CollectionStorage<StoredProgram>;
+
   readonly kind = "collection";
 
   /**
    * @param storage - The storage of the records. The store closes it in `close()`. Give it the
    *   option `versionOf: storedProgramVersion`, so that it can test `expectedVersion`.
    */
-  constructor(private readonly storage: CollectionStorage<StoredProgram>) {}
+  constructor(storage: CollectionStorage<StoredProgram>) {
+    this.storage = storage;
+  }
 
   async get(key: string): Promise<StoredProgram | undefined> {
     const record = await this.storage.get(key);

package/src/program-store/file.ts

@@ -71,12 +71,16 @@ export async function retryOnContention<T>(operation: () => Promise<T>): Promise
 }
 
 export class FileProgramStore implements ProgramStore {
+  readonly path: string;
+
   readonly kind = "file";
   /** The writes of this process, one at a time (the lock file orders the processes). */
   private queue: Promise<unknown> = Promise.resolve();
 
   /** @param path - The JSON file. The store makes it, and its folder, at the first write. */
-  constructor(readonly path: string) {}
+  constructor(path: string) {
+    this.path = path;
+  }
 
   async get(key: string): Promise<StoredProgram | undefined> {
     return (await this.read()).programs[key];

package/src/storage/factory.ts

@@ -51,7 +51,7 @@ export interface CreateSyncedRegistryConfig {
 
   /**
    * The first mode of the hybrid storage (roadmap R28): `local-only`, `write-through`,
-   * `write-back` or `remote-only`. `setMode()` of the registry changes it later. Only the type
+   * `write-back`, `remote-only` or `read-only`. `setMode()` of the registry changes it later. Only the type
    * "hybrid" has modes.
    * @default "write-through"
    */

package/src/storage/file-queue.ts

@@ -21,11 +21,15 @@ export type { QueuedOperation, QueueStore } from "./queue.js";
 
 /** A queue store in a JSON Lines file. */
 export class FileQueueStore implements QueueStore {
+  readonly path: string;
+
   /** The calls of this instance, one at a time */
   private chain: Promise<unknown> = Promise.resolve();
 
   /** @param path - The file. The store makes it, and its folder, at the first write. */
-  constructor(readonly path: string) {}
+  constructor(path: string) {
+    this.path = path;
+  }
 
   load(): Promise<QueuedOperation[]> {
     return this.serial(async () => {

package/src/storage/hybrid.ts

@@ -2,7 +2,7 @@
  * Hybrid Storage Implementation
  *
  * A local copy (an `InMemoryStorage`, or the `local` storage that the application gives) in
- * front of a remote `CollectionStorage` (often an `ApiStorage`). The storage has four modes, and
+ * front of a remote `CollectionStorage` (often an `ApiStorage`). The storage has five modes, and
  * `setMode()` changes the mode while the storage operates (roadmap R28):
  *
  * | Mode | Reads | Writes | Remote calls |
@@ -11,6 +11,7 @@
  * | `write-through` | the local copy, the remote on a miss | the local copy, then the remote | yes |
  * | `write-back` | the local copy, the remote on a miss | the local copy and the queue, a timer sends it | yes |
  * | `remote-only` | the remote | the remote | yes, and no local copy |
+ * | `read-only` | the local copy, the remote on a miss | refused with `ReadOnlyError` | reads and pulls only |
  *
  * - The queue is durable through the `queueStore` that the application gives.
  * - A sync asks for the changes since a version when the remote has `getChangesSince`.
@@ -93,10 +94,19 @@ export type WriteStrategy = "write-through" | "write-back";
  * - `write-through`: each write goes to the local copy, then to the remote.
  * - `write-back`: each write goes to the local copy and to the queue. A timer sends the queue.
  * - `remote-only`: each read and each write goes to the remote. The storage keeps no local copy.
+ * - `read-only`: the storage refuses each write with `ReadOnlyError` at once, with no change of
+ *   the local copy, the queue or the remote. Reads, pulls and the feed work as in `write-through`
+ *   (roadmap CLI-89). This mode sends no write: a queue that it holds waits for a mode that writes.
  */
-export type HybridMode = "local-only" | "write-through" | "write-back" | "remote-only";
+export type HybridMode = "local-only" | "write-through" | "write-back" | "remote-only" | "read-only";
 
-const MODES: ReadonlySet<string> = new Set<HybridMode>(["local-only", "write-through", "write-back", "remote-only"]);
+const MODES: ReadonlySet<string> = new Set<HybridMode>(["local-only", "write-through", "write-back", "remote-only", "read-only"]);
+
+/** True for the modes that keep a local copy and read the remote changes into it. */
+const pullsRemote = (mode: HybridMode): boolean => mode === "write-through" || mode === "write-back" || mode === "read-only";
+
+/** True for the modes that send writes to the remote. */
+const pushesRemote = (mode: HybridMode): boolean => mode !== "local-only" && mode !== "read-only";
 
 /**
  * Hybrid storage configuration options.
@@ -179,14 +189,14 @@ export interface HybridStorageOptions {
 
   /**
    * The interval of the periodic pull, for example `minutes(1)` (roadmap R28). A pull reads the
-   * remote changes into the local copy in the modes `write-through` and `write-back`.
+   * remote changes into the local copy in the modes `write-through`, `write-back` and `read-only`.
    * @default no periodic pull
    */
   pullInterval?: Duration;
 
   /**
    * Initialize by syncing from remote on construction: send the loaded queue, then read the
-   * remote. The mode `local-only` makes no remote call.
+   * remote. The mode `local-only` makes no remote call. The mode `read-only` sends no queue.
    * @default true
    */
   syncOnInit?: boolean;
@@ -469,6 +479,8 @@ interface TimerOptions {
  * process alive.
  */
 class SyncTimer {
+  private readonly options: TimerOptions;
+
   private cancel: Cancel | undefined;
   private active = false;
   /** True while `work` runs */
@@ -477,7 +489,9 @@ class SyncTimer {
   private again = false;
   private failures = 0;
 
-  constructor(private readonly options: TimerOptions) {}
+  constructor(options: TimerOptions) {
+    this.options = options;
+  }
 
   /**
    * This method starts the timer. A timer that waits does not start again. A start during a run
@@ -590,6 +604,21 @@ export class QueueFullError extends Error {
   }
 }
 
+/**
+ * The storage is in `read-only` mode, so it refuses the write (roadmap CLI-89). The local copy, the
+ * queue and the remote did not change. `operation` is the name of the refused operation.
+ */
+export class ReadOnlyError extends Error {
+  readonly operation: string;
+
+  override readonly name = "ReadOnlyError";
+  readonly code = "READ_ONLY";
+  constructor(operation: string) {
+    super(`The storage is in read-only mode: it refuses the operation ${operation}`);
+    this.operation = operation;
+  }
+}
+
 /** The remote gave items without a key, so a sync cannot know which local items to keep. */
 export class MissingKeysError extends Error {
   override readonly name = "MissingKeysError";
@@ -616,10 +645,13 @@ export class QueueStoreError extends Error {
  * their queued writes stay. `ids` are the ids of the conflicts.
  */
 export class ConflictError extends Error {
+  readonly ids: string[];
+
   override readonly name = "ConflictError";
   readonly code = "SYNC_CONFLICT";
-  constructor(readonly ids: string[]) {
+  constructor(ids: string[]) {
     super(`Conflict detected between local and remote versions of ${ids.length} items: ${ids.slice(0, 10).join(", ")}`);
+    this.ids = ids;
   }
 }
 
@@ -628,10 +660,15 @@ export class ConflictError extends Error {
  * error of the flush or of the sync.
  */
 export class ModeSwitchError extends Error {
+  readonly from: HybridMode;
+  readonly to: HybridMode;
+
   override readonly name = "ModeSwitchError";
   readonly code = "MODE_SWITCH_FAILED";
-  constructor(readonly from: HybridMode, readonly to: HybridMode, cause: unknown) {
+  constructor(from: HybridMode, to: HybridMode, cause: unknown) {
     super(`The storage could not change from ${from} to ${to}: the mode is still ${from}`, { cause });
+    this.from = from;
+    this.to = to;
   }
 }
 
@@ -653,10 +690,13 @@ export class SyncStateError extends Error {
  * `apply` before the hook settled.
  */
 export class RemoteApplyHookError extends Error {
+  readonly calls: number;
+
   override readonly name = "RemoteApplyHookError";
   readonly code = "REMOTE_APPLY_HOOK";
-  constructor(readonly calls: number) {
+  constructor(calls: number) {
     super(`The hook aroundRemoteApply called apply ${calls} times, not 1 time: the storage applied the changes 1 time`);
+    this.calls = calls;
   }
 }
 
@@ -688,7 +728,7 @@ const defaultKeyOf = (item: unknown): string | undefined => {
 
 function checkMode(mode: unknown): HybridMode {
   if (typeof mode !== "string" || !MODES.has(mode)) {
-    throw new TypeError(`Unknown mode ${JSON.stringify(mode)}: use local-only, write-through, write-back or remote-only`);
+    throw new TypeError(`Unknown mode ${JSON.stringify(mode)}: use local-only, write-through, write-back, remote-only or read-only`);
   }
   return mode as HybridMode;
 }
@@ -792,15 +832,25 @@ interface EchoEntry {
  *   a write whose echo never comes does not hold an id long.
  */
 class EchoLedger {
+  private readonly window: number;
+  private readonly now: () => number;
+  private readonly maxPerId: number;
+  private readonly maxIds: number;
+
   /** The versions of each id, the oldest first. The ids are in the order of their last write. */
   private readonly entries = new Map<string, EchoEntry[]>();
 
   constructor(
-    private readonly window: number,
-    private readonly now: () => number,
-    private readonly maxPerId = 20,
-    private readonly maxIds = 10_000,
-  ) {}
+    window: number,
+    now: () => number,
+    maxPerId = 20,
+    maxIds = 10_000,
+  ) {
+    this.window = window;
+    this.now = now;
+    this.maxPerId = maxPerId;
+    this.maxIds = maxIds;
+  }
 
   /** This method records the version that an own write of an id gives. `null`: a delete. */
   wrote(id: string, version: string | null): void {
@@ -1360,7 +1410,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
   private updateFeed(): void {
     const feed = this.feed;
     if (!feed) return;
-    const wanted = !this.closed && (this.mode === "write-through" || this.mode === "write-back");
+    const wanted = !this.closed && pullsRemote(this.mode);
     if (wanted === (this.feedStop !== undefined)) return;
     const token = ++this.feedToken;
     if (!wanted) {
@@ -1416,7 +1466,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
    */
   private async applyFeed(changes: RemoteChanges<T>, mark: number): Promise<void> {
     if (this.loadError) throw this.loadError;
-    if (this.closed || (this.mode !== "write-through" && this.mode !== "write-back")) return;
+    if (this.closed || !pullsRemote(this.mode)) return;
     if (changes.version === this.cursor) return;
     const follows = changes.since !== undefined && changes.since === this.cursor;
     const hook = this.aroundRemoteApply;
@@ -1450,7 +1500,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
    */
   private async applyHint(hint: RemoteChangeHint, mark: number): Promise<void> {
     if (this.loadError) throw this.loadError;
-    if (this.closed || (this.mode !== "write-through" && this.mode !== "write-back")) return;
+    if (this.closed || !pullsRemote(this.mode)) return;
     // The remote cannot tell what changed: a full pull
     if (hint.reset === true) return this.requestPull(hint, true);
     if (hint.version !== undefined && hint.version === this.cursor) return;
@@ -1491,7 +1541,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
           if (this.closed) return Promise.resolve();
           return this.track("pull", async () => {
             if (this.loadError) throw this.loadError;
-            if (this.mode === "write-through" || this.mode === "write-back") await this.pullThrough(hints.length > 0 ? "hint" : "gap", hints, full);
+            if (pullsRemote(this.mode)) await this.pullThrough(hints.length > 0 ? "hint" : "gap", hints, full);
           });
         }),
       )
@@ -1669,7 +1719,8 @@ export class HybridStorage<T> implements CollectionStorage<T> {
    * - The switch waits for the operations that run. The operations that start later wait for
    *   the switch. Switches and syncs run one at a time.
    * - A switch to a remote mode sends the queue first. A switch to `local-only` makes no remote
-   *   call: the queue stays until the next remote mode.
+   *   call: the queue stays until the next remote mode. A switch to `read-only` also sends the
+   *   queue first, so this mode starts with an empty queue, or the switch fails.
    * - A switch to `remote-only` drops the local copy, after the queue reached the remote.
    * - A switch from `local-only` or `remote-only` to a mode with a local copy syncs the local
    *   copy. The reads wait for the sync.
@@ -1732,7 +1783,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
 
   /**
    * This method starts and stops the timers for the mode. The push timer runs in `write-back`, the
-   * pull timer in `write-through` and `write-back`, and the send of the queue after a failure only
+   * pull timer in `write-through`, `write-back` and `read-only`, and the send of the queue after a failure only
    * in `write-through`. A failed run reports its error in the status, and the next delay grows.
    */
   private updateTimers(): void {
@@ -1740,7 +1791,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     if (this.mode === "write-back") this.pushTimer?.start();
     else this.pushTimer?.stop();
 
-    if (this.mode === "write-through" || this.mode === "write-back") this.pullTimer?.start();
+    if (pullsRemote(this.mode)) this.pullTimer?.start();
     else this.pullTimer?.stop();
 
     if (this.mode !== "write-through") this.drainTimer.stop();
@@ -1936,6 +1987,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
    * One write, in the mode of the storage. The result is the result of the local copy, or of the
    * remote in `remote-only` mode.
    *
+   * - `read-only`: the write throws `ReadOnlyError`, and nothing changes.
    * - `remote-only`: the remote only. Its error passes through.
    * - `write-back` and `local-only`: the local copy and the queue. A full queue refuses the write
    *   before the local change. The queue store keeps the operation before the write ends.
@@ -1958,6 +2010,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     applyRemote: () => Promise<R>,
   ): Promise<R> {
     return this.run(false, async () => {
+      if (this.mode === "read-only") throw new ReadOnlyError(type);
       const op: QueuedOperation = { type, data, timestamp: Date.now() };
 
       if (this.mode === "remote-only") {
@@ -2139,7 +2192,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
       this.deferred.delete(id);
       const mark = this.writeSeq;
       let item = deferred.item;
-      if (this.mode === "write-through" || this.mode === "write-back") {
+      if (pullsRemote(this.mode)) {
         try {
           item = await this.remote.get(id);
           this.isOnline = true;
@@ -2208,8 +2261,8 @@ export class HybridStorage<T> implements CollectionStorage<T> {
   /**
    * Sync all pending offline operations to remote.
    * Processes queued operations in order. When one fails, it and the later operations stay in
-   * the queue: the operations that reached the remote are not sent again. In `local-only` mode,
-   * the call does nothing.
+   * the queue: the operations that reached the remote are not sent again. In the modes `local-only`
+   * and `read-only`, the call does nothing.
    */
   syncToRemote(): Promise<void> {
     if (this.closed) return Promise.reject(this.closedError());
@@ -2218,7 +2271,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
 
   /**
    * This method sends the queue to the remote (roadmap R28). `ProcedureServer.useStorage` uses it. In
-   * `local-only` mode, it sends nothing: the queue waits for a remote mode.
+   * the modes `local-only` and `read-only`, it sends nothing: the queue waits for a mode that writes.
    */
   flush(): Promise<void> {
     return this.syncToRemote();
@@ -2252,7 +2305,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
       this.track("pull", async () => {
         await this.loaded;
         if (this.loadError) throw this.loadError;
-        if (this.mode === "write-through" || this.mode === "write-back") await this.pullThrough("pull", NO_HINTS);
+        if (pullsRemote(this.mode)) await this.pullThrough("pull", NO_HINTS);
       }),
     );
   }
@@ -2263,7 +2316,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
       this.track("push", async () => {
         await this.loaded;
         if (this.loadError) throw this.loadError;
-        if (this.mode !== "local-only") await this.pushQueue();
+        if (pushesRemote(this.mode)) await this.pushQueue();
       }),
     );
   }
@@ -2281,7 +2334,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
    * This method closes the storage.
    *
    * - It stops the timers, and waits for the operations, the mode switch and the syncs that run.
-   * - It sends the queue (not in `local-only` mode). The queue store keeps the operations that
+   * - It sends the queue (not in the modes `local-only` and `read-only`). The queue store keeps the operations that
    *   the remote did not take.
    * - It closes the remote and the local copy. A durable local copy keeps its items.
    * - After it, each operation rejects. A second `close()` does nothing: it gives the promise of
@@ -2310,7 +2363,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
       // After the syncs that run: send the pending operations. The queue store keeps the ones that
       // the remote did not take, and the status gets the failure.
       await this.serialize(async () => {
-        if (this.loadError || this.offlineOps.length === 0 || this.mode === "local-only") return;
+        if (this.loadError || this.offlineOps.length === 0 || !pushesRemote(this.mode)) return;
         await this.track("push", () => this.pushQueue()).catch(() => undefined);
       });
       await this.storeChain;
@@ -2442,7 +2495,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     if (this.options.syncOnInit && this.mode !== "local-only") {
       // A failure goes to the status: the reads go on with the local copy
       if (this.offlineOps.length > 0) await this.push().catch(() => undefined);
-      if (!this.closed && (this.mode === "write-through" || this.mode === "write-back")) {
+      if (!this.closed && pullsRemote(this.mode)) {
         await this.pull().catch(() => undefined);
       }
     }

package/src/storage/index.ts

@@ -41,6 +41,7 @@ export {
   HybridStorage,
   PendingWriteError,
   QueueFullError,
+  ReadOnlyError,
   MissingKeysError,
   QueueStoreError,
   ConflictError,

package/src/storage/types.ts

@@ -139,7 +139,7 @@ export interface SyncStatus {
   syncing: boolean;
 
   /** The mode of a hybrid storage (roadmap R28), or undefined for a storage without modes */
-  mode?: "local-only" | "write-through" | "write-back" | "remote-only" | undefined;
+  mode?: "local-only" | "write-through" | "write-back" | "remote-only" | "read-only" | undefined;
 
   /**
    * The newest failure of the sync that a later success of the same work did not clear (roadmap