nuxt-state 0.2.0 → 1.0.0

package/README.md

@@ -1,32 +1,14 @@
 # nuxt-state
 
-> Define shared Nuxt state using the same Composition API you already use in composables.
+> Define shared Nuxt state with the Vue Composition API.
 
-`nuxt-state` is an experimental Nuxt 4 module that explores one small primitive:
+`nuxt-state` is a focused Nuxt 4 module. A composable created with `defineState` runs lazily
+once per Nuxt application and returns the same result to every caller in that app. Its stable
+1.x public API is `defineState(factory)`.
 
-```ts
-defineState(() => {
-  // standard Vue Composition API
-  return {/* public state */}
-})
-```
-
-A regular composable runs its factory for every invocation. A composable created by
-`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 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
-
-Nuxt's `useState()` is excellent for simple SSR-aware values. Pinia is a strong choice
-when an application wants a dedicated state-management library and its ecosystem.
-This project does not replace either one. It explores a lightweight native abstraction
-between a raw `useState()` value and a full state-management library.
-
-There are no stores, actions, getters, mutations, IDs, configuration objects, or special
-wrappers. The factory and its return value use normal Vue semantics.
+It sits between a simple `useState()` value and a full state-management library such as
+Pinia. There are no stores, IDs, actions, getters, or special wrappers—only standard Vue
+primitives.
 
 ## Install
 
@@ -43,7 +25,7 @@ export default defineNuxtConfig({
 
 ## Usage
 
-Create a state in Nuxt 4's application source directory:
+Create states in `app/states/`:
 
 ```ts
 // app/states/counter.ts
@@ -55,154 +37,110 @@ export const useCounter = defineState(() => {
     count.value++
   }
 
-  return {
-    count,
-    double,
-    increment,
-  }
+  return { count, double, increment }
 })
 ```
 
-Exports from `app/states/`, including nested directories and multiple exports per file,
-are auto-imported. `defineState` is also auto-imported and can be used elsewhere, such
-as in `app/composables/`.
+Exports from this directory, including nested directories and multiple exports per file,
+are auto-imported. `defineState` is also auto-imported and may be used elsewhere.
 
 ```vue
 <script setup lang="ts">
 const { count, double, increment } = useCounter()
 
-count.value++
 increment()
 console.log(double.value)
 </script>
 ```
 
-Calling `useCounter()` in ten components returns the same object for that Nuxt app.
-Different server requests and different client apps receive different objects.
+All callers within one Nuxt app receive the exact factory result. Refs, reactive objects,
+computed refs, and functions retain their normal Vue behavior. Server requests and separate
+client apps never share instances.
 
-The returned object is not cloned, wrapped, or transformed. Refs remain refs, computed
-refs remain computed refs, reactive objects remain reactive, and functions are unchanged.
+## Nuxt Layers
 
-## Semantics
+States in the resolved `app/states/` directory of local, extended, or package-provided
+[Nuxt Layers](https://nuxt.com/docs/4.x/guide/going-further/layers) are auto-imported too.
+Normal Nuxt priority applies: project exports override layer exports, and higher-priority
+layers override lower-priority ones.
 
-- The factory is synchronous and takes no arguments.
-- The generated composable takes no arguments.
-- 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.
+## DevTools
 
-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.
+With Nuxt DevTools enabled, a development-only **Nuxt State** tab provides read-only views
+of active states and discovered state exports. It shows hydration status, safe bounded value
+previews, source paths, and layer origins without executing lazy factories.
 
-## SSR hydration
+The inspector cannot mutate state or invoke functions. It polls only while visible, adds no
+production runtime code, and labels active instances by their internal hydration key because
+Nuxt does not expose a stable mapping from that key to auto-import metadata.
 
-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)`.
+## Behavior
 
-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.
+- The factory and generated composable are synchronous and take no arguments.
+- The factory runs lazily, once per Nuxt app, inside an app-lived Vue effect scope.
+- Instances are stored in a `WeakMap` keyed by `NuxtApp` for SSR request isolation and garbage
+  collection.
+- Separate `defineState()` calls always have separate caches.
+- HMR recreates the state instead of preserving it.
+- Async work should be exposed as a function or use Nuxt data composables such as `useFetch`.
+
+## SSR hydration
+
+Mutable top-level refs and reactive objects returned by the factory are snapshotted after SSR
+and restored into client-created values before Vue hydration. The factory result is never
+replaced, so its computed refs, watchers, functions, and closures remain connected.
 
 ```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 }
+  return { count, user, double }
 })
 ```
 
