@taladb/react 0.11.0 → 0.11.1

package/dist/{chunk-SEH233OC.mjs → chunk-RAGFVMZN.mjs}

@@ -41,6 +41,47 @@ function TalaDBProvider(props) {
   }
   return /* @__PURE__ */ jsx(NamedProvider, { ...props });
 }
+var openDatabases = /* @__PURE__ */ new Map();
+function databaseKey(name, optionsKey) {
+  return `${name}\0${optionsKey}`;
+}
+function acquireDatabase(name, optionsKey, options) {
+  const key = databaseKey(name, optionsKey);
+  let entry = openDatabases.get(key);
+  if (entry) {
+    if (entry.closing !== void 0) {
+      clearTimeout(entry.closing);
+      entry.closing = void 0;
+    }
+  } else {
+    entry = {
+      // Dynamic import so `taladb`'s runtime never loads during SSR module
+      // evaluation (its Node entry pulls in the native binding, which a web
+      // app's server bundle does not ship).
+      promise: import("taladb").then(({ openDB }) => openDB(name, options)),
+      refs: 0
+    };
+    openDatabases.set(key, entry);
+  }
+  entry.refs++;
+  return entry.promise;
+}
+function releaseDatabase(name, optionsKey) {
+  const key = databaseKey(name, optionsKey);
+  const entry = openDatabases.get(key);
+  if (!entry) return;
+  entry.refs--;
+  if (entry.refs > 0 || entry.closing !== void 0) return;
+  entry.closing = setTimeout(() => {
+    if (entry.refs > 0) {
+      entry.closing = void 0;
+      return;
+    }
+    openDatabases.delete(key);
+    void entry.promise.then((db) => db.close()).catch(() => {
+    });
+  }, 0);
+}
 function NamedProvider({
   name,
   options,
@@ -54,20 +95,14 @@ function NamedProvider({
   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);
+    acquireDatabase(name, optionsKey, options).then((instance) => {
+      if (!cancelled) setDb(instance);
     }).catch((e) => {
       if (!cancelled) setError(e);
     });
     return () => {
       cancelled = true;
-      if (opened) void opened.close();
+      releaseDatabase(name, optionsKey);
       setDb(null);
     };
   }, [name, optionsKey]);

package/dist/index.js

@@ -76,6 +76,47 @@ function TalaDBProvider(props) {
   }
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(NamedProvider, { ...props });
 }
