prismcast 1.9.0 → 1.10.0

package/dist/config/persistence.context.js

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+const { promises: fsPromises } = fs;
+/**
+ * Builds the default StorageBackend wired to node:fs/promises. The returned adapter is stateless - every call delegates to fsPromises with the framework's
+ * documented contract (UTF-8 encoding for text I/O, recursive mkdir, native error propagation including the ENOENT code that the framework's branch detection
+ * relies on). Sharing one default instance across every store in the process is safe and cheap; persistence.ts caches a single one at module load.
+ * @returns A StorageBackend implementation backed by the real filesystem via node:fs/promises.
+ */
+export function createDefaultStorageBackend() {
+    return {
+        access: async (path) => fsPromises.access(path),
+        copyFile: async (source, destination) => fsPromises.copyFile(source, destination),
+        mkdir: async (path) => {
+            // The framework only ever uses recursive mkdir, so the adapter bakes that in rather than exposing the options bag through the StorageBackend surface.
+            await fsPromises.mkdir(path, { recursive: true });
+        },
+        readFile: async (path) => fsPromises.readFile(path, "utf-8"),
+        readdir: async (path) => fsPromises.readdir(path),
+        rename: async (source, destination) => fsPromises.rename(source, destination),
+        stat: async (path) => {
+            // Project Stats down to the field the framework actually uses (mtimeMs for snapshot pruning). Hides the wider Stats surface so backend implementers do not
+            // have to fabricate fields that the framework would never read.
+            const result = await fsPromises.stat(path);
+            return { mtimeMs: result.mtimeMs };
+        },
+        unlink: async (path) => fsPromises.unlink(path),
+        writeFile: async (path, content) => fsPromises.writeFile(path, content, "utf-8")
+    };
+}
+//# sourceMappingURL=persistence.context.js.map

package/dist/config/persistence.context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.context.js","sourceRoot":"","sources":["../../src/config/persistence.context.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B;IAEzC,OAAO;QAEL,MAAM,EAAE,KAAK,EAAE,IAAY,EAAiB,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC;QAEtE,QAAQ,EAAE,KAAK,EAAE,MAAc,EAAE,WAAmB,EAAiB,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;QAEhH,KAAK,EAAE,KAAK,EAAE,IAAY,EAAiB,EAAE;YAE3C,sJAAsJ;YACtJ,MAAM,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QAED,QAAQ,EAAE,KAAK,EAAE,IAAY,EAAmB,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAErF,OAAO,EAAE,KAAK,EAAE,IAAY,EAAqB,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC;QAE5E,MAAM,EAAE,KAAK,EAAE,MAAc,EAAE,WAAmB,EAAiB,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC;QAE5G,IAAI,EAAE,KAAK,EAAE,IAAY,EAAgC,EAAE;YAEzD,2JAA2J;YAC3J,gEAAgE;YAChE,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAE3C,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QACrC,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,IAAY,EAAiB,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC;QAEtE,SAAS,EAAE,KAAK,EAAE,IAAY,EAAE,OAAe,EAAiB,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC;KAChH,CAAC;AACJ,CAAC"}

package/dist/config/persistence.d.ts

@@ -1,59 +1,157 @@
 /**
- * Error thrown by `mutate()` when the backing file contains invalid JSON. Route handlers can catch this specifically to return 400 instead of 500. Background code
- * paths that swallow errors via try/catch will handle it like any other Error.
+ * Storage backend abstraction. The framework operates on any durable store that exposes the operations below over a path namespace - the default backend lives
+ * in persistence.context.ts and wires real-filesystem I/O via node:fs/promises, but the surface is intentionally narrow so alternative backends (for example, an
+ * in-memory backend used during tests, or a future object-store backend) can plug in without modifying the framework.
+ *
+ * Error contract: when a path is missing, throw a NodeJS.ErrnoException with `code: "ENOENT"` so the framework's existing branch detection (the read() ENOENT
+ * fast path, the doMutate ENOENT-tolerant backup copy, the snapshot ENOENT-tolerant source) continues to behave identically. All other failures (permission
+ * denied, I/O error, etc.) propagate as Error or NodeJS.ErrnoException with their native code so the framework's error logging surfaces accurate diagnostics.
+ *
+ * Encoding: every text operation is UTF-8 by contract. Backends do not accept other encodings - JSON is what the framework writes, and JSON is text.
+ */
+export interface StorageBackend {
+    readonly access: (path: string) => Promise<void>;
+    readonly copyFile: (source: string, destination: string) => Promise<void>;
+    readonly mkdir: (path: string) => Promise<void>;
+    readonly readdir: (path: string) => Promise<string[]>;
+    readonly readFile: (path: string) => Promise<string>;
+    readonly rename: (source: string, destination: string) => Promise<void>;
+    readonly stat: (path: string) => Promise<{
+        mtimeMs: number;
+    }>;
+    readonly unlink: (path: string) => Promise<void>;
+    readonly writeFile: (path: string, content: string) => Promise<void>;
+}
+/**
+ * Error thrown by `mutate()` when the backing file contains invalid JSON and recovery from .bak also failed. Route handlers can catch this specifically to
+ * return 400 instead of 500. Background code paths that swallow errors via try/catch will handle it like any other Error.
  */
 export declare class FileStoreParseError extends Error {
     name: string;
     constructor(label: string, filePath: string, parseMessage: string);
 }
