feat(plugin-stack-persistence): navigation context persistence plugin (#727)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: ENvironmentSet

.changeset/calm-stacks-persist.md

@@ -0,0 +1,5 @@
+---
+"@stackflow/plugin-stack-persistence": major
+---
+
+Package initial release; Persist and restore complete Stackflow navigation snapshots with optional metadata reuse strategies and explicit load/save error handling.

.pnp.cjs

@@ -0,0 +1,29 @@
+const { context } = require("esbuild");
+const config = require("@stackflow/esbuild-config");
+const pkg = require("./package.json");
+
+const watch = process.argv.includes("--watch");
+const external = Object.keys({
+  ...pkg.dependencies,
+  ...pkg.peerDependencies,
+});
+
+Promise.all([
+  context({
+    ...config({}),
+    format: "cjs",
+    external,
+  }).then((ctx) =>
+    watch ? ctx.watch() : ctx.rebuild().then(() => ctx.dispose()),
+  ),
+  context({
+    ...config({}),
+    format: "esm",
+    outExtension: {
+      ".js": ".mjs",
+    },
+    external,
+  }).then((ctx) =>
+    watch ? ctx.watch() : ctx.rebuild().then(() => ctx.dispose()),
+  ),
+]).catch(() => process.exit(1));

extensions/plugin-stack-persistence/esbuild.config.js

@@ -0,0 +1,52 @@
+{
+  "name": "@stackflow/plugin-stack-persistence",
+  "version": "0.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/daangn/stackflow.git",
+    "directory": "extensions/plugin-stack-persistence"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "yarn build:js && yarn build:dts",
+    "build:dts": "tsc --emitDeclarationOnly",
+    "build:js": "node ./esbuild.config.js",
+    "clean": "rimraf dist",
+    "dev": "yarn build:js --watch && yarn build:dts --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@stackflow/core": "^3.0.0",
+    "@stackflow/esbuild-config": "^1.0.3",
+    "@types/node": "^20.14.9",
+    "esbuild": "^0.23.0",
+    "rimraf": "^3.0.2",
+    "typescript": "^5.5.3"
+  },
+  "peerDependencies": {
+    "@stackflow/core": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "ultra": {
+    "concurrent": [
+      "dev",
+      "build"
+    ]
+  }
+}

extensions/plugin-stack-persistence/package.json

@@ -0,0 +1,6 @@
+import type { StackSnapshot } from "@stackflow/core";
+
+export type StackSnapshotRecord<Metadata> = {
+  snapshot: StackSnapshot;
+  metadata: Metadata;
+};

extensions/plugin-stack-persistence/src/StackSnapshotRecord.ts

@@ -0,0 +1,6 @@
+import type { StackSnapshotRecord } from "./StackSnapshotRecord";
+
+export interface StackSnapshotStorage<Metadata> {
+  load(): StackSnapshotRecord<Metadata> | null;
+  save(record: StackSnapshotRecord<Metadata>): Promise<void>;
+}

extensions/plugin-stack-persistence/src/StackSnapshotStorage.ts

@@ -0,0 +1,13 @@
+import type { StackSnapshot } from "@stackflow/core";
+import type { StackSnapshotRecord } from "./StackSnapshotRecord";
+
+export interface StackSnapshotStrategy<Metadata> {
+  createMetadata(args: {
+    snapshot: StackSnapshot;
+  }): Metadata;
+
+  shouldReuse(args: {
+    record: StackSnapshotRecord<Metadata>;
+    initialContext: unknown;
+  }): boolean;
+}

extensions/plugin-stack-persistence/src/StackSnapshotStrategy.ts

@@ -0,0 +1,19 @@
+export class StackSnapshotRecordSaveError extends Error {
+  cause: unknown;
+
+  constructor(cause: unknown, message?: string) {
+    super(message ?? "failed to save stack snapshot record");
+    this.name = "StackSnapshotRecordSaveError";
+    this.cause = cause;
+  }
+}
+
+export class StackSnapshotRecordLoadError extends Error {
+  cause: unknown;
+
+  constructor(cause: unknown, message?: string) {
+    super(message ?? "failed to load stack snapshot record");
+    this.name = "StackSnapshotRecordLoadError";
+    this.cause = cause;
+  }
+}

extensions/plugin-stack-persistence/src/errors.ts

@@ -0,0 +1,11 @@
+export {
+  StackSnapshotRecordSaveError,
+  StackSnapshotRecordLoadError
+} from "./errors";
+export { StackSnapshotRecord } from "./StackSnapshotRecord";
+export { StackSnapshotStorage } from "./StackSnapshotStorage";
+export { StackSnapshotStrategy } from "./StackSnapshotStrategy";
+export {
+  StackPersistencePluginOptions,
+  stackPersistencePlugin,
+} from "./stackPersistencePlugin";

extensions/plugin-stack-persistence/src/index.ts

@@ -0,0 +1,67 @@
+import type {
+  StackflowActions,
+  StackflowPlugin,
+} from "@stackflow/core";
+import { StackSnapshotRecordSaveError, StackSnapshotRecordLoadError } from "./errors";
+import type { StackSnapshotStorage } from "./StackSnapshotStorage";
+import type { StackSnapshotStrategy } from "./StackSnapshotStrategy";
+
+export type StackPersistencePluginOptions<Metadata> = {
+  storage: StackSnapshotStorage<Metadata>;
+  strategy: StackSnapshotStrategy<Metadata>;
+  onRecordLoadError?: (error: StackSnapshotRecordLoadError) => void;
+  onRecordSaveError?: (error: StackSnapshotRecordSaveError) => void;
+  onLoadError?: NonNullable<ReturnType<StackflowPlugin>['onLoadError']>;
+}
+
+export function stackPersistencePlugin<Metadata>(
+  { storage, strategy, onRecordLoadError, onRecordSaveError, onLoadError }: StackPersistencePluginOptions<Metadata>,
+): StackflowPlugin {
+  return () => {
+    const saveIfIdle = (actions: StackflowActions) => {
+      const stack = actions.getStack();
+
+      if (stack.globalTransitionState !== "idle") return;
+
+      const snapshot = actions.captureSnapshot();
+      const metadata = strategy.createMetadata({ snapshot });
+
+      storage.save({
+        snapshot,
+        metadata
+      }).catch(error => {
+        if (onRecordSaveError) return onRecordSaveError(error);
+        else throw error;
+      });
+    }
+
+    return {
+      key: "@stackflow/plugin-stack-persistence",
+      provideSnapshot({ initialContext }) {
+        try {
+          const record = storage.load();
+
+          if (!record)
+            return null;
+          if (strategy?.shouldReuse({ record, initialContext }) === false)
+            return null;
+
+          return record.snapshot;
+        } catch (error) {
+          onRecordLoadError?.(new StackSnapshotRecordLoadError(error));
+
+          return null;
+        }
+      },
+      onLoadError(...args) {
+        return onLoadError?.(...args) ?? { policy: "recover" }
+      },
+      onInit({ actions }) {
+        saveIfIdle(actions);
+      },
+      onChanged({ actions }) {
+        saveIfIdle(actions);
+      },
+    };
+  };
+}