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

.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.

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

@@ -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/package.json

@@ -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/src/StackSnapshotRecord.ts

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

extensions/plugin-stack-persistence/src/StackSnapshotStorage.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/StackSnapshotStrategy.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/errors.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/index.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/stackPersistencePlugin.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);
+      },
+    };
+  };
+}

extensions/plugin-stack-persistence/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "jsx": "preserve",
+    "module": "preserve",
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist"
+  },
+  "include": ["./src/**/*"]
+}

yarn.lock

@@ -6000,6 +6000,21 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@stackflow/plugin-stack-persistence@workspace:extensions/plugin-stack-persistence":
+  version: 0.0.0-use.local
+  resolution: "@stackflow/plugin-stack-persistence@workspace:extensions/plugin-stack-persistence"
+  dependencies:
+    "@stackflow/core": "npm:^3.0.0"
+    "@stackflow/esbuild-config": "npm:^1.0.3"
+    "@types/node": "npm:^20.14.9"
+    esbuild: "npm:^0.23.0"
+    rimraf: "npm:^3.0.2"
+    typescript: "npm:^5.5.3"
+  peerDependencies:
+    "@stackflow/core": ^3.0.0
+  languageName: unknown
+  linkType: soft
+
 "@stackflow/react-ui-core@npm:^1.3.6, @stackflow/react-ui-core@workspace:extensions/react-ui-core":
   version: 0.0.0-use.local
   resolution: "@stackflow/react-ui-core@workspace:extensions/react-ui-core"