@taladb/react 0.8.4 → 0.9.0

package/dist/index.d.mts

@@ -1,27 +1,52 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { TalaDB, Document, Collection, Filter } from 'taladb';
+import { TalaDB, OpenDBOptions, Document, Collection, Filter } from 'taladb';
 
-interface TalaDBProviderProps {
-    /** The TalaDB instance returned by `openDB()`. */
-    db: TalaDB;
+type TalaDBProviderProps = {
     children: ReactNode;
-}
+} & ({
+    /** A TalaDB instance you opened yourself with `openDB()`. */
+    db: TalaDB;
+    name?: never;
+    options?: never;
+    fallback?: never;
+} | {
+    /**
+     * Database name — the provider owns the `openDB(name)` lifecycle:
+     * it opens lazily on the client (never during SSR), provides the handle
+     * once ready, and closes it on unmount. The natural form for Next.js,
+     * where `openDB` cannot run during server rendering.
+     */
+    name: string;
+    /** Options forwarded to `openDB(name, options)` (e.g. inline sync config). */
+    options?: OpenDBOptions;
+    /**
+     * Rendered while the database is opening (and during SSR).
+     * Defaults to `null`. Children only render once the db is ready, so
+     * `useTalaDB()` never observes a missing instance.
+     */
+    fallback?: ReactNode;
+    db?: never;
+});
 /**
  * Provides a TalaDB instance to all child hooks.
  *
- * @example
+ * Two forms:
+ *
+ * **Instance form** — you own the lifecycle (plain React, React Native):
+ * ```tsx
  * const db = await openDB('myapp.db')
+ * <TalaDBProvider db={db}>…</TalaDBProvider>
+ * ```
  *
- * function App() {
- *   return (
- *     <TalaDBProvider db={db}>
- *       <MyComponent />
- *     </TalaDBProvider>
- *   )
- * }
+ * **Name form** — the provider owns the lifecycle (recommended for Next.js):
+ * ```tsx
+ * <TalaDBProvider name="myapp.db" fallback={<Splash />}>…</TalaDBProvider>
+ * ```
+ * The database opens client-side only; during SSR (and while opening) the
+ * `fallback` renders instead of children, so hooks always see a ready db.
  */
-declare function TalaDBProvider({ db, children }: TalaDBProviderProps): react_jsx_runtime.JSX.Element;
+declare function TalaDBProvider(props: TalaDBProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Returns the TalaDB instance from the nearest `<TalaDBProvider>`.
  *
@@ -49,6 +74,8 @@ interface FindResult<T> {
     data: T[];
     /** True until the first snapshot has been delivered from the database. */
     loading: boolean;
+    /** Most recent subscription error, cleared by the next successful snapshot. */
+    error: unknown | null;
 }
 /**
  * Subscribe to a live query. Re-renders whenever the matching documents change.
@@ -72,6 +99,8 @@ interface FindOneResult<T> {
     data: T | null;
     /** True until the first snapshot has been delivered from the database. */
     loading: boolean;
+    /** Most recent subscription error, cleared by the next successful snapshot. */
+    error: unknown | null;
 }
 /**
  * Subscribe to a single document live query. Re-renders when the matching

package/dist/index.d.ts

@@ -1,27 +1,52 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { TalaDB, Document, Collection, Filter } from 'taladb';
+import { TalaDB, OpenDBOptions, Document, Collection, Filter } from 'taladb';
 
-interface TalaDBProviderProps {
-    /** The TalaDB instance returned by `openDB()`. */
-    db: TalaDB;
+type TalaDBProviderProps = {
     children: ReactNode;
-}
+} & ({
+    /** A TalaDB instance you opened yourself with `openDB()`. */
+    db: TalaDB;
+    name?: never;
+    options?: never;
+    fallback?: never;
+} | {
+    /**
+     * Database name — the provider owns the `openDB(name)` lifecycle:
+     * it opens lazily on the client (never during SSR), provides the handle
+     * once ready, and closes it on unmount. The natural form for Next.js,
+     * where `openDB` cannot run during server rendering.
+     */
+    name: string;
+    /** Options forwarded to `openDB(name, options)` (e.g. inline sync config). */
+    options?: OpenDBOptions;
+    /**
+     * Rendered while the database is opening (and during SSR).
+     * Defaults to `null`. Children only render once the db is ready, so
+     * `useTalaDB()` never observes a missing instance.
+     */
+    fallback?: ReactNode;
+    db?: never;
+});
 /**
  * Provides a TalaDB instance to all child hooks.
  *
- * @example
+ * Two forms:
+ *
+ * **Instance form** — you own the lifecycle (plain React, React Native):
+ * ```tsx
  * const db = await openDB('myapp.db')
+ * <TalaDBProvider db={db}>…</TalaDBProvider>
+ * ```
  *
- * function App() {
- *   return (
- *     <TalaDBProvider db={db}>
- *       <MyComponent />
- *     </TalaDBProvider>
- *   )
- * }
+ * **Name form** — the provider owns the lifecycle (recommended for Next.js):
+ * ```tsx
+ * <TalaDBProvider name="myapp.db" fallback={<Splash />}>…</TalaDBProvider>
+ * ```
+ * The database opens client-side only; during SSR (and while opening) the
+ * `fallback` renders instead of children, so hooks always see a ready db.
  */
