@kronor/dtv 7.7.2 → 8.0.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.
@@ -0,0 +1,315 @@
1
+ # Row-Typed Views (TS DSL)
2
+
3
+ A TypeScript view can tell DTV which GraphQL row it is built on. Everything the
4
+ view then declares — columns, filters, Hasura conditions, nested selections — is
5
+ checked against that row: field paths have to exist, controls have to be able to
6
+ produce the type of the field they filter, and operators have to be ones Hasura
7
+ offers for that type.
8
+
9
+ This is opt-in. A view that passes no row type keeps working exactly as before,
10
+ and JSON views are unaffected (they are validated at runtime by the view
11
+ parser, not by these types).
12
+
13
+ ## Getting the row type
14
+
15
+ `dtv typegen` derives the row type from the schema and writes it next to each
16
+ view module, exporting both a type and a phantom value:
17
+
18
+ ```ts
19
+ // dtv.generated.payment-requests.ts (generated)
20
+ export type PaymentRequestsRow = PaymentRequest;
21
+ export const PaymentRequestsRowType = DTV.rowType<PaymentRequestsRow>();
22
+ ```
23
+
24
+ It also adds `rowType:` to the `DSL.column(...)` and `DSL.filter(...)` calls
25
+ written inline in the view, so in practice the wiring is done for you. See
26
+ [../typegen.md](../typegen.md). To write it by hand, `rowType<Row>()` produces
27
+ the phantom value from any row type you already have.
28
+
29
+ ## Columns
30
+
31
+ ```ts
32
+ DSL.column({
33
+ rowType: PaymentRequestsRowType,
34
+ id: 'amount',
35
+ name: 'Amount',
36
+ data: [valueQuery({ field: 'amount' })],
37
+ orderBy: 'amount',
38
+ cellRenderer: ({ data }) => data.amount // typed from the row, not `any`
39
+ });
40
+ ```
41
+
42
+ `data` selections are checked against the row (including nested object and
43
+ array selections), and the `cellRenderer`'s `data` argument is derived from
44
+ them with the row's own nullability preserved.
45
+
46
+ ## Filters
47
+
48
+ ```ts
49
+ DSL.filter({
50
+ rowType: PaymentRequestsRowType,
51
+ id: 'status',
52
+ label: 'Status',
53
+ expression: FilterExpr.equals({
54
+ field: 'status',
55
+ control: FilterControl.dropdown({
56
+ items: [{ label: 'Paid', value: 'paid' }, { label: 'Pending', value: 'pending' }]
57
+ })
58
+ })
59
+ });
60
+ ```
61
+
62
+ Three things are checked, for every leaf of the expression tree, and for every
63
+ field of an `and`/`or` field group:
64
+
65
+ | Check | Rejected example (given `amount: number`, `status: 'paid' \| 'pending'`) |
66
+ | --- | --- |
67
+ | The field path exists on the row | `field: 'amuont'`, `field: 'customer.nope'` |
68
+ | The control can produce the field's type | `field: 'amount', control: FilterControl.text()` |
69
+ | The operator exists for the field's type | `FilterExpr.iLike({ field: 'amount', … })` |
70
+
71
+ Failures read as the message itself, for example:
72
+
73
+ ```
74
+ Property '"control 'text' cannot produce a value for 'amount' (type number)"'
75
+ is missing in type … but required in type FilterTypeError<…>
76
+ ```
77
+
78
+ Details worth knowing:
79
+
80
+ - **Controls.** `text` needs a string field, `number` a numeric one. `date`
81
+ accepts string, number and `Date` fields, because Hasura's `date`,
82
+ `timestamp` and `timestamptz` scalars are generated as `string`.
83
+ - **Item lists.** `dropdown` and `multiselect` item values are each checked
84
+ against the field — this is what catches a typo in an enum value. A list
85
+ column is compared against its element type. Lists built at runtime are
86
+ widened and cannot be inspected, so they are not checked.
87
+ - **Starting values.** Every control takes an `initialValue`, typed as the value
88
+ that control produces: a string for `text`, one of the items for `dropdown`, a
89
+ list of them for `multiselect`, a `Date` for `date`. `customOperator` is the
90
+ exception — its `initialValue` seeds the *inner* value, alongside
91
+ `valueControl.initialValue`, rather than the `{ operator, value }` pair the
92
+ control stores.
93
+ - **Multiselect.** A multiselect produces a list of values, so on a scalar
94
+ field it is only allowed with `in`/`notIn`.
95
+ - **Operators.** The leaf operator is mapped to the Hasura operator DTV emits
96
+ for it and looked up in `HasuraOperatorFor<Value>` — the same source of truth
97
+ the Hasura DSL uses. `like`/`iLike` need a string field; `greaterThan` and
98
+ friends need a comparable one; `equals`, `in`, `notIn` and `isNull` are
99
+ always available.
100
+ - **customOperator.** Operators written inline are checked the same way, since
101
+ the built-in transform hands them to Hasura verbatim. An operator that is not
102
+ a Hasura operator name is left to the transform.
103
+
104
+ ### Escape hatches
105
+
106
+ These are cases where the declared shape no longer describes what reaches the
107
+ query, so the control and operator checks stand down:
108
+
109
+ - **A leaf with a `transform`.** A transform may re-map the value, the field, or
110
+ return a whole condition. Its field path is still checked, and a
111
+ `customOperator` operator list still is too.
112
+ - **`json`/`jsonb` columns**, which are generated as `any`, and rows with an
113
+ index signature: any control, any operator.
114
+ - **`custom` and `autocomplete` controls**, whose values are defined by a
115
+ component or a fetcher rather than by the control.
116
+
117
+ ### Transforms
118
+
119
+ A transform's `input` is typed from the control beside it, so it can be written
120
+ without a cast:
121
+
122
+ ```ts
123
+ FilterExpr.equals({
124
+ field: 'amount',
125
+ control: FilterControl.number(),
126
+ transform: { toQuery: input => TransformResult.value(input === null ? null : input * 100) }
127
+ // input: number | null
128
+ });
129
+ ```
130
+
131
+ What each control produces:
132
+
133
+ | Control | `input` |
134
+ | --- | --- |
135
+ | `text` | `string` |
136
+ | `number` | `number \| null` |
137
+ | `date` | `Date` |
138
+ | `dropdown` | the union of its item values |
139
+ | `multiselect` | an array of them |
140
+ | `autocomplete` | the item type its `suggestionFetcher` returns, or an array of them when `multiple: true` |
141
+ | `customOperator` | `{ operator, value }`, with `operator` narrowed to the operators it offers |
142
+ | `custom` | the value type of the component's `onChange`, else `unknown` |
143
+ | any of them, assembled at runtime | widened, as far as the list allows |
144
+
145
+ A transform that takes `unknown` still compiles, so existing ones need no
146
+ change; the type is what the control declares, not a guarantee. The same value
147
+ can also arrive as an `initialValue`, out of persisted filter state, from the
148
+ AI assistant, or from a consumer calling `setFilterState` — so a transform
149
+ facing those should still check what it gets.
150
+
151
+ On the row-scoped builder the transform is a **second argument**, which is what
152
+ lets each check be reported on the property that caused it while `input` stays
153
+ typed:
154
+
155
+ ```ts
156
+ F.iLike(
157
+ { field: 'amount', control: FilterControl.text() },
158
+ { toQuery: input => TransformResult.value(Number(input)) }
159
+ // input: string
160
+ );
161
+ ```
162
+
163
+ A transform is also told which filter it belongs to. `context.field` is the very
164
+ path the leaf declares, so the row-scoped Hasura DSL takes it directly and
165
+ resolves the field's type from it:
166
+
167
+ ```ts
168
+ F.greaterThan(
169
+ { field: 'amount', control: FilterControl.number() },
170
+ { toQuery: (input, context) => TransformResult.condition(H.condition(context.field, H.gt(Number(input)))) }
171
+ // ^ 'amount', so H rejects H.ilike here
172
+ );
173
+ ```
174
+
175
+ `context.result` holds the `TransformResult` builders — the same ones the module
176
+ exports, so a transform need not import them — with `fieldValue` restricted to
177
+ the row, since redirecting a filter to another field deserves the same check as
178
+ declaring it:
179
+
180
+ ```ts
181
+ F.equals(
182
+ { field: 'id', control: FilterControl.text() },
183
+ { toQuery: (input, context) => context.result.fieldValue('customer.email', input) }
184
+ );
185
+ ```
186
+
187
+ ### Filters whose transform owns the query
188
+
189
+ A filter can leave the query entirely to its transform — `computedCondition` has
190
+ no real field at all, and a transform is free to build a condition from a path
191
+ it closes over. The declared `field` is then meaningless to whoever reads the
192
+ applied-filter pill, which shows it.
193
+
194
+ `fieldLabel` is what the pill shows instead, so the field can stay a row path:
195
+
196
+ ```ts
197
+ FilterExpr.in({
198
+ field: 'subsidiaryId',
199
+ fieldLabel: 'Subsidiary',
200
+ control: FilterControl.multiselect({ items: subsidiaryItems }),
201
+ transform: subsidiaryCondition
202
+ });
203
+ ```
204
+
205
+ Without a `fieldLabel` the pill falls back to the field path, as before. A range
206
+ gives the same label to both of its bounds.
207
+
208
+ ### customOperator
209
+
210
+ A `customOperator` control stores the chosen operator beside the value, and only
211
+ a transform can turn that into a condition. `buildHasuraConditions` throws when
212
+ one is missing or returns a value instead, so both are compile errors under
213
+ `filter({ rowType })`:
214
+
215
+ ```ts
216
+ FilterExpr.equals({
217
+ field: 'amount',
218
+ control: FilterControl.customOperator({ operators, valueControl: FilterControl.number() }),
219
+ transform: { toQuery: (input, context) => context.transform.hasuraCustomOperator.toQuery(input, context) }
220
+ });
221
+ ```
222
+
223
+ Annotate a hand-written one `ConditionOnlyTransform` — a transform typed
224
+ `FilterTransform` may return either, which is not enough. A transform object
225
+ with no `toQuery` at all is rejected too; it would do nothing at query time.
226
+
227
+ ### Row-scoped builders
228
+
229
+ `FilterExpr` accepts any field name and is checked when the expression reaches
230
+ `filter({ rowType })`, which reports problems on the `filter()` call. Scoping
231
+ the builder to the row instead gives the editor a row to work from:
232
+
233
+ ```ts
234
+ const F = filterExprForRowType(PaymentRequestsRowType);
235
+
236
+ F.iLike({ field: 'customer.email', control: FilterControl.text() });
237
+ F.in({ field: 'status', control: FilterControl.multiselect({ items: [...] }) });
238
+ F.like({ field: F.field.or('reference', 'customer.email'), control: FilterControl.text() });
239
+ ```
240
+
241
+ Field names complete as they are typed, and each problem is reported on the
242
+ property that caused it — an unsupported operator on `field`, an unusable
243
+ control on `control`. The results are ordinary `FilterExpr` values, so
244
+ `filter({ rowType })` still checks them; the row-scoped builder is about where
245
+ errors appear, not about checking more.
246
+
247
+ `hasuraDSLforRowType` and `queryForRowType` are the same idea for
248
+ condition-producing transforms and for nested selections:
249
+
250
+ ```ts
251
+ const H = hasuraDSLforRowType(PaymentRequestsRowType);
252
+
253
+ H.condition('amount', H.gt(1000)); // path and operand both checked
254
+ H.scope('lines', Line => Line.condition('item.sku', Line.ilike('%SKU%')));
255
+ ```
256
+
257
+ ### Reusable filter helpers
258
+
259
+ The checks need a row type that is already known. In a generic helper that
260
+ builds filters for a row it hasn't been given yet, they cannot be evaluated and
261
+ are skipped rather than reported as failures — so constrain the helper's own
262
+ arguments and its callers stay checked:
263
+
264
+ ```ts
265
+ function textFilter<Row, const Field extends DSL.FilterFieldPath<Row>>(
266
+ args: { rowType: Row; id: string; label: string; field: Field }
267
+ ) {
268
+ return DSL.filter({
269
+ rowType: args.rowType,
270
+ id: args.id,
271
+ label: args.label,
272
+ expression: FilterExpr.equals({ field: args.field, control: FilterControl.text() })
273
+ });
274
+ }
275
+ ```
276
+
277
+ A helper that picks the control itself only makes sense on one kind of column,
278
+ and can say so — `ValidateFilterFieldType<Row, Field, Value>` brands the field
279
+ parameter, and is `unknown` when the field holds that type:
280
+
281
+ ```ts
282
+ function numberRangeFilter<Row, const Field extends DSL.FilterFieldPath<Row>>(args: {
283
+ rowType: Row;
284
+ id: string;
285
+ label: string;
286
+ field: Field & DSL.ValidateFilterFieldType<Row, Field, number>;
287
+ }) { /* ... */ }
288
+
289
+ numberRangeFilter({ rowType: PaymentRequestsRowType, id: 'amount', label: 'Amount', field: 'amount' });
290
+ numberRangeFilter({ rowType: PaymentRequestsRowType, id: 'when', label: 'When', field: 'createdAt' });
291
+ // field 'createdAt' holds string, and this filter needs number
292
+ ```
293
+
294
+ That restores at the call site what the helper's own body cannot check. It
295
+ resolves the type of the one field it is given rather than selecting the row's
296
+ fields by type: enumerating every path and resolving each one costs work
297
+ proportional to the size of the row, and exceeded TypeScript's instantiation
298
+ limit on real generated rows of around 900 lines.
299
+
300
+ Two things to know about what it accepts: nullability is ignored, so a
301
+ `number | null` column counts as numeric; and Hasura's `date`, `timestamp` and
302
+ `timestamptz` scalars are generated as `string`, so a date helper should ask for
303
+ `string | Date` rather than `Date`. Arrays are not unwrapped — ask for
304
+ `string[]` to match a list column.
305
+
306
+ ## What is not checked yet
307
+
308
+ - A view does not tie its columns and filters together: nothing stops a filter
309
+ built for one row type from being placed in a view over another.
310
+ - `boolExpType`, `orderByType`, `paginationKey` and `staticOrdering` on a view
311
+ are plain strings.
312
+ - A transform's *output* is only partly checked: `context.result.fieldValue`
313
+ restricts the field it redirects to, but not the value it produces, nor the
314
+ row a returned condition was built against.
315
+ - JSON views get none of this.
package/docs/typegen.md CHANGED
@@ -80,8 +80,42 @@ For each discovered `DSL.view({ id, collectionName, ... })` call, the generator
80
80
  That file contains:
