@marktiderman/genesis-core 1.4.0 → 1.5.0

package/dist/hooks/use-one.d.ts

@@ -1,5 +1,6 @@
 import { UseQueryResult } from '@tanstack/react-query';
-import { B as BaseRecord, I as Identifier } from '../types-zILrlHuV.js';
+import { B as BaseRecord, I as Identifier } from '../types-Dsqqr9s7.js';
+import '../types-C5bjsbxz.js';
 import '../form-types.js';
 
 interface UseOneOptions {

package/dist/hooks/use-resource-form.d.ts

@@ -1,8 +1,11 @@
 import { UseFormReturn } from 'react-hook-form';
 import { ResourceFormFieldDef } from '../form-types.js';
-import { p as InvalidationKey } from '../types-zILrlHuV.js';
+import { j as InvalidationKey } from '../types-Dsqqr9s7.js';
+import { MutationModeOptions } from './mutation-mode.js';
+import '../types-C5bjsbxz.js';
+import '@tanstack/react-query';
 
-interface UseResourceFormOptions {
+interface UseResourceFormOptions extends MutationModeOptions {
     resource: string;
     action: "create" | "edit";
     id?: string;
@@ -10,8 +13,27 @@ interface UseResourceFormOptions {
     fields?: ResourceFormFieldDef[];
     /** Full dataset used to auto-detect select fields from unique values. */
     listData?: Record<string, unknown>[];
+    /**
+     * The form is done. After the save in `pessimistic` mode (with the stored
+     * row); at once in `optimistic` and `undoable` modes (with the submitted
+     * values over the record, and no `id` for a create).
+     */
     onSuccess?: (data: Record<string, unknown>) => void;
+    /**
+     * The save failed. In `optimistic` and `undoable` modes the form may be
+     * gone by then, so show the error from here (genesis-ui's ResourceForm
+     * toasts it when no `onError` is given).
+     */
     onError?: (error: Error) => void;
+    /**
+     * Warn before unsaved changes are lost. Default false. While the form is
+     * dirty, closing or reloading the tab shows the browser's prompt, and
+     * `confirmLeave()` asks before in-app navigation (wire it to a router
+     * blocker; see SKILL.md "Unsaved changes").
+     */
+    warnWhenUnsaved?: boolean | {
+        message?: string;
+    };
     /**
      * Pre-fill create form defaults from URL query params: a param named like a
      * field (`?status=draft`) becomes that field's starting value. Default true.
@@ -48,6 +70,17 @@ interface UseResourceFormReturn {
     handleSave: (data: Record<string, unknown>) => Promise<void>;
     isSaving: boolean;
     isLoading: boolean;
+    /**
+     * The form has changes that have not been saved. False again once a save
+     * succeeds (or, in optimistic / undoable modes, is handed off).
+     */
+    isDirty: boolean;
+    /**
+     * For in-app navigation: true when it is fine to leave (nothing unsaved,
+     * `warnWhenUnsaved` off, or the user confirmed). Asks with
+     * `window.confirm` otherwise.
+     */
+    confirmLeave: () => boolean;
 }
 /** Build default values for a single array item from its sub-field definitions */
 declare function buildArrayItemDefaults(arrayFields: ResourceFormFieldDef[]): Record<string, unknown>;

package/dist/hooks/use-resource-form.js

@@ -1,7 +1,10 @@
-export { buildArrayItemDefaults, useResourceForm } from '../chunk-IHWWJUEN.js';
+export { buildArrayItemDefaults, useResourceForm } from '../chunk-IZT2O57C.js';
+import '../chunk-XQO4OH2N.js';
+import '../chunk-5NHR6ZXS.js';
 import '../chunk-RYEXWQFD.js';
-import '../chunk-ZK5C3OOT.js';
+import '../chunk-QH4P5MI2.js';
 import '../chunk-7NUL32W7.js';
+import '../chunk-ZK5C3OOT.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=use-resource-form.js.map

package/dist/hooks/use-resource.d.ts

@@ -1,8 +1,10 @@
 import { UseQueryResult, UseMutationResult } from '@tanstack/react-query';
-import { E as SortParam, k as FilterParam, p as InvalidationKey, q as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-zILrlHuV.js';
+import { m as SortParam, F as FilterParam, j as InvalidationKey, k as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-Dsqqr9s7.js';
+import { MutationModeOptions } from './mutation-mode.js';
+import '../types-C5bjsbxz.js';
 import '../form-types.js';
 
-interface UseResourceOptions<T> {
+interface UseResourceOptions<T> extends MutationModeOptions {
     defaultSort?: SortParam;
     /**
      * Re-synced whenever its value changes (deep-equal, order-independent),
@@ -15,6 +17,10 @@ interface UseResourceOptions<T> {
      */
     defaultFilters?: FilterParam[];
     defaultPerPage?: number;
+    /** The page to start on (from 1), e.g. restored from the URL. Default 1. */
+    defaultPage?: number;
+    /** The search to start with, e.g. restored from the URL. Default "". */
+    defaultSearch?: string;
     /** Supabase select/join syntax, e.g. "*, author:profiles(name)". */
     select?: string;
     /** Fields to search across when setSearch is called. Required for server-side search. */
@@ -34,9 +40,19 @@ interface UseResourceOptions<T> {
      * rather than flashing a skeleton. Default false.
      */
     keepPreviousData?: boolean;
+    /**
+     * After the write commits, with the provider's row. In `optimistic` and
+     * `undoable` modes that is after `create` / `update` / `remove` have
+     * already resolved.
+     */
     onCreateSuccess?: (data: T) => void;
     onUpdateSuccess?: (data: T) => void;
     onDeleteSuccess?: () => void;
+    /**
+     * A write failed. In `optimistic` and `undoable` modes this is the only
+     * place a failure is reported (the cache has already been put back), so
+     * show it to the user here.
+     */
     onError?: (error: Error) => void;
 }
 interface UseResourceReturn<T> {
@@ -49,11 +65,19 @@ interface UseResourceReturn<T> {
     setPage: (page: number) => void;
     setPerPage: (perPage: number) => void;
     setSearch: (query: string) => void;
-    /** Create a new record. Returns the created item. */
+    /**
+     * Create a new record. Returns the created item. In `optimistic` and
+     * `undoable` modes it resolves at once with the values given (no `id` yet;
+     * `onCreateSuccess` gets the stored row).
+     */
     create: (data: Partial<T>) => Promise<T>;
-    /** Update an existing record by id. Returns the updated item. */
+    /**
+     * Update an existing record by id. Returns the updated item. In
+     * `optimistic` and `undoable` modes it resolves at once with the cached
+     * row merged with `data`.
+     */
     update: (id: Identifier, data: Partial<T>) => Promise<T>;
-    /** Delete a record by id. */
+    /** Delete a record by id. Resolves at once in `optimistic` / `undoable` modes. */
     remove: (id: Identifier) => Promise<void>;
     /** True when any mutation is in-flight. */
     isMutating: boolean;

package/dist/hooks/use-resource.js

@@ -1,4 +1,5 @@
-export { useResource } from '../chunk-P4OIIRQS.js';
+export { useResource } from '../chunk-DVW5GXWZ.js';
+import '../chunk-QH4P5MI2.js';
 import '../chunk-7NUL32W7.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';

package/dist/hooks/use-unsaved-changes-guard.d.ts

@@ -0,0 +1,33 @@
+declare const DEFAULT_UNSAVED_CHANGES_MESSAGE = "You have unsaved changes. Leave without saving?";
+interface UseUnsavedChangesGuardOptions {
+    /** Guard while this is true (e.g. a form is dirty). */
+    when: boolean;
+    /** The question `confirmLeave` asks. */
+    message?: string;
+    /**
+     * How to ask. Default `window.confirm`. Must answer synchronously, since
+     * router blockers and `beforeunload` cannot wait.
+     */
+    confirm?: (message: string) => boolean;
+}
+interface UseUnsavedChangesGuardReturn {
+    /** True while leaving would lose changes. */
+    isBlocking: boolean;
+    /**
+     * Call before leaving in-app (closing a dialog, a router blocker). Returns
+     * true when it is fine to leave: nothing to lose, or the user said so.
+     */
+    confirmLeave: () => boolean;
+}
+/**
+ * Warns before unsaved changes are lost, without depending on a router.
+ *
+ * - While `when` is true, closing or reloading the tab shows the browser's
+ *   own "Leave site?" prompt (`beforeunload`).
+ * - `confirmLeave()` is for in-app navigation: wire it to your router's
+ *   blocker (React Router `useBlocker`, TanStack Router `useBlocker`), or call
+ *   it before closing a dialog. See SKILL.md "Unsaved changes".
+ */
+declare function useUnsavedChangesGuard(options: UseUnsavedChangesGuardOptions): UseUnsavedChangesGuardReturn;
+
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, type UseUnsavedChangesGuardOptions, type UseUnsavedChangesGuardReturn, useUnsavedChangesGuard };

package/dist/hooks/use-unsaved-changes-guard.js

@@ -0,0 +1,3 @@
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from '../chunk-XQO4OH2N.js';
+//# sourceMappingURL=use-unsaved-changes-guard.js.map
+//# sourceMappingURL=use-unsaved-changes-guard.js.map

package/dist/hooks/use-unsaved-changes-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"use-unsaved-changes-guard.js"}

package/dist/index.d.ts

@@ -1,13 +1,17 @@
-export { A as ArrayFilter, a as AuditEntry, B as BaseRecord, b as BulkChange, c as BulkResult, C as CreateParams, d as CreateResult, D as DataProvider, e as DataRow, f as DeleteParams, g as DeleteResult, F as FieldPermissions, h as FieldReference, i as FieldSchema, j as FilterOperator, k as FilterParam, G as GetManyParams, l as GetManyResult, m as GetOneParams, n as GetOneResult, H as HistoryParams, I as Identifier, o as ImportParams, p as InvalidationKey, L as ListParams, q as ListResult, N as NullFilter, P as PaginationParam, r as ProviderCapabilities, R as RangeFilter, s as RecordComment, t as ResourceAccess, u as ResourceContract, v as ResourceRelation, w as ResourceSchema, x as ResourceSummary, y as RowAction, z as RowFailure, S as ScalarFilter, E as SortParam, J as StorageType, U as UpdateParams, K as UpdateResult, V as VersionField, W as WriteEvent } from './types-zILrlHuV.js';
-export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from './write-outcome-BE3Tk6bA.js';
-export { DataProviderRoot, DataProviderRootProps, GenesisProvider, GenesisProviderProps, MockProviderOptions, SupabaseClient, SupabaseClientInput, SupabaseProviderOptions, SupabaseResourceConfig, SupabaseWriteContext, createMockProvider, createSupabaseProvider, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode } from './provider/index.js';
+export { A as ArrayFilter, B as BaseRecord, a as BulkChange, b as BulkResult, C as CreateParams, c as CreateResult, D as DataProvider, d as DeleteParams, e as DeleteResult, F as FilterParam, G as GetManyParams, f as GetManyResult, g as GetOneParams, h as GetOneResult, H as HistoryParams, I as Identifier, i as ImportParams, j as InvalidationKey, L as ListParams, k as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, l as RowFailure, S as ScalarFilter, m as SortParam, U as UpdateParams, n as UpdateResult, W as WriteEvent } from './types-Dsqqr9s7.js';
+export { D as DataReadError, a as DataReadErrorOptions, b as DataWriteError, c as DataWriteErrorOptions, R as ReadOutcome, W as WriteOutcome, i as isDataReadError, d as isDataWriteError, r as readFailureMessage } from './read-outcome-BQkYcV4t.js';
+export { DataProviderRoot, DataProviderRootProps, GenesisProvider, GenesisProviderProps, MockProviderOptions, PostgrestFieldErrors, SupabaseClient, SupabaseClientInput, SupabaseProviderOptions, SupabaseResourceConfig, SupabaseWriteContext, createMockProvider, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode } from './provider/index.js';
 export { S as StorageAdapter } from './types-DKcxHXxq.js';
 export { createLocalStorageAdapter, createMemoryStorageAdapter, createNoopStorageAdapter } from './storage/index.js';
 export { UseResourceOptions, UseResourceReturn, useResource } from './hooks/use-resource.js';
 export { UseOneOptions, useOne } from './hooks/use-one.js';
+export { useCapabilities } from './hooks/use-capabilities.js';
 export { UseResourceFormOptions, UseResourceFormReturn, buildArrayItemDefaults, useResourceForm } from './hooks/use-resource-form.js';
 export { UseWizardReturn, WizardStep, useWizard } from './hooks/use-wizard.js';
+export { DEFAULT_UNDO_DELAY_MS, MutationMode, MutationModeOptions, UndoableWrite, pendingWriteCount } from './hooks/mutation-mode.js';
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, UseUnsavedChangesGuardOptions, UseUnsavedChangesGuardReturn, useUnsavedChangesGuard } from './hooks/use-unsaved-changes-guard.js';
 export { FieldType, ResourceFormFieldDef, SelectOption, FieldType as WidgetHint } from './form-types.js';
+export { A as AuditEntry, D as DataRow, F as FieldPermissions, a as FieldReference, b as FieldSchema, c as FilterOperator, P as ProviderCapabilities, R as RecordComment, d as ResourceAccess, e as ResourceContract, f as ResourceRelation, g as ResourceSchema, h as ResourceSummary, i as RowAction, S as StorageType, V as VersionField } from './types-C5bjsbxz.js';
 export { decodeRecordKey, encodeRecordKey, keyFields } from './schema/index.js';
 export { titleCase } from './utils.js';
 import 'react';

package/dist/index.js

@@ -1,15 +1,19 @@
-export { createSupabaseProvider, toDataWriteError, writeOutcomeFromCode } from './chunk-NW26Z3LZ.js';
+export { createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from './chunk-RLY7TZUY.js';
 export { decodeRecordKey, encodeRecordKey, keyFields } from './chunk-KV2HW4G4.js';
-export { DataWriteError, isDataWriteError } from './chunk-6MBACQYA.js';
+export { DataReadError, isDataReadError, readFailureMessage } from './chunk-HUNGCTRA.js';
 import './chunk-XCX2TRBL.js';
 import './chunk-65SXNHWE.js';
-import './chunk-EL7YGOTY.js';
+import './chunk-HT43MPKW.js';
+export { buildArrayItemDefaults, useResourceForm } from './chunk-IZT2O57C.js';
+export { useResource } from './chunk-DVW5GXWZ.js';
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from './chunk-XQO4OH2N.js';
 export { useWizard } from './chunk-7KOLYF27.js';
-export { buildArrayItemDefaults, useResourceForm } from './chunk-IHWWJUEN.js';
+export { DataWriteError, isDataWriteError } from './chunk-5NHR6ZXS.js';
 export { titleCase } from './chunk-RYEXWQFD.js';
-export { useOne } from './chunk-ZK5C3OOT.js';
-export { useResource } from './chunk-P4OIIRQS.js';
+export { DEFAULT_UNDO_DELAY_MS, pendingWriteCount } from './chunk-QH4P5MI2.js';
 import './chunk-7NUL32W7.js';
+export { useCapabilities } from './chunk-BQOJX67X.js';
+export { useOne } from './chunk-ZK5C3OOT.js';
 export { DataProviderRoot, GenesisProvider, createMockProvider, useDataProvider, useStorage } from './chunk-GGSXSI6Z.js';
 export { createLocalStorageAdapter, createMemoryStorageAdapter, createNoopStorageAdapter } from './chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=index.js.map

package/dist/provider/index.d.ts

@@ -1,11 +1,12 @@
-import { D as DataProvider, I as Identifier, B as BaseRecord, p as InvalidationKey, W as WriteEvent } from '../types-zILrlHuV.js';
-export { A as ArrayFilter, b as BulkChange, c as BulkResult, C as CreateParams, d as CreateResult, f as DeleteParams, g as DeleteResult, k as FilterParam, G as GetManyParams, l as GetManyResult, m as GetOneParams, n as GetOneResult, H as HistoryParams, o as ImportParams, L as ListParams, q as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, z as RowFailure, S as ScalarFilter, E as SortParam, U as UpdateParams, K as UpdateResult } from '../types-zILrlHuV.js';
-import { D as DataWriteError, W as WriteOutcome } from '../write-outcome-BE3Tk6bA.js';
-export { a as DataWriteErrorOptions, i as isDataWriteError } from '../write-outcome-BE3Tk6bA.js';
+import { D as DataProvider, I as Identifier, B as BaseRecord, j as InvalidationKey, W as WriteEvent } from '../types-Dsqqr9s7.js';
+export { A as ArrayFilter, a as BulkChange, b as BulkResult, C as CreateParams, c as CreateResult, d as DeleteParams, e as DeleteResult, F as FilterParam, G as GetManyParams, f as GetManyResult, g as GetOneParams, h as GetOneResult, H as HistoryParams, i as ImportParams, L as ListParams, k as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, l as RowFailure, S as ScalarFilter, m as SortParam, U as UpdateParams, n as UpdateResult } from '../types-Dsqqr9s7.js';
+import { D as DataReadError, R as ReadOutcome, b as DataWriteError, W as WriteOutcome } from '../read-outcome-BQkYcV4t.js';
+export { a as DataReadErrorOptions, c as DataWriteErrorOptions, i as isDataReadError, d as isDataWriteError, r as readFailureMessage } from '../read-outcome-BQkYcV4t.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { QueryClient } from '@tanstack/react-query';
 import { S as StorageAdapter } from '../types-DKcxHXxq.js';
+import '../types-C5bjsbxz.js';
 import '../form-types.js';
 
 interface MockProviderOptions {
@@ -83,6 +84,23 @@ interface SupabaseWriteContext {
 interface SupabaseResourceConfig {
     /** Singular noun for failure messages, e.g. "project". Defaults to "record". */
     noun?: string;
+    /** Plural for list messages, when it isn't `noun` + "s" ("categories"). */
+    nounPlural?: string;
+    /**
+     * The columns a search covers. `[]` means the resource can't be searched,
+     * and `capabilities(resource).search` reports false so a UI hides the box.
+     * Set, they replace the caller's `search.fields`; omitted, those are used
+     * as given.
+     */
+    searchFields?: readonly string[];
+    /**
+     * The column a sorted list orders by last, so rows with equal sort values
+     * keep one order from page to page (none repeats, none is skipped).
+     * Default `"id"`; `false` for a table or view without one. With the
+     * default, a view that turns out to have no `id` column is read as before
+     * (without the key order) and a development warning suggests setting this.
+     */
+    orderKey?: string | false;
     /**
      * `"bin"` for a table whose delete trigger moves the row to a recycle bin
      * instead of removing it (see `SupabaseProviderOptions.binTables`).
@@ -140,6 +158,23 @@ interface SupabaseProviderOptions {
      * failure is logged and never turns a committed write into a failed one.
      */
     onWrite?: (event: WriteEvent) => void | Promise<void>;
+    /**
+     * The most rows one list page may ask for (PostgREST's `max-rows` caps
+     * reads anyway; default 1000). A larger request is refused with an
+     * `invalid` `DataReadError` (its `cause` says why) rather than cut short,
+     * so page boundaries never disagree with the caller's `perPage`.
+     * `capabilities().maxPerPage` reports it.
+     */
+    maxPerPage?: number;
+    /**
+     * Called with every failed read, before it is thrown. The thrown
+     * `DataReadError` carries a plain message for users; the store's own
+     * error (its raw text and code) is its `cause`, for logging here.
+     */
+    onReadError?: (error: DataReadError, context: {
+        resource: string;
+        operation: "getList" | "getOne" | "getMany";
+    }) => void | Promise<void>;
 }
 /**
  * The Supabase data provider. Reads and writes go through the client you
@@ -160,6 +195,12 @@ interface SupabaseProviderOptions {
  */
 declare function createSupabaseProvider(client: SupabaseClientInput, options?: SupabaseProviderOptions): DataProvider;
 
+/**
+ * Maps a store error code to the read outcome it means: the write mapping,
+ * with `22***` and PostgREST request errors (`PGRST1**` other than PGRST116,
+ * `42703` unknown column, `42P01` unknown table) read as `invalid`.
+ */
+declare function readOutcomeFromCode(code: string | null | undefined): ReadOutcome;
 /**
  * Maps a Postgres SQLSTATE or PostgREST error code to the write outcome it
  * means. Anything not listed is `error`: a code is only read as a refusal or
@@ -175,11 +216,42 @@ declare function createSupabaseProvider(client: SupabaseClientInput, options?: S
  * - `PGRST116` (one row was asked for and none came back) → `gone`
  */
 declare function writeOutcomeFromCode(code: string | null | undefined): WriteOutcome;
+/** Field errors read from a store error, with the safe sentence that sums them up. */
+interface PostgrestFieldErrors {
+    /** Column name → safe message for that input. */
+    fields: Record<string, string>;
+    /** One safe sentence for the whole error, to replace the store's raw text. */
+    message: string;
+}
+/**
+ * Reads which columns a Postgres constraint error is about, from PostgREST's
+ * `message` / `details`, and gives safe messages for them. Only plain column
+ * names are taken from the store's text; the values it echoes are never
+ * used. Returns `undefined` when nothing can be mapped safely.
+ *
+ * - `23505` unique violation, `Key (email)=(…) already exists.` → each
+ *   column: "This value is already in use." (several columns: "This
+ *   combination is already in use.")
+ * - `23502` not-null, `null value in column "title" …` → "This field is
+ *   required."
+ * - `23503` foreign key on insert/update, `Key (owner_id)=(…) is not present
+ *   in table …` → "The selected item doesn't exist."
+ */
+declare function fieldErrorsFromPostgrest(error: {
+    code?: unknown;
+    message?: unknown;
+    details?: unknown;
+}): PostgrestFieldErrors | undefined;
 /**
  * Turns anything a write threw, or the `{ message, code }` error a Supabase
  * client returned, into a `DataWriteError`. A `DataWriteError` passes through
  * unchanged; anything else keeps its message and `code`, and is kept as the
  * `cause`.
+ *
+ * When the error names the columns it is about (`fieldErrorsFromPostgrest`:
+ * unique, not-null and foreign-key violations), the result carries `fields`
+ * and its message is replaced with a safe sentence; the raw text stays on
+ * the `cause`.
  */
 declare function toDataWriteError(error: unknown): DataWriteError;
 
@@ -234,4 +306,4 @@ type GenesisProviderProps = {
  */
 declare function GenesisProvider({ children, provider, mock, storage, queryClient: queryClientProp, }: GenesisProviderProps): react.JSX.Element;
 
-export { BaseRecord, DataProvider, DataProviderRoot, type DataProviderRootProps, DataWriteError, GenesisProvider, type GenesisProviderProps, Identifier, InvalidationKey, type MockProviderOptions, type SupabaseClient, type SupabaseClientInput, type SupabaseProviderOptions, type SupabaseResourceConfig, type SupabaseWriteContext, WriteEvent, WriteOutcome, createMockProvider, createSupabaseProvider, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode };
+export { BaseRecord, DataProvider, DataProviderRoot, type DataProviderRootProps, DataReadError, DataWriteError, GenesisProvider, type GenesisProviderProps, Identifier, InvalidationKey, type MockProviderOptions, type PostgrestFieldErrors, ReadOutcome, type SupabaseClient, type SupabaseClientInput, type SupabaseProviderOptions, type SupabaseResourceConfig, type SupabaseWriteContext, WriteEvent, WriteOutcome, createMockProvider, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode };

package/dist/provider/index.js

@@ -1,5 +1,7 @@
-export { createSupabaseProvider, toDataWriteError, writeOutcomeFromCode } from '../chunk-NW26Z3LZ.js';
-export { DataWriteError, isDataWriteError } from '../chunk-6MBACQYA.js';
+export { createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from '../chunk-RLY7TZUY.js';
+export { DataReadError, isDataReadError, readFailureMessage } from '../chunk-HUNGCTRA.js';
+export { DataWriteError, isDataWriteError } from '../chunk-5NHR6ZXS.js';
+import '../chunk-RYEXWQFD.js';
 export { DataProviderRoot, GenesisProvider, createMockProvider, useDataProvider, useStorage } from '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=index.js.map

package/dist/read-outcome-BQkYcV4t.d.ts

@@ -0,0 +1,88 @@
+import { D as DataRow } from './types-C5bjsbxz.js';
+
+/**
+ * - `conflict`: someone else changed the row since it was read. `current`
+ *   carries the row as it is now.
+ * - `gone`: the row was deleted, or is no longer visible to this user. The
+ *   two cannot be told apart without a privileged look at the table, which
+ *   would show this user a fact about a row they cannot see.
+ * - `forbidden`: the row is visible and unchanged, but the app or the
+ *   database does not let this user make this change. Only reported when
+ *   that is proven, never assumed from "zero rows changed".
+ * - `invalid`: the store rejected the value (type, constraint, not-null).
+ * - `audit_failed`: the audit entry could not be written, so the edit was
+ *   rolled back with it.
+ * - `unauthenticated`: no signed-in user, or the session expired.
+ * - `error`: anything else. The edit did not commit.
+ */
+type WriteOutcome = "conflict" | "gone" | "forbidden" | "invalid" | "audit_failed" | "unauthenticated" | "error";
+interface DataWriteErrorOptions {
+    /** The row as it is now, for a `conflict`. Only fields the user may read. */
+    current?: DataRow;
+    /** The row's current version token, for a `conflict`. */
+    currentVersion?: string | null;
+    /**
+     * The store's own error code, when it gave one (a Postgres SQLSTATE such as
+     * `23505`, or a PostgREST code such as `PGRST301`).
+     */
+    code?: string;
+    /**
+     * Per-field messages, keyed by field (column) name, for a write the store
+     * rejected because of particular values. Each message is safe to show next
+     * to its input: plain words, never the store's raw text or the value.
+     * `useResourceForm` puts each one on its field.
+     */
+    fields?: Record<string, string>;
+    /** The underlying error, kept for logging. */
+    cause?: unknown;
+}
+/** Thrown by a provider when a write did not commit. */
+declare class DataWriteError extends Error {
+    readonly outcome: WriteOutcome;
+    readonly current?: DataRow;
+    readonly currentVersion?: string | null;
+    /** The store's own error code, when it gave one. */
+    readonly code?: string;
+    /**
+     * Per-field messages (field name → safe message), when the store said which
+     * values it rejected. See `DataWriteErrorOptions.fields`.
+     */
+    readonly fields?: Readonly<Record<string, string>>;
+    constructor(outcome: WriteOutcome, message: string, options?: DataWriteErrorOptions);
+}
+/**
+ * `instanceof` fails when two copies of this package are installed, so check
+ * the shape instead.
+ */
+declare function isDataWriteError(error: unknown): error is DataWriteError;
+
+/**
+ * - `unauthenticated`: no signed-in user, or the session expired.
+ * - `forbidden`: this user may not read these records.
+ * - `gone`: the one record asked for doesn't exist, or isn't visible.
+ * - `invalid`: the request itself was wrong (an unknown column, a bad value).
+ * - `error`: anything else.
+ */
+type ReadOutcome = "unauthenticated" | "forbidden" | "gone" | "invalid" | "error";
+interface DataReadErrorOptions {
+    /** The store's own error code (a Postgres SQLSTATE or PostgREST code). */
+    code?: string;
+    /** The underlying error, with its raw text, kept for logging. */
+    cause?: unknown;
+}
+/** Thrown by a provider when a read failed. Its `message` is safe to show. */
+declare class DataReadError extends Error {
+    readonly outcome: ReadOutcome;
+    /** The store's own error code, when it gave one. */
+    readonly code?: string;
+    constructor(outcome: ReadOutcome, message: string, options?: DataReadErrorOptions);
+}
+/**
+ * `instanceof` fails when two copies of this package are installed, so check
+ * the shape instead.
+ */
+declare function isDataReadError(error: unknown): error is DataReadError;
+/** The plain sentence for a failed read of `noun` records (one, or a list). */
+declare function readFailureMessage(outcome: ReadOutcome, noun: string, one: boolean, plural?: string): string;
+
+export { DataReadError as D, type ReadOutcome as R, type WriteOutcome as W, type DataReadErrorOptions as a, DataWriteError as b, type DataWriteErrorOptions as c, isDataWriteError as d, isDataReadError as i, readFailureMessage as r };

package/dist/schema/index.d.ts

@@ -1,6 +1,7 @@
-import { u as ResourceContract, I as Identifier, e as DataRow } from '../types-zILrlHuV.js';
-export { a as AuditEntry, F as FieldPermissions, h as FieldReference, i as FieldSchema, j as FilterOperator, r as ProviderCapabilities, s as RecordComment, t as ResourceAccess, v as ResourceRelation, w as ResourceSchema, x as ResourceSummary, y as RowAction, J as StorageType, V as VersionField } from '../types-zILrlHuV.js';
-export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-BE3Tk6bA.js';
+import { e as ResourceContract, D as DataRow } from '../types-C5bjsbxz.js';
+export { A as AuditEntry, F as FieldPermissions, a as FieldReference, b as FieldSchema, c as FilterOperator, P as ProviderCapabilities, R as RecordComment, d as ResourceAccess, f as ResourceRelation, g as ResourceSchema, h as ResourceSummary, i as RowAction, S as StorageType, V as VersionField } from '../types-C5bjsbxz.js';
+import { I as Identifier } from '../types-Dsqqr9s7.js';
+export { D as DataReadError, a as DataReadErrorOptions, b as DataWriteError, c as DataWriteErrorOptions, R as ReadOutcome, W as WriteOutcome, i as isDataReadError, d as isDataWriteError, r as readFailureMessage } from '../read-outcome-BQkYcV4t.js';
 export { FieldType as WidgetHint } from '../form-types.js';
 
 /** The key of a contract as a list, whichever form `key` was declared in. */

package/dist/schema/index.js

@@ -1,4 +1,5 @@
 export { decodeRecordKey, encodeRecordKey, keyFields } from '../chunk-KV2HW4G4.js';
-export { DataWriteError, isDataWriteError } from '../chunk-6MBACQYA.js';
+export { DataReadError, isDataReadError, readFailureMessage } from '../chunk-HUNGCTRA.js';
+export { DataWriteError, isDataWriteError } from '../chunk-5NHR6ZXS.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map