nuxt-state 0.0.2 → 0.2.0

package/README.md

@@ -15,8 +15,8 @@ A regular composable runs its factory for every invocation. A composable created
 `defineState` runs its factory lazily, once for the current Nuxt application instance,
 and returns that exact result to every caller in that app.
 
-This is a working prototype for discussion and possible future contribution to Nuxt.
-It is not yet presented as production-ready.
+This is a working open-source prototype for discussion and possible future contribution to
+Nuxt. The API is intentionally narrow and the project is not yet presented as production-ready.
 
 ## Why
 
@@ -41,9 +41,6 @@ export default defineNuxtConfig({
 })
 ```
 
-The package has not been published yet; during development, use this repository as a
-workspace dependency.
-
 ## Usage
 
 Create a state in Nuxt 4's application source directory:
@@ -93,39 +90,119 @@ refs remain computed refs, reactive objects remain reactive, and functions are u
 - The factory is lazy and runs at first use.
 - It runs once per Nuxt app instance.
 - The exact factory result is returned to all callers in that app.
+- The factory runs in a detached Vue effect scope owned by the Nuxt app, so effects and Nuxt
+  composables are not disposed with the first consuming component.
 - A module-local `WeakMap` keys instances by `NuxtApp`, providing request isolation while
   allowing old application instances to be garbage-collected.
 - Separate `defineState()` calls have separate closure-owned caches, including calls in
   the same file.
+- Mutable state used during SSR is restored into the client-created refs and reactive proxies
+  before Vue hydrates the component tree.
 
 Async factories are rejected by TypeScript and guarded at runtime for JavaScript users.
 Expose an async function from synchronous state or use Nuxt's data-fetching APIs instead.
 
-## SSR scope
+## SSR hydration
+
+Since v0.1.0, nuxt-state transparently hydrates mutable top-level members returned by the factory.
+Nuxt injects an internal call-site key at build time; the developer-facing call remains exactly
+`defineState(factory)`.
+
+On the server, the module captures the final values after rendering in one namespaced Nuxt
+payload entry. On the client, it runs the factory normally and patches those values into the
+new refs and reactive proxies before Vue hydration. The returned object is never replaced, so
+computed refs, functions, watchers, and closures created by the client factory remain wired to
+the hydrated state.
 
-v0 guarantees isolation between SSR requests: module-level state does not become a
-process-wide user-state singleton. This is intentionally different from hydration.
+```ts
+export const useAccount = defineState(() => {
+  const count = ref(0)
+  const user = reactive({ name: 'Guest', roles: [] as string[] })
+  const double = computed(() => count.value * 2)
+  const increment = () => count.value++
+
+  return { count, user, double, increment }
+})
+```
 
-v0 does **not** serialize or hydrate arbitrary factory results. A result may contain
-functions, computed refs, class instances, and other runtime-only values. If a state is
-mutated during SSR, the client may recreate the factory's initial state during hydration.
-Do not rely on server mutations transferring to the client yet.
+Nested serializable values inside supported refs and reactive objects are handled by Nuxt's
+payload serializer. Functions, readonly computed refs, and plain runtime objects are recreated
+by the factory rather than serialized. Concurrent SSR requests retain separate Nuxt-app
+registries and cannot share user state.
+
+Snapshot discovery is intentionally limited to mutable members exposed by the factory. Reactive
+state that must survive SSR hydration currently needs to be exposed from the `defineState`
+factory. A private ref captured only by a computed value or function is not visible to the
+snapshot layer; if it is mutated during SSR, its client value can differ and cause a hydration
+mismatch. Discovering closure-private Vue state would require a new explicit API, compiler-level
+analysis, or undocumented reactivity inspection, none of which belongs in v0.2.0.
+
+`useFetch()` can remain inside a synchronous state factory. Its request caching and payload
+hydration still belong to Nuxt; `nuxt-state` neither replaces nor triggers a second fetch
+mechanism. If multiple sibling SSR components must all render completed data, await the returned
+Nuxt `AsyncData` promise in a parent/page as you would with normal Nuxt data fetching.
+
+When a returned `useFetch().data` ref is snapshotted, both Nuxt's data payload and the internal
+state snapshot refer to it. Nuxt's graph serializer preserves the shared object identity, so the
+response body is emitted once rather than copied into the HTML twice. There is still a small
+snapshot-metadata overhead.
+
+## Compatibility
+
+### Supported
+
+- `ref()` and `reactive()`, including nested serializable objects and arrays;
+- `shallowRef()` and `shallowReactive()` with their shallow semantics preserved;
+- `Date`, `Map`, `Set`, shared references, and cyclic graphs supported by Nuxt's payload
+  serializer;
+- readonly computed chains and functions as client-recreated runtime state;
+- readonly views when their mutable source is also returned and hydrated;
+- `useFetch()`, `useAsyncData()`, `callOnce()`, `useCookie()`, `useRuntimeConfig()`, `useRoute()`,
+  and `useRouter()` in valid Nuxt contexts;
+- first use from plugins, route middleware, layouts, pages, and components;
+- state lifetime across client navigation and repeated component mount/unmount.
+
+`useFetch` and `useAsyncData` continue to own their request/payload behavior. nuxt-state's
+snapshot metadata points at the same payload graph rather than serializing response bodies again.
+`callOnce({ mode: 'navigation' })` retains Nuxt's normal per-navigation behavior.
+
+### Characterized or limited
+
+- A readonly view is not independent mutable state. If its mutable source is private, it follows
+  the private-state limitation below.
+- Writable computed refs are not supported hydration state. Vue exposes no public `isComputed`
+  check, and a writable computed currently looks like a mutable ref; restoring it invokes its
+  setter and may cause side effects. Return and hydrate its source refs instead.
+- Mutable reactive values that must survive SSR hydration need to be reachable through the
+  enumerable object returned from the factory.
+- The intended return is a composable-style object. Arbitrary ref, reactive-root, function, or
+  primitive returns still share per app, but the current member-based snapshot format does not
+  hydrate them.
+- Cycles are supported for Nuxt-serializable object graphs, not arbitrary native resources or
+  custom class instances.
 
 ## Current limitations
 
 - Nuxt 4 and Vue 3 only.
 - Synchronous factories only.
 - No persistence or browser-storage integration.
-- No arbitrary-state payload serialization or hydration yet.
+- Hydration is guaranteed for standard and shallow refs/reactives. `customRef()` and writable
+  computed hydration are not supported.
+- Hydrated values must be serializable by Nuxt's payload system; DOM nodes, sockets, functions
+  inside refs, symbols, and arbitrary native/class resources are unsupported.
+- Closure-private mutable state is not discoverable; return any ref/reactive value whose SSR
+  mutations must hydrate.
 - No Nuxt Layers support yet.
 - State resets when its module is hot-reloaded; HMR preservation is not implemented.
-- Compatibility with every context-sensitive Nuxt composable inside a factory is not
-  guaranteed yet.
+- Context-sensitive composables must still be called while normal Nuxt context is available.
 - There is no reset API, keyed/multi-instance state, DevTools integration, or central
-  registry.
+  user-facing registry.
+- The keyed transform is source-sensitive. The supported path is the module's auto-imported
+  `defineState`; a barrel re-export or unrelated manual wrapper is not guaranteed to receive an
+  internal hydration key.
 
-See [ROADMAP.md](./ROADMAP.md) for the technical questions behind future hydration and
-context compatibility.
+See [the architecture notes](./docs/architecture.md) and [roadmap](./docs/roadmap.md) for
+implementation constraints and deferred work.
 
 ## Development
 
@@ -134,15 +211,18 @@ Requires Node.js 22+ and pnpm.
 ```bash
 pnpm install
 pnpm dev
