@marktiderman/genesis-core 1.5.1 → 1.6.0

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

@@ -0,0 +1,27 @@
+import { QueryKey } from '@tanstack/react-query';
+import { o as SubscribeParams, l as ResourceChangeEvent } from '../types-CS9UpxQS.js';
+import '../types-C7FJtFXV.js';
+import '../form-types.js';
+
+/** How long a burst of change events is gathered into one refetch. */
+declare const DEFAULT_LIVE_DEBOUNCE_MS = 250;
+/** `live` as an object, to tune it. `live: true` takes the defaults. */
+interface LiveOptions {
+    /**
+     * Events arriving within this many milliseconds of each other cause one
+     * refetch, not one each. Default {@link DEFAULT_LIVE_DEBOUNCE_MS}. A
+     * steady stream still refetches at least every `4 × debounceMs`.
+     */
+    debounceMs?: number;
+}
+/**
+ * Subscribes while mounted and `enabled`, and invalidates `queryKey` (a
+ * prefix) once per burst of events that `accept` lets through. While the
+ * page is hidden the queries are only marked stale; they refetch when it is
+ * shown again (TanStack Query's `refetchOnWindowFocus`) or next used.
+ *
+ * @internal Used by `useResource` and `useOne`'s `live` option.
+ */
+declare function useLiveInvalidation(resource: string, live: boolean | LiveOptions | undefined, enabled: boolean, params: SubscribeParams, queryKey: QueryKey, accept?: (event: ResourceChangeEvent) => boolean): void;
+
+export { DEFAULT_LIVE_DEBOUNCE_MS, type LiveOptions, useLiveInvalidation };

package/dist/hooks/use-live.js

@@ -0,0 +1,5 @@
+export { DEFAULT_LIVE_DEBOUNCE_MS, useLiveInvalidation } from '../chunk-KXVHDK3Q.js';
+import '../chunk-GGSXSI6Z.js';
+import '../chunk-ZYJUEJ4Z.js';
+//# sourceMappingURL=use-live.js.map
+//# sourceMappingURL=use-live.js.map

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

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

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

@@ -1,6 +1,7 @@
 import { UseQueryResult } from '@tanstack/react-query';
