@marktiderman/genesis-core 1.7.0 → 1.9.0

package/README.md

@@ -106,6 +106,39 @@ const provider = createSupabaseProvider(supabase, {
 Both hooks also take an `invalidates` option for keys one screen cares about:
 `useResource("tasks", { invalidates: [["me"]] })`.
 
+### Reading from a view or a function
+
+A list often needs more than one table: a join, a count, a total. Give the resource a `source` and
+keep everything else (paging, filters, search, sort, "showing N of M", cursors, live updates,
+Retry): PostgREST filters a view or a set-returning function like a table. Writes still go to the
+table, and realtime still watches it.
+
+```ts
+createSupabaseProvider(supabase, {
+  resources: {
+    // A view joining tasks to people and counting comments.
+    tasks: { source: "tasks_with_people" },
+    // A function returning rows; args are read on every request.
+    course_progress: { source: { rpc: "group_progress", args: () => ({ group_id: currentGroupId() }) } },
+    // Embedded joins as the default columns (a caller's `select` still wins).
+    sessions: { select: "*, client:people(full_name)" },
+  },
+});
+```
+
+**Keep RLS on.** A plain view runs as its owner, and a `security definer` function as its definer, so
+either reads past row-level security and shows every row. Create the view
+`with (security_invoker = true)` and the function `security invoker` (or have it filter by
+`auth.uid()` itself):
+
+```sql
+create view public.tasks_with_people with (security_invoker = true) as
+  select t.*, p.full_name as person_name from public.tasks t join public.people p on p.id = t.person_id;
+```
+
+Writes send only the table's own columns: list them as `writeColumns`, or an update keeps just the
+columns the table's row has, so a form built from the view row never sends `person_name` back.
+
 ### Handling failures
 
 ```ts
@@ -117,6 +150,7 @@ try {
       case "forbidden": /* hide the control, say why */ break;
       case "gone": /* close the record, refresh the list */ break;
       case "invalid": /* show error.message by the form */ break;
+      case "duplicate": /* adopt the existing row, or show error.fields by the form */ break;
       case "unauthenticated": /* send to sign-in */ break;
       default: /* show error.message */
     }
@@ -354,3 +388,151 @@ leave; asks with `window.confirm` otherwise). For other state,
 `useUnsavedChangesGuard({ when, message, confirm })` gives the same
 `confirmLeave` and `beforeunload` handling. Neither depends on a router; see
 genesis-ui's SKILL.md "Unsaved changes" for React Router and TanStack Router.
+
+## Autosave a draft
+
+`useDraft` saves one row as someone edits it: an answer to a questionnaire, a
+note, a journal entry. The app supplies the writes (`create`, `update`), so it
+works with any backend. What it guarantees:
+
+- **When it saves:** a moment after the last change (`delayMs`, default 800).
+  Only one write runs at a time. The first save adds the row and later ones
+  change it. Nothing is written when the value is unchanged, and no row is
+  added for an empty value (`isEmpty`).
+- **Another tab started the row:** the first write fails as a duplicate (a
+  `duplicate` write outcome, or `isDuplicate`). `adopt` then merges into that
+  row, writing only the fields changed here (`dirty`), or reports it already
+  finished, and the draft stops.
+- **The server's copy wins** (sent elsewhere, returned by a reviewer): pass a
+  new `revision`. The draft starts again from `seed`, and `discarded` tells the
+  page that unsaved edits were dropped. `onRevision` can merge them instead.
+  A new revision that is only this draft's own save coming back (the same row,
+  holding what was saved) keeps every edit, so a revision built from the row's
+  id is safe across the first save's refetch. A revision that brings another
+  row first saves the edits pending here to the row they belong to (`idOf`,
+  default `row.id`).
+  `key` changes whenever the value is replaced from outside, so remount the
+  editor on it.
+- **Failures:** network failures are retried with backoff. Refusals
+  (forbidden, gone, invalid) aren't retried; they set `status: "error"` and a
+  plain `error`.
+- **Leaving the page** saves what's pending: on `pagehide` and `beforeunload`
+  (with `keepalive` passed to `update`), and on unmount.
+- **`commit(write)`** is the final write, a submit. It waits for any write in
+  flight and stops autosave once it succeeds. If it fails, autosave carries on.
+- **`enabled: false`** writes nothing: someone else's draft, or one already
+  sent.
+
+```tsx
+const draft = useDraft({
+  seed: { row: entry, value: entry?.answers ?? {} },
+  revision: `${entry?.id}:${entry?.status}`,
+  enabled: entry?.status !== "sent",
+  create: (answers) => api.addEntry(answers),
+  update: (row, answers) => api.saveEntry(row.id, answers),
+  toValue: (row) => row.answers,
+  onSaved: (row) => queryClient.setQueryData(["entry", row.id], row),
+});
+
+<Editor key={draft.key} value={draft.value} onChange={draft.set} />
+<Button onClick={() => draft.commit((row, answers) => api.send(row, answers))}>Send</Button>
+```
+
+`DraftController` is the same logic without React, for tests or other
+frameworks.
+
+## Query keys
+
+Build every cache key in one place, so a write invalidates what it made stale and nothing cached for
+one person shows to another.
+
+```ts
+import { ViewerScope, defineQueryKeys, resourceKeys } from "@marktiderman/genesis-core";
+
+export const worksheetKeys = defineQueryKeys("worksheet-items", {
+  // The fields that make one query distinct. Sort arrays: order never makes two keys.
+  lessonParts: (people: string[]) => ({ people: [...people].sort() }),
+  byEntry: (entryId: string) => ({ entryId }),
+});
+
+// Reading: keys exist only for a scope. `viewer` is required; `group` and `day` when the read depends on them.
+useQuery({ queryKey: worksheetKeys.for({ viewer: userId, group: practiceId }).lessonParts(people), queryFn });
+
+// Invalidating:
+queryClient.invalidateQueries({ queryKey: worksheetKeys.all });              // the whole domain
+queryClient.invalidateQueries({ queryKey: worksheetKeys.lessonParts.all });  // one kind
+queryClient.invalidateQueries(worksheetKeys.where({ people: personId }));    // every key with this person, multi-person keys included
+queryClient.invalidateQueries(worksheetKeys.where({ entryId }, "byEntry"));  // narrowed to one query
+queryClient.invalidateQueries({ queryKey: resourceKeys("tasks").all });      // what useResource / useOne cache
+
+// Once, around the signed-in app: screens mount only for a known viewer, and a sign-out or a new
+// person unmounts them and empties the cache first. (Resource keys carry no viewer; this keeps them apart.)
+<ViewerScope viewer={session === undefined ? undefined : (session?.user.id ?? null)}>
+  <App />
+</ViewerScope>
+```
+
+Keys are `[domain, kind, { ...fields, viewer, group?, day? }]`. `where(fields, kind?)` matches a
+field that is equal (`1` matches `"1"`; objects in any key order), an array field containing the
+value, or for an array value an array field containing every item. Never a substring.
+
+With a persisted cache (a native app's saved query cache), pass the viewer it was saved for as
+`persistedViewer`, or the first known viewer empties it on every cold start. Without `ViewerScope`, call `clearViewerCache(queryClient)` in the sign-in and
+sign-out actions, before the session changes: it also sends the old viewer's waiting undoable
+writes while the session is still theirs. `ViewerScope` drops those unsent writes instead (by then the
+session is the new viewer's), so prefer `clearViewerCache` in a sign-out action when undo is on.
+
+## One-off writes
+
+For the writes a resource page doesn't make: a database function, "one live row per key", or a few
+writes in a row. They fail with a `DataWriteError` in plain words, like the provider's own writes.
+
+```ts
+import { callRpc, createOrAdopt, useWrite } from "@marktiderman/genesis-core";
+
+// A database function. Your words for a code win; a guard's own `raise exception` (P0001) keeps its
+// words; 42501, 22023 and a missing function get plain defaults; anything else a generic sentence.
+await callRpc(supabase, "release_step", { item_id }, { messages: { "55000": "This course hasn't started yet." } });
+
+// One live row per key: create it, or adopt the row already there (merging in what you return).
+const { row, adopted } = await createOrAdopt(provider, "lesson_notes", { person_id, lesson_id, body }, {
+  key: ["person_id", "lesson_id"],
+  merge: (existing) => (existing.body ? null : { body }),
+});
+
+// In a component: pending, plain error words, and invalidation after a success.
+const release = useWrite((itemId: string) => callRpc(supabase, "release_step", { item_id: itemId }), {
+  invalidates: [["course-steps"], resourceKeys("tasks").all],
+});
+<Button onClick={() => release.fire(id)} disabled={release.pending}>Release</Button>
+```
+
+`run(args)` rejects on failure; `fire(args)` never does (the error shows in `error`). One write runs at a
+time: a second click while it runs gets the same promise, not a second write.
+
+## Days and time zones (`/dates`)
+
+A day is a `YYYY-MM-DD` string: the date on one time zone's clock. `new Date().toISOString().slice(0, 10)`
+gives the day in UTC. For an evening in the Americas that is already tomorrow, and for a morning in
+Asia it is still yesterday. A server's own zone is usually UTC too. `@marktiderman/genesis-core/dates`
+always takes the zone, so you can't fall into that by accident:
+
+```ts
+import { personDay, dayIn, dayRangeIn, addDays, startOfWeek } from "@marktiderman/genesis-core/dates";
+
+const today = personDay(profile);                 // the person's saved zone, else the device's, else UTC
+const yesterday = addDays(today, -1);
+const week = startOfWeek(today);                  // Monday; startOfWeek(today, 0) for Sunday
+const { start, end } = dayRangeIn(today, profile.timeZone); // the instants, for created_at >= start and < end
+```
+
+- `personDay(person, at?)` and `personTimeZone(person)`: the person's `timeZone` when the runtime
+  knows it, else `deviceTimeZone()`, else UTC. On a server, always pass the person's zone.
+- `dayIn(zone, at?)` and `wallClock(zone, at?)`: what the calendar and the clock say in `zone`.
+- `startOfDayIn(day, zone)` and `dayRangeIn(day, zone)`: the instants a day starts and ends.
+  Daylight-saving days are 23 or 25 hours long, and where midnight is skipped the day starts at the
+  first instant that exists.
+- `addDays`, `daysBetween`, `weekdayOf`, `startOfWeek` and `isDay`: plain calendar arithmetic on
+  `YYYY-MM-DD` strings, with no zone involved. They refuse days that don't exist, such as `2026-02-30`.
+
+In SQL, the same day is `(now() at time zone person_zone)::date`.

package/dist/chunk-52T2EYXH.js

@@ -0,0 +1,52 @@
+import { isDataWriteError } from './chunk-LG6TUBVM.js';
+import { useQueryClient, useMutation } from '@tanstack/react-query';
+import { useRef, useCallback } from 'react';
+
+var WRITE_FAILED = "That didn't work. Try again.";
+function useWrite(write, options = {}) {
+  const queryClient = useQueryClient();
+  const mutation = useMutation(writeMutation(queryClient, write, options));
+  const { mutateAsync } = mutation;
+  const inFlight = useRef(null);
+  const run = useCallback(
+    (args) => {
+      if (inFlight.current) return inFlight.current;
+      const p = mutateAsync(args).finally(() => {
+        if (inFlight.current === p) inFlight.current = null;
+      });
+      inFlight.current = p;
+      return p;
+    },
+    [mutateAsync]
+  );
+  const fire = useCallback((args) => run(args).catch(() => void 0), [run]);
+  const messageOf = options.messageOf ?? plainMessage;
+  return {
+    run,
+    fire,
+    pending: mutation.isPending,
+    error: mutation.error === null ? null : messageOf(mutation.error),
+    reset: mutation.reset
+  };
+}
+function writeMutation(queryClient, write, options) {
+  return {
+    mutationFn: write,
+    onSuccess: async (result, args) => {
+      try {
+        const keys = typeof options.invalidates === "function" ? options.invalidates(result, args) : options.invalidates;
+        await Promise.all((keys ?? []).map((queryKey) => queryClient.invalidateQueries({ queryKey: [...queryKey] })));
+        options.onSuccess?.(result, args);
+      } catch (error) {
+        console.error("[genesis-core] useWrite: a callback after the write failed:", error);
+      }
+    }
+  };
+}
+function plainMessage(error) {
+  return isDataWriteError(error) && error.message ? error.message : WRITE_FAILED;
+}
+
+export { WRITE_FAILED, useWrite, writeMutation };
+//# sourceMappingURL=chunk-52T2EYXH.js.map
+//# sourceMappingURL=chunk-52T2EYXH.js.map

package/dist/chunk-52T2EYXH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-write.ts"],"names":[],"mappings":";;;;AAKO,IAAM,YAAA,GAAe;AAsCrB,SAAS,QAAA,CACd,KAAA,EACA,OAAA,GAAiC,EAAC,EACZ;AACtB,EAAA,MAAM,cAAc,cAAA,EAAe;AACnC,EAAA,MAAM,WAAW,WAAA,CAA2B,aAAA,CAAc,WAAA,EAAa,KAAA,EAAO,OAAO,CAAC,CAAA;AACtF,EAAA,MAAM,EAAE,aAAY,GAAI,QAAA;AAExB,EAAA,MAAM,QAAA,GAAW,OAA0B,IAAI,CAAA;AAC/C,EAAA,MAAM,GAAA,GAAM,WAAA;AAAA,IACV,CAAC,IAAA,KAAY;AACX,MAAA,IAAI,QAAA,CAAS,OAAA,EAAS,OAAO,QAAA,CAAS,OAAA;AACtC,MAAA,MAAM,CAAA,GAAI,WAAA,CAAY,IAAI,CAAA,CAAE,QAAQ,MAAM;AACxC,QAAA,IAAI,QAAA,CAAS,OAAA,KAAY,CAAA,EAAG,QAAA,CAAS,OAAA,GAAU,IAAA;AAAA,MACjD,CAAC,CAAA;AACD,MAAA,QAAA,CAAS,OAAA,GAAU,CAAA;AACnB,MAAA,OAAO,CAAA;AAAA,IACT,CAAA;AAAA,IACA,CAAC,WAAW;AAAA,GACd;AACA,EAAA,MAAM,IAAA,GAAO,WAAA,CAAY,CAAC,IAAA,KAAY,GAAA,CAAI,IAAI,CAAA,CAAE,KAAA,CAAM,MAAM,MAAS,CAAA,EAAG,CAAC,GAAG,CAAC,CAAA;AAC7E,EAAA,MAAM,SAAA,GAAY,QAAQ,SAAA,IAAa,YAAA;AACvC,EAAA,OAAO;AAAA,IACL,GAAA;AAAA,IACA,IAAA;AAAA,IACA,SAAS,QAAA,CAAS,SAAA;AAAA,IAClB,OAAO,QAAA,CAAS,KAAA,KAAU,OAAO,IAAA,GAAO,SAAA,CAAU,SAAS,KAAK,CAAA;AAAA,IAChE,OAAO,QAAA,CAAS;AAAA,GAClB;AACF;AAGO,SAAS,aAAA,CACd,WAAA,EACA,KAAA,EACA,OAAA,EACgC;AAChC,EAAA,OAAO;AAAA,IACL,UAAA,EAAY,KAAA;AAAA,IACZ,SAAA,EAAW,OAAO,MAAA,EAAQ,IAAA,KAAS;AAGjC,MAAA,IAAI;AACF,QAAA,MAAM,IAAA,GAAO,OAAO,OAAA,CAAQ,WAAA,KAAgB,UAAA,GAAa,QAAQ,WAAA,CAAY,MAAA,EAAQ,IAAI,CAAA,GAAI,OAAA,CAAQ,WAAA;AACrG,QAAA,MAAM,QAAQ,GAAA,CAAA,CAAK,IAAA,IAAQ,EAAC,EAAG,GAAA,CAAI,CAAC,QAAA,KAAa,WAAA,CAAY,iBAAA,CAAkB,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAA,EAAG,CAAC,CAAC,CAAA;AAC5G,QAAA,OAAA,CAAQ,SAAA,GAAY,QAAQ,IAAI,CAAA;AAAA,MAClC,SAAS,KAAA,EAAO;AACd,QAAA,OAAA,CAAQ,KAAA,CAAM,+DAA+D,KAAK,CAAA;AAAA,MACpF;AAAA,IACF;AAAA,GACF;AACF;AAEA,SAAS,aAAa,KAAA,EAAwB;AAC5C,EAAA,OAAO,iBAAiB,KAAK,CAAA,IAAK,KAAA,CAAM,OAAA,GAAU,MAAM,OAAA,GAAU,YAAA;AACpE","file":"chunk-52T2EYXH.js","sourcesContent":["import { useMutation, useQueryClient, type QueryClient, type MutationOptions } from \"@tanstack/react-query\";\nimport { useCallback, useRef } from \"react\";\nimport type { InvalidationKey } from \"../provider/types\";\nimport { isDataWriteError } from \"../schema/write-outcome\";\n\nexport const WRITE_FAILED = \"That didn't work. Try again.\";\n\nexport interface UseWriteOptions<A, R> {\n  /** Keys made stale once the write succeeds (matched by prefix), or a function of its result. */\n  invalidates?: InvalidationKey[] | ((result: R, args: A) => InvalidationKey[]);\n  onSuccess?: (result: R, args: A) => void;\n  /** The words shown for a failure. Default: a write error's own plain message. */\n  messageOf?: (error: unknown) => string;\n}\n\nexport interface UseWriteReturn<A, R> {\n  /**\n   * Runs the write. Resolves with its result; rejects with the error (also\n   * shown in `error`). While one runs, another call returns the same promise.\n   */\n  run: (args: A) => Promise<R>;\n  /** Runs the write and never rejects: resolves with the result, or undefined when it failed. */\n  fire: (args: A) => Promise<R | undefined>;\n  pending: boolean;\n  /** Why the last run failed, in plain words; null after a success or `reset`. */\n  error: string | null;\n  reset: () => void;\n}\n\n/**\n * A one-off write that isn't a resource page's create, update or remove: a\n * database function, `createOrAdopt`, several writes in a row. It invalidates\n * what it made stale and reports failures in plain words.\n *\n * ```ts\n * const sendLesson = useWrite(\n *   (lessonId: string) => callRpc(supabase, \"send_lesson\", { lesson_id: lessonId }),\n *   { invalidates: [[\"tasks\"], lessonKeys.all] },\n * );\n * <Button onClick={() => sendLesson.fire(id)} disabled={sendLesson.pending}>Send</Button>\n * {sendLesson.error && <InlineError>{sendLesson.error}</InlineError>}\n * ```\n */\nexport function useWrite<A = void, R = unknown>(\n  write: (args: A) => Promise<R>,\n  options: UseWriteOptions<A, R> = {},\n): UseWriteReturn<A, R> {\n  const queryClient = useQueryClient();\n  const mutation = useMutation<R, unknown, A>(writeMutation(queryClient, write, options));\n  const { mutateAsync } = mutation;\n  // One write at a time: a second click while it runs gets the same promise, not a second write.\n  const inFlight = useRef<Promise<R> | null>(null);\n  const run = useCallback(\n    (args: A) => {\n      if (inFlight.current) return inFlight.current;\n      const p = mutateAsync(args).finally(() => {\n        if (inFlight.current === p) inFlight.current = null;\n      });\n      inFlight.current = p;\n      return p;\n    },\n    [mutateAsync],\n  );\n  const fire = useCallback((args: A) => run(args).catch(() => undefined), [run]);\n  const messageOf = options.messageOf ?? plainMessage;\n  return {\n    run,\n    fire,\n    pending: mutation.isPending,\n    error: mutation.error === null ? null : messageOf(mutation.error),\n    reset: mutation.reset,\n  };\n}\n\n/** useWrite's mutation: run the write, then invalidate and call `onSuccess`. */\nexport function writeMutation<A, R>(\n  queryClient: QueryClient,\n  write: (args: A) => Promise<R>,\n  options: UseWriteOptions<A, R>,\n): MutationOptions<R, unknown, A> {\n  return {\n    mutationFn: write,\n    onSuccess: async (result, args) => {\n      // The write committed: a failing callback is logged, never reported as a failed write\n      // (the person would make it again).\n      try {\n        const keys = typeof options.invalidates === \"function\" ? options.invalidates(result, args) : options.invalidates;\n        await Promise.all((keys ?? []).map((queryKey) => queryClient.invalidateQueries({ queryKey: [...queryKey] })));\n        options.onSuccess?.(result, args);\n      } catch (error) {\n        console.error(\"[genesis-core] useWrite: a callback after the write failed:\", error);\n      }\n    },\n  };\n}\n\nfunction plainMessage(error: unknown): string {\n  return isDataWriteError(error) && error.message ? error.message : WRITE_FAILED;\n}\n"]}

package/dist/chunk-5ORRAXIV.js

@@ -0,0 +1,30 @@
+import { flushPendingWrites, dropPendingWrites } from './chunk-S2ZXUNXB.js';
+import { useQueryClient } from '@tanstack/react-query';
+import { useState, Fragment as Fragment$1 } from 'react';
+import { jsx, Fragment } from 'react/jsx-runtime';
+
+async function clearViewerCache(queryClient) {
+  await flushPendingWrites(queryClient);
+  await queryClient.cancelQueries();
+  queryClient.clear();
+}
+function ViewerScope({ viewer, persistedViewer, fallback = null, children }) {
+  const queryClient = useQueryClient();
+  const [mounted, setMounted] = useState(void 0);
+  if (viewer === void 0) return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+  if (viewer !== mounted) {
+    const keep = mounted === void 0 && persistedViewer !== void 0 && persistedViewer === viewer;
+    if (!keep) {
+      dropPendingWrites(queryClient);
+      void queryClient.cancelQueries();
+      queryClient.clear();
+    }
+    setMounted(viewer);
+    return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+  }
+  return /* @__PURE__ */ jsx(Fragment$1, { children }, viewer ?? "signed-out");
+}
+
+export { ViewerScope, clearViewerCache };
+//# sourceMappingURL=chunk-5ORRAXIV.js.map
+//# sourceMappingURL=chunk-5ORRAXIV.js.map

package/dist/chunk-5ORRAXIV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/viewer-scope.tsx"],"names":["Fragment"],"mappings":";;;;;AAUA,eAAsB,iBAAiB,WAAA,EAAyC;AAC9E,EAAA,MAAM,mBAAmB,WAAW,CAAA;AACpC,EAAA,MAAM,YAAY,aAAA,EAAc;AAChC,EAAA,WAAA,CAAY,KAAA,EAAM;AACpB;AA6BO,SAAS,YAAY,EAAE,MAAA,EAAQ,iBAAiB,QAAA,GAAW,IAAA,EAAM,UAAS,EAAqB;AACpG,EAAA,MAAM,cAAc,cAAA,EAAe;AAEnC,EAAA,MAAM,CAAC,OAAA,EAAS,UAAU,CAAA,GAAI,SAAoC,MAAS,CAAA;AAC3E,EAAA,IAAI,WAAW,MAAA,EAAW,uBAAO,GAAA,CAAAA,QAAAA,EAAA,EAAG,QAAA,EAAA,QAAA,EAAS,CAAA;AAC7C,EAAA,IAAI,WAAW,OAAA,EAAS;AACtB,IAAA,MAAM,IAAA,GAAO,OAAA,KAAY,MAAA,IAAa,eAAA,KAAoB,UAAa,eAAA,KAAoB,MAAA;AAG3F,IAAA,IAAI,CAAC,IAAA,EAAM;AAIT,MAAA,iBAAA,CAAkB,WAAW,CAAA;AAC7B,MAAA,KAAK,YAAY,aAAA,EAAc;AAC/B,MAAA,WAAA,CAAY,KAAA,EAAM;AAAA,IACpB;AACA,IAAA,UAAA,CAAW,MAAM,CAAA;AACjB,IAAA,uBAAO,GAAA,CAAAA,QAAAA,EAAA,EAAG,QAAA,EAAA,QAAA,EAAS,CAAA;AAAA,EACrB;AACA,EAAA,uBAAO,GAAA,CAACA,UAAA,EAAA,EAAuC,QAAA,EAAA,EAAzB,MAAA,IAAU,YAAwB,CAAA;AAC1D","file":"chunk-5ORRAXIV.js","sourcesContent":["import { useQueryClient, type QueryClient } from \"@tanstack/react-query\";\nimport { Fragment, useState, type ReactNode } from \"react\";\nimport { dropPendingWrites, flushPendingWrites } from \"./mutation-mode\";\n\n/**\n * Empties the query cache for a new viewer: sends the old viewer's waiting\n * undoable writes (the session is still theirs), cancels reads in flight,\n * then removes every query. Call it in the sign-in and sign-out actions,\n * before the session changes.\n */\nexport async function clearViewerCache(queryClient: QueryClient): Promise<void> {\n  await flushPendingWrites(queryClient);\n  await queryClient.cancelQueries();\n  queryClient.clear();\n}\n\nexport interface ViewerScopeProps {\n  /** The signed-in viewer's id, null when signed out, undefined while the session loads. */\n  viewer: string | null | undefined;\n  /**\n   * The viewer a persisted cache was saved for. When the first known viewer\n   * is this one, the restored cache is kept; otherwise it's emptied.\n   */\n  persistedViewer?: string | null;\n  /** Shown while the session loads (and for the one render a change takes). */\n  fallback?: ReactNode;\n  children: ReactNode;\n}\n\n/**\n * Keeps one viewer's cached data from ever showing to the next. Children\n * render only once the viewer is known, under a key of that viewer, so a\n * sign-out or a new person signing in unmounts every screen and its queries\n * before the cache is emptied and the new viewer's screens mount fresh. The\n * first known viewer empties a restored cache too, unless it's the\n * `persistedViewer` it was saved for.\n *\n * ```tsx\n * <ViewerScope viewer={session === undefined ? undefined : (session?.user.id ?? null)}>\n *   <App />\n * </ViewerScope>\n * ```\n */\nexport function ViewerScope({ viewer, persistedViewer, fallback = null, children }: ViewerScopeProps) {\n  const queryClient = useQueryClient();\n  // The viewer the children were last mounted for; undefined before the first.\n  const [mounted, setMounted] = useState<string | null | undefined>(undefined);\n  if (viewer === undefined) return <>{fallback}</>;\n  if (viewer !== mounted) {\n    const keep = mounted === undefined && persistedViewer !== undefined && persistedViewer === viewer;\n    // Nothing for the new viewer is mounted yet, so emptying now can't strand\n    // a fetch; the old viewer's screens unmount with this render.\n    if (!keep) {\n      // The session already belongs to the new viewer: the old one's unsent\n      // writes must never go out under it. (clearViewerCache, run before the\n      // session changes, sends them instead.)\n      dropPendingWrites(queryClient);\n      void queryClient.cancelQueries();\n      queryClient.clear();\n    }\n    setMounted(viewer);\n    return <>{fallback}</>;\n  }\n  return <Fragment key={viewer ?? \"signed-out\"}>{children}</Fragment>;\n}\n"]}