-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.
+Nuxt's payload serializer handles nested serializable values, including supported `Date`,
+`Map`, `Set`, shared-reference, and cyclic graphs. Functions and readonly computed refs are
+recreated by the client factory rather than serialized.
 
-`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.
+Reactive state that must survive SSR hydration currently needs to be exposed from the
+`defineState` factory. Closure-private refs cannot be discovered; mutating one during SSR may
+therefore cause a hydration mismatch.
 
-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.
+`useFetch()` and `useAsyncData()` retain Nuxt's request caching and payload ownership. When
+their returned data ref is exposed, Nuxt's graph serializer keeps the shared payload object
+instead of duplicating the response body. The state snapshot adds only 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 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.
-- 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
-  `defineState`; a barrel re-export or unrelated manual wrapper is not guaranteed to receive an
-  internal hydration key.
-
-See [the architecture notes](./docs/architecture.md) and [roadmap](./docs/roadmap.md) for
-implementation constraints and deferred work.
+Supported:
+
+- `ref`, `reactive`, `shallowRef`, and `shallowReactive`;
+- readonly computed values and functions recreated by the client factory;
+- readonly views whose mutable source is also returned;
+- Nuxt-serializable nested values, shared references, and cycles;
+- `useFetch`, `useAsyncData`, `callOnce`, `useCookie`, `useRuntimeConfig`, `useRoute`, and
+  `useRouter` in valid Nuxt contexts;
+- first use from plugins, middleware, layouts, pages, and components;
+- project and Nuxt Layer states.
+
+Limitations:
+
+- Nuxt 4 and Vue 3 only; synchronous factories only.
+- Hydrated state must be an enumerable object containing supported mutable members.
+- Closure-private mutable state, `customRef`, and writable computed hydration are unsupported.
+  Restoring a writable computed may invoke its setter, so return its source refs instead.
+- Payload values must be serializable by Nuxt; DOM nodes, sockets, symbols, functions inside
+  refs, and arbitrary class/native resources are unsupported.
+- No persistence, reset API, keyed instances, or HMR state preservation.
+- Context-sensitive Nuxt composables still require a valid Nuxt context.
+- The supported transform path is the module's auto-imported `defineState`; barrel re-exports
+  and unrelated wrappers are not guaranteed to receive a hydration key.
+- DevTools is development-only and read-only.
+
+See [architecture](./docs/architecture.md) for implementation details and the
+[roadmap](./docs/roadmap.md) for deferred work.
 
 ## Development
 
@@ -220,9 +158,7 @@ pnpm prepack
 pnpm dev:build
 ```
 
-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.
+Install Chromium for browser tests with `pnpm exec playwright-core install chromium`.
 
 ## License
 

package/dist/module.json

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

package/dist/module.mjs

@@ -1,5 +1,22 @@
-import { resolve } from 'node:path';
-import { defineNuxtModule, createResolver, addImports, addPlugin, addImportsDir } from '@nuxt/kit';
+import { resolve, sep, relative, basename } from 'node:path';
+import { defineNuxtModule, createResolver, addImports, addPlugin, getLayerDirectories, addTemplate, addDevServerHandler, addImportsDir } from '@nuxt/kit';
+import { addCustomTab } from '@nuxt/devtools-kit';
+
+function registerDevtools(route, nuxt) {
+  addCustomTab(
+    {
+      name: "nuxt-state",
+      title: "Nuxt State",
+      icon: "carbon:data-vis-4",
+      category: "app",
+      view: {
+        type: "iframe",
+        src: route
+      }
+    },
+    nuxt
+  );
+}
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -22,8 +39,147 @@ const module$1 = defineNuxtModule({
       argumentLength: 2
     });
     addPlugin(resolver.resolve("./runtime/app/plugins/hydration"));
