@marktiderman/genesis-core 1.2.0 → 1.3.0

package/dist/hooks/index.d.ts

@@ -3,6 +3,6 @@ export { UseOneOptions, useOne } from './use-one.js';
 export { UseResourceFormOptions, UseResourceFormReturn, buildArrayItemDefaults, useResourceForm } from './use-resource-form.js';
 export { UseWizardReturn, WizardStep, useWizard } from './use-wizard.js';
 import '@tanstack/react-query';
-import '../types-C7UVaF87.js';
+import '../types-DUbRb8qV.js';
 import '../form-types.js';
 import 'react-hook-form';

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-C7UVaF87.js';
+import { B as BaseRecord, I as Identifier } from '../types-DUbRb8qV.js';
 import '../form-types.js';
 
 interface UseOneOptions {

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

@@ -1,5 +1,5 @@
 import { UseQueryResult, UseMutationResult } from '@tanstack/react-query';
-import { s as SortParam, i as FilterParam, m as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-C7UVaF87.js';
+import { z as SortParam, k as FilterParam, p as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-DUbRb8qV.js';
 import '../form-types.js';
 
 interface UseResourceOptions<T> {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { A as ArrayFilter, a as AuditEntry, B as BaseRecord, C as CreateParams, b as CreateResult, D as DataProvider, c as DataRow, d as DeleteParams, e as DeleteResult, F as FieldPermissions, f as FieldReference, g as FieldSchema, h as FilterOperator, i as FilterParam, G as GetManyParams, j as GetManyResult, k as GetOneParams, l as GetOneResult, I as Identifier, L as ListParams, m as ListResult, N as NullFilter, P as PaginationParam, n as ProviderCapabilities, R as RangeFilter, o as ResourceAccess, p as ResourceContract, q as ResourceSchema, r as ResourceSummary, S as ScalarFilter, s as SortParam, t as StorageType, U as UpdateParams, u as UpdateResult, V as VersionField } from './types-C7UVaF87.js';
-export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from './write-outcome-D8kjoQ1A.js';
+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, L as ListParams, p as ListResult, N as NullFilter, P as PaginationParam, q as ProviderCapabilities, R as RangeFilter, r as RecordComment, s as ResourceAccess, t as ResourceContract, u as ResourceRelation, v as ResourceSchema, w as ResourceSummary, x as RowAction, y as RowFailure, S as ScalarFilter, z as SortParam, E as StorageType, U as UpdateParams, J as UpdateResult, V as VersionField } from './types-DUbRb8qV.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from './write-outcome-aYToY3dK.js';
 export { DataProviderRoot, DataProviderRootProps, GenesisProvider, GenesisProviderProps, MockProviderOptions, SupabaseClient, SupabaseClientInput, createMockProvider, createSupabaseProvider, useDataProvider, useStorage } from './provider/index.js';
 export { S as StorageAdapter } from './types-DKcxHXxq.js';
 export { createLocalStorageAdapter, createMemoryStorageAdapter, createNoopStorageAdapter } from './storage/index.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 export { createSupabaseProvider } from './chunk-6AA4ISUA.js';
+import './chunk-XCX2TRBL.js';
 export { decodeRecordKey, encodeRecordKey, keyFields } from './chunk-KV2HW4G4.js';
 export { DataWriteError, isDataWriteError } from './chunk-4W4W7F4I.js';
-import './chunk-XCX2TRBL.js';
 import './chunk-65SXNHWE.js';
 import './chunk-EL7YGOTY.js';
 export { buildArrayItemDefaults, useResourceForm } from './chunk-5FTUB2M6.js';

package/dist/provider/index.d.ts

@@ -1,6 +1,6 @@
-import { D as DataProvider } from '../types-C7UVaF87.js';
-export { A as ArrayFilter, B as BaseRecord, C as CreateParams, b as CreateResult, d as DeleteParams, e as DeleteResult, i as FilterParam, G as GetManyParams, j as GetManyResult, k as GetOneParams, l as GetOneResult, I as Identifier, L as ListParams, m as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, S as ScalarFilter, s as SortParam, U as UpdateParams, u as UpdateResult } from '../types-C7UVaF87.js';
-export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-D8kjoQ1A.js';
+import { D as DataProvider } from '../types-DUbRb8qV.js';
+export { A as ArrayFilter, B as BaseRecord, 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, I as Identifier, o as ImportParams, L as ListParams, p as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, y as RowFailure, S as ScalarFilter, z as SortParam, U as UpdateParams, J as UpdateResult } from '../types-DUbRb8qV.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-aYToY3dK.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { S as StorageAdapter } from '../types-DKcxHXxq.js';

package/dist/schema/index.d.ts

@@ -1,6 +1,6 @@
-import { p as ResourceContract, I as Identifier, c as DataRow } from '../types-C7UVaF87.js';
-export { a as AuditEntry, F as FieldPermissions, f as FieldReference, g as FieldSchema, h as FilterOperator, n as ProviderCapabilities, o as ResourceAccess, q as ResourceSchema, r as ResourceSummary, t as StorageType, V as VersionField } from '../types-C7UVaF87.js';
-export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-D8kjoQ1A.js';
+import { t as ResourceContract, I as Identifier, e as DataRow } from '../types-DUbRb8qV.js';
+export { a as AuditEntry, F as FieldPermissions, h as FieldReference, i as FieldSchema, j as FilterOperator, q as ProviderCapabilities, r as RecordComment, s as ResourceAccess, u as ResourceRelation, v as ResourceSchema, w as ResourceSummary, x as RowAction, E as StorageType, V as VersionField } from '../types-DUbRb8qV.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-aYToY3dK.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-C7UVaF87.d.ts → types-DUbRb8qV.d.ts}

@@ -47,6 +47,8 @@ interface FieldSchema {
     readonly array?: boolean;
     /** Human note (surfaces in describe()/drift reports). */
     readonly description?: string;
+    /** Human label, e.g. "Date of birth". Absent means a UI derives one from `name`. */
+    readonly label?: string;
     /** The store's exact type, e.g. `timestamp with time zone` or `public.status`. */
     readonly dbType?: string;
     /** Which control fits this field. A hint: a UI may still choose another. */
@@ -97,6 +99,46 @@ interface ResourceAccess {
     readonly update: boolean;
     /** Why `update` (or `read`) is false, in one human sentence. */
     readonly reason?: string;
+    /** True when this user may add rows. Absent means the provider doesn't say. */
+    readonly create?: boolean;
+    /** True when this user may delete rows they can see. */
+    readonly delete?: boolean;
+    /** True when this user may read a row's audit history. */
+    readonly history?: boolean;
+    /** True when this user may read and add comments on rows they can see. */
+    readonly comment?: boolean;
+    /** Why `create`, `delete`, `history` or `comment` is false, in one human sentence each. */
+    readonly reasons?: {
+        readonly create?: string;
+        readonly delete?: string;
+        readonly history?: string;
+        readonly comment?: string;
+    };
+}
+/**
+ * How another resource relates to this one, from the store's foreign keys.
+ *
+ * - `one`: a field on THIS resource points at one row of `resource`.
+ * - `many`: rows of `resource` point at this row through their `field`.
+ * - `through`: many rows of `resource`, linked by the junction resource in
+ *   `through` (a table whose key is two foreign keys).
+ */
+interface ResourceRelation {
+    readonly kind: "one" | "many" | "through";
+    /** The related resource. */
+    readonly resource: string;
+    /**
+     * `one`: the field on this resource. `many`: the field on `resource` that
+     * holds this row's key. `through`: the junction's field holding this row's key.
+     */
+    readonly field: string;
+    /** For `through`: the junction resource, and its field pointing at `resource`. */
+    readonly through?: {
+        readonly resource: string;
+        readonly otherField: string;
+    };
+    /** True when at most one related row can exist (a unique foreign key). */
+    readonly unique?: boolean;
 }
 /**
  * The column a provider checks on every update so an edit never silently
@@ -111,7 +153,12 @@ interface VersionField {
      * `expectedVersion` echoes `String(row[field])` back unchanged.
      */
     readonly field: string;
-    readonly kind: "integer" | "timestamp";
+    /**
+     * `row`: no column tracks versions, so the token is a fingerprint of the
+     * row's values, and `field` is a name the provider adds to each record
+     * (it is not one of the resource's fields).
+     */
+    readonly kind: "integer" | "timestamp" | "row";
 }
 /**
  * A resource as `describe()` reports it for the CURRENT user: the contract,
@@ -124,6 +171,32 @@ interface ResourceSchema<Row extends DataRow = DataRow> extends ResourceContract
     readonly access: ResourceAccess;
     /** Present only when writes can be version-checked. */
     readonly version?: VersionField;
+    /** The field that best names a row to a person (a name or title), for links and pickers. */
+    readonly labelField?: string;
+    /** Resources this one links to or is linked from. Only ones this user may see. */
+    readonly relations?: readonly ResourceRelation[];
+    /** Fields the user may set when creating a row. Absent when creating isn't allowed. */
+    readonly createFields?: readonly string[];
+    /** Row actions this user may run: each calls the app's own function on one row. */
+    readonly actions?: readonly RowAction[];
+}
+/** A named operation on one row, carried out by the app's own database function. */
+interface RowAction {
+    readonly name: string;
+    readonly label: string;
+    /** Ask before running, with this question. */
+    readonly confirm?: string;
+    /** One sentence on what it does. */
+    readonly description?: string;
+}
+/** A comment on a record. */
+interface RecordComment {
+    readonly id: string;
+    /** The signed-in user who wrote it (the token's `sub`). */
+    readonly author: string;
+    readonly body: string;
+    /** ISO 8601, as the store recorded it. */
+    readonly createdAt: string;
 }
 /** One entry of `listResources()`: enough to draw a sidebar. */
 interface ResourceSummary {
@@ -151,6 +224,21 @@ interface ProviderCapabilities {
     readonly versionedWrites: boolean;
     /** Records may be keyed by more than one field. */
     readonly compositeKeys: boolean;
+    /** Server-side sort by several fields at once (`ListParams.sorts`). */
+    readonly multiSort?: boolean;
+    /** `create` and `deleteOne` are served, subject to each resource's access. */
+    readonly create?: boolean;
+    readonly delete?: boolean;
+    /** `history` is served, subject to each resource's access. */
+    readonly history?: boolean;
+    /** `importRows` is served, with a dry run. */
+    readonly import?: boolean;
+    /** `undo` is served. */
+    readonly undo?: boolean;
+    /** `runAction` is served. */
+    readonly actions?: boolean;
+    /** `comments` and `addComment` are served. */
+    readonly comments?: boolean;
 }
 /** One audit record, as committed alongside the edit it describes. */
 interface AuditEntry {
@@ -162,7 +250,10 @@ interface AuditEntry {
     readonly resource: string;
     /** The record's key, field name → value. */
     readonly key: DataRow;
-    readonly action: "create" | "update" | "delete";
+    /** `run` is a row action; `rowAction` names it. */
+    readonly action: "create" | "update" | "delete" | "run";
+    /** For `run`: which row action. */
+    readonly rowAction?: string;
     /** Values of the changed fields before the edit. */
     readonly before: DataRow | null;
     /** Values of the changed fields after the edit. */
@@ -219,6 +310,11 @@ type FilterParam = ScalarFilter | ArrayFilter | RangeFilter | NullFilter;
 interface ListParams {
     pagination?: PaginationParam;
     sort?: SortParam;
+    /**
+     * Sort by several fields, first one first. Wins over `sort` on a provider
+     * whose capabilities report `multiSort`; others use only `sort`.
+     */
+    sorts?: SortParam[];
     filters?: FilterParam[];
     /** Supabase select syntax, e.g. "*, author:profiles(name)". Mock provider ignores this. */
     select?: string;
@@ -258,6 +354,8 @@ interface CreateParams<T> {
 /** Result of `create`. */
 interface CreateResult<T> {
     data: T;
+    /** The audit entry committed with the new row, from a provider that audits. */
+    audit?: AuditEntry;
 }
 /** Parameters for `update`. */
 interface UpdateParams<T> {
@@ -287,12 +385,53 @@ interface UpdateResult<T> {
 /** Parameters for `deleteOne`. */
 interface DeleteParams {
     id: Identifier;
+    /** The version token the row was read at; see `UpdateParams.expectedVersion`. */
+    expectedVersion?: string | null;
 }
 /** Result of `deleteOne`. */
 interface DeleteResult {
     data: {
         id: Identifier;
     };
+    /** The audit entry committed with the deletion, from a provider that audits. */
+    audit?: AuditEntry;
+}
+/** One row's change in a bulk update. */
+interface BulkChange {
+    id: Identifier;
+    data: Record<string, unknown>;
+    /** The version token the row was read at. */
+    expectedVersion?: string | null;
+}
+/** Why one row of a bulk write or import didn't go through. */
+interface RowFailure {
+    /** The row's position in the request, from 0. */
+    index: number;
+    id?: Identifier;
+    outcome: string;
+    message: string;
+}
+/** Result of a bulk write: every row changed, or none did. */
+interface BulkResult {
+    /** Rows changed; always the number requested when `ok`. */
+    count: number;
+    ok: boolean;
+    /** Present when `ok` is false: every row that failed, so the caller can fix them all at once. */
+    failures?: RowFailure[];
+    /** One audit entry per row changed. */
+    audit?: AuditEntry[];
+}
+/** Parameters for `importRows`. */
+interface ImportParams {
+    rows: Record<string, unknown>[];
+    /** Check every row against the database and change nothing. */
+    dryRun: boolean;
+}
+/** Parameters for `history`. */
+interface HistoryParams {
+    id: Identifier;
+    /** Most recent first; default and maximum are the provider's. */
+    limit?: number;
 }
 interface DataProvider {
     getList<T extends BaseRecord = BaseRecord>(resource: string, params: ListParams): Promise<ListResult<T>>;
@@ -314,6 +453,64 @@ interface DataProvider {
      * controls a provider cannot serve instead of letting them error.
      */
     capabilities?(resource?: string): Promise<ProviderCapabilities>;
+    /**
+     * A record's audit history, most recent first, limited to the fields this
+     * user may read.
+     */
+    history?(resource: string, params: HistoryParams): Promise<AuditEntry[]>;
+    /**
+     * Update many rows in ONE transaction. All of them change or none do: a
+     * single conflict, refusal or invalid value rolls back the rest, and the
+     * result lists every row that failed.
+     */
+    updateMany?(resource: string, params: {
+        changes: BulkChange[];
+    }): Promise<BulkResult>;
+    /** Delete many rows in one transaction, all or none, each at its version. */
+    deleteMany?(resource: string, params: {
+        items: {
+            id: Identifier;
+            expectedVersion?: string | null;
+        }[];
+    }): Promise<BulkResult>;
+    /**
+     * Add rows from an import. With `dryRun`, every row is tried against the
+     * database and nothing is kept, so the result lists every row that would
+     * fail; without it, all rows are added in one transaction or none are.
+     */
+    importRows?(resource: string, params: ImportParams): Promise<BulkResult>;
+    /**
+     * Undo one audited change with a compensating write: put the changed
+     * fields back, remove an added row, or restore a deleted one. Refused when
+     * the row has changed since.
+     */
+    undo?(resource: string, params: {
+        auditId: string;
+    }): Promise<{
+        audit?: AuditEntry;
+    }>;
+    /**
+     * Run one of the resource's row actions (`ResourceSchema.actions`) on a
+     * row, at the version it was read. The app's function does the work; the
+     * row's change is audited.
+     */
+    runAction?(resource: string, params: {
+        id: Identifier;
+        action: string;
+        expectedVersion?: string | null;
+    }): Promise<{
+        data: Record<string, unknown> | null;
+        audit?: AuditEntry;
+    }>;
+    /** A record's comments, oldest first. */
+    comments?(resource: string, params: {
+        id: Identifier;
+    }): Promise<RecordComment[]>;
+    /** Add a comment to a record, as the signed-in user. */
+    addComment?(resource: string, params: {
+        id: Identifier;
+        body: string;
+    }): Promise<RecordComment>;
 }
 
-export type { ArrayFilter as A, BaseRecord as B, CreateParams as C, DataProvider as D, FieldPermissions as F, GetManyParams as G, Identifier as I, ListParams as L, NullFilter as N, PaginationParam as P, RangeFilter as R, ScalarFilter as S, UpdateParams as U, VersionField as V, AuditEntry as a, CreateResult as b, DataRow as c, DeleteParams as d, DeleteResult as e, FieldReference as f, FieldSchema as g, FilterOperator as h, FilterParam as i, GetManyResult as j, GetOneParams as k, GetOneResult as l, ListResult as m, ProviderCapabilities as n, ResourceAccess as o, ResourceContract as p, ResourceSchema as q, ResourceSummary as r, SortParam as s, StorageType as t, UpdateResult as u };
+export type { ArrayFilter as A, BaseRecord as B, CreateParams as C, DataProvider as D, StorageType as E, FieldPermissions as F, GetManyParams as G, HistoryParams as H, Identifier as I, UpdateResult as J, ListParams as L, NullFilter as N, PaginationParam as P, RangeFilter as R, ScalarFilter as S, UpdateParams as U, VersionField as V, AuditEntry as a, BulkChange as b, BulkResult as c, CreateResult as d, DataRow as e, DeleteParams as f, DeleteResult as g, FieldReference as h, FieldSchema as i, FilterOperator as j, FilterParam as k, GetManyResult as l, GetOneParams as m, GetOneResult as n, ImportParams as o, ListResult as p, ProviderCapabilities as q, RecordComment as r, ResourceAccess as s, ResourceContract as t, ResourceRelation as u, ResourceSchema as v, ResourceSummary as w, RowAction as x, RowFailure as y, SortParam as z };

package/dist/{write-outcome-D8kjoQ1A.d.ts → write-outcome-aYToY3dK.d.ts}

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

package/package.json

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