nuxt-state 0.1.0 → 0.2.0

package/README.md

@@ -90,6 +90,8 @@ 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
@@ -102,9 +104,9 @@ Expose an async function from synchronous state or use Nuxt's data-fetching APIs
 
 ## 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)`.
+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
@@ -128,25 +130,71 @@ payload serializer. Functions, readonly computed refs, and plain runtime objects
 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.
-- 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.
+- 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
   user-facing registry.
 - The keyed transform is source-sensitive. The supported path is the module's auto-imported
@@ -167,6 +215,7 @@ pnpm fmt:check
 pnpm lint
 pnpm test:types
 pnpm test
+pnpm test:stress
 pnpm prepack
 pnpm dev:build
 ```

package/dist/module.json

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

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

@@ -1,4 +1,5 @@
 import { useNuxtApp } from "#app";
+import { effectScope } from "vue";
 import { registerHydratableState } from "../state-registry.js";
 import { restoreState, snapshotState } from "../state-snapshot.js";
 function isPromiseLike(value) {
@@ -11,17 +12,28 @@ export function defineState(factory, internalKey) {
     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)
+        restore: (snapshot) => restoreState(instance, snapshot),
+        dispose: () => scope.stop()
       });
     }
     return instance;

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

@@ -1,5 +1,6 @@
 import { defineNuxtPlugin, useHydration } from "#app";
 import {
+  clearPendingStateSnapshots,
   collectStateSnapshots,
   receiveStateSnapshots
 } from "../state-registry.js";
@@ -10,4 +11,7 @@ export default defineNuxtPlugin((nuxtApp) => {
     () => collectStateSnapshots(nuxtApp),
     (snapshots) => receiveStateSnapshots(nuxtApp, snapshots)
   );
+  if (import.meta.client) {
+    nuxtApp.hook("app:mounted", () => clearPendingStateSnapshots(nuxtApp));
+  }
 });

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

@@ -2,6 +2,7 @@ export type StateHydrationPayload = Record<string, unknown>;
 export interface HydratableStateEntry {
     snapshot: () => unknown;
     restore: (snapshot: unknown) => void;
+    dispose?: () => void;
 }
 interface StateRegistry {
     active: Map<string, HydratableStateEntry>;
@@ -11,4 +12,5 @@ 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

@@ -12,6 +12,7 @@ export function getStateRegistry(nuxtApp) {
 }
 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);
@@ -36,3 +37,6 @@ export function receiveStateSnapshots(nuxtApp, snapshots) {
     entry.restore(snapshot);
   }
 }
+export function clearPendingStateSnapshots(nuxtApp) {
+  getStateRegistry(nuxtApp).hydration.clear();
+}

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

@@ -27,44 +27,48 @@ 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);
+  return Array.isArray(target) && Array.isArray(source) || isPlainRecord(target) && !isRef(target) && isPlainRecord(source) && !isRef(source);
 }
-function patchValue(target, 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++) {
-      if (canPatch(target[index], source[index])) {
-        patchValue(target[index], source[index]);
-      } else {
-        target[index] = source[index];
-      }
+      target[index] = patchValue(target[index], source[index], seen);
     }
     target.length = source.length;
-    return;
+    return target;
   }
-  if (!isPlainRecord(target) || !isPlainRecord(source)) return;
+  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)) {
-    if (canPatch(target[key], value)) {
-      patchValue(target[key], value);
-    } else {
-      target[key] = value;
-    }
+    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);
+      patchValue(target, entry.value, seen);
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-state",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Define shared Nuxt state using the same Composition API you already use in composables.",
   "keywords": [
     "composable",
@@ -77,8 +77,9 @@
     "fmt:check": "oxfmt --check",
     "test": "vitest run",
     "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": "nuxt-module-build build && 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"
   }
 }