package/dist/{chunk-ZKMAU6NN.js → chunk-BGTXN2E6.js}

@@ -1,3 +1,4 @@
+import { resourceKeys } from './chunk-RCAP3Q4T.js';
 import { useLiveInvalidation } from './chunk-KXVHDK3Q.js';
 import { useDataProvider } from './chunk-GGSXSI6Z.js';
 import { useQuery } from '@tanstack/react-query';
@@ -11,7 +12,7 @@ function useOne(resource, id, options = {}) {
     live,
     isEnabled && id != null,
     id != null ? { id } : {},
-    [resource, "detail", id],
+    resourceKeys(resource).detailsOf(id),
     (event) => event.type === "changed" || !("id" in event) || event.id == null || String(event.id) === String(id)
   );
   return useQuery({
@@ -23,7 +24,7 @@ function useOne(resource, id, options = {}) {
     // — no error, no refetch, just absent data. `useResource`'s list key has
     // always included `select` (it keys on the whole `params` object); this
     // was the one place it did not.
-    queryKey: [resource, "detail", id, select],
+    queryKey: resourceKeys(resource).detail(id, select),
     queryFn: async () => {
       if (id == null) throw new Error("Missing id");
       const result = await provider.getOne(resource, { id, select });
@@ -34,5 +35,5 @@ function useOne(resource, id, options = {}) {
 }
 
 export { useOne };
-//# sourceMappingURL=chunk-ZKMAU6NN.js.map
-//# sourceMappingURL=chunk-ZKMAU6NN.js.map
+//# sourceMappingURL=chunk-BGTXN2E6.js.map
+//# sourceMappingURL=chunk-BGTXN2E6.js.map

package/dist/chunk-BGTXN2E6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-one.ts"],"names":[],"mappings":";;;;;AAiCO,SAAS,MAAA,CACd,QAAA,EACA,EAAA,EACA,OAAA,GAAyB,EAAC,EACP;AACnB,EAAA,MAAM,WAAW,eAAA,EAAgB;AAEjC,EAAA,MAAM,EAAE,MAAA,EAAQ,OAAA,EAAS,IAAA,EAAK,GAAI,OAAA;AAClC,EAAA,MAAM,SAAA,GAAY,OAAA,IAAW,CAAC,CAAC,EAAA;AAG/B,EAAA,mBAAA;AAAA,IACE,QAAA;AAAA,IACA,IAAA;AAAA,IACA,aAAa,EAAA,IAAM,IAAA;AAAA,IACnB,EAAA,IAAM,IAAA,GAAO,EAAE,EAAA,KAAO,EAAC;AAAA,IACvB,YAAA,CAAa,QAAQ,CAAA,CAAE,SAAA,CAAU,EAAE,CAAA;AAAA,IACnC,CAAC,KAAA,KAAU,KAAA,CAAM,IAAA,KAAS,SAAA,IAAa,EAAE,IAAA,IAAQ,KAAA,CAAA,IAAU,KAAA,CAAM,EAAA,IAAM,QAAQ,MAAA,CAAO,KAAA,CAAM,EAAE,CAAA,KAAM,OAAO,EAAE;AAAA,GAC/G;AAEA,EAAA,OAAO,QAAA,CAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IASjB,UAAU,YAAA,CAAa,QAAQ,CAAA,CAAE,MAAA,CAAO,IAAI,MAAM,CAAA;AAAA,IAClD,SAAS,YAAY;AACnB,MAAA,IAAI,EAAA,IAAM,IAAA,EAAM,MAAM,IAAI,MAAM,YAAY,CAAA;AAC5C,MAAA,MAAM,MAAA,GAAS,MAAM,QAAA,CAAS,MAAA,CAAU,UAAU,EAAE,EAAA,EAAI,QAAQ,CAAA;AAChE,MAAA,OAAO,MAAA,CAAO,IAAA;AAAA,IAChB,CAAA;AAAA,IACA,OAAA,EAAS;AAAA,GACV,CAAA;AACH","file":"chunk-BGTXN2E6.js","sourcesContent":["import { useQuery, type UseQueryResult } from \"@tanstack/react-query\";\nimport { useDataProvider } from \"../provider/context\";\nimport type { BaseRecord, Identifier } from \"../provider/types\";\nimport { useLiveInvalidation, type LiveOptions } from \"./use-live\";\nimport { resourceKeys } from \"../query-keys\";\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface UseOneOptions {\n  /** Supabase select/join syntax, e.g. \"*, author:profiles(name)\". */\n  select?: string;\n  /** Defaults to `!!id` — won't fetch when id is falsy. */\n  enabled?: boolean;\n  /**\n   * Keep the record current while mounted: refetch it when the provider\n   * reports a change to it (`DataProvider.subscribe`). See\n   * `UseResourceOptions.live`. Off by default.\n   */\n  live?: boolean | LiveOptions;\n}\n\n// ---------------------------------------------------------------------------\n// Hook\n// ---------------------------------------------------------------------------\n\n/**\n * Fetch a single record by id, powered by TanStack Query.\n *\n * Returns the full `UseQueryResult<T>` with the data unwrapped from the\n * provider's `GetOneResult` wrapper.\n */\nexport function useOne<T extends BaseRecord = BaseRecord>(\n  resource: string,\n  id: Identifier | undefined | null,\n  options: UseOneOptions = {},\n): UseQueryResult<T> {\n  const provider = useDataProvider();\n\n  const { select, enabled, live } = options;\n  const isEnabled = enabled ?? !!id;\n\n  // Only this record's events; `changed` (events may have been missed) too.\n  useLiveInvalidation(\n    resource,\n    live,\n    isEnabled && id != null,\n    id != null ? { id } : {},\n    resourceKeys(resource).detailsOf(id),\n    (event) => event.type === \"changed\" || !(\"id\" in event) || event.id == null || String(event.id) === String(id),\n  );\n\n  return useQuery<T>({\n    // `select` is part of the key because it is part of the REQUEST: two pages\n    // asking for the same record with different projections get different\n    // rows back, and keying only on the id makes them share one cache entry.\n    // Whichever mounted first wins for the whole staleTime window, and the\n    // other silently renders a record missing the joined fields it asked for\n    // — no error, no refetch, just absent data. `useResource`'s list key has\n    // always included `select` (it keys on the whole `params` object); this\n    // was the one place it did not.\n    queryKey: resourceKeys(resource).detail(id, select),\n    queryFn: async () => {\n      if (id == null) throw new Error(\"Missing id\");\n      const result = await provider.getOne<T>(resource, { id, select });\n      return result.data;\n    },\n    enabled: isEnabled,\n  });\n}\n"]}

package/dist/chunk-DF2UWEEB.js

@@ -0,0 +1,38 @@
+import { DraftController } from './chunk-HBAPYA5K.js';
+import { useRef, useState, useSyncExternalStore, useEffect } from 'react';
+
+function useDraft(options) {
+  const latest = useRef(options);
+  latest.current = options;
+  const [draft] = useState(() => new DraftController(() => latest.current));
+  const state = useSyncExternalStore(draft.subscribe, draft.getState, draft.getState);
+  useEffect(() => {
+    draft.reseed(options.seed, options.revision);
+  }, [draft, options.revision]);
+  useEffect(() => {
+    draft.sync();
+  }, [draft, options.enabled]);
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const beforeUnload = (event) => {
+      if (!draft.pending()) return;
+      void draft.flush({ keepalive: true });
+      event.preventDefault();
+    };
+    const pageHide = () => {
+      if (draft.pending()) void draft.flush({ keepalive: true });
+    };
+    window.addEventListener("beforeunload", beforeUnload);
+    window.addEventListener("pagehide", pageHide);
+    return () => {
+      window.removeEventListener("beforeunload", beforeUnload);
+      window.removeEventListener("pagehide", pageHide);
+      if (draft.pending()) void draft.flush();
+    };
+  }, [draft]);
+  return { ...state, set: draft.set, flush: draft.flush, commit: draft.commit };
+}
+
+export { useDraft };
+//# sourceMappingURL=chunk-DF2UWEEB.js.map
+//# sourceMappingURL=chunk-DF2UWEEB.js.map