-    addImportsDir(resolve(nuxt.options.srcDir, "states/**"));
+    const devtools = nuxt.options.devtools;
+    const devtoolsEnabled = nuxt.options.dev && devtools !== false && !(typeof devtools === "object" && devtools.enabled === false);
+    const layers = getLayerDirectories(nuxt);
+    const stateDirectories = layers.map((layer) => resolve(layer.app, "states"));
+    if (devtoolsEnabled) {
+      const devtoolsRoute = "/__nuxt_state_devtools__/";
+      let knownStates = [];
+      nuxt.hook("imports:extend", (imports) => {
+        const winners = /* @__PURE__ */ new Map();
+        for (const item of imports) {
+          const layerIndex = stateDirectories.findIndex(
+            (directory) => item.from === directory || item.from.startsWith(`${directory}${sep}`)
+          );
+          const name = item.as || item.name;
+          if (layerIndex < 0 || winners.has(name)) continue;
+          const layer = layers[layerIndex];
+          const projectRelative = relative(nuxt.options.rootDir, item.from);
+          const source = projectRelative.startsWith("..") ? basename(item.from) : projectRelative;
+          const layerRelative = relative(nuxt.options.rootDir, layer.root).replace(/\/$/, "");
+          winners.set(name, {
+            name,
+            source,
+            origin: layerIndex === 0 ? "Project" : layerRelative || basename(layer.root)
+          });
+        }
+        knownStates = [...winners.values()].sort((a, b) => a.name.localeCompare(b.name));
+      });
+      addTemplate({
+        filename: "nuxt-state/metadata.mjs",
+        getContents: () => `export default ${JSON.stringify(knownStates)}`
+      });
+      registerDevtools(devtoolsRoute, nuxt);
+      addPlugin(resolver.resolve("./runtime/app/plugins/devtools.client"));
+      addDevServerHandler({
+        route: devtoolsRoute,
+        handler(event) {
+          event.node.res.setHeader("content-type", "text/html; charset=utf-8");
+          return renderDevtoolsView();
+        }
+      });
+    }
+    addImportsDir(layers.map((layer) => resolve(layer.app, "states/**")));
   }
 });
