@marktiderman/genesis-core 1.3.0 → 1.5.0

package/README.md

@@ -0,0 +1,223 @@
+# @marktiderman/genesis-core
+
+Genesis's platform-agnostic data layer: the `DataProvider` contract, providers
+(`createSupabaseProvider`, `createMockProvider`), the React roots that put a
+provider in context, and the hooks that read and write through it
+(`useResource`, `useOne`, `useResourceForm`).
+
+```bash
+pnpm add @marktiderman/genesis-core @tanstack/react-query react-hook-form zod @hookform/resolvers
+```
+
+## Mounting: share your app's query cache
+
+| Root | Query cache | Use when |
+| --- | --- | --- |
+| `DataProviderRoot` | **Your app's**: mount it inside your `QueryClientProvider` | The app already uses TanStack Query (most apps) |
+| `GenesisProvider` | **Its own new `QueryClient`**, unless you pass `queryClient` | Prototypes, mock data, apps with no query client yet |
+
+`GenesisProvider` without `queryClient` starts a second cache, so invalidating
+a key in app code doesn't refresh Genesis lists and vice versa. In an app that
+has a `QueryClientProvider`, do this:
+
+```tsx
+function DataRoot({ children }: { children: ReactNode }) {
+  const provider = useMemo(() => createSupabaseProvider(supabase, options), []);
+  return <DataProviderRoot provider={provider}>{children}</DataProviderRoot>;
+}
+// …inside <QueryClientProvider client={queryClient}>
+```
+
+Or `<GenesisProvider provider={provider} queryClient={queryClient}>`.
+
+Genesis query keys start with the resource name: `[resource, "list", params]` and
+`[resource, "detail", id, select]`. Invalidating `[resource]` refreshes all of them.
+
+## Supabase under RLS
+
+`createSupabaseProvider(client, options?)` reads and writes through the client
+you pass, under its session and row-level security. Writes never report a save
+that didn't happen:
+
+- **Zero rows is a failure.** `update` and `deleteOne` ask for the affected
+  rows. When RLS skips the row, the provider reads it back: still visible
+  throws `DataWriteError("forbidden")`; no longer visible throws
+  `DataWriteError("gone")`. (Under RLS, "deleted" and "hidden from you" look
+  the same, so both are `gone`.)
+- **Database errors are typed.** Every write error is a `DataWriteError` whose
+  `outcome` comes from its code (`writeOutcomeFromCode`), with the code on
+  `error.code` and the raw error as `cause`:
+
+  | Code | Outcome |
+  | --- | --- |
+  | `42501` (incl. "new row violates row-level security policy") | `forbidden` |
+  | `23***` (`23505` unique, `23503` foreign key, `23502` not null, `23514` check), `22***` | `invalid` |
+  | `PGRST301`–`PGRST303`, `28000`, `28P01` | `unauthenticated` |
+  | `PGRST116` | `gone` |
+  | anything else (`P0001` from a function, network failures) | `error`, with the database's message |
+
+- Reads are unchanged: a read error is still a plain `Error` with `code`.
+
+### Options
+
+```ts
+const provider = createSupabaseProvider(supabase, {
+  // Tables whose delete trigger moves the row to a recycle bin.
+  binTables: ["notes", "commitments"], // or (resource) => boolean
+  onWrite: async (event) => { /* { resource, kind, id, record? } after every committed write */ },
+  resources: {
+    projects: {
+      noun: "project", // "You can't change this project."
+      prepare: (values, { action, id }) => ({ name: String(values.name ?? "").trim() }),
+      create: async (row) => {
+        const { data, error } = await supabase.rpc("create_project", { _name: row.name });
+        if (error) throw error; // mapped by its code
+        return data; // the new id (read back) or the new row
+      },
+      invalidates: [["staff"], ["me"]],
+    },
+    customers: {
+      update: async (id, row) => {
+        const { data, error } = await supabase.rpc("update_customer", { _id: id, ...row });
+        if (error) throw error;
+        return data; // the row, its id, or nothing when no row changed
+      },
+    },
+    tasks: {
+      deleteMode: "bin",
+      toFormValues: (row) => ({ ...row, done: row.status === "done" }),
+      prepare: ({ done, ...rest }) => ({ ...rest, status: done ? "done" : "open" }),
+    },
+  },
+});
+```
+
+| Option | What it does |
+| --- | --- |
+| `binTables` / `resources[r].deleteMode: "bin"` | Recycle-bin delete: check the row is visible, delete it (asking for no rows, since a binning trigger reports none), read it back. Gone from view is success; still visible is `forbidden`; not visible to begin with is `gone`. Requires binned rows to drop out of the caller's view. `deleteMode: "hard"` opts a table back out. List every soft-delete table: one that isn't listed reports a successful bin as `gone`. |
+| `prepare(values, context)` | Runs before every create and update, overrides included. Gets a copy of the values; may be async. Throw `DataWriteError("invalid", message)` to refuse; nothing is sent. |
+| `create(row)` | Replaces the insert, e.g. a security-definer RPC. Return the row, or its id to have it read back. If the read-back fails, the create is still reported saved (with just the id), so nobody retries into a duplicate. |
+| `update(id, row)` | Replaces the update. Return the row, or its id (or `true`) to have it read back. Returning nothing (or `false`) means no row changed: the provider reads the row back and throws `forbidden` or `gone`, so a function that silently skips a row never reports a save. |
+| `toFormValues(row)` | Row → edit-form values, for a form shaped differently from its table. Served as `DataProvider.toFormValues`, which `useResourceForm` applies in edit mode. The reverse is `prepare`. |
+| `invalidates` | Other query keys a write makes stale, as a list or `(event) => keys`. Served as `DataProvider.invalidates`, which `useResource` and `useResourceForm` (and so `ResourcePage` and `ResourceForm`) invalidate after their writes, on top of `[resource]`. |
+| `onWrite(event)` | Called after every committed create, update and delete, including writes made straight through the provider. Awaited; if it throws, the error is logged and the write is still reported saved. |
+
+Both hooks also take an `invalidates` option for keys one screen cares about:
+`useResource("tasks", { invalidates: [["me"]] })`.
+
+### Handling failures
+
+```ts
+try {
+  await provider.update("projects", { id, data });
+} catch (error) {
+  if (isDataWriteError(error)) {
+    switch (error.outcome) {
+      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 "unauthenticated": /* send to sign-in */ break;
+      default: /* show error.message */
+    }
+  }
+}
+```
+
+### Races, and what the read-back can't tell you
+
+- A read-back runs after the write, so it reports what is true then. If
+  another session deletes the row in between, a refused update reads as
+  `gone`. Neither case ever reports success.
+- A bin delete of a row someone else deletes first reports success: the row
+  is gone from view, which is what was asked.
+- An update whose new row would fail the table's SELECT policy is refused by
+  Postgres (`42501`) and rolled back, so it surfaces as `forbidden`.
+- The provider addresses rows by an `id` column.
+
+## Write outcomes
+
+`DataWriteError`, `isDataWriteError` and `WriteOutcome` are exported from both
+the root and `@marktiderman/genesis-core/schema`. Check with
+`isDataWriteError(error)` rather than `instanceof`, which fails when two copies
+of the package are installed.
+
+### Field-level errors
+
+A `DataWriteError` may carry `fields`: field (column) name → a message safe to
+show by that input. `useResourceForm` puts each one on its field
+(`setError(field, { type: "server" })`), focuses the first, and sets
+`errors.root` to the error's message as the summary; a field the form does not
+show appears only in the summary.
+
+`createSupabaseProvider` fills `fields` where Postgres says which column it
+means (`fieldErrorsFromPostgrest`), and replaces the error's message with a
+plain sentence (the raw text stays on `cause`):
+
+| Code | Read from | Field message | Error message |
+| --- | --- | --- | --- |
+| `23505` unique | `details`: `Key (email)=(…) already exists.` | "This value is already in use." (several columns: "This combination is already in use.") | "Email is already in use." |
+| `23502` not null | `message`: `null value in column "title" …` | "This field is required." | "Title is required." |
+| `23503` foreign key (insert/update) | `details`: `Key (owner_id)=(…) is not present in table …` | "The selected item doesn't exist." | "Owner Id: the selected item doesn't exist." |
+
+Only plain column names are taken from the store's text; the values it echoes
+and constraint names never reach a message. Anything else (expression indexes,
+check constraints) is left unmapped. Your own provider or `prepare` rule can
+throw `new DataWriteError("invalid", "…", { fields: { slug: "Pick another slug." } })`.
+
+## Mutation modes
+
+`useResource` (its `create`, `update`, `remove`) and `useResourceForm` take
+`mutationMode`:
+
+| Mode | Cache | Provider | Returned promise / `onSuccess` |
+| --- | --- | --- | --- |
+| `"pessimistic"` (default) | refetched after the write | at once | after the write |
+| `"optimistic"` | patched at once; put back if the write fails | at once | at once |
+| `"undoable"` | patched at once; put back on undo or failure | after `undoDelayMs` (default 5000) unless undone | at once |
+
+- **Failures** in `optimistic` / `undoable` mode go to `onError` (the caller
+  was already told it worked, and the cache has been put back). Show them
+  there. `useResourceForm` also puts them on the form, if it is still open.
+- **The undo control is yours.** Core has no UI: `onUndoable(write)` is called
+  with `{ resource, kind, id, strategy, delayMs, undo(), commit() }`.
+  genesis-ui's `ResourceForm` and `ResourcePage` show a sonner toast with an
+  Undo button.
+- **A provider that serves `undo`** (`capabilities().undo === true` and an
+  `undo` method) gets an `undoable` write at once; `undo()` then calls
+  `provider.undo(resource, { auditId })` with the audit id the write returned
+  (`strategy: "provider"`). Without an audit id no undo is offered.
+- **Leaving sends.** When the hook unmounts during the delay (the form closes,
+  the route changes), waiting writes are sent at once, as React Admin does.
+  Closing or reloading the tab also sends them, and holds the page with the
+  browser's prompt so the requests can finish.
+- **What is patched:** an update merges the values into the row in every
+  cached list (`[resource, "list", …]`) and detail (`[resource, "detail", id,
+  …]`); a delete removes the row and lowers `total`. A create patches nothing
+  (its id and place in a sorted list are the server's), so `optimistic` /
+  `undoable` only change when it is sent and when the caller moves on. A
+  rollback restores only the row it patched, so concurrent writes on other
+  rows survive.
+- **Refetching waits.** While an optimistic or undoable write on a resource is
+  pending, the hooks hold off invalidating `[resource]`; the last write to
+  settle refetches. Other code that invalidates the resource (or a window-focus
+  refetch) during the delay shows the server's rows until then.
+
+```ts
+const tasks = useResource("tasks", {
+  mutationMode: "undoable",
+  onUndoable: (write) => toast("Deleted.", { action: { label: "Undo", onClick: () => void write.undo() } }),
+  onError: (error) => toast.error(error.message),
+});
+await tasks.remove(id); // resolves at once; sent in 5 s unless undone
+```
+
+## Unsaved changes
+
+`useResourceForm({ warnWhenUnsaved: true })` (default off) warns while the
+form is dirty: the browser's prompt on closing or reloading the tab, and
+`confirmLeave()` for in-app navigation. It returns `isDirty` (false again once
+a save succeeds or is handed off) and `confirmLeave()` (true when it is fine to
+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.

package/dist/chunk-5NHR6ZXS.js

@@ -0,0 +1,31 @@
+// src/schema/write-outcome.ts
+var DataWriteError = class extends Error {
+  outcome;
+  current;
+  currentVersion;
+  /** The store's own error code, when it gave one. */
+  code;
+  /**
+   * Per-field messages (field name → safe message), when the store said which
+   * values it rejected. See `DataWriteErrorOptions.fields`.
+   */
+  fields;
+  constructor(outcome, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "DataWriteError";
+    this.outcome = outcome;
+    this.current = options.current;
+    this.currentVersion = options.currentVersion;
+    if (options.code !== void 0) this.code = options.code;
+    if (options.fields && Object.keys(options.fields).length > 0) {
+      this.fields = Object.freeze({ ...options.fields });
+    }
+  }
+};
+function isDataWriteError(error) {
+  return error instanceof Error && error.name === "DataWriteError" && typeof error.outcome === "string";
+}
+
+export { DataWriteError, isDataWriteError };
+//# sourceMappingURL=chunk-5NHR6ZXS.js.map
+//# sourceMappingURL=chunk-5NHR6ZXS.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/write-outcome.ts"],"names":[],"mappings":";AAuDO,IAAM,cAAA,GAAN,cAA6B,KAAA,CAAM;AAAA,EAC/B,OAAA;AAAA,EACA,OAAA;AAAA,EACA,cAAA;AAAA;AAAA,EAEA,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA,MAAA;AAAA,EAET,WAAA,CAAY,OAAA,EAAuB,OAAA,EAAiB,OAAA,GAAiC,EAAC,EAAG;AACvF,IAAA,KAAA,CAAM,OAAA,EAAS,QAAQ,KAAA,KAAU,MAAA,GAAY,SAAY,EAAE,KAAA,EAAO,OAAA,CAAQ,KAAA,EAAO,CAAA;AACjF,IAAA,IAAA,CAAK,IAAA,GAAO,gBAAA;AACZ,IAAA,IAAA,CAAK,OAAA,GAAU,OAAA;AACf,IAAA,IAAA,CAAK,UAAU,OAAA,CAAQ,OAAA;AACvB,IAAA,IAAA,CAAK,iBAAiB,OAAA,CAAQ,cAAA;AAC9B,IAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,IAAA,CAAK,OAAO,OAAA,CAAQ,IAAA;AACpD,IAAA,IAAI,OAAA,CAAQ,UAAU,MAAA,CAAO,IAAA,CAAK,QAAQ,MAAM,CAAA,CAAE,SAAS,CAAA,EAAG;AAC5D,MAAA,IAAA,CAAK,SAAS,MAAA,CAAO,MAAA,CAAO,EAAE,GAAG,OAAA,CAAQ,QAAQ,CAAA;AAAA,IACnD;AAAA,EACF;AACF;AAMO,SAAS,iBAAiB,KAAA,EAAyC;AACxE,EAAA,OACE,iBAAiB,KAAA,IACjB,KAAA,CAAM,SAAS,gBAAA,IACf,OAAQ,MAAgC,OAAA,KAAY,QAAA;AAExD","file":"chunk-5NHR6ZXS.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Why a write did not save (DATA-STUDIO.md \"Write safety\")\n//\n// A write that changes nothing is never reported as \"permission denied\" by\n// assumption. The provider re-reads the row and says what actually happened.\n// ---------------------------------------------------------------------------\n\nimport type { DataRow } from \"./types\";\n\n/**\n * - `conflict`: someone else changed the row since it was read. `current`\n *   carries the row as it is now.\n * - `gone`: the row was deleted, or is no longer visible to this user. The\n *   two cannot be told apart without a privileged look at the table, which\n *   would show this user a fact about a row they cannot see.\n * - `forbidden`: the row is visible and unchanged, but the app or the\n *   database does not let this user make this change. Only reported when\n *   that is proven, never assumed from \"zero rows changed\".\n * - `invalid`: the store rejected the value (type, constraint, not-null).\n * - `audit_failed`: the audit entry could not be written, so the edit was\n *   rolled back with it.\n * - `unauthenticated`: no signed-in user, or the session expired.\n * - `error`: anything else. The edit did not commit.\n */\nexport type WriteOutcome =\n  | \"conflict\"\n  | \"gone\"\n  | \"forbidden\"\n  | \"invalid\"\n  | \"audit_failed\"\n  | \"unauthenticated\"\n  | \"error\";\n\nexport interface DataWriteErrorOptions {\n  /** The row as it is now, for a `conflict`. Only fields the user may read. */\n  current?: DataRow;\n  /** The row's current version token, for a `conflict`. */\n  currentVersion?: string | null;\n  /**\n   * The store's own error code, when it gave one (a Postgres SQLSTATE such as\n   * `23505`, or a PostgREST code such as `PGRST301`).\n   */\n  code?: string;\n  /**\n   * Per-field messages, keyed by field (column) name, for a write the store\n   * rejected because of particular values. Each message is safe to show next\n   * to its input: plain words, never the store's raw text or the value.\n   * `useResourceForm` puts each one on its field.\n   */\n  fields?: Record<string, string>;\n  /** The underlying error, kept for logging. */\n  cause?: unknown;\n}\n\n/** Thrown by a provider when a write did not commit. */\nexport class DataWriteError extends Error {\n  readonly outcome: WriteOutcome;\n  readonly current?: DataRow;\n  readonly currentVersion?: string | null;\n  /** The store's own error code, when it gave one. */\n  readonly code?: string;\n  /**\n   * Per-field messages (field name → safe message), when the store said which\n   * values it rejected. See `DataWriteErrorOptions.fields`.\n   */\n  readonly fields?: Readonly<Record<string, string>>;\n\n  constructor(outcome: WriteOutcome, message: string, options: DataWriteErrorOptions = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = \"DataWriteError\";\n    this.outcome = outcome;\n    this.current = options.current;\n    this.currentVersion = options.currentVersion;\n    if (options.code !== undefined) this.code = options.code;\n    if (options.fields && Object.keys(options.fields).length > 0) {\n      this.fields = Object.freeze({ ...options.fields });\n    }\n  }\n}\n\n/**\n * `instanceof` fails when two copies of this package are installed, so check\n * the shape instead.\n */\nexport function isDataWriteError(error: unknown): error is DataWriteError {\n  return (\n    error instanceof Error &&\n    error.name === \"DataWriteError\" &&\n    typeof (error as { outcome?: unknown }).outcome === \"string\"\n  );\n}\n"]}

package/dist/chunk-7NUL32W7.js

@@ -0,0 +1,14 @@
+// src/hooks/related-keys.ts
+function relatedKeys(provider, event, extra) {
+  let fromProvider = [];
+  try {
+    fromProvider = provider.invalidates?.(event) ?? [];
+  } catch (error) {
+    console.error(`[genesis-core] invalidates failed for "${event.resource}":`, error);
+  }
+  return [...fromProvider, ...extra ?? []];
+}
+
+export { relatedKeys };
+//# sourceMappingURL=chunk-7NUL32W7.js.map
+//# sourceMappingURL=chunk-7NUL32W7.js.map

package/dist/chunk-7NUL32W7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/related-keys.ts"],"names":[],"mappings":";AAOO,SAAS,WAAA,CACd,QAAA,EACA,KAAA,EACA,KAAA,EACmB;AACnB,EAAA,IAAI,eAAkC,EAAC;AACvC,EAAA,IAAI;AACF,IAAA,YAAA,GAAe,QAAA,CAAS,WAAA,GAAc,KAAK,CAAA,IAAK,EAAC;AAAA,EACnD,SAAS,KAAA,EAAO;AACd,IAAA,OAAA,CAAQ,KAAA,CAAM,CAAA,uCAAA,EAA0C,KAAA,CAAM,QAAQ,MAAM,KAAK,CAAA;AAAA,EACnF;AACA,EAAA,OAAO,CAAC,GAAG,YAAA,EAAc,GAAI,KAAA,IAAS,EAAG,CAAA;AAC3C","file":"chunk-7NUL32W7.js","sourcesContent":["import type { DataProvider, InvalidationKey, WriteEvent } from \"../provider/types\";\n\n/**\n * The cache keys a committed write makes stale beyond `[resource]`: the\n * provider's own (`DataProvider.invalidates`) plus the caller's. A provider\n * that throws here is logged and skipped; the write already committed.\n */\nexport function relatedKeys(\n  provider: DataProvider,\n  event: WriteEvent,\n  extra: InvalidationKey[] | undefined,\n): InvalidationKey[] {\n  let fromProvider: InvalidationKey[] = [];\n  try {\n    fromProvider = provider.invalidates?.(event) ?? [];\n  } catch (error) {\n    console.error(`[genesis-core] invalidates failed for \"${event.resource}\":`, error);\n  }\n  return [...fromProvider, ...(extra ?? [])];\n}\n"]}

