@procedures/store 0.0.0-stage → 0.1.0

package/dist/storage/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Procedure Storage Types
+ *
+ * Types for serializing and persisting procedure definitions.
+ * Enables procedure registry to be backed by CollectionStorage.
+ */
+import type { ProcedurePath, ProcedureMetadata } from "@procedures/client";
+/**
+ * Reference to a handler that can be loaded at runtime.
+ * Handlers cannot be serialized directly, so we store a reference.
+ */
+export interface HandlerReference {
+    /** Module name or path (e.g., "@procedures/cli-run") */
+    module: string;
+    /** Named export from the module (e.g., "libScanHandler") */
+    export: string;
+}
+/**
+ * Serialized procedure definition for storage.
+ * Contains only JSON-serializable data.
+ */
+export interface SerializedProcedure {
+    /** Procedure path (e.g., ['lib', 'scan']) */
+    path: ProcedurePath;
+    /** Procedure metadata */
+    metadata: ProcedureMetadata;
+    /** Whether this procedure supports streaming */
+    streaming?: boolean | undefined;
+    /** Reference to handler for runtime loading (optional) */
+    handlerRef?: HandlerReference | undefined;
+    /** Timestamp when stored */
+    storedAt?: number | undefined;
+    /** Version for conflict detection */
+    version?: number | undefined;
+}
+/**
+ * Function to load a handler from a reference.
+ * Used to restore handlers when loading procedures from storage.
+ */
+export interface HandlerLoader {
+    /**
+     * Load a handler from a reference.
+     *
+     * @param ref - Handler reference with module and export name
+     * @returns The handler function, or undefined if not found
+     */
+    load(ref: HandlerReference): Promise<unknown | undefined>;
+}
+/**
+ * Sync direction for registry operations.
+ */
+export type SyncDirection = "push" | "pull" | "both";
+/**
+ * Conflict resolution strategy.
+ */
+export type ConflictResolution = "local" | "remote" | "merge" | "error";
+/**
+ * Write strategy for persistence.
+ */
+export type WriteStrategy = "write-through" | "write-back";
+/**
+ * Status of a sync conflict.
+ */
+export interface SyncConflict {
+    /** Procedure path that had conflict */
+    path: ProcedurePath;
+    /** How the conflict was resolved */
+    resolution: ConflictResolution;
+    /** Local version (if any) */
+    local?: SerializedProcedure;
+    /** Remote version (if any) */
+    remote?: SerializedProcedure;
+}
+/**
+ * Result of a sync operation.
+ */
+export interface SyncResult {
+    /** Number of procedures pushed to storage */
+    pushed: number;
+    /** Number of procedures pulled from storage */
+    pulled: number;
+    /** Conflicts encountered during sync */
+    conflicts: SyncConflict[];
+    /** Timestamp of sync completion */
+    timestamp: number;
+}
+/**
+ * Current sync status of the registry.
+ */
+export interface SyncStatus {
+    /** Whether connected to remote storage */
+    connected: boolean;
+    /** Remote endpoint URL (if connected) */
+    endpoint?: string | undefined;
+    /** Last successful sync timestamp */
+    lastSync?: number | undefined;
+    /** Number of pending local changes */
+    pendingChanges: number;
+    /** Whether currently syncing */
+    syncing: boolean;
+}
+/**
+ * Options for SyncedProcedureRegistry.
+ */
+export interface SyncedRegistryOptions {
+    /** Write strategy: write-through (immediate) or write-back (queued) */
+    writeStrategy: WriteStrategy;
+    /** How to resolve conflicts when loading from storage */
+    conflictResolution: ConflictResolution;
+    /** Auto-sync interval in milliseconds (0 to disable) */
+    syncInterval?: number | undefined;
+    /** Handler loader for restoring handlers from references */
+    handlerLoader?: HandlerLoader | undefined;
+    /** Whether to sync on initialization */
+    syncOnInit?: boolean | undefined;
+}
+/**
+ * Configuration for creating a storage-backed registry.
+ */
+export interface ProcedureStorageConfig {
+    /** Storage type to use */
+    type: "memory" | "api" | "hybrid";
+    /** The collection of the core collection procedures for API storage (default: "procedures") */
+    collection?: string | undefined;
+    /** The service of the calls, for a server with other paths (default: `collections.<collection>`) */
+    service?: string | undefined;
+    /** Options for the synced registry */
+    options?: Partial<SyncedRegistryOptions> | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/storage/types.js

@@ -0,0 +1,8 @@
+/**
+ * Procedure Storage Types
+ *
+ * Types for serializing and persisting procedure definitions.
+ * Enables procedure registry to be backed by CollectionStorage.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here.
+ */
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,82 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A program store for procedure-as-data: save the programs that procedure.define makes, load them back after a restart, in memory, a JSON file or a remote collection storage.",
+  "keywords": [
+    "program-store",
+    "procedures",
+    "json-programs",
+    "persistence",
+    "registry",
+    "rpc"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/client-store"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/register.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "dependencies": {
+    "@procedures/client": "0.1.0",
+    "@procedures/collections": "0.1.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/src/errors.ts

@@ -0,0 +1,20 @@
+/**
+ * The error of a store procedure that cannot do its work.
+ *
+ * - NOT_CONFIGURED: the caller's registry has no store.
+ * - NOT_IMPLEMENTED: the action has no safe implementation (`procedure.remote connect`).
+ * - NO_HANDLER: `procedure.register` with `persist` got no handler that the loader allows.
+ * - NOT_A_PROGRAM: `procedure.store` got a code procedure. Only a procedure that
+ *   `procedure.define` made is a program: code lives in a package.
+ */
+export class ProcedureStoreError extends Error {
+  override readonly name = "ProcedureStoreError";
+  readonly code: ProcedureStoreErrorCode;
+
+  constructor(code: ProcedureStoreErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export type ProcedureStoreErrorCode = "NOT_CONFIGURED" | "NOT_IMPLEMENTED" | "NO_HANDLER" | "NOT_A_PROGRAM";

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @procedures/store: the program store of the client ecosystem (roadmap 3.2).
+ *
+ * - The program store: `ProgramStore` and its backends (`MemoryProgramStore`,
+ *   `FileProgramStore`, `CollectionProgramStore`), and the procedures `procedure.store`, `load`,
+ *   `sync` and `remote`. A stored program loads back as a runtime-defined procedure.
+ * - The storage layer that moved here from `@procedures/client`: the collection storages that
+ *   need a Client (`ApiStorage`, `HybridStorage`), the synced registry, the serialization, the
+ *   dynamic handler loader (an allowlist) and `procedure.register`.
+ *
+ * Importing the package registers its procedures.
+ */
+
+export * from "./storage/index.js";
+export * from "./program-store/index.js";
+export { ProcedureStoreError, type ProcedureStoreErrorCode } from "./errors.js";
+export { procedureStorageModule, procedureStorageProcedures } from "./procedures.js";
+export * from "./register.js";
+export * from "./types.js";

package/src/module.ts

@@ -0,0 +1,18 @@
+/**
+ * Module (no side effects): the procedures of client-store as data, for `createRegistry()`.
+ *
+ * The procedures of the store: `procedure.register` and the program store procedures
+ * `procedure.store`, `load`, `sync` and `remote`. The core registered the older versions of them
+ * before they moved here (roadmap 3.2).
+ */
+
+import { defineModule, type ProcedureModule } from "@procedures/client";
+import { procedureStorageProcedures } from "./procedures.js";
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const storeModule: ProcedureModule = defineModule("@procedures/store", procedureStorageProcedures);
+
+export default storeModule;

package/src/procedures.ts

@@ -0,0 +1,17 @@
+/**
+ * Every procedure of the package: procedure.register (the synced registry) and the procedures of
+ * the program store (procedure.store, load, sync and remote).
+ */
+
+import type { AnyProcedure } from "@procedures/client";
+import { procedureRegisterProcedure } from "./storage/procedures.js";
+import { programStoreProcedures } from "./program-store/procedures.js";
+
+/** All the procedures of client-store. */
+export const procedureStorageProcedures: AnyProcedure[] = [procedureRegisterProcedure, ...programStoreProcedures];
+
+/** All the procedures of client-store as a module. */
+export const procedureStorageModule: { name: string; procedures: AnyProcedure[] } = {
+  name: "procedure-storage",
+  procedures: procedureStorageProcedures,
+};

package/src/program-store/attach.ts

@@ -0,0 +1,46 @@
+/**
+ * The program store of a registry.
+ *
+ * A host gives a registry its store with `attachProgramStore(registry, store)`. The procedures
+ * `procedure.store`, `load` and `sync` use the store of the caller's registry (`ctx.registry`,
+ * or the global registry). Without a store, they fail with the code NOT_CONFIGURED.
+ */
+
+import { PROCEDURE_REGISTRY, type ProcedureContext, type ProcedureRegistryLike } from "@procedures/client";
+import type { ProgramStore } from "./types.js";
+import { ProcedureStoreError } from "../storage/procedures.js";
+
+const STORES = new WeakMap<object, ProgramStore>();
+
+/** Give a registry its program store. A second call replaces the store. */
+export function attachProgramStore(registry: object, store: ProgramStore): void {
+  STORES.set(registry, store);
+}
+
+/** Take the program store from a registry. */
+export function detachProgramStore(registry: object): void {
+  STORES.delete(registry);
+}
+
+/** The program store of a registry, or undefined. */
+export function getProgramStore(registry: object): ProgramStore | undefined {
+  return STORES.get(registry);
+}
+
+/** The registry of a caller: the context's registry, or the global registry. */
+export function callerRegistry(ctx: ProcedureContext | undefined): ProcedureRegistryLike {
+  return ctx?.registry ?? PROCEDURE_REGISTRY;
+}
+
+/** The program store of the caller's registry, or a NOT_CONFIGURED error. */
+export function requireProgramStore(ctx: ProcedureContext | undefined, what: string): ProgramStore {
+  const store = getProgramStore(callerRegistry(ctx));
+  if (!store) {
+    throw new ProcedureStoreError(
+      "NOT_CONFIGURED",
+      `${what} needs a program store, and this registry has none. ` +
+        "Give it one with attachProgramStore(registry, new FileProgramStore(path)) (or MemoryProgramStore, CollectionProgramStore)."
+    );
+  }
+  return store;
+}

package/src/program-store/collection.ts

@@ -0,0 +1,39 @@
+/**
+ * A program store on a collection storage: `InMemoryStorage` of client-collections, or a remote
+ * one, `ApiStorage` (the collection procedures of a server) or `HybridStorage` (a local cache with
+ * a remote copy). The key of each record is the key of the program.
+ */
+
+import type { CollectionStorage } from "@procedures/client";
+import { byKey, checkStoredProgram, keyMatches, type ProgramStore, type StoredProgram } from "./types.js";
+
+export class CollectionProgramStore implements ProgramStore {
+  readonly kind = "collection";
+
+  /** @param storage - The storage of the records. The store closes it in `close()`. */
+  constructor(private readonly storage: CollectionStorage<StoredProgram>) {}
+
+  async get(key: string): Promise<StoredProgram | undefined> {
+    const record = await this.storage.get(key);
+    // A copy: a local storage (InMemoryStorage) gives its own object
+    return record === undefined ? undefined : checkStoredProgram(structuredClone(record));
+  }
+
+  async list(prefix?: string): Promise<StoredProgram[]> {
+    const records = await this.storage.getAll();
+    return byKey(records.map((record) => checkStoredProgram(structuredClone(record))).filter((p) => keyMatches(p.key, prefix)));
+  }
+
+  async put(program: StoredProgram): Promise<void> {
+    const checked = checkStoredProgram(structuredClone(program));
+    await this.storage.set(checked.key, checked);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.storage.delete(key);
+  }
+
+  async close(): Promise<void> {
+    await this.storage.close();
+  }
+}

package/src/program-store/file.ts

@@ -0,0 +1,157 @@
+/**
+ * A program store in one JSON file.
+ *
+ * The file is `{ "schemaVersion": 1, "programs": { "<key>": <StoredProgram> } }`. Each operation
+ * reads the file again, so two processes see the programs of each other. A write takes a lock
+ * file (`<file>.lock`), reads, changes and writes the file through a temporary file and a rename,
+ * so a reader never sees a part of a write and two writers do not lose each other's programs.
+ * A file that is not valid JSON is an error: the store does not write over it.
+ */
+
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { byKey, checkStoredProgram, keyMatches, type ProgramStore, type StoredProgram } from "./types.js";
+
+interface ProgramFile {
+  schemaVersion: 1;
+  programs: Record<string, StoredProgram>;
+}
+
+/** A lock older than this belongs to a process that stopped: it is removed. */
+const STALE_LOCK_MS = 10_000;
+/** The longest wait for the lock. */
+const LOCK_TIMEOUT_MS = 30_000;
+
+/**
+ * True when another process holds a file for a moment. On Windows, a file that its owner is
+ * deleting or renaming cannot be opened until that completes: EPERM, EACCES or EBUSY.
+ */
+function isContention(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code === "EEXIST") return true;
+  return process.platform === "win32" && (code === "EPERM" || code === "EACCES" || code === "EBUSY");
+}
+
+const pause = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Run a file operation again while Windows holds the file for a moment. */
+async function retryOnContention<T>(operation: () => Promise<T>): Promise<T> {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (attempt >= 20 || code === "EEXIST" || !isContention(error)) throw error;
+      await pause(10 * attempt);
+    }
+  }
+}
+
+export class FileProgramStore implements ProgramStore {
+  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) {}
+
+  async get(key: string): Promise<StoredProgram | undefined> {
+    return (await this.read()).programs[key];
+  }
+
+  async list(prefix?: string): Promise<StoredProgram[]> {
+    return byKey(Object.values((await this.read()).programs).filter((p) => keyMatches(p.key, prefix)));
+  }
+
+  async put(program: StoredProgram): Promise<void> {
+    const checked = checkStoredProgram(structuredClone(program));
+    await this.change((file) => {
+      file.programs[checked.key] = checked;
+      return true;
+    });
+  }
+
+  async delete(key: string): Promise<boolean> {
+    let deleted = false;
+    await this.change((file) => {
+      deleted = Object.hasOwn(file.programs, key);
+      if (deleted) delete file.programs[key];
+      return deleted;
+    });
+    return deleted;
+  }
+
+  /** The content of the file. A missing file is an empty store. */
+  private async read(): Promise<ProgramFile> {
+    let text: string;
+    try {
+      text = await retryOnContention(() => readFile(this.path, "utf8"));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return { schemaVersion: 1, programs: {} };
+      throw error;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new Error(`The program store file is not valid JSON: ${this.path}. The store does not write over it.`);
+    }
+    const file = parsed as Partial<ProgramFile>;
+    if (file?.schemaVersion !== 1 || typeof file.programs !== "object" || file.programs === null) {
+      throw new Error(`The program store file has an unknown format (schemaVersion 1 expected): ${this.path}`);
+    }
+    // A null-prototype object: a key such as "__proto__" stays a plain key
+    const programs: Record<string, StoredProgram> = Object.create(null);
+    for (const [key, value] of Object.entries(file.programs)) programs[key] = checkStoredProgram(value);
+    return { schemaVersion: 1, programs };
+  }
+
+  /** Read, change and write the file under the lock. `change` gives false when nothing changed. */
+  private change(change: (file: ProgramFile) => boolean): Promise<void> {
+    const run = this.queue.then(() => this.withLock(async () => {
+      const file = await this.read();
+      if (change(file)) await this.write(file);
+    }));
+    this.queue = run.catch(() => undefined);
+    return run;
+  }
+
+  private async write(file: ProgramFile): Promise<void> {
+    await mkdir(dirname(this.path), { recursive: true });
+    const temporary = `${this.path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+      await writeFile(temporary, `${JSON.stringify(file, null, 2)}\n`, "utf8");
+      await retryOnContention(() => rename(temporary, this.path));
+    } catch (error) {
+      await rm(temporary, { force: true });
+      throw error;
+    }
+  }
+
+  private async withLock(work: () => Promise<void>): Promise<void> {
+    const lockPath = `${this.path}.lock`;
+    await mkdir(dirname(this.path), { recursive: true });
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+      try {
+        const handle = await open(lockPath, "wx");
+        await handle.close();
+        break;
+      } catch (error) {
+        if (!isContention(error) || Date.now() > deadline) throw error;
+        try {
+          const { mtimeMs } = await stat(lockPath);
+          if (Date.now() - mtimeMs > STALE_LOCK_MS) await rm(lockPath, { force: true });
+        } catch {
+          // The lock went away: try again
+        }
+        await pause(10 + Math.random() * 20);
+      }
+    }
+    try {
+      await work();
+    } finally {
+      await rm(lockPath, { force: true });
+    }
+  }
+}

package/src/program-store/index.ts

@@ -0,0 +1,17 @@
+/**
+ * The program store (roadmap 3.2): programs of procedure.define that outlive the process.
+ */
+
+export type { ProgramStore, StoredProgram } from "./types.js";
+export { checkStoredProgram } from "./types.js";
+export { MemoryProgramStore } from "./memory.js";
+export { FileProgramStore } from "./file.js";
+export { CollectionProgramStore } from "./collection.js";
+export { attachProgramStore, detachProgramStore, getProgramStore } from "./attach.js";
+export {
+  procedureStoreProcedure,
+  procedureLoadProcedure,
+  procedureSyncProcedure,
+  procedureRemoteProcedure,
+  programStoreProcedures,
+} from "./procedures.js";

package/src/program-store/memory.ts

@@ -0,0 +1,30 @@
+/**
+ * A program store in memory: for tests, and for a process that keeps its programs only while it
+ * runs. Each read and write copies the record, so a caller that changes a result does not change
+ * the store.
+ */
+
+import { byKey, checkStoredProgram, keyMatches, type ProgramStore, type StoredProgram } from "./types.js";
+
+export class MemoryProgramStore implements ProgramStore {
+  readonly kind = "memory";
+  private readonly programs = new Map<string, StoredProgram>();
+
+  async get(key: string): Promise<StoredProgram | undefined> {
+    const program = this.programs.get(key);
+    return program ? structuredClone(program) : undefined;
+  }
+
+  async list(prefix?: string): Promise<StoredProgram[]> {
+    return byKey([...this.programs.values()].filter((p) => keyMatches(p.key, prefix)).map((p) => structuredClone(p)));
+  }
+
+  async put(program: StoredProgram): Promise<void> {
+    const checked = checkStoredProgram(structuredClone(program));
+    this.programs.set(checked.key, checked);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.programs.delete(key);
+  }
+}