@noy-db/in-pinia 0.1.0-pre.3

package/dist/index.d.ts

@@ -0,0 +1,411 @@
+import * as pinia from 'pinia';
+import { StateTree, PiniaPlugin } from 'pinia';
+import { ShallowRef, Ref, ComputedRef } from 'vue';
+import { Query, Noydb, StandardSchemaV1, NoydbStore as NoydbStore$1, NoydbOptions, Role, Vault } from '@noy-db/hub';
+
+/**
+ * Reactive handle returned by `store.liveQuery(fn)`. Mirrors a hub
+ * `LiveQuery<R>` into Vue refs; `items` updates on every left- or
+ * joined-right-side mutation, `error` carries re-run errors as state
+ * (a `DanglingReferenceError` in strict join mode is the common case),
+ * `stop()` tears down upstream subscriptions. Auto-disposed on scope
+ * teardown when called inside a Vue setup / Pinia store body.
+ */
+interface NoydbLiveQuery<R> {
+    items: ShallowRef<readonly R[]>;
+    error: Ref<Error | null>;
+    stop(): void;
+}
+/**
+ * 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> {
+    /** Vault (tenant) name. */
+    vault: string;
+    /** Collection name within the vault. 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.
+     *
+     * Accepts any [Standard Schema v1](https://standardschema.dev) validator
+     * — Zod, Valibot, ArkType, Effect Schema, etc. The same validator is
+     * installed on the underlying `Collection`, so every `put()` is
+     * validated **before encryption** and every read is validated **after
+     * decryption**. The store's `add`/`update` methods inherit this
+     * validation automatically; no duplicate `.parse()` call is needed.
+     *
+     * Schema-less stores behave exactly as before (no validation, no
+     * perf cost, backwards compatible with usage).
+     */
+    schema?: StandardSchemaV1<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>;
+    liveQuery<R = T>(build: (q: Query<T>) => Query<R>): NoydbLiveQuery<R>;
+}
+/**
+ * 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/in-pinia';
+ *
+ * export const useInvoices = defineNoydbStore<Invoice>('invoices', {
+ *   vault: '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>;
+    liveQuery: <R = T>(build: (q: Query<T>) => Query<R>) => NoydbLiveQuery<R>;
+}, "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>;
+    liveQuery: <R = T>(build: (q: Query<T>) => Query<R>) => NoydbLiveQuery<R>;
+}, "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>;
+    liveQuery: <R = T>(build: (q: Query<T>) => Query<R>) => NoydbLiveQuery<R>;
+}, "byId" | "add" | "update" | "remove" | "refresh" | "query" | "liveQuery">>;
+
+/**
+ * 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/in-pinia';
+ * import { jsonFile } from '@noy-db/to-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: { vault: '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> {
+    /** Vault (tenant) name. */
+    vault: string;
+    /** Collection name within the vault. */
+    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 store to use for persistence. */
+    adapter: NoydbStore$1;
+    /** 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, 'store' | '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
+         * vault + 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>;
+    }
+}
+
+/**
+ * `useCapabilityGrant` — Vue/Pinia composable for time-boxed
+ * capability approval flows.
+ *
+ * The composable orchestrates a request → approve → expire / release
+ * lifecycle for a session-scoped capability. It manages UI state,
+ * persists the request to a reserved `_capability_requests` collection
+ * so a separate approver session can see it, and tracks TTL with
+ * auto-revert.
+ *
+ * **It does NOT itself flip capability bits.** Capability mechanisms
+ * vary across adopters: tier-based deployments wire `onGrant` to
+ * `vault.elevate(tier, opts)`; keyring-based deployments wire it to
+ * `db.grant(...)`; custom deployments do their own thing. Keeping the
+ * actual flip behind a callback avoids introducing a parallel
+ * "capability elevation" primitive in hub when the existing
+ * `vault.elevate()` already covers the time-boxed-grant pattern.
+ *
+ * ## State machine
+ *
+ *   idle  ─── .request() ───────►  requested
+ *   requested  ─── .approve() ──►  granted
+ *   granted    ─── TTL expires ─►  idle
+ *   granted    ─── .release() ──►  idle
+ *
+ * @module
+ */
+
+/** Reserved internal collection that holds capability-grant lifecycle records. */
+declare const CAPABILITY_REQUESTS_COLLECTION = "_capability_requests";
+type CapabilityGrantState = 'idle' | 'requested' | 'granted' | 'expired';
+/**
+ * On-disk shape of a capability-grant lifecycle record. Persisted in
+ * the reserved {@link CAPABILITY_REQUESTS_COLLECTION}. Encrypted with
+ * that collection's DEK at the storage layer; the in-memory shape
+ * here is plaintext.
+ *
+ * The audit trail invariant: this record carries metadata only —
+ * capability name, roles, ttl, reason. Never plaintext payload.
+ */
+interface CapabilityGrantRecord {
+    readonly id: string;
+    readonly capability: string;
+    readonly requestedBy: string;
+    readonly approverRole: Role;
+    readonly reason: string;
+    readonly ttlMs: number;
+    readonly status: 'requested' | 'granted' | 'released' | 'expired';
+    readonly requestedAt: string;
+    readonly approvedBy?: string;
+    readonly approvedAt?: string;
+    readonly expiresAt?: string;
+}
+interface UseCapabilityGrantOptions {
+    /** TTL in milliseconds for the granted window. */
+    readonly ttlMs: number;
+    /** Role required to call `.approve()`. Mismatch throws on `.approve()`. */
+    readonly approver: Role;
+    /** Audit-ledger string. Stamped on the request record; no plaintext payload. */
+    readonly reason: string;
+    /**
+     * Optional explicit vault. Either a `Vault` instance or its name.
+     * When omitted, resolves the active Noydb instance via
+     * `setActiveNoydb()` and opens the first vault the caller has
+     * already loaded.
+     */
+    readonly vault: Vault | string;
+    /**
+     * Called on the approver's session when `.approve()` succeeds. Wire
+     * this to whatever capability flip your codebase uses —
+     * `vault.elevate(tier, opts)` for tier-based deployments,
+     * `db.grant(...)` for keyring-based, custom for custom.
+     *
+     * The composable does NOT enforce that the capability was actually
+     * granted — it just tracks the lifecycle. The post-expiry "gated
+     * call throws" contract comes from the underlying mechanism the
+     * callback wires up (e.g., `ElevationExpiredError` from
+     * `vault.elevate`'s lazy TTL check).
+     */
+    readonly onGrant?: (ctx: {
+        record: CapabilityGrantRecord;
+        vault: Vault;
+    }) => void | Promise<void>;
+    /**
+     * Called when the grant ends (TTL expiry OR voluntary release).
+     * Mirror of `onGrant`. Idempotent — may be called twice if release
+     * and expiry race; callers should no-op on the second invocation.
+     */
+    readonly onRelease?: (ctx: {
+        record: CapabilityGrantRecord;
+        vault: Vault;
+        cause: 'released' | 'expired';
+    }) => void | Promise<void>;
+}
+interface UseCapabilityGrantReturn {
+    readonly state: Ref<CapabilityGrantState>;
+    /** Milliseconds remaining on the granted window; 0 outside `granted`. */
+    readonly timeRemaining: ComputedRef<number>;
+    /** Most recent error from request/approve/release (resets on next op). */
+    readonly error: Ref<Error | null>;
+    /** Issue a request. State must be `idle`. */
+    request(): Promise<void>;
+    /** Approve a pending request. State must be `requested`. */
+    approve(): Promise<void>;
+    /** Voluntarily revoke an active grant. State must be `granted`. */
+    release(): Promise<void>;
+}
+/**
+ * Build a reactive capability-grant lifecycle handle.
+ *
+ * @example Tier-based capability flip
+ * ```ts
+ * let elevated: ElevatedHandle | null = null
+ * const grant = useCapabilityGrant('canExportPlaintext', {
+ *   vault: 'V1',
+ *   ttlMs: 15 * 60_000,
+ *   approver: 'admin',
+ *   reason: 'bulk export',
+ *   onGrant: async ({ vault, record }) => {
+ *     elevated = await vault.elevate(2, {
+ *       ttlMs: record.ttlMs,
+ *       reason: record.reason,
+ *     })
+ *   },
+ *   onRelease: async () => { await elevated?.release(); elevated = null },
+ * })
+ * ```
+ */
+declare function useCapabilityGrant(capability: string, options: UseCapabilityGrantOptions): UseCapabilityGrantReturn;
+
+export { CAPABILITY_REQUESTS_COLLECTION, type CapabilityGrantRecord, type CapabilityGrantState, type NoydbLiveQuery, type NoydbPiniaPluginOptions, type NoydbStore, type NoydbStoreOptions, type StoreNoydbOptions, type UseCapabilityGrantOptions, type UseCapabilityGrantReturn, createNoydbPiniaPlugin, defineNoydbStore, getActiveNoydb, resolveNoydb, setActiveNoydb, useCapabilityGrant };