package/dist/chunk-BQOJX67X.js

@@ -0,0 +1,31 @@
+import { useDataProvider } from './chunk-GGSXSI6Z.js';
+import { useQuery } from '@tanstack/react-query';
+
+var providerIds = /* @__PURE__ */ new WeakMap();
+var nextProviderId = 1;
+function providerId(provider) {
+  let id = providerIds.get(provider);
+  if (id === void 0) {
+    id = nextProviderId++;
+    providerIds.set(provider, id);
+  }
+  return id;
+}
+function capabilitiesQueryKey(provider, resource) {
+  return ["__capabilities", providerId(provider), resource ?? ""];
+}
+function useCapabilities(resource, options = {}) {
+  const provider = useDataProvider();
+  return useQuery({
+    queryKey: capabilitiesQueryKey(provider, resource),
+    queryFn: () => provider.capabilities(resource),
+    enabled: (options.enabled ?? true) && !!provider.capabilities,
+    // Fresh for as long as this provider is in use; a swapped-out provider's
+    // entry has no observers and is collected after the usual gcTime.
+    staleTime: Infinity
+  });
+}
+
+export { capabilitiesQueryKey, useCapabilities };
+//# sourceMappingURL=chunk-BQOJX67X.js.map
+//# sourceMappingURL=chunk-BQOJX67X.js.map