-declare function TalaDBProvider({ db, children }: TalaDBProviderProps): react_jsx_runtime.JSX.Element;
+declare function TalaDBProvider(props: TalaDBProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Returns the TalaDB instance from the nearest `<TalaDBProvider>`.
  *
@@ -49,6 +74,8 @@ interface FindResult<T> {
     data: T[];
     /** True until the first snapshot has been delivered from the database. */
     loading: boolean;
+    /** Most recent subscription error, cleared by the next successful snapshot. */
+    error: unknown | null;
 }
 /**
  * Subscribe to a live query. Re-renders whenever the matching documents change.
@@ -72,6 +99,8 @@ interface FindOneResult<T> {
     data: T | null;
     /** True until the first snapshot has been delivered from the database. */
     loading: boolean;
+    /** Most recent subscription error, cleared by the next successful snapshot. */
+    error: unknown | null;
 }
 /**
  * Subscribe to a single document live query. Re-renders when the matching

package/dist/index.js

@@ -1,7 +1,10 @@
+'use client';
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +18,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -32,13 +43,49 @@ module.exports = __toCommonJS(index_exports);
 var import_react = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
 var TalaDBContext = (0, import_react.createContext)(null);
-function TalaDBProvider({ db, children }) {
+function TalaDBProvider(props) {
+  if ("db" in props && props.db) {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TalaDBContext.Provider, { value: props.db, children: props.children });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(NamedProvider, { ...props });
+}
+function NamedProvider({
+  name,
+  options,
+  fallback = null,
+  children
+}) {
+  const [db, setDb] = (0, import_react.useState)(null);
+  const [error, setError] = (0, import_react.useState)(null);
+  const optionsKey = JSON.stringify(options ?? null);
+  (0, import_react.useEffect)(() => {
+    setError(null);
+    let cancelled = false;
+    let opened = null;
+    import("taladb").then(({ openDB }) => openDB(name, options)).then((instance) => {
+      if (cancelled) {
+        void instance.close();
+        return;
+      }
+      opened = instance;
+      setDb(instance);
+    }).catch((e) => {
+      if (!cancelled) setError(e);
+    });
+    return () => {
+      cancelled = true;
+      if (opened) void opened.close();
+      setDb(null);
+    };
+  }, [name, optionsKey]);
+  if (error !== null) throw error;
+  if (db === null) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: fallback });
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TalaDBContext.Provider, { value: db, children });
 }
 function useTalaDB() {
   const db = (0, import_react.useContext)(TalaDBContext);
   if (db === null) {
-    throw new Error("useTalaDB must be used inside <TalaDBProvider db={...}>");
+    throw new Error('useTalaDB must be used inside <TalaDBProvider db={...}> or <TalaDBProvider name="...">');
   }
   return db;
 }
@@ -53,13 +100,16 @@ function useCollection(name) {
 // src/useFind.ts
 var import_react3 = require("react");
 function useFind(collection, filter) {
-  const snapshotRef = (0, import_react3.useRef)({ data: [], loading: true });
+  const snapshotRef = (0, import_react3.useRef)({ data: [], loading: true, error: null });
   const filterKey = JSON.stringify(filter ?? null);
   const subscribe = (0, import_react3.useCallback)(
     (notify) => {
-      snapshotRef.current = { data: snapshotRef.current.data, loading: true };
+      snapshotRef.current = { data: snapshotRef.current.data, loading: true, error: null };
       return collection.subscribe(filter ?? {}, (docs) => {
-        snapshotRef.current = { data: docs, loading: false };
+        snapshotRef.current = { data: docs, loading: false, error: null };
+        notify();
+      }, (error) => {
+        snapshotRef.current = { ...snapshotRef.current, loading: false, error };
         notify();
       });
     },
@@ -74,13 +124,16 @@ function useFind(collection, filter) {
 // src/useFindOne.ts
 var import_react4 = require("react");
 function useFindOne(collection, filter) {
-  const snapshotRef = (0, import_react4.useRef)({ data: null, loading: true });
+  const snapshotRef = (0, import_react4.useRef)({ data: null, loading: true, error: null });
   const filterKey = JSON.stringify(filter);
   const subscribe = (0, import_react4.useCallback)(
     (notify) => {
-      snapshotRef.current = { data: snapshotRef.current.data, loading: true };
+      snapshotRef.current = { data: snapshotRef.current.data, loading: true, error: null };
       return collection.subscribe(filter, (docs) => {
-        snapshotRef.current = { data: docs[0] ?? null, loading: false };
+        snapshotRef.current = { data: docs[0] ?? null, loading: false, error: null };
+        notify();
+      }, (error) => {
+        snapshotRef.current = { ...snapshotRef.current, loading: false, error };
         notify();
       });
     },

package/dist/index.mjs

@@ -1,14 +1,52 @@
+'use client';
+
 // src/context.tsx
-import { createContext, useContext } from "react";
-import { jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useState } from "react";
+import { Fragment, jsx } from "react/jsx-runtime";
 var TalaDBContext = createContext(null);
-function TalaDBProvider({ db, children }) {
+function TalaDBProvider(props) {
+  if ("db" in props && props.db) {
+    return /* @__PURE__ */ jsx(TalaDBContext.Provider, { value: props.db, children: props.children });
+  }
+  return /* @__PURE__ */ jsx(NamedProvider, { ...props });
+}
+function NamedProvider({
+  name,
+  options,
+  fallback = null,
+  children
+}) {
+  const [db, setDb] = useState(null);
+  const [error, setError] = useState(null);
+  const optionsKey = JSON.stringify(options ?? null);
+  useEffect(() => {
+    setError(null);
+    let cancelled = false;
+    let opened = null;
+    import("taladb").then(({ openDB }) => openDB(name, options)).then((instance) => {
+      if (cancelled) {
+        void instance.close();
+        return;
+      }
+      opened = instance;
+      setDb(instance);
+    }).catch((e) => {
+      if (!cancelled) setError(e);
+    });
+    return () => {
+      cancelled = true;
+      if (opened) void opened.close();
+      setDb(null);
+    };
+  }, [name, optionsKey]);
+  if (error !== null) throw error;
+  if (db === null) return /* @__PURE__ */ jsx(Fragment, { children: fallback });
   return /* @__PURE__ */ jsx(TalaDBContext.Provider, { value: db, children });
 }
 function useTalaDB() {
   const db = useContext(TalaDBContext);
   if (db === null) {
-    throw new Error("useTalaDB must be used inside <TalaDBProvider db={...}>");
+    throw new Error('useTalaDB must be used inside <TalaDBProvider db={...}> or <TalaDBProvider name="...">');
   }
   return db;
 }
