@adobe/data-persistence 0.9.90

package/dist/provider/mount.js

@@ -0,0 +1,20 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Mount a persistence session using the supplied provider.
+ *
+ * This is the single entry point for all persistence. The provider
+ * encapsulates the storage strategy — Node.js `fs`, OPFS, in-memory, or
+ * a custom cloud implementation.
+ *
+ * ```ts
+ * import { mount } from "@adobe/data-persistence";
+ * import { createNodeFsProvider } from "@adobe/data-persistence/node";
+ *
+ * const m = await mount(createNodeFsProvider("/tmp/my-db"), database);
+ * await m.service.load();
+ * // ...run app...
+ * await m.dispose();
+ * ```
+ */
+export const mount = (provider, database, options) => provider.mount(database, options);
+//# sourceMappingURL=mount.js.map

package/dist/provider/mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.js","sourceRoot":"","sources":["../../src/provider/mount.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAKvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACjB,QAA6B,EAC7B,QAA0D,EAC1D,OAA8B,EACL,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC"}

package/dist/provider/persistence-provider.d.ts

@@ -0,0 +1,63 @@
+import type { Database } from "@adobe/data/ecs";
+import type { IncrementalPersistenceService } from "../service/incremental-persistence-service.js";
+/**
+ * Options common to all persistence provider mounts.
+ */
+export interface ProviderMountOptions {
+    /**
+     * Automatically persist every non-transient, persistent transaction.
+     * Defaults to `true`.
+     */
+    readonly autoPersist?: boolean;
+    /**
+     * Checkpoint cadence. The first condition that fires triggers a checkpoint.
+     */
+    readonly checkpoint?: {
+        readonly everyNTransactions?: number;
+        readonly idleMs?: number;
+    };
+}
+/**
+ * A fully-wired persistence session returned by a `PersistenceProvider`.
+ *
+ * Obtained via `mount(provider, database, opts)`. Call `dispose()` to
+ * tear everything down in the correct order — do not call
+ * `service.dispose()` directly.
+ */
+export interface PersistenceMount {
+    /** The ready-to-use persistence service. */
+    readonly service: IncrementalPersistenceService;
+    /**
+     * Tear down the session: flushes in-flight writes, stops observers,
+     * releases worker/file handles. After this resolves the mount is
+     * unusable.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Pluggable persistence back-end.
+ *
+ * Implementers fall into two patterns:
+ *
+ * **Pattern A — byte-range storage** (OPFS, `node:fs`, byte-range capable
+ * cloud): Implement `PersistenceBackend` + `RandomAccessFile` and build a
+ * provider that wraps them with `createInprocessTransport` +
+ * `createIncrementalPersistenceService`. Reuses the full journal/manifest
+ * machinery.
+ *
+ * **Pattern B — whole-file storage** (object-storage blobs, cloud APIs
+ * without byte-range support): Implement `PersistenceProvider` directly.
+ * Override `mount()` to observe `database.observe.transactions`, accumulate
+ * deltas, and push a complete blob on `flush`/`checkpoint`. The journal and
+ * manifest logic are entirely provider-owned.
+ */
+export interface PersistenceProvider {
+    /** Human-readable identifier used in diagnostics. */
+    readonly providerName: string;
+    /**
+     * Build a fully-wired persistence mount for `database`. The returned
+     * `PersistenceMount` owns the full lifecycle; call `mount.dispose()`
+     * when done.
+     */
+    mount(database: Database<any, any, any, any, any, any, any, any>, options?: ProviderMountOptions): Promise<PersistenceMount>;
+}

package/dist/provider/persistence-provider.js

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export {};
+//# sourceMappingURL=persistence-provider.js.map

package/dist/provider/persistence-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-provider.js","sourceRoot":"","sources":["../../src/provider/persistence-provider.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/provider/persistence-provider.test.d.ts

@@ -0,0 +1,9 @@
+import type { PersistenceProvider } from "./persistence-provider.js";
+/**
+ * Run the full provider lifecycle contract against any provider.
+ * Call this from environment-specific test files to validate new providers.
+ *
+ * NOTE: the provider must support creating a fresh, empty persistence root
+ * on each call to `mount` (or accept a factory so each test gets isolation).
+ */
+export declare const runProviderContractTests: (providerName: string, makeProvider: () => PersistenceProvider) => void;

package/dist/provider/persistence-provider.test.js

@@ -0,0 +1,139 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// Provider-contract conformance tests.
+//
+// The `runProviderContractTests` helper exercises the full
+// mount → write → flush → checkpoint → dispose → reload lifecycle against
+// any PersistenceProvider. This file drives it against the MemoryProvider
+// (node-only, no I/O). The node-fs and OPFS providers are exercised by
+// their own environment-specific test files.
+import { Database } from "@adobe/data/ecs";
+import { F32 } from "@adobe/data/math";
+import { describe, expect, it } from "vitest";
+import { mount } from "./mount.js";
+import { createMemoryProvider } from "./create-memory-provider.js";
+// ─── Shared schema ────────────────────────────────────────────────────────────
+const entityPlugin = Database.Plugin.create({
+    components: {
+        x: F32.schema,
+        y: F32.schema,
+        label: { type: "string" },
+    },
+    archetypes: {
+        Point: ["x", "y", "label"],
+    },
+    transactions: {
+        createPoint(t, args) {
+            return t.archetypes.Point.insert(args);
+        },
+        movePoint(t, args) {
+            t.update(args.entity, { x: args.x, y: args.y });
+        },
+    },
+});
+const noCheckpoint = { everyNTransactions: 0, idleMs: 0 };
+// ─── Contract test suite (provider-agnostic) ──────────────────────────────────
+/**
+ * Run the full provider lifecycle contract against any provider.
+ * Call this from environment-specific test files to validate new providers.
+ *
+ * NOTE: the provider must support creating a fresh, empty persistence root
+ * on each call to `mount` (or accept a factory so each test gets isolation).
+ */
+export const runProviderContractTests = (providerName, makeProvider) => {
+    describe(`${providerName} — provider contract`, () => {
+        it("mount returns a service with the expected methods", async () => {
+            const provider = makeProvider();
+            const db = Database.create(entityPlugin);
+            const m = await mount(provider, db, { checkpoint: noCheckpoint });
+            expect(typeof m.service.save).toBe("function");
+            expect(typeof m.service.load).toBe("function");
+            expect(typeof m.service.flush).toBe("function");
+            expect(typeof m.service.checkpoint).toBe("function");
+            expect(typeof m.service.dispose).toBe("function");
+            expect(typeof m.dispose).toBe("function");
+            await m.dispose();
+        });
+        it("persists an entity across dispose → re-mount → load", async () => {
+            const provider = makeProvider();
+            const db1 = Database.create(entityPlugin);
+            const m1 = await mount(provider, db1, { checkpoint: noCheckpoint });
+            const entity = db1.transactions.createPoint({ x: 1, y: 2, label: "A" });
+            await m1.service.flush();
+            await m1.service.checkpoint();
+            await m1.dispose();
+            const db2 = Database.create(entityPlugin);
+            const m2 = await mount(provider, db2, { checkpoint: noCheckpoint });
+            await m2.service.load();
+            await m2.dispose();
+            const view = db2.read(entity);
+            expect(view).not.toBeNull();
+            expect(view.label).toBe("A");
+            expect(view.x).toBeCloseTo(1);
+            expect(view.y).toBeCloseTo(2);
+        });
+        it("persists multiple entities with correct values", async () => {
+            const provider = makeProvider();
+            const db1 = Database.create(entityPlugin);
+            const m1 = await mount(provider, db1, { checkpoint: noCheckpoint });
+            const e1 = db1.transactions.createPoint({ x: 10, y: 20, label: "P1" });
+            const e2 = db1.transactions.createPoint({ x: 30, y: 40, label: "P2" });
+            await m1.service.flush();
+            await m1.service.checkpoint();
+            await m1.dispose();
+            const db2 = Database.create(entityPlugin);
+            const m2 = await mount(provider, db2, { checkpoint: noCheckpoint });
+            await m2.service.load();
+            await m2.dispose();
+            expect(db2.read(e1)?.label).toBe("P1");
+            expect(db2.read(e2)?.label).toBe("P2");
+            expect(db2.read(e1)?.x).toBeCloseTo(10);
+            expect(db2.read(e2)?.y).toBeCloseTo(40);
+        });
+        it("reflects updates made after the initial checkpoint via journal replay", async () => {
+            const provider = makeProvider();
+            const db1 = Database.create(entityPlugin);
+            const m1 = await mount(provider, db1, { checkpoint: noCheckpoint });
+            const entity = db1.transactions.createPoint({ x: 0, y: 0, label: "Origin" });
+            await m1.service.flush();
+            await m1.service.checkpoint();
+            // Write after checkpoint — lives only in the journal.
+            db1.transactions.movePoint({ entity: entity, x: 99, y: 88 });
+            await m1.service.flush();
+            // Intentionally no second checkpoint.
+            await m1.dispose();
+            const db2 = Database.create(entityPlugin);
+            const m2 = await mount(provider, db2, { checkpoint: noCheckpoint });
+            await m2.service.load();
+            await m2.dispose();
+            const view = db2.read(entity);
+            expect(view).not.toBeNull();
+            expect(view.x).toBeCloseTo(99);
+            expect(view.y).toBeCloseTo(88);
+        });
+        it("dispose can be called multiple times without error", async () => {
+            const provider = makeProvider();
+            const db = Database.create(entityPlugin);
+            const m = await mount(provider, db, { checkpoint: noCheckpoint });
+            await m.dispose();
+            // Second dispose should be a safe no-op.
+            await m.dispose();
+        });
+        it("mount.service.serviceName is a non-empty string", async () => {
+            const provider = makeProvider();
+            const db = Database.create(entityPlugin);
+            const m = await mount(provider, db, { checkpoint: noCheckpoint });
+            expect(typeof m.service.serviceName).toBe("string");
+            expect(m.service.serviceName.length).toBeGreaterThan(0);
+            await m.dispose();
+        });
+        it("provider.providerName is a non-empty string", () => {
+            const provider = makeProvider();
+            expect(typeof provider.providerName).toBe("string");
+            expect(provider.providerName.length).toBeGreaterThan(0);
+        });
+    });
+};
+// ─── Run against MemoryProvider ───────────────────────────────────────────────
+runProviderContractTests("MemoryProvider", createMemoryProvider);
+//# sourceMappingURL=persistence-provider.test.js.map

package/dist/provider/persistence-provider.test.js.map

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

package/dist/service/component-nonpersistent-durability.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/service/component-nonpersistent-durability.test.js

@@ -0,0 +1,57 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+//
+// A component whose schema is marked `nonPersistent: true` must not be saved.
+// On load it is reconstructed via the hybrid rule: a defaulted one is reset to
+// its default (present); a no-default one is stripped (the entity restores into
+// the reduced archetype). This exercises the full worker/checkpoint/reload path.
+import { Database } from "@adobe/data/ecs";
+import { F32 } from "@adobe/data/math";
+import { beforeEach, describe, expect, it } from "vitest";
+import { createMemoryBackend } from "../backend/memory-backend.js";
+import { createWorkerPersistenceService } from "./create-worker-persistence-service.js";
+const plugin = Database.Plugin.create({
+    components: {
+        value: F32.schema,
+        // Defaulted nonPersistent component → reset to default on load.
+        cache: { type: "number", default: 7, nonPersistent: true },
+        // No-default nonPersistent component → stripped on load.
+        derived: { type: "number", nonPersistent: true },
+        // undefined-default (type-only placeholder, e.g. a GPUBuffer handle) →
+        // treated as no default → stripped on load.
+        gpuRef: { default: undefined, nonPersistent: true },
+    },
+    archetypes: {
+        Item: ["value", "cache", "derived", "gpuRef"],
+    },
+    transactions: {
+        spawn(t, args) {
+            return t.archetypes.Item.insert(args);
+        },
+    },
+});
+const noCheckpoint = { everyNTransactions: 0, idleMs: 0 };
+describe("component-level nonPersistent durability", () => {
+    let backend;
+    beforeEach(() => {
+        backend = createMemoryBackend();
+    });
+    it("does not persist nonPersistent columns: defaulted resets, no-default strips", async () => {
+        const db1 = Database.create(plugin);
+        const svc1 = await createWorkerPersistenceService({ database: db1, backend, checkpoint: noCheckpoint });
+        const e = db1.transactions.spawn({ value: 5, cache: 99, derived: 42, gpuRef: 12345 });
+        await svc1.flush();
+        await svc1.checkpoint();
+        await svc1.dispose();
+        const db2 = Database.create(plugin);
+        const svc2 = await createWorkerPersistenceService({ database: db2, backend, checkpoint: noCheckpoint });
+        await svc2.load();
+        await svc2.dispose();
+        const view = db2.read(e);
+        expect(view).not.toBeNull();
+        expect(view.value).toBe(5); // persistent component preserved
+        expect(view.cache).toBe(7); // defaulted nonPersistent → reset to default
+        expect("derived" in view).toBe(false); // no-default nonPersistent → stripped
+        expect("gpuRef" in view).toBe(false); // null-default nonPersistent → stripped
+    });
+});
+//# sourceMappingURL=component-nonpersistent-durability.test.js.map

package/dist/service/component-nonpersistent-durability.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-nonpersistent-durability.test.js","sourceRoot":"","sources":["../../src/service/component-nonpersistent-durability.test.ts"],"names":[],"mappings":"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"}

package/dist/service/create-incremental-persistence-service.d.ts

@@ -0,0 +1,7 @@
+import type { IncrementalPersistenceService, IncrementalPersistenceServiceOptions } from "./incremental-persistence-service.js";
+/**
+ * Create an {@link IncrementalPersistenceService}. The service subscribes
+ * to the database's transaction observer and writes changes incrementally
+ * via the configured backend / transport.
+ */
+export declare const createIncrementalPersistenceService: (options: IncrementalPersistenceServiceOptions) => Promise<IncrementalPersistenceService>;