package/dist/chunk-BQOJX67X.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-capabilities.ts"],"names":[],"mappings":";;;AAMA,IAAM,WAAA,uBAAkB,OAAA,EAAwB;AAChD,IAAI,cAAA,GAAiB,CAAA;AAErB,SAAS,WAAW,QAAA,EAA0B;AAC5C,EAAA,IAAI,EAAA,GAAK,WAAA,CAAY,GAAA,CAAI,QAAQ,CAAA;AACjC,EAAA,IAAI,OAAO,MAAA,EAAW;AACpB,IAAA,EAAA,GAAK,cAAA,EAAA;AACL,IAAA,WAAA,CAAY,GAAA,CAAI,UAAU,EAAE,CAAA;AAAA,EAC9B;AACA,EAAA,OAAO,EAAA;AACT;AAQO,SAAS,oBAAA,CAAqB,UAAkB,QAAA,EAAkD;AACvG,EAAA,OAAO,CAAC,gBAAA,EAAkB,UAAA,CAAW,QAAQ,CAAA,EAAG,YAAY,EAAE,CAAA;AAChE;AAOO,SAAS,eAAA,CACd,QAAA,EACA,OAAA,GAAiC,EAAC,EACI;AACtC,EAAA,MAAM,WAAW,eAAA,EAAgB;AACjC,EAAA,OAAO,QAAA,CAA+B;AAAA,IACpC,QAAA,EAAU,oBAAA,CAAqB,QAAA,EAAU,QAAQ,CAAA;AAAA,IACjD,OAAA,EAAS,MAAM,QAAA,CAAS,YAAA,CAAc,QAAQ,CAAA;AAAA,IAC9C,UAAU,OAAA,CAAQ,OAAA,IAAW,IAAA,KAAS,CAAC,CAAC,QAAA,CAAS,YAAA;AAAA;AAAA;AAAA,IAGjD,SAAA,EAAW;AAAA,GACZ,CAAA;AACH","file":"chunk-BQOJX67X.js","sourcesContent":["import { useQuery, type UseQueryResult } from \"@tanstack/react-query\";\nimport { useDataProvider } from \"../provider/context\";\nimport type { ProviderCapabilities } from \"../schema/types\";\n\n// A stable id per provider object, so capabilities cached for one provider\n// are never served for another that shares the same QueryClient.\nconst providerIds = new WeakMap<object, number>();\nlet nextProviderId = 1;\n\nfunction providerId(provider: object): number {\n  let id = providerIds.get(provider);\n  if (id === undefined) {\n    id = nextProviderId++;\n    providerIds.set(provider, id);\n  }\n  return id;\n}\n\n/**\n * The query key for `provider`'s capabilities for `resource`. It includes\n * the provider's identity: swapping the provider (another tenant, a\n * different store) asks the new one instead of reusing the old answer.\n * @internal\n */\nexport function capabilitiesQueryKey(provider: object, resource: string | undefined): readonly unknown[] {\n  return [\"__capabilities\", providerId(provider), resource ?? \"\"];\n}\n\n/**\n * What the data provider can do for `resource` (`provider.capabilities`),\n * cached per provider and resource. `data` stays undefined for a provider\n * that doesn't report capabilities, so a UI keeps its defaults.\n */\nexport function useCapabilities(\n  resource: string | undefined,\n  options: { enabled?: boolean } = {},\n): UseQueryResult<ProviderCapabilities> {\n  const provider = useDataProvider();\n  return useQuery<ProviderCapabilities>({\n    queryKey: capabilitiesQueryKey(provider, resource),\n    queryFn: () => provider.capabilities!(resource),\n    enabled: (options.enabled ?? true) && !!provider.capabilities,\n    // Fresh for as long as this provider is in use; a swapped-out provider's\n    // entry has no observers and is collected after the usual gcTime.\n    staleTime: Infinity,\n  });\n}\n"]}

