@noy-db/pinia 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# @noy-db/pinia
+
+> Pinia integration for [noy-db](https://github.com/vLannaAi/noy-db) — drop-in encrypted Pinia stores for Vue 3 / Nuxt 4.
+
+```bash
+pnpm add @noy-db/pinia @noy-db/core pinia vue
+# pick an adapter for your environment:
+pnpm add @noy-db/file       # local disk / USB
+pnpm add @noy-db/browser    # localStorage / IndexedDB
+pnpm add @noy-db/dynamo     # AWS DynamoDB
+```
+
+## Quick start
+
+```ts
+// stores/invoices.ts
+import { defineNoydbStore } from '@noy-db/pinia';
+
+interface Invoice {
+  id: string;
+  amount: number;
+  status: 'draft' | 'open' | 'paid';
+  client: string;
+}
+
+export const useInvoices = defineNoydbStore<Invoice>('invoices', {
+  compartment: 'C101',
+});
+```
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { createPinia } from 'pinia';
+import { createNoydb } from '@noy-db/core';
+import { jsonFile } from '@noy-db/file';
+import { setActiveNoydb } from '@noy-db/pinia';
+import App from './App.vue';
+
+const db = await createNoydb({
+  adapter: jsonFile({ dir: './data' }),
+  user: 'owner',
+  secret: () => prompt('Passphrase')!,
+});
+
+setActiveNoydb(db);
+
+createApp(App).use(createPinia()).mount('#app');
+```
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { useInvoices } from './stores/invoices';
+
+const invoices = useInvoices();
+await invoices.$ready;
+
+async function addOne() {
+  const id = `inv-${Date.now()}`;
+  await invoices.add(id, { id, amount: 100, status: 'draft', client: 'Acme' });
+}
+</script>
+
+<template>
+  <div>
+    <button @click="addOne">Add invoice</button>
+    <p>{{ invoices.count }} invoices</p>
+    <ul>
+      <li v-for="inv in invoices.items" :key="inv.id">
+        {{ inv.client }} — {{ inv.amount }} — {{ inv.status }}
+      </li>
+    </ul>
+  </div>
+</template>
+```
+
+## Store API
+
+Every store returned by `defineNoydbStore` exposes:
+
+| Member | Type | Purpose |
+|---|---|---|
+| `items` | `Ref<T[]>` | Reactive array of all decrypted records |
+| `count` | `ComputedRef<number>` | Reactive count |
+| `$ready` | `Promise<void>` | Resolves once the collection has hydrated on first use |
+| `byId(id)` | `(id) => T \| undefined` | O(N) cache lookup |
+| `add(id, record)` | `async (id, T) => void` | Encrypt + persist + update reactive state |
+| `update(id, record)` | `async (id, T) => void` | Alias for `add` (NOYDB `put` is upsert) |
+| `remove(id)` | `async (id) => void` | Delete + update reactive state |
+| `refresh()` | `async () => void` | Re-hydrate from the adapter (use after sync pulls) |
+| `query()` | `() => Query<T>` | Chainable query DSL — see `@noy-db/core` |
+
+## Composition
+
+The store is a real Pinia store. All these work unmodified:
+
+- `storeToRefs(store)` — destructure with reactivity intact
+- Vue Devtools — appears in the devtools tab like any other store
+- SSR — `items` is empty during server render, hydrates on the client
+- `pinia-plugin-persistedstate` — works as a fallback layer below NOYDB encryption
+
+## Schema validation
+
+Pass any object exposing `parse(input): T` (Zod, Valibot, ArkType, Effect Schema, etc.):
+
+```ts
+import { z } from 'zod';
+
+const InvoiceSchema = z.object({
+  id: z.string(),
+  amount: z.number().positive(),
+  status: z.enum(['draft', 'open', 'paid']),
+  client: z.string(),
+});
+
+export const useInvoices = defineNoydbStore<z.infer<typeof InvoiceSchema>>('invoices', {
+  compartment: 'C101',
+  schema: InvoiceSchema,
+});
+```
+
+`add()` and `update()` will throw if the record fails validation, before any encryption or write happens.
+
+## Query DSL
+
+The store's `query()` method returns the same chainable builder as `Collection.query()`:
+
+```ts
+const overdue = invoices.query()
+  .where('status', '==', 'open')
+  .where('dueDate', '<', new Date())
+  .orderBy('dueDate', 'asc')
+  .limit(50)
+  .toArray();
+```
+
+See [`@noy-db/core` query DSL docs](../core/README.md#query-dsl) for the full operator list.
+
+## Status
+
+Part of the v0.3 release. See [ROADMAP.md](../../ROADMAP.md#v03--pinia-first-dx--query--scale).
+
+## License
+
+MIT © vLannaAi

package/dist/index.cjs

@@ -0,0 +1,214 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createNoydbPiniaPlugin: () => createNoydbPiniaPlugin,
+  defineNoydbStore: () => defineNoydbStore,
+  getActiveNoydb: () => getActiveNoydb,
+  resolveNoydb: () => resolveNoydb,
+  setActiveNoydb: () => setActiveNoydb
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/defineNoydbStore.ts
+var import_pinia = require("pinia");
+var import_vue = require("vue");
+
+// src/context.ts
+var activeInstance = null;
+function setActiveNoydb(instance) {
+  activeInstance = instance;
+}
+function getActiveNoydb() {
+  return activeInstance;
+}
+function resolveNoydb(explicit) {
+  if (explicit) return explicit;
+  if (activeInstance) return activeInstance;
+  throw new Error(
+    "@noy-db/pinia: no Noydb instance bound.\n  Option A \u2014 pass `noydb:` directly to defineNoydbStore({...})\n  Option B \u2014 call setActiveNoydb(instance) once at app startup\n  Option C \u2014 install the @noy-db/nuxt module (Nuxt 4+)"
+  );
+}
+
+// src/defineNoydbStore.ts
+function defineNoydbStore(id, options) {
+  const collectionName = options.collection ?? id;
+  const prefetch = options.prefetch ?? true;
+  return (0, import_pinia.defineStore)(id, () => {
+    const items = (0, import_vue.shallowRef)([]);
+    const count = (0, import_vue.computed)(() => items.value.length);
+    let cachedCompartment = null;
+    let cachedCollection = null;
+    async function getCollection() {
+      if (cachedCollection) return cachedCollection;
+      const noydb = resolveNoydb(options.noydb ?? null);
+      cachedCompartment = await noydb.openCompartment(options.compartment);
+      cachedCollection = cachedCompartment.collection(collectionName);
+      return cachedCollection;
+    }
+    async function refresh() {
+      const c = await getCollection();
+      const list = await c.list();
+      items.value = list;
+    }
+    function byId(id2) {
+      for (const item of items.value) {
+        if (item.id === id2) return item;
+      }
+      return void 0;
+    }
+    async function add(id2, record) {
+      const validated = options.schema ? options.schema.parse(record) : record;
+      const c = await getCollection();
+      await c.put(id2, validated);
+      items.value = await c.list();
+    }
+    async function update(id2, record) {
+      await add(id2, record);
+    }
+    async function remove(id2) {
+      const c = await getCollection();
+      await c.delete(id2);
+      items.value = await c.list();
+    }
+    function query() {
+      if (!cachedCollection) {
+        throw new Error(
+          "@noy-db/pinia: query() called before the store was ready. Await store.$ready first, or set prefetch: true (default)."
+        );
+      }
+      return cachedCollection.query();
+    }
+    const $ready = prefetch ? refresh() : Promise.resolve();
+    return {
+      items,
+      count,
+      $ready,
+      byId,
+      add,
+      update,
+      remove,
+      refresh,
+      query
+    };
+  });
+}
+
+// src/plugin.ts
+var import_core = require("@noy-db/core");
+var STATE_DOC_ID = "__state__";
+function createNoydbPiniaPlugin(opts) {
+  let dbPromise = null;
+  function getDb() {
+    if (!dbPromise) {
+      dbPromise = (async () => {
+        const secret = await opts.secret();
+        return (0, import_core.createNoydb)({
+          adapter: opts.adapter,
+          user: opts.user,
+          secret,
+          ...opts.noydbOptions
+        });
+      })();
+    }
+    return dbPromise;
+  }
+  const compartmentCache = /* @__PURE__ */ new Map();
+  function getCompartment(name) {
+    let p = compartmentCache.get(name);
+    if (!p) {
+      p = getDb().then((db) => db.openCompartment(name));
+      compartmentCache.set(name, p);
+    }
+    return p;
+  }
+  return (context) => {
+    const noydbOption = context.options.noydb;
+    if (!noydbOption) {
+      context.store.$noydbAugmented = false;
+      return;
+    }
+    context.store.$noydbAugmented = true;
+    context.store.$noydbError = null;
+    const pending = /* @__PURE__ */ new Set();
+    const ready = (async () => {
+      try {
+        const compartment = await getCompartment(noydbOption.compartment);
+        const collection = compartment.collection(
+          noydbOption.collection
+        );
+        const persisted = await collection.get(STATE_DOC_ID);
+        if (persisted) {
+          const validated = noydbOption.schema ? noydbOption.schema.parse(persisted) : persisted;
+          const picked = pickKeys(validated, noydbOption.persist);
+          context.store.$patch(picked);
+        }
+        context.store.$subscribe(
+          (_mutation, state) => {
+            const subset = pickKeys(state, noydbOption.persist);
+            const p = collection.put(STATE_DOC_ID, subset).catch((err) => {
+              context.store.$noydbError = err instanceof Error ? err : new Error(String(err));
+            }).finally(() => {
+              pending.delete(p);
+            });
+            pending.add(p);
+          },
+          { detached: true }
+          // outlive the component that triggered the mutation
+        );
+      } catch (err) {
+        context.store.$noydbError = err instanceof Error ? err : new Error(String(err));
+      }
+    })();
+    context.store.$noydbReady = ready;
+    context.store.$noydbFlush = async () => {
+      await ready;
+      while (pending.size > 0) {
+        await Promise.all([...pending]);
+      }
+    };
+  };
+}
+function pickKeys(state, persist) {
+  if (persist === void 0 || persist === "*") {
+    return { ...state };
+  }
+  if (typeof persist === "string") {
+    return { [persist]: state[persist] };
+  }
+  if (Array.isArray(persist)) {
+    const out = {};
+    for (const key of persist) {
+      out[key] = state[key];
+    }
+    return out;
+  }
+  return { ...state };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createNoydbPiniaPlugin,
+  defineNoydbStore,
+  getActiveNoydb,
+  resolveNoydb,
+  setActiveNoydb
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/defineNoydbStore.ts","../src/context.ts","../src/plugin.ts"],"sourcesContent":["/**\n * @noy-db/pinia — Pinia integration for noy-db.\n *\n * Two adoption paths:\n *\n * 1. **Greenfield** — `defineNoydbStore<T>(id, options)` creates a new\n *    Pinia store fully wired to a NOYDB collection.\n *\n * 2. **Augmentation** — `createNoydbPiniaPlugin(options)` lets existing\n *    `defineStore()` stores opt into NOYDB persistence by adding one\n *    `noydb:` option, with no component code changes.\n *\n * Plus a global instance binding for both paths:\n *   - `setActiveNoydb(instance)` / `getActiveNoydb()` / `resolveNoydb()`\n */\n\nexport { defineNoydbStore } from './defineNoydbStore.js'\nexport type { NoydbStoreOptions, NoydbStore } from './defineNoydbStore.js'\nexport { setActiveNoydb, getActiveNoydb, resolveNoydb } from './context.js'\nexport { createNoydbPiniaPlugin } from './plugin.js'\nexport type { StoreNoydbOptions, NoydbPiniaPluginOptions } from './plugin.js'\n","/**\n * `defineNoydbStore` — drop-in `defineStore` that wires a Pinia store to a\n * NOYDB compartment + collection.\n *\n * Returned store exposes:\n *   - `items`        — reactive array of all records\n *   - `byId(id)`     — O(1) lookup\n *   - `count`        — reactive count getter\n *   - `add(id, rec)` — encrypt + persist + update reactive state\n *   - `update(id, rec)` — same as add (Collection.put is upsert)\n *   - `remove(id)`   — delete + update reactive state\n *   - `refresh()`    — re-hydrate from the adapter\n *   - `query()`      — chainable query DSL bound to the store\n *   - `$ready`       — Promise<void> resolved on first hydration\n *\n * Compatible with `storeToRefs`, Vue Devtools, SSR, and pinia plugins.\n */\n\nimport { defineStore } from 'pinia'\nimport { computed, shallowRef, type Ref, type ComputedRef } from 'vue'\nimport type { Noydb, Compartment, Collection, Query } from '@noy-db/core'\nimport { resolveNoydb } from './context.js'\n\n/**\n * Options accepted by `defineNoydbStore`.\n *\n * Generic `T` is the record shape — defaults to `unknown` if the caller\n * doesn't supply a type. Use `defineNoydbStore<Invoice>('invoices', {...})`\n * for full type safety.\n */\nexport interface NoydbStoreOptions<T> {\n  /** Compartment (tenant) name. */\n  compartment: string\n  /** Collection name within the compartment. Defaults to the store id. */\n  collection?: string\n  /**\n   * Optional explicit Noydb instance. If omitted, the store resolves the\n   * globally bound instance via `getActiveNoydb()`.\n   */\n  noydb?: Noydb | null\n  /**\n   * If true (default), hydration kicks off immediately when the store is\n   * first instantiated. If false, hydration is deferred until the first\n   * call to `refresh()` or any read accessor.\n   */\n  prefetch?: boolean\n  /**\n   * Optional schema validator. Any object exposing a `parse(input): T`\n   * method (Zod, Valibot, ArkType, etc.) is accepted.\n   */\n  schema?: { parse: (input: unknown) => T }\n}\n\n/**\n * The runtime shape of the store returned by `defineNoydbStore`.\n * Exposed as a public type so consumers can write `useStore: ReturnType<typeof useInvoices>`.\n */\nexport interface NoydbStore<T> {\n  items: Ref<T[]>\n  count: ComputedRef<number>\n  $ready: Promise<void>\n  byId(id: string): T | undefined\n  add(id: string, record: T): Promise<void>\n  update(id: string, record: T): Promise<void>\n  remove(id: string): Promise<void>\n  refresh(): Promise<void>\n  query(): Query<T>\n}\n\n/**\n * Define a Pinia store that's wired to a NOYDB collection.\n *\n * Generic T defaults to `unknown` — pass `<MyType>` for full type inference.\n *\n * @example\n * ```ts\n * import { defineNoydbStore } from '@noy-db/pinia';\n *\n * export const useInvoices = defineNoydbStore<Invoice>('invoices', {\n *   compartment: 'C101',\n *   schema: InvoiceSchema, // optional\n * });\n * ```\n */\nexport function defineNoydbStore<T>(\n  id: string,\n  options: NoydbStoreOptions<T>,\n) {\n  const collectionName = options.collection ?? id\n  const prefetch = options.prefetch ?? true\n\n  return defineStore(id, () => {\n    // Reactive state. shallowRef on items because the array reference is what\n    // changes — replacing it triggers reactivity without per-record proxying.\n    const items: Ref<T[]> = shallowRef<T[]>([])\n    const count = computed(() => items.value.length)\n\n    // Lazy collection handle — created on first hydrate.\n    let cachedCompartment: Compartment | null = null\n    let cachedCollection: Collection<T> | null = null\n\n    async function getCollection(): Promise<Collection<T>> {\n      if (cachedCollection) return cachedCollection\n      const noydb = resolveNoydb(options.noydb ?? null)\n      cachedCompartment = await noydb.openCompartment(options.compartment)\n      cachedCollection = cachedCompartment.collection<T>(collectionName)\n      return cachedCollection\n    }\n\n    async function refresh(): Promise<void> {\n      const c = await getCollection()\n      const list = await c.list()\n      items.value = list\n    }\n\n    function byId(id: string): T | undefined {\n      // Linear scan against the reactive cache. Index-aware lookups land in #13.\n      // Optimization opportunity: maintain a Map<string, T> alongside items.\n      for (const item of items.value) {\n        if ((item as { id?: string }).id === id) return item\n      }\n      return undefined\n    }\n\n    async function add(id: string, record: T): Promise<void> {\n      const validated = options.schema ? options.schema.parse(record) : record\n      const c = await getCollection()\n      await c.put(id, validated)\n      // Re-list to pick up the new record. Cheaper alternative would be to\n      // splice into items.value directly, but list() ensures consistency\n      // with the underlying cache.\n      items.value = await c.list()\n    }\n\n    async function update(id: string, record: T): Promise<void> {\n      // Collection.put is upsert; this is just a more readable alias.\n      await add(id, record)\n    }\n\n    async function remove(id: string): Promise<void> {\n      const c = await getCollection()\n      await c.delete(id)\n      items.value = await c.list()\n    }\n\n    function query(): Query<T> {\n      // Synchronous query() requires the collection to be hydrated.\n      // The lazy refresh() in $ready handles that — but if the user calls\n      // query() before $ready resolves, the collection still works because\n      // Collection.query() reads from its own internal cache (which Noydb\n      // hydrates lazily as well).\n      if (!cachedCollection) {\n        throw new Error(\n          '@noy-db/pinia: query() called before the store was ready. ' +\n          'Await store.$ready first, or set prefetch: true (default).',\n        )\n      }\n      return cachedCollection.query()\n    }\n\n    // Kick off hydration. The promise is exposed as $ready so components\n    // can `await store.$ready` before rendering data-dependent UI.\n    const $ready: Promise<void> = prefetch\n      ? refresh()\n      : Promise.resolve()\n\n    return {\n      items,\n      count,\n      $ready,\n      byId,\n      add,\n      update,\n      remove,\n      refresh,\n      query,\n    }\n  })\n}\n","/**\n * Active NOYDB instance binding.\n *\n * `defineNoydbStore` resolves the `Noydb` instance from one of three places,\n * in priority order:\n *\n *   1. The store options' explicit `noydb:` field (highest precedence — useful\n *      for tests and multi-database apps).\n *   2. A globally bound instance set via `setActiveNoydb()` — this is what the\n *      Nuxt module's runtime plugin and playground apps use.\n *   3. Throws a clear error if neither is set.\n *\n * Keeping the binding pluggable means tests can pass an instance directly\n * without polluting global state.\n */\n\nimport type { Noydb } from '@noy-db/core'\n\nlet activeInstance: Noydb | null = null\n\n/** Bind a Noydb instance globally. Called by the Nuxt module / app plugin. */\nexport function setActiveNoydb(instance: Noydb | null): void {\n  activeInstance = instance\n}\n\n/** Returns the globally bound Noydb instance, or null if none. */\nexport function getActiveNoydb(): Noydb | null {\n  return activeInstance\n}\n\n/**\n * Resolve the Noydb instance to use for a store. Throws if no instance is\n * bound — the error message points the developer at the three options.\n */\nexport function resolveNoydb(explicit?: Noydb | null): Noydb {\n  if (explicit) return explicit\n  if (activeInstance) return activeInstance\n  throw new Error(\n    '@noy-db/pinia: no Noydb instance bound.\\n' +\n    '  Option A — pass `noydb:` directly to defineNoydbStore({...})\\n' +\n    '  Option B — call setActiveNoydb(instance) once at app startup\\n' +\n    '  Option C — install the @noy-db/nuxt module (Nuxt 4+)',\n  )\n}\n","/**\n * `createNoydbPiniaPlugin` — augmentation path for existing Pinia stores.\n *\n * Lets a developer take any existing `defineStore()` call and opt into NOYDB\n * persistence by adding a single `noydb:` option, without touching component\n * code. The plugin watches the chosen state key(s), encrypts on change, syncs\n * to a NOYDB collection, and rehydrates on store init.\n *\n * @example\n * ```ts\n * import { createPinia } from 'pinia';\n * import { createNoydbPiniaPlugin } from '@noy-db/pinia';\n * import { jsonFile } from '@noy-db/file';\n *\n * const pinia = createPinia();\n * pinia.use(createNoydbPiniaPlugin({\n *   adapter: jsonFile({ dir: './data' }),\n *   user: 'owner-01',\n *   secret: () => promptPassphrase(),\n * }));\n *\n * // existing store — add one option, no component changes:\n * export const useClients = defineStore('clients', {\n *   state: () => ({ list: [] as Client[] }),\n *   noydb: { compartment: 'C101', collection: 'clients', persist: 'list' },\n * });\n * ```\n *\n * Design notes\n * ------------\n * - Each augmented store persists a SINGLE document at id `__state__`\n *   containing the picked keys. We don't try to map state arrays onto\n *   per-element records — that's `defineNoydbStore`'s territory.\n * - The Noydb instance is constructed lazily on first store-with-noydb\n *   instantiation, then memoized for the lifetime of the Pinia app.\n *   This means apps that don't actually use any noydb-augmented stores\n *   pay zero crypto cost.\n * - `secret` is a function so the passphrase can come from a prompt,\n *   biometric unlock, or session token — never stored in config.\n * - The plugin sets `store.$noydbReady` (a `Promise<void>`) and\n *   `store.$noydbError` (an `Error | null`) on every augmented store\n *   so components can await hydration and surface failures.\n */\n\nimport type { PiniaPluginContext, PiniaPlugin, StateTree } from 'pinia'\nimport { createNoydb, type Noydb, type NoydbOptions, type NoydbAdapter, type Compartment, type Collection } from '@noy-db/core'\n\n/**\n * Per-store NOYDB configuration. Attached to a Pinia store via the `noydb`\n * option inside `defineStore({ ..., noydb: {...} })`.\n *\n * `persist` selects which top-level state keys to mirror into NOYDB.\n * Pass a single key, an array of keys, or `'*'` to mirror the entire state.\n */\nexport interface StoreNoydbOptions<S extends StateTree = StateTree> {\n  /** Compartment (tenant) name. */\n  compartment: string\n  /** Collection name within the compartment. */\n  collection: string\n  /**\n   * Which state keys to persist. Defaults to `'*'` (the entire state object).\n   * Pass a string or string[] to scope to specific keys.\n   */\n  persist?: keyof S | (keyof S)[] | '*'\n  /**\n   * Optional schema validator applied at the document level (the persisted\n   * subset of state, not individual records). Throws if validation fails on\n   * hydration — the store stays at its initial state and `$noydbError` is set.\n   */\n  schema?: { parse: (input: unknown) => unknown }\n}\n\n/**\n * Configuration for `createNoydbPiniaPlugin`. Mirrors `NoydbOptions` but\n * makes `secret` a function so the passphrase can come from a prompt\n * rather than being stored in config.\n */\nexport interface NoydbPiniaPluginOptions {\n  /** The NOYDB adapter to use for persistence. */\n  adapter: NoydbAdapter\n  /** User identifier (matches the keyring file). */\n  user: string\n  /**\n   * Passphrase provider. Called once on first noydb-augmented store\n   * instantiation. Return a string or a Promise that resolves to one.\n   */\n  secret: () => string | Promise<string>\n  /** Optional Noydb open-options forwarded to `createNoydb`. */\n  noydbOptions?: Partial<Omit<NoydbOptions, 'adapter' | 'user' | 'secret'>>\n}\n\n// The fixed document id under which a store's persisted state lives. Using a\n// reserved prefix so it can't collide with any user-chosen record id.\nconst STATE_DOC_ID = '__state__'\n\n/**\n * Create a Pinia plugin that wires NOYDB persistence into any store\n * declaring a `noydb:` option.\n *\n * Returns a `PiniaPlugin` directly usable with `pinia.use(...)`.\n */\nexport function createNoydbPiniaPlugin(opts: NoydbPiniaPluginOptions): PiniaPlugin {\n  // Single Noydb instance shared across all augmented stores in this Pinia\n  // app. Created lazily on first use so apps that never instantiate a\n  // noydb-augmented store pay zero crypto cost.\n  let dbPromise: Promise<Noydb> | null = null\n  function getDb(): Promise<Noydb> {\n    if (!dbPromise) {\n      dbPromise = (async (): Promise<Noydb> => {\n        const secret = await opts.secret()\n        return createNoydb({\n          adapter: opts.adapter,\n          user: opts.user,\n          secret,\n          ...opts.noydbOptions,\n        })\n      })()\n    }\n    return dbPromise\n  }\n\n  // Compartment cache so opening a compartment is a one-time cost per app.\n  const compartmentCache = new Map<string, Promise<Compartment>>()\n  function getCompartment(name: string): Promise<Compartment> {\n    let p = compartmentCache.get(name)\n    if (!p) {\n      p = getDb().then((db) => db.openCompartment(name))\n      compartmentCache.set(name, p)\n    }\n    return p\n  }\n\n  return (context: PiniaPluginContext) => {\n    // Pinia stores can declare arbitrary options on `defineStore`, but the\n    // plugin context only exposes them via `context.options`. Pull our\n    // `noydb` option out and bail early if it's not present — that's\n    // the \"store is untouched\" path for non-augmented stores.\n    const noydbOption = (context.options as { noydb?: StoreNoydbOptions }).noydb\n    if (!noydbOption) {\n      // Mark the store as opted-out so devtools / consumers can detect it.\n      context.store.$noydbAugmented = false\n      return\n    }\n\n    context.store.$noydbAugmented = true\n    context.store.$noydbError = null as Error | null\n\n    // Track in-flight persistence promises so tests (and consumers) can\n    // await deterministic flushes via `$noydbFlush()`. Plain Set-of-Promises\n    // — entries auto-remove on settle.\n    const pending = new Set<Promise<void>>()\n\n    // Hydrate-then-subscribe. Both happen inside an async closure so the\n    // store can be awaited via `$noydbReady`.\n    const ready = (async (): Promise<void> => {\n      try {\n        const compartment = await getCompartment(noydbOption.compartment)\n        const collection: Collection<StateTree> = compartment.collection<StateTree>(\n          noydbOption.collection,\n        )\n\n        // 1. Hydration: read the persisted document (if any) and apply\n        //    the picked keys onto the store's current state. We use\n        //    `$patch` so reactivity fires correctly.\n        const persisted = await collection.get(STATE_DOC_ID)\n        if (persisted) {\n          const validated = noydbOption.schema\n            ? (noydbOption.schema.parse(persisted) as StateTree)\n            : persisted\n          const picked = pickKeys(validated, noydbOption.persist)\n          context.store.$patch(picked)\n        }\n\n        // 2. Subscribe: every state mutation triggers an encrypted write\n        //    of the picked subset back to NOYDB. The subscription captures\n        //    `collection` so it doesn't re-resolve on every event.\n        context.store.$subscribe(\n          (_mutation, state) => {\n            const subset = pickKeys(state, noydbOption.persist)\n            const p = collection.put(STATE_DOC_ID, subset)\n              .catch((err: unknown) => {\n                context.store.$noydbError = err instanceof Error ? err : new Error(String(err))\n              })\n              .finally(() => {\n                pending.delete(p)\n              })\n            pending.add(p)\n          },\n          { detached: true }, // outlive the component that triggered the mutation\n        )\n      } catch (err) {\n        context.store.$noydbError = err instanceof Error ? err : new Error(String(err))\n      }\n    })()\n\n    context.store.$noydbReady = ready\n    /**\n     * Wait for all in-flight persistence puts to settle. Use this in tests\n     * to deterministically observe the encrypted state on the adapter, and\n     * in app code before unmounting components that mutated the store.\n     */\n    context.store.$noydbFlush = async (): Promise<void> => {\n      await ready\n      // Snapshot the current pending set; new puts added during await\n      // are picked up by the next $noydbFlush() call.\n      while (pending.size > 0) {\n        await Promise.all([...pending])\n      }\n    }\n  }\n}\n\n/**\n * Pick the configured subset of keys from a state object.\n *\n * Behaviors:\n *   - `undefined` or `'*'` → returns the entire state shallow-copied\n *   - single key string → returns `{ [key]: state[key] }`\n *   - key array → returns `{ [k1]: state[k1], [k2]: state[k2], ... }`\n *\n * The result is always a fresh object so callers can mutate it without\n * touching the store's reactive state.\n */\nfunction pickKeys(state: StateTree, persist: StoreNoydbOptions['persist']): StateTree {\n  if (persist === undefined || persist === '*') {\n    return { ...state }\n  }\n  if (typeof persist === 'string') {\n    return { [persist]: state[persist] } as StateTree\n  }\n  if (Array.isArray(persist)) {\n    const out: StateTree = {}\n    for (const key of persist) {\n      out[key as string] = state[key as string]\n    }\n    return out\n  }\n  // Should be unreachable thanks to the type, but defensive default.\n  return { ...state }\n}\n\n// ─── Pinia module augmentation ─────────────────────────────────────\n//\n// Pinia exposes `DefineStoreOptionsBase` as the place where third-party\n// plugins are expected to attach their custom option types. Augmenting it\n// here means `defineStore('x', { ..., noydb: {...} })` autocompletes inside\n// the IDE and type-checks correctly without forcing users to import\n// anything from `@noy-db/pinia`.\n//\n// We also augment `PiniaCustomProperties` so the runtime fields we add to\n// every store (`$noydbReady`, `$noydbError`, `$noydbAugmented`) are typed.\n\ndeclare module 'pinia' {\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  export interface DefineStoreOptionsBase<S extends StateTree, Store> {\n    /**\n     * Opt this store into NOYDB persistence via the\n     * `createNoydbPiniaPlugin` augmentation plugin.\n     *\n     * The chosen state keys are encrypted and persisted to the configured\n     * compartment + collection on every mutation, and rehydrated on first\n     * store access.\n     */\n    noydb?: StoreNoydbOptions<S>\n  }\n\n  export interface PiniaCustomProperties {\n    /**\n     * Resolves once this store has finished its initial hydration from\n     * NOYDB. `undefined` for stores that don't declare a `noydb:` option.\n     */\n    $noydbReady?: Promise<void>\n    /**\n     * Set when hydration or persistence fails. `null` while healthy.\n     * Plugins (and devtools) can poll this to surface storage errors.\n     */\n    $noydbError?: Error | null\n    /**\n     * `true` if this store opted into NOYDB persistence via the `noydb:`\n     * option, `false` otherwise. Useful for debugging and devtools.\n     */\n    $noydbAugmented?: boolean\n    /**\n     * Wait for all in-flight encrypted persistence puts to complete.\n     * Useful in tests for deterministic flushing, and in app code before\n     * unmounting components that just mutated the store.\n     */\n    $noydbFlush?: () => Promise<void>\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACkBA,mBAA4B;AAC5B,iBAAiE;;;ACDjE,IAAI,iBAA+B;AAG5B,SAAS,eAAe,UAA8B;AAC3D,mBAAiB;AACnB;AAGO,SAAS,iBAA+B;AAC7C,SAAO;AACT;AAMO,SAAS,aAAa,UAAgC;AAC3D,MAAI,SAAU,QAAO;AACrB,MAAI,eAAgB,QAAO;AAC3B,QAAM,IAAI;AAAA,IACR;AAAA,EAIF;AACF;;;ADyCO,SAAS,iBACd,IACA,SACA;AACA,QAAM,iBAAiB,QAAQ,cAAc;AAC7C,QAAM,WAAW,QAAQ,YAAY;AAErC,aAAO,0BAAY,IAAI,MAAM;AAG3B,UAAM,YAAkB,uBAAgB,CAAC,CAAC;AAC1C,UAAM,YAAQ,qBAAS,MAAM,MAAM,MAAM,MAAM;AAG/C,QAAI,oBAAwC;AAC5C,QAAI,mBAAyC;AAE7C,mBAAe,gBAAwC;AACrD,UAAI,iBAAkB,QAAO;AAC7B,YAAM,QAAQ,aAAa,QAAQ,SAAS,IAAI;AAChD,0BAAoB,MAAM,MAAM,gBAAgB,QAAQ,WAAW;AACnE,yBAAmB,kBAAkB,WAAc,cAAc;AACjE,aAAO;AAAA,IACT;AAEA,mBAAe,UAAyB;AACtC,YAAM,IAAI,MAAM,cAAc;AAC9B,YAAM,OAAO,MAAM,EAAE,KAAK;AAC1B,YAAM,QAAQ;AAAA,IAChB;AAEA,aAAS,KAAKA,KAA2B;AAGvC,iBAAW,QAAQ,MAAM,OAAO;AAC9B,YAAK,KAAyB,OAAOA,IAAI,QAAO;AAAA,MAClD;AACA,aAAO;AAAA,IACT;AAEA,mBAAe,IAAIA,KAAY,QAA0B;AACvD,YAAM,YAAY,QAAQ,SAAS,QAAQ,OAAO,MAAM,MAAM,IAAI;AAClE,YAAM,IAAI,MAAM,cAAc;AAC9B,YAAM,EAAE,IAAIA,KAAI,SAAS;AAIzB,YAAM,QAAQ,MAAM,EAAE,KAAK;AAAA,IAC7B;AAEA,mBAAe,OAAOA,KAAY,QAA0B;AAE1D,YAAM,IAAIA,KAAI,MAAM;AAAA,IACtB;AAEA,mBAAe,OAAOA,KAA2B;AAC/C,YAAM,IAAI,MAAM,cAAc;AAC9B,YAAM,EAAE,OAAOA,GAAE;AACjB,YAAM,QAAQ,MAAM,EAAE,KAAK;AAAA,IAC7B;AAEA,aAAS,QAAkB;AAMzB,UAAI,CAAC,kBAAkB;AACrB,cAAM,IAAI;AAAA,UACR;AAAA,QAEF;AAAA,MACF;AACA,aAAO,iBAAiB,MAAM;AAAA,IAChC;AAIA,UAAM,SAAwB,WAC1B,QAAQ,IACR,QAAQ,QAAQ;AAEpB,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF,CAAC;AACH;;;AErIA,kBAAiH;AAgDjH,IAAM,eAAe;AAQd,SAAS,uBAAuB,MAA4C;AAIjF,MAAI,YAAmC;AACvC,WAAS,QAAwB;AAC/B,QAAI,CAAC,WAAW;AACd,mBAAa,YAA4B;AACvC,cAAM,SAAS,MAAM,KAAK,OAAO;AACjC,mBAAO,yBAAY;AAAA,UACjB,SAAS,KAAK;AAAA,UACd,MAAM,KAAK;AAAA,UACX;AAAA,UACA,GAAG,KAAK;AAAA,QACV,CAAC;AAAA,MACH,GAAG;AAAA,IACL;AACA,WAAO;AAAA,EACT;AAGA,QAAM,mBAAmB,oBAAI,IAAkC;AAC/D,WAAS,eAAe,MAAoC;AAC1D,QAAI,IAAI,iBAAiB,IAAI,IAAI;AACjC,QAAI,CAAC,GAAG;AACN,UAAI,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,gBAAgB,IAAI,CAAC;AACjD,uBAAiB,IAAI,MAAM,CAAC;AAAA,IAC9B;AACA,WAAO;AAAA,EACT;AAEA,SAAO,CAAC,YAAgC;AAKtC,UAAM,cAAe,QAAQ,QAA0C;AACvE,QAAI,CAAC,aAAa;AAEhB,cAAQ,MAAM,kBAAkB;AAChC;AAAA,IACF;AAEA,YAAQ,MAAM,kBAAkB;AAChC,YAAQ,MAAM,cAAc;AAK5B,UAAM,UAAU,oBAAI,IAAmB;AAIvC,UAAM,SAAS,YAA2B;AACxC,UAAI;AACF,cAAM,cAAc,MAAM,eAAe,YAAY,WAAW;AAChE,cAAM,aAAoC,YAAY;AAAA,UACpD,YAAY;AAAA,QACd;AAKA,cAAM,YAAY,MAAM,WAAW,IAAI,YAAY;AACnD,YAAI,WAAW;AACb,gBAAM,YAAY,YAAY,SACzB,YAAY,OAAO,MAAM,SAAS,IACnC;AACJ,gBAAM,SAAS,SAAS,WAAW,YAAY,OAAO;AACtD,kBAAQ,MAAM,OAAO,MAAM;AAAA,QAC7B;AAKA,gBAAQ,MAAM;AAAA,UACZ,CAAC,WAAW,UAAU;AACpB,kBAAM,SAAS,SAAS,OAAO,YAAY,OAAO;AAClD,kBAAM,IAAI,WAAW,IAAI,cAAc,MAAM,EAC1C,MAAM,CAAC,QAAiB;AACvB,sBAAQ,MAAM,cAAc,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAAA,YAChF,CAAC,EACA,QAAQ,MAAM;AACb,sBAAQ,OAAO,CAAC;AAAA,YAClB,CAAC;AACH,oBAAQ,IAAI,CAAC;AAAA,UACf;AAAA,UACA,EAAE,UAAU,KAAK;AAAA;AAAA,QACnB;AAAA,MACF,SAAS,KAAK;AACZ,gBAAQ,MAAM,cAAc,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAAA,MAChF;AAAA,IACF,GAAG;AAEH,YAAQ,MAAM,cAAc;AAM5B,YAAQ,MAAM,cAAc,YAA2B;AACrD,YAAM;AAGN,aAAO,QAAQ,OAAO,GAAG;AACvB,cAAM,QAAQ,IAAI,CAAC,GAAG,OAAO,CAAC;AAAA,MAChC;AAAA,IACF;AAAA,EACF;AACF;AAaA,SAAS,SAAS,OAAkB,SAAkD;AACpF,MAAI,YAAY,UAAa,YAAY,KAAK;AAC5C,WAAO,EAAE,GAAG,MAAM;AAAA,EACpB;AACA,MAAI,OAAO,YAAY,UAAU;AAC/B,WAAO,EAAE,CAAC,OAAO,GAAG,MAAM,OAAO,EAAE;AAAA,EACrC;AACA,MAAI,MAAM,QAAQ,OAAO,GAAG;AAC1B,UAAM,MAAiB,CAAC;AACxB,eAAW,OAAO,SAAS;AACzB,UAAI,GAAa,IAAI,MAAM,GAAa;AAAA,IAC1C;AACA,WAAO;AAAA,EACT;AAEA,SAAO,EAAE,GAAG,MAAM;AACpB;","names":["id"]}

package/dist/index.d.cts

@@ -0,0 +1,257 @@
+import * as pinia from 'pinia';
+import { StateTree, PiniaPlugin } from 'pinia';
+import { Ref, ComputedRef } from 'vue';
+import { Query, Noydb, NoydbAdapter, NoydbOptions } from '@noy-db/core';
+
+/**
+ * Options accepted by `defineNoydbStore`.
+ *
+ * Generic `T` is the record shape — defaults to `unknown` if the caller
+ * doesn't supply a type. Use `defineNoydbStore<Invoice>('invoices', {...})`
+ * for full type safety.
+ */
+interface NoydbStoreOptions<T> {
+    /** Compartment (tenant) name. */
+    compartment: string;
+    /** Collection name within the compartment. Defaults to the store id. */
+    collection?: string;
+    /**
+     * Optional explicit Noydb instance. If omitted, the store resolves the
+     * globally bound instance via `getActiveNoydb()`.
+     */
+    noydb?: Noydb | null;
+    /**
+     * If true (default), hydration kicks off immediately when the store is
+     * first instantiated. If false, hydration is deferred until the first
+     * call to `refresh()` or any read accessor.
+     */
+    prefetch?: boolean;
+    /**
+     * Optional schema validator. Any object exposing a `parse(input): T`
+     * method (Zod, Valibot, ArkType, etc.) is accepted.
+     */
+    schema?: {
+        parse: (input: unknown) => T;
+    };
+}
+/**
+ * The runtime shape of the store returned by `defineNoydbStore`.
+ * Exposed as a public type so consumers can write `useStore: ReturnType<typeof useInvoices>`.
+ */
+interface NoydbStore<T> {
+    items: Ref<T[]>;
+    count: ComputedRef<number>;
+    $ready: Promise<void>;
+    byId(id: string): T | undefined;
+    add(id: string, record: T): Promise<void>;
+    update(id: string, record: T): Promise<void>;
+    remove(id: string): Promise<void>;
+    refresh(): Promise<void>;
+    query(): Query<T>;
+}
+/**
+ * Define a Pinia store that's wired to a NOYDB collection.
+ *
+ * Generic T defaults to `unknown` — pass `<MyType>` for full type inference.
+ *
+ * @example
+ * ```ts
+ * import { defineNoydbStore } from '@noy-db/pinia';
+ *
+ * export const useInvoices = defineNoydbStore<Invoice>('invoices', {
+ *   compartment: 'C101',
+ *   schema: InvoiceSchema, // optional
+ * });
+ * ```
+ */
+declare function defineNoydbStore<T>(id: string, options: NoydbStoreOptions<T>): pinia.StoreDefinition<string, Pick<{
+    items: Ref<T[], T[]>;
+    count: ComputedRef<number>;
+    $ready: Promise<void>;
+    byId: (id: string) => T | undefined;
+    add: (id: string, record: T) => Promise<void>;
+    update: (id: string, record: T) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    refresh: () => Promise<void>;
+    query: () => Query<T>;
+}, "items" | "$ready">, Pick<{
+    items: Ref<T[], T[]>;
+    count: ComputedRef<number>;
+    $ready: Promise<void>;
+    byId: (id: string) => T | undefined;
+    add: (id: string, record: T) => Promise<void>;
+    update: (id: string, record: T) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    refresh: () => Promise<void>;
+    query: () => Query<T>;
+}, "count">, Pick<{
+    items: Ref<T[], T[]>;
+    count: ComputedRef<number>;
+    $ready: Promise<void>;
+    byId: (id: string) => T | undefined;
+    add: (id: string, record: T) => Promise<void>;
+    update: (id: string, record: T) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    refresh: () => Promise<void>;
+    query: () => Query<T>;
+}, "byId" | "add" | "update" | "remove" | "refresh" | "query">>;
+
+/**
+ * Active NOYDB instance binding.
+ *
+ * `defineNoydbStore` resolves the `Noydb` instance from one of three places,
+ * in priority order:
+ *
+ *   1. The store options' explicit `noydb:` field (highest precedence — useful
+ *      for tests and multi-database apps).
+ *   2. A globally bound instance set via `setActiveNoydb()` — this is what the
+ *      Nuxt module's runtime plugin and playground apps use.
+ *   3. Throws a clear error if neither is set.
+ *
+ * Keeping the binding pluggable means tests can pass an instance directly
+ * without polluting global state.
+ */
+
+/** Bind a Noydb instance globally. Called by the Nuxt module / app plugin. */
+declare function setActiveNoydb(instance: Noydb | null): void;
+/** Returns the globally bound Noydb instance, or null if none. */
+declare function getActiveNoydb(): Noydb | null;
+/**
+ * Resolve the Noydb instance to use for a store. Throws if no instance is
+ * bound — the error message points the developer at the three options.
+ */
+declare function resolveNoydb(explicit?: Noydb | null): Noydb;
+
+/**
+ * `createNoydbPiniaPlugin` — augmentation path for existing Pinia stores.
+ *
+ * Lets a developer take any existing `defineStore()` call and opt into NOYDB
+ * persistence by adding a single `noydb:` option, without touching component
+ * code. The plugin watches the chosen state key(s), encrypts on change, syncs
+ * to a NOYDB collection, and rehydrates on store init.
+ *
+ * @example
+ * ```ts
+ * import { createPinia } from 'pinia';
+ * import { createNoydbPiniaPlugin } from '@noy-db/pinia';
+ * import { jsonFile } from '@noy-db/file';
+ *
+ * const pinia = createPinia();
+ * pinia.use(createNoydbPiniaPlugin({
+ *   adapter: jsonFile({ dir: './data' }),
+ *   user: 'owner-01',
+ *   secret: () => promptPassphrase(),
+ * }));
+ *
+ * // existing store — add one option, no component changes:
+ * export const useClients = defineStore('clients', {
+ *   state: () => ({ list: [] as Client[] }),
+ *   noydb: { compartment: 'C101', collection: 'clients', persist: 'list' },
+ * });
+ * ```
+ *
+ * Design notes
+ * ------------
+ * - Each augmented store persists a SINGLE document at id `__state__`
+ *   containing the picked keys. We don't try to map state arrays onto
+ *   per-element records — that's `defineNoydbStore`'s territory.
+ * - The Noydb instance is constructed lazily on first store-with-noydb
+ *   instantiation, then memoized for the lifetime of the Pinia app.
+ *   This means apps that don't actually use any noydb-augmented stores
+ *   pay zero crypto cost.
+ * - `secret` is a function so the passphrase can come from a prompt,
+ *   biometric unlock, or session token — never stored in config.
+ * - The plugin sets `store.$noydbReady` (a `Promise<void>`) and
+ *   `store.$noydbError` (an `Error | null`) on every augmented store
+ *   so components can await hydration and surface failures.
+ */
+
+/**
+ * Per-store NOYDB configuration. Attached to a Pinia store via the `noydb`
+ * option inside `defineStore({ ..., noydb: {...} })`.
+ *
+ * `persist` selects which top-level state keys to mirror into NOYDB.
+ * Pass a single key, an array of keys, or `'*'` to mirror the entire state.
+ */
+interface StoreNoydbOptions<S extends StateTree = StateTree> {
+    /** Compartment (tenant) name. */
+    compartment: string;
+    /** Collection name within the compartment. */
+    collection: string;
+    /**
+     * Which state keys to persist. Defaults to `'*'` (the entire state object).
+     * Pass a string or string[] to scope to specific keys.
+     */
+    persist?: keyof S | (keyof S)[] | '*';
+    /**
+     * Optional schema validator applied at the document level (the persisted
+     * subset of state, not individual records). Throws if validation fails on
+     * hydration — the store stays at its initial state and `$noydbError` is set.
+     */
+    schema?: {
+        parse: (input: unknown) => unknown;
+    };
+}
+/**
+ * Configuration for `createNoydbPiniaPlugin`. Mirrors `NoydbOptions` but
+ * makes `secret` a function so the passphrase can come from a prompt
+ * rather than being stored in config.
+ */
+interface NoydbPiniaPluginOptions {
+    /** The NOYDB adapter to use for persistence. */
+    adapter: NoydbAdapter;
+    /** User identifier (matches the keyring file). */
+    user: string;
+    /**
+     * Passphrase provider. Called once on first noydb-augmented store
+     * instantiation. Return a string or a Promise that resolves to one.
+     */
+    secret: () => string | Promise<string>;
+    /** Optional Noydb open-options forwarded to `createNoydb`. */
+    noydbOptions?: Partial<Omit<NoydbOptions, 'adapter' | 'user' | 'secret'>>;
+}
+/**
+ * Create a Pinia plugin that wires NOYDB persistence into any store
+ * declaring a `noydb:` option.
+ *
+ * Returns a `PiniaPlugin` directly usable with `pinia.use(...)`.
+ */
+declare function createNoydbPiniaPlugin(opts: NoydbPiniaPluginOptions): PiniaPlugin;
+declare module 'pinia' {
+    interface DefineStoreOptionsBase<S extends StateTree, Store> {
+        /**
+         * Opt this store into NOYDB persistence via the
+         * `createNoydbPiniaPlugin` augmentation plugin.
+         *
+         * The chosen state keys are encrypted and persisted to the configured
+         * compartment + collection on every mutation, and rehydrated on first
+         * store access.
+         */
+        noydb?: StoreNoydbOptions<S>;
+    }
+    interface PiniaCustomProperties {
+        /**
+         * Resolves once this store has finished its initial hydration from
+         * NOYDB. `undefined` for stores that don't declare a `noydb:` option.
+         */
+        $noydbReady?: Promise<void>;
+        /**
+         * Set when hydration or persistence fails. `null` while healthy.
+         * Plugins (and devtools) can poll this to surface storage errors.
+         */
+        $noydbError?: Error | null;
+        /**
+         * `true` if this store opted into NOYDB persistence via the `noydb:`
+         * option, `false` otherwise. Useful for debugging and devtools.
+         */
+        $noydbAugmented?: boolean;
+        /**
+         * Wait for all in-flight encrypted persistence puts to complete.
+         * Useful in tests for deterministic flushing, and in app code before
+         * unmounting components that just mutated the store.
+         */
+        $noydbFlush?: () => Promise<void>;
+    }
+}
+
+export { type NoydbPiniaPluginOptions, type NoydbStore, type NoydbStoreOptions, type StoreNoydbOptions, createNoydbPiniaPlugin, defineNoydbStore, getActiveNoydb, resolveNoydb, setActiveNoydb };

package/dist/index.d.ts

@@ -0,0 +1,257 @@
+import * as pinia from 'pinia';
+import { StateTree, PiniaPlugin } from 'pinia';
+import { Ref, ComputedRef } from 'vue';
+import { Query, Noydb, NoydbAdapter, NoydbOptions } from '@noy-db/core';
+
+/**
+ * Options accepted by `defineNoydbStore`.
+ *
+ * Generic `T` is the record shape — defaults to `unknown` if the caller
+ * doesn't supply a type. Use `defineNoydbStore<Invoice>('invoices', {...})`
+ * for full type safety.
+ */
+interface NoydbStoreOptions<T> {
+    /** Compartment (tenant) name. */
+    compartment: string;
+    /** Collection name within the compartment. Defaults to the store id. */
+    collection?: string;
+    /**
+     * Optional explicit Noydb instance. If omitted, the store resolves the
+     * globally bound instance via `getActiveNoydb()`.
+     */
+    noydb?: Noydb | null;
+    /**
+     * If true (default), hydration kicks off immediately when the store is
+     * first instantiated. If false, hydration is deferred until the first
+     * call to `refresh()` or any read accessor.
+     */
+    prefetch?: boolean;
+    /**
+     * Optional schema validator. Any object exposing a `parse(input): T`
+     * method (Zod, Valibot, ArkType, etc.) is accepted.
+     */
+    schema?: {
+        parse: (input: unknown) => T;
+    };
+}
+/**
+ * The runtime shape of the store returned by `defineNoydbStore`.
+ * Exposed as a public type so consumers can write `useStore: ReturnType<typeof useInvoices>`.
+ */
+interface NoydbStore<T> {
+    items: Ref<T[]>;
+    count: ComputedRef<number>;
+    $ready: Promise<void>;
+    byId(id: string): T | undefined;
+    add(id: string, record: T): Promise<void>;
+    update(id: string, record: T): Promise<void>;
+    remove(id: string): Promise<void>;
+    refresh(): Promise<void>;
+    query(): Query<T>;
+}
+/**
+ * Define a Pinia store that's wired to a NOYDB collection.
+ *
+ * Generic T defaults to `unknown` — pass `<MyType>` for full type inference.
+ *
+ * @example
+ * ```ts
+ * import { defineNoydbStore } from '@noy-db/pinia';
+ *
+ * export const useInvoices = defineNoydbStore<Invoice>('invoices', {
+ *   compartment: 'C101',
+ *   schema: InvoiceSchema, // optional
+ * });
+ * ```
+ */
+declare function defineNoydbStore<T>(id: string, options: NoydbStoreOptions<T>): pinia.StoreDefinition<string, Pick<{
+    items: Ref<T[], T[]>;
+    count: ComputedRef<number>;
+    $ready: Promise<void>;
+    byId: (id: string) => T | undefined;
+    add: (id: string, record: T) => Promise<void>;
+    update: (id: string, record: T) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    refresh: () => Promise<void>;
+    query: () => Query<T>;
+}, "items" | "$ready">, Pick<{
+    items: Ref<T[], T[]>;
+    count: ComputedRef<number>;
+    $ready: Promise<void>;
+    byId: (id: string) => T | undefined;
+    add: (id: string, record: T) => Promise<void>;
+    update: (id: string, record: T) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    refresh: () => Promise<void>;
+    query: () => Query<T>;
+}, "count">, Pick<{
+    items: Ref<T[], T[]>;
+    count: ComputedRef<number>;
+    $ready: Promise<void>;
+    byId: (id: string) => T | undefined;
+    add: (id: string, record: T) => Promise<void>;
+    update: (id: string, record: T) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    refresh: () => Promise<void>;
+    query: () => Query<T>;
+}, "byId" | "add" | "update" | "remove" | "refresh" | "query">>;
+
+/**
+ * Active NOYDB instance binding.
+ *
+ * `defineNoydbStore` resolves the `Noydb` instance from one of three places,
+ * in priority order:
+ *
+ *   1. The store options' explicit `noydb:` field (highest precedence — useful
+ *      for tests and multi-database apps).
+ *   2. A globally bound instance set via `setActiveNoydb()` — this is what the
+ *      Nuxt module's runtime plugin and playground apps use.
+ *   3. Throws a clear error if neither is set.
+ *
+ * Keeping the binding pluggable means tests can pass an instance directly
+ * without polluting global state.
+ */
+
+/** Bind a Noydb instance globally. Called by the Nuxt module / app plugin. */
+declare function setActiveNoydb(instance: Noydb | null): void;
+/** Returns the globally bound Noydb instance, or null if none. */
+declare function getActiveNoydb(): Noydb | null;
+/**
+ * Resolve the Noydb instance to use for a store. Throws if no instance is
+ * bound — the error message points the developer at the three options.
+ */
+declare function resolveNoydb(explicit?: Noydb | null): Noydb;
+
+/**
+ * `createNoydbPiniaPlugin` — augmentation path for existing Pinia stores.
+ *
+ * Lets a developer take any existing `defineStore()` call and opt into NOYDB
+ * persistence by adding a single `noydb:` option, without touching component
+ * code. The plugin watches the chosen state key(s), encrypts on change, syncs
+ * to a NOYDB collection, and rehydrates on store init.
+ *
+ * @example
+ * ```ts
+ * import { createPinia } from 'pinia';
+ * import { createNoydbPiniaPlugin } from '@noy-db/pinia';
+ * import { jsonFile } from '@noy-db/file';
+ *
+ * const pinia = createPinia();
+ * pinia.use(createNoydbPiniaPlugin({
+ *   adapter: jsonFile({ dir: './data' }),
+ *   user: 'owner-01',
+ *   secret: () => promptPassphrase(),
+ * }));
+ *
+ * // existing store — add one option, no component changes:
+ * export const useClients = defineStore('clients', {
+ *   state: () => ({ list: [] as Client[] }),
+ *   noydb: { compartment: 'C101', collection: 'clients', persist: 'list' },
+ * });
+ * ```
+ *
+ * Design notes
+ * ------------
+ * - Each augmented store persists a SINGLE document at id `__state__`
+ *   containing the picked keys. We don't try to map state arrays onto
+ *   per-element records — that's `defineNoydbStore`'s territory.
+ * - The Noydb instance is constructed lazily on first store-with-noydb
+ *   instantiation, then memoized for the lifetime of the Pinia app.
+ *   This means apps that don't actually use any noydb-augmented stores
+ *   pay zero crypto cost.
+ * - `secret` is a function so the passphrase can come from a prompt,
+ *   biometric unlock, or session token — never stored in config.
+ * - The plugin sets `store.$noydbReady` (a `Promise<void>`) and
+ *   `store.$noydbError` (an `Error | null`) on every augmented store
+ *   so components can await hydration and surface failures.
+ */
+
+/**
+ * Per-store NOYDB configuration. Attached to a Pinia store via the `noydb`
+ * option inside `defineStore({ ..., noydb: {...} })`.
+ *
+ * `persist` selects which top-level state keys to mirror into NOYDB.
+ * Pass a single key, an array of keys, or `'*'` to mirror the entire state.
+ */
+interface StoreNoydbOptions<S extends StateTree = StateTree> {
+    /** Compartment (tenant) name. */
+    compartment: string;
+    /** Collection name within the compartment. */
+    collection: string;
+    /**
+     * Which state keys to persist. Defaults to `'*'` (the entire state object).
+     * Pass a string or string[] to scope to specific keys.
+     */
+    persist?: keyof S | (keyof S)[] | '*';
+    /**
+     * Optional schema validator applied at the document level (the persisted
+     * subset of state, not individual records). Throws if validation fails on
+     * hydration — the store stays at its initial state and `$noydbError` is set.
+     */
+    schema?: {
+        parse: (input: unknown) => unknown;
+    };
+}
+/**
+ * Configuration for `createNoydbPiniaPlugin`. Mirrors `NoydbOptions` but
+ * makes `secret` a function so the passphrase can come from a prompt
+ * rather than being stored in config.
+ */
+interface NoydbPiniaPluginOptions {
+    /** The NOYDB adapter to use for persistence. */
+    adapter: NoydbAdapter;
+    /** User identifier (matches the keyring file). */
+    user: string;
+    /**
+     * Passphrase provider. Called once on first noydb-augmented store
+     * instantiation. Return a string or a Promise that resolves to one.
+     */
+    secret: () => string | Promise<string>;
+    /** Optional Noydb open-options forwarded to `createNoydb`. */
+    noydbOptions?: Partial<Omit<NoydbOptions, 'adapter' | 'user' | 'secret'>>;
+}
+/**
+ * Create a Pinia plugin that wires NOYDB persistence into any store
+ * declaring a `noydb:` option.
+ *
+ * Returns a `PiniaPlugin` directly usable with `pinia.use(...)`.
+ */
+declare function createNoydbPiniaPlugin(opts: NoydbPiniaPluginOptions): PiniaPlugin;
+declare module 'pinia' {
+    interface DefineStoreOptionsBase<S extends StateTree, Store> {
+        /**
+         * Opt this store into NOYDB persistence via the
+         * `createNoydbPiniaPlugin` augmentation plugin.
+         *
+         * The chosen state keys are encrypted and persisted to the configured
+         * compartment + collection on every mutation, and rehydrated on first
+         * store access.
+         */
+        noydb?: StoreNoydbOptions<S>;
+    }
+    interface PiniaCustomProperties {
+        /**
+         * Resolves once this store has finished its initial hydration from
+         * NOYDB. `undefined` for stores that don't declare a `noydb:` option.
+         */
+        $noydbReady?: Promise<void>;
+        /**
+         * Set when hydration or persistence fails. `null` while healthy.
+         * Plugins (and devtools) can poll this to surface storage errors.
+         */
+        $noydbError?: Error | null;
+        /**
+         * `true` if this store opted into NOYDB persistence via the `noydb:`
+         * option, `false` otherwise. Useful for debugging and devtools.
+         */
+        $noydbAugmented?: boolean;
+        /**
+         * Wait for all in-flight encrypted persistence puts to complete.
+         * Useful in tests for deterministic flushing, and in app code before
+         * unmounting components that just mutated the store.
+         */
+        $noydbFlush?: () => Promise<void>;
+    }
+}
+
+export { type NoydbPiniaPluginOptions, type NoydbStore, type NoydbStoreOptions, type StoreNoydbOptions, createNoydbPiniaPlugin, defineNoydbStore, getActiveNoydb, resolveNoydb, setActiveNoydb };

package/dist/index.js

@@ -0,0 +1,183 @@
+// src/defineNoydbStore.ts
+import { defineStore } from "pinia";
+import { computed, shallowRef } from "vue";
+
+// src/context.ts
+var activeInstance = null;
+function setActiveNoydb(instance) {
+  activeInstance = instance;
+}
+function getActiveNoydb() {
+  return activeInstance;
+}
+function resolveNoydb(explicit) {
+  if (explicit) return explicit;
+  if (activeInstance) return activeInstance;
+  throw new Error(
+    "@noy-db/pinia: no Noydb instance bound.\n  Option A \u2014 pass `noydb:` directly to defineNoydbStore({...})\n  Option B \u2014 call setActiveNoydb(instance) once at app startup\n  Option C \u2014 install the @noy-db/nuxt module (Nuxt 4+)"
+  );
+}
+
+// src/defineNoydbStore.ts
+function defineNoydbStore(id, options) {
+  const collectionName = options.collection ?? id;
+  const prefetch = options.prefetch ?? true;
+  return defineStore(id, () => {
+    const items = shallowRef([]);
+    const count = computed(() => items.value.length);
+    let cachedCompartment = null;
+    let cachedCollection = null;
+    async function getCollection() {
+      if (cachedCollection) return cachedCollection;
+      const noydb = resolveNoydb(options.noydb ?? null);
+      cachedCompartment = await noydb.openCompartment(options.compartment);
+      cachedCollection = cachedCompartment.collection(collectionName);
+      return cachedCollection;
+    }
+    async function refresh() {
+      const c = await getCollection();
+      const list = await c.list();
+      items.value = list;
+    }
+    function byId(id2) {
+      for (const item of items.value) {
+        if (item.id === id2) return item;
+      }
+      return void 0;
+    }
+    async function add(id2, record) {
+      const validated = options.schema ? options.schema.parse(record) : record;
+      const c = await getCollection();
+      await c.put(id2, validated);
+      items.value = await c.list();
+    }
+    async function update(id2, record) {
+      await add(id2, record);
+    }
+    async function remove(id2) {
+      const c = await getCollection();
+      await c.delete(id2);
+      items.value = await c.list();
+    }
+    function query() {
+      if (!cachedCollection) {
+        throw new Error(
+          "@noy-db/pinia: query() called before the store was ready. Await store.$ready first, or set prefetch: true (default)."
+        );
+      }
+      return cachedCollection.query();
+    }
+    const $ready = prefetch ? refresh() : Promise.resolve();
+    return {
+      items,
+      count,
+      $ready,
+      byId,
+      add,
+      update,
+      remove,
+      refresh,
+      query
+    };
+  });
+}
+
+// src/plugin.ts
+import { createNoydb } from "@noy-db/core";
+var STATE_DOC_ID = "__state__";
+function createNoydbPiniaPlugin(opts) {
+  let dbPromise = null;
+  function getDb() {
+    if (!dbPromise) {
+      dbPromise = (async () => {
+        const secret = await opts.secret();
+        return createNoydb({
+          adapter: opts.adapter,
+          user: opts.user,
+          secret,
+          ...opts.noydbOptions
+        });
+      })();
+    }
+    return dbPromise;
+  }
+  const compartmentCache = /* @__PURE__ */ new Map();
+  function getCompartment(name) {
+    let p = compartmentCache.get(name);
+    if (!p) {
+      p = getDb().then((db) => db.openCompartment(name));
+      compartmentCache.set(name, p);
+    }
+    return p;
+  }
+  return (context) => {
+    const noydbOption = context.options.noydb;
+    if (!noydbOption) {
+      context.store.$noydbAugmented = false;
+      return;
+    }
+    context.store.$noydbAugmented = true;
+    context.store.$noydbError = null;
+    const pending = /* @__PURE__ */ new Set();
+    const ready = (async () => {
+      try {
+        const compartment = await getCompartment(noydbOption.compartment);
+        const collection = compartment.collection(
+          noydbOption.collection
+        );
+        const persisted = await collection.get(STATE_DOC_ID);
+        if (persisted) {
+          const validated = noydbOption.schema ? noydbOption.schema.parse(persisted) : persisted;
+          const picked = pickKeys(validated, noydbOption.persist);
+          context.store.$patch(picked);
+        }
+        context.store.$subscribe(
+          (_mutation, state) => {
+            const subset = pickKeys(state, noydbOption.persist);
+            const p = collection.put(STATE_DOC_ID, subset).catch((err) => {
+              context.store.$noydbError = err instanceof Error ? err : new Error(String(err));
+            }).finally(() => {
+              pending.delete(p);
+            });
+            pending.add(p);
+          },
+          { detached: true }
+          // outlive the component that triggered the mutation
+        );
+      } catch (err) {
+        context.store.$noydbError = err instanceof Error ? err : new Error(String(err));
+      }
+    })();
+    context.store.$noydbReady = ready;
+    context.store.$noydbFlush = async () => {
+      await ready;
+      while (pending.size > 0) {
+        await Promise.all([...pending]);
+      }
+    };
+  };
+}
+function pickKeys(state, persist) {
+  if (persist === void 0 || persist === "*") {
+    return { ...state };
+  }
+  if (typeof persist === "string") {
+    return { [persist]: state[persist] };
+  }
+  if (Array.isArray(persist)) {
+    const out = {};
+    for (const key of persist) {
+      out[key] = state[key];
+    }
+    return out;
+  }
+  return { ...state };
+}
+export {
+  createNoydbPiniaPlugin,
+  defineNoydbStore,
+  getActiveNoydb,
+  resolveNoydb,
+  setActiveNoydb
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/defineNoydbStore.ts","../src/context.ts","../src/plugin.ts"],"sourcesContent":["/**\n * `defineNoydbStore` — drop-in `defineStore` that wires a Pinia store to a\n * NOYDB compartment + collection.\n *\n * Returned store exposes:\n *   - `items`        — reactive array of all records\n *   - `byId(id)`     — O(1) lookup\n *   - `count`        — reactive count getter\n *   - `add(id, rec)` — encrypt + persist + update reactive state\n *   - `update(id, rec)` — same as add (Collection.put is upsert)\n *   - `remove(id)`   — delete + update reactive state\n *   - `refresh()`    — re-hydrate from the adapter\n *   - `query()`      — chainable query DSL bound to the store\n *   - `$ready`       — Promise<void> resolved on first hydration\n *\n * Compatible with `storeToRefs`, Vue Devtools, SSR, and pinia plugins.\n */\n\nimport { defineStore } from 'pinia'\nimport { computed, shallowRef, type Ref, type ComputedRef } from 'vue'\nimport type { Noydb, Compartment, Collection, Query } from '@noy-db/core'\nimport { resolveNoydb } from './context.js'\n\n/**\n * Options accepted by `defineNoydbStore`.\n *\n * Generic `T` is the record shape — defaults to `unknown` if the caller\n * doesn't supply a type. Use `defineNoydbStore<Invoice>('invoices', {...})`\n * for full type safety.\n */\nexport interface NoydbStoreOptions<T> {\n  /** Compartment (tenant) name. */\n  compartment: string\n  /** Collection name within the compartment. Defaults to the store id. */\n  collection?: string\n  /**\n   * Optional explicit Noydb instance. If omitted, the store resolves the\n   * globally bound instance via `getActiveNoydb()`.\n   */\n  noydb?: Noydb | null\n  /**\n   * If true (default), hydration kicks off immediately when the store is\n   * first instantiated. If false, hydration is deferred until the first\n   * call to `refresh()` or any read accessor.\n   */\n  prefetch?: boolean\n  /**\n   * Optional schema validator. Any object exposing a `parse(input): T`\n   * method (Zod, Valibot, ArkType, etc.) is accepted.\n   */\n  schema?: { parse: (input: unknown) => T }\n}\n\n/**\n * The runtime shape of the store returned by `defineNoydbStore`.\n * Exposed as a public type so consumers can write `useStore: ReturnType<typeof useInvoices>`.\n */\nexport interface NoydbStore<T> {\n  items: Ref<T[]>\n  count: ComputedRef<number>\n  $ready: Promise<void>\n  byId(id: string): T | undefined\n  add(id: string, record: T): Promise<void>\n  update(id: string, record: T): Promise<void>\n  remove(id: string): Promise<void>\n  refresh(): Promise<void>\n  query(): Query<T>\n}\n\n/**\n * Define a Pinia store that's wired to a NOYDB collection.\n *\n * Generic T defaults to `unknown` — pass `<MyType>` for full type inference.\n *\n * @example\n * ```ts\n * import { defineNoydbStore } from '@noy-db/pinia';\n *\n * export const useInvoices = defineNoydbStore<Invoice>('invoices', {\n *   compartment: 'C101',\n *   schema: InvoiceSchema, // optional\n * });\n * ```\n */\nexport function defineNoydbStore<T>(\n  id: string,\n  options: NoydbStoreOptions<T>,\n) {\n  const collectionName = options.collection ?? id\n  const prefetch = options.prefetch ?? true\n\n  return defineStore(id, () => {\n    // Reactive state. shallowRef on items because the array reference is what\n    // changes — replacing it triggers reactivity without per-record proxying.\n    const items: Ref<T[]> = shallowRef<T[]>([])\n    const count = computed(() => items.value.length)\n\n    // Lazy collection handle — created on first hydrate.\n    let cachedCompartment: Compartment | null = null\n    let cachedCollection: Collection<T> | null = null\n\n    async function getCollection(): Promise<Collection<T>> {\n      if (cachedCollection) return cachedCollection\n      const noydb = resolveNoydb(options.noydb ?? null)\n      cachedCompartment = await noydb.openCompartment(options.compartment)\n      cachedCollection = cachedCompartment.collection<T>(collectionName)\n      return cachedCollection\n    }\n\n    async function refresh(): Promise<void> {\n      const c = await getCollection()\n      const list = await c.list()\n      items.value = list\n    }\n\n    function byId(id: string): T | undefined {\n      // Linear scan against the reactive cache. Index-aware lookups land in #13.\n      // Optimization opportunity: maintain a Map<string, T> alongside items.\n      for (const item of items.value) {\n        if ((item as { id?: string }).id === id) return item\n      }\n      return undefined\n    }\n\n    async function add(id: string, record: T): Promise<void> {\n      const validated = options.schema ? options.schema.parse(record) : record\n      const c = await getCollection()\n      await c.put(id, validated)\n      // Re-list to pick up the new record. Cheaper alternative would be to\n      // splice into items.value directly, but list() ensures consistency\n      // with the underlying cache.\n      items.value = await c.list()\n    }\n\n    async function update(id: string, record: T): Promise<void> {\n      // Collection.put is upsert; this is just a more readable alias.\n      await add(id, record)\n    }\n\n    async function remove(id: string): Promise<void> {\n      const c = await getCollection()\n      await c.delete(id)\n      items.value = await c.list()\n    }\n\n    function query(): Query<T> {\n      // Synchronous query() requires the collection to be hydrated.\n      // The lazy refresh() in $ready handles that — but if the user calls\n      // query() before $ready resolves, the collection still works because\n      // Collection.query() reads from its own internal cache (which Noydb\n      // hydrates lazily as well).\n      if (!cachedCollection) {\n        throw new Error(\n          '@noy-db/pinia: query() called before the store was ready. ' +\n          'Await store.$ready first, or set prefetch: true (default).',\n        )\n      }\n      return cachedCollection.query()\n    }\n\n    // Kick off hydration. The promise is exposed as $ready so components\n    // can `await store.$ready` before rendering data-dependent UI.\n    const $ready: Promise<void> = prefetch\n      ? refresh()\n      : Promise.resolve()\n\n    return {\n      items,\n      count,\n      $ready,\n      byId,\n      add,\n      update,\n      remove,\n      refresh,\n      query,\n    }\n  })\n}\n","/**\n * Active NOYDB instance binding.\n *\n * `defineNoydbStore` resolves the `Noydb` instance from one of three places,\n * in priority order:\n *\n *   1. The store options' explicit `noydb:` field (highest precedence — useful\n *      for tests and multi-database apps).\n *   2. A globally bound instance set via `setActiveNoydb()` — this is what the\n *      Nuxt module's runtime plugin and playground apps use.\n *   3. Throws a clear error if neither is set.\n *\n * Keeping the binding pluggable means tests can pass an instance directly\n * without polluting global state.\n */\n\nimport type { Noydb } from '@noy-db/core'\n\nlet activeInstance: Noydb | null = null\n\n/** Bind a Noydb instance globally. Called by the Nuxt module / app plugin. */\nexport function setActiveNoydb(instance: Noydb | null): void {\n  activeInstance = instance\n}\n\n/** Returns the globally bound Noydb instance, or null if none. */\nexport function getActiveNoydb(): Noydb | null {\n  return activeInstance\n}\n\n/**\n * Resolve the Noydb instance to use for a store. Throws if no instance is\n * bound — the error message points the developer at the three options.\n */\nexport function resolveNoydb(explicit?: Noydb | null): Noydb {\n  if (explicit) return explicit\n  if (activeInstance) return activeInstance\n  throw new Error(\n    '@noy-db/pinia: no Noydb instance bound.\\n' +\n    '  Option A — pass `noydb:` directly to defineNoydbStore({...})\\n' +\n    '  Option B — call setActiveNoydb(instance) once at app startup\\n' +\n    '  Option C — install the @noy-db/nuxt module (Nuxt 4+)',\n  )\n}\n","/**\n * `createNoydbPiniaPlugin` — augmentation path for existing Pinia stores.\n *\n * Lets a developer take any existing `defineStore()` call and opt into NOYDB\n * persistence by adding a single `noydb:` option, without touching component\n * code. The plugin watches the chosen state key(s), encrypts on change, syncs\n * to a NOYDB collection, and rehydrates on store init.\n *\n * @example\n * ```ts\n * import { createPinia } from 'pinia';\n * import { createNoydbPiniaPlugin } from '@noy-db/pinia';\n * import { jsonFile } from '@noy-db/file';\n *\n * const pinia = createPinia();\n * pinia.use(createNoydbPiniaPlugin({\n *   adapter: jsonFile({ dir: './data' }),\n *   user: 'owner-01',\n *   secret: () => promptPassphrase(),\n * }));\n *\n * // existing store — add one option, no component changes:\n * export const useClients = defineStore('clients', {\n *   state: () => ({ list: [] as Client[] }),\n *   noydb: { compartment: 'C101', collection: 'clients', persist: 'list' },\n * });\n * ```\n *\n * Design notes\n * ------------\n * - Each augmented store persists a SINGLE document at id `__state__`\n *   containing the picked keys. We don't try to map state arrays onto\n *   per-element records — that's `defineNoydbStore`'s territory.\n * - The Noydb instance is constructed lazily on first store-with-noydb\n *   instantiation, then memoized for the lifetime of the Pinia app.\n *   This means apps that don't actually use any noydb-augmented stores\n *   pay zero crypto cost.\n * - `secret` is a function so the passphrase can come from a prompt,\n *   biometric unlock, or session token — never stored in config.\n * - The plugin sets `store.$noydbReady` (a `Promise<void>`) and\n *   `store.$noydbError` (an `Error | null`) on every augmented store\n *   so components can await hydration and surface failures.\n */\n\nimport type { PiniaPluginContext, PiniaPlugin, StateTree } from 'pinia'\nimport { createNoydb, type Noydb, type NoydbOptions, type NoydbAdapter, type Compartment, type Collection } from '@noy-db/core'\n\n/**\n * Per-store NOYDB configuration. Attached to a Pinia store via the `noydb`\n * option inside `defineStore({ ..., noydb: {...} })`.\n *\n * `persist` selects which top-level state keys to mirror into NOYDB.\n * Pass a single key, an array of keys, or `'*'` to mirror the entire state.\n */\nexport interface StoreNoydbOptions<S extends StateTree = StateTree> {\n  /** Compartment (tenant) name. */\n  compartment: string\n  /** Collection name within the compartment. */\n  collection: string\n  /**\n   * Which state keys to persist. Defaults to `'*'` (the entire state object).\n   * Pass a string or string[] to scope to specific keys.\n   */\n  persist?: keyof S | (keyof S)[] | '*'\n  /**\n   * Optional schema validator applied at the document level (the persisted\n   * subset of state, not individual records). Throws if validation fails on\n   * hydration — the store stays at its initial state and `$noydbError` is set.\n   */\n  schema?: { parse: (input: unknown) => unknown }\n}\n\n/**\n * Configuration for `createNoydbPiniaPlugin`. Mirrors `NoydbOptions` but\n * makes `secret` a function so the passphrase can come from a prompt\n * rather than being stored in config.\n */\nexport interface NoydbPiniaPluginOptions {\n  /** The NOYDB adapter to use for persistence. */\n  adapter: NoydbAdapter\n  /** User identifier (matches the keyring file). */\n  user: string\n  /**\n   * Passphrase provider. Called once on first noydb-augmented store\n   * instantiation. Return a string or a Promise that resolves to one.\n   */\n  secret: () => string | Promise<string>\n  /** Optional Noydb open-options forwarded to `createNoydb`. */\n  noydbOptions?: Partial<Omit<NoydbOptions, 'adapter' | 'user' | 'secret'>>\n}\n\n// The fixed document id under which a store's persisted state lives. Using a\n// reserved prefix so it can't collide with any user-chosen record id.\nconst STATE_DOC_ID = '__state__'\n\n/**\n * Create a Pinia plugin that wires NOYDB persistence into any store\n * declaring a `noydb:` option.\n *\n * Returns a `PiniaPlugin` directly usable with `pinia.use(...)`.\n */\nexport function createNoydbPiniaPlugin(opts: NoydbPiniaPluginOptions): PiniaPlugin {\n  // Single Noydb instance shared across all augmented stores in this Pinia\n  // app. Created lazily on first use so apps that never instantiate a\n  // noydb-augmented store pay zero crypto cost.\n  let dbPromise: Promise<Noydb> | null = null\n  function getDb(): Promise<Noydb> {\n    if (!dbPromise) {\n      dbPromise = (async (): Promise<Noydb> => {\n        const secret = await opts.secret()\n        return createNoydb({\n          adapter: opts.adapter,\n          user: opts.user,\n          secret,\n          ...opts.noydbOptions,\n        })\n      })()\n    }\n    return dbPromise\n  }\n\n  // Compartment cache so opening a compartment is a one-time cost per app.\n  const compartmentCache = new Map<string, Promise<Compartment>>()\n  function getCompartment(name: string): Promise<Compartment> {\n    let p = compartmentCache.get(name)\n    if (!p) {\n      p = getDb().then((db) => db.openCompartment(name))\n      compartmentCache.set(name, p)\n    }\n    return p\n  }\n\n  return (context: PiniaPluginContext) => {\n    // Pinia stores can declare arbitrary options on `defineStore`, but the\n    // plugin context only exposes them via `context.options`. Pull our\n    // `noydb` option out and bail early if it's not present — that's\n    // the \"store is untouched\" path for non-augmented stores.\n    const noydbOption = (context.options as { noydb?: StoreNoydbOptions }).noydb\n    if (!noydbOption) {\n      // Mark the store as opted-out so devtools / consumers can detect it.\n      context.store.$noydbAugmented = false\n      return\n    }\n\n    context.store.$noydbAugmented = true\n    context.store.$noydbError = null as Error | null\n\n    // Track in-flight persistence promises so tests (and consumers) can\n    // await deterministic flushes via `$noydbFlush()`. Plain Set-of-Promises\n    // — entries auto-remove on settle.\n    const pending = new Set<Promise<void>>()\n\n    // Hydrate-then-subscribe. Both happen inside an async closure so the\n    // store can be awaited via `$noydbReady`.\n    const ready = (async (): Promise<void> => {\n      try {\n        const compartment = await getCompartment(noydbOption.compartment)\n        const collection: Collection<StateTree> = compartment.collection<StateTree>(\n          noydbOption.collection,\n        )\n\n        // 1. Hydration: read the persisted document (if any) and apply\n        //    the picked keys onto the store's current state. We use\n        //    `$patch` so reactivity fires correctly.\n        const persisted = await collection.get(STATE_DOC_ID)\n        if (persisted) {\n          const validated = noydbOption.schema\n            ? (noydbOption.schema.parse(persisted) as StateTree)\n            : persisted\n          const picked = pickKeys(validated, noydbOption.persist)\n          context.store.$patch(picked)\n        }\n\n        // 2. Subscribe: every state mutation triggers an encrypted write\n        //    of the picked subset back to NOYDB. The subscription captures\n        //    `collection` so it doesn't re-resolve on every event.\n        context.store.$subscribe(\n          (_mutation, state) => {\n            const subset = pickKeys(state, noydbOption.persist)\n            const p = collection.put(STATE_DOC_ID, subset)\n              .catch((err: unknown) => {\n                context.store.$noydbError = err instanceof Error ? err : new Error(String(err))\n              })\n              .finally(() => {\n                pending.delete(p)\n              })\n            pending.add(p)\n          },\n          { detached: true }, // outlive the component that triggered the mutation\n        )\n      } catch (err) {\n        context.store.$noydbError = err instanceof Error ? err : new Error(String(err))\n      }\n    })()\n\n    context.store.$noydbReady = ready\n    /**\n     * Wait for all in-flight persistence puts to settle. Use this in tests\n     * to deterministically observe the encrypted state on the adapter, and\n     * in app code before unmounting components that mutated the store.\n     */\n    context.store.$noydbFlush = async (): Promise<void> => {\n      await ready\n      // Snapshot the current pending set; new puts added during await\n      // are picked up by the next $noydbFlush() call.\n      while (pending.size > 0) {\n        await Promise.all([...pending])\n      }\n    }\n  }\n}\n\n/**\n * Pick the configured subset of keys from a state object.\n *\n * Behaviors:\n *   - `undefined` or `'*'` → returns the entire state shallow-copied\n *   - single key string → returns `{ [key]: state[key] }`\n *   - key array → returns `{ [k1]: state[k1], [k2]: state[k2], ... }`\n *\n * The result is always a fresh object so callers can mutate it without\n * touching the store's reactive state.\n */\nfunction pickKeys(state: StateTree, persist: StoreNoydbOptions['persist']): StateTree {\n  if (persist === undefined || persist === '*') {\n    return { ...state }\n  }\n  if (typeof persist === 'string') {\n    return { [persist]: state[persist] } as StateTree\n  }\n  if (Array.isArray(persist)) {\n    const out: StateTree = {}\n    for (const key of persist) {\n      out[key as string] = state[key as string]\n    }\n    return out\n  }\n  // Should be unreachable thanks to the type, but defensive default.\n  return { ...state }\n}\n\n// ─── Pinia module augmentation ─────────────────────────────────────\n//\n// Pinia exposes `DefineStoreOptionsBase` as the place where third-party\n// plugins are expected to attach their custom option types. Augmenting it\n// here means `defineStore('x', { ..., noydb: {...} })` autocompletes inside\n// the IDE and type-checks correctly without forcing users to import\n// anything from `@noy-db/pinia`.\n//\n// We also augment `PiniaCustomProperties` so the runtime fields we add to\n// every store (`$noydbReady`, `$noydbError`, `$noydbAugmented`) are typed.\n\ndeclare module 'pinia' {\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  export interface DefineStoreOptionsBase<S extends StateTree, Store> {\n    /**\n     * Opt this store into NOYDB persistence via the\n     * `createNoydbPiniaPlugin` augmentation plugin.\n     *\n     * The chosen state keys are encrypted and persisted to the configured\n     * compartment + collection on every mutation, and rehydrated on first\n     * store access.\n     */\n    noydb?: StoreNoydbOptions<S>\n  }\n\n  export interface PiniaCustomProperties {\n    /**\n     * Resolves once this store has finished its initial hydration from\n     * NOYDB. `undefined` for stores that don't declare a `noydb:` option.\n     */\n    $noydbReady?: Promise<void>\n    /**\n     * Set when hydration or persistence fails. `null` while healthy.\n     * Plugins (and devtools) can poll this to surface storage errors.\n     */\n    $noydbError?: Error | null\n    /**\n     * `true` if this store opted into NOYDB persistence via the `noydb:`\n     * option, `false` otherwise. Useful for debugging and devtools.\n     */\n    $noydbAugmented?: boolean\n    /**\n     * Wait for all in-flight encrypted persistence puts to complete.\n     * Useful in tests for deterministic flushing, and in app code before\n     * unmounting components that just mutated the store.\n     */\n    $noydbFlush?: () => Promise<void>\n  }\n}\n"],"mappings":"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","names":["id"]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@noy-db/pinia",
+  "version": "0.3.0",
+  "description": "Pinia integration for noy-db — defineNoydbStore() and the augmentation plugin for existing stores",
+  "license": "MIT",
+  "author": "vLannaAi <vicio@lanna.ai>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/pinia#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/pinia"
+  },
+  "bugs": {
+    "url": "https://github.com/vLannaAi/noy-db/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "pinia": "^2.1.0 || ^3.0.0",
+    "vue": "^3.4.0",
+    "@noy-db/core": "0.3.0"
+  },
+  "devDependencies": {
+    "@vue/test-utils": "^2.4.6",
+    "happy-dom": "^15.11.7",
+    "pinia": "^3.0.1",
+    "vue": "^3.5.32",
+    "@noy-db/core": "0.3.0"
+  },
+  "keywords": [
+    "noy-db",
+    "pinia",
+    "vue",
+    "vue3",
+    "nuxt",
+    "store",
+    "encryption",
+    "zero-knowledge",
+    "offline-first"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}