81
81
 
82
82
  - TypeScript types for GraphQL output types reachable from the view’s `collectionName` row type (not exported)
83
- - One exported alias:
83
+ - Two exported members:
84
84
  - `<ViewIdPascal>Row` – the inferred row type for that view’s `collectionName`
85
+ - `<ViewIdPascal>RowType` – a phantom value of that type, produced by `DSL.rowType<…>()`, which
86
+ the DSL helpers take as `rowType`
87
+
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
92
+ re-running the generator is safe.
93
+
94
+ Passing `rowType` is what turns on checking of a view's columns and filters
95
+ against its row — see [api/row-typed-views.md](api/row-typed-views.md). A view
96
+ where no call ends up with a `rowType` gets no generated file.
97
+
98
+ ## What the run reports
99
+
100
+ A view that produces no types leaves whatever generated file is already
101
+ committed next to it, so the row type it describes silently goes stale while
102
+ the code that imports it keeps type-checking against the old shape. Every way
103
+ that can happen is reported:
104
+
105
+ - **A view the scanner could not read** — its `id`, or its `source.collectionName`
106
+ / `source.functionName`, is not a string literal — is named on stderr with
107
+ which part was unreadable. A dynamic id such as
108
+ `` id: subsidiaryId ? `${viewId}-${subsidiaryId}` : viewId `` is the usual
109
+ cause; the generator has no way to know what the id will be at run time.
110
+ - **A view whose types could not be written** fails the command, naming the view
111
+ and the error. The run finishes the other views first, so one broken view
112
+ reports the rest rather than hiding them.
113
+ - **A generated module that was removed**, because nothing in its view passes
114
+ `rowType:` any more, is named on stderr.
115
+
116
+ The closing line counts what was written against what was found — `Generated
117
+ types for 61 of 62 view(s).` — so a view that dropped out is visible without
118
+ reading the warnings.
85
119
 
86
120
  ## Current limitations (v1)
87
121
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kronor/dtv",
3
- "version": "7.7.2",
3
+ "version": "8.0.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",