@procedures/store 0.8.0 → 0.8.1

package/src/storage/index.ts

@@ -16,6 +16,7 @@ export type {
   SyncConflict,
   SyncResult,
   SyncStatus,
+  SyncError,
   SyncedRegistryOptions,
   ProcedureStorageConfig,
 } from "./types.js";
@@ -44,8 +45,24 @@ export {
   QueueStoreError,
   ConflictError,
   ModeSwitchError,
+  SyncStateError,
 } from "./hybrid.js";
 export type { HybridStorageOptions, HybridMode, LocalCopyStorage } from "./hybrid.js";
+// The push feed of the remote changes (roadmap CLI-21, CLI-15)
+export { EventsChangeFeed } from "./feed.js";
+export type {
+  ChangeEventSource,
+  EventSubscriber,
+  EventsChangeFeedOptions,
+  RemoteChangeFeed,
+  RemoteChangeHint,
+  RemoteChangeListener,
+  RemoteChanges,
+} from "./feed.js";
+// The sync state of HybridStorage: the cursor and the base versions (roadmap CLI-21).
+// IndexedDbSyncStateStore is in "@procedures/store/indexeddb".
+export { MemorySyncStateStore } from "./sync-state.js";
+export type { SyncState, SyncStateChange, SyncStateStore } from "./sync-state.js";
 // The queue of HybridStorage and its store (roadmap R28). FileQueueStore is in
 // "@procedures/store/file-queue": it uses node:fs. IndexedDbQueueStore is in
 // "@procedures/store/indexeddb": it uses the IndexedDB of a browser (roadmap R45).

package/src/storage/sync-state.ts

