@nwire/store-file 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @nwire/store-file
+
+> File-snapshot `ActorStore` + `ProjectionStore` — survives process restart, no DB.
+
+## What it does
+
+Persists actor state and projection rows to a single JSON file. Writes are debounced (50 ms) to coalesce bursts; tenant-partitioned. Not a production database — `@nwire/store-mongo` (or future `-postgres`, `-dynamodb`) for prod. Useful for dev/CI without infrastructure.
+
+## Install
+
+```bash
+pnpm add @nwire/store-file
+```
+
+## Quick start
+
+```ts
+import { FileSnapshotStore, FileSnapshotProjectionView } from "@nwire/store-file";
+import { createApp } from "@nwire/forge";
+
+const store = new FileSnapshotStore("./data/snapshot.json");
+const projView = new FileSnapshotProjectionView(store);
+
+const app = createApp("learnflow", {
+  modules,
+  actorStore: store,
+  projectionStore: projView,
+});
+```
+
+## API surface
+
+- `FileSnapshotStore(path)` — implements `ActorStore`.
+- `FileSnapshotProjectionView(store)` — implements `ProjectionStore` against the same snapshot.
+
+## When to use
+
+Dev environments without a database, CI pipelines that need persistence across test phases, tiny single-node apps. Fits L2/L3.
+
+## Standalone use
+
+For developers using `@nwire/store-file` **without the rest of Nwire** — pair it with any TypeScript project, any container, any HTTP framework.
+
+```ts
+// See the package's main entry (src/) for the standalone surface.
+// The exports below work without @nwire/app or @nwire/forge.
+import {} from /* ...standalone exports... */ "@nwire/store-file";
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack — register it via `app.use(...)` or it auto-wires when you compose `createApp({ modules })`.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  /* ...config... */
+});
+// Adapter/plugin wiring happens here when applicable.
+```
+
+## See also
+
+- [Architecture sketch §05 — Adapters tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/store-mongo](../nwire-store-mongo)

package/dist/__tests__/store-file.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * File-snapshot store — persists actor + projection state to disk; survives
+ * a "process restart" (re-instantiating the store from the same path).
+ */
+export {};
+//# sourceMappingURL=store-file.test.d.ts.map

package/dist/__tests__/store-file.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-file.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/store-file.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/__tests__/store-file.test.js