+var openDatabases = /* @__PURE__ */ new Map();
+function databaseKey(name, optionsKey) {
+  return `${name}\0${optionsKey}`;
+}
+function acquireDatabase(name, optionsKey, options) {
+  const key = databaseKey(name, optionsKey);
+  let entry = openDatabases.get(key);
+  if (entry) {
+    if (entry.closing !== void 0) {
+      clearTimeout(entry.closing);
+      entry.closing = void 0;
+    }
+  } else {
+    entry = {
+      // Dynamic import so `taladb`'s runtime never loads during SSR module
+      // evaluation (its Node entry pulls in the native binding, which a web
+      // app's server bundle does not ship).
+      promise: import("taladb").then(({ openDB }) => openDB(name, options)),
+      refs: 0
+    };
+    openDatabases.set(key, entry);
+  }
+  entry.refs++;
+  return entry.promise;
+}
+function releaseDatabase(name, optionsKey) {
+  const key = databaseKey(name, optionsKey);
+  const entry = openDatabases.get(key);
+  if (!entry) return;
+  entry.refs--;
+  if (entry.refs > 0 || entry.closing !== void 0) return;
+  entry.closing = setTimeout(() => {
+    if (entry.refs > 0) {
+      entry.closing = void 0;
+      return;
+    }
+    openDatabases.delete(key);
+    void entry.promise.then((db) => db.close()).catch(() => {
+    });
+  }, 0);
+}
 function NamedProvider({
   name,
   options,
@@ -89,20 +130,14 @@ function NamedProvider({
   (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);
+    acquireDatabase(name, optionsKey, options).then((instance) => {
+      if (!cancelled) setDb(instance);
     }).catch((e) => {
       if (!cancelled) setError(e);
     });
     return () => {
       cancelled = true;
-      if (opened) void opened.close();
+      releaseDatabase(name, optionsKey);
       setDb(null);
     };
   }, [name, optionsKey]);

package/dist/index.mjs

@@ -5,7 +5,7 @@ import {
   useCollectionOptions,
   useFind,
   useTalaDB
-} from "./chunk-SEH233OC.mjs";
+} from "./chunk-RAGFVMZN.mjs";
 
 // src/useFindOne.ts
 import { useCallback, useRef, useSyncExternalStore } from "react";

package/dist/query/index.d.mts

@@ -1440,22 +1440,7 @@ interface HydrateResult {
     /** Documents left alone because they carry unsynced local work. */
     skipped: number;
 }
-/**
- * Write a server response into the local collection.
- *
- * The rule that matters, and the one a naive bulk upsert gets wrong: **a
- * response must never overwrite a document with unsynced local work.** The
- * moment connectivity returns, a refetch and a queued edit race, and the
- * obvious implementation silently discards whatever the user did offline.
- * Anything not `synced` is therefore left exactly as it is — the drain loop
- * owns those documents until the server accepts them.
- *
- * Inserts go through one `insertMany`; updates cannot be batched, because each
- * document sets different values and the engine exposes no upsert. That matters
- * on a secondary browser tab, where every write is forwarded to the primary and
- * the forward buffer is bounded — see PLAN-query.md §5.
- */
-declare function hydrate<T extends Document>(collection: Collection<T>, docs: T[], now: number): Promise<HydrateResult>;
+declare function hydrate<T extends Document>(collection: Collection<T>, docs: T[], now: number, collectionName?: string): Promise<HydrateResult>;
 
 /**
  * Rules 1 and 2 — client ids are authoritative, and writes are idempotent.

package/dist/query/index.d.ts

@@ -1440,22 +1440,7 @@ interface HydrateResult {
     /** Documents left alone because they carry unsynced local work. */
     skipped: number;
 }
