@taladb/react 0.10.2 → 0.11.1

package/dist/query/index.js

@@ -0,0 +1,2252 @@
+'use client';
+"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/query/index.ts
+var query_exports = {};
+__export(query_exports, {
+  DEFAULT_METHODS: () => DEFAULT_METHODS,
+  DEFAULT_RETRY: () => DEFAULT_RETRY,
+  DEFAULT_STALE_TIME: () => DEFAULT_STALE_TIME,
+  ENVELOPE_FIELDS: () => ENVELOPE_FIELDS,
+  ENVELOPE_INDEXES: () => ENVELOPE_INDEXES,
+  QUERY_COLLECTION: () => QUERY_COLLECTION,
+  QueryProvider: () => QueryProvider,
+  backoffMs: () => backoffMs,
+  cancelShared: () => cancelShared,
+  checkClassification: () => checkClassification,
+  checkMutationFilter: () => checkMutationFilter,
+  checkResponseBody: () => checkResponseBody,
+  checkResponseId: () => checkResponseId,
+  coalesce: () => coalesce,
+  contains: () => contains,
+  defaultClassify: () => defaultClassify,
+  defineParams: () => defineParams,
+  deleteQueryRecord: () => deleteQueryRecord,
+  drainOnce: () => drainOnce,
+  ensureEnvelopeIndexes: () => ensureEnvelopeIndexes,
+  eq: () => eq,
+  extractDocuments: () => extractDocuments,
+  gt: () => gt,
+  gte: () => gte,
+  hashQueryKey: () => hashQueryKey,
+  hydrate: () => hydrate,
+  inflightKey: () => inflightKey,
+  isBoundParams: () => isBoundParams,
+  isDev: () => isDev2,
+  isOffline: () => isOffline,
+  isShared: () => isShared,
+  isStale: () => isStale,
+  keepPreviousData: () => keepPreviousData,
+  lt: () => lt,
+  lte: () => lte,
+  ne: () => ne,
+  newDocId: () => newDocId,
+  normalizeParams: () => normalizeParams,
+  noteIgnoredOptions: () => noteIgnoredOptions,
+  oneOf: () => oneOf,
+  openQueryCollection: () => openQueryCollection,
+  queryRecordId: () => queryRecordId,
+  readQueryRecord: () => readQueryRecord,
+  replaceEqualDeep: () => replaceEqualDeep,
+  reservedFieldsIn: () => reservedFieldsIn,
+  resetCollectionWarnings: () => resetWarnings,
+  resetForgetTimers: () => resetForgetTimers,
+  resetInflight: () => resetInflight,
+  resetMutationScopes: () => resetMutationScopes,
+  resetWarnings: () => resetWarnings,
+  resolveCollectionName: () => resolveCollectionName,
+  resolveUrl: () => resolveUrl,
+  retryDelayMs: () => retryDelayMs,
+  runShared: () => runShared,
+  sendWrite: () => sendWrite,
+  shape: () => shape,
+  shouldRetry: () => shouldRetry,
+  stampPending: () => stampPending,
+  stampSynced: () => stampSynced,
+  toPendingWrite: () => toPendingWrite,
+  useMutation: () => useMutation,
+  useQuery: () => useQuery,
+  useQueryContext: () => useQueryContext,
+  useSyncStatus: () => useSyncStatus,
+  warnOnce: () => warnOnce,
+  writeConfirmed: () => writeConfirmed,
+  writeLocal: () => writeLocal,
+  writeQueryRecord: () => writeQueryRecord
+});
+module.exports = __toCommonJS(query_exports);
+
+// src/query/context.tsx
+var import_react2 = require("react");
+
+// src/context.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var TalaDBContext = (0, import_react.createContext)(null);
+var CollectionOptionsContext = (0, import_react.createContext)({
+  get: () => void 0,
+  names: () => []
+});
+function useCollectionOptions() {
+  return (0, import_react.useContext)(CollectionOptionsContext);
+}
+function useTalaDB() {
+  const db = (0, import_react.useContext)(TalaDBContext);
+  if (db === null) {
+    throw new Error('useTalaDB must be used inside <TalaDBProvider db={...}> or <TalaDBProvider name="...">');
+  }
+  return db;
+}
+
+// src/query/envelope.ts
+var ENVELOPE_FIELDS = [
+  "_sync",
+  "_op",
+  "_attempt",
+  "_error",
+  "_fetched_at",
+  "_retry_at",
+  "_endpoint",
+  "_method",
+  "_revision"
+];
+var ENVELOPE_INDEXES = ["_sync", "_changed_at"];
+var revisionCounter = 0;
+function nextRevision() {
+  revisionCounter = (revisionCounter + 1) % Number.MAX_SAFE_INTEGER;
+  return `${Date.now().toString(36)}-${revisionCounter.toString(36)}`;
+}
+function reservedFieldsIn(doc) {
+  return ENVELOPE_FIELDS.filter((field) => field in doc);
+}
+function stampSynced(doc, now) {
+  return {
+    ...doc,
+    _sync: "synced",
+    _attempt: 0,
+    _error: null,
+    _fetched_at: now,
+    _retry_at: 0,
+    _revision: null
+  };
+}
+function stampPending(doc, op, previous) {
+  return {
+    ...doc,
+    _sync: "pending",
+    _op: op,
+    _attempt: 0,
+    _error: null,
+    _fetched_at: previous?._fetched_at ?? 0,
+    // Eligible immediately; the drain pushes this forward when it backs off.
+    _retry_at: 0,
+    _revision: nextRevision()
+  };
+}
+function coalesce(pending, next) {
+  if (pending === void 0) return next;
+  if (pending === "insert") return next === "delete" ? null : "insert";
+  if (pending === "update") return next === "delete" ? "delete" : "update";
+  return "delete";
+}
+
+// src/query/canonical.ts
+var ENGINE_FIELDS = /* @__PURE__ */ new Set(["_id", "_changed_at"]);
+function withoutEnvelope(doc) {
+  const application = {};
+  for (const [field, value] of Object.entries(doc)) {
+    if (!ENVELOPE_FIELDS.includes(field)) application[field] = value;
+  }
+  return application;
+}
+async function applyCanonical(collection, current, canonical, now) {
+  const id = canonical._id;
+  const stamped = stampSynced(canonical, now);
+  if (current === null) {
+    await collection.insert(stamped);
+    return;
+  }
+  const fields = { ...stamped };
+  delete fields._id;
+  delete fields._changed_at;
+  const unset = {};
+  for (const field of Object.keys(current)) {
+    if (!ENGINE_FIELDS.has(field) && !(field in fields)) unset[field] = true;
+  }
+  const update = { $set: fields };
+  if (Object.keys(unset).length > 0) update.$unset = unset;
+  await collection.updateOne({ _id: id }, update);
+}
+
+// src/query/endpoint.ts
+var DEFAULT_METHODS = {
+  insert: "POST",
+  update: "PUT",
+  delete: "DELETE"
+};
+function resolveUrl(template, collection, id, type) {
+  const withCollection = template.split(":collection").join(collection);
+  if (type === "insert") {
+    const trimmed = withCollection.replace(/\/:id\/?$/, "");
+    return trimmed.split(":id").join(id);
+  }
+  return withCollection.split(":id").join(id);
+}
+function defaultClassify(response) {
+  if (response.ok) return "ok";
+  if (response.status === 409) return "applied";
+  if (response.status >= 500 || response.status === 408 || response.status === 429) return "retry";
+  return "terminal";
+}
+
+// src/query/validate.ts
+var PREFIX = "[@taladb/react/query]";
+var isDev = () => typeof process === "undefined" || process.env.NODE_ENV !== "production";
+function checkResponseId(op, body, attempt) {
+  if (body === null) return;
+  const returned = body._id;
+  if (typeof returned !== "string" || returned === op.id) return;
+  console.warn(
+    attempt > 0 ? `${PREFIX} Contract rule 2 (idempotent writes): a retried ${op.type} on "${op.collection}" came back with a different id (sent ${op.id}, received ${returned}). The server treated the retry as a new record, so this write has just been duplicated. Make the endpoint upsert on the supplied \`_id\`.` : `${PREFIX} Contract rule 1 (client ids are authoritative): the endpoint for "${op.collection}" returned id ${returned} for a document sent as ${op.id}. Every write will duplicate on the server. Accept \`_id\` from the body and do not reassign it.`
+  );
+}
+function checkResponseBody(op, body) {
+  if (op.type === "delete" || body !== null) return;
+  console.warn(
+    `${PREFIX} Contract rule 4 (canonical response body): the endpoint for "${op.collection}" answered a ${op.type} with no JSON document. Server-set fields \u2014 timestamps, defaults, computed columns \u2014 will be missing locally until the next refetch, with no symptom in between. Return the stored document.`
+  );
+}
+function checkClassification(op, status, outcome) {
+  if (outcome === "retry" && status >= 400 && status < 500 && status !== 408 && status !== 429) {
+    console.warn(
+      `${PREFIX} Contract rule 3 (error classes): classify() returned "retry" for status ${status} on a ${op.type} to "${op.collection}". A 4xx will fail identically forever, so this write will be retried until the tab closes. Return "terminal" for a client error, or "applied" for a 409.`
+    );
+  }
+  if (outcome === "terminal" && status >= 500) {
+    console.warn(
+      `${PREFIX} Contract rule 3 (error classes): classify() returned "terminal" for status ${status}. A 5xx may recover; parking it as failed needs a human to retry what a back-off would have fixed.`
+    );
+  }
+}
+function checkMutationFilter(where) {
+  if (where === null || typeof where !== "object") return;
+  const fields = Object.keys(where);
+  if (fields.length === 1 && fields[0] === "_id") return;
+  console.warn(
+    `${PREFIX} A mutation filter must be { _id }, not { ${fields.join(", ")} }. On a secondary browser tab a filter-based write is forwarded to the primary and re-evaluated there against authoritative data, so it can affect a different set of documents than the UI just showed.`
+  );
+}
+function warnDrainNotPrimary() {
+  console.warn(
+    `${PREFIX} A drain cycle was requested on a secondary tab and skipped. This is expected and harmless. Running it there would re-send writes every cycle, because a secondary reads a pending set that lags, and its own bookkeeping lands at the primary later.`
+  );
+}
+
+// src/query/send.ts
+async function sendWrite(backend, op, signal, attempt = 0, keepalive = false) {
+  const doFetch = backend.fetch ?? globalThis.fetch;
+  const headers = new Headers(backend.headers ? await backend.headers() : void 0);
+  const body = op.type === "delete" ? void 0 : JSON.stringify(op.document);
+  if (body !== void 0 && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  const response = await doFetch(backend.url(op), {
+    keepalive,
+    method: backend.method[op.type],
+    headers,
+    body,
+    signal
+  });
+  const outcome = backend.classify(response, op);
+  const document2 = await readDocument(response, outcome);
+  if (isDev()) {
+    checkClassification(op, response.status, outcome);
+    if (outcome === "ok") {
+      checkResponseId(op, document2, attempt);
+      checkResponseBody(op, document2);
+    }
+  }
+  return { outcome, document: document2, status: response.status };
+}
+async function readDocument(response, outcome) {
+  if (outcome !== "ok") return null;
+  try {
+    const parsed = await response.json();
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function toPendingWrite(collection, id, type, document2) {
+  return { collection, id, type, document: type === "delete" ? null : document2 };
+}
+
+// src/query/drain.ts
+var EMPTY = {
+  sent: 0,
+  synced: 0,
+  deferred: 0,
+  failed: 0,
+  superseded: 0,
+  skippedNotPrimary: false
+};
+function backoffMs(attempt, random = Math.random) {
+  const base = Math.min(1e3 * 2 ** Math.max(0, attempt - 1), 3e5);
+  const jitter = 1 + (random() - 0.5) / 2;
+  return Math.round(base * jitter);
+}
+async function drainOnce(deps) {
+  const { db, backend, collections } = deps;
+  const now = deps.now ?? Date.now;
+  const random = deps.random ?? Math.random;
+  const batch = deps.batch ?? 25;
+  if (!(await db.isPrimary?.() ?? true)) {
+    if (isDev()) warnDrainNotPrimary();
+    return { ...EMPTY, skippedNotPrimary: true };
+  }
+  const stats = { ...EMPTY };
+  for (const name of collections()) {
+    const collection = db.collection(name);
+    const due = await collection.aggregate([
+      { $match: { _sync: "pending", _retry_at: { $lte: now() } } },
+      { $sort: { _changed_at: 1 } },
+      { $limit: batch }
+    ]);
+    await Promise.all(due.map((doc) => sendOne(collection, name, doc, stats, deps, now, random)));
+  }
+  return stats;
+}
+async function sendOne(collection, name, doc, stats, deps, now, random) {
+  const id = doc._id;
+  const op = doc._op;
+  const sentRevision = doc._revision;
+  const backend = routeFor(doc, name, id, op, deps.backend);
+  if (backend === null) {
+    return;
+  }
+  stats.sent++;
+  let result;
+  try {
+    const attempt = doc._attempt ?? 0;
+    result = await sendWrite(
+      backend,
+      toPendingWrite(name, id, op, withoutEnvelope(doc)),
+      void 0,
+      attempt,
+      deps.keepalive ?? false
+    );
+  } catch {
+    await defer(collection, id, doc, stats, now, random);
+    return;
+  }
+  const current = await collection.findOne({ _id: id });
+  if (current === null) return;
+  if (current._revision !== sentRevision) {
+    stats.superseded++;
+    return;
+  }
+  switch (result.outcome) {
+    case "ok":
+    case "applied": {
+      if (op === "delete") {
+        await collection.deleteOne({ _id: id });
+      } else {
+        const responseDocument = result.document;
+        const canonical = {
+          ...responseDocument && Object.keys(responseDocument).length > 0 ? responseDocument : withoutEnvelope(current),
+          _id: id
+        };
+        await applyCanonical(collection, current, canonical, now());
+      }
+      stats.synced++;
+      return;
+    }
+    case "retry":
+      await defer(collection, id, doc, stats, now, random);
+      return;
+    case "terminal":
+      await collection.updateOne(
+        { _id: id },
+        {
+          $set: {
+            _sync: "failed",
+            _error: `The server rejected this ${op} with status ${result.status}.`
+          }
+        }
+      );
+      stats.failed++;
+  }
+}
+async function defer(collection, id, doc, stats, now, random) {
+  const attempt = (doc._attempt ?? 0) + 1;
+  await collection.updateOne(
+    { _id: id },
+    { $set: { _attempt: attempt, _retry_at: now() + backoffMs(attempt, random) } }
+  );
+  stats.deferred++;
+}
+function routeFor(doc, collection, id, op, fallback) {
+  const template = doc._endpoint;
+  if (template === void 0) {
+    if (fallback === null) return null;
+    const candidate = fallback.url(toPendingWrite(collection, id, op, withoutEnvelope(doc)));
+    return candidate === "" ? null : { ...fallback, url: () => candidate };
+  }
+  const url = resolveUrl(template, collection, id, op);
+  const method = doc._method ?? fallback?.method[op] ?? "POST";
+  return {
+    url: () => url,
+    method: { insert: method, update: method, delete: method },
+    headers: fallback?.headers,
+    classify: fallback?.classify ?? defaultClassify,
+    fetch: fallback?.fetch
+  };
+}
+
+// src/query/keys.ts
+var import_taladb = require("taladb");
+var QUERY_COLLECTION = "taladb_queries";
+function hashQueryKey(key) {
+  return JSON.stringify(key, (_field, value) => normalise(value));
+}
+function normalise(value) {
+  if (value === void 0) return UNDEFINED_MARKER;
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "function" || typeof value === "symbol") {
+      throw new TypeError(
+        `A query key may not contain a ${typeof value}. Keys must be JSON-shaped (primitives, arrays, plain objects) so that equal keys hash identically.`
+      );
+    }
+    return value;
+  }
+  if (!isPlainObject(value)) return value;
+  const sorted = {};
+  for (const field of Object.keys(value).sort()) {
+    sorted[field] = value[field];
+  }
+  return sorted;
+}
+var UNDEFINED_MARKER = "\0undefined";
+function isPlainObject(value) {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function queryRecordId(collection, key, hash = hashQueryKey) {
+  return (0, import_taladb.deriveDocId)(QUERY_COLLECTION, `${collection}\0${hash(key)}`);
+}
+function newDocId(collection) {
+  return (0, import_taladb.deriveDocId)(collection, globalThis.crypto.randomUUID());
+}
+
+// src/query/queries.ts
+async function ensureEnvelopeIndexes(collection) {
+  for (const field of ENVELOPE_INDEXES) {
+    await collection.createIndex(field);
+  }
+}
+async function openQueryCollection(db) {
+  const collection = db.collection(QUERY_COLLECTION);
+  await collection.createIndex("collection");
+  return collection;
+}
+async function readQueryRecord(queries, collection, key, hash) {
+  return queries.findOne({ _id: queryRecordId(collection, key, hash) });
+}
+async function deleteQueryRecord(queries, collection, key, hash) {
+  await queries.deleteOne({ _id: queryRecordId(collection, key, hash) });
+}
+async function writeQueryRecord(queries, collection, key, ids, now, ttl, shape2 = "array", payload, hash = hashQueryKey) {
+  const record = {
+    _id: queryRecordId(collection, key, hash),
+    collection,
+    key: hash(key),
+    ids,
+    fetchedAt: now,
+    ttl,
+    shape: shape2,
+    ...payload === void 0 ? {} : { payload }
+  };
+  const replaced = await queries.updateOne(
+    { _id: record._id },
+    {
+      $set: {
+        ids,
+        fetchedAt: now,
+        ttl,
+        collection,
+        key: record.key,
+        shape: shape2,
+        // Written unconditionally so a query that stops returning an envelope
+        // does not keep serving the previous response's `total` forever.
+        payload: payload ?? null
+      }
+    }
+  );
+  if (!replaced) await queries.insert(record);
+  return record;
+}
+function isStale(record, now) {
+  return now >= record.fetchedAt + record.ttl;
+}
+
+// src/query/context.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var QueryContext = (0, import_react2.createContext)(null);
+function useQueryContext() {
+  const value = (0, import_react2.useContext)(QueryContext);
+  if (value === null) {
+    throw new Error(
+      "A @taladb/react/query hook was used outside <QueryProvider>. Wrap the tree in <TalaDBProvider><QueryProvider \u2026>\u2026</QueryProvider></TalaDBProvider>."
+    );
+  }
+  return value;
+}
+function QueryProvider({
+  children,
+  headers,
+  classify,
+  fetch,
+  drain,
+  resolveCollection,
+  defaultOptions
+}) {
+  const db = useTalaDB();
+  const [queries, setQueries] = (0, import_react2.useState)(null);
+  const liveRef = (0, import_react2.useRef)(true);
+  (0, import_react2.useEffect)(() => {
+    liveRef.current = true;
+    let cancelled = false;
+    void openQueryCollection(db).then((collection) => {
+      if (!cancelled) setQueries(collection);
+    }).catch((error) => {
+      console.error("[@taladb/react/query] Failed to open the query-record collection.", error);
+    });
+    return () => {
+      cancelled = true;
+      liveRef.current = false;
+    };
+  }, [db]);
+  const backend = (0, import_react2.useMemo)(
+    () => ({
+      url: () => "",
+      method: DEFAULT_METHODS,
+      headers,
+      classify: classify ?? defaultClassify,
+      fetch
+    }),
+    [headers, classify, fetch]
+  );
+  const defaults = defaultOptions?.queries;
+  const policy = drain?.policy ?? "auto";
+  const intervalMs = drain?.intervalMs;
+  const batch = drain?.batch;
+  const flushAt = drain?.flushAt ?? 100;
+  const flushOnHide = drain?.flushOnHide ?? true;
+  const managedRef = (0, import_react2.useRef)(/* @__PURE__ */ new Set());
+  const [collections, setCollections] = (0, import_react2.useState)([]);
+  const register = (0, import_react2.useCallback)((collection) => {
+    if (managedRef.current.has(collection)) return;
+    managedRef.current.add(collection);
+    setCollections([...managedRef.current]);
+  }, []);
+  const runningRef = (0, import_react2.useRef)(false);
+  const queuedSinceDrainRef = (0, import_react2.useRef)(0);
+  const [draining, setDraining] = (0, import_react2.useState)(false);
+  const runDrain = (0, import_react2.useCallback)(async (keepalive = false) => {
+    if (runningRef.current) return;
+    if (managedRef.current.size === 0) return;
+    runningRef.current = true;
+    queuedSinceDrainRef.current = 0;
+    setDraining(true);
+    try {
+      await drainOnce({
+        db,
+        backend,
+        collections: () => [...managedRef.current],
+        batch,
+        keepalive
+      });
+    } catch (error) {
+      console.error("[@taladb/react/query] Drain cycle failed.", error);
+    } finally {
+      runningRef.current = false;
+      setDraining(false);
+    }
+  }, [db, backend, batch]);
+  const requestDrain = (0, import_react2.useCallback)(
+    (force = false) => {
+      queuedSinceDrainRef.current += 1;
+      const overThreshold = flushAt !== false && queuedSinceDrainRef.current >= flushAt;
+      if (!force && !overThreshold) {
+        if (policy === "manual") return;
+        if (policy === "interval") return;
+        if (policy === "online-only" && typeof navigator !== "undefined" && !navigator.onLine) {
+          return;
+        }
+      }
+      if (overThreshold && !force && policy === "manual") return;
+      void runDrain();
+    },
+    [policy, flushAt, runDrain]
+  );
+  const noteWrite = (0, import_react2.useCallback)(() => {
+    queuedSinceDrainRef.current += 1;
+    if (flushAt === false || queuedSinceDrainRef.current < flushAt) return;
+    if (policy === "manual") return;
+    if (typeof navigator !== "undefined" && navigator.onLine === false) return;
+    void runDrain();
+  }, [flushAt, policy, runDrain]);
+  (0, import_react2.useEffect)(() => {
+    if (policy === "manual" || typeof window === "undefined") return;
+    const onOnline = () => void runDrain();
+    window.addEventListener("online", onOnline);
+    return () => window.removeEventListener("online", onOnline);
+  }, [policy, runDrain]);
+  (0, import_react2.useEffect)(() => {
+    if (policy !== "interval") return;
+    const id = setInterval(() => void runDrain(), intervalMs ?? 3e4);
+    return () => clearInterval(id);
+  }, [policy, intervalMs, runDrain]);
+  (0, import_react2.useEffect)(() => {
+    if (!flushOnHide || policy === "manual" || typeof window === "undefined") return;
+    const onHidden = () => {
+      if (typeof document !== "undefined" && document.visibilityState !== "hidden") return;
+      void runDrain();
+    };
+    const onPageHide = () => void runDrain(true);
+    document.addEventListener("visibilitychange", onHidden);
+    window.addEventListener("pagehide", onPageHide);
+    return () => {
+      document.removeEventListener("visibilitychange", onHidden);
+      window.removeEventListener("pagehide", onPageHide);
+    };
+  }, [flushOnHide, policy, runDrain]);
+  const value = (0, import_react2.useMemo)(
+    () => ({
+      queries,
+      backend,
+      drain: { policy, intervalMs, batch, flushAt, flushOnHide },
+      resolveCollection,
+      defaults,
+      register,
+      collections,
+      draining,
+      requestDrain,
+      noteWrite
+    }),
+    // Spread by field: an inline `drain={{…}}` object would otherwise produce a
+    // new context value on every render and re-run every consumer's effects.
+    [
+      queries,
+      backend,
+      policy,
+      intervalMs,
+      batch,
+      flushAt,
+      flushOnHide,
+      resolveCollection,
+      defaults,
+      register,
+      collections,
+      draining,
+      requestDrain,
+      noteWrite
+    ]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(QueryContext.Provider, { value, children });
+}
+
+// src/query/useQuery.ts
+var import_react5 = require("react");
+
+// src/useCollection.ts
+var import_react3 = require("react");
+function useCollection(name, options) {
+  const db = useTalaDB();
+  const registry = useCollectionOptions();
+  const explicit = (0, import_react3.useRef)(options);
+  explicit.current = options;
+  return (0, import_react3.useMemo)(
+    () => db.collection(name, explicit.current ?? registry.get(name)),
+    [db, name, registry]
+  );
+}
+
+// src/useFind.ts
+var import_react4 = require("react");
+function useFind(collection, filter) {
+  const snapshotRef = (0, import_react4.useRef)({ data: [], loading: true, error: null });
+  const filterKey = JSON.stringify(filter ?? null);
+  const subscribe = (0, import_react4.useCallback)(
+    (notify) => {
+      snapshotRef.current = { data: snapshotRef.current.data, loading: true, error: null };
+      return collection.subscribe(filter ?? {}, (docs) => {
+        snapshotRef.current = { data: docs, loading: false, error: null };
+        notify();
+      }, (error) => {
+        snapshotRef.current = { ...snapshotRef.current, loading: false, error };
+        notify();
+      });
+    },
+    // filterKey captures the serialised filter; collection is the identity dep.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [collection, filterKey]
+  );
+  const getSnapshot = (0, import_react4.useCallback)(() => snapshotRef.current, []);
+  return (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+}
+
+// src/query/dev.ts
+var seen = /* @__PURE__ */ new Set();
+function isDev2() {
+  return typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+}
+function warnOnce(key, message) {
+  if (!isDev2() || seen.has(key)) return;
+  seen.add(key);
+  console.warn(`[@taladb/react/query] ${message}`);
+}
+function resetWarnings() {
+  seen.clear();
+}
+var IGNORED = {
+  notifyOnChangeProps: "is not implemented. It is a render optimisation with no effect on correctness; every result field is computed either way.",
+  structuralSharing: "is always on and cannot be disabled. Turning it off would make `data` a new reference on every database snapshot, and a live query produces those far more often than a polling cache does."
+};
+function noteIgnoredOptions(options) {
+  if (!isDev2()) return;
+  for (const [option, explanation] of Object.entries(IGNORED)) {
+    if (options[option] === void 0) continue;
+    warnOnce(`ignored:${option}`, `\`${option}\` ${explanation}`);
+  }
+}
+
+// src/query/collection.ts
+function resolveCollectionName({
+  collection,
+  queryKey,
+  resolve,
+  registered
+}) {
+  if (collection !== void 0) return collection;
+  const resolved = resolve?.(queryKey);
+  const inferred = resolved ?? (typeof queryKey[0] === "string" ? queryKey[0] : void 0);
+  if (inferred === void 0 || inferred === "") {
+    throw new Error(
+      `${describe(queryKey)} has no collection: its first key segment is not a string, so there is nothing to infer from. Pass \`collection: '\u2026'\` on the query, or a \`resolveCollection\` function to <QueryProvider>.`
+    );
+  }
+  if (registered.length === 0) {
+    warnOnce(
+      inferred,
+      `${describe(queryKey)} is storing documents in the '${inferred}' collection, inferred from its first key segment. No collections are registered on <TalaDBProvider>, so this could not be checked \u2014 register them to get schema validation and a real error on a typo.`
+    );
+    return inferred;
+  }
+  if (!registered.includes(inferred)) {
+    throw new Error(
+      `${describe(queryKey)} would store documents in a '${inferred}' collection, inferred from its first key segment, but the registered collections are: ${registered.join(", ")}. Either pass \`collection\` explicitly, or give <QueryProvider> a \`resolveCollection\` function if your query keys do not start with the collection name.`
+    );
+  }
+  return inferred;
+}
+function describe(queryKey) {
+  let rendered;
+  try {
+    rendered = JSON.stringify(queryKey);
+  } catch {
+    rendered = "[unserialisable key]";
+  }
+  return `useQuery(${rendered})`;
+}
+
+// src/query/hydrate.ts
+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 unique = /* @__PURE__ */ new Map();
+  for (const doc of docs) {
+    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) {
+    state.set(doc._id, doc);
+  }
+  const fresh = [];
+  let updated = 0;
+  let skipped = 0;
+  for (const doc of deduped) {
+    const id = doc._id;
+    if (!state.has(id)) {
+      fresh.push(stampSynced(doc, now));
+      continue;
+    }
+    const current = state.get(id);
+    const syncState = current._sync;
+    if (syncState !== void 0 && syncState !== "synced") {
+      skipped++;
+      continue;
+    }
+    await applyCanonical(collection, current, doc, now);
+    updated++;
+  }
+  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;
+  console.warn(
+    `[@taladb/react/query] A server response carried reserved field(s) ${reserved.join(", ")} on document ` + String(doc._id) + ". These belong to the sync envelope; the response will overwrite them and the document can fall out of the pending queue. Rename the field(s) on the server."
+  );
+}
+
+// src/query/shape.ts
+function extractDocuments({
+  raw,
+  collection,
+  queryKey,
+  documents
+}) {
+  if (documents !== void 0) {
+    const extracted = documents(raw);
+    if (!Array.isArray(extracted)) {
+      throw new Error(
+        `${describe2(queryKey)}: \`documents\` must return an array of documents, but returned ${typeName(extracted)}. It selects the part of the response that is stored in the '${collection}' collection.`
+      );
+    }
+    return { documents: extracted, shape: "envelope" };
+  }
+  if (Array.isArray(raw)) return { documents: raw, shape: "array" };
+  if (isDocumentLike(raw)) return { documents: [raw], shape: "document" };
+  throw new Error(
+    `${describe2(queryKey)}: \`queryFn\` returned ${typeName(raw)}, which is neither a document nor a list of documents.
+
+Unlike TanStack Query, \`data\` here is resolved from the '` + collection + "' collection rather than from the response, so the response has to say which part of itself is documents. For an envelope like `{ items, total }`, add:\n\n  documents: (raw) => raw.items,\n  assemble:  (docs, raw) => ({ ...raw, items: docs }),\n\nA document is an object with a string `_id`. If yours uses a different identifier, map it in `queryFn` before returning."
+  );
+}
+function isDocumentLike(raw) {
+  return typeof raw === "object" && raw !== null && !Array.isArray(raw) && typeof raw._id === "string";
+}
+function typeName(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  if (typeof value === "object") {
+    const keys = Object.keys(value);
+    const shown = keys.slice(0, 4).join(", ");
+    return keys.length === 0 ? "an empty object" : `an object with keys { ${shown}${keys.length > 4 ? ", \u2026" : ""} }`;
+  }
+  return `a ${typeof value}`;
+}
+function describe2(queryKey) {
+  let rendered;
+  try {
+    rendered = JSON.stringify(queryKey);
+  } catch {
+    rendered = "[unserialisable key]";
+  }
+  return `useQuery(${rendered})`;
+}
+
+// src/query/inflight.ts
+var inflight = /* @__PURE__ */ new Map();
+function inflightKey(collection, keyHash) {
+  return `${collection}\0${keyHash}`;
+}
+function runShared(key, work, callerSignal) {
+  let entry = inflight.get(key);
+  if (entry === void 0) {
+    const controller = new AbortController();
+    const created = { controller, waiters: 0, promise: void 0 };
+    created.promise = work(controller.signal).finally(() => {
+      if (inflight.get(key) === created) inflight.delete(key);
+    });
+    inflight.set(key, created);
+    entry = created;
+  }
+  const joined = entry;
+  joined.waiters += 1;
+  let left = false;
+  const leave = () => {
+    if (left) return;
+    left = true;
+    joined.waiters -= 1;
+    if (joined.waiters === 0) joined.controller.abort();
+  };
+  callerSignal.addEventListener("abort", leave, { once: true });
+  return joined.promise.finally(() => {
+    if (!left) {
+      left = true;
+      joined.waiters -= 1;
+    }
+    callerSignal.removeEventListener("abort", leave);
+  });
+}
+function cancelShared(key) {
+  const entry = inflight.get(key);
+  if (entry === void 0) return;
+  inflight.delete(key);
+  entry.controller.abort();
+}
+function isShared(key) {
+  return inflight.has(key);
+}
+function resetInflight() {
+  for (const entry of inflight.values()) entry.controller.abort();
+  inflight.clear();
+}
+
+// src/query/params.ts
+var predicate = (field, op) => ({
+  kind: "predicate",
+  field,
+  op
+});
+var eq = (field) => predicate(field, "$eq");
+var ne = (field) => predicate(field, "$ne");
+var gte = (field) => predicate(field, "$gte");
+var lte = (field) => predicate(field, "$lte");
+var gt = (field) => predicate(field, "$gt");
+var lt = (field) => predicate(field, "$lt");
+var contains = (field) => predicate(field, "$contains");
+var oneOf = (field) => predicate(field, "$in");
+var shape = () => ({ kind: "shape" });
+function defineParams(spec) {
+  return (values) => bindParams(spec, values);
+}
+function isBoundParams(value) {
+  return typeof value === "object" && value !== null && typeof value.toFilter === "function";
+}
+function normalizeParams(params) {
+  if (params === void 0) return void 0;
+  if (isBoundParams(params)) return params;
+  return bindParams({}, params);
+}
+function bindParams(spec, values) {
+  return {
+    values,
+    toSearchParams: () => {
+      const search = new URLSearchParams();
+      for (const [name, value] of Object.entries(values)) {
+        if (value === void 0 || value === null) continue;
+        if (Array.isArray(value)) {
+          if (value.length > 0) search.set(name, value.join(","));
+          continue;
+        }
+        search.set(name, String(value));
+      }
+      return search;
+    },
+    toFilter: () => buildFilter(spec, values),
+    shapeParams: () => Object.keys(values).filter(
+      (name) => spec[name]?.kind === "shape" && values[name] !== void 0
+    )
+  };
+}
+function buildFilter(spec, values) {
+  const clauses = [];
+  for (const [name, value] of Object.entries(values)) {
+    if (value === void 0 || value === null) continue;
+    const declared = spec[name];
+    if (declared === void 0 || declared.kind !== "predicate") continue;
+    if (declared.field === void 0 || declared.op === void 0) continue;
+    if (Array.isArray(value) && value.length === 0) continue;
+    clauses.push({
+      [declared.field]: declared.op === "$eq" ? value : { [declared.op]: value }
+    });
+  }
+  if (clauses.length === 0) return void 0;
+  if (clauses.length === 1) return clauses[0];
+  return { $and: clauses };
+}
+
+// src/query/retry.ts
+var DEFAULT_RETRY = 3;
+function shouldRetry(retry, failureCount, error) {
+  const setting = retry ?? DEFAULT_RETRY;
+  if (typeof setting === "function") return setting(failureCount, error);
+  if (typeof setting === "boolean") return setting;
+  return failureCount <= setting;
+}
+function retryDelayMs(retryDelay, attemptIndex, error) {
+  if (typeof retryDelay === "number") return retryDelay;
+  if (typeof retryDelay === "function") return retryDelay(attemptIndex, error);
+  return Math.min(1e3 * 2 ** attemptIndex, 3e4);
+}
+function sleep(ms, signal) {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      resolve();
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function isOffline() {
+  return typeof navigator !== "undefined" && navigator.onLine === false;
+}
+
+// src/query/structural.ts
+function replaceEqualDeep(previous, next) {
+  if (previous === next) return next;
+  const bothArrays = Array.isArray(previous) && Array.isArray(next);
+  if (bothArrays || isPlainObject2(previous) && isPlainObject2(next)) {
+    const previousItems = previous;
+    const nextItems = next;
+    const previousKeys = Object.keys(previousItems);
+    const nextKeys = Object.keys(nextItems);
+    let equal = previousKeys.length === nextKeys.length;
+    const merged = bothArrays ? [] : {};
+    for (const key of nextKeys) {
+      const child = replaceEqualDeep(previousItems[key], nextItems[key]);
+      if (equal && child !== previousItems[key]) equal = false;
+      merged[key] = child;
+    }
+    return equal ? previous : merged;
+  }
+  return next;
+}
+function isPlainObject2(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+// src/query/useQuery.ts
+var MATCH_NONE = { _id: { $in: [] } };
+var DEFAULT_STALE_TIME = 60 * 6e4;
+var INITIAL = {
+  ids: null,
+  shape: "array",
+  payload: void 0,
+  error: null,
+  fetchStatus: "idle",
+  dataUpdatedAt: 0,
+  errorUpdatedAt: 0,
+  failureCount: 0,
+  failureReason: null,
+  errorUpdateCount: 0,
+  isFetched: false,
+  isFetchedAfterMount: false,
+  fromCollection: false
+};
+function isAbort(cause) {
+  return cause instanceof Error && cause.name === "AbortError";
+}
+function toError(cause) {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+function keepPreviousData(previous) {
+  return previous;
+}
+function resolvePlaceholder(options, previous) {
+  const placeholder = options.placeholderData;
+  if (placeholder === void 0) return void 0;
+  return typeof placeholder === "function" ? placeholder(previous) : placeholder;
+}
+function buildResult(common, data, error) {
+  if (error !== null) {
+    return data === void 0 ? {
+      ...common,
+      status: "error",
+      data: void 0,
+      error,
+      isPending: false,
+      isSuccess: false,
+      isError: true,
+      isLoadingError: true,
+      isRefetchError: false
+    } : {
+      ...common,
+      status: "error",
+      data,
+      error,
+      isPending: false,
+      isSuccess: false,
+      isError: true,
+      isLoadingError: false,
+      isRefetchError: true
+    };
+  }
+  if (data === void 0) {
+    return {
+      ...common,
+      status: "pending",
+      data: void 0,
+      error: null,
+      isPending: true,
+      isSuccess: false,
+      isError: false,
+      isLoadingError: false,
+      isRefetchError: false
+    };
+  }
+  return {
+    ...common,
+    status: "success",
+    data,
+    error: null,
+    isPending: false,
+    isSuccess: true,
+    isError: false,
+    isLoadingError: false,
+    isRefetchError: false
+  };
+}
+function useQuery(options) {
+  const { queryKey, meta } = options;
+  const enabled = typeof options.enabled === "function" ? options.enabled() : options.enabled ?? true;
+  const { queries, register, resolveCollection, defaults } = useQueryContext();
+  const staleTime = options.staleTime ?? defaults?.staleTime ?? DEFAULT_STALE_TIME;
+  const retry = options.retry ?? defaults?.retry;
+  const retryDelay = options.retryDelay ?? defaults?.retryDelay;
+  const networkMode = options.networkMode ?? defaults?.networkMode;
+  const refetchOnMount = options.refetchOnMount ?? defaults?.refetchOnMount;
+  const refetchOnWindowFocus = options.refetchOnWindowFocus ?? defaults?.refetchOnWindowFocus;
+  const refetchOnReconnect = options.refetchOnReconnect ?? defaults?.refetchOnReconnect;
+  const refetchIntervalOption = options.refetchInterval ?? defaults?.refetchInterval;
+  const refetchInterval = typeof refetchIntervalOption === "function" ? refetchIntervalOption() : refetchIntervalOption;
+  const refetchIntervalInBackground = options.refetchIntervalInBackground ?? defaults?.refetchIntervalInBackground ?? false;
+  const throwOnError = options.throwOnError ?? defaults?.throwOnError ?? false;
+  const forgetAfter = options.forgetAfter ?? defaults?.forgetAfter ?? Number.POSITIVE_INFINITY;
+  const hashFn = options.queryKeyHashFn ?? hashQueryKey;
+  noteIgnoredOptions(options);
+  const registry = useCollectionOptions();
+  const params = (0, import_react5.useMemo)(
+    () => normalizeParams(options.params),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(options.params === void 0 ? null : options.params.values ?? options.params)]
+  );
+  const effectiveKey = (0, import_react5.useMemo)(
+    () => params === void 0 ? queryKey : [...queryKey, params.values],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [hashFn(queryKey), params]
+  );
+  const keyHash = hashFn(effectiveKey);
+  const name = (0, import_react5.useMemo)(
+    () => resolveCollectionName({
+      collection: options.collection,
+      // The caller's key, not the parameter-extended one: the collection is
+      // named by what they wrote, and appending values must not change it.
+      queryKey,
+      resolve: resolveCollection,
+      registered: registry.names()
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [options.collection, keyHash, resolveCollection, registry]
+  );
+  const collection = useCollection(name);
+  const [state, setState] = (0, import_react5.useState)(() => ({
+    ...INITIAL,
+    fetchStatus: enabled ? "fetching" : "idle"
+  }));
+  const offline = options.offline ?? "strict";
+  const [renderedKey, setRenderedKey] = (0, import_react5.useState)(keyHash);
+  const previousDataRef = (0, import_react5.useRef)(void 0);
+  if (renderedKey !== keyHash) {
+    setRenderedKey(keyHash);
+    setState({ ...INITIAL, fetchStatus: enabled ? "fetching" : "idle" });
+  }
+  const queryFnRef = (0, import_react5.useRef)(options.queryFn);
+  queryFnRef.current = options.queryFn;
+  const staleTimeRef = (0, import_react5.useRef)(staleTime);
+  staleTimeRef.current = staleTime;
+  const metaRef = (0, import_react5.useRef)(meta);
+  metaRef.current = meta;
+  const documentsRef = (0, import_react5.useRef)(options.documents);
+  documentsRef.current = options.documents;
+  const assembleRef = (0, import_react5.useRef)(options.assemble);
+  assembleRef.current = options.assemble;
+  const initialDataRef = (0, import_react5.useRef)(options.initialData);
+  initialDataRef.current = options.initialData;
+  const initialDataUpdatedAtRef = (0, import_react5.useRef)(options.initialDataUpdatedAt);
+  initialDataUpdatedAtRef.current = options.initialDataUpdatedAt;
+  const retryRef = (0, import_react5.useRef)(retry);
+  retryRef.current = retry;
+  const retryDelayRef = (0, import_react5.useRef)(retryDelay);
+  retryDelayRef.current = retryDelay;
+  const networkModeRef = (0, import_react5.useRef)(networkMode);
+  networkModeRef.current = networkMode;
+  const enabledRef = (0, import_react5.useRef)(enabled);
+  enabledRef.current = enabled;
+  const hashRef = (0, import_react5.useRef)(hashFn);
+  hashRef.current = hashFn;
+  const forgetAfterRef = (0, import_react5.useRef)(forgetAfter);
+  forgetAfterRef.current = forgetAfter;
+  const paramsRef = (0, import_react5.useRef)(params);
+  paramsRef.current = params;
+  const stateRef = (0, import_react5.useRef)(state);
+  stateRef.current = state;
+  (0, import_react5.useEffect)(() => {
+    register(name);
+  }, [register, name]);
+  const refetchControllersRef = (0, import_react5.useRef)(/* @__PURE__ */ new Set());
+  const resolversRef = (0, import_react5.useRef)([]);
+  const foundRef = (0, import_react5.useRef)(void 0);
+  const mountedRef = (0, import_react5.useRef)(true);
+  (0, import_react5.useEffect)(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      for (const controller of refetchControllersRef.current) controller.abort();
+      refetchControllersRef.current.clear();
+      const waiting = resolversRef.current;
+      resolversRef.current = [];
+      for (const { resolve } of waiting) resolve(resultRef.current);
+    };
+  }, []);
+  const nextResult = (0, import_react5.useCallback)(() => {
+    if (!mountedRef.current) return Promise.resolve(resultRef.current);
+    return new Promise((resolve) => {
+      const entry = { resolve, snapshot: foundRef.current };
+      resolversRef.current.push(entry);
+      setTimeout(() => {
+        const index = resolversRef.current.indexOf(entry);
+        if (index === -1) return;
+        resolversRef.current.splice(index, 1);
+        resolve(resultRef.current);
+      }, 50);
+    });
+  }, []);
+  (0, import_react5.useEffect)(() => {
+    cancelForget(name, keyHash);
+    return () => {
+      const after = forgetAfterRef.current;
+      if (!Number.isFinite(after) || queries === null) return;
+      scheduleForget(name, keyHash, after, () => {
+        void deleteQueryRecord(queries, name, effectiveKey, hashRef.current).catch(() => {
+        });
+      });
+    };
+  }, [queries, name, keyHash]);
+  const patch = (0, import_react5.useCallback)((next) => {
+    if (mountedRef.current) setState((current) => ({ ...current, ...next }));
+  }, []);
+  const commit = (0, import_react5.useCallback)(
+    async (raw, fetchedAt) => {
+      const { documents: docs, shape: shape3 } = extractDocuments({
+        raw,
+        collection: name,
+        queryKey: effectiveKey,
+        documents: documentsRef.current
+      });
+      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(
+        queries,
+        name,
+        effectiveKey,
+        nextIds,
+        fetchedAt,
+        staleTimeRef.current,
+        shape3,
+        payload2,
+        hashRef.current
+      );
+      return {
+        ids: nextIds,
+        shape: shape3,
+        payload: payload2,
+        error: null,
+        fetchStatus: "idle",
+        dataUpdatedAt: fetchedAt,
+        failureCount: 0,
+        failureReason: null,
+        isFetched: true,
+        fromCollection: false
+      };
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queries, collection, name, keyHash]
+  );
+  const attemptFetch = (0, import_react5.useCallback)(
+    async (signal) => {
+      let failures = 0;
+      for (; ; ) {
+        try {
+          return await queryFnRef.current({
+            queryKey: effectiveKey,
+            signal,
+            meta: metaRef.current,
+            params: paramsRef.current
+          });
+        } catch (cause) {
+          if (signal.aborted) throw cause;
+          const error = toError(cause);
+          failures += 1;
+          patch({ failureCount: failures, failureReason: error });
+          if (!shouldRetry(retryRef.current, failures, error)) throw error;
+          await sleep(retryDelayMs(retryDelayRef.current, failures - 1, error), signal);
+          if (signal.aborted) throw error;
+        }
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [keyHash, patch]
+  );
+  const revalidate = (0, import_react5.useCallback)(
+    async (signal) => {
+      if (queries === null) return;
+      if (networkModeRef.current !== "always" && isOffline()) {
+        patch({ fetchStatus: "paused" });
+        return;
+      }
+      patch({ fetchStatus: "fetching" });
+      try {
+        const committed = await runShared(
+          inflightKey(name, keyHash),
+          async (sharedSignal) => {
+            const raw = await attemptFetch(sharedSignal);
+            return commit(raw, Date.now());
+          },
+          signal
+        );
+        if (signal.aborted) return;
+        patch({ ...committed, isFetchedAfterMount: true });
+      } catch (cause) {
+        if (signal.aborted) return;
+        if (isAbort(cause)) {
+          patch({ fetchStatus: "idle" });
+          return;
+        }
+        const error = toError(cause);
+        setState((current) => ({
+          ...current,
+          error,
+          fetchStatus: "idle",
+          errorUpdatedAt: Date.now(),
+          // `attemptFetch` already counted each network failure. A shape error
+          // never reached it, so this floors the count at one.
+          failureCount: Math.max(current.failureCount, 1),
+          failureReason: error,
+          errorUpdateCount: current.errorUpdateCount + 1,
+          isFetched: true
+        }));
+        throw error;
+      }
+    },
+    // `queryKey` is covered by keyHash; including the array itself would defeat it.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queries, collection, name, keyHash, attemptFetch, commit, patch]
+  );
+  const refetchIfAllowed = (0, import_react5.useCallback)(
+    (trigger) => {
+      const setting = trigger ?? true;
+      if (setting === false || !enabledRef.current) return;
+      const { dataUpdatedAt } = stateRef.current;
+      const stale = dataUpdatedAt === 0 || Date.now() >= dataUpdatedAt + staleTimeRef.current;
+      if (setting !== "always" && !stale) return;
+      const controller = new AbortController();
+      void revalidate(controller.signal).catch(() => {
+      });
+    },
+    [revalidate]
+  );
+  (0, import_react5.useEffect)(() => {
+    if (queries === null) return;
+    const controller = new AbortController();
+    void (async () => {
+      try {
+        await ensureEnvelopeIndexes(collection);
+        const record = await readQueryRecord(queries, name, effectiveKey, hashRef.current);
+        if (controller.signal.aborted) return;
+        if (record !== null) {
+          patch({
+            ids: record.ids,
+            // Restored, not re-derived: a detail view whose response was one
+            // document must not come back as a one-element array on reload.
+            shape: record.shape ?? "array",
+            payload: record.payload ?? void 0,
+            dataUpdatedAt: record.fetchedAt,
+            isFetched: true
+          });
+          const onMount = refetchOnMount ?? true;
+          const staleEnough = onMount === "always" || record.fetchedAt === 0 || Date.now() >= record.fetchedAt + staleTimeRef.current;
+          if (!enabled || onMount === false || !staleEnough) {
+            patch({ fetchStatus: "idle" });
+            return;
+          }
+        } else {
+          const seed = initialDataRef.current;
+          if (seed !== void 0) {
+            const raw = typeof seed === "function" ? seed() : seed;
+            const seededAt = initialDataUpdatedAtRef.current ?? Date.now();
+            const committed = await commit(raw, seededAt);
+            if (controller.signal.aborted) return;
+            patch(committed);
+            if (!enabled || Date.now() < seededAt + staleTimeRef.current) {
+              patch({ fetchStatus: "idle" });
+              return;
+            }
+          } else if (!enabled) {
+            patch({ fetchStatus: "idle" });
+            return;
+          }
+        }
+        await revalidate(controller.signal);
+      } catch {
+        if (offline === "collection" && stateRef.current.ids === null) {
+          const filter2 = paramsRef.current?.toFilter();
+          if (filter2 !== void 0 && !controller.signal.aborted) {
+            const shapeParams = paramsRef.current?.shapeParams() ?? [];
+            if (shapeParams.length > 0) {
+              warnOnce(
+                `offline-shape:${name}`,
+                `useQuery on '${name}' fell back to the whole collection while offline, but its parameters include ${shapeParams.join(", ")}, which only the server can honour. There is no page 2 of a local query \u2014 expect more results than the request would have returned.`
+              );
+            }
+            patch({ fromCollection: true, isFetched: true });
+          }
+        }
+        patch({ fetchStatus: "idle" });
+      }
+    })();
+    return () => controller.abort();
+  }, [enabled, refetchOnMount, offline, queries, collection, name, keyHash, revalidate, commit, patch]);
+  (0, import_react5.useEffect)(() => {
+    if (typeof window === "undefined" || refetchOnWindowFocus === false) return;
+    const onFocus = () => {
+      if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
+      refetchIfAllowed(refetchOnWindowFocus);
+    };
+    window.addEventListener("visibilitychange", onFocus);
+    window.addEventListener("focus", onFocus);
+    return () => {
+      window.removeEventListener("visibilitychange", onFocus);
+      window.removeEventListener("focus", onFocus);
+    };
+  }, [refetchOnWindowFocus, refetchIfAllowed]);
+  (0, import_react5.useEffect)(() => {
+    if (typeof window === "undefined" || refetchOnReconnect === false) return;
+    const onOnline = () => refetchIfAllowed(refetchOnReconnect);
+    window.addEventListener("online", onOnline);
+    return () => window.removeEventListener("online", onOnline);
+  }, [refetchOnReconnect, refetchIfAllowed]);
+  (0, import_react5.useEffect)(() => {
+    if (!refetchInterval || !enabled) return;
+    const timer = setInterval(() => {
+      if (!refetchIntervalInBackground && typeof document !== "undefined" && document.visibilityState === "hidden") {
+        return;
+      }
+      refetchIfAllowed("always");
+    }, refetchInterval);
+    return () => clearInterval(timer);
+  }, [refetchInterval, refetchIntervalInBackground, enabled, refetchIfAllowed]);
+  const [, forceStaleCheck] = (0, import_react5.useState)(0);
+  (0, import_react5.useEffect)(() => {
+    if (state.dataUpdatedAt === 0 || !Number.isFinite(staleTime)) return;
+    const staleAt = state.dataUpdatedAt + staleTime;
+    if (Date.now() >= staleAt) return;
+    let timer;
+    const check = () => {
+      const remaining = staleAt - Date.now();
+      if (remaining > 0) {
+        timer = setTimeout(check, remaining);
+        return;
+      }
+      forceStaleCheck((n) => n + 1);
+    };
+    timer = setTimeout(check, staleAt - Date.now());
+    return () => clearTimeout(timer);
+  }, [state.dataUpdatedAt, staleTime]);
+  const ids = state.ids;
+  const { where } = options;
+  const whereHash = where === void 0 ? "" : JSON.stringify(where);
+  const { fromCollection } = state;
+  const filter = (0, import_react5.useMemo)(() => {
+    const clauses = [];
+    if (fromCollection) {
+      const params2 = paramsRef.current?.toFilter();
+      if (params2 !== void 0) clauses.push(params2);
+    } else {
+      if (ids === null || ids.length === 0) return MATCH_NONE;
+      clauses.push({ _id: { $in: ids } });
+      const params2 = paramsRef.current?.toFilter();
+      if (params2 !== void 0) clauses.push(params2);
+    }
+    if (where !== void 0) clauses.push(where);
+    if (clauses.length === 0) return MATCH_NONE;
+    if (clauses.length === 1) return clauses[0];
+    return { $and: clauses };
+  }, [ids, whereHash, fromCollection, keyHash]);
+  const { data: found } = useFind(collection, filter);
+  const documents = (0, import_react5.useMemo)(() => {
+    if (fromCollection) {
+      return found.filter((doc) => doc._op !== "delete");
+    }
+    if (ids === null) return void 0;
+    const byId = /* @__PURE__ */ new Map();
+    for (const doc of found) byId.set(doc._id, doc);
+    const ordered = [];
+    for (const id of ids) {
+      const doc = byId.get(id);
+      if (doc !== void 0 && doc._op !== "delete") ordered.push(doc);
+    }
+    return ordered;
+  }, [found, ids, fromCollection]);
+  const { shape: shape2, payload } = state;
+  const assembled = (0, import_react5.useMemo)(() => {
+    if (documents === void 0) return void 0;
+    if (shape2 === "document") {
+      return documents[0];
+    }
+    if (shape2 === "envelope" && assembleRef.current !== void 0) {
+      const assemble = assembleRef.current;
+      return assemble(documents, payload);
+    }
+    return documents;
+  }, [documents, shape2, payload]);
+  const { select } = options;
+  const selected = (0, import_react5.useMemo)(() => {
+    if (select === void 0 || assembled === void 0) return assembled;
+    return select(assembled);
+  }, [assembled, select]);
+  const sharedRef = (0, import_react5.useRef)(void 0);
+  const shared = replaceEqualDeep(sharedRef.current, selected);
+  sharedRef.current = shared;
+  if (shared !== void 0) previousDataRef.current = shared;
+  const placeholder = shared === void 0 && state.error === null ? resolvePlaceholder(options, previousDataRef.current) : void 0;
+  const isPlaceholderData = placeholder !== void 0;
+  const data = isPlaceholderData ? placeholder : shared;
+  const resultRef = (0, import_react5.useRef)(void 0);
+  const refetch = (0, import_react5.useCallback)(
+    async (opts) => {
+      if (opts?.cancelRefetch !== false) cancelShared(inflightKey(name, keyHash));
+      const controller = new AbortController();
+      refetchControllersRef.current.add(controller);
+      try {
+        await revalidate(controller.signal);
+      } catch (cause) {
+        if (opts?.throwOnError) throw cause;
+      } finally {
+        refetchControllersRef.current.delete(controller);
+      }
+      return nextResult();
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [revalidate, name, keyHash]
+  );
+  const isFetching = state.fetchStatus === "fetching";
+  const isPending = ids === null;
+  const isStale2 = state.dataUpdatedAt === 0 || Date.now() >= state.dataUpdatedAt + staleTime;
+  const common = {
+    fetchStatus: state.fetchStatus,
+    isLoading: isPending && isFetching,
+    isFetching,
+    isPaused: state.fetchStatus === "paused",
+    isRefetching: isFetching && !isPending,
+    isStale: isStale2,
+    isFetched: state.isFetched,
+    isFetchedAfterMount: state.isFetchedAfterMount,
+    isPlaceholderData,
+    fromCollection: state.fromCollection,
+    dataUpdatedAt: state.dataUpdatedAt,
+    errorUpdatedAt: state.errorUpdatedAt,
+    failureCount: state.failureCount,
+    failureReason: state.failureReason,
+    errorUpdateCount: state.errorUpdateCount,
+    refetch
+  };
+  const result = buildResult(common, data, state.error);
+  resultRef.current = result;
+  (0, import_react5.useEffect)(() => {
+    foundRef.current = found;
+    if (resolversRef.current.length === 0) return;
+    const ready = resolversRef.current.filter((entry) => entry.snapshot !== found);
+    if (ready.length === 0) return;
+    resolversRef.current = resolversRef.current.filter((entry) => entry.snapshot === found);
+    for (const { resolve } of ready) resolve(resultRef.current);
+  });
+  if (state.error !== null && shouldThrow(throwOnError, state.error)) throw state.error;
+  return result;
+}
+function shouldThrow(setting, error) {
+  return typeof setting === "function" ? setting(error) : setting;
+}
+var forgetTimers = /* @__PURE__ */ new Map();
+function forgetKey(collection, keyHash) {
+  return `${collection}\0${keyHash}`;
+}
+function scheduleForget(collection, keyHash, after, run) {
+  const key = forgetKey(collection, keyHash);
+  const timer = setTimeout(() => {
+    forgetTimers.delete(key);
+    run();
+  }, after);
+  timer.unref?.();
+  forgetTimers.set(key, timer);
+}
+function cancelForget(collection, keyHash) {
+  const key = forgetKey(collection, keyHash);
+  const timer = forgetTimers.get(key);
+  if (timer === void 0) return;
+  clearTimeout(timer);
+  forgetTimers.delete(key);
+}
+function resetForgetTimers() {
+  for (const timer of forgetTimers.values()) clearTimeout(timer);
+  forgetTimers.clear();
+}
+
+// src/query/useMutation.ts
+var import_react6 = require("react");
+
+// src/query/mutate.ts
+function stampRoute(route, op) {
+  if (route?.url === void 0) return {};
+  return {
+    _endpoint: route.url,
+    _method: route.method?.[op] ?? DEFAULT_METHODS[op]
+  };
+}
+var OP_FOR = {
+  insert: "insert",
+  update: "update",
+  delete: "delete"
+};
+async function writeLocal(collection, op, now, route) {
+  if (op.type === "insert") {
+    const doc = { ...stampPending(op.doc, "insert"), ...stampRoute(route, "insert") };
+    const id2 = await collection.insert(doc);
+    return { id: id2, op: "insert", cancelled: false };
+  }
+  const id = op.where._id;
+  const existing = await collection.findOne({ _id: id });
+  if (existing === null) {
+    throw new Error(
+      `Cannot ${op.type} document ${id}: it is not in the local collection. Writes apply locally first, so the document must already be here.`
+    );
+  }
+  const next = coalesce(pendingOp(existing), OP_FOR[op.type]);
+  if (next === null) {
+    await collection.deleteOne({ _id: id });
+    return { id, op: null, cancelled: true };
+  }
+  const fields = {
+    ...op.type === "update" ? op.set : {},
+    _sync: "pending",
+    _op: next,
+    _attempt: 0,
+    _error: null,
+    _retry_at: 0,
+    _revision: nextRevision(),
+    // The verb follows the coalesced operation, not the one just requested:
+    // editing an unsent insert still POSTs.
+    ...stampRoute(route, next)
+  };
+  await collection.updateOne(
+    { _id: id },
+    {
+      $set: fields,
+      // A hook without a route means "use the provider", not "reuse whatever
+      // endpoint a previous write happened to stamp on this document".
+      ...route?.url === void 0 ? { $unset: { _endpoint: true, _method: true } } : {}
+    }
+  );
+  return { id, op: next, cancelled: false };
+}
+function pendingOp(doc) {
+  if (doc._sync !== "pending" && doc._sync !== "failed") return void 0;
+  return doc._op;
+}
+async function writeConfirmed(collection, doc, now) {
+  const id = doc._id;
+  const current = await collection.findOne({ _id: id });
+  await applyCanonical(collection, current, doc, now);
+}
+
+// src/query/useMutation.ts
+var INITIAL2 = {
+  status: "idle",
+  data: void 0,
+  error: null,
+  variables: void 0,
+  submittedAt: 0,
+  failureCount: 0,
+  failureReason: null,
+  paused: false
+};
+function toError2(cause) {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+function useMutation(options) {
+  const {
+    collection: name,
+    url,
+    method,
+    mode = "optimistic",
+    operation = "insert"
+  } = options;
+  if (options.mutationFn !== void 0 && mode !== "immediate") {
+    throw new Error(
+      `useMutation({ collection: '${name}' }) was given a \`mutationFn\` in '${mode}' mode. Under '${mode}' the request is sent by the drain loop, long after this component is gone \u2014 after a route change, a reload, a week \u2014 so there is no closure left to call and the write would be silently dropped.
+
+Either route it by template, which is data and survives:
+  useMutation({ collection: '${name}', url: '/api/${name}/:id' })
+
+or send it from here and store only what the server agreed to:
+  useMutation({ collection: '${name}', mode: 'immediate', mutationFn })`
+    );
+  }
+  const { backend, register, requestDrain, noteWrite } = useQueryContext();
+  const collection = useCollection(name);
+  const [state, setState] = (0, import_react6.useState)(INITIAL2);
+  const callbacksRef = (0, import_react6.useRef)(options);
+  callbacksRef.current = options;
+  (0, import_react6.useEffect)(() => {
+    register(name);
+  }, [register, name]);
+  const watchersRef = (0, import_react6.useRef)(/* @__PURE__ */ new Set());
+  const mountedRef = (0, import_react6.useRef)(true);
+  (0, import_react6.useEffect)(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      for (const stop of watchersRef.current) stop();
+      watchersRef.current.clear();
+    };
+  }, []);
+  const patch = (0, import_react6.useCallback)((next) => {
+    if (mountedRef.current) setState((current) => ({ ...current, ...next }));
+  }, []);
+  const reset = (0, import_react6.useCallback)(() => {
+    if (mountedRef.current) setState(INITIAL2);
+  }, []);
+  const mutateAsync = (0, import_react6.useCallback)(
+    async (variables, perCall) => {
+      const hooks = callbacksRef.current;
+      const op = toOperation(operation, variables);
+      if (isDev() && op.type !== "insert") checkMutationFilter(op.where);
+      patch({
+        status: "pending",
+        variables,
+        error: null,
+        data: void 0,
+        submittedAt: Date.now()
+      });
+      let context;
+      try {
+        context = await hooks.onMutate?.(variables);
+        const data = mode === "immediate" ? await runScoped(
+          hooks.scope?.id,
+          () => attemptWrite({
+            retry: hooks.retry,
+            retryDelay: hooks.retryDelay,
+            networkMode: hooks.networkMode,
+            onPaused: (paused) => patch({ paused }),
+            onFailure: (count, reason) => patch({ failureCount: count, failureReason: reason }),
+            send: () => sendThenStore({
+              collection,
+              name,
+              op,
+              url,
+              method,
+              backend,
+              mutationFn: hooks.mutationFn,
+              variables
+            })
+          })
+        ) : await storeThenSend({ collection, op, url, method, mode, requestDrain, noteWrite });
+        patch({
+          status: "success",
+          data,
+          error: null,
+          failureCount: 0,
+          failureReason: null,
+          paused: false
+        });
+        await hooks.onSuccess?.(data, variables, context);
+        await perCall?.onSuccess?.(data, variables, context);
+        await hooks.onSettled?.(data, null, variables, context);
+        await perCall?.onSettled?.(data, null, variables, context);
+        if (mode === "immediate") {
+          await hooks.onSynced?.(data, variables);
+          await perCall?.onSynced?.(data, variables);
+        } else if (hooks.onSynced !== void 0 || perCall?.onSynced !== void 0) {
+          watchUntilSynced(collection, data._id, watchersRef, () => {
+            void hooks.onSynced?.(data, variables);
+            void perCall?.onSynced?.(data, variables);
+          });
+        }
+        return data;
+      } catch (cause) {
+        const error = toError2(cause);
+        setState((current) => ({
+          ...current,
+          status: "error",
+          data: void 0,
+          error,
+          failureCount: Math.max(current.failureCount, 1),
+          failureReason: error,
+          paused: false
+        }));
+        await hooks.onError?.(error, variables, context);
+        await perCall?.onError?.(error, variables, context);
+        await hooks.onSettled?.(void 0, error, variables, context);
+        await perCall?.onSettled?.(void 0, error, variables, context);
+        throw error;
+      }
+    },
+    [collection, name, mode, operation, url, method, backend, requestDrain, noteWrite, patch]
+  );
+  const mutate = (0, import_react6.useCallback)(
+    (variables, perCall) => {
+      void mutateAsync(variables, perCall).catch(() => {
+      });
+    },
+    [mutateAsync]
+  );
+  const common = {
+    mutate,
+    mutateAsync,
+    reset,
+    // `immediate` is the only mode that can be blocked by connectivity; the
+    // others commit locally and let the drain worry about the network.
+    isPaused: state.paused,
+    failureCount: state.failureCount,
+    failureReason: state.failureReason,
+    submittedAt: state.submittedAt
+  };
+  const result = buildResult2(common, state);
+  const throwOnError = options.throwOnError ?? false;
+  if (state.error !== null && (typeof throwOnError === "function" ? throwOnError(state.error) : throwOnError)) {
+    throw state.error;
+  }
+  return result;
+}
+async function attemptWrite(args) {
+  const { retry, retryDelay, networkMode, onPaused, onFailure, send } = args;
+  const controller = new AbortController();
+  let failures = 0;
+  for (; ; ) {
+    if ((networkMode ?? "online") === "online" && isOffline()) {
+      onPaused(true);
+      await waitForOnline();
+      onPaused(false);
+    }
+    try {
+      return await send();
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      failures += 1;
+      onFailure(failures, error);
+      if (!shouldRetry(retry ?? 0, failures, error)) throw error;
+      await sleep(retryDelayMs(retryDelay, failures - 1, error), controller.signal);
+    }
+  }
+}
+function waitForOnline() {
+  if (typeof window === "undefined") return Promise.resolve();
+  return new Promise((resolve) => {
+    const onOnline = () => {
+      window.removeEventListener("online", onOnline);
+      resolve();
+    };
+    window.addEventListener("online", onOnline);
+  });
+}
+var scopeChains = /* @__PURE__ */ new Map();
+function runScoped(id, work) {
+  if (id === void 0) return work();
+  const previous = scopeChains.get(id) ?? Promise.resolve();
+  const next = previous.then(work, work);
+  const settled = next.then(
+    () => void 0,
+    () => void 0
+  );
+  scopeChains.set(id, settled);
+  void settled.then(() => {
+    if (scopeChains.get(id) === settled) scopeChains.delete(id);
+  });
+  return next;
+}
+function resetMutationScopes() {
+  scopeChains.clear();
+}
+function watchUntilSynced(collection, id, watchers, fire) {
+  if (id === void 0) return;
+  let stop;
+  let done = false;
+  const finish = () => {
+    if (done) return;
+    done = true;
+    if (stop !== void 0) {
+      watchers.current.delete(stop);
+      stop();
+    }
+  };
+  stop = collection.subscribe({ _id: id }, (docs) => {
+    const doc = docs[0];
+    if (doc === void 0) {
+      finish();
+      return;
+    }
+    if (doc._sync === "synced") {
+      finish();
+      fire();
+    }
+  });
+  watchers.current.add(stop);
+}
+function toOperation(operation, variables) {
+  const values = variables ?? {};
+  if (operation === "insert") return { type: "insert", doc: values };
+  const id = values._id;
+  if (typeof id !== "string" || id === "") {
+    throw new Error(
+      `useMutation({ operation: '${operation}' }) needs an \`_id\` on the variables \u2014 mutate({ _id, \u2026 }). Writes are addressed by id, never by filter: a filter is re-evaluated at the primary tab against data the calling tab has not seen.`
+    );
+  }
+  if (operation === "delete") return { type: "delete", where: { _id: id } };
+  const { _id: _ignored, ...set } = values;
+  return { type: "update", where: { _id: id }, set };
+}
+async function storeThenSend(args) {
+  const { collection, op, url, method, mode, requestDrain, noteWrite } = args;
+  const written = await writeLocal(collection, op, Date.now(), { url, method });
+  if (mode === "optimistic") requestDrain();
+  else noteWrite();
+  const stored = await collection.findOne({ _id: written.id });
+  return stored === null ? { _id: written.id } : withoutEnvelope(stored);
+}
+async function sendThenStore(args) {
+  const { collection, name, op, url, method, backend, mutationFn, variables } = args;
+  if (mutationFn !== void 0) {
+    const returned = await mutationFn(variables);
+    const id2 = returned?._id !== void 0 ? String(returned._id) : op.type === "insert" ? op.doc._id ?? newDocId(name) : op.where._id;
+    if (op.type === "delete") {
+      await collection.deleteOne({ _id: id2 });
+      return { _id: id2 };
+    }
+    const stored2 = { ...returned, _id: id2 };
+    await writeConfirmed(collection, stored2, Date.now());
+    return stored2;
+  }
+  if (url === void 0) {
+    throw new Error(
+      "useMutation({ mode: 'immediate' }) needs a `url` \u2014 the request is sent from here, so there is nothing to route it by otherwise."
+    );
+  }
+  const id = op.type === "insert" ? op.doc._id ?? newDocId(name) : op.where._id;
+  const body = op.type === "delete" ? null : op.type === "insert" ? { ...op.doc, _id: id } : { ...op.set, _id: id };
+  const verb = method?.[op.type] ?? backend?.method[op.type] ?? DEFAULT_METHODS[op.type];
+  const headers = new Headers(backend?.headers ? await backend.headers() : void 0);
+  if (body !== null && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  const doFetch = backend?.fetch ?? globalThis.fetch;
+  const response = await doFetch(resolveUrl(url, name, id, op.type), {
+    method: verb,
+    headers,
+    body: body === null ? void 0 : JSON.stringify(body)
+  });
+  const outcome = backend?.classify ? backend.classify(response, { collection: name, id, type: op.type, document: body }) : defaultClassify(response);
+  if (outcome === "retry" || outcome === "terminal") {
+    throw new Error(
+      `The server rejected this ${op.type} with status ${response.status}. Nothing was written locally.`
+    );
+  }
+  if (op.type === "delete") {
+    await collection.deleteOne({ _id: id });
+    return { _id: id };
+  }
+  const canonical = await readJson(response);
+  const fallback = op.type === "update" ? { ...withoutEnvelope(await collection.findOne({ _id: id }) ?? {}), ...body } : body;
+  const stored = {
+    ...canonical && Object.keys(canonical).length > 0 ? canonical : fallback,
+    _id: id
+  };
+  await writeConfirmed(collection, stored, Date.now());
+  return stored;
+}
+function buildResult2(common, state) {
+  if (state.status === "error") {
+    return {
+      ...common,
+      status: "error",
+      data: void 0,
+      error: state.error,
+      variables: state.variables,
+      isIdle: false,
+      isPending: false,
+      isSuccess: false,
+      isError: true
+    };
+  }
+  if (state.status === "success") {
+    return {
+      ...common,
+      status: "success",
+      data: state.data,
+      error: null,
+      variables: state.variables,
+      isIdle: false,
+      isPending: false,
+      isSuccess: true,
+      isError: false
+    };
+  }
+  if (state.status === "pending") {
+    return {
+      ...common,
+      status: "pending",
+      data: void 0,
+      error: null,
+      variables: state.variables,
+      isIdle: false,
+      isPending: true,
+      isSuccess: false,
+      isError: false
+    };
+  }
+  return {
+    ...common,
+    status: "idle",
+    data: void 0,
+    error: null,
+    variables: void 0,
+    isIdle: true,
+    isPending: false,
+    isSuccess: false,
+    isError: false
+  };
+}
+async function readJson(response) {
+  try {
+    const parsed = await response.json();
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/query/useSyncStatus.ts
+var import_react7 = require("react");
+var QUEUED = { _sync: { $in: ["pending", "failed"] } };
+function useSyncStatus() {
+  const db = useTalaDB();
+  const { collections, draining, requestDrain } = useQueryContext();
+  const slicesRef = (0, import_react7.useRef)(/* @__PURE__ */ new Map());
+  const [version, bump] = (0, import_react7.useState)(0);
+  const [online, setOnline] = (0, import_react7.useState)(
+    () => typeof navigator === "undefined" ? true : navigator.onLine
+  );
+  (0, import_react7.useEffect)(() => {
+    if (typeof window === "undefined") return;
+    const update = () => setOnline(navigator.onLine);
+    window.addEventListener("online", update);
+    window.addEventListener("offline", update);
+    return () => {
+      window.removeEventListener("online", update);
+      window.removeEventListener("offline", update);
+    };
+  }, []);
+  (0, import_react7.useEffect)(() => {
+    const unsubscribes = collections.map((name) => {
+      const collection = db.collection(name);
+      return collection.subscribe(QUEUED, (docs) => {
+        slicesRef.current.set(name, summarise(name, docs));
+        bump((n) => n + 1);
+      });
+    });
+    return () => {
+      for (const unsubscribe of unsubscribes) unsubscribe();
+    };
+  }, [db, collections]);
+  const { pending, failed } = (0, import_react7.useMemo)(() => {
+    let total = 0;
+    const failures = [];
+    for (const slice of slicesRef.current.values()) {
+      total += slice.pending;
+      failures.push(...slice.failed);
+    }
+    return { pending: total, failed: failures };
+  }, [version]);
+  const findCollection = (0, import_react7.useCallback)(
+    async (id) => {
+      for (const name of collections) {
+        const collection = db.collection(name);
+        if (await collection.findOne({ _id: id }) !== null) return collection;
+      }
+      return null;
+    },
+    [db, collections]
+  );
+  const retry = (0, import_react7.useCallback)(
+    (id) => {
+      void (async () => {
+        const collection = await findCollection(id);
+        if (collection === null) return;
+        await collection.updateOne(
+          { _id: id },
+          { $set: { _sync: "pending", _attempt: 0, _error: null, _retry_at: 0 } }
+        );
+        requestDrain(true);
+      })();
+    },
+    [findCollection, requestDrain]
+  );
+  const discard = (0, import_react7.useCallback)(
+    (id) => {
+      void (async () => {
+        const collection = await findCollection(id);
+        if (collection === null) return;
+        const doc = await collection.findOne({ _id: id });
+        if (doc === null) return;
+        if (doc._op === "insert") {
+          await collection.deleteOne({ _id: id });
+        } else {
+          await collection.updateOne(
+            { _id: id },
+            { $set: { _sync: "synced", _op: null, _attempt: 0, _error: null, _retry_at: 0 } }
+          );
+        }
+      })();
+    },
+    [findCollection]
+  );
+  return { pending, failed, draining, online, retry, discard };
+}
+function summarise(collection, docs) {
+  let pending = 0;
+  const failed = [];
+  for (const doc of docs) {
+    if (doc._sync === "pending") {
+      pending++;
+    } else if (doc._sync === "failed") {
+      failed.push({
+        collection,
+        id: doc._id,
+        op: doc._op ?? "update",
+        error: doc._error ?? "Unknown error",
+        attempts: doc._attempt ?? 0
+      });
+    }
+  }
+  return { pending, failed };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_METHODS,
+  DEFAULT_RETRY,
+  DEFAULT_STALE_TIME,
+  ENVELOPE_FIELDS,
+  ENVELOPE_INDEXES,
+  QUERY_COLLECTION,
+  QueryProvider,
+  backoffMs,
+  cancelShared,
+  checkClassification,
+  checkMutationFilter,
+  checkResponseBody,
+  checkResponseId,
+  coalesce,
+  contains,
+  defaultClassify,
+  defineParams,
+  deleteQueryRecord,
+  drainOnce,
+  ensureEnvelopeIndexes,
+  eq,
+  extractDocuments,
+  gt,
+  gte,
+  hashQueryKey,
+  hydrate,
+  inflightKey,
+  isBoundParams,
+  isDev,
+  isOffline,
+  isShared,
+  isStale,
+  keepPreviousData,
+  lt,
+  lte,
+  ne,
+  newDocId,
+  normalizeParams,
+  noteIgnoredOptions,
+  oneOf,
+  openQueryCollection,
+  queryRecordId,
+  readQueryRecord,
+  replaceEqualDeep,
+  reservedFieldsIn,
+  resetCollectionWarnings,
+  resetForgetTimers,
+  resetInflight,
+  resetMutationScopes,
+  resetWarnings,
+  resolveCollectionName,
+  resolveUrl,
+  retryDelayMs,
+  runShared,
+  sendWrite,
+  shape,
+  shouldRetry,
+  stampPending,
+  stampSynced,
+  toPendingWrite,
+  useMutation,
+  useQuery,
+  useQueryContext,
+  useSyncStatus,
+  warnOnce,
+  writeConfirmed,
+  writeLocal,
+  writeQueryRecord
+});