package/dist/chunk-DF2UWEEB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-draft.ts"],"names":[],"mappings":";;;AAqCO,SAAS,SAAkC,OAAA,EAAmD;AACnG,EAAA,MAAM,MAAA,GAAS,OAAO,OAAO,CAAA;AAC7B,EAAA,MAAA,CAAO,OAAA,GAAU,OAAA;AAEjB,EAAA,MAAM,CAAC,KAAK,CAAA,GAAI,QAAA,CAAS,MAAM,IAAI,eAAA,CAAsB,MAAM,MAAA,CAAO,OAAO,CAAC,CAAA;AAC9E,EAAA,MAAM,QAAQ,oBAAA,CAAqB,KAAA,CAAM,WAAW,KAAA,CAAM,QAAA,EAAU,MAAM,QAAQ,CAAA;AAElF,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,KAAA,CAAM,MAAA,CAAO,OAAA,CAAQ,IAAA,EAAM,OAAA,CAAQ,QAAQ,CAAA;AAAA,EAG7C,CAAA,EAAG,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAC,CAAA;AAE5B,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,KAAA,CAAM,IAAA,EAAK;AAAA,EACb,CAAA,EAAG,CAAC,KAAA,EAAO,OAAA,CAAQ,OAAO,CAAC,CAAA;AAE3B,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACnC,IAAA,MAAM,YAAA,GAAe,CAAC,KAAA,KAA6B;AACjD,MAAA,IAAI,CAAC,KAAA,CAAM,OAAA,EAAQ,EAAG;AACtB,MAAA,KAAK,KAAA,CAAM,KAAA,CAAM,EAAE,SAAA,EAAW,MAAM,CAAA;AACpC,MAAA,KAAA,CAAM,cAAA,EAAe;AAAA,IACvB,CAAA;AACA,IAAA,MAAM,WAAW,MAAM;AACrB,MAAA,IAAI,KAAA,CAAM,SAAQ,EAAG,KAAK,MAAM,KAAA,CAAM,EAAE,SAAA,EAAW,IAAA,EAAM,CAAA;AAAA,IAC3D,CAAA;AACA,IAAA,MAAA,CAAO,gBAAA,CAAiB,gBAAgB,YAAY,CAAA;AACpD,IAAA,MAAA,CAAO,gBAAA,CAAiB,YAAY,QAAQ,CAAA;AAC5C,IAAA,OAAO,MAAM;AACX,MAAA,MAAA,CAAO,mBAAA,CAAoB,gBAAgB,YAAY,CAAA;AACvD,MAAA,MAAA,CAAO,mBAAA,CAAoB,YAAY,QAAQ,CAAA;AAE/C,MAAA,IAAI,KAAA,CAAM,OAAA,EAAQ,EAAG,KAAK,MAAM,KAAA,EAAM;AAAA,IACxC,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,KAAK,CAAC,CAAA;AAEV,EAAA,OAAO,EAAE,GAAG,KAAA,EAAO,GAAA,EAAK,KAAA,CAAM,GAAA,EAAK,KAAA,EAAO,KAAA,CAAM,KAAA,EAAO,MAAA,EAAQ,KAAA,CAAM,MAAA,EAAO;AAC9E","file":"chunk-DF2UWEEB.js","sourcesContent":["import { useEffect, useRef, useState, useSyncExternalStore } from \"react\";\nimport {\n  DraftController,\n  type DraftOptions,\n  type DraftState,\n  type DraftValue,\n} from \"./draft-controller\";\n\nexport interface UseDraftReturn<V extends DraftValue, R> extends DraftState<V, R> {\n  /** The editor's new value; saved a moment after the last change. */\n  set: (value: V) => void;\n  /** Save now. Never rejects; a failure shows in `status` and `error`. */\n  flush: () => Promise<void>;\n  /** The final write (a submit); see `DraftController.commit`. */\n  commit: DraftController<V, R>[\"commit\"];\n}\n\n/**\n * Autosave one draft row: saved a moment after each change, one write at a\n * time, added on the first save that has something in it, merged into a row\n * another tab started (`adopt`), and started again when the server's copy wins\n * (`revision`). Leaving the page saves what's pending (and warns while it\n * can't), and `commit` makes the final write. The app supplies the writes.\n *\n * ```tsx\n * const draft = useDraft({\n *   seed: { row: entry, value: entry?.answers ?? {} },\n *   revision: `${entry?.id}:${entry?.status}`,\n *   enabled: entry?.status !== \"sent\",\n *   create: (answers) => api.addEntry(answers),\n *   update: (row, answers) => api.saveEntry(row.id, answers),\n *   toValue: (row) => row.answers,\n *   onSaved: (row) => queryClient.setQueryData([\"entry\", row.id], row),\n * });\n * <Editor key={draft.key} value={draft.value} onChange={draft.set} />\n * ```\n */\nexport function useDraft<V extends DraftValue, R>(options: DraftOptions<V, R>): UseDraftReturn<V, R> {\n  const latest = useRef(options);\n  latest.current = options;\n  // Created once; reads the latest options on every use, so callbacks are never stale.\n  const [draft] = useState(() => new DraftController<V, R>(() => latest.current));\n  const state = useSyncExternalStore(draft.subscribe, draft.getState, draft.getState);\n\n  useEffect(() => {\n    draft.reseed(options.seed, options.revision);\n    // Only a new revision starts the draft again; a new seed object alone doesn't.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [draft, options.revision]);\n\n  useEffect(() => {\n    draft.sync();\n  }, [draft, options.enabled]);\n\n  useEffect(() => {\n    if (typeof window === \"undefined\") return;\n    const beforeUnload = (event: BeforeUnloadEvent) => {\n      if (!draft.pending()) return;\n      void draft.flush({ keepalive: true });\n      event.preventDefault();\n    };\n    const pageHide = () => {\n      if (draft.pending()) void draft.flush({ keepalive: true });\n    };\n    window.addEventListener(\"beforeunload\", beforeUnload);\n    window.addEventListener(\"pagehide\", pageHide);\n    return () => {\n      window.removeEventListener(\"beforeunload\", beforeUnload);\n      window.removeEventListener(\"pagehide\", pageHide);\n      // Leaving the page within the app: save what's pending.\n      if (draft.pending()) void draft.flush();\n    };\n  }, [draft]);\n\n  return { ...state, set: draft.set, flush: draft.flush, commit: draft.commit };\n}\n"]}