+pnpm fmt:check
 pnpm lint
 pnpm test:types
 pnpm test
+pnpm test:stress
 pnpm prepack
 pnpm dev:build
 ```
 
-The playground contains two counter components, a reactive object example, a nested
-state, and two independent states exported from one file.
+The browser suite requires Chromium, installed with
+`pnpm exec playwright-core install chromium`. The playground contains two counter components,
+a reactive object example, a nested state, and two independent states exported from one file.
 
 ## License
 

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": "^4.0.0"
   },
   "configKey": "nuxt-state",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,5 +1,5 @@
 import { resolve } from 'node:path';
-import { defineNuxtModule, createResolver, addImports, addImportsDir } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addImports, addPlugin, addImportsDir } from '@nuxt/kit';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -11,10 +11,17 @@ const module$1 = defineNuxtModule({
   defaults: {},
   setup(_options, nuxt) {
     const resolver = createResolver(import.meta.url);
+    const defineStateSource = resolver.resolve("./runtime/app/composables/defineState");
     addImports({
       name: "defineState",
-      from: resolver.resolve("./runtime/app/composables/defineState")
+      from: defineStateSource
     });
+    nuxt.options.optimization.keyedComposables.push({
+      name: "defineState",
+      source: defineStateSource,
+      argumentLength: 2
+    });
+    addPlugin(resolver.resolve("./runtime/app/plugins/hydration"));
     addImportsDir(resolve(nuxt.options.srcDir, "states/**"));
   }
 });

package/dist/runtime/app/composables/defineState.js

@@ -1,21 +1,41 @@
 import { useNuxtApp } from "#app";
+import { effectScope } from "vue";
+import { registerHydratableState } from "../state-registry.js";
+import { restoreState, snapshotState } from "../state-snapshot.js";
 function isPromiseLike(value) {
   return (typeof value === "object" && value !== null || typeof value === "function") && "then" in value && typeof value.then === "function";
 }
-export function defineState(factory) {
+export function defineState(factory, internalKey) {
   const instances = /* @__PURE__ */ new WeakMap();
   return function useDefinedState() {
     const nuxtApp = useNuxtApp();
     if (instances.has(nuxtApp)) {
       return instances.get(nuxtApp);
     }
-    const instance = factory();
+    const scope = effectScope(true);
+    let instance;
+    try {
+      instance = scope.run(factory);
+    } catch (error) {
+      scope.stop();
+      throw error;
+    }
     if (isPromiseLike(instance)) {
+      scope.stop();
       throw new TypeError(
         "[nuxt-state] State factories must be synchronous. Expose an async function from the state or use Nuxt data-fetching composables instead."
       );
     }
     instances.set(nuxtApp, instance);
+    const app = nuxtApp;
+    app.vueApp?.onUnmount?.(() => scope.stop());
+    if (internalKey) {
+      registerHydratableState(nuxtApp, internalKey, {
+        snapshot: () => snapshotState(instance),
+        restore: (snapshot) => restoreState(instance, snapshot),
+        dispose: () => scope.stop()
+      });
+    }
     return instance;
   };
 }

package/dist/runtime/app/plugins/hydration.d.ts

@@ -0,0 +1,3 @@
+export declare const STATE_PAYLOAD_KEY: "__nuxt_state__";
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/app/plugins/hydration.js

@@ -0,0 +1,17 @@
+import { defineNuxtPlugin, useHydration } from "#app";
+import {
+  clearPendingStateSnapshots,
+  collectStateSnapshots,
+  receiveStateSnapshots
+} from "../state-registry.js";
+export const STATE_PAYLOAD_KEY = "__nuxt_state__";
+export default defineNuxtPlugin((nuxtApp) => {
+  useHydration(
+    STATE_PAYLOAD_KEY,
+    () => collectStateSnapshots(nuxtApp),
+    (snapshots) => receiveStateSnapshots(nuxtApp, snapshots)
+  );
+  if (import.meta.client) {
+    nuxtApp.hook("app:mounted", () => clearPendingStateSnapshots(nuxtApp));
+  }
+});

package/dist/runtime/app/state-registry.d.ts

@@ -0,0 +1,16 @@
+export type StateHydrationPayload = Record<string, unknown>;
+export interface HydratableStateEntry {
+    snapshot: () => unknown;
+    restore: (snapshot: unknown) => void;
+    dispose?: () => void;
+}
+interface StateRegistry {
+    active: Map<string, HydratableStateEntry>;
+    hydration: Map<string, unknown>;
+}
+export declare function getStateRegistry(nuxtApp: object): StateRegistry;
+export declare function registerHydratableState(nuxtApp: object, key: string, entry: HydratableStateEntry): void;
+export declare function collectStateSnapshots(nuxtApp: object): StateHydrationPayload;
+export declare function receiveStateSnapshots(nuxtApp: object, snapshots: StateHydrationPayload | undefined): void;
+export declare function clearPendingStateSnapshots(nuxtApp: object): void;
+export {};

package/dist/runtime/app/state-registry.js

@@ -0,0 +1,42 @@
+const registries = /* @__PURE__ */ new WeakMap();
+export function getStateRegistry(nuxtApp) {
+  let registry = registries.get(nuxtApp);
+  if (!registry) {
+    registry = {
+      active: /* @__PURE__ */ new Map(),
+      hydration: /* @__PURE__ */ new Map()
+    };
+    registries.set(nuxtApp, registry);
+  }
+  return registry;
+}
+export function registerHydratableState(nuxtApp, key, entry) {
+  const registry = getStateRegistry(nuxtApp);
+  registry.active.get(key)?.dispose?.();
+  registry.active.set(key, entry);
+  if (registry.hydration.has(key)) {
+    const snapshot = registry.hydration.get(key);
+    registry.hydration.delete(key);
+    entry.restore(snapshot);
+  }
+}
+export function collectStateSnapshots(nuxtApp) {
+  const snapshots = {};
+  for (const [key, entry] of getStateRegistry(nuxtApp).active) {
+    snapshots[key] = entry.snapshot();
+  }
+  return snapshots;
+}
+export function receiveStateSnapshots(nuxtApp, snapshots) {
+  const registry = getStateRegistry(nuxtApp);
+  registry.hydration = new Map(Object.entries(snapshots ?? {}));
+  for (const [key, entry] of registry.active) {
+    if (!registry.hydration.has(key)) continue;
+    const snapshot = registry.hydration.get(key);
+    registry.hydration.delete(key);
+    entry.restore(snapshot);
+  }
+}
+export function clearPendingStateSnapshots(nuxtApp) {
+  getStateRegistry(nuxtApp).hydration.clear();
+}

package/dist/runtime/app/state-snapshot.d.ts

@@ -0,0 +1,13 @@
+interface RefSnapshot {
+    type: 'ref';
+    value: unknown;
+}
+interface ReactiveSnapshot {
+    type: 'reactive';
+    value: unknown;
+}
+type StateSnapshotEntry = RefSnapshot | ReactiveSnapshot;
+export type StateSnapshot = Record<string, StateSnapshotEntry>;
+export declare function snapshotState(state: unknown): StateSnapshot;
+export declare function restoreState(state: unknown, snapshot: unknown): void;
+export {};

package/dist/runtime/app/state-snapshot.js

@@ -0,0 +1,74 @@
+import { isReactive, isReadonly, isRef, toRaw } from "vue";
+function isObjectLike(value) {
+  return typeof value === "object" && value !== null || typeof value === "function";
+}
+function unwrapReactive(value) {
+  return isReactive(value) ? toRaw(value) : value;
+}
+export function snapshotState(state) {
+  const snapshot = {};
+  if (!isObjectLike(state)) return snapshot;
+  for (const [name, value] of Object.entries(state)) {
+    if (isRef(value) && !isReadonly(value)) {
+      snapshot[name] = {
+        type: "ref",
+        value: unwrapReactive(value.value)
+      };
+    } else if (isReactive(value) && !isReadonly(value)) {
+      snapshot[name] = {
+        type: "reactive",
+        value: toRaw(value)
+      };
+    }
+  }
+  return snapshot;
+}
+function isPlainRecord(value) {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+function canPatch(target, source) {
+  return Array.isArray(target) && Array.isArray(source) || isPlainRecord(target) && !isRef(target) && isPlainRecord(source) && !isRef(source);
+}
+function isTrackableObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function patchValue(target, source, seen) {
+  if (!isTrackableObject(source)) return source;
+  if (seen.has(source)) return seen.get(source);
+  if (!canPatch(target, source)) {
+    seen.set(source, source);
+    return source;
+  }
+  seen.set(source, target);
+  if (Array.isArray(target) && Array.isArray(source)) {
+    for (let index = 0; index < source.length; index++) {
+      target[index] = patchValue(target[index], source[index], seen);
+    }
+    target.length = source.length;
+    return target;
+  }
+  if (!isPlainRecord(target) || !isPlainRecord(source)) return source;
+  for (const key of Object.keys(target)) {
+    if (!(key in source)) delete target[key];
+  }
+  for (const [key, value] of Object.entries(source)) {
+    target[key] = patchValue(target[key], value, seen);
+  }
+  return target;
+}
+function isStateSnapshotEntry(value) {
+  return isPlainRecord(value) && (value.type === "ref" || value.type === "reactive") && Object.hasOwn(value, "value");
+}
+export function restoreState(state, snapshot) {
+  if (!isObjectLike(state) || !isPlainRecord(snapshot)) return;
+  const seen = /* @__PURE__ */ new WeakMap();
+  for (const [name, entry] of Object.entries(snapshot)) {
+    if (!isStateSnapshotEntry(entry)) continue;
+    const target = state[name];
+    if (entry.type === "ref" && isRef(target) && !isReadonly(target)) {
+      target.value = entry.value;
+    } else if (entry.type === "reactive" && isReactive(target) && !isReadonly(target)) {
+      patchValue(target, entry.value, seen);
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-state",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "Define shared Nuxt state using the same Composition API you already use in composables.",
   "keywords": [
     "composable",
@@ -58,6 +58,7 @@
     "nuxt": "^4.5.2",
     "oxfmt": "^0.65.0",
     "oxlint": "^1.80.0",
+    "playwright-core": "^1.62.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "vue": "^3.5.31",
@@ -75,8 +76,10 @@
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "test": "vitest run",
-    "check": "pnpm run fmt && pnpm run lint",
+    "test:browser": "vitest run test/browser",
+    "test:stress": "vitest run --config vitest.stress.config.ts",
+    "check": "pnpm run fmt:check && pnpm run lint",
     "test:watch": "vitest",
-    "test:types": "vue-tsc --noEmit && pnpm --dir playground exec vue-tsc --noEmit"
+    "test:types": "nuxt-module-build prepare && nuxt-module-build build && vue-tsc --noEmit && pnpm --dir playground exec vue-tsc --noEmit"
   }
 }