@marktiderman/genesis-core 2.5.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/dist/{chunk-227N654S.js → chunk-BIIENNTW.js} +2 -2
  2. package/dist/chunk-BIIENNTW.js.map +1 -0
  3. package/dist/{chunk-XMC4EJUE.js → chunk-EHFYSJJA.js} +6 -3
  4. package/dist/chunk-EHFYSJJA.js.map +1 -0
  5. package/dist/chunk-LZVU5NGV.js +82 -0
  6. package/dist/chunk-LZVU5NGV.js.map +1 -0
  7. package/dist/{chunk-X6EO3XBB.js → chunk-OKCSGNCU.js} +9 -4
  8. package/dist/chunk-OKCSGNCU.js.map +1 -0
  9. package/dist/{chunk-H2RGMX6L.js → chunk-OWYX4BEI.js} +3 -3
  10. package/dist/{chunk-H2RGMX6L.js.map → chunk-OWYX4BEI.js.map} +1 -1
  11. package/dist/csv.d.ts +1 -3
  12. package/dist/dates.d.ts +27 -1
  13. package/dist/dates.js +1 -1
  14. package/dist/form-types.d.ts +1 -70
  15. package/dist/hooks/index.d.ts +3 -4
  16. package/dist/hooks/index.js +6 -5
  17. package/dist/hooks/mutation-mode.d.ts +1 -3
  18. package/dist/hooks/related-keys.d.ts +1 -3
  19. package/dist/hooks/use-capabilities.d.ts +1 -2
  20. package/dist/hooks/use-infinite-resource.d.ts +1 -3
  21. package/dist/hooks/use-link-options.d.ts +58 -0
  22. package/dist/hooks/use-link-options.js +10 -0
  23. package/dist/hooks/use-link-options.js.map +1 -0
  24. package/dist/hooks/use-live.d.ts +1 -3
  25. package/dist/hooks/use-one.d.ts +1 -3
  26. package/dist/hooks/use-relation-label.d.ts +8 -4
  27. package/dist/hooks/use-relation-label.js +1 -1
  28. package/dist/hooks/use-resource-form.d.ts +1 -3
  29. package/dist/hooks/use-resource-form.js +2 -2
  30. package/dist/hooks/use-resource.d.ts +1 -3
  31. package/dist/hooks/use-write.d.ts +1 -3
  32. package/dist/index.d.ts +5 -6
  33. package/dist/index.js +6 -5
  34. package/dist/provider/index.d.ts +4 -6
  35. package/dist/resource-view/index.d.ts +85 -4
  36. package/dist/resource-view/index.js +122 -34
  37. package/dist/resource-view/index.js.map +1 -1
  38. package/dist/schema/index.d.ts +3 -5
  39. package/dist/testing/index.d.ts +2 -4
  40. package/dist/types-r_Rlw7BB.d.ts +800 -0
  41. package/dist/{write-outcome-CFnpciUI.d.ts → write-outcome-BWV34wh5.d.ts} +1 -1
  42. package/package.json +1 -1
  43. package/dist/chunk-227N654S.js.map +0 -1
  44. package/dist/chunk-X6EO3XBB.js.map +0 -1
  45. package/dist/chunk-XMC4EJUE.js.map +0 -1
  46. package/dist/types-CXhqXPN1.d.ts +0 -367
  47. package/dist/types-o8j7g6O6.d.ts +0 -331
