@noy-db/in-react 0.2.0-pre.9 → 0.3.0-pre.2

package/README.md

@@ -26,7 +26,7 @@ See the [main repository](https://github.com/vLannaAi/noy-db#readme) for setup,
 
 - 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)
+- Spec — [`SPEC.md`](https://github.com/vLannaAi/noy-db-docs/blob/main/SPEC.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noy-db/in-react",
-  "version": "0.2.0-pre.9",
+  "version": "0.3.0-pre.2",
   "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>",
@@ -17,17 +17,10 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
-  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -36,11 +29,11 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "@noy-db/hub": "0.2.0-pre.9"
+    "@noy-db/hub": "0.3.0-pre.2"
   },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",
@@ -48,7 +41,7 @@
     "happy-dom": "^15.11.7",
     "react": "^18.3.0",
     "react-dom": "^18.3.0",
-    "@noy-db/hub": "0.2.0-pre.9"
+    "@noy-db/hub": "0.3.0-pre.2"
   },
   "keywords": [
     "noy-db",

package/dist/index.cjs

@@ -1,156 +0,0 @@
-"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

@@ -1 +0,0 @@
-{"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

@@ -1,73 +0,0 @@
-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 };