package/dist/{chunk-QFTMHOEH.js → chunk-DVW5GXWZ.js}

@@ -1,6 +1,8 @@
-import { useDataProvider } from './chunk-6V2TIN3G.js';
+import { invalidateResource, useDelayedWrites, executeWrite, cachedRecord } from './chunk-QH4P5MI2.js';
+import { relatedKeys } from './chunk-7NUL32W7.js';
+import { useDataProvider } from './chunk-GGSXSI6Z.js';
 import { useState, useCallback, useMemo } from 'react';
-import { useQueryClient, useQuery, useMutation } from '@tanstack/react-query';
+import { useQueryClient, useQuery, keepPreviousData, useMutation } from '@tanstack/react-query';
 
 function stableFilterKey(filters) {
   if (!filters) return void 0;
@@ -19,21 +21,28 @@ function useResource(resource, options = {}) {
     defaultSort,
     defaultFilters,
     defaultPerPage = 25,
+    defaultPage = 1,
+    defaultSearch = "",
     select,
     searchFields: searchFieldsOption,
     enabled = true,
+    invalidates,
+    keepPreviousData: keepPreviousData$1 = false,
     onCreateSuccess,
     onUpdateSuccess,
     onDeleteSuccess,
-    onError
+    onError,
+    mutationMode = "pessimistic",
+    undoDelayMs,
+    onUndoable
   } = options;
   const provider = useDataProvider();
   const queryClient = useQueryClient();
   const [sort, setSortRaw] = useState(defaultSort);
   const [filters, setFiltersRaw] = useState(defaultFilters ?? []);
-  const [page, setPage] = useState(1);
+  const [page, setPage] = useState(Math.max(1, Math.floor(defaultPage)));
   const [perPage, setPerPageRaw] = useState(defaultPerPage);
-  const [searchQuery, setSearchQuery] = useState("");
+  const [searchQuery, setSearchQuery] = useState(defaultSearch);
   const defaultFiltersKey = stableFilterKey(defaultFilters);
   const [syncedFiltersKey, setSyncedFiltersKey] = useState(defaultFiltersKey);
   if (defaultFiltersKey !== syncedFiltersKey) {
@@ -76,11 +85,17 @@ function useResource(resource, options = {}) {
   const list = useQuery({
     queryKey: listQueryKey,
     queryFn: () => provider.getList(resource, params),
-    enabled
+    enabled,
+    placeholderData: keepPreviousData$1 ? keepPreviousData : void 0
   });
-  const invalidateResource = useCallback(
-    () => queryClient.invalidateQueries({ queryKey: [resource] }),
-    [queryClient, resource]
+  const invalidateAfter = useCallback(
+    (event) => {
+      void invalidateResource(queryClient, resource);
+      for (const queryKey of relatedKeys(provider, event, invalidates)) {
+        void queryClient.invalidateQueries({ queryKey: [...queryKey] });
+      }
+    },
+    [queryClient, resource, provider, invalidates]
   );
   const defaultOnError = useCallback(
     (error) => {
@@ -88,37 +103,75 @@ function useResource(resource, options = {}) {
     },
     [resource]
   );
+  const reportError = onError ?? defaultOnError;
+  const delayed = useDelayedWrites();
+  const modeArgs = {
+    queryClient,
+    provider,
+    resource,
+    mode: mutationMode,
+    undoDelayMs,
+    onUndoable,
+    delayed,
+    failedLater: reportError
+  };
   const createMutation = useMutation({
     mutationFn: async (data) => {
-      const result = await provider.create(resource, { data });
-      return result.data;
+      const outcome = await executeWrite({
+        ...modeArgs,
+        kind: "create",
+        data,
+        send: async () => {
+          const result = await provider.create(resource, { data });
+          return { record: result.data, audit: result.audit };
+        },
+        committed: (record) => {
+          invalidateAfter({ resource, kind: "create", id: record.id, record });
+          onCreateSuccess?.(record);
+        }
+      });
+      return outcome.status === "committed" ? outcome.record : data;
     },
-    onSuccess: (data) => {
-      invalidateResource();
-      onCreateSuccess?.(data);
-    },
-    onError: onError ?? defaultOnError
+    onError: reportError
   });
   const updateMutation = useMutation({
     mutationFn: async ({ id, data }) => {
-      const result = await provider.update(resource, { id, data });
-      return result.data;
-    },
-    onSuccess: (data) => {
-      invalidateResource();
-      onUpdateSuccess?.(data);
+      const before = cachedRecord(queryClient, resource, id);
+      const outcome = await executeWrite({
+        ...modeArgs,
+        kind: "update",
+        id,
+        data,
+        send: async () => {
+          const result = await provider.update(resource, { id, data });
+          return { record: result.data, audit: result.audit };
+        },
+        committed: (record) => {
+          invalidateAfter({ resource, kind: "update", id, record });
+          onUpdateSuccess?.(record);
+        }
+      });
+      return outcome.status === "committed" ? outcome.record : { ...before ?? {}, ...data, id: before?.id ?? id };
     },
-    onError: onError ?? defaultOnError
+    onError: reportError
   });
   const deleteMutation = useMutation({
     mutationFn: async (id) => {
-      await provider.deleteOne(resource, { id });
-    },
-    onSuccess: () => {
-      invalidateResource();
-      onDeleteSuccess?.();
+      await executeWrite({
+        ...modeArgs,
+        kind: "delete",
+        id,
+        send: async () => {
+          const result = await provider.deleteOne(resource, { id });
+          return { record: void 0, audit: result?.audit };
+        },
+        committed: () => {
+          invalidateAfter({ resource, kind: "delete", id });
+          onDeleteSuccess?.();
+        }
+      });
     },
-    onError: onError ?? defaultOnError
+    onError: reportError
   });
   const create = useCallback(
     (data) => createMutation.mutateAsync(data),
@@ -152,5 +205,5 @@ function useResource(resource, options = {}) {
 }
 
 export { useResource };
-//# sourceMappingURL=chunk-QFTMHOEH.js.map
-//# sourceMappingURL=chunk-QFTMHOEH.js.map
+//# sourceMappingURL=chunk-DVW5GXWZ.js.map
+//# sourceMappingURL=chunk-DVW5GXWZ.js.map

package/dist/chunk-DVW5GXWZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks/use-resource.ts"],"names":["keepPreviousData","keepPreviousPlaceholder"],"mappings":"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","file":"chunk-DVW5GXWZ.js","sourcesContent":["import { useState, useCallback, useMemo } from \"react\";\nimport {\n  keepPreviousData as keepPreviousPlaceholder,\n  useQuery,\n  useMutation,\n  useQueryClient,\n  type UseQueryResult,\n  type UseMutationResult,\n} from \"@tanstack/react-query\";\nimport { useDataProvider } from \"../provider/context\";\nimport type {\n  BaseRecord,\n  Identifier,\n  SortParam,\n  FilterParam,\n  ListParams,\n  ListResult,\n  InvalidationKey,\n  WriteEvent,\n} from \"../provider/types\";\nimport { relatedKeys } from \"./related-keys\";\nimport {\n  cachedRecord,\n  executeWrite,\n  invalidateResource,\n  useDelayedWrites,\n  type MutationModeOptions,\n} from \"./mutation-mode\";\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface UseResourceOptions<T> extends MutationModeOptions {\n  defaultSort?: SortParam;\n  /**\n   * Re-synced whenever its value changes (deep-equal, order-independent),\n   * not just its identity — safe to pass a scope/audience-derived array that\n   * changes across renders. This only covers CHANGES on an already-mounted\n   * hook, though: if this starts `undefined` while the real value resolves\n   * asynchronously, gate `enabled` on that same readiness signal too — the\n   * hook cannot tell \"no defaultFilters intended\" apart from \"not resolved\n   * yet,\" so an ungated hook's very first fetch can still run unscoped.\n   */\n  defaultFilters?: FilterParam[];\n  defaultPerPage?: number;\n  /** The page to start on (from 1), e.g. restored from the URL. Default 1. */\n  defaultPage?: number;\n  /** The search to start with, e.g. restored from the URL. Default \"\". */\n  defaultSearch?: string;\n  /** Supabase select/join syntax, e.g. \"*, author:profiles(name)\". */\n  select?: string;\n  /** Fields to search across when setSearch is called. Required for server-side search. */\n  searchFields?: string[];\n  /** Disable auto-fetching. */\n  enabled?: boolean;\n  /**\n   * Other query keys to invalidate after a create, update or delete, on top\n   * of `[resource]` and the provider's own `invalidates` (e.g. `[[\"me\"]]`\n   * when a write changes the signed-in user's roles).\n   */\n  invalidates?: InvalidationKey[];\n  /**\n   * While the next page / sort / search is loading, keep returning the\n   * previous result (`list.isPlaceholderData` is true meanwhile) instead of\n   * dropping to `undefined`. A paged list then stays on screen between pages\n   * rather than flashing a skeleton. Default false.\n   */\n  keepPreviousData?: boolean;\n  /**\n   * After the write commits, with the provider's row. In `optimistic` and\n   * `undoable` modes that is after `create` / `update` / `remove` have\n   * already resolved.\n   */\n  onCreateSuccess?: (data: T) => void;\n  onUpdateSuccess?: (data: T) => void;\n  onDeleteSuccess?: () => void;\n  /**\n   * A write failed. In `optimistic` and `undoable` modes this is the only\n   * place a failure is reported (the cache has already been put back), so\n   * show it to the user here.\n   */\n  onError?: (error: Error) => void;\n}\n\n// ---------------------------------------------------------------------------\n// Return type\n// ---------------------------------------------------------------------------\n\nexport interface UseResourceReturn<T> {\n  /** TanStack Query result for the list query. */\n  list: UseQueryResult<ListResult<T>>;\n  /** Current list params (pagination, sort, filters, search). */\n  params: ListParams;\n  setSort: (sort: SortParam | undefined) => void;\n  setFilters: (filters: FilterParam[]) => void;\n  setPage: (page: number) => void;\n  setPerPage: (perPage: number) => void;\n  setSearch: (query: string) => void;\n  /**\n   * Create a new record. Returns the created item. In `optimistic` and\n   * `undoable` modes it resolves at once with the values given (no `id` yet;\n   * `onCreateSuccess` gets the stored row).\n   */\n  create: (data: Partial<T>) => Promise<T>;\n  /**\n   * Update an existing record by id. Returns the updated item. In\n   * `optimistic` and `undoable` modes it resolves at once with the cached\n   * row merged with `data`.\n   */\n  update: (id: Identifier, data: Partial<T>) => Promise<T>;\n  /** Delete a record by id. Resolves at once in `optimistic` / `undoable` modes. */\n  remove: (id: Identifier) => Promise<void>;\n  /** True when any mutation is in-flight. */\n  isMutating: boolean;\n  createMutation: UseMutationResult<T, Error, Partial<T>>;\n  updateMutation: UseMutationResult<T, Error, { id: Identifier; data: Partial<T> }>;\n  deleteMutation: UseMutationResult<void, Error, Identifier>;\n}\n\n// ---------------------------------------------------------------------------\n// Filter identity — a deep-equality key independent of object-key order, so\n// a caller that rebuilds the same logical filters via a differently-ordered\n// spread (e.g. `{...base, operator: \"eq\"}` vs `{operator: \"eq\", ...base}`)\n// doesn't trip a spurious resync + pagination reset on an unrelated rerender.\n// ---------------------------------------------------------------------------\n\nfunction stableFilterKey(filters: FilterParam[] | undefined): string | undefined {\n  if (!filters) return undefined;\n  return JSON.stringify(\n    filters.map((f) => {\n      const sorted: Record<string, unknown> = {};\n      for (const key of Object.keys(f).sort()) {\n        sorted[key] = (f as unknown as Record<string, unknown>)[key];\n      }\n      return sorted;\n    }),\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Hook\n// ---------------------------------------------------------------------------\n\nexport function useResource<T extends BaseRecord = BaseRecord>(\n  resource: string,\n  options: UseResourceOptions<T> = {},\n): UseResourceReturn<T> {\n  const {\n    defaultSort,\n    defaultFilters,\n    defaultPerPage = 25,\n    defaultPage = 1,\n    defaultSearch = \"\",\n    select,\n    searchFields: searchFieldsOption,\n    enabled = true,\n    invalidates,\n    keepPreviousData = false,\n    onCreateSuccess,\n    onUpdateSuccess,\n    onDeleteSuccess,\n    onError,\n    mutationMode = \"pessimistic\",\n    undoDelayMs,\n    onUndoable,\n  } = options;\n\n  const provider = useDataProvider();\n  const queryClient = useQueryClient();\n\n  // -------------------------------------------------------------------------\n  // State\n  // -------------------------------------------------------------------------\n\n  const [sort, setSortRaw] = useState<SortParam | undefined>(defaultSort);\n  const [filters, setFiltersRaw] = useState<FilterParam[]>(defaultFilters ?? []);\n  const [page, setPage] = useState(Math.max(1, Math.floor(defaultPage)));\n  const [perPage, setPerPageRaw] = useState(defaultPerPage);\n  const [searchQuery, setSearchQuery] = useState(defaultSearch);\n\n  // `defaultFilters` often resolves asynchronously — a caller's scope/audience\n  // (team, project, ...) can still be loading on first render, so the array\n  // it passes in changes value (not just identity) after mount, and may later\n  // clear back to undefined (e.g. the scope itself is cleared). Re-syncing\n  // here, during render rather than in an effect, means `filters` is already\n  // correct by the time `params`/`list` below compute for this pass — no\n  // stray unscoped fetch on the frame before an effect would have caught up.\n  //\n  // This only closes the gap for `defaultFilters` CHANGING across renders on\n  // an already-mounted, already-enabled hook (e.g. a scope switch). It cannot\n  // help the very first render: `filters` still seeds from whatever\n  // `defaultFilters` is on mount, and `undefined` here is genuinely ambiguous\n  // between \"this caller never uses defaultFilters\" (in which case forcing a\n  // fetch to wait would break it forever) and \"the real value hasn't resolved\n  // yet.\" A caller in the second case MUST also gate `enabled` on that same\n  // readiness signal for its very first fetch to be correctly scoped — this\n  // hook has no way to tell the two cases apart on its own.\n  const defaultFiltersKey = stableFilterKey(defaultFilters);\n  const [syncedFiltersKey, setSyncedFiltersKey] = useState(defaultFiltersKey);\n  if (defaultFiltersKey !== syncedFiltersKey) {\n    setSyncedFiltersKey(defaultFiltersKey);\n    setFiltersRaw(defaultFilters ?? []);\n    setPage(1);\n  }\n\n  const setSort = useCallback((s: SortParam | undefined) => {\n    setSortRaw(s);\n    setPage(1);\n  }, []);\n\n  const setFilters = useCallback((f: FilterParam[]) => {\n    setFiltersRaw(f);\n    setPage(1);\n  }, []);\n\n  const setPerPage = useCallback((value: number) => {\n    setPerPageRaw(value);\n    setPage(1);\n  }, []);\n\n  const setSearch = useCallback((query: string) => {\n    setSearchQuery(query);\n    setPage(1);\n  }, []);\n\n  // -------------------------------------------------------------------------\n  // Params\n  // -------------------------------------------------------------------------\n\n  const params = useMemo<ListParams>(() => {\n    const p: ListParams = {\n      pagination: { page, perPage },\n      sort,\n      filters: filters.length > 0 ? filters : undefined,\n      select,\n    };\n    if (searchQuery && searchFieldsOption && searchFieldsOption.length > 0) {\n      p.search = { query: searchQuery, fields: searchFieldsOption };\n    }\n    return p;\n  }, [page, perPage, sort, filters, select, searchQuery, searchFieldsOption]);\n\n  // -------------------------------------------------------------------------\n  // List query\n  // -------------------------------------------------------------------------\n\n  const listQueryKey = useMemo(\n    () => [resource, \"list\", params] as const,\n    [resource, params],\n  );\n\n  const list = useQuery<ListResult<T>>({\n    queryKey: listQueryKey,\n    queryFn: () => provider.getList<T>(resource, params),\n    enabled,\n    placeholderData: keepPreviousData ? keepPreviousPlaceholder : undefined,\n  });\n\n  // -------------------------------------------------------------------------\n  // Mutations\n  // -------------------------------------------------------------------------\n\n  const invalidateAfter = useCallback(\n    (event: WriteEvent) => {\n      // Waits while an optimistic/undoable write on the resource is pending.\n      void invalidateResource(queryClient, resource);\n      for (const queryKey of relatedKeys(provider, event, invalidates)) {\n        void queryClient.invalidateQueries({ queryKey: [...queryKey] });\n      }\n    },\n    [queryClient, resource, provider, invalidates],\n  );\n\n  const defaultOnError = useCallback(\n    (error: Error) => {\n      console.error(`[useResource] ${resource} mutation failed:`, error.message);\n    },\n    [resource],\n  );\n  const reportError = onError ?? defaultOnError;\n\n  const delayed = useDelayedWrites();\n  const modeArgs = {\n    queryClient,\n    provider,\n    resource,\n    mode: mutationMode,\n    undoDelayMs,\n    onUndoable,\n    delayed,\n    failedLater: reportError,\n  };\n\n  const createMutation = useMutation<T, Error, Partial<T>>({\n    mutationFn: async (data) => {\n      const outcome = await executeWrite<T>({\n        ...modeArgs,\n        kind: \"create\",\n        data: data as Record<string, unknown>,\n        send: async () => {\n          const result = await provider.create<T>(resource, { data });\n          return { record: result.data, audit: result.audit };\n        },\n        committed: (record) => {\n          invalidateAfter({ resource, kind: \"create\", id: record.id, record });\n          onCreateSuccess?.(record);\n        },\n      });\n      return outcome.status === \"committed\" ? outcome.record : (data as T);\n    },\n    onError: reportError,\n  });\n\n  const updateMutation = useMutation<\n    T,\n    Error,\n    { id: Identifier; data: Partial<T> }\n  >({\n    mutationFn: async ({ id, data }) => {\n      const before = cachedRecord(queryClient, resource, id);\n      const outcome = await executeWrite<T>({\n        ...modeArgs,\n        kind: \"update\",\n        id,\n        data: data as Record<string, unknown>,\n        send: async () => {\n          const result = await provider.update<T>(resource, { id, data });\n          return { record: result.data, audit: result.audit };\n        },\n        committed: (record) => {\n          invalidateAfter({ resource, kind: \"update\", id, record });\n          onUpdateSuccess?.(record);\n        },\n      });\n      return outcome.status === \"committed\"\n        ? outcome.record\n        : ({ ...(before ?? {}), ...data, id: before?.id ?? id } as T);\n    },\n    onError: reportError,\n  });\n\n  const deleteMutation = useMutation<void, Error, Identifier>({\n    mutationFn: async (id) => {\n      await executeWrite<void>({\n        ...modeArgs,\n        kind: \"delete\",\n        id,\n        send: async () => {\n          const result = await provider.deleteOne(resource, { id });\n          return { record: undefined, audit: result?.audit };\n        },\n        committed: () => {\n          invalidateAfter({ resource, kind: \"delete\", id });\n          onDeleteSuccess?.();\n        },\n      });\n    },\n    onError: reportError,\n  });\n\n  // -------------------------------------------------------------------------\n  // Convenience wrappers\n  // -------------------------------------------------------------------------\n\n  const create = useCallback(\n    (data: Partial<T>) => createMutation.mutateAsync(data),\n    [createMutation],\n  );\n\n  const update = useCallback(\n    (id: Identifier, data: Partial<T>) =>\n      updateMutation.mutateAsync({ id, data }),\n    [updateMutation],\n  );\n\n  const remove = useCallback(\n    (id: Identifier) => deleteMutation.mutateAsync(id),\n    [deleteMutation],\n  );\n\n  const isMutating =\n    createMutation.isPending ||\n    updateMutation.isPending ||\n    deleteMutation.isPending;\n\n  return {\n    list,\n    params,\n    setSort,\n    setFilters,\n    setPage,\n    setPerPage,\n    setSearch,\n    create,\n    update,\n    remove,\n    isMutating,\n    createMutation,\n    updateMutation,\n    deleteMutation,\n  };\n}\n"]}

package/dist/{chunk-6V2TIN3G.js → chunk-GGSXSI6Z.js}

@@ -168,7 +168,8 @@ function GenesisProvider({
   children,
   provider,
   mock,
-  storage
+  storage,
+  queryClient: queryClientProp
 }) {
   if (provider && mock) {
     if (process.env.NODE_ENV !== "production") {
@@ -183,7 +184,7 @@ function GenesisProvider({
     );
   }, [provider, mock]);
   const queryClient = useMemo(
-    () => new QueryClient({
+    () => queryClientProp ?? new QueryClient({
       defaultOptions: {
         queries: {
           staleTime: 5 * 60 * 1e3
@@ -191,12 +192,12 @@ function GenesisProvider({
         }
       }
     }),
-    []
+    [queryClientProp]
   );
   const resolvedStorage = storage ?? defaultStorage;
   return /* @__PURE__ */ jsx(QueryClientProvider, { client: queryClient, children: /* @__PURE__ */ jsx(StorageContext.Provider, { value: resolvedStorage, children: /* @__PURE__ */ jsx(DataProviderRoot, { provider: resolvedProvider, children }) }) });
 }
 
 export { DataProviderRoot, GenesisProvider, createMockProvider, useDataProvider, useStorage };
-//# sourceMappingURL=chunk-6V2TIN3G.js.map
-//# sourceMappingURL=chunk-6V2TIN3G.js.map
+//# sourceMappingURL=chunk-GGSXSI6Z.js.map
+//# sourceMappingURL=chunk-GGSXSI6Z.js.map

package/dist/chunk-GGSXSI6Z.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/provider/mock-provider.ts","../src/provider/context.tsx"],"names":[],"mappings":"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","file":"chunk-GGSXSI6Z.js","sourcesContent":["import type {\n  DataProvider,\n  ListParams,\n  FilterParam,\n} from \"./types\";\n\n// ---------------------------------------------------------------------------\n// Mock DataProvider — operates on in-memory arrays, deep-cloned on creation\n// ---------------------------------------------------------------------------\n\nexport interface MockProviderOptions {\n  /** Simulated latency in ms (default 0). */\n  delay?: number;\n}\n\ntype Row = Record<string, unknown>;\n\nexport function createMockProvider(\n  datasets: Record<string, Row[]>,\n  options: MockProviderOptions = {},\n): DataProvider {\n  const { delay = 0 } = options;\n\n  // Deep clone so mutations don't affect the original data.\n  const store: Record<string, Row[]> = JSON.parse(JSON.stringify(datasets));\n\n  // Instance-scoped ID counter (NOT module-level).\n  let nextId = 1;\n\n  // ---------------------------------------------------------------------------\n  // Helpers\n  // ---------------------------------------------------------------------------\n\n  function getTable(resource: string): Row[] {\n    if (!store[resource]) {\n      store[resource] = [];\n    }\n    return store[resource];\n  }\n\n  async function withDelay<T>(value: T): Promise<T> {\n    if (delay > 0) {\n      await new Promise((r) => setTimeout(r, delay));\n    }\n    return value;\n  }\n\n  function matchesFilter(row: Row, filter: FilterParam): boolean {\n    const val = row[filter.field];\n\n    switch (filter.operator) {\n      case \"eq\":\n        return val === filter.value;\n      case \"neq\":\n        return val !== filter.value;\n      case \"gt\":\n        return (val as number) > (filter.value as number);\n      case \"lt\":\n        return (val as number) < (filter.value as number);\n      case \"gte\":\n        return (val as number) >= (filter.value as number);\n      case \"lte\":\n        return (val as number) <= (filter.value as number);\n      case \"contains\":\n        return typeof val === \"string\" &&\n          val.toLowerCase().includes(String(filter.value).toLowerCase());\n      case \"in\":\n        return filter.value.includes(val as string | number | boolean);\n      case \"is_null\":\n        return val === null || val === undefined;\n      case \"is_not_null\":\n        return val !== null && val !== undefined;\n      case \"between\": {\n        const [lo, hi] = filter.value;\n        return (val as number) >= (lo as number) && (val as number) <= (hi as number);\n      }\n    }\n  }\n\n  function matchesSearch(\n    row: Row,\n    search: { query: string; fields: string[] },\n  ): boolean {\n    const q = search.query.toLowerCase();\n    return search.fields.some((field) => {\n      const val = row[field];\n      return typeof val === \"string\" && val.toLowerCase().includes(q);\n    });\n  }\n\n  function compareValues(a: unknown, b: unknown): number {\n    if (typeof a === \"string\" && typeof b === \"string\") {\n      return a.localeCompare(b, undefined, { numeric: true });\n    }\n    if (typeof a === \"number\" && typeof b === \"number\") {\n      return a - b;\n    }\n    // Fallback: coerce to string.\n    return String(a ?? \"\").localeCompare(String(b ?? \"\"), undefined, {\n      numeric: true,\n    });\n  }\n\n  function applyListParams(table: Row[], params: ListParams): { data: Row[]; total: number } {\n    let rows = [...table];\n\n    // Filters (AND).\n    if (params.filters) {\n      for (const f of params.filters) {\n        rows = rows.filter((r) => matchesFilter(r, f));\n      }\n    }\n\n    // Search (OR across fields, AND with filters).\n    if (params.search && params.search.query) {\n      rows = rows.filter((r) => matchesSearch(r, params.search!));\n    }\n\n    const total = rows.length;\n\n    // Sort.\n    if (params.sort) {\n      const { field, order } = params.sort;\n      rows.sort((a, b) => {\n        const cmp = compareValues(a[field], b[field]);\n        return order === \"desc\" ? -cmp : cmp;\n      });\n    }\n\n    // Pagination (offset-based).\n    if (params.pagination) {\n      const { page, perPage } = params.pagination;\n      const start = (page - 1) * perPage;\n      rows = rows.slice(start, start + perPage);\n    }\n\n    return { data: rows, total };\n  }\n\n  // ---------------------------------------------------------------------------\n  // DataProvider implementation\n  // ---------------------------------------------------------------------------\n\n  const provider: DataProvider = {\n    async getList(_resource, params) {\n      const table = getTable(_resource);\n      const result = applyListParams(table, params);\n      return withDelay(result) as never;\n    },\n\n    async getOne(_resource, params) {\n      const table = getTable(_resource);\n      const row = table.find((r) => String(r.id) === String(params.id));\n      if (!row) {\n        throw new Error(\n          `[MockProvider] Record not found: ${_resource}#${params.id}`,\n        );\n      }\n      return withDelay({ data: JSON.parse(JSON.stringify(row)) }) as never;\n    },\n\n    async getMany(_resource, params) {\n      const table = getTable(_resource);\n      const idSet = new Set(params.ids.map(String));\n      const rows = table.filter((r) => idSet.has(String(r.id)));\n      return withDelay({ data: JSON.parse(JSON.stringify(rows)) }) as never;\n    },\n\n    async create(_resource, params) {\n      const table = getTable(_resource);\n      const id = String(nextId++);\n      const row = { id, ...params.data } as Row;\n      table.push(row);\n      return withDelay({ data: JSON.parse(JSON.stringify(row)) }) as never;\n    },\n\n    async update(_resource, params) {\n      const table = getTable(_resource);\n      const idx = table.findIndex((r) => String(r.id) === String(params.id));\n      if (idx === -1) {\n        throw new Error(\n          `[MockProvider] Record not found: ${_resource}#${params.id}`,\n        );\n      }\n      table[idx] = { ...table[idx], ...params.data };\n      return withDelay({ data: JSON.parse(JSON.stringify(table[idx])) }) as never;\n    },\n\n    async deleteOne(_resource, params) {\n      const table = getTable(_resource);\n      const idx = table.findIndex((r) => String(r.id) === String(params.id));\n      if (idx === -1) {\n        throw new Error(\n          `[MockProvider] Record not found: ${_resource}#${params.id}`,\n        );\n      }\n      table.splice(idx, 1);\n      return withDelay({ data: { id: params.id } });\n    },\n  };\n\n  return provider;\n}\n","import {\n  createContext,\n  useContext,\n  useMemo,\n  type ReactNode,\n} from \"react\";\nimport { QueryClient, QueryClientProvider } from \"@tanstack/react-query\";\nimport type { DataProvider } from \"./types\";\nimport { createMockProvider, type MockProviderOptions } from \"./mock-provider\";\nimport type { StorageAdapter } from \"../storage/types\";\nimport { createLocalStorageAdapter } from \"../storage/adapters\";\n\n// ---------------------------------------------------------------------------\n// Context\n// ---------------------------------------------------------------------------\n\nconst DataProviderContext = createContext<DataProvider | null>(null);\nconst StorageContext = createContext<StorageAdapter>(createLocalStorageAdapter());\n\n// ---------------------------------------------------------------------------\n// DataProviderRoot — thin context wrapper\n// ---------------------------------------------------------------------------\n\n/**\n * Puts a `DataProvider` in context, and nothing else. Mount it inside your\n * app's own `QueryClientProvider` and the Genesis hooks share that cache:\n * the same query keys (`[resource, \"list\", params]`,\n * `[resource, \"detail\", id, select]`), so invalidating `[resource]` from app\n * code refreshes Genesis lists too, and vice versa.\n */\nexport interface DataProviderRootProps {\n  provider: DataProvider;\n  children: ReactNode;\n}\n\nexport function DataProviderRoot({ provider, children }: DataProviderRootProps) {\n  return (\n    <DataProviderContext.Provider value={provider}>\n      {children}\n    </DataProviderContext.Provider>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Hook\n// ---------------------------------------------------------------------------\n\nexport function useDataProvider(): DataProvider {\n  const ctx = useContext(DataProviderContext);\n  if (!ctx) {\n    throw new Error(\n      \"useDataProvider must be used inside <DataProviderRoot> or <GenesisProvider>. \" +\n        \"Wrap your app (or the relevant subtree) in one of these providers.\",\n    );\n  }\n  return ctx;\n}\n\nexport function useStorage(): StorageAdapter {\n  return useContext(StorageContext);\n}\n\n// ---------------------------------------------------------------------------\n// GenesisProvider — convenience wrapper\n// ---------------------------------------------------------------------------\n\ntype Row = Record<string, unknown>;\n\nexport type GenesisProviderProps =\n  | {\n      children: ReactNode;\n      /** Pass a ready-made DataProvider. Mutually exclusive with `mock`. */\n      provider: DataProvider;\n      mock?: never;\n      /** Platform-specific storage adapter. Defaults to localStorage (SSR-safe). */\n      storage?: StorageAdapter;\n      /**\n       * The TanStack Query client to use. Without it, GenesisProvider creates\n       * its OWN client — a second cache beside any the app already has, so app\n       * queries and Genesis queries would not see each other's invalidations.\n       * An app with a `QueryClientProvider` should pass its client here, or\n       * use `DataProviderRoot` inside that provider instead.\n       */\n      queryClient?: QueryClient;\n    }\n  | {\n      children: ReactNode;\n      provider?: never;\n      /** Pass mock datasets. Mutually exclusive with `provider`. */\n      mock: {\n        datasets: Record<string, Row[]>;\n        options?: MockProviderOptions;\n      };\n      /** Platform-specific storage adapter. Defaults to localStorage (SSR-safe). */\n      storage?: StorageAdapter;\n      /** See the `provider` variant. */\n      queryClient?: QueryClient;\n    };\n\nconst defaultStorage = createLocalStorageAdapter();\n\n/**\n * Convenience root: a `QueryClientProvider`, storage, and a data provider\n * (yours, or a mock built from datasets). It creates its own `QueryClient`\n * unless you pass `queryClient`; an app that already has one should pass it,\n * or mount `DataProviderRoot` inside its existing `QueryClientProvider`.\n */\nexport function GenesisProvider({\n  children,\n  provider,\n  mock,\n  storage,\n  queryClient: queryClientProp,\n}: GenesisProviderProps) {\n  if (provider && mock) {\n    if (process.env.NODE_ENV !== \"production\") {\n      console.warn(\"[GenesisProvider] Both `provider` and `mock` were passed. `provider` takes precedence. This is likely a mistake.\");\n    }\n  }\n\n  // Build provider from mock datasets when no explicit provider is given.\n  const resolvedProvider = useMemo(() => {\n    if (provider) return provider;\n    if (mock) return createMockProvider(mock.datasets, mock.options);\n    throw new Error(\n      \"<GenesisProvider> requires either a `provider` or `mock` prop.\",\n    );\n  }, [provider, mock]);\n\n  // The caller's QueryClient, or an internal one with sensible defaults.\n  const queryClient = useMemo(\n    () =>\n      queryClientProp ??\n      new QueryClient({\n        defaultOptions: {\n          queries: {\n            staleTime: 5 * 60 * 1000, // 5 minutes\n          },\n        },\n      }),\n    [queryClientProp],\n  );\n\n  const resolvedStorage = storage ?? defaultStorage;\n\n  return (\n    <QueryClientProvider client={queryClient}>\n      <StorageContext.Provider value={resolvedStorage}>\n        <DataProviderRoot provider={resolvedProvider}>\n          {children}\n        </DataProviderRoot>\n      </StorageContext.Provider>\n    </QueryClientProvider>\n  );\n}\n"]}

package/dist/chunk-HT43MPKW.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-HT43MPKW.js.map
+//# sourceMappingURL=chunk-HT43MPKW.js.map

package/dist/{chunk-EL7YGOTY.js.map → chunk-HT43MPKW.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-EL7YGOTY.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-HT43MPKW.js"}