-/**
- * Write a server response into the local collection.
- *
- * The rule that matters, and the one a naive bulk upsert gets wrong: **a
- * response must never overwrite a document with unsynced local work.** The
- * moment connectivity returns, a refetch and a queued edit race, and the
- * obvious implementation silently discards whatever the user did offline.
- * Anything not `synced` is therefore left exactly as it is — the drain loop
- * owns those documents until the server accepts them.
- *
- * Inserts go through one `insertMany`; updates cannot be batched, because each
- * document sets different values and the engine exposes no upsert. That matters
- * on a secondary browser tab, where every write is forwarded to the primary and
- * the forward buffer is bounded — see PLAN-query.md §5.
- */
-declare function hydrate<T extends Document>(collection: Collection<T>, docs: T[], now: number): Promise<HydrateResult>;
+declare function hydrate<T extends Document>(collection: Collection<T>, docs: T[], now: number, collectionName?: string): Promise<HydrateResult>;
 
 /**
  * Rules 1 and 2 — client ids are authoritative, and writes are idempotent.

package/dist/query/index.js

@@ -777,18 +777,25 @@ function describe(queryKey) {
 }
 
 // src/query/hydrate.ts
-async function hydrate(collection, docs, now) {
+var import_taladb2 = require("taladb");
+var hydrationChains = /* @__PURE__ */ new WeakMap();
+function hydrate(collection, docs, now, collectionName) {
+  const key = collection;
+  const previous = hydrationChains.get(key) ?? Promise.resolve();
+  const run = previous.then(() => hydrateOnce(collection, docs, now, collectionName));
+  hydrationChains.set(key, run.catch(() => void 0));
+  return run;
+}
+async function hydrateOnce(collection, docs, now, collectionName) {
   if (docs.length === 0) return { inserted: 0, updated: 0, skipped: 0 };
-  const ids = [];
+  const unique = /* @__PURE__ */ new Map();
   for (const doc of docs) {
-    if (typeof doc._id !== "string" || doc._id === "") {
-      throw new Error(
-        "A hydrated document has no `_id`. Client ids are authoritative: the endpoint must echo back the `_id` it was sent, and must not assign its own."
-      );
-    }
-    ids.push(doc._id);
+    if (!(0, import_taladb2.isDocId)(doc._id)) throw badDocId(doc._id, collectionName);
     if (process.env.NODE_ENV !== "production") warnOnReservedFields(doc);
+    unique.set(doc._id, doc);
   }
+  const deduped = [...unique.values()];
+  const ids = [...unique.keys()];
   const existing = await collection.find({ _id: { $in: ids } });
   const state = /* @__PURE__ */ new Map();
   for (const doc of existing) {
@@ -797,7 +804,7 @@ async function hydrate(collection, docs, now) {
   const fresh = [];
   let updated = 0;
   let skipped = 0;
-  for (const doc of docs) {
+  for (const doc of deduped) {
     const id = doc._id;
     if (!state.has(id)) {
       fresh.push(stampSynced(doc, now));
@@ -815,6 +822,25 @@ async function hydrate(collection, docs, now) {
   if (fresh.length > 0) await collection.insertMany(fresh);
   return { inserted: fresh.length, updated, skipped };
 }
+function badDocId(value, collectionName) {
+  const where = collectionName ? ` for collection '${collectionName}'` : "";
+  if (value === void 0 || value === null || value === "") {
+    return new Error(
+      `[@taladb/react/query] A document in the response${where} has no \`_id\`. \`data\` is resolved from the local collection, not from what \`queryFn\` returned, so every document needs one. Map your rows in \`queryFn\`: \`rows.map((row) => ({ ...row, _id: deriveDocId(collection, String(row.id)) }))\`.`
+    );
+  }
+  if (typeof value !== "string") {
+    return new Error(
+      `[@taladb/react/query] \`_id\` must be a string${where}, got ${typeof value}. Derive one from your natural key with \`deriveDocId(collection, String(row.id))\`.`
+    );
+  }
+  return new Error(
+    `[@taladb/react/query] \`_id\` ${JSON.stringify(value)}${where} is not a ULID, so the engine cannot store it \u2014 ids are 16 raw bytes on disk. This is what a natural key (a numeric id, a slug, a UUID) looks like when it is passed straight through from the server. Fold it into a ULID in \`queryFn\` instead:
+  import { deriveDocId } from 'taladb'
+  rows.map((row) => ({ ...row, _id: deriveDocId(${collectionName ? `'${collectionName}'` : "collection"}, String(row.id)) }))
+The same key always maps to the same id, which is what keeps refetches idempotent.`
+  );
+}
 function warnOnReservedFields(doc) {
   const reserved = reservedFieldsIn(doc);
   if (reserved.length === 0) return;
@@ -1257,7 +1283,7 @@ function useQuery(options) {
         queryKey: effectiveKey,
         documents: documentsRef.current
       });
-      await hydrate(collection, docs, fetchedAt);
+      await hydrate(collection, docs, fetchedAt, name);
       const nextIds = docs.map((doc) => doc._id);
       const payload2 = shape3 === "envelope" && assembleRef.current !== void 0 ? raw : void 0;
       await writeQueryRecord(

package/dist/query/index.mjs

@@ -4,7 +4,7 @@ import {
   useCollectionOptions,
   useFind,
   useTalaDB
-} from "../chunk-SEH233OC.mjs";
+} from "../chunk-RAGFVMZN.mjs";
 
 // src/query/context.tsx
 import {
@@ -643,18 +643,25 @@ function describe(queryKey) {
 }
 
 // src/query/hydrate.ts
-async function hydrate(collection, docs, now) {
+import { isDocId } from "taladb";
+var hydrationChains = /* @__PURE__ */ new WeakMap();
+function hydrate(collection, docs, now, collectionName) {
+  const key = collection;
+  const previous = hydrationChains.get(key) ?? Promise.resolve();
+  const run = previous.then(() => hydrateOnce(collection, docs, now, collectionName));
+  hydrationChains.set(key, run.catch(() => void 0));
+  return run;
+}
+async function hydrateOnce(collection, docs, now, collectionName) {
   if (docs.length === 0) return { inserted: 0, updated: 0, skipped: 0 };
-  const ids = [];
+  const unique = /* @__PURE__ */ new Map();
   for (const doc of docs) {
-    if (typeof doc._id !== "string" || doc._id === "") {
-      throw new Error(
-        "A hydrated document has no `_id`. Client ids are authoritative: the endpoint must echo back the `_id` it was sent, and must not assign its own."
-      );
-    }
-    ids.push(doc._id);
+    if (!isDocId(doc._id)) throw badDocId(doc._id, collectionName);
     if (process.env.NODE_ENV !== "production") warnOnReservedFields(doc);
+    unique.set(doc._id, doc);
   }
+  const deduped = [...unique.values()];
+  const ids = [...unique.keys()];
   const existing = await collection.find({ _id: { $in: ids } });
   const state = /* @__PURE__ */ new Map();
   for (const doc of existing) {
@@ -663,7 +670,7 @@ async function hydrate(collection, docs, now) {
   const fresh = [];
   let updated = 0;
   let skipped = 0;
-  for (const doc of docs) {
+  for (const doc of deduped) {
     const id = doc._id;
     if (!state.has(id)) {
       fresh.push(stampSynced(doc, now));
@@ -681,6 +688,25 @@ async function hydrate(collection, docs, now) {
   if (fresh.length > 0) await collection.insertMany(fresh);
   return { inserted: fresh.length, updated, skipped };
 }
+function badDocId(value, collectionName) {
+  const where = collectionName ? ` for collection '${collectionName}'` : "";
+  if (value === void 0 || value === null || value === "") {
+    return new Error(
+      `[@taladb/react/query] A document in the response${where} has no \`_id\`. \`data\` is resolved from the local collection, not from what \`queryFn\` returned, so every document needs one. Map your rows in \`queryFn\`: \`rows.map((row) => ({ ...row, _id: deriveDocId(collection, String(row.id)) }))\`.`
+    );
+  }
+  if (typeof value !== "string") {
+    return new Error(
+      `[@taladb/react/query] \`_id\` must be a string${where}, got ${typeof value}. Derive one from your natural key with \`deriveDocId(collection, String(row.id))\`.`
+    );
+  }
+  return new Error(
+    `[@taladb/react/query] \`_id\` ${JSON.stringify(value)}${where} is not a ULID, so the engine cannot store it \u2014 ids are 16 raw bytes on disk. This is what a natural key (a numeric id, a slug, a UUID) looks like when it is passed straight through from the server. Fold it into a ULID in \`queryFn\` instead:
+  import { deriveDocId } from 'taladb'
+  rows.map((row) => ({ ...row, _id: deriveDocId(${collectionName ? `'${collectionName}'` : "collection"}, String(row.id)) }))
+The same key always maps to the same id, which is what keeps refetches idempotent.`
+  );
+}
 function warnOnReservedFields(doc) {
   const reserved = reservedFieldsIn(doc);
   if (reserved.length === 0) return;
@@ -1123,7 +1149,7 @@ function useQuery(options) {
         queryKey: effectiveKey,
         documents: documentsRef.current
       });
-      await hydrate(collection, docs, fetchedAt);
+      await hydrate(collection, docs, fetchedAt, name);
       const nextIds = docs.map((doc) => doc._id);
       const payload2 = shape3 === "envelope" && assembleRef.current !== void 0 ? raw : void 0;
       await writeQueryRecord(

package/package.json

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