@procedures/store 0.2.3 → 0.4.0

package/src/storage/index.ts

@@ -36,8 +36,21 @@ export type { SerializeOptions, DeserializeOptions } from "./serialization.js";
 // The collection storages that need a Client (before: "@procedures/client/collections")
 export { ApiStorage } from "./api.js";
 export type { ApiStorageOptions } from "./api.js";
-export { HybridStorage } from "./hybrid.js";
-export type { HybridStorageOptions } from "./hybrid.js";
+export {
+  HybridStorage,
+  PendingWriteError,
+  QueueFullError,
+  MissingKeysError,
+  QueueStoreError,
+  ConflictError,
+  ModeSwitchError,
+} from "./hybrid.js";
+export type { HybridStorageOptions, HybridMode, LocalCopyStorage } from "./hybrid.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).
+export { MemoryQueueStore } from "./queue.js";
+export type { QueuedOperation, QueueStore } from "./queue.js";
 
 // Adapter
 export { ProcedureStorageAdapter } from "./adapter.js";

package/src/storage/queue.ts

@@ -0,0 +1,128 @@
+/**
+ * The queue of `HybridStorage` and the store that keeps it (roadmap R28).
+ *
+ * A write that waits for the remote is a `QueuedOperation`. The storage keeps the queue in
+ * memory and writes each change to a `QueueStore` before it acknowledges the write. A new storage
+ * with the same store loads the queue again, so a write that waits survives a restart.
+ *
+ * - `MemoryQueueStore` keeps the queue in memory. It is the default. A new storage that gets the
+ *   same instance loads its queue, so the tests can simulate a restart.
+ * - `FileQueueStore` keeps the queue in a JSON Lines file. It is in `@procedures/store/file-queue`,
+ *   because it uses `node:fs`. The root of the package stays usable in a browser.
+ * - `IndexedDbQueueStore` keeps the queue in IndexedDB, for a browser (roadmap R45). It is in
+ *   `@procedures/store/indexeddb`, and it implements the four methods of `QueueStore` on one
+ *   object store.
+ */
+
+/** A write that waits in the queue for the remote. Each field is JSON. */
+export interface QueuedOperation {
+  /** The kind of the write. */
+  type: "set" | "delete" | "setBatch" | "deleteBatch" | "clear";
+  /**
+   * The arguments of the write: `{ id, value }` for set, `{ id }` for delete,
+   * `{ items: [[id, value]] }` for setBatch, `{ ids }` for deleteBatch, `{}` for clear.
+   */
+  data: unknown;
+  /** The time of the write, in milliseconds since 1970. */
+  timestamp: number;
+  /**
+   * The remote version that the write changed, for each id with a known version. `null`: the
+   * remote had no item. Only a storage with `versionOf` writes it. A conflict test after a restart
+   * reads it.
+   */
+  base?: Array<[string, string | null]>;
+}
+
+/**
+ * The store that keeps the queue of a `HybridStorage` (roadmap R28). The storage calls the
+ * methods one at a time, in the order of the changes.
+ */
+export interface QueueStore {
+  /** This method gives the operations that the store holds, the oldest first. */
+  load(): Promise<QueuedOperation[]>;
+  /** This method adds an operation at the end. */
+  append(operation: QueuedOperation): Promise<void>;
+  /** This method puts these operations in the place of all operations. */
+  replace(operations: QueuedOperation[]): Promise<void>;
+  /** This method removes all operations. */
+  clear(): Promise<void>;
+}
+
+/** A queue store in memory: the default. Its queue lives as long as the instance. */
+export class MemoryQueueStore implements QueueStore {
+  private operations: QueuedOperation[] = [];
+
+  load(): Promise<QueuedOperation[]> {
+    return Promise.resolve(this.operations.slice());
+  }
+
+  append(operation: QueuedOperation): Promise<void> {
+    this.operations.push(operation);
+    return Promise.resolve();
+  }
+
+  replace(operations: QueuedOperation[]): Promise<void> {
+    this.operations = operations.slice();
+    return Promise.resolve();
+  }
+
+  clear(): Promise<void> {
+    this.operations = [];
+    return Promise.resolve();
+  }
+
+  /** The number of operations that the store holds. */
+  get size(): number {
+    return this.operations.length;
+  }
+}
+
+/** The ids that an operation changes ("*" for clear). */
+export function idsOf(op: QueuedOperation): string[] {
+  const data = op.data as { id?: string; ids?: string[]; items?: Array<[string, unknown]> };
+  switch (op.type) {
+    case "set":
+    case "delete":
+      return data.id === undefined ? [] : [data.id];
+    case "setBatch":
+      return (data.items ?? []).map(([id]) => id);
+    case "deleteBatch":
+      return data.ids ?? [];
+    case "clear":
+      return ["*"];
+  }
+}
+
+/**
+ * The operation without the id, or undefined when nothing stays. A clear cannot lose an id: it
+ * stays as it is.
+ */
+export function withoutId(op: QueuedOperation, id: string): QueuedOperation | undefined {
+  const data = op.data as { id?: string; ids?: string[]; items?: Array<[string, unknown]> };
+  switch (op.type) {
+    case "set":
+    case "delete":
+      return data.id === id ? undefined : op;
+    case "setBatch": {
+      const items = (data.items ?? []).filter(([itemId]) => itemId !== id);
+      return items.length === 0 ? undefined : { ...op, data: { items } };
+    }
+    case "deleteBatch": {
+      const ids = (data.ids ?? []).filter((other) => other !== id);
+      return ids.length === 0 ? undefined : { ...op, data: { ids } };
+    }
+    case "clear":
+      return op;
+  }
+}
+
+/** True when a value has the shape of a queued operation. A loaded file can hold anything. */
+export function isQueuedOperation(value: unknown): value is QueuedOperation {
+  if (typeof value !== "object" || value === null) return false;
+  const { type, data, timestamp } = value as Partial<QueuedOperation>;
+  return (
+    (type === "set" || type === "delete" || type === "setBatch" || type === "deleteBatch" || type === "clear") &&
+    typeof data === "object" && data !== null &&
+    typeof timestamp === "number"
+  );
+}

