@marktiderman/genesis-core 2.4.1 → 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.
- package/README.md +42 -0
- package/dist/{chunk-ZIMQUFXD.js → chunk-37RWGNIO.js} +9 -4
- package/dist/chunk-37RWGNIO.js.map +1 -0
- package/dist/chunk-BIIENNTW.js +497 -0
- 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-5NEOX2N7.js → chunk-OWYX4BEI.js} +4 -4
- package/dist/{chunk-5NEOX2N7.js.map → chunk-OWYX4BEI.js.map} +1 -1
- package/dist/csv.d.ts +1 -3
- package/dist/dates.d.ts +199 -1
- package/dist/dates.js +1 -1
- package/dist/errors.d.ts +8 -1
- package/dist/errors.js +1 -1
- package/dist/form-types.d.ts +1 -70
- package/dist/hooks/index.d.ts +3 -4
- package/dist/hooks/index.js +7 -6
- 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 +7 -6
- package/dist/provider/index.d.ts +4 -6
- package/dist/resource-view/index.d.ts +118 -4
- package/dist/resource-view/index.js +148 -35
- 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-3B4IFDMK.js +0 -117
- package/dist/chunk-3B4IFDMK.js.map +0 -1
- package/dist/chunk-X6EO3XBB.js.map +0 -1
- package/dist/chunk-XMC4EJUE.js.map +0 -1
- package/dist/chunk-ZIMQUFXD.js.map +0 -1
- package/dist/types-CXhqXPN1.d.ts +0 -367
- package/dist/types-o8j7g6O6.d.ts +0 -331
package/dist/types-o8j7g6O6.d.ts
DELETED
|
@@ -1,331 +0,0 @@
|
|
|
1
|
-
import { FieldType } from './form-types.js';
|
|
2
|
-
|
|
3
|
-
/**
|
|
4
|
-
* Portable storage type of a field — what kind of value the store holds,
|
|
5
|
-
* independent of how a UI should edit it. The exact native type, when the
|
|
6
|
-
* store reports one, is on {@link FieldSchema.dbType}.
|
|
7
|
-
*
|
|
8
|
-
* Exactly the six types the switchboard shipped as `FieldType`, so existing
|
|
9
|
-
* exhaustive maps over it keep compiling. Finer distinctions (date versus
|
|
10
|
-
* timestamp, enum, uuid) live in `dbType` and `widget`, not here.
|
|
11
|
-
*/
|
|
12
|
-
type StorageType = "string" | "number" | "boolean" | "datetime" | "json" | "relation";
|
|
13
|
-
/** A canonical, provider-agnostic row. Keys are field names from the schema. */
|
|
14
|
-
type DataRow = Record<string, unknown>;
|
|
15
|
-
/**
|
|
16
|
-
* What the CURRENT user may do with one field. Reported by a provider's
|
|
17
|
-
* `describe()`; never inferred in the browser.
|
|
18
|
-
*
|
|
19
|
-
* `read: false` means the value is never sent to this user, so the column
|
|
20
|
-
* must not render at all (an answer key, a payout amount). `update: false`
|
|
21
|
-
* with `read: true` renders the column read-only.
|
|
22
|
-
*/
|
|
23
|
-
interface FieldPermissions {
|
|
24
|
-
readonly read: boolean;
|
|
25
|
-
readonly update: boolean;
|
|
26
|
-
/** Why `update` (or `read`) is false, in one human sentence. */
|
|
27
|
-
readonly reason?: string;
|
|
28
|
-
}
|
|
29
|
-
/** A foreign-key style link from this field to another resource's field. */
|
|
30
|
-
interface FieldReference {
|
|
31
|
-
readonly resource: string;
|
|
32
|
-
readonly field: string;
|
|
33
|
-
}
|
|
34
|
-
interface FieldSchema {
|
|
35
|
-
/** Canonical field name in the resource's shape (provider-agnostic). */
|
|
36
|
-
readonly name: string;
|
|
37
|
-
/** Portable storage type. */
|
|
38
|
-
readonly type: StorageType;
|
|
39
|
-
/** True when a row may omit this field. */
|
|
40
|
-
readonly optional?: boolean;
|
|
41
|
-
/**
|
|
42
|
-
* True when the field holds an ORDERED LIST of `type` values (e.g. a
|
|
43
|
-
* multi-relation like `deps`/`serves`). Promotion emits a Postgres ARRAY
|
|
44
|
-
* column (`<base>[]`) instead of a lossy scalar, so the cardinality survives
|
|
45
|
-
* L1→L3 (CMT-1742-014).
|
|
46
|
-
*/
|
|
47
|
-
readonly array?: boolean;
|
|
48
|
-
/** Human note (surfaces in describe()/drift reports). */
|
|
49
|
-
readonly description?: string;
|
|
50
|
-
/** Human label, e.g. "Date of birth". Absent means a UI derives one from `name`. */
|
|
51
|
-
readonly label?: string;
|
|
52
|
-
/** The store's exact type, e.g. `timestamp with time zone` or `public.status`. */
|
|
53
|
-
readonly dbType?: string;
|
|
54
|
-
/** Which control fits this field. A hint: a UI may still choose another. */
|
|
55
|
-
readonly widget?: FieldType;
|
|
56
|
-
/** True when the store accepts null for this field. */
|
|
57
|
-
readonly nullable?: boolean;
|
|
58
|
-
/** True when the store fills the field itself on insert. */
|
|
59
|
-
readonly hasDefault?: boolean;
|
|
60
|
-
/** True when the store computes the field; it is never written. */
|
|
61
|
-
readonly generated?: boolean;
|
|
62
|
-
/** Allowed values, for enum-like fields. */
|
|
63
|
-
readonly enumValues?: readonly string[];
|
|
64
|
-
/** The resource and field this one points at, when it is a link. */
|
|
65
|
-
readonly references?: FieldReference;
|
|
66
|
-
/** The current user's rights on this field, when a provider reports them. */
|
|
67
|
-
readonly permissions?: FieldPermissions;
|
|
68
|
-
/**
|
|
69
|
-
* The server owns this field (a status it derives, a total, an audit stamp): clients never write
|
|
70
|
-
* it, so a UI shows it read-only. Declared once (`@genesis {"readonly": true}`); the database's
|
|
71
|
-
* own guards still enforce it.
|
|
72
|
-
*/
|
|
73
|
-
readonly readOnly?: boolean;
|
|
74
|
-
/**
|
|
75
|
-
* The value is sensitive (a note for staff, a health detail): a UI leaves it out of lists, exports
|
|
76
|
-
* and previews unless a screen asks for it. Hiding it from a user is the database's job.
|
|
77
|
-
*/
|
|
78
|
-
readonly sensitive?: boolean;
|
|
79
|
-
}
|
|
80
|
-
/**
|
|
81
|
-
* One declaration of a resource: its fields and its identity.
|
|
82
|
-
*
|
|
83
|
-
* `key` names the identity field, or several for a composite key (a junction
|
|
84
|
-
* table keyed on `(team_id, user_id)`). Use {@link keyFields} to read it as
|
|
85
|
-
* a list without caring which form it took.
|
|
86
|
-
*/
|
|
87
|
-
interface ResourceContract<Row extends DataRow = DataRow> {
|
|
88
|
-
/** Resource name the app addresses, e.g. "tickets" or "public.tickets". */
|
|
89
|
-
readonly name: string;
|
|
90
|
-
/**
|
|
91
|
-
* Identity field name, or names for a composite key, in key order.
|
|
92
|
-
*
|
|
93
|
-
* Typed `string` (not `keyof Row & string`) on purpose: `keyof Row` is a
|
|
94
|
-
* dependent type that TypeScript checks contravariantly, which would make
|
|
95
|
-
* `ResourceContract<WorkCycleRow>` non-assignable to the erased
|
|
96
|
-
* `ResourceContract<DataRow>` that generic consumers accept. The key is
|
|
97
|
-
* validated against the field schema at runtime instead.
|
|
98
|
-
*/
|
|
99
|
-
readonly key: string | readonly string[];
|
|
100
|
-
readonly fields: readonly FieldSchema[];
|
|
101
|
-
/** Optional doc string. */
|
|
102
|
-
readonly description?: string;
|
|
103
|
-
/** Human label, e.g. "Clients". */
|
|
104
|
-
readonly label?: string;
|
|
105
|
-
/** The field that best names a row to a person (a name or title), for links and pickers. */
|
|
106
|
-
readonly labelField?: string;
|
|
107
|
-
/** What one row is called in sentences ("brand"), and several ("brands") when not `noun` + "s". */
|
|
108
|
-
readonly noun?: string;
|
|
109
|
-
readonly nounPlural?: string;
|
|
110
|
-
/** Phantom marker so `Row` is inferable from a contract. */
|
|
111
|
-
readonly __row?: Row;
|
|
112
|
-
}
|
|
113
|
-
/** The row type a contract describes (its phantom `__row`), or `DataRow` when it carries none. */
|
|
114
|
-
type RowOf<C> = C extends {
|
|
115
|
-
readonly __row?: infer R;
|
|
116
|
-
} ? (unknown extends R ? DataRow : NonNullable<R>) : DataRow;
|
|
117
|
-
/**
|
|
118
|
-
* Declares a resource contract for a row type, keeping the literal contract (field names, key,
|
|
119
|
-
* labelField) and attaching the row type so views can read it with `RowOf`. `labelField` must be
|
|
120
|
-
* one of the row's fields.
|
|
121
|
-
*
|
|
122
|
-
* ```ts
|
|
123
|
-
* export const publicBrands = defineResource<PublicBrandsRow>()({ name: "public.brands", key: "id", fields: [...] });
|
|
124
|
-
* type Row = RowOf<typeof publicBrands>; // PublicBrandsRow
|
|
125
|
-
* ```
|
|
126
|
-
*/
|
|
127
|
-
declare function defineResource<Row extends DataRow>(): <const C extends ResourceContract<Row> & {
|
|
128
|
-
readonly labelField?: keyof Row & string;
|
|
129
|
-
}>(contract: C) => C & {
|
|
130
|
-
readonly __row?: Row;
|
|
131
|
-
};
|
|
132
|
-
/** What the current user may do with a whole resource. */
|
|
133
|
-
interface ResourceAccess {
|
|
134
|
-
readonly read: boolean;
|
|
135
|
-
/** True when at least one field can be updated on rows this user can see. */
|
|
136
|
-
readonly update: boolean;
|
|
137
|
-
/** Why `update` (or `read`) is false, in one human sentence. */
|
|
138
|
-
readonly reason?: string;
|
|
139
|
-
/** True when this user may add rows. Absent means the provider doesn't say. */
|
|
140
|
-
readonly create?: boolean;
|
|
141
|
-
/** True when this user may delete rows they can see. */
|
|
142
|
-
readonly delete?: boolean;
|
|
143
|
-
/** True when this user may read a row's audit history. */
|
|
144
|
-
readonly history?: boolean;
|
|
145
|
-
/** True when this user may read and add comments on rows they can see. */
|
|
146
|
-
readonly comment?: boolean;
|
|
147
|
-
/** Why `create`, `delete`, `history` or `comment` is false, in one human sentence each. */
|
|
148
|
-
readonly reasons?: {
|
|
149
|
-
readonly create?: string;
|
|
150
|
-
readonly delete?: string;
|
|
151
|
-
readonly history?: string;
|
|
152
|
-
readonly comment?: string;
|
|
153
|
-
};
|
|
154
|
-
}
|
|
155
|
-
/**
|
|
156
|
-
* How another resource relates to this one, from the store's foreign keys.
|
|
157
|
-
*
|
|
158
|
-
* - `one`: a field on THIS resource points at one row of `resource`.
|
|
159
|
-
* - `many`: rows of `resource` point at this row through their `field`.
|
|
160
|
-
* - `through`: many rows of `resource`, linked by the junction resource in
|
|
161
|
-
* `through` (a table whose key is two foreign keys).
|
|
162
|
-
*/
|
|
163
|
-
interface ResourceRelation {
|
|
164
|
-
readonly kind: "one" | "many" | "through";
|
|
165
|
-
/** The related resource. */
|
|
166
|
-
readonly resource: string;
|
|
167
|
-
/**
|
|
168
|
-
* `one`: the field on this resource. `many`: the field on `resource` that
|
|
169
|
-
* holds this row's key. `through`: the junction's field holding this row's key.
|
|
170
|
-
*/
|
|
171
|
-
readonly field: string;
|
|
172
|
-
/** For `through`: the junction resource, and its field pointing at `resource`. */
|
|
173
|
-
readonly through?: {
|
|
174
|
-
readonly resource: string;
|
|
175
|
-
readonly otherField: string;
|
|
176
|
-
};
|
|
177
|
-
/** True when at most one related row can exist (a unique foreign key). */
|
|
178
|
-
readonly unique?: boolean;
|
|
179
|
-
}
|
|
180
|
-
/**
|
|
181
|
-
* The column a provider checks on every update so an edit never silently
|
|
182
|
-
* overwrites someone else's. Only reported when the store itself advances it
|
|
183
|
-
* on every successful update (a trigger such as `moddatetime`), because a
|
|
184
|
-
* column nothing advances detects nothing.
|
|
185
|
-
*/
|
|
186
|
-
interface VersionField {
|
|
187
|
-
/**
|
|
188
|
-
* The field holding the version. A provider with versioned writes returns
|
|
189
|
-
* each row with its exact version token in this field, as a string, and
|
|
190
|
-
* `expectedVersion` echoes `String(row[field])` back unchanged.
|
|
191
|
-
*/
|
|
192
|
-
readonly field: string;
|
|
193
|
-
/**
|
|
194
|
-
* `row`: no column tracks versions, so the token is a fingerprint of the
|
|
195
|
-
* row's values, and `field` is a name the provider adds to each record
|
|
196
|
-
* (it is not one of the resource's fields).
|
|
197
|
-
*/
|
|
198
|
-
readonly kind: "integer" | "timestamp" | "row";
|
|
199
|
-
}
|
|
200
|
-
/**
|
|
201
|
-
* A resource as `describe()` reports it for the CURRENT user: the contract,
|
|
202
|
-
* plus what this user may do. Fields the user may not read are left out
|
|
203
|
-
* entirely, not marked hidden.
|
|
204
|
-
*/
|
|
205
|
-
interface ResourceSchema<Row extends DataRow = DataRow> extends ResourceContract<Row> {
|
|
206
|
-
/** Human label, e.g. "Clients". */
|
|
207
|
-
readonly label?: string;
|
|
208
|
-
readonly access: ResourceAccess;
|
|
209
|
-
/** Present only when writes can be version-checked. */
|
|
210
|
-
readonly version?: VersionField;
|
|
211
|
-
/** The field that best names a row to a person (a name or title), for links and pickers. */
|
|
212
|
-
readonly labelField?: string;
|
|
213
|
-
/** Resources this one links to or is linked from. Only ones this user may see. */
|
|
214
|
-
readonly relations?: readonly ResourceRelation[];
|
|
215
|
-
/** Fields the user may set when creating a row. Absent when creating isn't allowed. */
|
|
216
|
-
readonly createFields?: readonly string[];
|
|
217
|
-
/** Row actions this user may run: each calls the app's own function on one row. */
|
|
218
|
-
readonly actions?: readonly RowAction[];
|
|
219
|
-
}
|
|
220
|
-
/** A named operation on one row, carried out by the app's own database function. */
|
|
221
|
-
interface RowAction {
|
|
222
|
-
readonly name: string;
|
|
223
|
-
readonly label: string;
|
|
224
|
-
/** Ask before running, with this question. */
|
|
225
|
-
readonly confirm?: string;
|
|
226
|
-
/** One sentence on what it does. */
|
|
227
|
-
readonly description?: string;
|
|
228
|
-
}
|
|
229
|
-
/** A comment on a record. */
|
|
230
|
-
interface RecordComment {
|
|
231
|
-
readonly id: string;
|
|
232
|
-
/** The signed-in user who wrote it (the token's `sub`). */
|
|
233
|
-
readonly author: string;
|
|
234
|
-
readonly body: string;
|
|
235
|
-
/** ISO 8601, as the store recorded it. */
|
|
236
|
-
readonly createdAt: string;
|
|
237
|
-
}
|
|
238
|
-
/** One entry of `listResources()`: enough to draw a sidebar. */
|
|
239
|
-
interface ResourceSummary {
|
|
240
|
-
readonly name: string;
|
|
241
|
-
readonly label?: string;
|
|
242
|
-
readonly description?: string;
|
|
243
|
-
readonly access: ResourceAccess;
|
|
244
|
-
}
|
|
245
|
-
/** Filter operators a provider may support. Mirrors `FilterParam["operator"]`. */
|
|
246
|
-
type FilterOperator = "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains" | "in" | "between" | "is_null" | "is_not_null";
|
|
247
|
-
/**
|
|
248
|
-
* What a provider can do. A UI hides any control the provider cannot serve,
|
|
249
|
-
* instead of letting it error (DATA-STUDIO.md decision 9).
|
|
250
|
-
*/
|
|
251
|
-
interface ProviderCapabilities {
|
|
252
|
-
/** Server-side text search across fields. */
|
|
253
|
-
readonly search: boolean;
|
|
254
|
-
/** Server-side sort. */
|
|
255
|
-
readonly sort: boolean;
|
|
256
|
-
/** Server-side filter operators. Empty means no server filtering. */
|
|
257
|
-
readonly filterOperators: readonly FilterOperator[];
|
|
258
|
-
/** `updateMany` / `deleteMany` in one transaction. */
|
|
259
|
-
readonly bulkWrites: boolean;
|
|
260
|
-
/** Updates honour `expectedVersion` and reject stale writes. */
|
|
261
|
-
readonly versionedWrites: boolean;
|
|
262
|
-
/** Records may be keyed by more than one field. */
|
|
263
|
-
readonly compositeKeys: boolean;
|
|
264
|
-
/** Server-side sort by several fields at once (`ListParams.sorts`). */
|
|
265
|
-
readonly multiSort?: boolean;
|
|
266
|
-
/** `create` and `deleteOne` are served, subject to each resource's access. */
|
|
267
|
-
readonly create?: boolean;
|
|
268
|
-
readonly delete?: boolean;
|
|
269
|
-
/** `history` is served, subject to each resource's access. */
|
|
270
|
-
readonly history?: boolean;
|
|
271
|
-
/** `importRows` is served, with a dry run. */
|
|
272
|
-
readonly import?: boolean;
|
|
273
|
-
/** `undo` is served. */
|
|
274
|
-
readonly undo?: boolean;
|
|
275
|
-
/** `runAction` is served. */
|
|
276
|
-
readonly actions?: boolean;
|
|
277
|
-
/** `comments` and `addComment` are served. */
|
|
278
|
-
readonly comments?: boolean;
|
|
279
|
-
/**
|
|
280
|
-
* The most rows one `getList` page may ask for. A request for more is
|
|
281
|
-
* refused (it is not cut short, which would shift later page boundaries),
|
|
282
|
-
* so a client that wants every row must page at this size or less.
|
|
283
|
-
*/
|
|
284
|
-
readonly maxPerPage?: number;
|
|
285
|
-
/**
|
|
286
|
-
* A delete moves the record to a recycle bin (it can be restored) instead
|
|
287
|
-
* of removing it. Asked per resource: `capabilities(resource)`.
|
|
288
|
-
*/
|
|
289
|
-
readonly softDelete?: boolean;
|
|
290
|
-
/**
|
|
291
|
-
* `create`, `update` and `deleteOne` honour `keepalive: true` in their
|
|
292
|
-
* params (e.g. `fetch(url, { keepalive: true })`), so a write sent while
|
|
293
|
-
* the page unloads still reaches the server. Without it, closing the tab
|
|
294
|
-
* while an optimistic or undoable write is being sent shows the browser's
|
|
295
|
-
* "Leave site?" prompt.
|
|
296
|
-
*/
|
|
297
|
-
readonly keepaliveWrites?: boolean;
|
|
298
|
-
/**
|
|
299
|
-
* `getList` serves cursor (keyset) paging: `pagination.cursor` in,
|
|
300
|
-
* `nextCursor` out. Pages stay correct while rows are added or removed,
|
|
301
|
-
* and a deep page costs no more than the first.
|
|
302
|
-
*/
|
|
303
|
-
readonly cursorPagination?: boolean;
|
|
304
|
-
/**
|
|
305
|
-
* `subscribe` reports changes to this resource (asked per resource:
|
|
306
|
-
* `capabilities(resource)`), so `live` lists and records refresh when
|
|
307
|
-
* someone else changes them.
|
|
308
|
-
*/
|
|
309
|
-
readonly realtime?: boolean;
|
|
310
|
-
}
|
|
311
|
-
/** One audit record, as committed alongside the edit it describes. */
|
|
312
|
-
interface AuditEntry {
|
|
313
|
-
readonly id: string;
|
|
314
|
-
/** ISO 8601 timestamp, as the store recorded it. */
|
|
315
|
-
readonly occurredAt: string;
|
|
316
|
-
/** The signed-in user who made the edit (the token's `sub`). */
|
|
317
|
-
readonly actor: string | null;
|
|
318
|
-
readonly resource: string;
|
|
319
|
-
/** The record's key, field name → value. */
|
|
320
|
-
readonly key: DataRow;
|
|
321
|
-
/** `run` is a row action; `rowAction` names it. */
|
|
322
|
-
readonly action: "create" | "update" | "delete" | "run";
|
|
323
|
-
/** For `run`: which row action. */
|
|
324
|
-
readonly rowAction?: string;
|
|
325
|
-
/** Values of the changed fields before the edit. */
|
|
326
|
-
readonly before: DataRow | null;
|
|
327
|
-
/** Values of the changed fields after the edit. */
|
|
328
|
-
readonly after: DataRow | null;
|
|
329
|
-
}
|
|
330
|
-
|
|
331
|
-
export { type AuditEntry as A, type DataRow as D, type FieldSchema as F, type ProviderCapabilities as P, type RecordComment as R, type StorageType as S, type VersionField as V, type FieldPermissions as a, type FieldReference as b, type FilterOperator as c, type ResourceAccess as d, type ResourceContract as e, type ResourceRelation as f, type ResourceSchema as g, type ResourceSummary as h, type RowAction as i, type RowOf as j, defineResource as k };
|