@marktiderman/genesis-core 2.5.0 → 2.7.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.
- package/dist/{chunk-227N654S.js → chunk-BIIENNTW.js} +2 -2
- package/dist/chunk-BIIENNTW.js.map +1 -0
- package/dist/{chunk-XMC4EJUE.js → chunk-EHFYSJJA.js} +6 -3
- package/dist/chunk-EHFYSJJA.js.map +1 -0
- package/dist/chunk-LZVU5NGV.js +82 -0
- package/dist/chunk-LZVU5NGV.js.map +1 -0
- package/dist/{chunk-X6EO3XBB.js → chunk-OKCSGNCU.js} +9 -4
- package/dist/chunk-OKCSGNCU.js.map +1 -0
- package/dist/{chunk-H2RGMX6L.js → chunk-OWYX4BEI.js} +3 -3
- package/dist/{chunk-H2RGMX6L.js.map → chunk-OWYX4BEI.js.map} +1 -1
- package/dist/csv.d.ts +1 -3
- package/dist/dates.d.ts +27 -1
- package/dist/dates.js +1 -1
- package/dist/form-types.d.ts +1 -70
- package/dist/hooks/index.d.ts +3 -4
- package/dist/hooks/index.js +6 -5
- package/dist/hooks/mutation-mode.d.ts +1 -3
- package/dist/hooks/related-keys.d.ts +1 -3
- package/dist/hooks/use-capabilities.d.ts +1 -2
- package/dist/hooks/use-infinite-resource.d.ts +1 -3
- package/dist/hooks/use-link-options.d.ts +58 -0
- package/dist/hooks/use-link-options.js +10 -0
- package/dist/hooks/use-link-options.js.map +1 -0
- package/dist/hooks/use-live.d.ts +1 -3
- package/dist/hooks/use-one.d.ts +1 -3
- package/dist/hooks/use-relation-label.d.ts +8 -4
- package/dist/hooks/use-relation-label.js +1 -1
- package/dist/hooks/use-resource-form.d.ts +1 -3
- package/dist/hooks/use-resource-form.js +2 -2
- package/dist/hooks/use-resource.d.ts +1 -3
- package/dist/hooks/use-write.d.ts +1 -3
- package/dist/index.d.ts +5 -6
- package/dist/index.js +6 -5
- package/dist/provider/index.d.ts +4 -6
- package/dist/resource-view/index.d.ts +85 -4
- package/dist/resource-view/index.js +122 -34
- package/dist/resource-view/index.js.map +1 -1
- package/dist/schema/index.d.ts +3 -5
- package/dist/testing/index.d.ts +2 -4
- package/dist/types-r_Rlw7BB.d.ts +800 -0
- package/dist/{write-outcome-CFnpciUI.d.ts → write-outcome-BWV34wh5.d.ts} +1 -1
- package/package.json +1 -1
- package/dist/chunk-227N654S.js.map +0 -1
- package/dist/chunk-X6EO3XBB.js.map +0 -1
- package/dist/chunk-XMC4EJUE.js.map +0 -1
- package/dist/types-CXhqXPN1.d.ts +0 -367
- package/dist/types-o8j7g6O6.d.ts +0 -331
|
@@ -0,0 +1,800 @@
|
|
|
1
|
+
type FieldType = "text" | "number" | "email"
|
|
2
|
+
/** A phone number: `type="tel"` and the phone keypad. Stored as text. */
|
|
3
|
+
| "tel" | "url" | "textarea" | "select" | "checkbox" | "switch" | "date" | "hidden" | "relation" | "file" | "image" | "array";
|
|
4
|
+
interface SelectOption {
|
|
5
|
+
value: string;
|
|
6
|
+
label: string;
|
|
7
|
+
}
|
|
8
|
+
interface ResourceFormFieldDef {
|
|
9
|
+
key: string;
|
|
10
|
+
label?: string;
|
|
11
|
+
type?: FieldType;
|
|
12
|
+
placeholder?: string;
|
|
13
|
+
required?: boolean;
|
|
14
|
+
defaultValue?: unknown;
|
|
15
|
+
options?: SelectOption[];
|
|
16
|
+
hidden?: boolean;
|
|
17
|
+
/** Shown read-only when editing, and never sent by an edit (a create still sends it). */
|
|
18
|
+
readOnlyOnEdit?: boolean;
|
|
19
|
+
/**
|
|
20
|
+
* The column takes null. A left-empty input is then sent as null on an edit and left out of
|
|
21
|
+
* a create (so the column's default applies), text included. `false`: an empty text input keeps
|
|
22
|
+
* sending "" (left out of a create when `hasDefault`), while an empty input of another type is
|
|
23
|
+
* handled as for `true`, since "" is never a valid value for those. Unset, the form doesn't know
|
|
24
|
+
* the column: every empty input is sent as it is ("" or undefined), on a create and an edit.
|
|
25
|
+
*/
|
|
26
|
+
nullable?: boolean;
|
|
27
|
+
/**
|
|
28
|
+
* The column has a default: a create leaves an empty input out, text included, so the default
|
|
29
|
+
* applies. Acts only when `nullable` is set.
|
|
30
|
+
*/
|
|
31
|
+
hasDefault?: boolean;
|
|
32
|
+
description?: string;
|
|
33
|
+
/**
|
|
34
|
+
* The browser's autofill token (`name`, `given-name`, `email`, `tel`, `street-address`,
|
|
35
|
+
* `one-time-code`, `off`, ...). Unset, the input carries no `autocomplete` attribute, whatever
|
|
36
|
+
* its type, so the browser applies its own heuristics (it may still offer to fill it). Set a
|
|
37
|
+
* token on forms about the viewer (sign-up, their own profile), and `off` on a form about
|
|
38
|
+
* someone else (an admin editing a member).
|
|
39
|
+
*/
|
|
40
|
+
autoComplete?: string;
|
|
41
|
+
/**
|
|
42
|
+
* Which on-screen keyboard a phone shows. Unset, it follows the type: `email`, `tel`, `url`,
|
|
43
|
+
* and, for a number with `min >= 0`, `decimal` (which has no minus key, so a number that can be
|
|
44
|
+
* negative keeps the browser's own keyboard).
|
|
45
|
+
*/
|
|
46
|
+
inputMode?: "none" | "text" | "decimal" | "numeric" | "tel" | "search" | "email" | "url";
|
|
47
|
+
/** The label on the keyboard's Return key (`next`, `done`, `go`, `search`, `send`). */
|
|
48
|
+
enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send";
|
|
49
|
+
min?: number;
|
|
50
|
+
max?: number;
|
|
51
|
+
rows?: number;
|
|
52
|
+
/**
|
|
53
|
+
* Longest value accepted by a text-like field (text, email, url, textarea).
|
|
54
|
+
* Validated on save, and the web renderer also sets the input's
|
|
55
|
+
* `maxLength` so the user cannot type past it.
|
|
56
|
+
*/
|
|
57
|
+
maxLength?: number;
|
|
58
|
+
/**
|
|
59
|
+
* A link's picker: lists `resource` through the data provider (its row-level security), searched
|
|
60
|
+
* and paged on the server, and stores the picked row's `valueField`.
|
|
61
|
+
*/
|
|
62
|
+
relation?: {
|
|
63
|
+
resource: string;
|
|
64
|
+
/** The linked field that names a row. Unset: the provider's `describe`, else a name-like field. */
|
|
65
|
+
labelField?: string;
|
|
66
|
+
valueField?: string;
|
|
67
|
+
/** Show the search box. Default: once there are more than ten rows, or more pages. */
|
|
68
|
+
searchable?: boolean;
|
|
69
|
+
allowCreate?: boolean;
|
|
70
|
+
/** The linked fields a search matches. Default: `labelField`. */
|
|
71
|
+
searchFields?: string[];
|
|
72
|
+
/**
|
|
73
|
+
* Filters every list request carries (the linked view's scope and default filter), fixed or
|
|
74
|
+
* from the form's values, for a picker that follows another field.
|
|
75
|
+
*/
|
|
76
|
+
filters?: FilterParam[] | ((values: Readonly<Record<string, unknown>>) => FilterParam[]);
|
|
77
|
+
/** The words for a picked row the viewer can't see, or that's gone. Never its raw id. */
|
|
78
|
+
missingLabel?: string;
|
|
79
|
+
/**
|
|
80
|
+
* How the key reaches the form. `"text"` (default, as before): the key as a string, `""` for
|
|
81
|
+
* none. `"row"`: as the row holds it (a number stays a number), `null` for None; a view's
|
|
82
|
+
* link uses it.
|
|
83
|
+
*/
|
|
84
|
+
keys?: "text" | "row";
|
|
85
|
+
};
|
|
86
|
+
/** Accepted file types, e.g. "image/*", ".pdf,.doc". */
|
|
87
|
+
accept?: string;
|
|
88
|
+
/** Max file size in bytes. Default 10MB. */
|
|
89
|
+
maxSize?: number;
|
|
90
|
+
/** Allow multiple files. */
|
|
91
|
+
multiple?: boolean;
|
|
92
|
+
/** Sub-field definitions for array (child records) fields. */
|
|
93
|
+
arrayFields?: ResourceFormFieldDef[];
|
|
94
|
+
/** Minimum number of array items. */
|
|
95
|
+
arrayMin?: number;
|
|
96
|
+
/** Maximum number of array items. */
|
|
97
|
+
arrayMax?: number;
|
|
98
|
+
/** Group heading for field grouping in the form. */
|
|
99
|
+
group?: string;
|
|
100
|
+
/** Column span in 2-column layout. Default 1. */
|
|
101
|
+
colSpan?: 1 | 2;
|
|
102
|
+
/** Return false to hide this field based on current form values. */
|
|
103
|
+
visible?: (values: Record<string, unknown>) => boolean;
|
|
104
|
+
/** Return true to disable this field based on current form values. */
|
|
105
|
+
disabled?: (values: Record<string, unknown>) => boolean;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Portable storage type of a field — what kind of value the store holds,
|
|
110
|
+
* independent of how a UI should edit it. The exact native type, when the
|
|
111
|
+
* store reports one, is on {@link FieldSchema.dbType}.
|
|
112
|
+
*
|
|
113
|
+
* Exactly the six types the switchboard shipped as `FieldType`, so existing
|
|
114
|
+
* exhaustive maps over it keep compiling. Finer distinctions (date versus
|
|
115
|
+
* timestamp, enum, uuid) live in `dbType` and `widget`, not here.
|
|
116
|
+
*/
|
|
117
|
+
type StorageType = "string" | "number" | "boolean" | "datetime" | "json" | "relation";
|
|
118
|
+
/** A canonical, provider-agnostic row. Keys are field names from the schema. */
|
|
119
|
+
type DataRow = Record<string, unknown>;
|
|
120
|
+
/**
|
|
121
|
+
* What the CURRENT user may do with one field. Reported by a provider's
|
|
122
|
+
* `describe()`; never inferred in the browser.
|
|
123
|
+
*
|
|
124
|
+
* `read: false` means the value is never sent to this user, so the column
|
|
125
|
+
* must not render at all (an answer key, a payout amount). `update: false`
|
|
126
|
+
* with `read: true` renders the column read-only.
|
|
127
|
+
*/
|
|
128
|
+
interface FieldPermissions {
|
|
129
|
+
readonly read: boolean;
|
|
130
|
+
readonly update: boolean;
|
|
131
|
+
/** Why `update` (or `read`) is false, in one human sentence. */
|
|
132
|
+
readonly reason?: string;
|
|
133
|
+
}
|
|
134
|
+
/** A foreign-key style link from this field to another resource's field. */
|
|
135
|
+
interface FieldReference {
|
|
136
|
+
readonly resource: string;
|
|
137
|
+
readonly field: string;
|
|
138
|
+
}
|
|
139
|
+
interface FieldSchema {
|
|
140
|
+
/** Canonical field name in the resource's shape (provider-agnostic). */
|
|
141
|
+
readonly name: string;
|
|
142
|
+
/** Portable storage type. */
|
|
143
|
+
readonly type: StorageType;
|
|
144
|
+
/** True when a row may omit this field. */
|
|
145
|
+
readonly optional?: boolean;
|
|
146
|
+
/**
|
|
147
|
+
* True when the field holds an ORDERED LIST of `type` values (e.g. a
|
|
148
|
+
* multi-relation like `deps`/`serves`). Promotion emits a Postgres ARRAY
|
|
149
|
+
* column (`<base>[]`) instead of a lossy scalar, so the cardinality survives
|
|
150
|
+
* L1→L3 (CMT-1742-014).
|
|
151
|
+
*/
|
|
152
|
+
readonly array?: boolean;
|
|
153
|
+
/** Human note (surfaces in describe()/drift reports). */
|
|
154
|
+
readonly description?: string;
|
|
155
|
+
/** Human label, e.g. "Date of birth". Absent means a UI derives one from `name`. */
|
|
156
|
+
readonly label?: string;
|
|
157
|
+
/** The store's exact type, e.g. `timestamp with time zone` or `public.status`. */
|
|
158
|
+
readonly dbType?: string;
|
|
159
|
+
/** Which control fits this field. A hint: a UI may still choose another. */
|
|
160
|
+
readonly widget?: FieldType;
|
|
161
|
+
/** True when the store accepts null for this field. */
|
|
162
|
+
readonly nullable?: boolean;
|
|
163
|
+
/** True when the store fills the field itself on insert. */
|
|
164
|
+
readonly hasDefault?: boolean;
|
|
165
|
+
/** True when the store computes the field; it is never written. */
|
|
166
|
+
readonly generated?: boolean;
|
|
167
|
+
/** Allowed values, for enum-like fields. */
|
|
168
|
+
readonly enumValues?: readonly string[];
|
|
169
|
+
/** The resource and field this one points at, when it is a link. */
|
|
170
|
+
readonly references?: FieldReference;
|
|
171
|
+
/** The current user's rights on this field, when a provider reports them. */
|
|
172
|
+
readonly permissions?: FieldPermissions;
|
|
173
|
+
/**
|
|
174
|
+
* The server owns this field (a status it derives, a total, an audit stamp): clients never write
|
|
175
|
+
* it, so a UI shows it read-only. Declared once (`@genesis {"readonly": true}`); the database's
|
|
176
|
+
* own guards still enforce it.
|
|
177
|
+
*/
|
|
178
|
+
readonly readOnly?: boolean;
|
|
179
|
+
/**
|
|
180
|
+
* The value is sensitive (a note for staff, a health detail): a UI leaves it out of lists, exports
|
|
181
|
+
* and previews unless a screen asks for it. Hiding it from a user is the database's job.
|
|
182
|
+
*/
|
|
183
|
+
readonly sensitive?: boolean;
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* One declaration of a resource: its fields and its identity.
|
|
187
|
+
*
|
|
188
|
+
* `key` names the identity field, or several for a composite key (a junction
|
|
189
|
+
* table keyed on `(team_id, user_id)`). Use {@link keyFields} to read it as
|
|
190
|
+
* a list without caring which form it took.
|
|
191
|
+
*/
|
|
192
|
+
interface ResourceContract<Row extends DataRow = DataRow> {
|
|
193
|
+
/** Resource name the app addresses, e.g. "tickets" or "public.tickets". */
|
|
194
|
+
readonly name: string;
|
|
195
|
+
/**
|
|
196
|
+
* Identity field name, or names for a composite key, in key order.
|
|
197
|
+
*
|
|
198
|
+
* Typed `string` (not `keyof Row & string`) on purpose: `keyof Row` is a
|
|
199
|
+
* dependent type that TypeScript checks contravariantly, which would make
|
|
200
|
+
* `ResourceContract<WorkCycleRow>` non-assignable to the erased
|
|
201
|
+
* `ResourceContract<DataRow>` that generic consumers accept. The key is
|
|
202
|
+
* validated against the field schema at runtime instead.
|
|
203
|
+
*/
|
|
204
|
+
readonly key: string | readonly string[];
|
|
205
|
+
readonly fields: readonly FieldSchema[];
|
|
206
|
+
/** Optional doc string. */
|
|
207
|
+
readonly description?: string;
|
|
208
|
+
/** Human label, e.g. "Clients". */
|
|
209
|
+
readonly label?: string;
|
|
210
|
+
/** The field that best names a row to a person (a name or title), for links and pickers. */
|
|
211
|
+
readonly labelField?: string;
|
|
212
|
+
/** What one row is called in sentences ("brand"), and several ("brands") when not `noun` + "s". */
|
|
213
|
+
readonly noun?: string;
|
|
214
|
+
readonly nounPlural?: string;
|
|
215
|
+
/** Phantom marker so `Row` is inferable from a contract. */
|
|
216
|
+
readonly __row?: Row;
|
|
217
|
+
}
|
|
218
|
+
/** The row type a contract describes (its phantom `__row`), or `DataRow` when it carries none. */
|
|
219
|
+
type RowOf<C> = C extends {
|
|
220
|
+
readonly __row?: infer R;
|
|
221
|
+
} ? (unknown extends R ? DataRow : NonNullable<R>) : DataRow;
|
|
222
|
+
/**
|
|
223
|
+
* Declares a resource contract for a row type, keeping the literal contract (field names, key,
|
|
224
|
+
* labelField) and attaching the row type so views can read it with `RowOf`. `labelField` must be
|
|
225
|
+
* one of the row's fields.
|
|
226
|
+
*
|
|
227
|
+
* ```ts
|
|
228
|
+
* export const publicBrands = defineResource<PublicBrandsRow>()({ name: "public.brands", key: "id", fields: [...] });
|
|
229
|
+
* type Row = RowOf<typeof publicBrands>; // PublicBrandsRow
|
|
230
|
+
* ```
|
|
231
|
+
*/
|
|
232
|
+
declare function defineResource<Row extends DataRow>(): <const C extends ResourceContract<Row> & {
|
|
233
|
+
readonly labelField?: keyof Row & string;
|
|
234
|
+
}>(contract: C) => C & {
|
|
235
|
+
readonly __row?: Row;
|
|
236
|
+
};
|
|
237
|
+
/** What the current user may do with a whole resource. */
|
|
238
|
+
interface ResourceAccess {
|
|
239
|
+
readonly read: boolean;
|
|
240
|
+
/** True when at least one field can be updated on rows this user can see. */
|
|
241
|
+
readonly update: boolean;
|
|
242
|
+
/** Why `update` (or `read`) is false, in one human sentence. */
|
|
243
|
+
readonly reason?: string;
|
|
244
|
+
/** True when this user may add rows. Absent means the provider doesn't say. */
|
|
245
|
+
readonly create?: boolean;
|
|
246
|
+
/** True when this user may delete rows they can see. */
|
|
247
|
+
readonly delete?: boolean;
|
|
248
|
+
/** True when this user may read a row's audit history. */
|
|
249
|
+
readonly history?: boolean;
|
|
250
|
+
/** True when this user may read and add comments on rows they can see. */
|
|
251
|
+
readonly comment?: boolean;
|
|
252
|
+
/** Why `create`, `delete`, `history` or `comment` is false, in one human sentence each. */
|
|
253
|
+
readonly reasons?: {
|
|
254
|
+
readonly create?: string;
|
|
255
|
+
readonly delete?: string;
|
|
256
|
+
readonly history?: string;
|
|
257
|
+
readonly comment?: string;
|
|
258
|
+
};
|
|
259
|
+
}
|
|
260
|
+
/**
|
|
261
|
+
* How another resource relates to this one, from the store's foreign keys.
|
|
262
|
+
*
|
|
263
|
+
* - `one`: a field on THIS resource points at one row of `resource`.
|
|
264
|
+
* - `many`: rows of `resource` point at this row through their `field`.
|
|
265
|
+
* - `through`: many rows of `resource`, linked by the junction resource in
|
|
266
|
+
* `through` (a table whose key is two foreign keys).
|
|
267
|
+
*/
|
|
268
|
+
interface ResourceRelation {
|
|
269
|
+
readonly kind: "one" | "many" | "through";
|
|
270
|
+
/** The related resource. */
|
|
271
|
+
readonly resource: string;
|
|
272
|
+
/**
|
|
273
|
+
* `one`: the field on this resource. `many`: the field on `resource` that
|
|
274
|
+
* holds this row's key. `through`: the junction's field holding this row's key.
|
|
275
|
+
*/
|
|
276
|
+
readonly field: string;
|
|
277
|
+
/** For `through`: the junction resource, and its field pointing at `resource`. */
|
|
278
|
+
readonly through?: {
|
|
279
|
+
readonly resource: string;
|
|
280
|
+
readonly otherField: string;
|
|
281
|
+
};
|
|
282
|
+
/** True when at most one related row can exist (a unique foreign key). */
|
|
283
|
+
readonly unique?: boolean;
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* The column a provider checks on every update so an edit never silently
|
|
287
|
+
* overwrites someone else's. Only reported when the store itself advances it
|
|
288
|
+
* on every successful update (a trigger such as `moddatetime`), because a
|
|
289
|
+
* column nothing advances detects nothing.
|
|
290
|
+
*/
|
|
291
|
+
interface VersionField {
|
|
292
|
+
/**
|
|
293
|
+
* The field holding the version. A provider with versioned writes returns
|
|
294
|
+
* each row with its exact version token in this field, as a string, and
|
|
295
|
+
* `expectedVersion` echoes `String(row[field])` back unchanged.
|
|
296
|
+
*/
|
|
297
|
+
readonly field: string;
|
|
298
|
+
/**
|
|
299
|
+
* `row`: no column tracks versions, so the token is a fingerprint of the
|
|
300
|
+
* row's values, and `field` is a name the provider adds to each record
|
|
301
|
+
* (it is not one of the resource's fields).
|
|
302
|
+
*/
|
|
303
|
+
readonly kind: "integer" | "timestamp" | "row";
|
|
304
|
+
}
|
|
305
|
+
/**
|
|
306
|
+
* A resource as `describe()` reports it for the CURRENT user: the contract,
|
|
307
|
+
* plus what this user may do. Fields the user may not read are left out
|
|
308
|
+
* entirely, not marked hidden.
|
|
309
|
+
*/
|
|
310
|
+
interface ResourceSchema<Row extends DataRow = DataRow> extends ResourceContract<Row> {
|
|
311
|
+
/** Human label, e.g. "Clients". */
|
|
312
|
+
readonly label?: string;
|
|
313
|
+
readonly access: ResourceAccess;
|
|
314
|
+
/** Present only when writes can be version-checked. */
|
|
315
|
+
readonly version?: VersionField;
|
|
316
|
+
/** The field that best names a row to a person (a name or title), for links and pickers. */
|
|
317
|
+
readonly labelField?: string;
|
|
318
|
+
/** Resources this one links to or is linked from. Only ones this user may see. */
|
|
319
|
+
readonly relations?: readonly ResourceRelation[];
|
|
320
|
+
/** Fields the user may set when creating a row. Absent when creating isn't allowed. */
|
|
321
|
+
readonly createFields?: readonly string[];
|
|
322
|
+
/** Row actions this user may run: each calls the app's own function on one row. */
|
|
323
|
+
readonly actions?: readonly RowAction[];
|
|
324
|
+
}
|
|
325
|
+
/** A named operation on one row, carried out by the app's own database function. */
|
|
326
|
+
interface RowAction {
|
|
327
|
+
readonly name: string;
|
|
328
|
+
readonly label: string;
|
|
329
|
+
/** Ask before running, with this question. */
|
|
330
|
+
readonly confirm?: string;
|
|
331
|
+
/** One sentence on what it does. */
|
|
332
|
+
readonly description?: string;
|
|
333
|
+
}
|
|
334
|
+
/** A comment on a record. */
|
|
335
|
+
interface RecordComment {
|
|
336
|
+
readonly id: string;
|
|
337
|
+
/** The signed-in user who wrote it (the token's `sub`). */
|
|
338
|
+
readonly author: string;
|
|
339
|
+
readonly body: string;
|
|
340
|
+
/** ISO 8601, as the store recorded it. */
|
|
341
|
+
readonly createdAt: string;
|
|
342
|
+
}
|
|
343
|
+
/** One entry of `listResources()`: enough to draw a sidebar. */
|
|
344
|
+
interface ResourceSummary {
|
|
345
|
+
readonly name: string;
|
|
346
|
+
readonly label?: string;
|
|
347
|
+
readonly description?: string;
|
|
348
|
+
readonly access: ResourceAccess;
|
|
349
|
+
}
|
|
350
|
+
/** Filter operators a provider may support. Mirrors `FilterParam["operator"]`. */
|
|
351
|
+
type FilterOperator = "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains" | "in" | "between" | "is_null" | "is_not_null";
|
|
352
|
+
/**
|
|
353
|
+
* What a provider can do. A UI hides any control the provider cannot serve,
|
|
354
|
+
* instead of letting it error (DATA-STUDIO.md decision 9).
|
|
355
|
+
*/
|
|
356
|
+
interface ProviderCapabilities {
|
|
357
|
+
/** Server-side text search across fields. */
|
|
358
|
+
readonly search: boolean;
|
|
359
|
+
/** Server-side sort. */
|
|
360
|
+
readonly sort: boolean;
|
|
361
|
+
/** Server-side filter operators. Empty means no server filtering. */
|
|
362
|
+
readonly filterOperators: readonly FilterOperator[];
|
|
363
|
+
/** `updateMany` / `deleteMany` in one transaction. */
|
|
364
|
+
readonly bulkWrites: boolean;
|
|
365
|
+
/** Updates honour `expectedVersion` and reject stale writes. */
|
|
366
|
+
readonly versionedWrites: boolean;
|
|
367
|
+
/** Records may be keyed by more than one field. */
|
|
368
|
+
readonly compositeKeys: boolean;
|
|
369
|
+
/** Server-side sort by several fields at once (`ListParams.sorts`). */
|
|
370
|
+
readonly multiSort?: boolean;
|
|
371
|
+
/** `create` and `deleteOne` are served, subject to each resource's access. */
|
|
372
|
+
readonly create?: boolean;
|
|
373
|
+
readonly delete?: boolean;
|
|
374
|
+
/** `history` is served, subject to each resource's access. */
|
|
375
|
+
readonly history?: boolean;
|
|
376
|
+
/** `importRows` is served, with a dry run. */
|
|
377
|
+
readonly import?: boolean;
|
|
378
|
+
/** `undo` is served. */
|
|
379
|
+
readonly undo?: boolean;
|
|
380
|
+
/** `runAction` is served. */
|
|
381
|
+
readonly actions?: boolean;
|
|
382
|
+
/** `comments` and `addComment` are served. */
|
|
383
|
+
readonly comments?: boolean;
|
|
384
|
+
/**
|
|
385
|
+
* The most rows one `getList` page may ask for. A request for more is
|
|
386
|
+
* refused (it is not cut short, which would shift later page boundaries),
|
|
387
|
+
* so a client that wants every row must page at this size or less.
|
|
388
|
+
*/
|
|
389
|
+
readonly maxPerPage?: number;
|
|
390
|
+
/**
|
|
391
|
+
* A delete moves the record to a recycle bin (it can be restored) instead
|
|
392
|
+
* of removing it. Asked per resource: `capabilities(resource)`.
|
|
393
|
+
*/
|
|
394
|
+
readonly softDelete?: boolean;
|
|
395
|
+
/**
|
|
396
|
+
* `create`, `update` and `deleteOne` honour `keepalive: true` in their
|
|
397
|
+
* params (e.g. `fetch(url, { keepalive: true })`), so a write sent while
|
|
398
|
+
* the page unloads still reaches the server. Without it, closing the tab
|
|
399
|
+
* while an optimistic or undoable write is being sent shows the browser's
|
|
400
|
+
* "Leave site?" prompt.
|
|
401
|
+
*/
|
|
402
|
+
readonly keepaliveWrites?: boolean;
|
|
403
|
+
/**
|
|
404
|
+
* `getList` serves cursor (keyset) paging: `pagination.cursor` in,
|
|
405
|
+
* `nextCursor` out. Pages stay correct while rows are added or removed,
|
|
406
|
+
* and a deep page costs no more than the first.
|
|
407
|
+
*/
|
|
408
|
+
readonly cursorPagination?: boolean;
|
|
409
|
+
/**
|
|
410
|
+
* `subscribe` reports changes to this resource (asked per resource:
|
|
411
|
+
* `capabilities(resource)`), so `live` lists and records refresh when
|
|
412
|
+
* someone else changes them.
|
|
413
|
+
*/
|
|
414
|
+
readonly realtime?: boolean;
|
|
415
|
+
}
|
|
416
|
+
/** One audit record, as committed alongside the edit it describes. */
|
|
417
|
+
interface AuditEntry {
|
|
418
|
+
readonly id: string;
|
|
419
|
+
/** ISO 8601 timestamp, as the store recorded it. */
|
|
420
|
+
readonly occurredAt: string;
|
|
421
|
+
/** The signed-in user who made the edit (the token's `sub`). */
|
|
422
|
+
readonly actor: string | null;
|
|
423
|
+
readonly resource: string;
|
|
424
|
+
/** The record's key, field name → value. */
|
|
425
|
+
readonly key: DataRow;
|
|
426
|
+
/** `run` is a row action; `rowAction` names it. */
|
|
427
|
+
readonly action: "create" | "update" | "delete" | "run";
|
|
428
|
+
/** For `run`: which row action. */
|
|
429
|
+
readonly rowAction?: string;
|
|
430
|
+
/** Values of the changed fields before the edit. */
|
|
431
|
+
readonly before: DataRow | null;
|
|
432
|
+
/** Values of the changed fields after the edit. */
|
|
433
|
+
readonly after: DataRow | null;
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
/** Record identifier — supports both string UUIDs and numeric auto-increment IDs. */
|
|
437
|
+
type Identifier = string | number;
|
|
438
|
+
/** Base record type — all resources must have an id. */
|
|
439
|
+
type BaseRecord = {
|
|
440
|
+
id: Identifier;
|
|
441
|
+
[key: string]: unknown;
|
|
442
|
+
};
|
|
443
|
+
/**
|
|
444
|
+
* Pagination parameters: offset (`page`) or cursor (keyset).
|
|
445
|
+
*
|
|
446
|
+
* Cursor paging: set `cursor` to `null` for the first page and to the
|
|
447
|
+
* previous page's `ListResult.nextCursor` for each next one. A provider that
|
|
448
|
+
* serves it (`capabilities().cursorPagination`) then ignores `page` and
|
|
449
|
+
* returns `nextCursor`; one that doesn't ignores `cursor` and pages by
|
|
450
|
+
* `page`, returning no `nextCursor`. `useInfiniteResource` handles both.
|
|
451
|
+
*/
|
|
452
|
+
interface PaginationParam {
|
|
453
|
+
page: number;
|
|
454
|
+
perPage: number;
|
|
455
|
+
/** `null`: the first page, by cursor. A string: the page after that cursor. Opaque. */
|
|
456
|
+
cursor?: string | null;
|
|
457
|
+
}
|
|
458
|
+
/** Sort direction for a single field. */
|
|
459
|
+
interface SortParam {
|
|
460
|
+
field: string;
|
|
461
|
+
order: "asc" | "desc";
|
|
462
|
+
}
|
|
463
|
+
/**
|
|
464
|
+
* Filter expressions — discriminated union by operator.
|
|
465
|
+
* Filters are AND-ed together in queries.
|
|
466
|
+
*/
|
|
467
|
+
/** Operators that compare a field against a single scalar value. */
|
|
468
|
+
interface ScalarFilter {
|
|
469
|
+
field: string;
|
|
470
|
+
operator: "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains";
|
|
471
|
+
value: string | number | boolean;
|
|
472
|
+
}
|
|
473
|
+
/** Operator that checks field membership in a list. */
|
|
474
|
+
interface ArrayFilter {
|
|
475
|
+
field: string;
|
|
476
|
+
operator: "in";
|
|
477
|
+
value: (string | number | boolean)[];
|
|
478
|
+
}
|
|
479
|
+
/** Operator that checks field is within a range. */
|
|
480
|
+
interface RangeFilter {
|
|
481
|
+
field: string;
|
|
482
|
+
operator: "between";
|
|
483
|
+
value: [string | number, string | number];
|
|
484
|
+
}
|
|
485
|
+
/** Operators that check for null/non-null — no value needed. */
|
|
486
|
+
interface NullFilter {
|
|
487
|
+
field: string;
|
|
488
|
+
operator: "is_null" | "is_not_null";
|
|
489
|
+
}
|
|
490
|
+
type FilterParam = ScalarFilter | ArrayFilter | RangeFilter | NullFilter;
|
|
491
|
+
/**
|
|
492
|
+
* How a list's total is counted: `exact` counts every matching row (slow on
|
|
493
|
+
* large tables), `estimated` and `planned` ask the database's statistics
|
|
494
|
+
* (fast, approximate), `none` skips the count (`total` is -1).
|
|
495
|
+
*/
|
|
496
|
+
type CountMode = "exact" | "estimated" | "planned" | "none";
|
|
497
|
+
/** Parameters for `getList`. */
|
|
498
|
+
interface ListParams {
|
|
499
|
+
pagination?: PaginationParam;
|
|
500
|
+
sort?: SortParam;
|
|
501
|
+
/**
|
|
502
|
+
* Sort by several fields, first one first. Wins over `sort` on a provider
|
|
503
|
+
* whose capabilities report `multiSort`; others use only `sort`.
|
|
504
|
+
*/
|
|
505
|
+
sorts?: SortParam[];
|
|
506
|
+
filters?: FilterParam[];
|
|
507
|
+
/** Supabase select syntax, e.g. "*, author:profiles(name)". Mock provider ignores this. */
|
|
508
|
+
select?: string;
|
|
509
|
+
/** Multi-field text search (case-insensitive). */
|
|
510
|
+
search?: {
|
|
511
|
+
query: string;
|
|
512
|
+
fields: string[];
|
|
513
|
+
};
|
|
514
|
+
/** How to count `total`; wins over the resource's own setting. Providers that can't choose count exactly. */
|
|
515
|
+
count?: CountMode;
|
|
516
|
+
}
|
|
517
|
+
/** Result of `getList`. */
|
|
518
|
+
interface ListResult<T> {
|
|
519
|
+
data: T[];
|
|
520
|
+
/**
|
|
521
|
+
* Rows matching the filters and search. `-1` means not counted: in cursor
|
|
522
|
+
* mode after the first page, or with `count: "none"`. A pager must treat -1
|
|
523
|
+
* as unknown (no last page number) and stop on a short page instead.
|
|
524
|
+
*/
|
|
525
|
+
total: number;
|
|
526
|
+
/** True when `total` is the database's estimate (`estimated` or `planned`), so a screen says "about". */
|
|
527
|
+
totalIsEstimate?: boolean;
|
|
528
|
+
/**
|
|
529
|
+
* Cursor mode only: the cursor for the next page, or `null` when this is
|
|
530
|
+
* the last one. Absent when the provider paged by offset.
|
|
531
|
+
*/
|
|
532
|
+
nextCursor?: string | null;
|
|
533
|
+
/**
|
|
534
|
+
* Cursor mode only: the cursor for the page before this one, or `null` on
|
|
535
|
+
* the first page. Lets an infinite list drop pages from the front (TanStack
|
|
536
|
+
* Query's `maxPages`) and load them again when scrolled back.
|
|
537
|
+
*/
|
|
538
|
+
prevCursor?: string | null;
|
|
539
|
+
}
|
|
540
|
+
/** Parameters for `getOne`. */
|
|
541
|
+
interface GetOneParams {
|
|
542
|
+
id: Identifier;
|
|
543
|
+
/** Supabase select syntax, e.g. "*, author:profiles(name)". Defaults to "*". */
|
|
544
|
+
select?: string;
|
|
545
|
+
}
|
|
546
|
+
/** Result of `getOne`. */
|
|
547
|
+
interface GetOneResult<T> {
|
|
548
|
+
data: T;
|
|
549
|
+
}
|
|
550
|
+
/** Parameters for `getMany`. */
|
|
551
|
+
interface GetManyParams {
|
|
552
|
+
ids: Identifier[];
|
|
553
|
+
}
|
|
554
|
+
/** Result of `getMany`. */
|
|
555
|
+
interface GetManyResult<T> {
|
|
556
|
+
data: T[];
|
|
557
|
+
}
|
|
558
|
+
/** Parameters for `create`. */
|
|
559
|
+
interface CreateParams<T> {
|
|
560
|
+
data: Partial<T>;
|
|
561
|
+
/**
|
|
562
|
+
* Sent while the page unloads (an `undoable` write flushed on close or
|
|
563
|
+
* reload). A fetch-based provider should pass `keepalive: true` to `fetch`
|
|
564
|
+
* so the request outlives the page, and report `keepaliveWrites` in its
|
|
565
|
+
* capabilities. Others ignore it.
|
|
566
|
+
*/
|
|
567
|
+
keepalive?: boolean;
|
|
568
|
+
}
|
|
569
|
+
/** Result of `create`. */
|
|
570
|
+
interface CreateResult<T> {
|
|
571
|
+
data: T;
|
|
572
|
+
/** The audit entry committed with the new row, from a provider that audits. */
|
|
573
|
+
audit?: AuditEntry;
|
|
574
|
+
}
|
|
575
|
+
/** Parameters for `update`. */
|
|
576
|
+
interface UpdateParams<T> {
|
|
577
|
+
/**
|
|
578
|
+
* The record's identifier. For a composite key, the canonical string from
|
|
579
|
+
* `encodeRecordKey` (`@marktiderman/genesis-core/schema`).
|
|
580
|
+
*/
|
|
581
|
+
id: Identifier;
|
|
582
|
+
data: Partial<T>;
|
|
583
|
+
/**
|
|
584
|
+
* The version token the caller read the row at. A provider that reports
|
|
585
|
+
* `versionedWrites` in its capabilities rejects the update with a
|
|
586
|
+
* `DataWriteError` (`conflict`) when the row has moved on since, instead of
|
|
587
|
+
* overwriting someone else's edit. Providers without versioned writes
|
|
588
|
+
* ignore it.
|
|
589
|
+
*/
|
|
590
|
+
expectedVersion?: string | null;
|
|
591
|
+
/** See `CreateParams.keepalive`. */
|
|
592
|
+
keepalive?: boolean;
|
|
593
|
+
}
|
|
594
|
+
/** Result of `update`. */
|
|
595
|
+
interface UpdateResult<T> {
|
|
596
|
+
data: T;
|
|
597
|
+
/** The row's new version token, from a provider with versioned writes. */
|
|
598
|
+
version?: string | null;
|
|
599
|
+
/** The audit entry committed with the edit, from a provider that audits. */
|
|
600
|
+
audit?: AuditEntry;
|
|
601
|
+
}
|
|
602
|
+
/** Parameters for `deleteOne`. */
|
|
603
|
+
interface DeleteParams {
|
|
604
|
+
id: Identifier;
|
|
605
|
+
/** The version token the row was read at; see `UpdateParams.expectedVersion`. */
|
|
606
|
+
expectedVersion?: string | null;
|
|
607
|
+
/** See `CreateParams.keepalive`. */
|
|
608
|
+
keepalive?: boolean;
|
|
609
|
+
}
|
|
610
|
+
/** Result of `deleteOne`. */
|
|
611
|
+
interface DeleteResult {
|
|
612
|
+
data: {
|
|
613
|
+
id: Identifier;
|
|
614
|
+
};
|
|
615
|
+
/** The audit entry committed with the deletion, from a provider that audits. */
|
|
616
|
+
audit?: AuditEntry;
|
|
617
|
+
}
|
|
618
|
+
/** One row's change in a bulk update. */
|
|
619
|
+
interface BulkChange {
|
|
620
|
+
id: Identifier;
|
|
621
|
+
data: Record<string, unknown>;
|
|
622
|
+
/** The version token the row was read at. */
|
|
623
|
+
expectedVersion?: string | null;
|
|
624
|
+
}
|
|
625
|
+
/** Why one row of a bulk write or import didn't go through. */
|
|
626
|
+
interface RowFailure {
|
|
627
|
+
/** The row's position in the request, from 0. */
|
|
628
|
+
index: number;
|
|
629
|
+
id?: Identifier;
|
|
630
|
+
outcome: string;
|
|
631
|
+
message: string;
|
|
632
|
+
}
|
|
633
|
+
/** Result of a bulk write: every row changed, or none did. */
|
|
634
|
+
interface BulkResult {
|
|
635
|
+
/** Rows changed; always the number requested when `ok`. */
|
|
636
|
+
count: number;
|
|
637
|
+
ok: boolean;
|
|
638
|
+
/** Present when `ok` is false: every row that failed, so the caller can fix them all at once. */
|
|
639
|
+
failures?: RowFailure[];
|
|
640
|
+
/** One audit entry per row changed. */
|
|
641
|
+
audit?: AuditEntry[];
|
|
642
|
+
}
|
|
643
|
+
/** Parameters for `importRows`. */
|
|
644
|
+
interface ImportParams {
|
|
645
|
+
rows: Record<string, unknown>[];
|
|
646
|
+
/** Check every row against the database and change nothing. */
|
|
647
|
+
dryRun: boolean;
|
|
648
|
+
}
|
|
649
|
+
/** Parameters for `history`. */
|
|
650
|
+
interface HistoryParams {
|
|
651
|
+
id: Identifier;
|
|
652
|
+
/** Most recent first; default and maximum are the provider's. */
|
|
653
|
+
limit?: number;
|
|
654
|
+
}
|
|
655
|
+
/** A write that committed, as passed to a provider's `onWrite` and `invalidates`. */
|
|
656
|
+
interface WriteEvent {
|
|
657
|
+
resource: string;
|
|
658
|
+
kind: "create" | "update" | "delete";
|
|
659
|
+
id: Identifier;
|
|
660
|
+
/** The row as written, when the provider has it (not for a delete). */
|
|
661
|
+
record?: BaseRecord;
|
|
662
|
+
}
|
|
663
|
+
/**
|
|
664
|
+
* A change to a resource, as `DataProvider.subscribe` reports it.
|
|
665
|
+
*
|
|
666
|
+
* Treat it as a HINT that cached reads are stale, never as data to show:
|
|
667
|
+
* the Genesis hooks refetch through the provider's normal (RLS-checked)
|
|
668
|
+
* read instead of writing `record` into the cache. `changed` says only that
|
|
669
|
+
* something may have changed (e.g. after a reconnect, when events may have
|
|
670
|
+
* been missed), so every cached read of the resource should be refetched.
|
|
671
|
+
*/
|
|
672
|
+
type ResourceChangeEvent = {
|
|
673
|
+
type: "created" | "updated" | "deleted";
|
|
674
|
+
/** The changed record's id, when the provider knows it. */
|
|
675
|
+
id?: Identifier;
|
|
676
|
+
/** The record as the provider saw it, when it sends one. A hint only. */
|
|
677
|
+
record?: BaseRecord;
|
|
678
|
+
} | {
|
|
679
|
+
type: "changed";
|
|
680
|
+
};
|
|
681
|
+
/** What a `subscribe` call watches. Every field narrows; none is required. */
|
|
682
|
+
interface SubscribeParams {
|
|
683
|
+
/** Watch one record only. */
|
|
684
|
+
id?: Identifier;
|
|
685
|
+
/**
|
|
686
|
+
* The list's filters. A provider MAY use them to send fewer events; it
|
|
687
|
+
* may also ignore them and report every change to the resource.
|
|
688
|
+
*/
|
|
689
|
+
filters?: FilterParam[];
|
|
690
|
+
}
|
|
691
|
+
/**
|
|
692
|
+
* A cache key to invalidate after a write. Shaped like a TanStack Query
|
|
693
|
+
* `QueryKey` (`readonly unknown[]`), matched by prefix.
|
|
694
|
+
*/
|
|
695
|
+
type InvalidationKey = readonly unknown[];
|
|
696
|
+
interface DataProvider {
|
|
697
|
+
getList<T extends BaseRecord = BaseRecord>(resource: string, params: ListParams): Promise<ListResult<T>>;
|
|
698
|
+
getOne<T extends BaseRecord = BaseRecord>(resource: string, params: GetOneParams): Promise<GetOneResult<T>>;
|
|
699
|
+
getMany<T extends BaseRecord = BaseRecord>(resource: string, params: GetManyParams): Promise<GetManyResult<T>>;
|
|
700
|
+
create<T extends BaseRecord = BaseRecord>(resource: string, params: CreateParams<T>): Promise<CreateResult<T>>;
|
|
701
|
+
update<T extends BaseRecord = BaseRecord>(resource: string, params: UpdateParams<T>): Promise<UpdateResult<T>>;
|
|
702
|
+
deleteOne(resource: string, params: DeleteParams): Promise<DeleteResult>;
|
|
703
|
+
/**
|
|
704
|
+
* The resource's real shape for the CURRENT user: fields, key, version
|
|
705
|
+
* field, and per-field read and update rights. Fields the user may not read
|
|
706
|
+
* are omitted entirely.
|
|
707
|
+
*/
|
|
708
|
+
describe?(resource: string): Promise<ResourceSchema>;
|
|
709
|
+
/** Every resource this user may see, for a sidebar or a picker. */
|
|
710
|
+
listResources?(): Promise<ResourceSummary[]>;
|
|
711
|
+
/**
|
|
712
|
+
* What this provider can do, optionally for one resource. A UI hides the
|
|
713
|
+
* controls a provider cannot serve instead of letting them error.
|
|
714
|
+
*/
|
|
715
|
+
capabilities?(resource?: string): Promise<ProviderCapabilities>;
|
|
716
|
+
/**
|
|
717
|
+
* A record's audit history, most recent first, limited to the fields this
|
|
718
|
+
* user may read.
|
|
719
|
+
*/
|
|
720
|
+
history?(resource: string, params: HistoryParams): Promise<AuditEntry[]>;
|
|
721
|
+
/**
|
|
722
|
+
* Update many rows in ONE transaction. All of them change or none do: a
|
|
723
|
+
* single conflict, refusal or invalid value rolls back the rest, and the
|
|
724
|
+
* result lists every row that failed.
|
|
725
|
+
*/
|
|
726
|
+
updateMany?(resource: string, params: {
|
|
727
|
+
changes: BulkChange[];
|
|
728
|
+
}): Promise<BulkResult>;
|
|
729
|
+
/** Delete many rows in one transaction, all or none, each at its version. */
|
|
730
|
+
deleteMany?(resource: string, params: {
|
|
731
|
+
items: {
|
|
732
|
+
id: Identifier;
|
|
733
|
+
expectedVersion?: string | null;
|
|
734
|
+
}[];
|
|
735
|
+
}): Promise<BulkResult>;
|
|
736
|
+
/**
|
|
737
|
+
* Add rows from an import. With `dryRun`, every row is tried against the
|
|
738
|
+
* database and nothing is kept, so the result lists every row that would
|
|
739
|
+
* fail; without it, all rows are added in one transaction or none are.
|
|
740
|
+
*/
|
|
741
|
+
importRows?(resource: string, params: ImportParams): Promise<BulkResult>;
|
|
742
|
+
/**
|
|
743
|
+
* Undo one audited change with a compensating write: put the changed
|
|
744
|
+
* fields back, remove an added row, or restore a deleted one. Refused when
|
|
745
|
+
* the row has changed since.
|
|
746
|
+
*/
|
|
747
|
+
undo?(resource: string, params: {
|
|
748
|
+
auditId: string;
|
|
749
|
+
}): Promise<{
|
|
750
|
+
audit?: AuditEntry;
|
|
751
|
+
}>;
|
|
752
|
+
/**
|
|
753
|
+
* Run one of the resource's row actions (`ResourceSchema.actions`) on a
|
|
754
|
+
* row, at the version it was read. The app's function does the work; the
|
|
755
|
+
* row's change is audited.
|
|
756
|
+
*/
|
|
757
|
+
runAction?(resource: string, params: {
|
|
758
|
+
id: Identifier;
|
|
759
|
+
action: string;
|
|
760
|
+
expectedVersion?: string | null;
|
|
761
|
+
}): Promise<{
|
|
762
|
+
data: Record<string, unknown> | null;
|
|
763
|
+
audit?: AuditEntry;
|
|
764
|
+
}>;
|
|
765
|
+
/** A record's comments, oldest first. */
|
|
766
|
+
comments?(resource: string, params: {
|
|
767
|
+
id: Identifier;
|
|
768
|
+
}): Promise<RecordComment[]>;
|
|
769
|
+
/** Add a comment to a record, as the signed-in user. */
|
|
770
|
+
addComment?(resource: string, params: {
|
|
771
|
+
id: Identifier;
|
|
772
|
+
body: string;
|
|
773
|
+
}): Promise<RecordComment>;
|
|
774
|
+
/**
|
|
775
|
+
* Maps a stored row to the values an edit form starts from, for a resource
|
|
776
|
+
* whose form shape differs from its table (the reverse of a write's
|
|
777
|
+
* `prepare`). `useResourceForm` applies it in edit mode.
|
|
778
|
+
*/
|
|
779
|
+
toFormValues?(resource: string, record: Record<string, unknown>): Record<string, unknown>;
|
|
780
|
+
/**
|
|
781
|
+
* Watch a resource for changes made anywhere (other users, other tabs,
|
|
782
|
+
* server jobs). Calls `callback` for each change until the returned
|
|
783
|
+
* function is called, which must release everything the subscription
|
|
784
|
+
* holds (sockets, channels). Report `realtime: true` in `capabilities()`
|
|
785
|
+
* for the resources it serves; for others it may return a no-op.
|
|
786
|
+
*
|
|
787
|
+
* Events are invalidation hints: `useResource({ live: true })` and
|
|
788
|
+
* `useOne(..., { live: true })` refetch on them and never trust their
|
|
789
|
+
* payload.
|
|
790
|
+
*/
|
|
791
|
+
subscribe?(resource: string, params: SubscribeParams, callback: (event: ResourceChangeEvent) => void): () => void;
|
|
792
|
+
/**
|
|
793
|
+
* Other cache keys a committed write makes stale, beyond the resource's
|
|
794
|
+
* own `[resource]` keys. `useResource` and `useResourceForm` invalidate
|
|
795
|
+
* them after their writes.
|
|
796
|
+
*/
|
|
797
|
+
invalidates?(event: WriteEvent): InvalidationKey[];
|
|
798
|
+
}
|
|
799
|
+
|
|
800
|
+
export { type ArrayFilter as A, type BaseRecord as B, type CountMode as C, type DataProvider as D, type ResourceSchema as E, type FieldSchema as F, type GetManyParams as G, type HistoryParams as H, type InvalidationKey as I, type ResourceSummary as J, type RowAction as K, type ListParams as L, type RowFailure as M, type NullFilter as N, type RowOf as O, type PaginationParam as P, type ScalarFilter as Q, type RangeFilter as R, type SortParam as S, type SelectOption as T, type StorageType as U, type SubscribeParams as V, type WriteEvent as W, type UpdateParams as X, type UpdateResult as Y, type VersionField as Z, defineResource as _, type FilterParam as a, type Identifier as b, type AuditEntry as c, type BulkChange as d, type BulkResult as e, type CreateParams as f, type CreateResult as g, type DataRow as h, type DeleteParams as i, type DeleteResult as j, type FieldPermissions as k, type FieldReference as l, type FieldType as m, type FilterOperator as n, type GetManyResult as o, type GetOneParams as p, type GetOneResult as q, type ImportParams as r, type ListResult as s, type ProviderCapabilities as t, type RecordComment as u, type ResourceAccess as v, type ResourceChangeEvent as w, type ResourceContract as x, type ResourceFormFieldDef as y, type ResourceRelation as z };
|