@kronor/dtv 8.1.3 → 9.1.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/cli/typegen/runTypegen.js +4 -4
- package/dist/index.es.js +11621 -11548
- package/dist/types/dsl/columnTyping.d.ts +116 -0
- package/dist/types/dsl/columns.d.ts +58 -13
- package/dist/types/dsl/filterExpr.d.ts +1 -1
- package/dist/types/dsl/filterTyping.d.ts +33 -47
- package/dist/types/dsl/filters.d.ts +4 -4
- package/dist/types/dsl/index.d.ts +2 -0
- package/dist/types/dsl/typeErrors.d.ts +61 -0
- package/dist/types/framework/cached-value.d.ts +11 -0
- package/dist/types/framework/result.d.ts +6 -0
- package/dist/types/framework/serial-queue.d.ts +11 -0
- package/dist/types/framework/useUserDataManager.d.ts +8 -7
- package/dist/types/framework/user-data-errors.d.ts +8 -0
- package/dist/types/framework/user-data-manager.d.ts +7 -1
- package/dist/types/framework/user-data-storage.d.ts +17 -0
- package/dist/types/framework/user-data.d.ts +5 -0
- package/docs/api/row-typed-views.md +91 -25
- package/docs/typegen.md +5 -5
- package/package.json +1 -1
|
@@ -6,10 +6,9 @@ checked against that row: field paths have to exist, controls have to be able to
|
|
|
6
6
|
produce the type of the field they filter, and operators have to be ones Hasura
|
|
7
7
|
offers for that type.
|
|
8
8
|
|
|
9
|
-
`
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
runtime by the view parser, not by these types).
|
|
9
|
+
`column()`, `virtualColumn()`, `fieldColumn()` and `filter()` all require
|
|
10
|
+
`rowType`: a column or filter has to say which row it is built on. JSON views are unaffected (they are
|
|
11
|
+
validated at runtime by the view parser, not by these types).
|
|
13
12
|
|
|
14
13
|
## Getting the row type
|
|
15
14
|
|
|
@@ -22,8 +21,9 @@ export type PaymentRequestsRow = PaymentRequest;
|
|
|
22
21
|
export const PaymentRequestsRowType = DTV.rowType<PaymentRequestsRow>();
|
|
23
22
|
```
|
|
24
23
|
|
|
25
|
-
It also adds `rowType:` to the `DSL.column(...)
|
|
26
|
-
written inline in the view,
|
|
24
|
+
It also adds `rowType:` to the `DSL.column(...)`, `DSL.virtualColumn(...)`,
|
|
25
|
+
`DSL.fieldColumn(...)` and `DSL.filter(...)` calls written inline in the view,
|
|
26
|
+
so in practice the wiring is done for you. See
|
|
27
27
|
[../typegen.md](../typegen.md). To write it by hand, `rowType<Row>()` produces
|
|
28
28
|
the phantom value from any row type you already have.
|
|
29
29
|
|
|
@@ -42,7 +42,66 @@ DSL.column({
|
|
|
42
42
|
|
|
43
43
|
`data` selections are checked against the row (including nested object and
|
|
44
44
|
array selections), and the `cellRenderer`'s `data` argument is derived from
|
|
45
|
-
them with the row's own nullability preserved.
|
|
45
|
+
them with the row's own nullability preserved. `virtualColumn()` takes the same
|
|
46
|
+
`rowType`, and its `data` is checked the same way.
|
|
47
|
+
|
|
48
|
+
### Reusable column helpers
|
|
49
|
+
|
|
50
|
+
A column shared between views often takes its field from the caller —
|
|
51
|
+
`accountColumn(rowType, 'arAccount')`. Its renderer was written for one kind of
|
|
52
|
+
value, so the caller's field has to hold that kind of value. `fieldColumn`
|
|
53
|
+
builds such a column and checks the field against the caller's row:
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
type Account = { accountNr: string; accountName: string | null };
|
|
57
|
+
|
|
58
|
+
function accountColumn<Row, const Field extends string>(
|
|
59
|
+
rowType: Row,
|
|
60
|
+
field: Field & DSL.ValidateColumnFieldType<Row, Field, Account | null>,
|
|
61
|
+
name: string,
|
|
62
|
+
) {
|
|
63
|
+
return DSL.fieldColumn({
|
|
64
|
+
rowType,
|
|
65
|
+
field,
|
|
66
|
+
name,
|
|
67
|
+
select: { object: [valueQuery({ field: 'accountNr' }), valueQuery({ field: 'accountName' })] },
|
|
68
|
+
cellRenderer: ({ value }) => value === null ? null : `${value.accountNr} ${value.accountName ?? ''}`,
|
|
69
|
+
});
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
accountColumn(InvoicesRowType, 'arAccount', 'AR account');
|
|
73
|
+
accountColumn(InvoicesRowType, 'memo', 'Memo');
|
|
74
|
+
// field 'memo' holds string, and this column renders an object
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
- **The value.** The renderer gets the field's value as `value`, typed as the
|
|
78
|
+
value it declares, which is what the field is checked against. A renderer
|
|
79
|
+
that declares nothing, like the one above, gets the field's own type — or,
|
|
80
|
+
inside a helper, the type the helper's field was checked against
|
|
81
|
+
(`Account | null`). A field that is
|
|
82
|
+
missing from the row data arrives as `null`, so an optional field
|
|
83
|
+
(`note?: string`) is typed `string | null`.
|
|
84
|
+
- **Nullability counts**, unlike for filter helpers: a cell has to render the
|
|
85
|
+
null too. A field that can be null — itself, or because an object on its
|
|
86
|
+
dotted path can be — is only accepted by a renderer whose value admits null
|
|
87
|
+
(`field 'customer.account' can be null, and this column does not render
|
|
88
|
+
null`).
|
|
89
|
+
- **The selection follows from the value type**: nothing for a scalar,
|
|
90
|
+
`select: { object: [...] }` for an object, `select: { list: [...], limit, ... }`
|
|
91
|
+
for a list, each checked against it. A dotted path that steps into a list is
|
|
92
|
+
rejected: select the list instead.
|
|
93
|
+
- **Ordering.** `orderBy` names the field itself for a scalar
|
|
94
|
+
(`orderBy: 'memo'`), or a scalar inside it for an object
|
|
95
|
+
(`orderBy: 'arAccount.accountNr'`); a list cannot be ordered by. The path has
|
|
96
|
+
to be one the selection includes, which is checked when the column is built.
|
|
97
|
+
- **Forwarding.** The field has to be a literal path, or a field branded as
|
|
98
|
+
above. A plain `string`, or a helper's own `Field` that nothing has checked, is
|
|
99
|
+
rejected, since nothing could check it. A helper that takes the field from its
|
|
100
|
+
own caller brands its parameter with `ValidateColumnFieldType` and hands it
|
|
101
|
+
on. While the row is unknown the brand stands in for the check: a field
|
|
102
|
+
checked to hold `Account` is accepted by a helper that renders
|
|
103
|
+
`Account | null`, but a field checked to hold `Account | null` is rejected by
|
|
104
|
+
one that renders `Account` or a `string`.
|
|
46
105
|
|
|
47
106
|
## Filters
|
|
48
107
|
|
|
@@ -73,7 +132,7 @@ Failures read as the message itself, for example:
|
|
|
73
132
|
|
|
74
133
|
```
|
|
75
134
|
Property '"control 'text' cannot produce a value for 'amount' (type number)"'
|
|
76
|
-
is missing in type … but required in type
|
|
135
|
+
is missing in type … but required in type DslTypeError<…>
|
|
77
136
|
```
|
|
78
137
|
|
|
79
138
|
Details worth knowing:
|
|
@@ -259,13 +318,19 @@ H.scope('lines', Line => Line.condition('item.sku', Line.ilike('%SKU%')));
|
|
|
259
318
|
|
|
260
319
|
The checks need a row type that is already known. In a generic helper that
|
|
261
320
|
builds filters for a row it hasn't been given yet, they cannot be evaluated and
|
|
262
|
-
are skipped rather than reported as failures
|
|
263
|
-
|
|
321
|
+
are skipped rather than reported as failures. The helper says what its field
|
|
322
|
+
has to hold instead, the same way a column helper does:
|
|
323
|
+
`ValidateFilterFieldType<Row, Field, Value>` brands the field parameter, and is
|
|
324
|
+
`unknown` when the field is on the row and holds that type. `Value` is what the
|
|
325
|
+
helper's control produces:
|
|
264
326
|
|
|
265
327
|
```ts
|
|
266
|
-
function textFilter<Row, const Field extends DSL.
|
|
267
|
-
|
|
268
|
-
|
|
328
|
+
function textFilter<Row, const Field extends DSL.FilterField>(args: {
|
|
329
|
+
rowType: Row;
|
|
330
|
+
id: string;
|
|
331
|
+
label: string;
|
|
332
|
+
field: Field & DSL.ValidateFilterFieldType<Row, Field, string>;
|
|
333
|
+
}) {
|
|
269
334
|
return DSL.filter({
|
|
270
335
|
rowType: args.rowType,
|
|
271
336
|
id: args.id,
|
|
@@ -273,14 +338,8 @@ function textFilter<Row, const Field extends DSL.FilterFieldPath<Row>>(
|
|
|
273
338
|
expression: FilterExpr.equals({ field: args.field, control: FilterControl.text() })
|
|
274
339
|
});
|
|
275
340
|
}
|
|
276
|
-
```
|
|
277
341
|
|
|
278
|
-
|
|
279
|
-
and can say so — `ValidateFilterFieldType<Row, Field, Value>` brands the field
|
|
280
|
-
parameter, and is `unknown` when the field holds that type:
|
|
281
|
-
|
|
282
|
-
```ts
|
|
283
|
-
function numberRangeFilter<Row, const Field extends DSL.FilterFieldPath<Row>>(args: {
|
|
342
|
+
function numberRangeFilter<Row, const Field extends DSL.FilterField>(args: {
|
|
284
343
|
rowType: Row;
|
|
285
344
|
id: string;
|
|
286
345
|
label: string;
|
|
@@ -292,11 +351,18 @@ numberRangeFilter({ rowType: PaymentRequestsRowType, id: 'when', label: 'When',
|
|
|
292
351
|
// field 'createdAt' holds string, and this filter needs number
|
|
293
352
|
```
|
|
294
353
|
|
|
295
|
-
That restores at the call site what the helper's own body cannot check.
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
354
|
+
That restores at the call site what the helper's own body cannot check. Every
|
|
355
|
+
field of an `and`/`or` group is checked. `unknown` as `Value` accepts any field
|
|
356
|
+
on the row. A plain `string` field is rejected, and so is a helper's own
|
|
357
|
+
`Field` that nothing has checked. A helper can hand its branded field on to
|
|
358
|
+
another helper, and is accepted where the same or a wider `Value` is asked for,
|
|
359
|
+
as with columns.
|
|
360
|
+
|
|
361
|
+
It resolves the type of the one field it is given rather than constraining it
|
|
362
|
+
to `FilterFieldPath<Row>` or selecting the row's fields by type: enumerating
|
|
363
|
+
every path and resolving each one costs work proportional to the size of the
|
|
364
|
+
row, and exceeded TypeScript's instantiation limit on real generated rows of
|
|
365
|
+
around 900 lines.
|
|
300
366
|
|
|
301
367
|
Two things to know about what it accepts: nullability is ignored, so a
|
|
302
368
|
`number | null` column counts as numeric; and Hasura's `date`, `timestamp` and
|
package/docs/typegen.md
CHANGED
|
@@ -86,13 +86,13 @@ That file contains:
|
|
|
86
86
|
the DSL helpers take as `rowType`
|
|
87
87
|
|
|
88
88
|
The generator also edits the view module itself, as a convenience: it imports
|
|
89
|
-
`<ViewIdPascal>RowType` and adds `rowType:` to the `DSL.column(...)
|
|
90
|
-
`DSL.
|
|
91
|
-
do not have one yet. Calls that already pass `rowType` are left alone, so
|
|
89
|
+
`<ViewIdPascal>RowType` and adds `rowType:` to the `DSL.column(...)`,
|
|
90
|
+
`DSL.virtualColumn(...)`, `DSL.fieldColumn(...)` and `DSL.filter(...)` calls
|
|
91
|
+
written inline in the `DSL.view({ ... })` argument that do not have one yet. Calls that already pass `rowType` are left alone, so
|
|
92
92
|
re-running the generator is safe.
|
|
93
93
|
|
|
94
|
-
Passing `rowType` is what turns on checking of a view's columns
|
|
95
|
-
row, and
|
|
94
|
+
Passing `rowType` is what turns on checking of a view's columns and filters
|
|
95
|
+
against its row, and all of these helpers require it — see
|
|
96
96
|
[api/row-typed-views.md](api/row-typed-views.md). A view where no call ends up
|
|
97
97
|
with a `rowType` gets no generated file.
|
|
98
98
|
|