-import { B as BaseRecord, I as Identifier } from '../types-DDOmG9hj.js';
-import '../types-5cuflvha.js';
+import { B as BaseRecord, I as Identifier } from '../types-CS9UpxQS.js';
+import { LiveOptions } from './use-live.js';
+import '../types-C7FJtFXV.js';
 import '../form-types.js';
 
 interface UseOneOptions {
@@ -8,6 +9,12 @@ interface UseOneOptions {
     select?: string;
     /** Defaults to `!!id` — won't fetch when id is falsy. */
     enabled?: boolean;
+    /**
+     * Keep the record current while mounted: refetch it when the provider
+     * reports a change to it (`DataProvider.subscribe`). See
+     * `UseResourceOptions.live`. Off by default.
+     */
+    live?: boolean | LiveOptions;
 }
 /**
  * Fetch a single record by id, powered by TanStack Query.

package/dist/hooks/use-one.js

@@ -1,4 +1,5 @@
-export { useOne } from '../chunk-ZK5C3OOT.js';
+export { useOne } from '../chunk-ZKMAU6NN.js';
+import '../chunk-KXVHDK3Q.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=use-one.js.map

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

@@ -1,8 +1,8 @@
 import { UseFormReturn } from 'react-hook-form';
 import { ResourceFormFieldDef } from '../form-types.js';
-import { j as InvalidationKey } from '../types-DDOmG9hj.js';
+import { j as InvalidationKey } from '../types-CS9UpxQS.js';
 import { MutationModeOptions } from './mutation-mode.js';
-import '../types-5cuflvha.js';
+import '../types-C7FJtFXV.js';
 import '@tanstack/react-query';
 
 interface UseResourceFormOptions extends MutationModeOptions {

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

@@ -1,11 +1,12 @@
-export { buildArrayItemDefaults, useResourceForm } from '../chunk-3JSFTLDV.js';
+export { buildArrayItemDefaults, useResourceForm } from '../chunk-CKGGE6WA.js';
+import '../chunk-ZKMAU6NN.js';
 import '../chunk-XQO4OH2N.js';
 import '../chunk-5NHR6ZXS.js';
 import '../chunk-RYEXWQFD.js';
-import '../chunk-F3BE7NGM.js';
+import '../chunk-OBUBP4BY.js';
 import '../chunk-7NUL32W7.js';
 import '../chunk-BQOJX67X.js';
-import '../chunk-ZK5C3OOT.js';
+import '../chunk-KXVHDK3Q.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=use-resource-form.js.map

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

@@ -1,7 +1,8 @@
 import { UseQueryResult, UseMutationResult } from '@tanstack/react-query';
-import { m as SortParam, F as FilterParam, j as InvalidationKey, k as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-DDOmG9hj.js';
+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 { MutationModeOptions } from './mutation-mode.js';
-import '../types-5cuflvha.js';
+import { LiveOptions } from './use-live.js';
+import '../types-C7FJtFXV.js';
 import '../form-types.js';
 
 interface UseResourceOptions<T> extends MutationModeOptions {
@@ -40,6 +41,17 @@ interface UseResourceOptions<T> extends MutationModeOptions {
      * rather than flashing a skeleton. Default false.
      */
     keepPreviousData?: boolean;
+    /**
+     * Keep the list current while mounted: subscribe to the provider's change
+     * events (`DataProvider.subscribe`) and refetch this resource's cached
+     * reads (lists and records) when it reports one, once per burst of
+     * events. Events are hints: rows always come from the provider's normal
+     * read. Pending optimistic and undoable writes stay applied over the
+     * refetch. Needs a provider that serves `subscribe` for the resource
+     * (`capabilities(resource).realtime`); otherwise it does nothing. Off by
+     * default.
+     */
+    live?: boolean | LiveOptions;
     /**
      * After the write commits, with the provider's row. In `optimistic` and
      * `undoable` modes that is after `create` / `update` / `remove` have

package/dist/hooks/use-resource.js

@@ -1,7 +1,8 @@
-export { useResource } from '../chunk-6Q477CHB.js';
-import '../chunk-F3BE7NGM.js';
+export { useResource } from '../chunk-KV6KH3L2.js';
+import '../chunk-OBUBP4BY.js';
 import '../chunk-7NUL32W7.js';
 import '../chunk-BQOJX67X.js';
+import '../chunk-KXVHDK3Q.js';
 import '../chunk-GGSXSI6Z.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=use-resource.js.map

package/dist/index.d.ts

@@ -1,17 +1,19 @@
-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-DDOmG9hj.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-kgNhfuST.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 { 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';
 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 { 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_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-5cuflvha.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';
 export { titleCase } from './utils.js';
 import 'react';

package/dist/index.js

@@ -1,19 +1,21 @@
-export { createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from './chunk-E5VYFAQO.js';
+import './chunk-XCX2TRBL.js';
+export { createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from './chunk-Y475Z7BM.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-HT43MPKW.js';
-export { buildArrayItemDefaults, useResourceForm } from './chunk-3JSFTLDV.js';
-export { useResource } from './chunk-6Q477CHB.js';
+import './chunk-V3GDAELU.js';
+export { buildArrayItemDefaults, useResourceForm } from './chunk-CKGGE6WA.js';
+export { useOne } from './chunk-ZKMAU6NN.js';
+export { useResource } from './chunk-KV6KH3L2.js';
 export { DEFAULT_UNSAVED_CHANGES_MESSAGE, useUnsavedChangesGuard } from './chunk-XQO4OH2N.js';
 export { useWizard } from './chunk-7KOLYF27.js';
 export { DataWriteError, isDataWriteError } from './chunk-5NHR6ZXS.js';
 export { titleCase } from './chunk-RYEXWQFD.js';
-export { DEFAULT_UNDO_DELAY_MS, pendingWriteCount } from './chunk-F3BE7NGM.js';
+export { DEFAULT_UNDO_DELAY_MS, pendingWriteCount } from './chunk-OBUBP4BY.js';
 import './chunk-7NUL32W7.js';
 export { useCapabilities } from './chunk-BQOJX67X.js';
-export { useOne } from './chunk-ZK5C3OOT.js';
+export { useInfiniteResource } from './chunk-ADD2RIGA.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';
 //# sourceMappingURL=index.js.map

package/dist/provider/index.d.ts

@@ -1,12 +1,12 @@
-import { D as DataProvider, I as Identifier, B as BaseRecord, j as InvalidationKey, W as WriteEvent } from '../types-DDOmG9hj.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-DDOmG9hj.js';
-import { D as DataReadError, R as ReadOutcome, b as DataWriteError, W as WriteOutcome } from '../read-outcome-kgNhfuST.js';
-export { a as DataReadErrorOptions, c as DataWriteErrorOptions, i as isDataReadError, d as isDataWriteError, r as readFailureMessage } from '../read-outcome-kgNhfuST.js';
+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 * as react from 'react';
 import { ReactNode } from 'react';
 import { QueryClient } from '@tanstack/react-query';
 import { S as StorageAdapter } from '../types-DKcxHXxq.js';
-import '../types-5cuflvha.js';
+import '../types-C7FJtFXV.js';
 import '../form-types.js';
 
 interface MockProviderOptions {
@@ -37,6 +37,7 @@ interface SupabaseQueryBuilder {
     or(filters: string): SupabaseQueryBuilder;
     order(column: string, options?: {
         ascending?: boolean;
+        nullsFirst?: boolean;
     }): SupabaseQueryBuilder;
     range(from: number, to: number): SupabaseQueryBuilder;
     single(): SupabaseQueryBuilder;
@@ -55,6 +56,35 @@ interface SupabaseQueryBuilder {
  */
 interface SupabaseClient {
     from(table: string): SupabaseQueryBuilder;
+    /** Supabase Realtime; needed only for `subscribe` (see `SupabaseProviderOptions.realtime`). */
+    channel?(name: string): SupabaseRealtimeChannel;
+    /** Releases a channel made by `channel()`. */
+    removeChannel?(channel: SupabaseRealtimeChannel): unknown;
+}
+/**
+ * One `postgres_changes` message, as Supabase Realtime sends it. Only the
+ * fields the provider reads; a real payload has more.
+ */
+interface SupabaseRealtimePayload {
+    eventType: "INSERT" | "UPDATE" | "DELETE";
+    /** The row after an insert or update (empty for a delete). */
+    new?: Record<string, unknown>;
+    /** For a delete or update: the old row's key (all of it with `REPLICA IDENTITY FULL`). */
+    old?: Record<string, unknown>;
+}
+/**
+ * The part of a Supabase `RealtimeChannel` the provider uses. A real
+ * `@supabase/supabase-js` channel satisfies it.
+ */
+interface SupabaseRealtimeChannel {
+    on(type: "postgres_changes", filter: {
+        event: "*" | "INSERT" | "UPDATE" | "DELETE";
+        schema: string;
+        table: string;
+        filter?: string;
+    }, callback: (payload: SupabaseRealtimePayload) => void): SupabaseRealtimeChannel;
+    subscribe(callback?: (status: string, error?: unknown) => void): SupabaseRealtimeChannel;
+    unsubscribe?(): unknown;
 }
 /**
  * What `createSupabaseProvider` actually requires from its `client` argument
@@ -72,6 +102,9 @@ interface SupabaseClient {
  */
 interface SupabaseClientInput {
     from(table: string): unknown;
+    /** Supabase Realtime, for `subscribe`. Any real client's `channel` fits. */
+    channel?(name: string): unknown;
+    removeChannel?(channel: unknown): unknown;
 }
 /** What a write hook is told about the write it is part of. */
 interface SupabaseWriteContext {
@@ -138,6 +171,14 @@ interface SupabaseResourceConfig {
      * `useResource` and `useResourceForm` invalidate after their writes.
      */
     invalidates?: InvalidationKey[] | ((event: WriteEvent) => InvalidationKey[]);
+    /**
+     * Serve `subscribe` for this resource through Supabase Realtime
+     * (`postgres_changes`), so `live` lists and records refresh when the table
+     * changes. The table must be in the `supabase_realtime` publication, with
+     * RLS on. `false` turns it off even when `SupabaseProviderOptions.realtime`
+     * covers the resource.
+     */
+    realtime?: boolean;
 }
 /** Options for `createSupabaseProvider`. All optional; none changes reads. */
 interface SupabaseProviderOptions {
@@ -175,6 +216,13 @@ interface SupabaseProviderOptions {
         resource: string;
         operation: "getList" | "getOne" | "getMany";
     }) => void | Promise<void>;
+    /**
+     * Which resources `subscribe` serves through Supabase Realtime: `true` for
+     * all, a list of names, or a test. Off by default; a resource's own
+     * `resources[name].realtime` wins. Needs a client with `channel()` (any
+     * `@supabase/supabase-js` client).
+     */
+    realtime?: boolean | readonly string[] | ((resource: string) => boolean);
 }
 /**
  * The Supabase data provider. Reads and writes go through the client you
@@ -310,4 +358,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 SupabaseResourceConfig, type SupabaseWriteContext, WriteEvent, WriteOutcome, createMockProvider, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, 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 SupabaseRealtimeChannel, type SupabaseRealtimePayload, type SupabaseResourceConfig, type SupabaseWriteContext, WriteEvent, WriteOutcome, createMockProvider, createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, useDataProvider, useStorage, writeOutcomeFromCode };

package/dist/provider/index.js

@@ -1,4 +1,4 @@
-export { createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from '../chunk-E5VYFAQO.js';
+export { createSupabaseProvider, fieldErrorsFromPostgrest, readOutcomeFromCode, toDataWriteError, writeOutcomeFromCode } from '../chunk-Y475Z7BM.js';
 export { DataReadError, isDataReadError, readFailureMessage } from '../chunk-HUNGCTRA.js';
 export { DataWriteError, isDataWriteError } from '../chunk-5NHR6ZXS.js';
 import '../chunk-RYEXWQFD.js';

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

@@ -1,4 +1,4 @@
-import { D as DataRow } from './types-5cuflvha.js';
+import { D as DataRow } from './types-C7FJtFXV.js';
 
 /**
  * - `conflict`: someone else changed the row since it was read. `current`

package/dist/schema/index.d.ts

@@ -1,7 +1,7 @@
-import { e as ResourceContract, D as DataRow } from '../types-5cuflvha.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-5cuflvha.js';
-import { I as Identifier } from '../types-DDOmG9hj.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-kgNhfuST.js';
+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';
 export { FieldType as WidgetHint } from '../form-types.js';
 
 /** The key of a contract as a list, whichever form `key` was declared in. */

package/dist/{types-5cuflvha.d.ts → types-C7FJtFXV.d.ts}

@@ -258,6 +258,18 @@ interface ProviderCapabilities {
      * "Leave site?" prompt.
      */
     readonly keepaliveWrites?: boolean;
+    /**
+     * `getList` serves cursor (keyset) paging: `pagination.cursor` in,
+     * `nextCursor` out. Pages stay correct while rows are added or removed,
+     * and a deep page costs no more than the first.
+     */
+    readonly cursorPagination?: boolean;
+    /**
+     * `subscribe` reports changes to this resource (asked per resource:
+     * `capabilities(resource)`), so `live` lists and records refresh when
+     * someone else changes them.
+     */
+    readonly realtime?: boolean;
 }
 /** One audit record, as committed alongside the edit it describes. */
 interface AuditEntry {

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

@@ -1,4 +1,4 @@
-import { A as AuditEntry, g as ResourceSchema, h as ResourceSummary, P as ProviderCapabilities, R as RecordComment } from './types-5cuflvha.js';
+import { A as AuditEntry, g as ResourceSchema, h as ResourceSummary, P as ProviderCapabilities, R as RecordComment } from './types-C7FJtFXV.js';
 
 /** Record identifier — supports both string UUIDs and numeric auto-increment IDs. */
 type Identifier = string | number;
@@ -7,11 +7,20 @@ type BaseRecord = {
     id: Identifier;
     [key: string]: unknown;
 };
-/** Pagination parameters (offset-based, with optional cursor for future use). */
+/**
+ * Pagination parameters: offset (`page`) or cursor (keyset).
+ *
+ * Cursor paging: set `cursor` to `null` for the first page and to the
+ * previous page's `ListResult.nextCursor` for each next one. A provider that
+ * serves it (`capabilities().cursorPagination`) then ignores `page` and
+ * returns `nextCursor`; one that doesn't ignores `cursor` and pages by
+ * `page`, returning no `nextCursor`. `useInfiniteResource` handles both.
+ */
 interface PaginationParam {
     page: number;
     perPage: number;
-    cursor?: string;
+    /** `null`: the first page, by cursor. A string: the page after that cursor. Opaque. */
+    cursor?: string | null;
 }
 /** Sort direction for a single field. */
 interface SortParam {
@@ -67,7 +76,16 @@ interface ListParams {
 /** Result of `getList`. */
 interface ListResult<T> {
     data: T[];
+    /**
+     * Rows matching the filters and search. In cursor mode a provider may
+     * count only on the first page (`cursor: null`) and return `-1` after it.
+     */
     total: number;
+    /**
+     * Cursor mode only: the cursor for the next page, or `null` when this is
+     * the last one. Absent when the provider paged by offset.
+     */
+    nextCursor?: string | null;
 }
 /** Parameters for `getOne`. */
 interface GetOneParams {
@@ -192,6 +210,34 @@ interface WriteEvent {
     /** The row as written, when the provider has it (not for a delete). */
     record?: BaseRecord;
 }
+/**
+ * A change to a resource, as `DataProvider.subscribe` reports it.
+ *
+ * Treat it as a HINT that cached reads are stale, never as data to show:
+ * the Genesis hooks refetch through the provider's normal (RLS-checked)
+ * read instead of writing `record` into the cache. `changed` says only that
+ * something may have changed (e.g. after a reconnect, when events may have
+ * been missed), so every cached read of the resource should be refetched.
+ */
+type ResourceChangeEvent = {
+    type: "created" | "updated" | "deleted";
+    /** The changed record's id, when the provider knows it. */
+    id?: Identifier;
+    /** The record as the provider saw it, when it sends one. A hint only. */
+    record?: BaseRecord;
+} | {
+    type: "changed";
+};
+/** What a `subscribe` call watches. Every field narrows; none is required. */
+interface SubscribeParams {
+    /** Watch one record only. */
+    id?: Identifier;
+    /**
+     * The list's filters. A provider MAY use them to send fewer events; it
+     * may also ignore them and report every change to the resource.
+     */
+    filters?: FilterParam[];
+}
 /**
  * A cache key to invalidate after a write. Shaped like a TanStack Query
  * `QueryKey` (`readonly unknown[]`), matched by prefix.
@@ -281,6 +327,18 @@ interface DataProvider {
      * `prepare`). `useResourceForm` applies it in edit mode.
      */
     toFormValues?(resource: string, record: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Watch a resource for changes made anywhere (other users, other tabs,
+     * server jobs). Calls `callback` for each change until the returned
+     * function is called, which must release everything the subscription
+     * holds (sockets, channels). Report `realtime: true` in `capabilities()`
+     * for the resources it serves; for others it may return a no-op.
+     *
+     * Events are invalidation hints: `useResource({ live: true })` and
+     * `useOne(..., { live: true })` refetch on them and never trust their
+     * payload.
+     */
+    subscribe?(resource: string, params: SubscribeParams, callback: (event: ResourceChangeEvent) => void): () => void;
     /**
      * Other cache keys a committed write makes stale, beyond the resource's
      * own `[resource]` keys. `useResource` and `useResourceForm` invalidate
@@ -289,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, RowFailure as l, SortParam as m, UpdateResult as n };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marktiderman/genesis-core",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "private": false,
   "type": "module",
   "sideEffects": false,

package/dist/chunk-6Q477CHB.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/hooks/use-resource.ts"],"names":["keepPreviousData","keepPreviousPlaceholder"],"mappings":"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","file":"chunk-6Q477CHB.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  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      // Pending optimistic/undoable patches are re-applied to the refetch.\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 modeArgs = {\n    queryClient,\n    provider,\n    resource,\n    mode: mutationMode,\n    undoDelayMs,\n    onUndoable,\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 ({ keepalive }) => {\n          const result = await provider.create<T>(resource, { data, ...(keepalive ? { keepalive } : {}) });\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 (ctx) => {\n          const result = await provider.update<T>(resource, {\n            id,\n            data: (ctx.data ?? data) as Partial<T>,\n            ...(ctx.keepalive ? { keepalive: true } : {}),\n          });\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 ({ keepalive }) => {\n          const result = await provider.deleteOne(resource, { id, ...(keepalive ? { keepalive } : {}) });\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"]}