@marktiderman/genesis-core 1.7.0 → 1.9.0

package/dist/hooks/index.js

@@ -1,17 +1,21 @@
-import '../chunk-V3GDAELU.js';
-export { useInfiniteResource } from '../chunk-ADD2RIGA.js';
-export { buildArrayItemDefaults, useResourceForm } from '../chunk-Y3SCYMNN.js';
-import '../chunk-5NHR6ZXS.js';
-export { useOne } from '../chunk-ZKMAU6NN.js';
-export { useResource } from '../chunk-QFR6YJ3R.js';
-export { DEFAULT_LIVE_DEBOUNCE_MS } from '../chunk-KXVHDK3Q.js';
-export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from '../chunk-XQO4OH2N.js';
+export { ViewerScope, clearViewerCache } from '../chunk-5ORRAXIV.js';
+export { useResource } from '../chunk-NMFABW4Y.js';
 export { useWizard } from '../chunk-7KOLYF27.js';
-import '../chunk-RYEXWQFD.js';
-export { DEFAULT_UNDO_DELAY_MS, pendingWriteCount } from '../chunk-OBUBP4BY.js';
+export { WRITE_FAILED, useWrite } from '../chunk-52T2EYXH.js';
+export { useDraft } from '../chunk-DF2UWEEB.js';
+export { useInfiniteResource } from '../chunk-NZPJI7FC.js';
+export { buildArrayItemDefaults, useResourceForm } from '../chunk-OSPLIKSH.js';
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from '../chunk-XQO4OH2N.js';
+export { DEFAULT_UNDO_DELAY_MS, dropPendingWrites, flushPendingWrites, pendingWriteCount } from '../chunk-S2ZXUNXB.js';
+import '../chunk-7NUL32W7.js';
 export { useCapabilities } from '../chunk-BQOJX67X.js';
+export { useOne } from '../chunk-BGTXN2E6.js';
+import '../chunk-RCAP3Q4T.js';
+export { DEFAULT_LIVE_DEBOUNCE_MS } from '../chunk-KXVHDK3Q.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
-import '../chunk-7NUL32W7.js';
+import '../chunk-RYEXWQFD.js';
+export { DEFAULT_DRAFT_DELAY_MS, DRAFT_NOT_SAVED, DraftController, isNetworkFailure, stableJson } from '../chunk-HBAPYA5K.js';
+import '../chunk-LG6TUBVM.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/hooks/mutation-mode.d.ts

@@ -1,5 +1,5 @@
 import { QueryClient } from '@tanstack/react-query';
-import { I as Identifier, B as BaseRecord, D as DataProvider } from '../types-CS9UpxQS.js';
+import { a as Identifier, B as BaseRecord, D as DataProvider } from '../types-B9DDfvWa.js';
 import { A as AuditEntry } from '../types-C7FJtFXV.js';
 import '../form-types.js';
 