+function renderDevtoolsView() {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>Nuxt State</title>
+  <style>
+    :root { color-scheme: light dark; font: 14px/1.5 ui-sans-serif, system-ui, sans-serif; }
+    * { box-sizing: border-box; }
+    body { margin: 0; color: #d9e1ea; background: #101418; }
+    header { position: sticky; top: 0; z-index: 1; display: flex; gap: 12px; align-items: center; padding: 14px 18px; border-bottom: 1px solid #2a343e; background: #101418ee; }
+    h1 { margin: 0 auto 0 0; font-size: 18px; }
+    input, button { border: 1px solid #34414d; border-radius: 7px; background: #182027; color: inherit; padding: 7px 10px; }
+    input { width: min(280px, 42vw); }
+    button { cursor: pointer; }
+    main { display: grid; gap: 12px; padding: 16px; }
+    article { border: 1px solid #2a343e; border-radius: 10px; background: #151b21; overflow: hidden; }
+    article > div { padding: 12px 14px; }
+    h2 { margin: 0; font-size: 15px; }
+    .meta { color: #94a3b1; font-size: 12px; overflow-wrap: anywhere; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { padding: 8px 14px; border-top: 1px solid #27313a; text-align: left; vertical-align: top; }
+    th { color: #91a0ad; font-size: 11px; text-transform: uppercase; }
+    td:nth-child(1) { width: 22%; font-weight: 600; }
+    td:nth-child(2) { width: 16%; color: #65d8a5; }
+    pre { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; font: 12px/1.45 ui-monospace, monospace; }
+    .empty, .error { padding: 36px; text-align: center; color: #91a0ad; }
+    .badge { display: inline-block; margin-left: 7px; padding: 1px 6px; border-radius: 999px; background: #263a32; color: #7ee2ad; font-size: 11px; }
+    @media (prefers-color-scheme: light) {
+      body { color: #202832; background: #f7f9fb; }
+      header { border-color: #d9e0e6; background: #f7f9fbee; }
+      input, button, article { border-color: #d7dfe6; background: white; }
+      th, td { border-color: #e3e8ed; }
+      .badge { background: #dff7ea; color: #176b43; }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Nuxt State <span class="badge">Read only</span></h1>
+    <input id="filter" type="search" placeholder="Filter active states">
+    <button id="refresh" type="button">Refresh</button>
+  </header>
+  <main id="states"><p class="empty">Connecting to the Nuxt app\u2026</p></main>
+  <script>
+    const root = document.querySelector('#states')
+    const filter = document.querySelector('#filter')
+    let activeStates = []
+    let knownStates = []
+    let timer
+    let visible = true
+    let refreshing = false
+
+    const escapeHTML = value => String(value).replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char])
+    const render = () => {
+      const query = filter.value.trim().toLowerCase()
+      const shown = activeStates.filter(state => (state.name + ' ' + state.key).toLowerCase().includes(query))
+      const known = knownStates.filter(state => (state.name + ' ' + state.source + ' ' + state.origin).toLowerCase().includes(query))
+      const activeHTML = shown.length
+        ? shown.map(state => '<article><div><h2>' + escapeHTML(state.name) + '<span class="badge">' + escapeHTML(state.hydration) + '</span></h2><div class="meta">Internal hydration key: ' + escapeHTML(state.key) + '</div></div><table><thead><tr><th>Member</th><th>Kind</th><th>Value preview</th></tr></thead><tbody>' + state.members.map(member => '<tr><td>' + escapeHTML(member.name) + '</td><td>' + escapeHTML(member.kind) + '</td><td><pre>' + escapeHTML(JSON.stringify(member.value, null, 2)) + '</pre></td></tr>').join('') + '</tbody></table></article>').join('')
+        : '<p class="empty">' + (activeStates.length ? 'No matching active states.' : 'No active states yet. Opening this panel does not instantiate lazy state.') + '</p>'
+      const knownHTML = known.length
+        ? '<article><div><h2>Known states</h2><div class="meta">Discovered statically; factories remain lazy.</div></div><table><thead><tr><th>Name</th><th>Origin</th><th>Source</th></tr></thead><tbody>' + known.map(state => '<tr><td>' + escapeHTML(state.name) + '</td><td>' + escapeHTML(state.origin) + '</td><td><pre>' + escapeHTML(state.source) + '</pre></td></tr>').join('') + '</tbody></table></article>'
+        : ''
+      root.innerHTML = activeHTML + knownHTML
+    }
+    const refresh = async () => {
+      if (!visible || refreshing) return
+      refreshing = true
+      try {
+        const client = window.__NUXT_DEVTOOLS__
+        if (!client?.host?.nuxt) throw new Error('Nuxt DevTools host is not connected.')
+        const request = { result: undefined }
+        await client.host.nuxt.callHook('nuxt-state:inspect', request)
+        activeStates = request.result?.active || []
+        knownStates = request.result?.known || []
+        render()
+      } catch (error) {
+        root.innerHTML = '<p class="error">' + escapeHTML(error?.message || error) + '</p>'
+      } finally {
+        refreshing = false
+      }
+    }
+    const observer = new IntersectionObserver(entries => {
+      visible = entries.some(entry => entry.isIntersecting)
+      if (visible) refresh()
+    })
+    observer.observe(document.documentElement)
+    filter.addEventListener('input', render)
+    document.querySelector('#refresh').addEventListener('click', refresh)
+    timer = setInterval(refresh, 1000)
+    addEventListener('pagehide', () => { clearInterval(timer); observer.disconnect() }, { once: true })
+    refresh()
+  <\/script>
+</body>
+</html>`;
+}
 
 export { module$1 as default };

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

@@ -30,11 +30,23 @@ export function defineState(factory, internalKey) {
     const app = nuxtApp;
     app.vueApp?.onUnmount?.(() => scope.stop());
     if (internalKey) {
-      registerHydratableState(nuxtApp, internalKey, {
+      const entry = {
         snapshot: () => snapshotState(instance),
         restore: (snapshot) => restoreState(instance, snapshot),
         dispose: () => scope.stop()
-      });
+      };
+      if (import.meta.dev) {
+        entry.debug = {
+          state: instance,
+          hydration: import.meta.server ? "Server" : "Client-only"
+        };
+        const restore = entry.restore;
+        entry.restore = (snapshot) => {
+          restore(snapshot);
+          entry.debug.hydration = "Hydrated";
+        };
+      }
+      registerHydratableState(nuxtApp, internalKey, entry);
     }
     return instance;
   };

package/dist/runtime/app/devtools-metadata.d.ts

@@ -0,0 +1,4 @@
+declare module '#build/nuxt-state/metadata' {
+  const states: Array<{ name: string; source: string; origin: string }>
+  export default states
+}

package/dist/runtime/app/plugins/devtools.client.d.ts

@@ -0,0 +1,2 @@
+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/devtools.client.js

@@ -0,0 +1,17 @@
+import { defineNuxtPlugin } from "#app";
+import knownStates from "#build/nuxt-state/metadata";
+import { inspectActiveStates } from "../state-inspector.js";
+export default defineNuxtPlugin({
+  name: "nuxt-state:devtools",
+  setup(nuxtApp) {
+    nuxtApp.hook(
+      "nuxt-state:inspect",
+      ((request) => {
+        request.result = {
+          active: inspectActiveStates(nuxtApp),
+          known: knownStates
+        };
+      })
+    );
+  }
+});

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

@@ -0,0 +1,16 @@
+export interface StateInspectorMember {
+    name: string;
+    kind: string;
+    value: unknown;
+}
+export interface StateInspectorEntry {
+    key: string;
+    name: string;
+    source?: string;
+    origin?: string;
+    hydration: 'Hydrated' | 'Client-only' | 'Server';
+    members: StateInspectorMember[];
+}
+export declare function inspectActiveStates(nuxtApp: object): StateInspectorEntry[];
+export declare function classifyStateMember(value: unknown): string;
+export declare function previewValue(value: unknown): unknown;

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

@@ -0,0 +1,149 @@
+import { isReactive, isReadonly, isRef, isShallow, toRaw } from "vue";
+import { getStateRegistry } from "./state-registry.js";
+const MAX_DEPTH = 4;
+const MAX_ITEMS = 40;
+const MAX_NODES = 200;
+const MAX_STRING = 500;
+export function inspectActiveStates(nuxtApp) {
+  const entries = [];
+  for (const [key, entry] of getStateRegistry(nuxtApp).active) {
+    if (!entry.debug) continue;
+    const state = entry.debug.state;
+    const members = inspectMembers(state);
+    entries.push({
+      key,
+      name: entry.debug.name || `State ${key}`,
+      source: entry.debug.source,
+      origin: entry.debug.origin,
+      hydration: entry.debug.hydration,
+      members
+    });
+  }
+  return entries;
+}
+export function classifyStateMember(value) {
+  if (typeof value === "function") return "function";
+  if (isRef(value)) {
+    if (isReadonly(value)) return "readonly ref";
+    return isShallow(value) ? "shallowRef" : "ref";
+  }
+  if (isReactive(value)) {
+    if (isReadonly(value)) return "readonly";
+    return isShallow(value) ? "shallowReactive" : "reactive";
+  }
+  if (isReadonly(value)) return "readonly";
+  return "other";
+}
+export function previewValue(value) {
+  try {
+    const context = { seen: /* @__PURE__ */ new WeakMap(), nodes: 0, truncated: false };
+    const preview = visit(value, 0, context);
+    return context.truncated ? { preview, truncated: true } : preview;
+  } catch (error) {
+    return { unavailable: safeErrorMessage(error) };
+  }
+}
+function inspectMembers(state) {
+  if (!isObjectLike(state)) {
+    return [{ name: "value", kind: classifyStateMember(state), value: previewValue(state) }];
+  }
+  try {
+    return Object.keys(state).map((name) => {
+      try {
+        const value = state[name];
+        return {
+          name,
+          kind: classifyStateMember(value),
+          value: previewValue(isRef(value) ? value.value : value)
+        };
+      } catch (error) {
+        return { name, kind: "unavailable", value: { unavailable: safeErrorMessage(error) } };
+      }
+    });
+  } catch (error) {
+    return [
+      {
+        name: "value",
+        kind: "unavailable",
+        value: { unavailable: safeErrorMessage(error) }
+      }
+    ];
+  }
+}
+function visit(value, depth, context) {
+  if (typeof value === "string") {
+    if (value.length <= MAX_STRING) return value;
+    context.truncated = true;
+    return `${value.slice(0, MAX_STRING)}\u2026`;
+  }
+  if (value === null || ["number", "boolean", "undefined"].includes(typeof value)) return value;
+  if (typeof value === "bigint") return `${value}n`;
+  if (typeof value === "symbol") return value.toString();
+  if (typeof value === "function") return `\u0192 ${value.name || "anonymous"}()`;
+  if (typeof value !== "object") return String(value);
+  const raw = isReactive(value) || isReadonly(value) ? toRaw(value) : value;
+  const known = context.seen.get(raw);
+  if (known) return { reference: `#${known}` };
+  const id = ++context.nodes;
+  context.seen.set(raw, id);
+  if (context.nodes > MAX_NODES || depth >= MAX_DEPTH) {
+    context.truncated = true;
+    return { id: `#${id}`, truncated: true };
+  }
+  if (raw instanceof Date) {
+    return {
+      id: `#${id}`,
+      type: "Date",
+      value: Number.isNaN(raw.valueOf()) ? "Invalid Date" : raw.toISOString()
+    };
+  }
+  if (raw instanceof Map) {
+    const items = [...raw.entries()];
+    if (items.length > MAX_ITEMS) context.truncated = true;
+    return {
+      id: `#${id}`,
+      type: "Map",
+      entries: items.slice(0, MAX_ITEMS).map(([key, item]) => [visit(key, depth + 1, context), visit(item, depth + 1, context)]),
+      ...items.length > MAX_ITEMS ? { truncated: true, total: items.length } : {}
+    };
+  }
+  if (raw instanceof Set) {
+    const items = [...raw];
+    if (items.length > MAX_ITEMS) context.truncated = true;
+    return {
+      id: `#${id}`,
+      type: "Set",
+      values: items.slice(0, MAX_ITEMS).map((item) => visit(item, depth + 1, context)),
+      ...items.length > MAX_ITEMS ? { truncated: true, total: items.length } : {}
+    };
+  }
+  if (Array.isArray(raw)) {
+    if (raw.length > MAX_ITEMS) context.truncated = true;
+    return {
+      id: `#${id}`,
+      type: "Array",
+      values: raw.slice(0, MAX_ITEMS).map((item) => visit(item, depth + 1, context)),
+      ...raw.length > MAX_ITEMS ? { truncated: true, total: raw.length } : {}
+    };
+  }
+  if (Object.getPrototypeOf(raw) !== Object.prototype && Object.getPrototypeOf(raw) !== null) {
+    const constructor = raw.constructor;
+    return { id: `#${id}`, unsupported: constructor?.name || "Object" };
+  }
+  const properties = Object.entries(raw);
+  if (properties.length > MAX_ITEMS) context.truncated = true;
+  return {
+    id: `#${id}`,
+    properties: Object.fromEntries(
+      properties.slice(0, MAX_ITEMS).map(([key, item]) => [key, visit(item, depth + 1, context)])
+    ),
+    ...properties.length > MAX_ITEMS ? { truncated: true, total: properties.length } : {}
+  };
+}
+function isObjectLike(value) {
+  return typeof value === "object" && value !== null || typeof value === "function";
+}
+function safeErrorMessage(error) {
+  if (error instanceof Error) return error.message.slice(0, 200);
+  return "Value could not be inspected";
+}

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

@@ -3,6 +3,13 @@ export interface HydratableStateEntry {
     snapshot: () => unknown;
     restore: (snapshot: unknown) => void;
     dispose?: () => void;
+    debug?: {
+        state: unknown;
+        name?: string;
+        source?: string;
+        origin?: string;
+        hydration: 'Hydrated' | 'Client-only' | 'Server';
+    };
 }
 interface StateRegistry {
     active: Map<string, HydratableStateEntry>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-state",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Define shared Nuxt state using the same Composition API you already use in composables.",
   "keywords": [
     "composable",
@@ -44,6 +44,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@nuxt/devtools-kit": "^3.4.2",
     "@nuxt/kit": "^4.5.2"
   },
   "devDependencies": {
@@ -52,12 +53,14 @@
     "@nuxt/module-builder": "^1.0.3",
     "@nuxt/schema": "^4.5.2",
     "@nuxt/test-utils": "^4.1.0",
+    "@pinia/nuxt": "1.0.2",
     "@types/node": "latest",
     "changelogen": "^0.6.2",
     "happy-dom": "^20.8.3",
     "nuxt": "^4.5.2",
     "oxfmt": "^0.65.0",
     "oxlint": "^1.80.0",
+    "pinia": "4.0.3",
     "playwright-core": "^1.62.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
@@ -68,6 +71,7 @@
     "node": ">=22"
   },
   "scripts": {
+    "bench:bundle-size": "pnpm run prepack && node benchmarks/bundle-size/run.mjs",
     "dev": "pnpm dev:prepare && nuxt dev playground",
     "dev:build": "nuxt build playground",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
@@ -80,6 +84,6 @@
     "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 prepare && 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 && nuxt prepare playground && pnpm --dir playground exec vue-tsc --noEmit"
   }
 }