+/**
+ * A single declarative schema migration. Migrations are keyed by their target schema version inside FileStoreOptions.migrations - the framework runs them in
+ * order from the file's current version up to the store's currentSchemaVersion, mutating the in-memory data in place and stamping the new version after each
+ * application.
+ */
+export interface Migration<T> {
+    description: string;
+    apply: (data: T) => void;
+}
+/**
+ * The result of running migrations during a read operation.
+ */
+export interface MigrationResult {
+    applied: string[];
+    fromVersion: number;
+    toVersion: number;
+}
+/**
+ * A single integrity issue detected by a store's validator. Surfaced via logging; the write proceeds regardless of severity.
+ */
+export interface ValidationIssue {
+    category: string;
+    description: string;
+    severity: "warning" | "error";
+}
 /**
  * Result from a read-only file store access. Callers that only need data (export endpoints, API responses) use this without risking a save-back.
  */
 export interface FileStoreReadResult<T> {
     data: T;
+    migrationResult: MigrationResult;
     parseError: boolean;
     parseErrorMessage?: string;
+    recoveredFromBackup: boolean;
 }
 /**
- * Options for creating a file store instance.
+ * Options for creating a file store instance. The first three fields (defaultValue, label, parse, path) are the minimum surface required for any store. The
+ * remaining fields opt in to schema versioning, migrations, and integrity validation - any store can adopt them as its data shape grows.
  * @template T - The in-memory data type that callers mutate.
  */
 export interface FileStoreOptions<T> {
+    backend?: StorageBackend;
     beforeWrite?: (data: T) => unknown;
+    currentSchemaVersion?: number;
     defaultValue: () => T;
+    getSchemaVersion?: (data: T) => number;
     label: string;
+    migrations?: Record<number, Migration<T>>;
     parse: (raw: string) => T;
     path: () => string;
+    recordMigration?: (data: T, description: string) => void;
+    setSchemaVersion?: (data: T, version: number) => void;
+    validate?: (prev: T, next: T) => ValidationIssue[];
 }
 /**
- * A transactional file store that provides atomic writes, serialized mutations, corruption protection, and backup rotation. Callers interact with data through
- * `mutate()` (serialized read-modify-write) and `read()` (read-only access). Direct file I/O is never exposed.
+ * A transactional file store that provides atomic writes, serialized mutations, corruption recovery, snapshots, declarative migrations, and integrity
+ * validation. Callers interact with data through `mutate()` (serialized read-modify-write) and `read()` (read-only access). Direct file I/O is never exposed.
  * @template T - The in-memory data type that callers mutate.
  */
 export interface FileStore<T> {
     /**
-     * Serialized read-modify-write operation. The mutation function receives the current data and modifies it in place. The store handles atomicity,
-     * serialization, corruption guard, backup, and beforeWrite transforms.
+     * Verifies migrations are up-to-date and persists the upgrade if any were applied. Idempotent - when the file is already at the current schema version this
+     * is a single read with no write. Called once per store at startup by the release boot coordinator after snapshots have been captured.
+     * @returns The migration result so callers can log per-store outcomes.
+     */
+    ensureMigrated(): Promise<MigrationResult>;
+    /**
+     * Serialized read-modify-write operation. The mutation function receives the current data (already migrated to the latest schema version) and modifies it in
+     * place. The store handles atomicity, serialization, corruption guard, backup, validation, and beforeWrite transforms.
      * @param fn - Mutation function. Receives current data. Modify in place; return value is ignored.
-     * @throws FileStoreParseError if the file contains invalid JSON (corruption guard).
+     * @throws FileStoreParseError if the file contains invalid JSON and no usable backup is available (corruption guard).
      */
     mutate(fn: (current: T) => void): Promise<void>;
     /**
-     * Read-only access to the current file contents. Returns the parsed data with parse status. Does not acquire the serialization lock...safe to call concurrently.
+     * Read-only access to the current file contents. Returns the parsed data with parse status, recovery status, and migration result. Does not acquire the
+     * serialization lock - safe to call concurrently. Migrations run in-memory but are not persisted by read() alone; callers who need to persist an upgrade
+     * should use ensureMigrated() (or do so implicitly via mutate()).
      */
     read(): Promise<FileStoreReadResult<T>>;
+    /**
+     * Creates a labeled snapshot copy of the current file inside a `snapshots/` subdirectory next to the source file (named `<file>.<label>`). Idempotent on
+     * the label - if a snapshot with the same label already exists, this is a no-op. After a successful create, prunes older snapshots for the same file so at
+     * most SNAPSHOT_RETENTION remain (by mtime). Used to preserve a guaranteed restore point at release boundaries before any migrations can mutate the file.
+     * @param label - The filename suffix appended after the source file's basename and a dot. Typically a version string like `pre-v1.10.0`.
+     */
+    snapshot(label: string): Promise<void>;
 }
