@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.
@@ -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
- `filter()` requires `rowType`: a filter has to say which row it is built on.
10
- Columns are still opt-in — a `column()` that passes no row type keeps working
11
- exactly as before — and JSON views are unaffected (they are validated at
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(...)` and `DSL.filter(...)` calls
26
- written inline in the view, so in practice the wiring is done for you. See
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 FilterTypeError<…>
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 — so constrain the helper's own
263
- arguments and its callers stay checked:
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.FilterFieldPath<Row>>(
267
- args: { rowType: Row; id: string; label: string; field: Field }
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
- A helper that picks the control itself only makes sense on one kind of column,
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. It
296
- resolves the type of the one field it is given rather than selecting the row's
297
- fields by type: enumerating every path and resolving each one costs work
298
- proportional to the size of the row, and exceeded TypeScript's instantiation
299
- limit on real generated rows of around 900 lines.
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(...)` and
90
- `DSL.filter(...)` calls written inline in the `DSL.view({ ... })` argument that
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 against its
95
- row, and `DSL.filter(...)` requires it — see
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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kronor/dtv",
3
- "version": "8.1.3",
3
+ "version": "9.1.0",
4
4
  "description": "Schema-driven, declarative table views with advanced filtering, data fetching and AI-assisted filter generation.",
5
5
  "repository": {
6
6
  "type": "git",