@@ -23,13 +61,16 @@ function useCollection(name) {
 // src/useFind.ts
 import { useCallback, useRef, useSyncExternalStore } from "react";
 function useFind(collection, filter) {
-  const snapshotRef = useRef({ data: [], loading: true });
+  const snapshotRef = useRef({ data: [], loading: true, error: null });
   const filterKey = JSON.stringify(filter ?? null);
   const subscribe = useCallback(
     (notify) => {
-      snapshotRef.current = { data: snapshotRef.current.data, loading: true };
+      snapshotRef.current = { data: snapshotRef.current.data, loading: true, error: null };
       return collection.subscribe(filter ?? {}, (docs) => {
-        snapshotRef.current = { data: docs, loading: false };
+        snapshotRef.current = { data: docs, loading: false, error: null };
+        notify();
+      }, (error) => {
+        snapshotRef.current = { ...snapshotRef.current, loading: false, error };
         notify();
       });
     },
@@ -44,13 +85,16 @@ function useFind(collection, filter) {
 // src/useFindOne.ts
 import { useCallback as useCallback2, useRef as useRef2, useSyncExternalStore as useSyncExternalStore2 } from "react";
 function useFindOne(collection, filter) {
-  const snapshotRef = useRef2({ data: null, loading: true });
+  const snapshotRef = useRef2({ data: null, loading: true, error: null });
   const filterKey = JSON.stringify(filter);
   const subscribe = useCallback2(
     (notify) => {
-      snapshotRef.current = { data: snapshotRef.current.data, loading: true };
+      snapshotRef.current = { data: snapshotRef.current.data, loading: true, error: null };
       return collection.subscribe(filter, (docs) => {
-        snapshotRef.current = { data: docs[0] ?? null, loading: false };
+        snapshotRef.current = { data: docs[0] ?? null, loading: false, error: null };
+        notify();
+      }, (error) => {
+        snapshotRef.current = { ...snapshotRef.current, loading: false, error };
         notify();
       });
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taladb/react",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "React hooks for TalaDB — useFind, useFindOne, and useCollection for React and React Native",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -41,7 +41,7 @@
   },
   "peerDependencies": {
     "react": ">=18.0.0",
-    "taladb": "^0.8.4"
+    "taladb": "^0.9.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",
@@ -53,7 +53,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.0",
-    "taladb": "0.8.4"
+    "taladb": "0.9.0"
   },
   "scripts": {
     "build": "tsup",