@ai-matrx/records 0.80.8 → 0.81.1

package/dist/react/index.js

@@ -18,6 +18,10 @@ function registry() {
   return g[REGISTRY] ??= /* @__PURE__ */ new Map();
 }
 var primedKey = (organizationId, tableId, viewId) => `${organizationId}|${tableId}|${viewId ?? ""}`;
+function primeTablePageBundle(input) {
+  const answer = Promise.resolve(input.answer).catch((thrown) => ({ data: null, error: thrown }));
+  registry().set(primedKey(input.organizationId, input.tableId, input.viewId), { answer, at: Date.now() });
+}
 function takePrimedTablePageBundle(organizationId, tableId, viewId) {
   if (!organizationId) return null;
   const key = primedKey(organizationId, tableId, viewId);
@@ -27,6 +31,9 @@ function takePrimedTablePageBundle(organizationId, tableId, viewId) {
   primed.delete(key);
   return Date.now() - held.at < PRIMED_TTL_MS ? held.answer : null;
 }
+function primeRecordPageBundle(input) {
+  primeTablePageBundle({ organizationId: input.organizationId, tableId: `record:${input.recordId}`, answer: input.answer });
+}
 
 // src/core/recordChanges.ts
 var listeners = /* @__PURE__ */ new Set();
@@ -144,8 +151,8 @@ function liftWithheld(rows) {
 }
 
 // src/subscription.ts
-function hasQuietHours(quiet) {
-  return Boolean(quiet?.start && quiet?.end);
+function hasQuietHours(quiet2) {
+  return Boolean(quiet2?.start && quiet2?.end);
 }
 function callersTimeZone() {
   try {
@@ -7569,7 +7576,7 @@ function useRecordsActor() {
 }
 
 // src/react/hooks.ts
-import { useCallback, useEffect as useEffect2, useId, useMemo as useMemo2, useRef as useRef2, useState, useSyncExternalStore } from "react";
+import { use, useCallback, useEffect as useEffect3, useId, useMemo as useMemo2, useRef as useRef2, useState, useSyncExternalStore } from "react";
 
 // src/react/dataCache.ts
 var RECORDS_CACHE_GRACE_MS = 3e4;
@@ -7722,6 +7729,12 @@ function releaseEntry(handle) {
   entry.refs = Math.max(0, entry.refs - 1);
   if (entry.refs === 0) scheduleClose(entry);
 }
+function seedEntry(handle, data, stale) {
+  const entry = handle;
+  if (entry.started || entry.snapshot.data !== null) return;
+  entry.snapshot = { data, loading: false, error: null };
+  entry.started = !stale;
+}
 function openHold(holdKey) {
   const holds = root().holds;
   let hold = holds.get(holdKey);
@@ -7752,17 +7765,154 @@ function recordsCacheCounters() {
   return { ...root().counters };
 }
 
-// src/react/hold.tsx
+// src/react/seed.tsx
 import { createContext as createContext2, createElement as createElement2, useContext as useContext2, useEffect } from "react";
-var HoldContext = createContext2(null);
+
+// src/core/seed.ts
+var BUNDLE_DOORS = /* @__PURE__ */ new Set(["table_page_bundle", "record_page_bundle"]);
+function seedKey(door, args) {
+  return `${door}|${canonicalArgs(args)}`;
+}
+function answersOf(door, args, data) {
+  const out = [{ door, args, data }];
+  if (!BUNDLE_DOORS.has(door) || !data || typeof data !== "object") return out;
+  const parts = data.parts;
+  if (!Array.isArray(parts)) return out;
+  for (const part of parts) {
+    if (part.error !== void 0 || part.data === void 0) continue;
+    if (typeof part.door !== "string" || !part.args || typeof part.args !== "object") continue;
+    out.push({ door: part.door, args: part.args, data: part.data });
+  }
+  return out;
+}
+function seedIndex(seed) {
+  const index = /* @__PURE__ */ new Map();
+  for (const a of seed.answers) {
+    for (const spread of answersOf(a.door, a.args, a.data)) index.set(seedKey(spread.door, spread.args), spread.data);
+  }
+  return index;
+}
+var MISS = { code: "SEED_MISS", message: "Not in the page's seed.", details: null, hint: null };
+function missingQuery(onMiss) {
+  const answer = () => {
+    onMiss();
+    return Promise.resolve({ data: null, error: MISS, count: null });
+  };
+  const chain = new Proxy(function() {
+  }, {
+    get(_target, prop) {
+      if (prop === "then") return (ok2, bad) => answer().then(ok2, bad);
+      return () => chain;
+    },
+    apply: () => chain
+  });
+  return { select: () => chain };
+}
+function seededDataSource(index) {
+  let missed = false;
+  const source = {
+    rpc(fn, args) {
+      const key = seedKey(fn, args);
+      if (index.has(key)) return Promise.resolve({ data: index.get(key), error: null });
+      missed = true;
+      return Promise.resolve({ data: null, error: MISS });
+    },
+    schema: () => ({ from: () => missingQuery(() => missed = true) })
+  };
+  return { source, missed: () => missed };
+}
+
+// src/react/seed.tsx
+var SEED_FRESH_MS = 3e4;
+var stores = /* @__PURE__ */ new WeakMap();
+var quiet = () => {
+};
+function storeFor(seed) {
+  const held = stores.get(seed);
+  if (held) return held;
+  const index = seedIndex(seed);
+  const runs = /* @__PURE__ */ new Map();
+  const store = {
+    live: true,
+    run(slot, run, config) {
+      const asked = runs.get(slot);
+      if (asked) return asked;
+      const { source, missed } = seededDataSource(index);
+      const { realtime: _live, ...quietConfig } = config;
+      const client = createRecordsClient({ ...quietConfig, dataSource: source, onError: quiet });
+      const stale = typeof seed.at !== "number" || Date.now() - seed.at > SEED_FRESH_MS;
+      const outcome = Promise.resolve().then(() => run(client)).then(
+        (answer) => answer.ok && !missed() ? { seeded: true, data: answer.data, stale } : { seeded: false },
+        () => ({ seeded: false })
+      );
+      runs.set(slot, outcome);
+      return outcome;
+    }
+  };
+  stores.set(seed, store);
+  if (typeof window !== "undefined") {
+    for (const a of seed.answers) {
+      const org = a.args["p_organization_id"];
+      if (typeof org !== "string") continue;
+      if (a.door === "table_page_bundle" && typeof a.args["p_table_id"] === "string") {
+        const view = a.args["p_view_id"];
+        primeTablePageBundle({ organizationId: org, tableId: a.args["p_table_id"], viewId: typeof view === "string" ? view : null, answer: { data: a.data, error: null } });
+      } else if (a.door === "record_page_bundle" && typeof a.args["p_record_id"] === "string") {
+        primeRecordPageBundle({ organizationId: org, recordId: a.args["p_record_id"], answer: { data: a.data, error: null } });
+      }
+    }
+  }
+  return store;
+}
+var SeedContext = createContext2(null);
+function RecordsSeedProvider({ seed, children }) {
+  const store = seed && Array.isArray(seed.answers) ? storeFor(seed) : null;
+  useEffect(() => {
+    if (store) store.live = false;
+  }, [store]);
+  return createElement2(SeedContext.Provider, { value: store }, children);
+}
+function useSeedStore() {
+  const store = useContext2(SeedContext);
+  return store && store.live ? store : null;
+}
+
+// src/react/hold.tsx
+import { createContext as createContext3, createElement as createElement3, useContext as useContext3, useEffect as useEffect2 } from "react";
+var HoldContext = createContext3(null);
 function RecordsHoldScope({ holdKey, children }) {
-  return createElement2(HoldContext.Provider, { value: holdKey }, children);
+  return createElement3(HoldContext.Provider, { value: holdKey }, children);
 }
 function useRecordsHold(holdKey) {
-  useEffect(() => holdKey ? openHold(holdKey) : void 0, [holdKey]);
+  useEffect2(() => holdKey ? openHold(holdKey) : void 0, [holdKey]);
 }
 function useHoldKey() {
-  return useContext2(HoldContext);
+  return useContext3(HoldContext);
+}
+
+// src/react/pageOrder.ts
+function pageOrderOf(sort, narrowed) {
+  return { sortFields: (sort ?? []).map((key) => key.field), narrowed };
+}
+var same = (a, b) => {
+  if (a === b) return true;
+  if ((a === null || a === void 0 || a === "") && (b === null || b === void 0 || b === "")) return true;
+  return JSON.stringify(a) === JSON.stringify(b);
+};
+function patchMovesRows(held, fresh, order) {
+  if (order.sortFields.length === 0 && !order.narrowed) return false;
+  for (const row of held) {
+    const next = fresh.get(row.id);
+    if (!next) continue;
+    const was = row.document ?? {};
+    const now = next.document ?? {};
+    if (order.narrowed) {
+      if (!same(was, now)) return true;
+      continue;
+    }
+    for (const field2 of order.sortFields) if (!same(was[field2], now[field2])) return true;
+  }
+  return false;
 }
 
 // src/react/hooks.ts
@@ -7777,12 +7927,17 @@ function useAsync(run, key, live) {
   );
   entry.run = run;
   entry.client = client;
+  const seed = useSeedStore();
+  if (seed && entry.snapshot.data === null && !entry.snapshot.error && !entry.started) {
+    const outcome = use(seed.run(`${identityOf(client)}|${key}`, run, client.config));
+    if (outcome.seeded) seedEntry(entry, outcome.data, outcome.stale);
+  }
   const snapshot = useSyncExternalStore(entry.subscribe, entry.getSnapshot, entry.getSnapshot);
-  useEffect2(() => {
+  useEffect3(() => {
     acquireEntry(entry);
     return () => releaseEntry(entry);
   }, [entry]);
-  useEffect2(() => {
+  useEffect3(() => {
     if (holdKey) pinToHold(holdKey, slot, entry);
   }, [holdKey, slot, entry]);
   const lastData = useRef2(null);
@@ -7792,25 +7947,33 @@ function useAsync(run, key, live) {
   const setData = useCallback((update) => entry.setData(update), [entry]);
   return { ...shown, reload, setData };
 }
+function useSeededAnswer(key, run) {
+  const client = useRecordsClient();
+  const seed = useSeedStore();
+  if (!seed || key === null) return void 0;
+  const outcome = use(seed.run(`${identityOf(client)}|own:${key}`, run, client.config));
+  return outcome.seeded ? outcome.data : void 0;
+}
 function serverEntry(run, client) {
-  const snapshot = { data: null, loading: true, error: null };
-  return {
+  const entry = {
     key: "server",
-    snapshot,
+    snapshot: { data: null, loading: true, error: null },
     run,
     client,
     subscribe: () => () => {
     },
-    getSnapshot: () => snapshot,
+    // Read through the entry: a page seed may answer it during this render (`seedEntry`).
+    getSnapshot: () => entry.snapshot,
     refetch: () => {
     },
     setData: () => {
     }
   };
+  return entry;
 }
 function useTable(tableId) {
   const revision = useShapeRevision(tableId);
-  useEffect2(() => {
+  useEffect3(() => {
     if (tableId) registerShapeInterest(tableId);
   }, [tableId]);
   return useAsync(
@@ -7872,7 +8035,7 @@ function useShapeRevision(tableId) {
 }
 function useFields(tableId, recordType) {
   const revision = useShapeRevision(tableId);
-  useEffect2(() => {
+  useEffect3(() => {
     if (tableId) registerShapeInterest(tableId);
   }, [tableId]);
   return useAsync(
@@ -7908,7 +8071,7 @@ function useReverseColumns(tableId) {
 }
 function useReverseLinks(tableId, columns, recordIds, limit = 3, offset = 0) {
   const [writes, setWrites] = useState(0);
-  useEffect2(() => onRecordChanged(() => setWrites((n) => n + 1)), []);
+  useEffect3(() => onRecordChanged(() => setWrites((n) => n + 1)), []);
   const idsKey = recordIds.join(",");
   const columnsKey = columns.map((c) => c.source_field_id).join(",");
   return useAsync(
@@ -7935,7 +8098,7 @@ function useReverseLinks(tableId, columns, recordIds, limit = 3, offset = 0) {
     tableId ? `reverse-links:${tableId}:${columnsKey}:${limit}:${offset}:${idsKey}:${writes}` : "reverse-links:none"
   );
 }
-function liveRowsFor(tableId) {
+function liveRowsFor(tableId, order = { sortFields: [], narrowed: false }) {
   return (entry) => {
     const client = entry.client;
     const realtime = client.config.realtime;
@@ -7954,6 +8117,10 @@ function liveRowsFor(tableId) {
         entry.refetch();
         return;
       }
+      if (patchMovesRows(held, fresh, order)) {
+        entry.refetch();
+        return;
+      }
       entry.setData(
         (current) => current === null ? current : {
           ...current,
@@ -8061,7 +8228,7 @@ function useRecords(tableId, options = {}) {
     // on every render must not re-read the page on every render, and a parent
     // that changes the question must re-read on the first one.
     `records:${tableId ?? "none"}:${pageSize}:${page2}:${filterKey}:s${shape}`,
-    liveRowsFor(tableId)
+    liveRowsFor(tableId, pageOrderOf(void 0, filterKey !== "{}"))
   );
   const { live, liveReason } = liveStatus(useRecordsClient(), tableId);
   return { ...useSharedRows(useKeptPage(tableId, base)), live, liveReason };
@@ -8089,14 +8256,14 @@ function useRecordPage(tableId, options = {}) {
       return answered.ok ? { ok: true, data: { rows: answered.data.rows, total: answered.data.total, sortIgnored: answered.data.sort_ignored ?? [] } } : answered;
     },
     `page:${tableId ?? "none"}:${pageSize}:${page2}:${filterKey}:${search ?? ""}:${sortKey}:${viewId ?? ""}:s${shape}`,
-    liveRowsFor(tableId)
+    liveRowsFor(tableId, pageOrderOf(options.sort, filterKey !== "{}" || search !== null))
   );
   const { live, liveReason } = liveStatus(useRecordsClient(), tableId);
   return { ...useSharedRows(useKeptPage(tableId, base)), live, liveReason };
 }
 function useRecordChangeRevision(recordId) {
   const [revision, setRevision] = useState(0);
-  useEffect2(() => {
+  useEffect3(() => {
     if (!recordId) return;
     return onRecordChanged((changed) => {
       if (changed === recordId) setRevision((n) => n + 1);
@@ -8467,7 +8634,7 @@ function useMergeField(key, state) {
   const client = useRecordsClient();
   const [resolution, setResolution] = useState(null);
   const resolver = client.config.resolver;
-  useEffect2(() => {
+  useEffect3(() => {
     if (!key) {
       setResolution(null);
       return;
@@ -8502,11 +8669,11 @@ function useMergeField(key, state) {
 }
 
 // src/react/entity-reference.ts
-import { useEffect as useEffect3, useState as useState2 } from "react";
+import { useEffect as useEffect4, useState as useState2 } from "react";
 function useEntityReferenceKinds() {
   const client = useRecordsClient();
   const [state, setState] = useState2({ data: null, loading: true, error: null });
-  useEffect3(() => {
+  useEffect4(() => {
     let live = true;
     void entityReferenceKinds(client.config.dataSource).then((res) => {
       if (!live) return;
@@ -8522,7 +8689,7 @@ function useEntityReferenceWords(refs) {
   const client = useRecordsClient();
   const key = refs.map((r) => `${r.token}:${r.id}`).join(",");
   const [state, setState] = useState2({ data: null, loading: refs.length > 0, error: null });
-  useEffect3(() => {
+  useEffect4(() => {
     let live = true;
     void entityReferenceWords(client.config.dataSource, client.config.organizationId, refs).then((res) => {
       if (!live) return;
@@ -8538,7 +8705,7 @@ function useEntityReferenceSearch(tokens, search, enabled = true) {
   const client = useRecordsClient();
   const key = `${tokens.join(",")}|${search.trim()}|${enabled ? 1 : 0}`;
   const [state, setState] = useState2({ data: null, loading: enabled && tokens.length > 0, error: null });
-  useEffect3(() => {
+  useEffect4(() => {
     if (!enabled || tokens.length === 0) {
       setState({ data: [], loading: false, error: null });
       return;
@@ -8560,7 +8727,7 @@ function useEntityReferenceSearch(tokens, search, enabled = true) {
 }
 
 // src/react/useAppTable.ts
-import { useCallback as useCallback2, useEffect as useEffect4, useRef as useRef3, useState as useState3 } from "react";
+import { useCallback as useCallback2, useEffect as useEffect5, useRef as useRef3, useState as useState3 } from "react";
 
 // src/core/declareTable.ts
 function tokenFor(name) {
@@ -8864,7 +9031,7 @@ function useAppTable(def, options = {}) {
   const [revision, setRevision] = useState3(0);
   const rowsRef = useRef3([]);
   rowsRef.current = rows;
-  useEffect4(() => {
+  useEffect5(() => {
     let live = true;
     setLoading(true);
     (async () => {
@@ -8925,7 +9092,7 @@ function archivedTableOf(error) {
 }
 
 // src/react/useStoreTable.ts
-import { useEffect as useEffect6, useMemo as useMemo4 } from "react";
+import { useEffect as useEffect7, useMemo as useMemo4 } from "react";
 
 // src/app-table/store-table.ts
 function storeTable(def) {
@@ -10160,7 +10327,7 @@ function createTableDataPort({ client, aliases }) {
 }
 
 // src/data/react.tsx
-import { createContext as createContext3, createElement as createElement3, useContext as useContext3, useEffect as useEffect5, useMemo as useMemo3, useRef as useRef4 } from "react";
+import { createContext as createContext4, createElement as createElement4, useContext as useContext4, useEffect as useEffect6, useMemo as useMemo3, useRef as useRef4 } from "react";
 import {
   QueryClient as QueryClientClass,
   QueryClientContext,
@@ -10214,13 +10381,13 @@ function retryable(failureCount, thrown) {
   const code = thrown instanceof DataRefusal ? thrown.error.code : "unreachable";
   return (code === "unreachable" || code === "timed_out") && failureCount < 2;
 }
-var DataPortContext = createContext3(null);
+var DataPortContext = createContext4(null);
 function hostEvents(port) {
   return { on: (event, listener) => port.subscribe(event, listener) };
 }
 var warnedNotLive = false;
 function useDataPort(scope) {
-  const held = useContext3(DataPortContext);
+  const held = useContext4(DataPortContext);
   if (scope) return scope;
   if (!held) {
     throw new Error(
@@ -10506,7 +10673,7 @@ function acquireLive(qc, port, events, portKey, alias) {
 }
 var FALLBACK_KEY = /* @__PURE__ */ Symbol.for("@ai-matrx/records/data-query-client");
 function useRecordsQueryClient() {
-  const provided = useContext3(QueryClientContext);
+  const provided = useContext4(QueryClientContext);
   if (provided) return provided;
   const g = globalThis;
   let held = g[FALLBACK_KEY];
@@ -10519,7 +10686,7 @@ function useRecordsQueryClient() {
 function useLive(alias, scope) {
   const qc = useRecordsQueryClient();
   const { port, portKey, events } = useDataPort(scope);
-  useEffect5(() => {
+  useEffect6(() => {
     if (!alias) return;
     return acquireLive(qc, port, events, portKey, alias);
   }, [qc, port, events, portKey, alias]);
@@ -10555,7 +10722,7 @@ function useDataRows(alias, query = {}, scope) {
   const keyHash = hashKey(rowsKey);
   const loaded = q.data?.pages.length ?? 0;
   const { isFetching, hasNextPage, isFetchNextPageError, fetchNextPage } = q;
-  useEffect5(() => {
+  useEffect6(() => {
     const w = want.current;
     if (w.key !== keyHash || isFetching || loaded >= w.pages) return;
     if (!hasNextPage || isFetchNextPageError) {
@@ -10732,7 +10899,7 @@ function useStoreTable(table, options = {}) {
   const limit = Math.min(options.limit ?? STORE_ROWS_CEILING, STORE_ROWS_CEILING);
   const read = useDataRows(alias, built.ok ? built.data : { pageSize: 1 }, scope);
   const write = useDataMutations(alias, scope);
-  useEffect6(() => {
+  useEffect7(() => {
     if (built.ok && read.hasMore && !read.loadingMore && !read.loading && !read.error && read.rows.length < limit) read.loadMore();
   }, [built.ok, read.hasMore, read.loadingMore, read.loading, read.error, read.rows.length, limit, read]);
   const rows = useMemo4(() => read.rows.slice(0, limit).filter((r) => r["_pending"] !== true).map((r) => toNamed(table, r)), [read.rows, limit, table]);
@@ -12203,6 +12370,8 @@ export {
   RULE_USES,
   RecordsHoldScope,
   RecordsProvider,
+  RecordsSeedProvider,
+  SEED_FRESH_MS,
   SHOWN_TO_LABEL,
   SHOWN_TO_VALUES,
   SHOWN_TO_WHO_MAY_CHANGE,
@@ -12394,6 +12563,7 @@ export {
   useReverseColumns,
   useReverseLinks,
   useRowActions,
+  useSeededAnswer,
   useStoreTable,
   useTable,
   useTableArchive,