@@ -0,0 +1,109 @@
+/**
+ * File-snapshot store — persists actor + projection state to disk; survives
+ * a "process restart" (re-instantiating the store from the same path).
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { z } from "zod";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import { defineEvent } from "@nwire/messages";
+import * as forge from "@nwire/forge";
+import { FileSnapshotStore, FileSnapshotProjectionView } from "../store-file";
+const { defineAction, defineActor, defineHandler, defineProjection, eventFactory, Runtime } = forge;
+const TodoCreatedEventDef = defineEvent({
+    name: "todos.created",
+    schema: z.object({ todoId: z.string(), title: z.string() }),
+});
+const TodoCreated = eventFactory(TodoCreatedEventDef);
+const TodoActorData = z.object({
+    todoId: z.string(),
+    title: z.string().optional(),
+});
+const Todo = defineActor("todo", {
+    schema: TodoActorData,
+    key: "todoId",
+    initial: "open",
+    states: {
+        open: {
+            on: {
+                [TodoCreated.name]: {
+                    assign: (_, event) => {
+                        const e = event;
+                        return { todoId: e.todoId, title: e.title };
+                    },
+                },
+            },
+        },
+    },
+});
+const TodosByOwner = defineProjection("todos-by-owner", {
+    listens: [TodoCreatedEventDef],
+    initial: () => ({}),
+    on: {
+        [TodoCreatedEventDef.name]: (state, event) => {
+            const e = event;
+            return { ...state, [e.todoId]: { todoId: e.todoId, title: e.title } };
+        },
+    },
+});
+const createTodo = defineAction({
+    name: "todos.create",
+    schema: z.object({ todoId: z.string(), title: z.string() }),
+});
+const createTodoHandler = defineHandler(createTodo, async (input) => TodoCreated({ todoId: input.todoId, title: input.title }));
+describe("FileSnapshotStore — actor + projection state survives restart", () => {
+    let tmpDir;
+    let snapshotPath;
+    beforeEach(async () => {
+        tmpDir = await mkdtemp(join(tmpdir(), "amit-snapshot-"));
+        snapshotPath = join(tmpDir, "snapshot.json");
+    });
+    afterEach(async () => {
+        await rm(tmpDir, { recursive: true, force: true });
+    });
+    it("saves and reloads actor + projection state from the snapshot file", async () => {
+        const store1 = new FileSnapshotStore(snapshotPath);
+        const projView1 = new FileSnapshotProjectionView(store1);
+        const r1 = new Runtime({ actorStore: store1, projectionStore: projView1 });
+        r1.registerActor(Todo);
+        r1.registerHandler(createTodoHandler);
+        r1.registerProjection(TodosByOwner);
+        await r1.dispatch(createTodo, { todoId: "t-1", title: "Buy milk" });
+        await r1.dispatch(createTodo, { todoId: "t-2", title: "Walk dog" });
+        await store1.flush();
+        // "Restart" — fresh store + runtime against the same file.
+        const store2 = new FileSnapshotStore(snapshotPath);
+        const projView2 = new FileSnapshotProjectionView(store2);
+        const r2 = new Runtime({ actorStore: store2, projectionStore: projView2 });
+        r2.registerActor(Todo);
+        r2.registerProjection(TodosByOwner);
+        const t1 = await store2.load("todo", "t-1");
+        const t2 = await store2.load("todo", "t-2");
+        expect(t1).not.toBeNull();
+        expect(t2).not.toBeNull();
+        expect((t1?.data).title).toBe("Buy milk");
+        expect((t2?.data).title).toBe("Walk dog");
+        const proj = await projView2.load("todos-by-owner");
+        expect(proj).not.toBeNull();
+        expect(proj?.["t-1"]?.title).toBe("Buy milk");
+        expect(proj?.["t-2"]?.title).toBe("Walk dog");
+    });
+    it("preserves tenant partitioning across restart", async () => {
+        const store = new FileSnapshotStore(snapshotPath);
+        const proj = new FileSnapshotProjectionView(store);
+        const r = new Runtime({ actorStore: store, projectionStore: proj });
+        r.registerActor(Todo);
+        r.registerHandler(createTodoHandler);
+        const { seedEnvelope } = await import("@nwire/forge");
+        await r.dispatch(createTodo, { todoId: "t-1", title: "A" }, seedEnvelope({ tenant: "tlv" }));
+        await r.dispatch(createTodo, { todoId: "t-1", title: "B" }, seedEnvelope({ tenant: "jlm" }));
+        await store.flush();
+        const store2 = new FileSnapshotStore(snapshotPath);
+        const a = await store2.load("todo", "t-1", "tlv");
+        const b = await store2.load("todo", "t-1", "jlm");
+        expect((a?.data).title).toBe("A");
+        expect((b?.data).title).toBe("B");
+    });
+});
+//# sourceMappingURL=store-file.test.js.map

package/dist/__tests__/store-file.test.js.map

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

package/dist/file-snapshot-store.d.ts

@@ -0,0 +1,60 @@
+/**
+ * File-snapshot stores — persist actor + projection state to a JSON file on
+ * disk. Demonstrates the swappable-store contract; survives a process restart;
+ * not intended as a production database.
+ *
+ * Writes are debounced: every save schedules a flush 50ms in the future,
+ * coalescing bursts (e.g. inside a single dispatch's actor + projection + DLQ
+ * writes). `flush()` waits for any pending write to complete — call it before
+ * shutdown or before reading the file externally.
+ *
+ * For production: write `MongoActorStore` / `MongoProjectionStore` against
+ * the same `ActorStore` / `ProjectionStore` interfaces. Same shape; just
+ * different storage primitives.
+ */
+import type * as forge from "@nwire/forge";
+type ActorStore = forge.ActorStore;
+type ActorInstance = forge.ActorInstance;
+type ProjectionStore = forge.ProjectionStore;
+/**
+ * File-backed actor store. Pair with `FileSnapshotProjectionView` (below)
+ * to share the same JSON file for projections — both stores use the same
+ * underlying `state` field via the view's wrapper.
+ */
+export declare class FileSnapshotStore implements ActorStore {
+    private readonly path;
+    private state;
+    private loaded;
+    private pendingWrite;
+    private writePromise;
+    constructor(path: string);
+    private actorCacheKey;
+    private projectionCacheKey;
+    private ensureLoaded;
+    private scheduleFlush;
+    private persistNow;
+    /**
+     * Wait for any pending debounced write, then force a final write. Call
+     * before shutdown or before reading the file externally.
+     */
+    flush(): Promise<void>;
+    load(actorName: string, key: string, tenant?: string): Promise<ActorInstance | null>;
+    save(instance: ActorInstance): Promise<void>;
+    exists(actorName: string, key: string, tenant?: string): Promise<boolean>;
+    listInstances(actorName: string, tenant?: string): Promise<readonly ActorInstance[]>;
+    loadProjection<TState = unknown>(projectionName: string, tenant?: string): Promise<TState | null>;
+    saveProjection<TState = unknown>(projectionName: string, state: TState, tenant?: string): Promise<void>;
+}
+/**
+ * Adapter: `FileSnapshotStore` exposes both interfaces but `ProjectionStore`
+ * wants `load`/`save` (not the prefixed names that would clash with `ActorStore`).
+ * This thin wrapper presents the projection face.
+ */
+export declare class FileSnapshotProjectionView implements ProjectionStore {
+    private readonly store;
+    constructor(store: FileSnapshotStore);
+    load<TState = unknown>(name: string, tenant?: string): Promise<TState | null>;
+    save<TState = unknown>(name: string, state: TState, tenant?: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=file-snapshot-store.d.ts.map

package/dist/file-snapshot-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-snapshot-store.d.ts","sourceRoot":"","sources":["../src/file-snapshot-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAE3C,KAAK,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;AACnC,KAAK,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;AAEzC,KAAK,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC;AAU7C;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,YAAY,CAAoC;gBAE5C,IAAI,EAAE,MAAM;IAIxB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,kBAAkB;YAIZ,YAAY;IAe1B,OAAO,CAAC,aAAa;YAWP,UAAU;IAMxB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAWtB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAMxF,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB5C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAK7E,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IAapF,cAAc,CAAC,MAAM,GAAG,OAAO,EACnC,cAAc,EAAE,MAAM,EACtB,MAAM,GAAE,MAAW,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAOnB,cAAc,CAAC,MAAM,GAAG,OAAO,EACnC,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAW,GAClB,OAAO,CAAC,IAAI,CAAC;CAWjB;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,YAAW,eAAe;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,iBAAiB;IAErD,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAG7E,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGpF"}

package/dist/file-snapshot-store.js

@@ -0,0 +1,160 @@
+/**
+ * File-snapshot stores — persist actor + projection state to a JSON file on
+ * disk. Demonstrates the swappable-store contract; survives a process restart;
+ * not intended as a production database.
+ *
+ * Writes are debounced: every save schedules a flush 50ms in the future,
+ * coalescing bursts (e.g. inside a single dispatch's actor + projection + DLQ
+ * writes). `flush()` waits for any pending write to complete — call it before
+ * shutdown or before reading the file externally.
+ *
+ * For production: write `MongoActorStore` / `MongoProjectionStore` against
+ * the same `ActorStore` / `ProjectionStore` interfaces. Same shape; just
+ * different storage primitives.
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+const EMPTY = { version: 1, actors: {}, projections: {} };
+/**
+ * File-backed actor store. Pair with `FileSnapshotProjectionView` (below)
+ * to share the same JSON file for projections — both stores use the same
+ * underlying `state` field via the view's wrapper.
+ */
+export class FileSnapshotStore {
+    path;
+    state = EMPTY;
+    loaded = false;
+    pendingWrite = null;
+    writePromise = Promise.resolve();
+    constructor(path) {
+        this.path = path;
+    }
+    actorCacheKey(name, key, tenant) {
+        return `${tenant}::${name}::${key}`;
+    }
+    projectionCacheKey(name, tenant) {
+        return `${tenant}::${name}`;
+    }
+    async ensureLoaded() {
+        if (this.loaded)
+            return;
+        try {
+            const raw = await readFile(this.path, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed?.version === 1) {
+                this.state = parsed;
+            }
+        }
+        catch (err) {
+            // Missing or corrupt file → start empty.
+            void err;
+        }
+        this.loaded = true;
+    }
+    scheduleFlush() {
+        if (this.pendingWrite)
+            return;
+        this.pendingWrite = setTimeout(() => {
+            this.pendingWrite = null;
+            this.writePromise = this.writePromise.then(() => this.persistNow());
+        }, 50);
+        if (typeof this.pendingWrite.unref === "function") {
+            this.pendingWrite.unref();
+        }
+    }
+    async persistNow() {
+        await mkdir(dirname(this.path), { recursive: true }).catch(() => undefined);
+        const serialized = JSON.stringify(this.state);
+        await writeFile(this.path, serialized, "utf8");
+    }
+    /**
+     * Wait for any pending debounced write, then force a final write. Call
+     * before shutdown or before reading the file externally.
+     */
+    async flush() {
+        if (this.pendingWrite) {
+            clearTimeout(this.pendingWrite);
+            this.pendingWrite = null;
+        }
+        await this.writePromise;
+        await this.persistNow();
+    }
+    // ─── ActorStore ──────────────────────────────────────────────────
+    async load(actorName, key, tenant = "") {
+        await this.ensureLoaded();
+        const stored = this.state.actors[this.actorCacheKey(actorName, key, tenant)];
+        return stored ? structuredClone(stored) : null;
+    }
+    async save(instance) {
+        await this.ensureLoaded();
+        const cloned = {
+            actorName: instance.actorName,
+            key: instance.key,
+            tenant: instance.tenant,
+            state: instance.state,
+            data: structuredClone(instance.data),
+            activeTimers: structuredClone(instance.activeTimers),
+        };
+        this.state = {
+            ...this.state,
+            actors: {
+                ...this.state.actors,
+                [this.actorCacheKey(instance.actorName, instance.key, instance.tenant)]: cloned,
+            },
+        };
+        this.scheduleFlush();
+    }
+    async exists(actorName, key, tenant = "") {
+        await this.ensureLoaded();
+        return Boolean(this.state.actors[this.actorCacheKey(actorName, key, tenant)]);
+    }
+    async listInstances(actorName, tenant) {
+        await this.ensureLoaded();
+        const result = [];
+        for (const value of Object.values(this.state.actors)) {
+            if (value.actorName !== actorName)
+                continue;
+            if (tenant !== undefined && value.tenant !== tenant)
+                continue;
+            result.push(structuredClone(value));
+        }
+        return result;
+    }
+    // ─── ProjectionStore ─────────────────────────────────────────────
+    async loadProjection(projectionName, tenant = "") {
+        await this.ensureLoaded();
+        const k = this.projectionCacheKey(projectionName, tenant);
+        if (!(k in this.state.projections))
+            return null;
+        return structuredClone(this.state.projections[k]);
+    }
+    async saveProjection(projectionName, state, tenant = "") {
+        await this.ensureLoaded();
+        this.state = {
+            ...this.state,
+            projections: {
+                ...this.state.projections,
+                [this.projectionCacheKey(projectionName, tenant)]: structuredClone(state),
+            },
+        };
+        this.scheduleFlush();
+    }
+}
+/**
+ * Adapter: `FileSnapshotStore` exposes both interfaces but `ProjectionStore`
+ * wants `load`/`save` (not the prefixed names that would clash with `ActorStore`).
+ * This thin wrapper presents the projection face.
+ */
+export class FileSnapshotProjectionView {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    load(name, tenant) {
+        return this.store.loadProjection(name, tenant);
+    }
+    save(name, state, tenant) {
+        return this.store.saveProjection(name, state, tenant);
+    }
+}
+//# sourceMappingURL=file-snapshot-store.js.map

package/dist/file-snapshot-store.js.map

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

package/dist/store-file.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@nwire/store-file` — file-snapshot ActorStore + ProjectionStore.
+ *
+ *   import { FileSnapshotStore, FileSnapshotProjectionView } from '@nwire/store-file'
+ *
+ *   const store = new FileSnapshotStore('./data/snapshot.json')
+ *   const projView = new FileSnapshotProjectionView(store)
+ *
+ *   const app = createApp({ modules, actorStore: store, projectionStore: projView })
+ *
+ * Writes are debounced (50ms) to coalesce bursts; survives process restart;
+ * tenant-partitioned. Not a production database — `@nwire/store-mongo` (or
+ * `-postgres`, `-dynamodb`) for prod. Useful for dev/CI without infrastructure.
+ */
+export { FileSnapshotStore, FileSnapshotProjectionView } from "./file-snapshot-store";
+//# sourceMappingURL=store-file.d.ts.map

package/dist/store-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-file.d.ts","sourceRoot":"","sources":["../src/store-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/store-file.js

@@ -0,0 +1,16 @@
+/**
+ * `@nwire/store-file` — file-snapshot ActorStore + ProjectionStore.
+ *
+ *   import { FileSnapshotStore, FileSnapshotProjectionView } from '@nwire/store-file'
+ *
+ *   const store = new FileSnapshotStore('./data/snapshot.json')
+ *   const projView = new FileSnapshotProjectionView(store)
+ *
+ *   const app = createApp({ modules, actorStore: store, projectionStore: projView })
+ *
+ * Writes are debounced (50ms) to coalesce bursts; survives process restart;
+ * tenant-partitioned. Not a production database — `@nwire/store-mongo` (or
+ * `-postgres`, `-dynamodb`) for prod. Useful for dev/CI without infrastructure.
+ */
+export { FileSnapshotStore, FileSnapshotProjectionView } from "./file-snapshot-store";
+//# sourceMappingURL=store-file.js.map

package/dist/store-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-file.js","sourceRoot":"","sources":["../src/store-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nwire/store-file",
+  "version": "0.7.0",
+  "description": "Nwire — file-snapshot ActorStore + ProjectionStore. JSON snapshot persisted to disk with debounced writes. Survives process restart; tenant-partitioned. Dev/CI use, not production.",
+  "keywords": [
+    "actor-store",
+    "adapter",
+    "file",
+    "nwire",
+    "projection-store",
+    "snapshot",
+    "store"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/store-file.js",
+  "types": "./dist/store-file.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/store-file.js",
+      "types": "./dist/store-file.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/forge": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "zod": "^4.0.0",
+    "@nwire/messages": "0.7.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}