package/dist/{chunk-Y475Z7BM.js → chunk-EF5BKT4B.js}

@@ -1,6 +1,6 @@
 import { DataReadError, readFailureMessage } from './chunk-HUNGCTRA.js';
-import { isDataWriteError, DataWriteError } from './chunk-5NHR6ZXS.js';
 import { titleCase } from './chunk-RYEXWQFD.js';
+import { isDataWriteError, DataWriteError } from './chunk-LG6TUBVM.js';
 
 // src/provider/postgrest-errors.ts
 function readOutcomeFromCode(code) {
@@ -17,6 +17,7 @@ function writeOutcomeFromCode(code) {
   if (code === "PGRST116") return "gone";
   if (code === "PGRST301" || code === "PGRST302" || code === "PGRST303") return "unauthenticated";
   if (code === "28000" || code === "28P01") return "unauthenticated";
+  if (code === "23505") return "duplicate";
   if (/^2[23][0-9A-Z]{3}$/.test(code)) return "invalid";
   return "error";
 }
@@ -251,6 +252,35 @@ function createSupabaseProvider(client, options = {}) {
     await reportReadError(error, resource, operation);
   }
   const from = (resource) => client.from(resource);
+  function readName(resource) {
+    const source = configFor(resource).source;
+    return typeof source === "string" ? source : source ? source.rpc : resource;
+  }
+  async function tableValues(resource, values, id) {
+    const config = configFor(resource);
+    if (config.writeColumns) {
+      const allowed = new Set(config.writeColumns);
+      return Object.fromEntries(Object.entries(values).filter(([key]) => allowed.has(key)));
+    }
+    if (!config.source || id === void 0) return values;
+    const row = await readBack(resource, id);
+    if (!row) return values;
+    return Object.fromEntries(Object.entries(values).filter(([key]) => key in row));
+  }
+  function read(resource, columns, count) {
+    const config = configFor(resource);
+    const cols = columns ?? config.select ?? "*";
+    const source = config.source;
+    if (source && typeof source === "object") {
+      if (!client.rpc) {
+        throw new DataReadError("error", `[SupabaseProvider] "${resource}" reads from ${source.rpc}(), but the client has no rpc.`);
+      }
+      const builder = client.rpc(source.rpc, source.args?.() ?? {}, count ? { count } : void 0);
+      return builder.select(cols);
+    }
+    const table = client.from(source ?? resource);
+    return count ? table.select(cols, { count }) : table.select(cols);
+  }
   const configFor = (resource) => options.resources?.[resource] ?? {};
   const nounFor = (resource) => configFor(resource).noun ?? "record";
   function realtimeEnabled(resource) {
@@ -365,10 +395,7 @@ function createSupabaseProvider(client, options = {}) {
         return refuseCursor(resource, "the cursor was made for a different sort; start again from the first page (cursor: null).");
       }
     }
-    let query = from(resource).select(
-      params.select ?? "*",
-      ...cursor ? [] : [{ count: "exact" }]
-    );
+    let query = read(resource, params.select, cursor ? void 0 : "exact");
     query = applyFilters(query, params.filters);
     const search = searchClauses(resource, params);
     const keyset = after ? keysetClauses(after) : "";
@@ -429,10 +456,7 @@ function createSupabaseProvider(client, options = {}) {
         return getCursorPage(resource, params, configuredKey === void 0 ? "id" : configuredKey);
       }
       const run2 = (key) => {
-        let query = client.from(resource).select(
-          params.select ?? "*",
-          { count: "exact" }
-        );
+        let query = read(resource, params.select, "exact");
         query = applyFilters(query, params.filters);
         const clauses = searchClauses(resource, params);
         if (clauses) {
@@ -456,7 +480,7 @@ function createSupabaseProvider(client, options = {}) {
       };
       const guessKey = configuredKey === void 0 && !keylessResources.has(resource);
       let result = await run2(configuredKey ?? (keylessResources.has(resource) ? false : "id"));
-      if (guessKey && isMissingColumn(result.error, resource, "id")) {
+      if (guessKey && isMissingColumn(result.error, readName(resource), "id")) {
         keylessResources.add(resource);
         if (process.env.NODE_ENV !== "production") {
           console.warn(
@@ -469,13 +493,13 @@ function createSupabaseProvider(client, options = {}) {
       return { data: result.data ?? [], total: result.count ?? 0 };
     },
     async getOne(resource, params) {
-      const result = await client.from(resource).select(params.select ?? "*").eq("id", params.id).single();
+      const result = await read(resource, params.select).eq("id", params.id).single();
       await throwIfReadError(result, resource, "getOne");
       return { data: result.data };
     },
     async getMany(resource, params) {
       if (params.ids.length === 0) return { data: [] };
-      const result = await client.from(resource).select("*").in("id", params.ids);
+      const result = await read(resource, void 0).in("id", params.ids);
       await throwIfReadError(result, resource, "getMany");
       return { data: result.data ?? [] };
     },
@@ -555,10 +579,10 @@ function createSupabaseProvider(client, options = {}) {
       };
     },
     async create(resource, params) {
-      const row = await prepare(resource, params.data, {
+      const row = await tableValues(
         resource,
-        action: "create"
-      });
+        await prepare(resource, params.data, { resource, action: "create" })
+      );
       const override = configFor(resource).create;
       let record;
       if (override) {
@@ -587,11 +611,11 @@ function createSupabaseProvider(client, options = {}) {
     },
     async update(resource, params) {
       const { id } = params;
-      const row = await prepare(resource, params.data, {
+      const row = await tableValues(
         resource,
-        action: "update",
+        await prepare(resource, params.data, { resource, action: "update", id }),
         id
-      });
+      );
       const override = configFor(resource).update;
       let record;
       if (override) {
@@ -664,6 +688,60 @@ function createSupabaseProvider(client, options = {}) {
   return provider;
 }
 
-export { createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode };
-//# sourceMappingURL=chunk-Y475Z7BM.js.map
-//# sourceMappingURL=chunk-Y475Z7BM.js.map
+// src/provider/write-helpers.ts
+var DEFAULT_RPC_MESSAGES = {
+  "42501": "You can't do that.",
+  "22023": "That request isn't valid.",
+  "23505": "That already exists.",
+  "28000": "Sign in to continue.",
+  PGRST202: "That action isn't available.",
+  PGRST301: "Sign in to continue."
+};
+var RPC_FAILED = "That didn't work. Try again.";
+async function callRpc(client, fn, args = {}, options = {}) {
+  let result;
+  try {
+    result = await client.rpc(fn, args);
+  } catch (error) {
+    if (isDataWriteError(error)) throw error;
+    throw new DataWriteError("error", RPC_FAILED, { cause: error });
+  }
+  if (!result || typeof result !== "object") {
+    throw new DataWriteError("error", RPC_FAILED, { cause: new Error(`rpc ${fn} returned ${String(result)}`) });
+  }
+  if (!result.error) return result.data;
+  const mapped = toDataWriteError(result.error);
+  const code = mapped.code;
+  const custom = code !== void 0 ? options.messages?.[code] : void 0;
+  const raw = result.error.message;
+  const guardWords = typeof raw === "string" && raw.trim() ? raw : void 0;
+  const message = custom ?? (code === "P0001" ? guardWords : void 0) ?? (mapped.fields ? mapped.message : void 0) ?? (code !== void 0 ? DEFAULT_RPC_MESSAGES[code] : void 0) ?? RPC_FAILED;
+  throw new DataWriteError(mapped.outcome, message, { code, fields: mapped.fields, cause: result.error });
+}
+async function createOrAdopt(provider, resource, data, options) {
+  if (options.key.length === 0) throw new Error(`[genesis-core] createOrAdopt("${resource}") needs a key`);
+  try {
+    return { row: (await provider.create(resource, { data })).data, adopted: false };
+  } catch (error) {
+    if (!isDataWriteError(error) || error.outcome !== "duplicate") throw error;
+    if (error.fields && Object.keys(error.fields).some((field) => !options.key.includes(field))) throw error;
+    const filters = options.key.map((field) => {
+      const value = data[field];
+      if (value === null || value === void 0) return { field, operator: "is_null" };
+      if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+        throw new Error(`[genesis-core] createOrAdopt("${resource}") key field ${field} must be a string, number or boolean`);
+      }
+      return { field, operator: "eq", value };
+    });
+    const { data: rows } = await provider.getList(resource, { filters, pagination: { page: 1, perPage: 2 } });
+    if (rows.length !== 1) throw error;
+    const existing = rows[0];
+    const changes = options.merge?.(existing);
+    if (!changes || Object.keys(changes).length === 0) return { row: existing, adopted: true };
+    return { row: (await provider.update(resource, { id: existing.id, data: changes })).data, adopted: true };
+  }
+}
+
+export { DEFAULT_RPC_MESSAGES, RPC_FAILED, callRpc, createOrAdopt, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode };
+//# sourceMappingURL=chunk-EF5BKT4B.js.map
+//# sourceMappingURL=chunk-EF5BKT4B.js.map