@@ -46,6 +46,18 @@ interface MutationModeOptions {
 declare function sameValue(a: unknown, b: unknown): boolean;
 /** The record as the cache has it now, from a detail entry or any list. */
 declare function cachedRecord(queryClient: QueryClient, resource: string, id: Identifier): BaseRecord | undefined;
+/**
+ * Sends every optimistic or undoable write still waiting on this client now,
+ * and resolves once all have settled. Call it while the session that made
+ * them still holds (a sign-out action, before signing out).
+ */
+declare function flushPendingWrites(queryClient: QueryClient): Promise<void>;
+/**
+ * Drops every write on this client not yet sent, without reporting them: the
+ * viewer who made them is gone, so they must never be sent (or re-applied)
+ * under the next one. Writes already sending finish under the old session.
+ */
+declare function dropPendingWrites(queryClient: QueryClient): void;
 /** Optimistic or undoable writes on `resource` not yet settled. */
 declare function pendingWriteCount(queryClient: QueryClient, resource: string): number;
 /**
@@ -116,4 +128,4 @@ declare const DROPPED_WRITE_MESSAGE = "This change was not saved: it was made on
  */
 declare function executeWrite<R extends BaseRecord | void>(args: ExecuteWriteArgs<R>): Promise<ExecuteWriteResult<R>>;
 
-export { DEFAULT_UNDO_DELAY_MS, DROPPED_WRITE_MESSAGE, type ExecuteWriteArgs, type ExecuteWriteResult, type MutationMode, type MutationModeOptions, type SendContext, type UndoableWrite, cachedRecord, executeWrite, invalidateResource, pendingWriteCount, providerServesUndo, sameValue };
+export { DEFAULT_UNDO_DELAY_MS, DROPPED_WRITE_MESSAGE, type ExecuteWriteArgs, type ExecuteWriteResult, type MutationMode, type MutationModeOptions, type SendContext, type UndoableWrite, cachedRecord, dropPendingWrites, executeWrite, flushPendingWrites, invalidateResource, pendingWriteCount, providerServesUndo, sameValue };

package/dist/hooks/mutation-mode.js

@@ -1,5 +1,6 @@
-export { DEFAULT_UNDO_DELAY_MS, DROPPED_WRITE_MESSAGE, cachedRecord, executeWrite, invalidateResource, pendingWriteCount, providerServesUndo, sameValue } from '../chunk-OBUBP4BY.js';
+export { DEFAULT_UNDO_DELAY_MS, DROPPED_WRITE_MESSAGE, cachedRecord, dropPendingWrites, executeWrite, flushPendingWrites, invalidateResource, pendingWriteCount, providerServesUndo, sameValue } from '../chunk-S2ZXUNXB.js';
 import '../chunk-BQOJX67X.js';
+import '../chunk-RCAP3Q4T.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=mutation-mode.js.map

package/dist/hooks/related-keys.d.ts

@@ -1,4 +1,4 @@
-import { D as DataProvider, W as WriteEvent, j as InvalidationKey } from '../types-CS9UpxQS.js';
+import { D as DataProvider, W as WriteEvent, I as InvalidationKey } from '../types-B9DDfvWa.js';
 import '../types-C7FJtFXV.js';
 import '../form-types.js';
 

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

@@ -0,0 +1,33 @@
+import { DraftValue, DraftState, DraftController, DraftOptions } from './draft-controller.js';
+
+interface UseDraftReturn<V extends DraftValue, R> extends DraftState<V, R> {
+    /** The editor's new value; saved a moment after the last change. */
+    set: (value: V) => void;
+    /** Save now. Never rejects; a failure shows in `status` and `error`. */
+    flush: () => Promise<void>;
+    /** The final write (a submit); see `DraftController.commit`. */
+    commit: DraftController<V, R>["commit"];
+}
+/**
+ * Autosave one draft row: saved a moment after each change, one write at a
+ * time, added on the first save that has something in it, merged into a row
+ * another tab started (`adopt`), and started again when the server's copy wins
+ * (`revision`). Leaving the page saves what's pending (and warns while it
+ * can't), and `commit` makes the final write. The app supplies the writes.
+ *
+ * ```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} />
+ * ```
+ */
+declare function useDraft<V extends DraftValue, R>(options: DraftOptions<V, R>): UseDraftReturn<V, R>;
+
+export { type UseDraftReturn, useDraft };

package/dist/hooks/use-draft.js

@@ -0,0 +1,5 @@
+export { useDraft } from '../chunk-DF2UWEEB.js';
+import '../chunk-HBAPYA5K.js';
+import '../chunk-LG6TUBVM.js';
+//# sourceMappingURL=use-draft.js.map
+//# sourceMappingURL=use-draft.js.map

package/dist/hooks/use-draft.js.map

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

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

@@ -1,5 +1,5 @@
 import { UseInfiniteQueryResult, InfiniteData } from '@tanstack/react-query';
-import { n as SortParam, F as FilterParam, k as ListResult, L as ListParams, B as BaseRecord } from '../types-CS9UpxQS.js';
+import { n as SortParam, F as FilterParam, k as ListResult, L as ListParams, B as BaseRecord } from '../types-B9DDfvWa.js';
 import { LiveOptions } from './use-live.js';
 import '../types-C7FJtFXV.js';
 import '../form-types.js';

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

@@ -1,4 +1,5 @@
-export { useInfiniteResource } from '../chunk-ADD2RIGA.js';
+export { useInfiniteResource } from '../chunk-NZPJI7FC.js';
+import '../chunk-RCAP3Q4T.js';
 import '../chunk-KXVHDK3Q.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';

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

@@ -1,5 +1,5 @@
 import { QueryKey } from '@tanstack/react-query';
-import { o as SubscribeParams, l as ResourceChangeEvent } from '../types-CS9UpxQS.js';
+import { o as SubscribeParams, l as ResourceChangeEvent } from '../types-B9DDfvWa.js';
 import '../types-C7FJtFXV.js';
 import '../form-types.js';
 

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

@@ -1,5 +1,5 @@
 import { UseQueryResult } from '@tanstack/react-query';
-import { B as BaseRecord, I as Identifier } from '../types-CS9UpxQS.js';
+import { B as BaseRecord, a as Identifier } from '../types-B9DDfvWa.js';
 import { LiveOptions } from './use-live.js';
 import '../types-C7FJtFXV.js';
 import '../form-types.js';

package/dist/hooks/use-one.js

@@ -1,4 +1,5 @@
-export { useOne } from '../chunk-ZKMAU6NN.js';
+export { useOne } from '../chunk-BGTXN2E6.js';
+import '../chunk-RCAP3Q4T.js';
 import '../chunk-KXVHDK3Q.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';

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

@@ -1,6 +1,6 @@
 import { UseFormReturn } from 'react-hook-form';
 import { ResourceFormFieldDef } from '../form-types.js';
-import { j as InvalidationKey } from '../types-CS9UpxQS.js';
+import { I as InvalidationKey } from '../types-B9DDfvWa.js';
 import { MutationModeOptions } from './mutation-mode.js';
 import '../types-C7FJtFXV.js';
 import '@tanstack/react-query';

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

@@ -1,13 +1,14 @@
-export { buildArrayItemDefaults, useResourceForm } from '../chunk-Y3SCYMNN.js';
-import '../chunk-5NHR6ZXS.js';
-import '../chunk-ZKMAU6NN.js';
-import '../chunk-KXVHDK3Q.js';
+export { buildArrayItemDefaults, useResourceForm } from '../chunk-OSPLIKSH.js';
 import '../chunk-XQO4OH2N.js';
-import '../chunk-RYEXWQFD.js';
-import '../chunk-OBUBP4BY.js';
+import '../chunk-S2ZXUNXB.js';
+import '../chunk-7NUL32W7.js';
 import '../chunk-BQOJX67X.js';
+import '../chunk-BGTXN2E6.js';
+import '../chunk-RCAP3Q4T.js';
+import '../chunk-KXVHDK3Q.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
-import '../chunk-7NUL32W7.js';
+import '../chunk-RYEXWQFD.js';
+import '../chunk-LG6TUBVM.js';
 //# sourceMappingURL=use-resource-form.js.map
 //# sourceMappingURL=use-resource-form.js.map

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

@@ -1,5 +1,5 @@
 import { UseQueryResult, UseMutationResult } from '@tanstack/react-query';
-import { n as SortParam, F as FilterParam, j as InvalidationKey, k as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-CS9UpxQS.js';
+import { n as SortParam, F as FilterParam, I as InvalidationKey, k as ListResult, L as ListParams, a as Identifier, B as BaseRecord } from '../types-B9DDfvWa.js';
 import { MutationModeOptions } from './mutation-mode.js';
 import { LiveOptions } from './use-live.js';
 import '../types-C7FJtFXV.js';

package/dist/hooks/use-resource.js

@@ -1,9 +1,10 @@
-export { useResource } from '../chunk-QFR6YJ3R.js';
-import '../chunk-KXVHDK3Q.js';
-import '../chunk-OBUBP4BY.js';
+export { useResource } from '../chunk-NMFABW4Y.js';
+import '../chunk-S2ZXUNXB.js';
+import '../chunk-7NUL32W7.js';
 import '../chunk-BQOJX67X.js';
+import '../chunk-RCAP3Q4T.js';
+import '../chunk-KXVHDK3Q.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
-import '../chunk-7NUL32W7.js';
 //# sourceMappingURL=use-resource.js.map
 //# sourceMappingURL=use-resource.js.map

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

@@ -0,0 +1,45 @@
+import { QueryClient, MutationOptions } from '@tanstack/react-query';
+import { I as InvalidationKey } from '../types-B9DDfvWa.js';
+import '../types-C7FJtFXV.js';
+import '../form-types.js';
+
+declare const WRITE_FAILED = "That didn't work. Try again.";
+interface UseWriteOptions<A, R> {
+    /** Keys made stale once the write succeeds (matched by prefix), or a function of its result. */
+    invalidates?: InvalidationKey[] | ((result: R, args: A) => InvalidationKey[]);
+    onSuccess?: (result: R, args: A) => void;
+    /** The words shown for a failure. Default: a write error's own plain message. */
+    messageOf?: (error: unknown) => string;
+}
+interface UseWriteReturn<A, R> {
+    /**
+     * Runs the write. Resolves with its result; rejects with the error (also
+     * shown in `error`). While one runs, another call returns the same promise.
+     */
+    run: (args: A) => Promise<R>;
+    /** Runs the write and never rejects: resolves with the result, or undefined when it failed. */
+    fire: (args: A) => Promise<R | undefined>;
+    pending: boolean;
+    /** Why the last run failed, in plain words; null after a success or `reset`. */
+    error: string | null;
+    reset: () => void;
+}
+/**
+ * A one-off write that isn't a resource page's create, update or remove: a
+ * database function, `createOrAdopt`, several writes in a row. It invalidates
+ * what it made stale and reports failures in plain words.
+ *
+ * ```ts
+ * const sendLesson = useWrite(
+ *   (lessonId: string) => callRpc(supabase, "send_lesson", { lesson_id: lessonId }),
+ *   { invalidates: [["tasks"], lessonKeys.all] },
+ * );
+ * <Button onClick={() => sendLesson.fire(id)} disabled={sendLesson.pending}>Send</Button>
+ * {sendLesson.error && <InlineError>{sendLesson.error}</InlineError>}
+ * ```
+ */
+declare function useWrite<A = void, R = unknown>(write: (args: A) => Promise<R>, options?: UseWriteOptions<A, R>): UseWriteReturn<A, R>;
+/** useWrite's mutation: run the write, then invalidate and call `onSuccess`. */
+declare function writeMutation<A, R>(queryClient: QueryClient, write: (args: A) => Promise<R>, options: UseWriteOptions<A, R>): MutationOptions<R, unknown, A>;
+
+export { type UseWriteOptions, type UseWriteReturn, WRITE_FAILED, useWrite, writeMutation };

package/dist/hooks/use-write.js

@@ -0,0 +1,4 @@
+export { WRITE_FAILED, useWrite, writeMutation } from '../chunk-52T2EYXH.js';
+import '../chunk-LG6TUBVM.js';
+//# sourceMappingURL=use-write.js.map
+//# sourceMappingURL=use-write.js.map

package/dist/hooks/use-write.js.map

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

package/dist/index.d.ts

@@ -1,21 +1,93 @@
-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 ResourceChangeEvent, m as RowFailure, S as ScalarFilter, n as SortParam, o as SubscribeParams, U as UpdateParams, p as UpdateResult, W as WriteEvent } from './types-CS9UpxQS.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-C_9HbXvb.js';
-export { DataProviderRoot, DataProviderRootProps, GenesisProvider, GenesisProviderProps, MockProviderOptions, PostgrestFieldErrors, SupabaseClient, SupabaseClientInput, SupabaseProviderOptions, SupabaseRealtimeChannel, SupabaseRealtimePayload, SupabaseResourceConfig, SupabaseWriteContext, createMockProvider, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode } from './provider/index.js';
+import { L as ListParams, a as Identifier } from './types-B9DDfvWa.js';
+export { A as ArrayFilter, B as BaseRecord, b as BulkChange, c as BulkResult, C as CreateParams, d as CreateResult, D as DataProvider, e as DeleteParams, f as DeleteResult, F as FilterParam, G as GetManyParams, g as GetManyResult, h as GetOneParams, i as GetOneResult, H as HistoryParams, j as ImportParams, I as InvalidationKey, k as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, l as ResourceChangeEvent, m as RowFailure, S as ScalarFilter, n as SortParam, o as SubscribeParams, U as UpdateParams, p as UpdateResult, W as WriteEvent } from './types-B9DDfvWa.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-B6nACXZ7.js';
+export { CallRpcOptions, CreateOrAdoptOptions, DEFAULT_RPC_MESSAGES, DataProviderRoot, DataProviderRootProps, GenesisProvider, GenesisProviderProps, MockProviderOptions, PostgrestFieldErrors, RPC_FAILED, RpcClient, SupabaseClient, SupabaseClientInput, SupabaseProviderOptions, SupabaseRealtimeChannel, SupabaseRealtimePayload, SupabaseResourceConfig, SupabaseWriteContext, callRpc, createMockProvider, createOrAdopt, 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 { InfinitePageParam, UseInfiniteResourceOptions, UseInfiniteResourceReturn, useInfiniteResource } from './hooks/use-infinite-resource.js';
 export { useCapabilities } from './hooks/use-capabilities.js';
+export { UseWriteOptions, UseWriteReturn, WRITE_FAILED, useWrite } from './hooks/use-write.js';
+export { UseDraftReturn, useDraft } from './hooks/use-draft.js';
+export { DEFAULT_DRAFT_DELAY_MS, DRAFT_NOT_SAVED, DraftAdoption, DraftController, DraftOptions, DraftSeed, DraftState, DraftStatus, DraftValue, isNetworkFailure, stableJson } from './hooks/draft-controller.js';
+export { ViewerScope, ViewerScopeProps, clearViewerCache } from './hooks/index.js';
 export { DEFAULT_LIVE_DEBOUNCE_MS, LiveOptions } from './hooks/use-live.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_UNDO_DELAY_MS, MutationMode, MutationModeOptions, UndoableWrite, dropPendingWrites, flushPendingWrites, 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-C7FJtFXV.js';
 export { decodeRecordKey, encodeRecordKey, keyFields } from './schema/index.js';
+import { Query } from '@tanstack/react-query';
 export { titleCase } from './utils.js';
 import 'react';
-import '@tanstack/react-query';
 import 'react-hook-form';
+
+/** Who and when a key is for. `viewer` is required; null means signed out. */
+interface KeyScope {
+    viewer: string | null;
+    /** The group, practice or space the screen is filtered to. */
+    group?: string | null;
+    /** The person-day (YYYY-MM-DD) a "today" read is for. */
+    day?: string | null;
+}
+type Fields = Record<string, unknown>;
+type QueryDefs = Record<string, (...args: never[]) => Fields>;
+type ScopedKey<D extends string, K> = readonly [D, K, Fields];
+/** A filter for `invalidateQueries` / `removeQueries` / `getQueriesData`. */
+interface KeyFilter {
+    predicate: (query: Query) => boolean;
+}
+type QueryKeys<D extends string, Q extends QueryDefs> = {
+    /** Every key in the domain: `[domain]`. */
+    readonly all: readonly [D];
+    /** Builds keys for one scope. */
+    for(scope: KeyScope): {
+        [K in keyof Q]: (...args: Parameters<Q[K]>) => ScopedKey<D, K>;
+    };
+    /**
+     * Keys whose fields match `fields`: an equal value (`1` matches `"1"`,
+     * objects whatever their key order), an array field containing the value,
+     * or, for an array value, an array field containing every item. `kind`
+     * narrows it to one query.
+     */
+    where(fields: Fields, kind?: keyof Q): KeyFilter;
+} & {
+    readonly [K in keyof Q]: {
+        readonly all: readonly [D, K];
+    };
+};
+/**
+ * The keys of one domain. Each query maps its arguments to the fields that
+ * make it distinct (sort arrays so order never makes two keys):
+ *
+ * ```ts
+ * export const worksheetKeys = defineQueryKeys("worksheet-items", {
+ *   lessonParts: (people: string[]) => ({ people: [...people].sort() }),
+ *   byEntry: (entryId: string) => ({ entryId }),
+ * });
+ * useQuery({ queryKey: worksheetKeys.for({ viewer }).lessonParts(people), … });
+ * queryClient.invalidateQueries(worksheetKeys.where({ people: personId }));
+ * queryClient.invalidateQueries(worksheetKeys.where({ entryId }, "byEntry"));
+ * queryClient.invalidateQueries({ queryKey: worksheetKeys.lessonParts.all });
+ * ```
+ */
+declare function defineQueryKeys<const D extends string, Q extends QueryDefs>(domain: D, queries: Q): QueryKeys<D, Q>;
+/**
+ * The keys Genesis's own hooks cache a resource under, for writing into or
+ * invalidating them by hand: `[resource]` covers them all.
+ */
+declare function resourceKeys(resource: string): {
+    all: readonly [string];
+    lists: readonly [string, "list"];
+    list: (params: ListParams) => readonly [string, "list", ListParams];
+    details: readonly [string, "detail"];
+    /** Every projection of one record: `detail(id, select)` for any `select`. */
+    detailsOf: (id: Identifier | null | undefined) => readonly [string, "detail", Identifier | null | undefined];
+    detail: (id: Identifier | null | undefined, select?: string) => readonly [string, "detail", Identifier | null | undefined, string | undefined];
+    infinite: (params: unknown) => readonly [string, "infinite", unknown];
+};
+
+export { Identifier, type KeyFilter, type KeyScope, ListParams, type QueryKeys, type ScopedKey, defineQueryKeys, resourceKeys };

package/dist/index.js

@@ -1,22 +1,26 @@
-export { createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from './chunk-Y475Z7BM.js';
+export { DEFAULT_RPC_MESSAGES, RPC_FAILED, callRpc, createOrAdopt, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from './chunk-EF5BKT4B.js';
 export { decodeRecordKey, encodeRecordKey, keyFields } from './chunk-KV2HW4G4.js';
 export { DataReadError, isDataReadError, readFailureMessage } from './chunk-HUNGCTRA.js';
 import './chunk-XCX2TRBL.js';
 import './chunk-65SXNHWE.js';
-import './chunk-V3GDAELU.js';
-export { useInfiniteResource } from './chunk-ADD2RIGA.js';
-export { buildArrayItemDefaults, useResourceForm } from './chunk-Y3SCYMNN.js';
-export { DataWriteError, isDataWriteError } from './chunk-5NHR6ZXS.js';
-export { useOne } from './chunk-ZKMAU6NN.js';
-export { useResource } from './chunk-QFR6YJ3R.js';
-export { DEFAULT_LIVE_DEBOUNCE_MS } from './chunk-KXVHDK3Q.js';
-export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from './chunk-XQO4OH2N.js';
+export { ViewerScope, clearViewerCache } from './chunk-5ORRAXIV.js';
+export { useResource } from './chunk-NMFABW4Y.js';
 export { useWizard } from './chunk-7KOLYF27.js';
-export { titleCase } from './chunk-RYEXWQFD.js';
-export { DEFAULT_UNDO_DELAY_MS, pendingWriteCount } from './chunk-OBUBP4BY.js';
+export { WRITE_FAILED, useWrite } from './chunk-52T2EYXH.js';
+export { useDraft } from './chunk-DF2UWEEB.js';
+export { useInfiniteResource } from './chunk-NZPJI7FC.js';
+export { buildArrayItemDefaults, useResourceForm } from './chunk-OSPLIKSH.js';
+export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from './chunk-XQO4OH2N.js';
+export { DEFAULT_UNDO_DELAY_MS, dropPendingWrites, flushPendingWrites, pendingWriteCount } from './chunk-S2ZXUNXB.js';
+import './chunk-7NUL32W7.js';
 export { useCapabilities } from './chunk-BQOJX67X.js';
+export { useOne } from './chunk-BGTXN2E6.js';
+export { defineQueryKeys, resourceKeys } from './chunk-RCAP3Q4T.js';
+export { DEFAULT_LIVE_DEBOUNCE_MS } from './chunk-KXVHDK3Q.js';
 export { DataProviderRoot, GenesisProvider, createMockProvider, useDataProvider, useStorage } from './chunk-GGSXSI6Z.js';
 export { createLocalStorageAdapter, createMemoryStorageAdapter, createNoopStorageAdapter } from './chunk-ZYJUEJ4Z.js';
-import './chunk-7NUL32W7.js';
+export { titleCase } from './chunk-RYEXWQFD.js';
+export { DEFAULT_DRAFT_DELAY_MS, DRAFT_NOT_SAVED, DraftController, isNetworkFailure, stableJson } from './chunk-HBAPYA5K.js';
+export { DataWriteError, isDataWriteError } from './chunk-LG6TUBVM.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/provider/index.d.ts

@@ -1,7 +1,7 @@
-import { D as DataProvider, I as Identifier, B as BaseRecord, j as InvalidationKey, W as WriteEvent } from '../types-CS9UpxQS.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 ResourceChangeEvent, m as RowFailure, S as ScalarFilter, n as SortParam, o as SubscribeParams, U as UpdateParams, p as UpdateResult } from '../types-CS9UpxQS.js';
-import { D as DataReadError, R as ReadOutcome, b as DataWriteError, W as WriteOutcome } from '../read-outcome-C_9HbXvb.js';
-export { a as DataReadErrorOptions, c as DataWriteErrorOptions, i as isDataReadError, d as isDataWriteError, r as readFailureMessage } from '../read-outcome-C_9HbXvb.js';
+import { D as DataProvider, a as Identifier, B as BaseRecord, I as InvalidationKey, W as WriteEvent } from '../types-B9DDfvWa.js';
+export { A as ArrayFilter, b as BulkChange, c as BulkResult, C as CreateParams, d as CreateResult, e as DeleteParams, f as DeleteResult, F as FilterParam, G as GetManyParams, g as GetManyResult, h as GetOneParams, i as GetOneResult, H as HistoryParams, j as ImportParams, L as ListParams, k as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, l as ResourceChangeEvent, m as RowFailure, S as ScalarFilter, n as SortParam, o as SubscribeParams, U as UpdateParams, p as UpdateResult } from '../types-B9DDfvWa.js';
+import { D as DataReadError, R as ReadOutcome, b as DataWriteError, W as WriteOutcome } from '../read-outcome-B6nACXZ7.js';
+export { a as DataReadErrorOptions, c as DataWriteErrorOptions, i as isDataReadError, d as isDataWriteError, r as readFailureMessage } from '../read-outcome-B6nACXZ7.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { QueryClient } from '@tanstack/react-query';
@@ -102,6 +102,10 @@ interface SupabaseRealtimeChannel {
  */
 interface SupabaseClientInput {
     from(table: string): unknown;
+    /** Database functions, for a resource whose `source` is an `rpc`. Any real client's `rpc` fits. */
+    rpc?(fn: string, args?: Record<string, unknown>, options?: {
+        count?: "exact" | "planned" | "estimated";
+    }): unknown;
     /** Supabase Realtime, for `subscribe`. Any real client's `channel` fits. */
     channel?(name: string): unknown;
     removeChannel?(channel: unknown): unknown;
@@ -179,6 +183,38 @@ interface SupabaseResourceConfig {
      * covers the resource.
      */
     realtime?: boolean;
+    /**
+     * Read this resource from somewhere else than its table: a view (joins,
+     * counts, aggregations) or a database function that returns rows. Writes
+     * still go to the table. Lists keep paging, filters, search, sort, totals
+     * and cursors, because PostgREST filters a view or a set-returning function
+     * like a table. Realtime still watches the table.
+     *
+     * Row-level security: a plain view runs as its owner and a SECURITY DEFINER
+     * function as its definer, so either one reads past RLS. Create the view
+     * `with (security_invoker = true)` and the function `security invoker` (or
+     * have it filter by `auth.uid()` itself), or this exposes every row.
+     *
+     * ```ts
+     * resources: {
+     *   tasks: { source: "tasks_with_people" },
+     *   course_progress: { source: { rpc: "group_progress", args: () => ({ group_id: currentGroup() }) } },
+     * }
+     * ```
+     */
+    source?: string | {
+        rpc: string;
+        args?: () => Record<string, unknown>;
+    };
+    /** The columns read when the caller names none, e.g. embedded joins: `"*, person:people(full_name)"`. Default `"*"`. */
+    select?: string;
+    /**
+     * With a `source` (or a `select` that embeds other tables), the table's own
+     * columns: creates and updates write only these, so a form built from the
+     * richer read row never sends its joined or computed columns to the table.
+     * Without it, an update writes only the columns the table's row has.
+     */
+    writeColumns?: readonly string[];
 }
 /** Options for `createSupabaseProvider`. All optional; none changes reads. */
 interface SupabaseProviderOptions {
@@ -256,9 +292,10 @@ declare function readOutcomeFromCode(code: string | null | undefined): ReadOutco
  *
  * - `42501` (insufficient privilege, including "new row violates row-level
  *   security policy") → `forbidden`
- * - `22***` (data exception: bad type, out of range) and `23***` (integrity
- *   constraint: `23505` unique, `23503` foreign key, `23502` not null,
- *   `23514` check) → `invalid`
+ * - `23505` (unique violation) → `duplicate`
+ * - `22***` (data exception: bad type, out of range) and the other `23***`
+ *   (integrity constraint: `23503` foreign key, `23502` not null, `23514`
+ *   check) → `invalid`
  * - `PGRST301`–`PGRST303` (JWT missing, expired or rejected), `28000`,
  *   `28P01` → `unauthenticated`
  * - `PGRST116` (one row was asked for and none came back) → `gone`
@@ -307,6 +344,48 @@ declare function fieldErrorsFromPostgrest(error: {
  */
 declare function toDataWriteError(error: unknown): DataWriteError;
 
+/** Anything with Supabase's `rpc`. */
+interface RpcClient {
+    rpc(fn: string, args?: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: unknown;
+    }>;
+}
+/** The words shown for a code when the caller gives none. A guard's own `raise exception` (P0001) keeps its words. */
+declare const DEFAULT_RPC_MESSAGES: Readonly<Record<string, string>>;
+declare const RPC_FAILED = "That didn't work. Try again.";
+interface CallRpcOptions {
+    /** Words per error code, e.g. `{ "55000": "This course has already started." }`; these win over the defaults. */
+    messages?: Record<string, string>;
+}
+/**
+ * Calls a database function and returns its result. A failure throws a
+ * DataWriteError with the usual outcome and code, and words a person can
+ * read: yours for the code, a guard's own message (P0001), the defaults
+ * above, or a generic sentence. The raw error stays on `cause`.
+ */
+declare function callRpc<T = unknown>(client: RpcClient, fn: string, args?: Record<string, unknown>, options?: CallRpcOptions): Promise<T>;
+interface CreateOrAdoptOptions<T extends BaseRecord> {
+    /** The fields that make a row unique (its unique index), read from `data`. */
+    key: readonly (keyof T & string)[];
+    /**
+     * Changes to write over a row that was already there; return null to keep it
+     * as it is. It runs on the row as read just now, and the update isn't
+     * conditional: two callers merging into one row at once can each overwrite
+     * the other. Where that matters, merge in a database function instead.
+     */
+    merge?: (existing: T) => Partial<T> | null;
+}
+/**
+ * "One live row per key": creates the row, or, when one with the same key is
+ * already there (a `duplicate`), adopts it, optionally merging changes in.
+ * `adopted` says which. A duplicate you can't see is still an error.
+ */
+declare function createOrAdopt<T extends BaseRecord>(provider: DataProvider, resource: string, data: Partial<T>, options: CreateOrAdoptOptions<T>): Promise<{
+    row: T;
+    adopted: boolean;
+}>;
+
 /**
  * Puts a `DataProvider` in context, and nothing else. Mount it inside your
  * app's own `QueryClientProvider` and the Genesis hooks share that cache:
@@ -358,4 +437,4 @@ type GenesisProviderProps = {
  */
 declare function GenesisProvider({ children, provider, mock, storage, queryClient: queryClientProp, }: GenesisProviderProps): react.JSX.Element;
 
-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 SupabaseRealtimeChannel, type SupabaseRealtimePayload, type SupabaseResourceConfig, type SupabaseWriteContext, WriteEvent, WriteOutcome, createMockProvider, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode };
+export { BaseRecord, type CallRpcOptions, type CreateOrAdoptOptions, DEFAULT_RPC_MESSAGES, DataProvider, DataProviderRoot, type DataProviderRootProps, DataReadError, DataWriteError, GenesisProvider, type GenesisProviderProps, Identifier, InvalidationKey, type MockProviderOptions, type PostgrestFieldErrors, RPC_FAILED, ReadOutcome, type RpcClient, type SupabaseClient, type SupabaseClientInput, type SupabaseProviderOptions, type SupabaseRealtimeChannel, type SupabaseRealtimePayload, type SupabaseResourceConfig, type SupabaseWriteContext, WriteEvent, WriteOutcome, callRpc, createMockProvider, createOrAdopt, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode };

package/dist/provider/index.js

@@ -1,8 +1,8 @@
-export { createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from '../chunk-Y475Z7BM.js';
+export { DEFAULT_RPC_MESSAGES, RPC_FAILED, callRpc, createOrAdopt, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from '../chunk-EF5BKT4B.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';
+import '../chunk-RYEXWQFD.js';
+export { DataWriteError, isDataWriteError } from '../chunk-LG6TUBVM.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{read-outcome-C_9HbXvb.d.ts → read-outcome-B6nACXZ7.d.ts}

@@ -9,13 +9,16 @@ import { D as DataRow } from './types-C7FJtFXV.js';
  * - `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".
+ * - `duplicate`: a row with the same unique key already exists (`23505`).
+ *   A caller keeping "one live row per key" (a draft, a natural-key upsert)
+ *   adopts the existing row instead; `fields` still names the clashing field.
  * - `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";
+type WriteOutcome = "conflict" | "gone" | "forbidden" | "duplicate" | "invalid" | "audit_failed" | "unauthenticated" | "error";
 interface DataWriteErrorOptions {
     /** The row as it is now, for a `conflict`. Only fields the user may read. */
     current?: DataRow;

package/dist/schema/index.d.ts

@@ -1,7 +1,7 @@
 import { e as ResourceContract, D as DataRow } from '../types-C7FJtFXV.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-C7FJtFXV.js';
-import { I as Identifier } from '../types-CS9UpxQS.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-C_9HbXvb.js';
+import { a as Identifier } from '../types-B9DDfvWa.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-B6nACXZ7.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,5 +1,5 @@
 export { decodeRecordKey, encodeRecordKey, keyFields } from '../chunk-KV2HW4G4.js';
 export { DataReadError, isDataReadError, readFailureMessage } from '../chunk-HUNGCTRA.js';
-export { DataWriteError, isDataWriteError } from '../chunk-5NHR6ZXS.js';
+export { DataWriteError, isDataWriteError } from '../chunk-LG6TUBVM.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{types-CS9UpxQS.d.ts → types-B9DDfvWa.d.ts}

@@ -347,4 +347,4 @@ interface DataProvider {
     invalidates?(event: WriteEvent): InvalidationKey[];
 }
 
-export type { ArrayFilter as A, BaseRecord as B, CreateParams as C, DataProvider as D, FilterParam as F, GetManyParams as G, HistoryParams as H, Identifier as I, ListParams as L, NullFilter as N, PaginationParam as P, RangeFilter as R, ScalarFilter as S, UpdateParams as U, WriteEvent as W, BulkChange as a, BulkResult as b, CreateResult as c, DeleteParams as d, DeleteResult as e, GetManyResult as f, GetOneParams as g, GetOneResult as h, ImportParams as i, InvalidationKey as j, ListResult as k, ResourceChangeEvent as l, RowFailure as m, SortParam as n, SubscribeParams as o, UpdateResult as p };
+export type { ArrayFilter as A, BaseRecord as B, CreateParams as C, DataProvider as D, FilterParam as F, GetManyParams as G, HistoryParams as H, InvalidationKey as I, ListParams as L, NullFilter as N, PaginationParam as P, RangeFilter as R, ScalarFilter as S, UpdateParams as U, WriteEvent as W, Identifier as a, BulkChange as b, BulkResult as c, CreateResult as d, DeleteParams as e, DeleteResult as f, GetManyResult as g, GetOneParams as h, GetOneResult as i, ImportParams as j, ListResult as k, ResourceChangeEvent as l, RowFailure as m, SortParam as n, SubscribeParams as o, UpdateResult as p };