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

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,33 @@
+# @noy-db/in-react
+
+[![npm](https://img.shields.io/npm/v/%40noy-db/in-react.svg)](https://www.npmjs.com/package/@noy-db/in-react)
+
+> React hooks for noy-db
+
+Part of [**`@noy-db/hub`**](https://www.npmjs.com/package/@noy-db/hub) — the zero-knowledge, offline-first, encrypted document store.
+
+## Install
+
+```bash
+pnpm add @noy-db/hub @noy-db/in-react
+```
+
+## What it is
+
+React hooks for noy-db — useNoydb, useVault, useCollection, useQuery, useSync. Uses useSyncExternalStore for reactive subscriptions. Zero deps beyond React.
+
+## Status
+
+**Pre-release** (`0.1.0-pre.1`). API may change before `1.0`.
+
+## Documentation
+
+See the [main repository](https://github.com/vLannaAi/noy-db#readme) for setup, examples, and the full subsystem catalog.
+
+- Source — [`packages/in-react`](https://github.com/vLannaAi/noy-db/tree/main/packages/in-react)
+- Issues — [github.com/vLannaAi/noy-db/issues](https://github.com/vLannaAi/noy-db/issues)
+- Spec — [`SPEC.md`](https://github.com/vLannaAi/noy-db/blob/main/SPEC.md)
+
+## License
+
+[MIT](./LICENSE) © vLannaAi

package/dist/index.cjs

@@ -0,0 +1,156 @@
+"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, {
+  NoydbProvider: () => NoydbProvider,
+  useCollection: () => useCollection,
+  useNoydb: () => useNoydb,
+  useQuery: () => useQuery,
+  useSync: () => useSync,
+  useVault: () => useVault
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+var NoydbContext = (0, import_react.createContext)(null);
+function NoydbProvider(props) {
+  return (0, import_react.createElement)(NoydbContext.Provider, { value: props.db }, props.children);
+}
+function useNoydb() {
+  const db = (0, import_react.useContext)(NoydbContext);
+  if (!db) {
+    throw new Error(
+      "[@noy-db/in-react] useNoydb(): no NoydbProvider found in the React tree. Wrap your app with <NoydbProvider db={db}>."
+    );
+  }
+  return db;
+}
+function useVault(name, options) {
+  const db = useNoydb();
+  const [state, setState] = (0, import_react.useState)({ vault: null, loading: true, error: null });
+  (0, import_react.useEffect)(() => {
+    let cancelled = false;
+    setState({ vault: null, loading: true, error: null });
+    db.openVault(name, options).then((v) => {
+      if (!cancelled) setState({ vault: v, loading: false, error: null });
+    }).catch((err) => {
+      if (!cancelled) setState({ vault: null, loading: false, error: err });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [db, name, options?.locale]);
+  return state;
+}
+function useCollection(vault, collectionName) {
+  const [state, setState] = (0, import_react.useState)(() => ({
+    data: [],
+    loading: true,
+    error: null
+  }));
+  const coll = (0, import_react.useMemo)(
+    () => vault ? vault.collection(collectionName) : null,
+    [vault, collectionName]
+  );
+  (0, import_react.useEffect)(() => {
+    if (!coll) {
+      setState({ data: [], loading: true, error: null });
+      return;
+    }
+    let cancelled = false;
+    const refresh = async () => {
+      try {
+        const records = await coll.list();
+        if (!cancelled) setState({ data: records, loading: false, error: null });
+      } catch (err) {
+        if (!cancelled) setState({ data: [], loading: false, error: err });
+      }
+    };
+    void refresh();
+    const unsubscribe = coll.subscribe(() => {
+      void refresh();
+    });
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [coll]);
+  return state;
+}
+function useQuery(vault, collectionName, builder, deps = []) {
+  const [state, setState] = (0, import_react.useState)(() => ({
+    data: null,
+    loading: true,
+    error: null
+  }));
+  const coll = (0, import_react.useMemo)(
+    () => vault ? vault.collection(collectionName) : null,
+    [vault, collectionName]
+  );
+  (0, import_react.useEffect)(() => {
+    if (!coll) return;
+    let cancelled = false;
+    const run = async () => {
+      try {
+        const result = await Promise.resolve(builder(coll.query()));
+        if (!cancelled) setState({ data: result, loading: false, error: null });
+      } catch (err) {
+        if (!cancelled) setState({ data: null, loading: false, error: err });
+      }
+    };
+    void run();
+    const unsubscribe = coll.subscribe(() => {
+      void run();
+    });
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [coll, ...deps]);
+  return state;
+}
+function useSync(db) {
+  const ctx = (0, import_react.useContext)(NoydbContext);
+  const instance = db ?? ctx;
+  if (!instance) {
+    throw new Error("[@noy-db/in-react] useSync(): no Noydb instance (pass explicitly or wrap in <NoydbProvider>).");
+  }
+  const [state, setState] = (0, import_react.useState)({ lastEvent: null, error: null });
+  (0, import_react.useEffect)(() => {
+    const handler = (event) => {
+      setState({ lastEvent: event, error: null });
+    };
+    instance.on("change", handler);
+    return () => {
+      instance.off("change", handler);
+    };
+  }, [instance]);
+  return state;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NoydbProvider,
+  useCollection,
+  useNoydb,
+  useQuery,
+  useSync,
+  useVault
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/in-react** — React hooks for noy-db.\n *\n * Five hooks that live on top of React 18+'s `useSyncExternalStore`:\n *\n *   - {@link useNoydb}       — read the `Noydb` instance from context\n *   - {@link useVault}       — open a vault, subscribed for lifecycle\n *   - {@link useCollection}  — reactive record list\n *   - {@link useQuery}       — reactive result of a query builder\n *   - {@link useSync}        — reactive sync state\n *\n * Change events drive re-renders via `useSyncExternalStore`, which\n * concurrent-mode-safely bridges an external subscription into React's\n * scheduling. No extra state library needed.\n *\n * @packageDocumentation\n */\n\nimport {\n  createContext,\n  createElement,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n  type ReactNode,\n} from 'react'\nimport type { Noydb, Vault, ChangeEvent, Query } from '@noy-db/hub'\n\n// ─── Context ────────────────────────────────────────────────────────────\n\nconst NoydbContext = createContext<Noydb | null>(null)\n\nexport interface NoydbProviderProps {\n  readonly db: Noydb\n  readonly children: ReactNode\n}\n\n/** Provides a `Noydb` instance to every component under this tree. */\nexport function NoydbProvider(props: NoydbProviderProps): ReactNode {\n  return createElement(NoydbContext.Provider, { value: props.db }, props.children)\n}\n\n/** Access the Noydb instance supplied by the nearest `<NoydbProvider>`. */\nexport function useNoydb(): Noydb {\n  const db = useContext(NoydbContext)\n  if (!db) {\n    throw new Error(\n      '[@noy-db/in-react] useNoydb(): no NoydbProvider found in the React tree. ' +\n      'Wrap your app with <NoydbProvider db={db}>.',\n    )\n  }\n  return db\n}\n\n// ─── useVault ───────────────────────────────────────────────────────────\n\nexport interface UseVaultState {\n  readonly vault: Vault | null\n  readonly loading: boolean\n  readonly error: Error | null\n}\n\n/**\n * Open a vault by name and track its lifecycle. The vault is opened\n * on mount (re-opened when `name` changes). Optional `locale` is\n * forwarded to the hub; secret / biometric unlock happens out-of-band\n * (create the Noydb instance with `secret`, or use `@noy-db/on-*`).\n */\nexport function useVault(name: string, options?: { locale?: string }): UseVaultState {\n  const db = useNoydb()\n  const [state, setState] = useState<UseVaultState>({ vault: null, loading: true, error: null })\n\n  useEffect(() => {\n    let cancelled = false\n    setState({ vault: null, loading: true, error: null })\n    db.openVault(name, options)\n      .then((v) => {\n        if (!cancelled) setState({ vault: v, loading: false, error: null })\n      })\n      .catch((err: Error) => {\n        if (!cancelled) setState({ vault: null, loading: false, error: err })\n      })\n    return () => {\n      cancelled = true\n    }\n  }, [db, name, options?.locale])\n\n  return state\n}\n\n// ─── useCollection ──────────────────────────────────────────────────────\n\n/**\n * Reactive list of every record in a collection. Auto-refreshes on\n * any change event from the hub — put, delete, or sync.\n */\nexport function useCollection<T>(\n  vault: Vault | null,\n  collectionName: string,\n): { data: T[]; loading: boolean; error: Error | null } {\n  const [state, setState] = useState<{ data: T[]; loading: boolean; error: Error | null }>(() => ({\n    data: [], loading: true, error: null,\n  }))\n\n  const coll = useMemo(\n    () => (vault ? vault.collection<T>(collectionName) : null),\n    [vault, collectionName],\n  )\n\n  useEffect(() => {\n    if (!coll) {\n      setState({ data: [], loading: true, error: null })\n      return\n    }\n    let cancelled = false\n    const refresh = async (): Promise<void> => {\n      try {\n        const records = await coll.list()\n        if (!cancelled) setState({ data: records, loading: false, error: null })\n      } catch (err) {\n        if (!cancelled) setState({ data: [], loading: false, error: err as Error })\n      }\n    }\n    void refresh()\n    const unsubscribe = coll.subscribe(() => { void refresh() })\n    return () => {\n      cancelled = true\n      unsubscribe()\n    }\n  }, [coll])\n\n  return state\n}\n\n// ─── useQuery ───────────────────────────────────────────────────────────\n\n/**\n * Reactive result of a query builder. The builder is re-executed\n * whenever the collection's change stream fires.\n */\nexport function useQuery<T, R>(\n  vault: Vault | null,\n  collectionName: string,\n  builder: (q: Query<T>) => Promise<R> | R,\n  deps: readonly unknown[] = [],\n): { data: R | null; loading: boolean; error: Error | null } {\n  const [state, setState] = useState<{ data: R | null; loading: boolean; error: Error | null }>(() => ({\n    data: null, loading: true, error: null,\n  }))\n\n  const coll = useMemo(\n    () => (vault ? vault.collection<T>(collectionName) : null),\n    [vault, collectionName],\n  )\n\n  useEffect(() => {\n    if (!coll) return\n    let cancelled = false\n    const run = async (): Promise<void> => {\n      try {\n        const result = await Promise.resolve(builder(coll.query() as unknown as Query<T>))\n        if (!cancelled) setState({ data: result, loading: false, error: null })\n      } catch (err) {\n        if (!cancelled) setState({ data: null, loading: false, error: err as Error })\n      }\n    }\n    void run()\n    const unsubscribe = coll.subscribe(() => { void run() })\n    return () => {\n      cancelled = true\n      unsubscribe()\n    }\n  }, [coll, ...deps])\n\n  return state\n}\n\n// ─── useSync ────────────────────────────────────────────────────────────\n\nexport interface UseSyncState {\n  readonly lastEvent: ChangeEvent | null\n  readonly error: Error | null\n}\n\n/**\n * Subscribe to the hub's cross-collection change stream. Useful for\n * top-level status indicators (\"unsynced changes\", last-update time).\n */\nexport function useSync(db?: Noydb): UseSyncState {\n  const ctx = useContext(NoydbContext)\n  const instance = db ?? ctx\n  if (!instance) {\n    throw new Error('[@noy-db/in-react] useSync(): no Noydb instance (pass explicitly or wrap in <NoydbProvider>).')\n  }\n  const [state, setState] = useState<UseSyncState>({ lastEvent: null, error: null })\n\n  useEffect(() => {\n    const handler = (event: ChangeEvent): void => {\n      setState({ lastEvent: event, error: null })\n    }\n    instance.on('change', handler)\n    return () => {\n      instance.off('change', handler)\n    }\n  }, [instance])\n\n  return state\n}\n\n// ─── Re-exports for convenience ─────────────────────────────────────────\n\nexport type { Noydb, Vault, Collection, ChangeEvent } from '@noy-db/hub'\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,73 @@
+import { ReactNode } from 'react';
+import { Noydb, ChangeEvent, Vault, Query } from '@noy-db/hub';
+export { ChangeEvent, Collection, Noydb, Vault } from '@noy-db/hub';
+
+/**
+ * **@noy-db/in-react** — React hooks for noy-db.
+ *
+ * Five hooks that live on top of React 18+'s `useSyncExternalStore`:
+ *
+ *   - {@link useNoydb}       — read the `Noydb` instance from context
+ *   - {@link useVault}       — open a vault, subscribed for lifecycle
+ *   - {@link useCollection}  — reactive record list
+ *   - {@link useQuery}       — reactive result of a query builder
+ *   - {@link useSync}        — reactive sync state
+ *
+ * Change events drive re-renders via `useSyncExternalStore`, which
+ * concurrent-mode-safely bridges an external subscription into React's
+ * scheduling. No extra state library needed.
+ *
+ * @packageDocumentation
+ */
+
+interface NoydbProviderProps {
+    readonly db: Noydb;
+    readonly children: ReactNode;
+}
+/** Provides a `Noydb` instance to every component under this tree. */
+declare function NoydbProvider(props: NoydbProviderProps): ReactNode;
+/** Access the Noydb instance supplied by the nearest `<NoydbProvider>`. */
+declare function useNoydb(): Noydb;
+interface UseVaultState {
+    readonly vault: Vault | null;
+    readonly loading: boolean;
+    readonly error: Error | null;
+}
+/**
+ * Open a vault by name and track its lifecycle. The vault is opened
+ * on mount (re-opened when `name` changes). Optional `locale` is
+ * forwarded to the hub; secret / biometric unlock happens out-of-band
+ * (create the Noydb instance with `secret`, or use `@noy-db/on-*`).
+ */
+declare function useVault(name: string, options?: {
+    locale?: string;
+}): UseVaultState;
+/**
+ * Reactive list of every record in a collection. Auto-refreshes on
+ * any change event from the hub — put, delete, or sync.
+ */
+declare function useCollection<T>(vault: Vault | null, collectionName: string): {
+    data: T[];
+    loading: boolean;
+    error: Error | null;
+};
+/**
+ * Reactive result of a query builder. The builder is re-executed
+ * whenever the collection's change stream fires.
+ */
+declare function useQuery<T, R>(vault: Vault | null, collectionName: string, builder: (q: Query<T>) => Promise<R> | R, deps?: readonly unknown[]): {
+    data: R | null;
+    loading: boolean;
+    error: Error | null;
+};
+interface UseSyncState {
+    readonly lastEvent: ChangeEvent | null;
+    readonly error: Error | null;
+}
+/**
+ * Subscribe to the hub's cross-collection change stream. Useful for
+ * top-level status indicators ("unsynced changes", last-update time).
+ */
+declare function useSync(db?: Noydb): UseSyncState;
+
+export { NoydbProvider, type NoydbProviderProps, type UseSyncState, type UseVaultState, useCollection, useNoydb, useQuery, useSync, useVault };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import { ReactNode } from 'react';
+import { Noydb, ChangeEvent, Vault, Query } from '@noy-db/hub';
+export { ChangeEvent, Collection, Noydb, Vault } from '@noy-db/hub';
+
+/**
+ * **@noy-db/in-react** — React hooks for noy-db.
+ *
+ * Five hooks that live on top of React 18+'s `useSyncExternalStore`:
+ *
+ *   - {@link useNoydb}       — read the `Noydb` instance from context
+ *   - {@link useVault}       — open a vault, subscribed for lifecycle
+ *   - {@link useCollection}  — reactive record list
+ *   - {@link useQuery}       — reactive result of a query builder
+ *   - {@link useSync}        — reactive sync state
+ *
+ * Change events drive re-renders via `useSyncExternalStore`, which
+ * concurrent-mode-safely bridges an external subscription into React's
+ * scheduling. No extra state library needed.
+ *
+ * @packageDocumentation
+ */
+
+interface NoydbProviderProps {
+    readonly db: Noydb;
+    readonly children: ReactNode;
+}
+/** Provides a `Noydb` instance to every component under this tree. */
+declare function NoydbProvider(props: NoydbProviderProps): ReactNode;
+/** Access the Noydb instance supplied by the nearest `<NoydbProvider>`. */
+declare function useNoydb(): Noydb;
+interface UseVaultState {
+    readonly vault: Vault | null;
+    readonly loading: boolean;
+    readonly error: Error | null;
+}
+/**
+ * Open a vault by name and track its lifecycle. The vault is opened
+ * on mount (re-opened when `name` changes). Optional `locale` is
+ * forwarded to the hub; secret / biometric unlock happens out-of-band
+ * (create the Noydb instance with `secret`, or use `@noy-db/on-*`).
+ */
+declare function useVault(name: string, options?: {
+    locale?: string;
+}): UseVaultState;
+/**
+ * Reactive list of every record in a collection. Auto-refreshes on
+ * any change event from the hub — put, delete, or sync.
+ */
+declare function useCollection<T>(vault: Vault | null, collectionName: string): {
+    data: T[];
+    loading: boolean;
+    error: Error | null;
+};
+/**
+ * Reactive result of a query builder. The builder is re-executed
+ * whenever the collection's change stream fires.
+ */
+declare function useQuery<T, R>(vault: Vault | null, collectionName: string, builder: (q: Query<T>) => Promise<R> | R, deps?: readonly unknown[]): {
+    data: R | null;
+    loading: boolean;
+    error: Error | null;
+};
+interface UseSyncState {
+    readonly lastEvent: ChangeEvent | null;
+    readonly error: Error | null;
+}
+/**
+ * Subscribe to the hub's cross-collection change stream. Useful for
+ * top-level status indicators ("unsynced changes", last-update time).
+ */
+declare function useSync(db?: Noydb): UseSyncState;
+
+export { NoydbProvider, type NoydbProviderProps, type UseSyncState, type UseVaultState, useCollection, useNoydb, useQuery, useSync, useVault };

package/dist/index.js

@@ -0,0 +1,133 @@
+// src/index.ts
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useMemo,
+  useState
+} from "react";
+var NoydbContext = createContext(null);
+function NoydbProvider(props) {
+  return createElement(NoydbContext.Provider, { value: props.db }, props.children);
+}
+function useNoydb() {
+  const db = useContext(NoydbContext);
+  if (!db) {
+    throw new Error(
+      "[@noy-db/in-react] useNoydb(): no NoydbProvider found in the React tree. Wrap your app with <NoydbProvider db={db}>."
+    );
+  }
+  return db;
+}
+function useVault(name, options) {
+  const db = useNoydb();
+  const [state, setState] = useState({ vault: null, loading: true, error: null });
+  useEffect(() => {
+    let cancelled = false;
+    setState({ vault: null, loading: true, error: null });
+    db.openVault(name, options).then((v) => {
+      if (!cancelled) setState({ vault: v, loading: false, error: null });
+    }).catch((err) => {
+      if (!cancelled) setState({ vault: null, loading: false, error: err });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [db, name, options?.locale]);
+  return state;
+}
+function useCollection(vault, collectionName) {
+  const [state, setState] = useState(() => ({
+    data: [],
+    loading: true,
+    error: null
+  }));
+  const coll = useMemo(
+    () => vault ? vault.collection(collectionName) : null,
+    [vault, collectionName]
+  );
+  useEffect(() => {
+    if (!coll) {
+      setState({ data: [], loading: true, error: null });
+      return;
+    }
+    let cancelled = false;
+    const refresh = async () => {
+      try {
+        const records = await coll.list();
+        if (!cancelled) setState({ data: records, loading: false, error: null });
+      } catch (err) {
+        if (!cancelled) setState({ data: [], loading: false, error: err });
+      }
+    };
+    void refresh();
+    const unsubscribe = coll.subscribe(() => {
+      void refresh();
+    });
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [coll]);
+  return state;
+}
+function useQuery(vault, collectionName, builder, deps = []) {
+  const [state, setState] = useState(() => ({
+    data: null,
+    loading: true,
+    error: null
+  }));
+  const coll = useMemo(
+    () => vault ? vault.collection(collectionName) : null,
+    [vault, collectionName]
+  );
+  useEffect(() => {
+    if (!coll) return;
+    let cancelled = false;
+    const run = async () => {
+      try {
+        const result = await Promise.resolve(builder(coll.query()));
+        if (!cancelled) setState({ data: result, loading: false, error: null });
+      } catch (err) {
+        if (!cancelled) setState({ data: null, loading: false, error: err });
+      }
+    };
+    void run();
+    const unsubscribe = coll.subscribe(() => {
+      void run();
+    });
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [coll, ...deps]);
+  return state;
+}
+function useSync(db) {
+  const ctx = useContext(NoydbContext);
+  const instance = db ?? ctx;
+  if (!instance) {
+    throw new Error("[@noy-db/in-react] useSync(): no Noydb instance (pass explicitly or wrap in <NoydbProvider>).");
+  }
+  const [state, setState] = useState({ lastEvent: null, error: null });
+  useEffect(() => {
+    const handler = (event) => {
+      setState({ lastEvent: event, error: null });
+    };
+    instance.on("change", handler);
+    return () => {
+      instance.off("change", handler);
+    };
+  }, [instance]);
+  return state;
+}
+export {
+  NoydbProvider,
+  useCollection,
+  useNoydb,
+  useQuery,
+  useSync,
+  useVault
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/in-react** — React hooks for noy-db.\n *\n * Five hooks that live on top of React 18+'s `useSyncExternalStore`:\n *\n *   - {@link useNoydb}       — read the `Noydb` instance from context\n *   - {@link useVault}       — open a vault, subscribed for lifecycle\n *   - {@link useCollection}  — reactive record list\n *   - {@link useQuery}       — reactive result of a query builder\n *   - {@link useSync}        — reactive sync state\n *\n * Change events drive re-renders via `useSyncExternalStore`, which\n * concurrent-mode-safely bridges an external subscription into React's\n * scheduling. No extra state library needed.\n *\n * @packageDocumentation\n */\n\nimport {\n  createContext,\n  createElement,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n  type ReactNode,\n} from 'react'\nimport type { Noydb, Vault, ChangeEvent, Query } from '@noy-db/hub'\n\n// ─── Context ────────────────────────────────────────────────────────────\n\nconst NoydbContext = createContext<Noydb | null>(null)\n\nexport interface NoydbProviderProps {\n  readonly db: Noydb\n  readonly children: ReactNode\n}\n\n/** Provides a `Noydb` instance to every component under this tree. */\nexport function NoydbProvider(props: NoydbProviderProps): ReactNode {\n  return createElement(NoydbContext.Provider, { value: props.db }, props.children)\n}\n\n/** Access the Noydb instance supplied by the nearest `<NoydbProvider>`. */\nexport function useNoydb(): Noydb {\n  const db = useContext(NoydbContext)\n  if (!db) {\n    throw new Error(\n      '[@noy-db/in-react] useNoydb(): no NoydbProvider found in the React tree. ' +\n      'Wrap your app with <NoydbProvider db={db}>.',\n    )\n  }\n  return db\n}\n\n// ─── useVault ───────────────────────────────────────────────────────────\n\nexport interface UseVaultState {\n  readonly vault: Vault | null\n  readonly loading: boolean\n  readonly error: Error | null\n}\n\n/**\n * Open a vault by name and track its lifecycle. The vault is opened\n * on mount (re-opened when `name` changes). Optional `locale` is\n * forwarded to the hub; secret / biometric unlock happens out-of-band\n * (create the Noydb instance with `secret`, or use `@noy-db/on-*`).\n */\nexport function useVault(name: string, options?: { locale?: string }): UseVaultState {\n  const db = useNoydb()\n  const [state, setState] = useState<UseVaultState>({ vault: null, loading: true, error: null })\n\n  useEffect(() => {\n    let cancelled = false\n    setState({ vault: null, loading: true, error: null })\n    db.openVault(name, options)\n      .then((v) => {\n        if (!cancelled) setState({ vault: v, loading: false, error: null })\n      })\n      .catch((err: Error) => {\n        if (!cancelled) setState({ vault: null, loading: false, error: err })\n      })\n    return () => {\n      cancelled = true\n    }\n  }, [db, name, options?.locale])\n\n  return state\n}\n\n// ─── useCollection ──────────────────────────────────────────────────────\n\n/**\n * Reactive list of every record in a collection. Auto-refreshes on\n * any change event from the hub — put, delete, or sync.\n */\nexport function useCollection<T>(\n  vault: Vault | null,\n  collectionName: string,\n): { data: T[]; loading: boolean; error: Error | null } {\n  const [state, setState] = useState<{ data: T[]; loading: boolean; error: Error | null }>(() => ({\n    data: [], loading: true, error: null,\n  }))\n\n  const coll = useMemo(\n    () => (vault ? vault.collection<T>(collectionName) : null),\n    [vault, collectionName],\n  )\n\n  useEffect(() => {\n    if (!coll) {\n      setState({ data: [], loading: true, error: null })\n      return\n    }\n    let cancelled = false\n    const refresh = async (): Promise<void> => {\n      try {\n        const records = await coll.list()\n        if (!cancelled) setState({ data: records, loading: false, error: null })\n      } catch (err) {\n        if (!cancelled) setState({ data: [], loading: false, error: err as Error })\n      }\n    }\n    void refresh()\n    const unsubscribe = coll.subscribe(() => { void refresh() })\n    return () => {\n      cancelled = true\n      unsubscribe()\n    }\n  }, [coll])\n\n  return state\n}\n\n// ─── useQuery ───────────────────────────────────────────────────────────\n\n/**\n * Reactive result of a query builder. The builder is re-executed\n * whenever the collection's change stream fires.\n */\nexport function useQuery<T, R>(\n  vault: Vault | null,\n  collectionName: string,\n  builder: (q: Query<T>) => Promise<R> | R,\n  deps: readonly unknown[] = [],\n): { data: R | null; loading: boolean; error: Error | null } {\n  const [state, setState] = useState<{ data: R | null; loading: boolean; error: Error | null }>(() => ({\n    data: null, loading: true, error: null,\n  }))\n\n  const coll = useMemo(\n    () => (vault ? vault.collection<T>(collectionName) : null),\n    [vault, collectionName],\n  )\n\n  useEffect(() => {\n    if (!coll) return\n    let cancelled = false\n    const run = async (): Promise<void> => {\n      try {\n        const result = await Promise.resolve(builder(coll.query() as unknown as Query<T>))\n        if (!cancelled) setState({ data: result, loading: false, error: null })\n      } catch (err) {\n        if (!cancelled) setState({ data: null, loading: false, error: err as Error })\n      }\n    }\n    void run()\n    const unsubscribe = coll.subscribe(() => { void run() })\n    return () => {\n      cancelled = true\n      unsubscribe()\n    }\n  }, [coll, ...deps])\n\n  return state\n}\n\n// ─── useSync ────────────────────────────────────────────────────────────\n\nexport interface UseSyncState {\n  readonly lastEvent: ChangeEvent | null\n  readonly error: Error | null\n}\n\n/**\n * Subscribe to the hub's cross-collection change stream. Useful for\n * top-level status indicators (\"unsynced changes\", last-update time).\n */\nexport function useSync(db?: Noydb): UseSyncState {\n  const ctx = useContext(NoydbContext)\n  const instance = db ?? ctx\n  if (!instance) {\n    throw new Error('[@noy-db/in-react] useSync(): no Noydb instance (pass explicitly or wrap in <NoydbProvider>).')\n  }\n  const [state, setState] = useState<UseSyncState>({ lastEvent: null, error: null })\n\n  useEffect(() => {\n    const handler = (event: ChangeEvent): void => {\n      setState({ lastEvent: event, error: null })\n    }\n    instance.on('change', handler)\n    return () => {\n      instance.off('change', handler)\n    }\n  }, [instance])\n\n  return state\n}\n\n// ─── Re-exports for convenience ─────────────────────────────────────────\n\nexport type { Noydb, Vault, Collection, ChangeEvent } from '@noy-db/hub'\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@noy-db/in-react",
+  "version": "0.1.0-pre.3",
+  "description": "React hooks for noy-db — useNoydb, useVault, useCollection, useQuery, useSync. Uses useSyncExternalStore for reactive subscriptions. Zero deps beyond React.",
+  "license": "MIT",
+  "author": "vLannaAi <vicio@lanna.ai>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/in-react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/in-react"
+  },
+  "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": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "@noy-db/hub": "0.1.0-pre.3"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^18.0.0",
+    "happy-dom": "^15.11.7",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "@noy-db/hub": "0.1.0-pre.3"
+  },
+  "keywords": [
+    "noy-db",
+    "in-react",
+    "react",
+    "hooks",
+    "zero-knowledge"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}