package/src/storage/synced-registry.ts

@@ -21,6 +21,19 @@ 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 type { HybridMode } from "./hybrid.js";
+
+/** A storage with modes: `HybridStorage` (roadmap R28). */
+interface StorageWithModes {
+  getMode(): HybridMode;
+  setMode(mode: HybridMode): Promise<void>;
+}
+
+function hasModes(storage: unknown): storage is StorageWithModes {
+  const candidate = storage as Partial<StorageWithModes> | null;
+  return typeof candidate?.setMode === "function" && typeof candidate.getMode === "function";
+}
 
 // =============================================================================
 // Extended Registration Options
@@ -100,7 +113,10 @@ export function getProcedureStore(registry: ProcedureRegistry): SyncedProcedureR
 export class SyncedProcedureRegistry {
   private readonly baseRegistry: ProcedureRegistry;
   private readonly adapter: ProcedureStorageAdapter;
-  private readonly options: SyncedRegistryOptions;
+  /** The storage of the records: `setMode` changes its mode */
+  private readonly storage: CollectionStorage<SerializedProcedure>;
+  /** The options, with the sync interval in milliseconds */
+  private readonly options: Omit<SyncedRegistryOptions, "syncInterval"> & { syncInterval: number };
 
   /** Pending changes for write-back strategy */
   private pendingChanges: Map<string, AnyProcedure> = new Map();
@@ -142,13 +158,14 @@ export class SyncedProcedureRegistry {
     options: Partial<SyncedRegistryOptions> = {}
   ) {
     this.baseRegistry = baseRegistry;
+    this.storage = storage;
     this.adapter = new ProcedureStorageAdapter(storage, {
       handlerLoader: options.handlerLoader,
     });
     this.options = {
       writeStrategy: options.writeStrategy ?? "write-through",
       conflictResolution: options.conflictResolution ?? "local",
-      syncInterval: options.syncInterval ?? 0,
+      syncInterval: optionalMs(options.syncInterval, "syncInterval") ?? 0,
       handlerLoader: options.handlerLoader,
       syncOnInit: options.syncOnInit ?? false,
     };
@@ -494,9 +511,35 @@ export class SyncedProcedureRegistry {
       lastSync: this.lastSyncTime,
       pendingChanges: this.pendingChanges.size + this.pendingDeletes.size,
       syncing: this.syncing,
+      mode: this.getMode(),
     };
   }
 
+  // ===========================================================================
+  // The mode of the storage (roadmap R28)
+  // ===========================================================================
+
+  /** The mode of the storage, or undefined when the storage has no modes. */
+  getMode(): HybridMode | undefined {
+    return hasModes(this.storage) ? this.storage.getMode() : undefined;
+  }
+
+  /**
+   * This method changes the mode of the storage while the registry operates (roadmap R28). The registry
+   * waits for its write-through stores that run, then `HybridStorage.setMode()` changes the
+   * mode: it sends the queued records before the change.
+   *
+   * @param mode - `local-only`, `write-through`, `write-back` or `remote-only`
+   * @throws When the storage has no modes, or when the switch fails (`ModeSwitchError`)
+   */
+  async setMode(mode: HybridMode): Promise<void> {
+    if (!hasModes(this.storage)) {
+      throw new Error('The storage of this registry has no modes: use createSyncedRegistry({ type: "hybrid" })');
+    }
+    await this.flushWrites();
+    await this.storage.setMode(mode);
+  }
+
   // ===========================================================================
   // Auto-Sync
   // ===========================================================================
@@ -504,9 +547,11 @@ export class SyncedProcedureRegistry {
   /**
    * Start auto-sync at specified interval.
    *
-   * @param intervalMs - Sync interval in milliseconds
+   * @param interval - The sync interval
    */
-  startAutoSync(intervalMs: number): void {
+  startAutoSync(interval: Duration | number): void {
+    // 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(() => {
       void this.sync("both").catch((err) => {

package/src/storage/types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { ProcedurePath, ProcedureMetadata } from "@procedures/client";
+import type { Duration } from "@procedures/client";
 
 // =============================================================================
 // Serialized Procedure
@@ -136,6 +137,9 @@ export interface SyncStatus {
 
   /** Whether currently syncing */
   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;
 }
 
 // =============================================================================
@@ -152,8 +156,8 @@ export interface SyncedRegistryOptions {
   /** How to resolve conflicts when loading from storage */
   conflictResolution: ConflictResolution;
 
-  /** Auto-sync interval in milliseconds (0 to disable) */
-  syncInterval?: number | undefined;
+  /** Auto-sync interval, for example `minutes(1)` (0 to disable) */
+  syncInterval?: Duration | undefined;
 
   /** Handler loader for restoring handlers from references */
   handlerLoader?: HandlerLoader | undefined;