@procedures/store 0.3.0 → 0.5.0

package/src/storage/hybrid.ts

@@ -16,6 +16,10 @@
  * - A sync asks for the changes since a version when the remote has `getChangesSince`.
  * - With `versionOf`, a conflict is a change on both sides, and `conflictResolution` decides.
  * - `pullInterval` keeps the local copy fresh.
+ * - Each write takes a copy of the value (`structuredClone`), for the local copy, the queue and the
+ *   remote. The reads give the copies of the local copy, or of the remote in `remote-only` mode.
+ * - A full sync reads the local ids with `getIds()`, so it does not copy each local item.
+ * - After `close()`, each operation rejects, and a second `close()` does nothing.
  */
 
 import type { CollectionStorage, StorageChanges, StorageMetadata } from "@procedures/collections";
@@ -260,7 +264,8 @@ type PulledChanges<T> = Omit<StorageChanges<T>, "version"> & { version?: string
 /**
  * A storage for the local copy of a `HybridStorage` (roadmap R45): a collection storage that gives
  * its entries. A durable one, for example `SqliteStorage` of `@procedures/sqlite`, keeps the local
- * copy after a restart.
+ * copy after a restart. With `getIds()`, a full sync reads the local ids without a copy of the
+ * values.
  */
 export type LocalCopyStorage<T> = CollectionStorage<T> & { getEntries(): Promise<Array<[string, T]>> };
 
@@ -336,7 +341,10 @@ export class HybridStorage<T> implements CollectionStorage<T> {
   private active = 0;
   private idleWaiters: Array<() => void> = [];
   private isOnline = true;
+  /** True after `close()`: each operation rejects */
   private closed = false;
+  /** The work of the first `close()` */
+  private closing: Promise<void> | undefined;
   /** A counter of local writes for each id, so a sync does not restore an older remote value */
   private readonly writeVersions = new Map<string, number>();
   private clearVersion = 0;
@@ -406,6 +414,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
    */
   async setMode(mode: HybridMode): Promise<void> {
     const target = checkMode(mode);
+    if (this.closed) throw this.closedError();
     const previous = this.gate;
     let release!: () => void;
     this.gate = new Promise<void>((resolve) => (release = resolve));
@@ -461,7 +470,8 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     const push = this.mode === "write-back" && this.options.syncInterval > 0;
     if (push && !this.syncTimer) {
       this.syncTimer = setInterval(() => {
-        this.syncToRemote().catch((err) => {
+        if (this.closed) return;
+        this.push().catch((err) => {
           console.error("Periodic sync failed:", err);
         });
       }, this.options.syncInterval);
@@ -475,7 +485,8 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     const pull = this.options.pullInterval > 0 && (this.mode === "write-through" || this.mode === "write-back");
     if (pull && !this.pullTimer) {
       this.pullTimer = setInterval(() => {
-        this.syncFromRemote().catch((err) => {
+        if (this.closed) return;
+        this.pull().catch((err) => {
           console.error("Periodic pull failed:", err);
         });
       }, this.options.pullInterval);
@@ -540,6 +551,15 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     return this.run(true, () => (this.mode === "remote-only" ? this.remoteRead(() => this.remoteEntries()) : this.local.getEntries()));
   }
 
+  /**
+   * The ids of the items, in the order of the entries: the ids of the local copy, or of the remote
+   * in `remote-only` mode. The ids come without a copy of the values when the storage under them
+   * has `getIds()`.
+   */
+  async getIds(): Promise<string[]> {
+    return this.run(true, () => (this.mode === "remote-only" ? this.remoteRead(() => this.remoteIds()) : this.localIds()));
+  }
+
   async find(predicate: (item: T) => boolean): Promise<T[]> {
     return this.run(true, () =>
       this.mode === "remote-only" ? this.remoteRead(() => this.remote.find(predicate)) : this.local.find(predicate),
@@ -577,7 +597,12 @@ export class HybridStorage<T> implements CollectionStorage<T> {
   // ═══ Write Operations ═══
   //
 
-  async set(id: string, value: T): Promise<void> {
+  /**
+   * This method sets an item. The storage takes a copy of the value, so a later change of the
+   * value does not change the local copy, the queue or the remote write.
+   */
+  async set(id: string, written: T): Promise<void> {
+    const value = structuredClone(written);
     await this.write("set", { id, value }, [id], async () => {
       this.bump(id);
       await this.local.set(id, value);
@@ -602,7 +627,9 @@ export class HybridStorage<T> implements CollectionStorage<T> {
   // ═══ Bulk Operations ═══
   //
 
-  async setBatch(items: Array<[string, T]>): Promise<void> {
+  /** This method sets several items. The storage takes a copy of each value, as `set` does. */
+  async setBatch(written: Array<[string, T]>): Promise<void> {
+    const items = written.map(([id, value]): [string, T] => [id, structuredClone(value)]);
     await this.write("setBatch", { items }, items.map(([id]) => id), async () => {
       for (const [id] of items) this.bump(id);
       await this.local.setBatch(items);
@@ -752,11 +779,8 @@ export class HybridStorage<T> implements CollectionStorage<T> {
    * - Syncs run one at a time.
    */
   syncFromRemote(): Promise<void> {
-    return this.serialize(async () => {
-      await this.loaded;
-      if (this.loadError) throw this.loadError;
-      if (this.mode === "write-through" || this.mode === "write-back") await this.pullRemote(false);
-    });
+    if (this.closed) return Promise.reject(this.closedError());
+    return this.pull();
   }
 
   /**
@@ -766,11 +790,8 @@ export class HybridStorage<T> implements CollectionStorage<T> {
    * the call does nothing.
    */
   syncToRemote(): Promise<void> {
-    return this.serialize(async () => {
-      await this.loaded;
-      if (this.loadError) throw this.loadError;
-      if (this.mode !== "local-only") await this.pushQueue();
-    });
+    if (this.closed) return Promise.reject(this.closedError());
+    return this.push();
   }
 
   /**
@@ -789,17 +810,52 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     await this.syncFromRemote();
   }
 
+  /** The pull of `syncFromRemote()`, after the syncs that run. */
+  private pull(): Promise<void> {
+    return this.serialize(async () => {
+      await this.loaded;
+      if (this.loadError) throw this.loadError;
+      if (this.mode === "write-through" || this.mode === "write-back") await this.pullRemote(false);
+    });
+  }
+
+  /** The push of `syncToRemote()`, after the syncs that run. */
+  private push(): Promise<void> {
+    return this.serialize(async () => {
+      await this.loaded;
+      if (this.loadError) throw this.loadError;
+      if (this.mode !== "local-only") await this.pushQueue();
+    });
+  }
+
+  /** The error of an operation after `close()`. */
+  private closedError(): Error {
+    return new Error("The HybridStorage is closed");
+  }
+
   //
   // ═══ Lifecycle & Metadata ═══
   //
 
   /**
-   * This method stops the timers, sends the queue (not in `local-only` mode), and closes the remote and the
-   * local copy. The queue store keeps the operations that the remote did not take. A durable local
-   * copy keeps its items.
+   * 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
+   *   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
+   *   the first one, without its error.
    */
-  async close(): Promise<void> {
+  close(): Promise<void> {
+    if (this.closing) return this.closing.catch(() => undefined);
     this.closed = true;
+    this.closing = this.shutDown();
+    return this.closing;
+  }
+
+  /** The work of `close()`. */
+  private async shutDown(): Promise<void> {
     for (const timer of [this.syncTimer, this.pullTimer]) {
       if (timer) clearInterval(timer);
     }
@@ -811,14 +867,18 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     }
 
     await this.loaded;
-    // Sync pending operations before closing
-    if (this.offlineOps.length > 0 && this.mode !== "local-only") {
+    // The operations and the switch that started before close() end first
+    await this.gate;
+    await this.idle();
+    // After the syncs that run: send the pending operations
+    await this.serialize(async () => {
+      if (this.loadError || this.offlineOps.length === 0 || this.mode === "local-only") return;
       try {
-        await this.syncToRemote();
+        await this.pushQueue();
       } catch (error) {
         console.error("Failed to sync before close:", error);
       }
-    }
+    });
     await this.storeChain;
 
     // Close remote storage (an ApiStorage leaves the caller's client open)
@@ -829,15 +889,23 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     }
   }
 
+  /**
+   * The metadata of the storage. `size` is the result of `size()`: the number of items of the
+   * storage, also in `remote-only` mode. `stats.localSize` is the number of items of the local
+   * copy. Before, `size` was the size of the local copy, which `remote-only` keeps empty (found by
+   * the contract suite of `@procedures/collections/testing`).
+   */
   async getMetadata(): Promise<StorageMetadata> {
+    const currentSize = await this.size();
+    const localSize = await this.local.size();
     const totalOps = this.stats.cacheHits + this.stats.cacheMisses;
     const hitRate = totalOps > 0 ? (this.stats.cacheHits / totalOps) * 100 : 0;
-    const currentSize = await this.local.size();
 
     return {
       type: "hybrid",
       size: currentSize,
       stats: {
+        localSize,
         hitRate: Math.round(hitRate * 100) / 100,
         cacheHits: this.stats.cacheHits,
         cacheMisses: this.stats.cacheMisses,
@@ -861,6 +929,7 @@ export class HybridStorage<T> implements CollectionStorage<T> {
    * and never during a mode switch.
    */
   private async run<R>(read: boolean, work: () => Promise<R>): Promise<R> {
+    if (this.closed) throw this.closedError();
     await (read ? this.ready : this.loaded);
     for (;;) {
       const gate = this.gate;
@@ -868,6 +937,8 @@ export class HybridStorage<T> implements CollectionStorage<T> {
       // No new switch started while this operation waited
       if (this.gate === gate) break;
     }
+    // close() started while this operation waited
+    if (this.closed) throw this.closedError();
     if (this.loadError) throw this.loadError;
     this.active++;
     try {
@@ -913,15 +984,16 @@ export class HybridStorage<T> implements CollectionStorage<T> {
 
   /** The first sync: send the loaded queue, then read the remote. */
   private async initialSync(): Promise<void> {
-    if (this.loadError) return;
+    // A close() before the first sync: the storage makes no remote call
+    if (this.loadError || this.closed) return;
     if (this.options.syncOnInit && this.mode !== "local-only") {
       if (this.offlineOps.length > 0) {
-        await this.syncToRemote().catch((err) => {
+        await this.push().catch((err) => {
           console.error("Failed to send the queue on init:", err);
         });
       }
-      if (this.mode === "write-through" || this.mode === "write-back") {
-        await this.syncFromRemote().catch((err) => {
+      if (!this.closed && (this.mode === "write-through" || this.mode === "write-back")) {
+        await this.pull().catch((err) => {
           console.error("Failed to sync on init:", err);
         });
       }
@@ -980,10 +1052,9 @@ export class HybridStorage<T> implements CollectionStorage<T> {
       remoteIds.add(id);
       if (await this.pullItem(id, item, changedLocally, conflicts)) queueChanged = true;
     }
-    // The remote deleted these items
-    const gone = changes.full
-      ? (await this.local.getEntries()).map(([id]) => id).filter((id) => !remoteIds.has(id))
-      : changes.deleted;
+    // The remote deleted these items. A full pull reads only the local ids: before, it read each
+    // local entry, and the local copy copied each value for it.
+    const gone = changes.full ? (await this.localIds()).filter((id) => !remoteIds.has(id)) : changes.deleted;
     for (const id of gone) {
       if (await this.pullDelete(id, changedLocally, conflicts)) queueChanged = true;
     }
@@ -1175,6 +1246,18 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     return entries;
   }
 
+  /** The ids of the local copy: from `getIds()` when it has it, without a copy of the values. */
+  private async localIds(): Promise<string[]> {
+    if (this.local.getIds) return this.local.getIds();
+    return (await this.local.getEntries()).map(([id]) => id);
+  }
+
+  /** The ids of the remote: from `getIds()` when it has it, or else from its entries. */
+  private async remoteIds(): Promise<string[]> {
+    if (this.remote.getIds) return this.remote.getIds();
+    return (await this.remoteEntries()).map(([id]) => id);
+  }
+
   /**
    * This method sends the queue. The operations that reached the remote leave the queue. The queue store
    * gets the change at the end.
@@ -1494,7 +1577,8 @@ export class HybridStorage<T> implements CollectionStorage<T> {
     const delay = this.options.syncInterval > 0 ? this.options.syncInterval : 5000;
     this.drainTimer = setTimeout(() => {
       this.drainTimer = null;
-      this.syncToRemote().catch(() => this.scheduleDrain());
+      if (this.closed) return;
+      this.push().catch(() => this.scheduleDrain());
     }, delay);
     (this.drainTimer as { unref?: () => void }).unref?.();
   }

package/src/storage/synced-registry.ts

@@ -140,6 +140,12 @@ export class SyncedProcedureRegistry {
   /** Whether currently connected to remote storage */
   private connected = false;
 
+  /** True after `close()`: the registry writes nothing to its closed storage */
+  private closed = false;
+
+  /** The sync of the auto-sync timer that runs. `close()` waits for it. */
+  private autoSyncRun: Promise<unknown> | undefined;
+
   /** Remote endpoint (if connected) */
   private endpoint: string | undefined;
 
@@ -204,7 +210,8 @@ export class SyncedProcedureRegistry {
     }
     this.touch(key);
 
-    if (options?.persist === false) {
+    // After close(), the storage is closed: the registry keeps the procedure in memory only
+    if (options?.persist === false || this.closed) {
       return;
     }
     this.pendingDeletes.delete(key);
@@ -231,7 +238,7 @@ export class SyncedProcedureRegistry {
   unregister(path: ProcedurePath): boolean {
     const result = this.baseRegistry.unregister(path);
 
-    if (result) {
+    if (result && !this.closed) {
       const key = pathToKey(path);
       this.pendingChanges.delete(key);
       this.touch(key);
@@ -554,9 +561,16 @@ export class SyncedProcedureRegistry {
     const intervalMs = typeof interval === "number" ? interval : toMs(interval, "interval");
     this.stopAutoSync();
     const handle = setInterval(() => {
-      void this.sync("both").catch((err) => {
-        console.error("Auto-sync failed:", err);
-      });
+      // One auto-sync at a time, and none after close()
+      if (this.closed || this.autoSyncRun) return;
+      const run = this.sync("both")
+        .catch((err) => {
+          console.error("Auto-sync failed:", err);
+        })
+        .finally(() => {
+          if (this.autoSyncRun === run) this.autoSyncRun = undefined;
+        });
+      this.autoSyncRun = run;
     }, intervalMs);
     // Don't let the auto-sync timer keep the process alive. See BUGS-2026-07.md (M4).
     handle.unref?.();
@@ -726,10 +740,16 @@ export class SyncedProcedureRegistry {
   // ===========================================================================
 
   /**
-   * Close the synced registry and cleanup resources.
+   * This method closes the registry: it stops the auto-sync, waits for the sync that runs, writes
+   * the pending changes, and closes the storage. After it, `register()` and `unregister()` change
+   * only the registry in memory, because the storage rejects each operation. A second `close()`
+   * does nothing.
    */
   async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
     this.stopAutoSync();
+    await this.autoSyncRun;
 
     // Flush pending changes before closing
     await this.flushPending();