+/**
+ * Snapshots every registered store under the given label. Used at startup to capture a guaranteed restore point at release boundaries before any migrations
+ * can run. The label is typically `pre-v<package-version>` so each release boot leaves a snapshot named for the version that was running.
+ *
+ * Snapshots run in parallel since they are independent file copies. Failures within individual snapshots are logged by the snapshot helper itself and do not
+ * propagate; the coordinator always returns successfully so a single store's snapshot failure does not block startup.
+ * @param label - The snapshot label suffix.
+ */
+export declare function snapshotAllForRelease(label: string): Promise<void>;
+/**
+ * Runs ensureMigrated() on every registered store. Called once at startup after snapshotAllForRelease so that any pending migrations execute against a file
+ * that already has its pre-version snapshot captured. Idempotent within a release - subsequent boots see no pending migrations and skip the upgrade write.
+ */
+export declare function ensureAllMigrated(): Promise<void>;
 /**
  * Creates a transactional file store instance. Each instance owns a single JSON file and provides serialized, atomic access to it.
  *
  * Safety guarantees:
  * - **Atomic writes:** data is written to a `.tmp` file and renamed over the original. `rename()` is atomic on POSIX and NTFS.
  * - **Serialization:** a promise chain ensures only one `mutate()` runs at a time. Concurrent callers queue behind the active operation.
- * - **Corruption guard:** `mutate()` throws `FileStoreParseError` if the file contains invalid JSON, preventing save-over-corrupt cascades.
- * - **Backup rotation:** before each write, the current file is copied to `.bak`. One-deep rotation provides a recovery path.
+ * - **Corruption guard:** `mutate()` throws `FileStoreParseError` if both the main file and its `.bak` are unparseable, preventing save-over-corrupt cascades.
+ * - **Backup rotation:** before each write, the current file is copied to `.bak`. One-deep rotation provides a recovery path for the previous good version.
+ * - **Auto-recovery:** when the main file fails to parse, `read()` transparently restores from `.bak` (atomic temp+rename) and surfaces `recoveredFromBackup`
+ *   on the result so callers can banner the event. Only when both files are unparseable does the result fall back to defaults with `parseError: true`.
+ * - **Versioned snapshots:** `snapshot(label)` writes a copy of the current file into a `snapshots/` subdirectory, named `<file>.<label>`, idempotent on the
+ *   label. After each successful create the directory is pruned to at most SNAPSHOT_RETENTION entries per file (by mtime).
+ * - **Declarative migrations:** when `migrations` and `currentSchemaVersion` are provided, `read()` runs any pending migrations in memory and returns the
+ *   upgraded data. `ensureMigrated()` persists the upgrade if any were applied. Migrations are version-keyed and idempotent across boots.
+ * - **Pre-write validation:** when `validate` is provided, `mutate()` invokes it with the pre-mutation snapshot and post-mutation state, surfacing integrity
+ *   issues via the log.
+ * - **Post-write integrity check:** after every successful rename, the file is read back and byte-compared against what was written. On mismatch, the .bak is
+ *   restored and the call throws - catches encoder bugs, partial writes, and any filesystem-level corruption that happened during the write.
  *
  * @template T - The in-memory data type that callers mutate.
  * @param options - Store configuration.
- * @returns A FileStore instance with `read()` and `mutate()` methods.
+ * @returns A FileStore instance. Auto-registers in the global store registry so the release boot coordinator can snapshot it.
  */
 export declare function createFileStore<T>(options: FileStoreOptions<T>): FileStore<T>;