@@ -1,367 +0,0 @@
1
- import { A as AuditEntry, g as ResourceSchema, h as ResourceSummary, P as ProviderCapabilities, R as RecordComment } from './types-o8j7g6O6.js';
2
-
3
- /** Record identifier — supports both string UUIDs and numeric auto-increment IDs. */
4
- type Identifier = string | number;
5
- /** Base record type — all resources must have an id. */
6
- type BaseRecord = {
7
- id: Identifier;
8
- [key: string]: unknown;
9
- };
10
- /**
11
- * Pagination parameters: offset (`page`) or cursor (keyset).
12
- *
13
- * Cursor paging: set `cursor` to `null` for the first page and to the
14
- * previous page's `ListResult.nextCursor` for each next one. A provider that
15
- * serves it (`capabilities().cursorPagination`) then ignores `page` and
16
- * returns `nextCursor`; one that doesn't ignores `cursor` and pages by
17
- * `page`, returning no `nextCursor`. `useInfiniteResource` handles both.
18
- */
19
- interface PaginationParam {
20
- page: number;
21
- perPage: number;
22
- /** `null`: the first page, by cursor. A string: the page after that cursor. Opaque. */
23
- cursor?: string | null;
24
- }
25
- /** Sort direction for a single field. */
26
- interface SortParam {
27
- field: string;
28
- order: "asc" | "desc";
29
- }
30
- /**
31
- * Filter expressions — discriminated union by operator.
32
- * Filters are AND-ed together in queries.
33
- */
34
- /** Operators that compare a field against a single scalar value. */
35
- interface ScalarFilter {
36
- field: string;
37
- operator: "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains";
38
- value: string | number | boolean;
39
- }
40
- /** Operator that checks field membership in a list. */
41
- interface ArrayFilter {
42
- field: string;
43
- operator: "in";
44
- value: (string | number | boolean)[];
45
- }
46
- /** Operator that checks field is within a range. */
47
- interface RangeFilter {
48
- field: string;
49
- operator: "between";
50
- value: [string | number, string | number];
51
- }
52
- /** Operators that check for null/non-null — no value needed. */
53
- interface NullFilter {
54
- field: string;
55
- operator: "is_null" | "is_not_null";
56
- }
57
- type FilterParam = ScalarFilter | ArrayFilter | RangeFilter | NullFilter;
58
- /**
59
- * How a list's total is counted: `exact` counts every matching row (slow on
60
- * large tables), `estimated` and `planned` ask the database's statistics
61
- * (fast, approximate), `none` skips the count (`total` is -1).
62
- */
63
- type CountMode = "exact" | "estimated" | "planned" | "none";
64
- /** Parameters for `getList`. */
65
- interface ListParams {
66
- pagination?: PaginationParam;
67
- sort?: SortParam;
68
- /**
69
- * Sort by several fields, first one first. Wins over `sort` on a provider
70
- * whose capabilities report `multiSort`; others use only `sort`.
71
- */
72
- sorts?: SortParam[];
73
- filters?: FilterParam[];
74
- /** Supabase select syntax, e.g. "*, author:profiles(name)". Mock provider ignores this. */
75
- select?: string;
76
- /** Multi-field text search (case-insensitive). */
77
- search?: {
78
- query: string;
79
- fields: string[];
80
- };
81
- /** How to count `total`; wins over the resource's own setting. Providers that can't choose count exactly. */
82
- count?: CountMode;
83
- }
84
- /** Result of `getList`. */
85
- interface ListResult<T> {
86
- data: T[];
87
- /**
88
- * Rows matching the filters and search. `-1` means not counted: in cursor
89
- * mode after the first page, or with `count: "none"`. A pager must treat -1
90
- * as unknown (no last page number) and stop on a short page instead.
91
- */
92
- total: number;
93
- /** True when `total` is the database's estimate (`estimated` or `planned`), so a screen says "about". */
94
- totalIsEstimate?: boolean;
95
- /**
96
- * Cursor mode only: the cursor for the next page, or `null` when this is
97
- * the last one. Absent when the provider paged by offset.
98
- */
99
- nextCursor?: string | null;
100
- /**
101
- * Cursor mode only: the cursor for the page before this one, or `null` on
102
- * the first page. Lets an infinite list drop pages from the front (TanStack
103
- * Query's `maxPages`) and load them again when scrolled back.
104
- */
105
- prevCursor?: string | null;
106
- }
107
- /** Parameters for `getOne`. */
108
- interface GetOneParams {
109
- id: Identifier;
110
- /** Supabase select syntax, e.g. "*, author:profiles(name)". Defaults to "*". */
111
- select?: string;
112
- }
113
- /** Result of `getOne`. */
114
- interface GetOneResult<T> {
115
- data: T;
116
- }
117
- /** Parameters for `getMany`. */
118
- interface GetManyParams {
119
- ids: Identifier[];
120
- }
121
- /** Result of `getMany`. */
122
- interface GetManyResult<T> {
123
- data: T[];
124
- }
125
- /** Parameters for `create`. */
126
- interface CreateParams<T> {
127
- data: Partial<T>;
128
- /**
129
- * Sent while the page unloads (an `undoable` write flushed on close or
130
- * reload). A fetch-based provider should pass `keepalive: true` to `fetch`
131
- * so the request outlives the page, and report `keepaliveWrites` in its
132
- * capabilities. Others ignore it.
133
- */
134
- keepalive?: boolean;
135
- }
136
- /** Result of `create`. */
137
- interface CreateResult<T> {
138
- data: T;
139
- /** The audit entry committed with the new row, from a provider that audits. */
140
- audit?: AuditEntry;
141
- }
142
- /** Parameters for `update`. */
143
- interface UpdateParams<T> {
144
- /**
145
- * The record's identifier. For a composite key, the canonical string from
146
- * `encodeRecordKey` (`@marktiderman/genesis-core/schema`).
147
- */
148
- id: Identifier;
149
- data: Partial<T>;
150
- /**
151
- * The version token the caller read the row at. A provider that reports
152
- * `versionedWrites` in its capabilities rejects the update with a
153
- * `DataWriteError` (`conflict`) when the row has moved on since, instead of
154
- * overwriting someone else's edit. Providers without versioned writes
155
- * ignore it.
156
- */
157
- expectedVersion?: string | null;
158
- /** See `CreateParams.keepalive`. */
159
- keepalive?: boolean;
160
- }
161
- /** Result of `update`. */
162
- interface UpdateResult<T> {
163
- data: T;
164
- /** The row's new version token, from a provider with versioned writes. */
165
- version?: string | null;
166
- /** The audit entry committed with the edit, from a provider that audits. */
167
- audit?: AuditEntry;
168
- }
169
- /** Parameters for `deleteOne`. */
170
- interface DeleteParams {
171
- id: Identifier;
172
- /** The version token the row was read at; see `UpdateParams.expectedVersion`. */
173
- expectedVersion?: string | null;
174
- /** See `CreateParams.keepalive`. */
175
- keepalive?: boolean;
176
- }
177
- /** Result of `deleteOne`. */
178
- interface DeleteResult {
179
- data: {
180
- id: Identifier;
181
- };
182
- /** The audit entry committed with the deletion, from a provider that audits. */
183
- audit?: AuditEntry;
184
- }
185
- /** One row's change in a bulk update. */
186
- interface BulkChange {
187
- id: Identifier;
188
- data: Record<string, unknown>;
189
- /** The version token the row was read at. */
190
- expectedVersion?: string | null;
191
- }
192
- /** Why one row of a bulk write or import didn't go through. */
193
- interface RowFailure {
194
- /** The row's position in the request, from 0. */
195
- index: number;
196
- id?: Identifier;
197
- outcome: string;
198
- message: string;
199
- }
200
- /** Result of a bulk write: every row changed, or none did. */
201
- interface BulkResult {
202
- /** Rows changed; always the number requested when `ok`. */
203
- count: number;
204
- ok: boolean;
205
- /** Present when `ok` is false: every row that failed, so the caller can fix them all at once. */
206
- failures?: RowFailure[];
207
- /** One audit entry per row changed. */
208
- audit?: AuditEntry[];
209
- }
210
- /** Parameters for `importRows`. */
211
- interface ImportParams {
212
- rows: Record<string, unknown>[];
213
- /** Check every row against the database and change nothing. */
214
- dryRun: boolean;
215
- }
216
- /** Parameters for `history`. */
217
- interface HistoryParams {
218
- id: Identifier;
219
- /** Most recent first; default and maximum are the provider's. */
220
- limit?: number;
221
- }
222
- /** A write that committed, as passed to a provider's `onWrite` and `invalidates`. */
223
- interface WriteEvent {
224
- resource: string;
225
- kind: "create" | "update" | "delete";
226
- id: Identifier;
227
- /** The row as written, when the provider has it (not for a delete). */
228
- record?: BaseRecord;
229
- }
230
- /**
231
- * A change to a resource, as `DataProvider.subscribe` reports it.
232
- *
233
- * Treat it as a HINT that cached reads are stale, never as data to show:
234
- * the Genesis hooks refetch through the provider's normal (RLS-checked)
235
- * read instead of writing `record` into the cache. `changed` says only that
236
- * something may have changed (e.g. after a reconnect, when events may have
237
- * been missed), so every cached read of the resource should be refetched.
238
- */
239
- type ResourceChangeEvent = {
240
- type: "created" | "updated" | "deleted";
241
- /** The changed record's id, when the provider knows it. */
242
- id?: Identifier;
243
- /** The record as the provider saw it, when it sends one. A hint only. */
244
- record?: BaseRecord;
245
- } | {
246
- type: "changed";
247
- };
248
- /** What a `subscribe` call watches. Every field narrows; none is required. */
249
- interface SubscribeParams {
250
- /** Watch one record only. */
251
- id?: Identifier;
252
- /**
253
- * The list's filters. A provider MAY use them to send fewer events; it
254
- * may also ignore them and report every change to the resource.
255
- */
256
- filters?: FilterParam[];
257
- }
258
- /**
259
- * A cache key to invalidate after a write. Shaped like a TanStack Query
260
- * `QueryKey` (`readonly unknown[]`), matched by prefix.
261
- */
262
- type InvalidationKey = readonly unknown[];
263
- interface DataProvider {
264
- getList<T extends BaseRecord = BaseRecord>(resource: string, params: ListParams): Promise<ListResult<T>>;
265
- getOne<T extends BaseRecord = BaseRecord>(resource: string, params: GetOneParams): Promise<GetOneResult<T>>;
266
- getMany<T extends BaseRecord = BaseRecord>(resource: string, params: GetManyParams): Promise<GetManyResult<T>>;
267
- create<T extends BaseRecord = BaseRecord>(resource: string, params: CreateParams<T>): Promise<CreateResult<T>>;
268
- update<T extends BaseRecord = BaseRecord>(resource: string, params: UpdateParams<T>): Promise<UpdateResult<T>>;
269
- deleteOne(resource: string, params: DeleteParams): Promise<DeleteResult>;
270
- /**
271
- * The resource's real shape for the CURRENT user: fields, key, version
272
- * field, and per-field read and update rights. Fields the user may not read
273
- * are omitted entirely.
274
- */
275
- describe?(resource: string): Promise<ResourceSchema>;
276
- /** Every resource this user may see, for a sidebar or a picker. */
277
- listResources?(): Promise<ResourceSummary[]>;
278
- /**
279
- * What this provider can do, optionally for one resource. A UI hides the
280
- * controls a provider cannot serve instead of letting them error.
281
- */
282
- capabilities?(resource?: string): Promise<ProviderCapabilities>;
283
- /**
284
- * A record's audit history, most recent first, limited to the fields this
285
- * user may read.
286
- */
287
- history?(resource: string, params: HistoryParams): Promise<AuditEntry[]>;
288
- /**
289
- * Update many rows in ONE transaction. All of them change or none do: a
290
- * single conflict, refusal or invalid value rolls back the rest, and the
291
- * result lists every row that failed.
292
- */
293
- updateMany?(resource: string, params: {
294
- changes: BulkChange[];
295
- }): Promise<BulkResult>;
296
- /** Delete many rows in one transaction, all or none, each at its version. */
297
- deleteMany?(resource: string, params: {
298
- items: {
299
- id: Identifier;
300
- expectedVersion?: string | null;
301
- }[];
302
- }): Promise<BulkResult>;
303
- /**
304
- * Add rows from an import. With `dryRun`, every row is tried against the
305
- * database and nothing is kept, so the result lists every row that would
306
- * fail; without it, all rows are added in one transaction or none are.
307
- */
308
- importRows?(resource: string, params: ImportParams): Promise<BulkResult>;
309
- /**
310
- * Undo one audited change with a compensating write: put the changed
311
- * fields back, remove an added row, or restore a deleted one. Refused when
312
- * the row has changed since.
313
- */
314
- undo?(resource: string, params: {
315
- auditId: string;
316
- }): Promise<{
317
- audit?: AuditEntry;
318
- }>;
319
- /**
320
- * Run one of the resource's row actions (`ResourceSchema.actions`) on a
321
- * row, at the version it was read. The app's function does the work; the
322
- * row's change is audited.
323
- */
324
- runAction?(resource: string, params: {
325
- id: Identifier;
326
- action: string;
327
- expectedVersion?: string | null;
328
- }): Promise<{
329
- data: Record<string, unknown> | null;
330
- audit?: AuditEntry;
331
- }>;
332
- /** A record's comments, oldest first. */
333
- comments?(resource: string, params: {
334
- id: Identifier;
335
- }): Promise<RecordComment[]>;
336
- /** Add a comment to a record, as the signed-in user. */
337
- addComment?(resource: string, params: {
338
- id: Identifier;
339
- body: string;
340
- }): Promise<RecordComment>;
341
- /**
342
- * Maps a stored row to the values an edit form starts from, for a resource
343
- * whose form shape differs from its table (the reverse of a write's
344
- * `prepare`). `useResourceForm` applies it in edit mode.
345
- */
346
- toFormValues?(resource: string, record: Record<string, unknown>): Record<string, unknown>;
347
- /**
348
- * Watch a resource for changes made anywhere (other users, other tabs,
349
- * server jobs). Calls `callback` for each change until the returned
350
- * function is called, which must release everything the subscription
351
- * holds (sockets, channels). Report `realtime: true` in `capabilities()`
352
- * for the resources it serves; for others it may return a no-op.
353
- *
354
- * Events are invalidation hints: `useResource({ live: true })` and
355
- * `useOne(..., { live: true })` refetch on them and never trust their
356
- * payload.
357
- */
358
- subscribe?(resource: string, params: SubscribeParams, callback: (event: ResourceChangeEvent) => void): () => void;
359
- /**
360
- * Other cache keys a committed write makes stale, beyond the resource's
361
- * own `[resource]` keys. `useResource` and `useResourceForm` invalidate
362
- * them after their writes.
363
- */
364
- invalidates?(event: WriteEvent): InvalidationKey[];
365
- }
366
-
367
- export type { ArrayFilter as A, BaseRecord as B, CountMode 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, SortParam as S, UpdateParams as U, WriteEvent as W, Identifier as a, BulkChange as b, BulkResult as c, CreateParams as d, CreateResult as e, DeleteParams as f, DeleteResult as g, GetManyResult as h, GetOneParams as i, GetOneResult as j, ImportParams as k, ListResult as l, ResourceChangeEvent as m, RowFailure as n, ScalarFilter as o, SubscribeParams as p, UpdateResult as q };