@@ -0,0 +1,89 @@
+/**
+ * The sync state of a `HybridStorage` and the store that keeps it (roadmap CLI-21).
+ *
+ * The sync state is the cursor (the remote version of the last pull) and the base versions (the
+ * last known remote version of each id). A store keeps them after a reload. A new storage with the
+ * same store then asks the remote only for the changes since the cursor, and it finds the conflicts
+ * of the writes after the reload.
+ *
+ * - `MemorySyncStateStore` keeps the state in memory. A new storage that gets the same instance
+ *   loads the state, so the tests can simulate a reload.
+ * - `IndexedDbSyncStateStore` keeps the state in IndexedDB, for a browser. It is in
+ *   `@procedures/store/indexeddb`.
+ *
+ * The state belongs to its local copy. Give a store only with a durable local copy, and give each
+ * storage its own store.
+ */
+
+/** The sync state of a `HybridStorage`. Each field is JSON. */
+export interface SyncState {
+  /** The remote version of the last pull, or undefined: the next pull reads all items. */
+  readonly cursor?: string | undefined;
+  /** The last known remote version of each id. `null`: the remote has no item. */
+  readonly bases: ReadonlyArray<readonly [string, string | null]>;
+}
+
+/** A change of the sync state, from a `HybridStorage` to its store. */
+export interface SyncStateChange extends SyncState {
+  /** True: the change replaces the whole state. False: it changes the cursor and the ids that it names. */
+  readonly reset: boolean;
+  /** The ids whose base is not known any more. Empty when `reset` is true. */
+  readonly forgotten: readonly string[];
+}
+
+/**
+ * The store of the sync state of a `HybridStorage` (roadmap CLI-21). The storage calls the methods
+ * one at a time, in the order of the changes.
+ */
+export interface SyncStateStore {
+  /** This method gives the state that the store holds, or undefined when it holds none. */
+  load(): Promise<SyncState | undefined>;
+  /** This method writes a change of the state. */
+  write(change: SyncStateChange): Promise<void>;
+  /** This method removes the state. */
+  clear(): Promise<void>;
+}
+
+/** A sync state store in memory. Its state lives as long as the instance. */
+export class MemorySyncStateStore implements SyncStateStore {
+  private cursor: string | undefined;
+  private readonly bases = new Map<string, string | null>();
+  private written = false;
+
+  load(): Promise<SyncState | undefined> {
+    if (!this.written) return Promise.resolve(undefined);
+    return Promise.resolve({ ...(this.cursor !== undefined && { cursor: this.cursor }), bases: [...this.bases] });
+  }
+
+  write(change: SyncStateChange): Promise<void> {
+    if (change.reset) this.bases.clear();
+    this.cursor = change.cursor;
+    for (const [id, version] of change.bases) this.bases.set(id, version);
+    for (const id of change.forgotten) this.bases.delete(id);
+    this.written = true;
+    return Promise.resolve();
+  }
+
+  clear(): Promise<void> {
+    this.cursor = undefined;
+    this.bases.clear();
+    this.written = false;
+    return Promise.resolve();
+  }
+
+  /** The number of base versions that the store holds. */
+  get size(): number {
+    return this.bases.size;
+  }
+}
+
+/** True when a value has the shape of a sync state. A loaded store can hold anything. */
+export function isSyncState(value: unknown): value is SyncState {
+  if (typeof value !== "object" || value === null) return false;
+  const { cursor, bases } = value as { cursor?: unknown; bases?: unknown };
+  return (
+    (cursor === undefined || typeof cursor === "string") &&
+    Array.isArray(bases) &&
+    bases.every((entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && (entry[1] === null || typeof entry[1] === "string"))
+  );
+}

package/src/storage/synced-registry.ts

@@ -5,13 +5,14 @@
  * Enables procedure persistence and sync across backends.
  */
 
-import type { CollectionStorage } from "@procedures/collections";
+import { StorageListeners, type CollectionStorage } from "@procedures/collections";
 import { ProcedureRegistry } from "@procedures/client";
 import type { AnyProcedure, ProcedurePath, RegistrationOptions } from "@procedures/client";
 import { pathToKey } from "@procedures/client";
 import type {
   SerializedProcedure,
   SyncedRegistryOptions,
+  SyncError,
   SyncResult,
   SyncStatus,
   SyncDirection,
@@ -21,7 +22,7 @@ import type {
 } from "./types.js";
 import { ProcedureStorageAdapter } from "./adapter.js";
 import { serializeProcedure, deserializeProcedure, getSerializedKey } from "./serialization.js";
-import { optionalMs, toMs, type Duration } from "@procedures/client";
+import { optionalMs, realClock, toMs, type Cancel, type Clock, type Duration } from "@procedures/client";
 import type { HybridMode } from "./hybrid.js";
 
 /** A storage with modes: `HybridStorage` (roadmap R28). */
@@ -155,8 +156,17 @@ export class SyncedProcedureRegistry {
   /** Whether currently syncing */
   private syncing = false;
 
-  /** Auto-sync interval handle */
-  private syncIntervalHandle: ReturnType<typeof setInterval> | undefined;
+  /** The clock of the auto-sync */
+  private readonly clock: Clock;
+
+  /** The auto-sync that runs: the timer of its next sync */
+  private autoSync: { cancel: Cancel | undefined } | undefined;
+
+  /** The failures of the auto-sync and of the write-through writes that a later success did not clear */
+  private readonly failures = new Map<SyncError["operation"], SyncError>();
+
+  /** The listeners of `onStatus()` */
+  private readonly statusListeners = new StorageListeners<SyncStatus>();
 
   constructor(
     baseRegistry: ProcedureRegistry,
@@ -175,6 +185,7 @@ export class SyncedProcedureRegistry {
       handlerLoader: options.handlerLoader,
       syncOnInit: options.syncOnInit ?? false,
     };
+    this.clock = options.clock ?? realClock;
 
     // The storage procedures of this registry find this wrapper
     STORES.set(baseRegistry, this);
@@ -216,11 +227,12 @@ export class SyncedProcedureRegistry {
     }
     this.pendingDeletes.delete(key);
     if (this.options.writeStrategy === "write-through") {
-      // Write-through: persist now. flushWrites() waits for these writes.
+      // Write-through: persist now. flushWrites() waits for these writes. A failure goes to the status.
       this.track(
-        this.storeRecords([registered]).catch((err) => {
-          console.error(`Failed to persist procedure ${key}:`, err);
-        })
+        this.storeRecords([registered]).then(
+          () => this.succeed("push"),
+          (error: unknown) => this.fail("push", new Error(`Failed to persist procedure ${key}`, { cause: error })),
+        )
       );
     } else {
       // Write-back: queue for later sync
@@ -244,9 +256,10 @@ export class SyncedProcedureRegistry {
       this.touch(key);
       if (this.options.writeStrategy === "write-through") {
         this.track(
-          this.adapter.remove(path).catch((err) => {
-            console.error(`Failed to remove procedure ${key} from storage:`, err);
-          })
+          this.adapter.remove(path).then(
+            () => this.succeed("push"),
+            (error: unknown) => this.fail("push", new Error(`Failed to remove procedure ${key} from storage`, { cause: error })),
+          )
         );
       } else {
         this.pendingDeletes.set(key, path);
@@ -509,9 +522,11 @@ export class SyncedProcedureRegistry {
   }
 
   /**
-   * Get current sync status.
+   * Get current sync status. `error` is the newest failure of the auto-sync or of a write-through
+   * write that a later success did not clear.
    */
   getStatus(): SyncStatus {
+    const error = [...this.failures.values()].at(-1);
     return {
       connected: this.connected,
       endpoint: this.endpoint,
@@ -519,9 +534,32 @@ export class SyncedProcedureRegistry {
       pendingChanges: this.pendingChanges.size + this.pendingDeletes.size,
       syncing: this.syncing,
       mode: this.getMode(),
+      ...(error !== undefined && { error }),
     };
   }
 
+  /**
+   * This method sends the status to a listener after each failure and each success of the auto-sync
+   * and of the write-through writes (roadmap CLI-13). Before, the failures went to the console.
+   *
+   * @returns The function that stops the status. A second use of it does nothing.
+   */
+  onStatus(listener: (status: SyncStatus) => void): () => void {
+    return this.statusListeners.add(listener);
+  }
+
+  /** This method keeps a failure for the status, and sends the status. */
+  private fail(operation: SyncError["operation"], error: unknown): void {
+    this.failures.delete(operation);
+    this.failures.set(operation, { operation, error });
+    this.statusListeners.emit(this.getStatus());
+  }
+
+  /** This method clears the failure of an operation after a success, and sends the status. */
+  private succeed(operation: SyncError["operation"]): void {
+    if (this.failures.delete(operation)) this.statusListeners.emit(this.getStatus());
+  }
+
   // ===========================================================================
   // The mode of the storage (roadmap R28)
   // ===========================================================================
@@ -560,31 +598,38 @@ export class SyncedProcedureRegistry {
     // A number is the internal form of the option, in milliseconds
     const intervalMs = typeof interval === "number" ? interval : toMs(interval, "interval");
     this.stopAutoSync();
-    const handle = setInterval(() => {
-      // 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?.();
-    this.syncIntervalHandle = handle;
+    const loop: { cancel: Cancel | undefined } = { cancel: undefined };
+    this.autoSync = loop;
+    // The next sync waits for the interval after the end of the last one: one auto-sync at a time
+    const arm = (): void => {
+      const cancel = this.clock.after(intervalMs, () => {
+        loop.cancel = undefined;
+        // None after close() or stopAutoSync()
+        if (this.closed || this.autoSync !== loop) return;
+        const run = this.sync("both")
+          .then(
+            () => this.succeed("sync"),
+            (error: unknown) => this.fail("sync", error),
+          )
+          .finally(() => {
+            if (this.autoSyncRun === run) this.autoSyncRun = undefined;
+            if (!this.closed && this.autoSync === loop) arm();
+          });
+        this.autoSyncRun = run;
+      });
+      // Don't let the auto-sync timer keep the process alive. See BUGS-2026-07.md (M4).
+      cancel.unref?.();
+      loop.cancel = cancel;
+    };
+    arm();
   }
 
   /**
    * Stop auto-sync.
    */
   stopAutoSync(): void {
-    if (this.syncIntervalHandle) {
-      clearInterval(this.syncIntervalHandle);
-      this.syncIntervalHandle = undefined;
-    }
+    this.autoSync?.cancel?.();
+    this.autoSync = undefined;
   }
 
   // ===========================================================================

package/src/storage/types.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ProcedurePath, ProcedureMetadata } from "@procedures/client";
-import type { Duration } from "@procedures/client";
+import type { Clock, Duration } from "@procedures/client";
 
 // =============================================================================
 // Serialized Procedure
@@ -140,6 +140,23 @@ export interface SyncStatus {
 
   /** 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;
+
+  /**
+   * The newest failure of the sync that a later success of the same work did not clear (roadmap
+   * CLI-13), or undefined. Before, the failures went to the console.
+   */
+  error?: SyncError | undefined;
+}
+
+/** A failure of a sync, for its status. */
+export interface SyncError {
+  /**
+   * The work that failed: the load of the queue, a push of the queue or of the records, a pull, a
+   * sync of both directions, or the queue store or the sync state store.
+   */
+  readonly operation: "load" | "push" | "pull" | "sync" | "store";
+  /** The error of the work. */
+  readonly error: unknown;
 }
 
 // =============================================================================
@@ -159,6 +176,13 @@ export interface SyncedRegistryOptions {
   /** Auto-sync interval, for example `minutes(1)` (0 to disable) */
   syncInterval?: Duration | undefined;
 
+  /**
+   * The clock of the auto-sync. A test gives `fakeClock` of `@mark1russell7/service/testing`. The
+   * timer does not keep a Node process alive.
+   * @default the clock of the platform (`realClock` of `@procedures/client`)
+   */
+  clock?: Clock | undefined;
+
   /** Handler loader for restoring handlers from references */
   handlerLoader?: HandlerLoader | undefined;