nuxt-state 0.0.2 → 0.1.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:
@@ -97,35 +94,67 @@ refs remain computed refs, reactive objects remain reactive, and functions are u
   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
+
+v0.1.0 transparently hydrates mutable top-level members returned by the factory when they are
+created with `ref()` or `reactive()`. 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.
+
+```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 guarantees isolation between SSR requests: module-level state does not become a
-process-wide user-state singleton. This is intentionally different from hydration.
+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.
 
-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.
+`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.
 
 ## 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 `ref()` and `reactive()` members only. Advanced
+  primitives such as shallow/custom refs and writable-computed edge cases are not v0.1.0
+  guarantees.
+- Hydrated values must be serializable by Nuxt's payload system; DOM nodes, sockets, functions
+  inside refs, symbols, and arbitrary native/class resources are unsupported.
 - 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.
 - 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,6 +163,7 @@ Requires Node.js 22+ and pnpm.
 ```bash
 pnpm install
 pnpm dev
+pnpm fmt:check
 pnpm lint
 pnpm test:types
 pnpm test
@@ -141,8 +171,9 @@ 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.1.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,8 +1,10 @@
 import { useNuxtApp } from "#app";
+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();
@@ -16,6 +18,12 @@ export function defineState(factory) {
       );
     }
     instances.set(nuxtApp, instance);
+    if (internalKey) {
+      registerHydratableState(nuxtApp, internalKey, {
+        snapshot: () => snapshotState(instance),
+        restore: (snapshot) => restoreState(instance, snapshot)
+      });
+    }
     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,13 @@
+import { defineNuxtPlugin, useHydration } from "#app";
+import {
+  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)
+  );
+});

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

@@ -0,0 +1,14 @@
+export type StateHydrationPayload = Record<string, unknown>;
+export interface HydratableStateEntry {
+    snapshot: () => unknown;
+    restore: (snapshot: unknown) => 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 {};

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

@@ -0,0 +1,38 @@
+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.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);
+  }
+}

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,70 @@
+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) && isPlainRecord(source);
+}
+function patchValue(target, source) {
+  if (Array.isArray(target) && Array.isArray(source)) {
+    for (let index = 0; index < source.length; index++) {
+      if (canPatch(target[index], source[index])) {
+        patchValue(target[index], source[index]);
+      } else {
+        target[index] = source[index];
+      }
+    }
+    target.length = source.length;
+    return;
+  }
+  if (!isPlainRecord(target) || !isPlainRecord(source)) return;
+  for (const key of Object.keys(target)) {
+    if (!(key in source)) delete target[key];
+  }
+  for (const [key, value] of Object.entries(source)) {
+    if (canPatch(target[key], value)) {
+      patchValue(target[key], value);
+    } else {
+      target[key] = value;
+    }
+  }
+}
+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;
+  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);
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-state",
-  "version": "0.0.2",
+  "version": "0.1.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,9 @@
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "test": "vitest run",
-    "check": "pnpm run fmt && pnpm run lint",
+    "test:browser": "vitest run test/browser",
+    "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 build && vue-tsc --noEmit && pnpm --dir playground exec vue-tsc --noEmit"
   }
 }