@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.
- package/README.md +2 -0
- package/dist/cli/typegen/runTypegen.js +169 -74
- package/dist/index.es.js +3750 -3765
- package/dist/types/dsl/filterControl.d.ts +125 -33
- package/dist/types/dsl/filterExpr.d.ts +88 -139
- package/dist/types/dsl/filterExprForRow.d.ts +111 -0
- package/dist/types/dsl/filterTransform.d.ts +1 -1
- package/dist/types/dsl/filterTyping.d.ts +228 -0
- package/dist/types/dsl/filters.d.ts +41 -19
- package/dist/types/dsl/index.d.ts +2 -0
- package/dist/types/framework/data.d.ts +1 -1
- package/dist/types/framework/filters.d.ts +87 -18
- package/dist/types/framework/graphql/query.d.ts +3 -3
- package/dist/types/framework/view-parser.d.ts +11 -0
- package/dist/types/lib/index.d.ts +2 -1
- package/docs/api/README.md +1 -0
- package/docs/api/row-typed-views.md +315 -0
- package/docs/typegen.md +35 -1
- package/package.json +1 -1
|
@@ -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
|
-
-
|
|
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
|
|