@kronor/dtv 8.1.3 → 9.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,116 @@
1
+ /**
2
+ * Type-level validation of the field a reusable column is given.
3
+ *
4
+ * A column written for one view names its fields as literals, and `column({
5
+ * rowType })` checks them. A column shared between views often takes its
6
+ * field from the caller instead — `accountColumn(rowType, 'arAccount')`. Its
7
+ * renderer was written for one kind of value (an account, an amount, a flag),
8
+ * so the caller's field has to hold that kind of value. `fieldColumn` (see
9
+ * ./columns) builds such a column and checks the field with
10
+ * `ValidateColumnFieldType`; a helper that takes the field from its own caller
11
+ * brands its parameter the same way and hands it on:
12
+ *
13
+ * function accountColumn<Row, const Field extends string>(
14
+ * rowType: Row,
15
+ * field: Field & ValidateColumnFieldType<Row, Field, Account | null>,
16
+ * ) { return fieldColumn({ rowType, field, ... }); }
17
+ *
18
+ * While `Row` is a type parameter the field cannot be looked up, so a field
19
+ * handed on is accepted by its brand: one checked to hold `Value` goes where a
20
+ * `Value` (or something wider, such as `Value | null`) is rendered, and nowhere
21
+ * else (see `CheckedAs` in ./typeErrors). The brand also gives an inline
22
+ * renderer, which declares no value type of its own, its `value`: `Account |
23
+ * null` above.
24
+ *
25
+ * Filter helpers take their field the same way, with `ValidateFilterFieldType`.
26
+ * Unlike there, nullability counts. A filter on a nullable
27
+ * column filters the values it does have; a cell has to render the null too.
28
+ * A field that can be null — itself, or because an object on its path can be —
29
+ * is only accepted by a column whose `Value` admits null.
30
+ *
31
+ * The field has to be a literal path, or a field branded as above. A plain
32
+ * `string`, or a helper's own `Field` that nothing has checked, cannot be
33
+ * checked anywhere, so it is rejected rather than let through. A path that goes
34
+ * through a list is rejected too, since the cell would get an array of values.
35
+ *
36
+ * The field is resolved as one path, not constrained by `FieldPath<Row>`:
37
+ * enumerating every path of a generated row is costly, and when the constraint
38
+ * fails tsc reports the whole union of paths instead of the one that is wrong.
39
+ *
40
+ * Failures surface as a `DslTypeError`, whose single property *name* is the
41
+ * message, so tsc prints it verbatim at the call.
42
+ *
43
+ * Escape hatches, as for filters: a field typed `any` or `unknown` (json/jsonb
44
+ * columns) and rows with an index signature accept anything.
45
+ */
46
+ import type { ArrayQuery, Query, QueryForRowSafe } from '@kronor/hasura-graphql';
47
+ import type { Brand, CheckedAs, DescribeType, IsAny, NestingDepth, Opaque } from './typeErrors';
48
+ declare const throughList: unique symbol;
49
+ /** The value of a path that steps into a list: not a single value a cell can render. */
50
+ type ThroughList<List extends string> = {
51
+ [throughList]: List;
52
+ };
53
+ /** null when the key can be missing: the cell reads a missing field as null. */
54
+ type MissingAsNull<Row, Key extends keyof Row> = undefined extends Row[Key] ? null : Partial<Pick<Row, Key>> extends Pick<Row, Key> ? null : never;
55
+ /**
56
+ * The value a cell gets at a dotted path: the field's own type, plus null when
57
+ * it or an object on the way can be null or missing (`undefined` never reaches
58
+ * the cell, see `readPath` in ./columns). `never` when the path is not on the
59
+ * row; `ThroughList` when it steps into a list; `unknown` on a row with an
60
+ * index signature.
61
+ */
62
+ export type ColumnFieldValue<Row, Path extends string, Prefix extends string = ''> = string extends keyof Row ? unknown : Path extends `${infer Head}.${infer Tail}` ? Head extends keyof Row ? NonNullable<Row[Head]> extends readonly unknown[] ? ThroughList<`${Prefix}${Head}`> : ColumnFieldValue<NonNullable<Row[Head]>, Tail, `${Prefix}${Head}.`> extends infer Inner ? [Inner] extends [never] ? never : Inner extends ThroughList<string> ? Inner : Inner | (null extends Row[Head] ? null : never) | MissingAsNull<Row, Head> : never : never : Path extends keyof Row ? Exclude<Row[Path], undefined> | MissingAsNull<Row, Path> : never;
63
+ type Nullish = null | undefined;
64
+ type FieldErrors<Row, Field extends string, Value> = string extends Field ? `the field must be a literal path; a helper takes it as 'Field & ValidateColumnFieldType<Row, Field, Value>'` : string extends keyof Row ? never : ColumnFieldValue<Row, Field> extends infer Held ? Opaque<Held> extends true ? never : [Held] extends [never] ? `field '${Field}' is not on the row` : [Held] extends [ThroughList<infer List>] ? `field '${Field}' goes through the list '${List}'; select the list instead` : [Held] extends [Value] ? never : [Exclude<Held, Nullish>] extends [Value] ? `field '${Field}' can be null, and this column does not render null` : `field '${Field}' holds ${DescribeType<Exclude<Held, Nullish>>}, and this column renders ${DescribeType<Exclude<Value, Nullish>>}` : never;
65
+ /**
66
+ * `unknown` when the field at `Field` holds a `Value` (nullability included),
67
+ * otherwise a `DslTypeError` saying what it holds instead. While `Row` is a
68
+ * type parameter, a brand checked against a narrower `Value` (see above).
69
+ */
70
+ export type ValidateColumnFieldType<Row, Field extends string, Value> = [
71
+ Row,
72
+ Field
73
+ ] extends [infer R, infer F extends string] ? Brand<FieldErrors<R, F, Value>> : CheckedAs<Value>;
74
+ type ListElement<Value> = NonNullable<Value> extends readonly (infer Element)[] ? NonNullable<Element> : never;
75
+ /** The arguments a list selection takes besides its selection set. */
76
+ type ListArguments = Pick<ArrayQuery, 'orderBy' | 'distinctOn' | 'limit' | 'where'>;
77
+ /** What `fieldColumn` can select inside its field, unchecked: see `FieldColumnSelect`. */
78
+ export type FieldSelection = {
79
+ object: readonly Query[];
80
+ } | ({
81
+ list: readonly Query[];
82
+ } & ListArguments);
83
+ /**
84
+ * What `fieldColumn` selects inside its field, decided by the value its
85
+ * renderer takes: nothing for a scalar, the object's fields for an object, and
86
+ * the element's fields (plus the list arguments) for a list. The selection is
87
+ * checked against `Value`, which is itself checked against the row.
88
+ */
89
+ export type FieldColumnSelect<Value> = IsAny<Value> extends true ? {
90
+ select?: undefined;
91
+ } : [NonNullable<Value>] extends [readonly unknown[]] ? {
92
+ select: {
93
+ list: readonly QueryForRowSafe<ListElement<Value>>[];
94
+ } & ListArguments;
95
+ } : [NonNullable<Value>] extends [object] ? {
96
+ select: {
97
+ object: readonly QueryForRowSafe<NonNullable<Value>>[];
98
+ };
99
+ } : {
100
+ select?: undefined;
101
+ };
102
+ /**
103
+ * The scalar paths inside an object, through nested objects but not lists:
104
+ * what a selection of it can be ordered by.
105
+ */
106
+ type ScalarPaths<Value, Depth extends keyof NestingDepth = 4> = Opaque<Value> extends true ? string : {
107
+ [K in Extract<keyof Value, string>]: Opaque<Value[K]> extends true ? K : [NonNullable<Value[K]>] extends [readonly unknown[]] ? never : [NonNullable<Value[K]>] extends [Date] ? K : [NonNullable<Value[K]>] extends [object] ? Depth extends 0 ? never : `${K}.${ScalarPaths<NonNullable<Value[K]>, NestingDepth[Depth]>}` : K;
108
+ }[Extract<keyof Value, string>];
109
+ /**
110
+ * What a `fieldColumn` can be ordered by: the field itself when it holds a
111
+ * scalar, a scalar inside it when it holds an object (`'arAccount.accountNr'`),
112
+ * nothing when it holds a list. The path still has to be one the column
113
+ * selects, which is checked when the column is built.
114
+ */
115
+ export type FieldColumnOrderBy<Field extends string, Value> = Opaque<Value> extends true ? string : [NonNullable<Value>] extends [readonly unknown[]] ? never : [NonNullable<Value>] extends [Date] ? Field : [NonNullable<Value>] extends [object] ? `${Field}.${ScalarPaths<NonNullable<Value>>}` : Field;
116
+ export {};
@@ -5,14 +5,22 @@
5
5
  * and provide a concise, ergonomic way to build column definitions while
6
6
  * retaining full type safety.
7
7
  *
8
+ * Every column is declared against the view's row type (`rowType`): the
9
+ * fields it selects have to exist on the row, and its renderer sees them with
10
+ * the row's own types, nullability included. A column shared between views
11
+ * that takes its field from the caller is built with `fieldColumn`, which
12
+ * checks that field against the caller's row.
13
+ *
8
14
  * The query builders themselves (`valueQuery` / `objectQuery` / `arrayQuery`)
9
15
  * and `rowType` come from @kronor/hasura-graphql and are re-exported here so
10
16
  * view authors have a single import site.
11
17
  */
12
- import { type FieldQuery, type DataFromFieldQueriesSafe, type DataFromFieldQueriesForRowSafe, type FieldQueryForRowSafe, type TableColumnDefinition, type VirtualColumnDefinition, type CellRenderer, type OrderableFieldPath, type TableColumnDefinitionFooter } from "../framework/column-definition";
18
+ import type { ReactNode } from "react";
19
+ import { type FieldQuery, type DataFromFieldQueriesForRowSafe, type FieldQueryForRowSafe, type TableColumnDefinition, type VirtualColumnDefinition, type CellRenderer, type CellRendererProps, type OrderableFieldPath, type TableColumnDefinitionFooter } from "../framework/column-definition";
20
+ import type { ColumnFieldValue, FieldColumnOrderBy, FieldColumnSelect, ValidateColumnFieldType } from "./columnTyping";
13
21
  export { valueQuery, objectQuery, arrayQuery, rowType } from "@kronor/hasura-graphql";
14
22
  /**
15
- * Creates a renderable table column definition.
23
+ * Creates a renderable table column definition for a view over `Row`.
16
24
  * Convenience wrapper around the underlying TableColumnDefinition type.
17
25
  */
18
26
  export declare function column<Row, const FieldQueries extends readonly FieldQuery[]>(args: {
@@ -24,21 +32,58 @@ export declare function column<Row, const FieldQueries extends readonly FieldQue
24
32
  orderBy?: OrderableFieldPath<FieldQueries>;
25
33
  cellRenderer: CellRenderer<DataFromFieldQueriesForRowSafe<Row, FieldQueries>>;
26
34
  }): TableColumnDefinition<FieldQueries, DataFromFieldQueriesForRowSafe<Row, FieldQueries>>;
27
- export declare function column<const FieldQueries extends readonly FieldQuery[]>(args: {
28
- rowType?: never;
29
- id: string;
35
+ /** The props a `fieldColumn` renderer gets: the usual ones, plus the field's value. */
36
+ export type FieldCellRendererProps<Value> = CellRendererProps & {
37
+ value: Value;
38
+ };
39
+ type FieldCellRenderer<Value> = (props: FieldCellRendererProps<Value>) => ReactNode;
40
+ /**
41
+ * A column showing one field of the row, given as a (dotted) path — for a
42
+ * column shared between views that takes its field from the caller:
43
+ *
44
+ * function accountColumn<Row, const Field extends string>(
45
+ * rowType: Row,
46
+ * field: Field & ValidateColumnFieldType<Row, Field, Account | null>,
47
+ * name: string,
48
+ * ) {
49
+ * return fieldColumn({
50
+ * rowType,
51
+ * field,
52
+ * name,
53
+ * select: { object: [valueQuery({ field: 'accountNr' })] },
54
+ * cellRenderer: ({ value }) => value?.accountNr ?? null,
55
+ * });
56
+ * }
57
+ *
58
+ * The renderer gets the field's value as `value` (null when the field is
59
+ * missing, or an object on the path is null or missing). Its type is the one
60
+ * the renderer declares, which is what the field is checked against, so a
61
+ * renderer that does not handle null only accepts fields that cannot be null.
62
+ * A renderer that declares nothing gets the field's own type — inside a helper
63
+ * like the one above, the type its field was checked against (`Account | null`). What is
64
+ * selected inside the field follows from that type: nothing for a scalar,
65
+ * `select: { object: [...] }` for an object, `select: { list: [...] }` for a
66
+ * list, each checked against it. `orderBy` names the field itself for a
67
+ * scalar, or a scalar inside it for an object.
68
+ *
69
+ * See ./columnTyping for how a helper's own field is checked.
70
+ */
71
+ export declare function fieldColumn<Row, const Field extends string, Value = ColumnFieldValue<Row, Field>>(args: {
72
+ rowType: Row;
73
+ field: Field & ValidateColumnFieldType<Row, Field, Value>;
74
+ id?: string;
30
75
  name: string;
31
- data: FieldQueries;
32
76
  footer?: TableColumnDefinitionFooter;
33
- orderBy?: OrderableFieldPath<FieldQueries>;
34
- cellRenderer: CellRenderer<DataFromFieldQueriesSafe<FieldQueries>>;
35
- }): TableColumnDefinition<FieldQueries>;
77
+ orderBy?: NoInfer<FieldColumnOrderBy<Field, Value>>;
78
+ cellRenderer: FieldCellRenderer<Value>;
79
+ } & NoInfer<FieldColumnSelect<Value>>): TableColumnDefinition;
36
80
  /**
37
- * Creates a data-only virtual column definition. Convenience wrapper around
38
- * the underlying VirtualColumnDefinition type.
81
+ * Creates a data-only virtual column definition for a view over `Row`.
82
+ * Convenience wrapper around the underlying VirtualColumnDefinition type.
39
83
  */
40
- export declare function virtualColumn<const FieldQueries extends readonly FieldQuery[]>(args: {
84
+ export declare function virtualColumn<Row, const FieldQueries extends readonly FieldQuery[]>(args: {
85
+ rowType: Row;
41
86
  id: string;
42
- data: FieldQueries;
87
+ data: FieldQueries & readonly FieldQueryForRowSafe<Row>[];
43
88
  }): VirtualColumnDefinition<FieldQueries>;
44
89
  export type { Query } from "../framework/column-definition";
@@ -1,6 +1,7 @@
1
1
  import type { ConditionOnlyTransform, FilterControl, FilterExpr as FilterExprType, FilterField, FilterTransform } from '../framework/filters';
2
2
  import type { ControlValue } from './filterControl';
3
3
  import type { FilterLeafOperator } from './filterTyping';
4
+ import type { IsAny } from './typeErrors';
4
5
  export type { ConditionOnlyTransform, FilterField, FilterTransform };
5
6
  export type FilterExpr = FilterExprType;
6
7
  /**
@@ -19,7 +20,6 @@ export type FilterExprLeaf<Type extends FilterLeafOperator, Field extends Filter
19
20
  export type FilterExprLeafWithTransform<Type extends FilterLeafOperator, Field extends FilterField, Control extends FilterControl, Transform extends FilterTransform<any>> = FilterExprLeaf<Type, Field, Control> & {
20
21
  transform: Transform;
21
22
  };
22
- type IsAny<T> = 0 extends 1 & T ? true : false;
23
23
  type Exactly<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
24
24
  /**
25
25
  * Whether a transform was actually passed.
@@ -15,7 +15,7 @@
15
15
  * so `FilterExpr.iLike({ field: 'amount' })` and `H.condition('amount',
16
16
  * H.ilike(...))` now agree.
17
17
  *
18
- * Failures surface as a `FilterTypeError`, whose single property *name* is the
18
+ * Failures surface as a `DslTypeError`, whose single property *name* is the
19
19
  * message, so tsc prints it verbatim at the `filter()` call.
20
20
  *
21
21
  * Deliberate escape hatches — all of them cases where the declared shape no
@@ -34,24 +34,11 @@
34
34
  */
35
35
  import type { HasuraOperatorFor, PathValue } from '@kronor/hasura-graphql';
36
36
  import type { FilterControl, FilterExpr, TransformConditionResult } from '../framework/filters';
37
- /**
38
- * A failed check. The message is the property name so that tsc reports
39
- * "Property '<message>' is missing ..." instead of a structural diff.
40
- */
41
- export type FilterTypeError<Message extends string> = {
42
- [K in Message]: never;
43
- };
37
+ import type { Brand, CheckedAs, DescribeType, IsAny, NestingDepth, Opaque } from './typeErrors';
44
38
  /** Mutable counterpart of an inferred `readonly` tuple. */
45
39
  export type MutableTuple<T extends readonly unknown[]> = [...T];
46
- type IsAny<T> = 0 extends 1 & T ? true : false;
47
40
  type IsTuple<T> = T extends readonly unknown[] ? (number extends T['length'] ? false : true) : false;
48
- /** Value types nothing can be concluded from: json/jsonb columns, widened rows. */
49
- type Opaque<Value> = IsAny<Value> extends true ? true : unknown extends Value ? true : false;
50
41
  type Accepts<Value, Allowed> = [Extract<Value, Allowed>] extends [never] ? false : true;
51
- /** Non-distributive so that literal unions (Hasura enums) describe as one word. */
52
- type DescribeType<Value> = [
53
- Value
54
- ] extends [string] ? 'string' : [Value] extends [number] ? 'number' : [Value] extends [boolean] ? 'boolean' : [Value] extends [Date] ? 'Date' : [Value] extends [readonly unknown[]] ? 'a list' : [Value] extends [object] ? 'an object' : 'unknown';
55
42
  type ShowValue<Value> = [
56
43
  Value
57
44
  ] extends [string] ? `'${Value}'` : [Value] extends [number] ? `${Value}` : [Value] extends [boolean] ? `${Value}` : DescribeType<Value>;
@@ -78,7 +65,7 @@ type PathsOf<Field> = Field extends string ? readonly [Field] : Field extends {
78
65
  or: infer Paths extends readonly string[];
79
66
  } ? Paths : readonly [];
80
67
  type HasTransform<Leaf> = 'transform' extends keyof Leaf ? [Exclude<Leaf['transform'], undefined>] extends [never] ? false : true : false;
81
- type PathError<Row, Path extends string> = [PathValue<Row, Path>] extends [never] ? `'${Path}' is not a field of the row type` : never;
68
+ type PathError<Row, Path extends string> = string extends Path ? `the field must be a literal path; a helper takes it as 'Field & ValidateFilterFieldType<Row, Field, Value>'` : [PathValue<Row, Path>] extends [never] ? `'${Path}' is not a field of the row type` : never;
82
69
  type ControlError<Path extends string, Value, Control extends FilterControl> = Control extends {
83
70
  type: 'dropdown' | 'multiselect';
84
71
  items: infer Items;
@@ -158,22 +145,11 @@ type LeafErrors<Row, Leaf> = Leaf extends {
158
145
  value: infer Control extends FilterControl;
159
146
  } ? PathErrors<Row, Field> | OperatorListErrors<Row, Field, Control> | CustomOperatorTransformError<Leaf, Control> | EmptyTransformError<Leaf> | (HasTransform<Leaf> extends true ? never : ControlErrors<Row, Type, Field, Control> | OperatorErrors<Row, Type, Field>) : never;
160
147
  /**
161
- * Decrementing counter that bounds how far into and/or/not the walk goes.
162
- * Real filter trees are a few levels deep; the bound exists because during
163
- * inference the expression is still a type variable, and an unbounded walk
164
- * would recur until tsc gives up ("excessively deep").
148
+ * `NestingDepth` bounds how far into and/or/not the walk goes. Real filter
149
+ * trees are a few levels deep; the bound exists because during inference the
150
+ * expression is still a type variable, and an unbounded walk would recur until
151
+ * tsc gives up ("excessively deep").
165
152
  */
166
- type NestingDepth = {
167
- 0: never;
168
- 1: 0;
169
- 2: 1;
170
- 3: 2;
171
- 4: 3;
172
- 5: 4;
173
- 6: 5;
174
- 7: 6;
175
- 8: 7;
176
- };
177
153
  type ExprErrors<Row, Expr, Depth extends keyof NestingDepth = 8> = Depth extends 0 ? never : Expr extends {
178
154
  type: 'and' | 'or';
179
155
  filters: infer Filters;
@@ -181,7 +157,6 @@ type ExprErrors<Row, Expr, Depth extends keyof NestingDepth = 8> = Depth extends
181
157
  type: 'not';
182
158
  filter: infer Child;
183
159
  } ? ExprErrors<Row, Child, NestingDepth[Depth]> : LeafErrors<Row, Expr>;
184
- type Brand<Errors> = [Errors] extends [never] ? unknown : FilterTypeError<Extract<Errors, string>>;
185
160
  /**
186
161
  * The checks above, addressed one argument at a time so that a row-scoped
187
162
  * builder (./filterExprForRow) can report each on the property that caused it
@@ -192,36 +167,47 @@ export type ValidateControlForRow<Row, Type extends FilterLeafOperator, Field, C
192
167
  /** Only what still applies once a transform decides the value (see above). */
193
168
  export type ValidateOperatorListForRow<Row, Field, Control extends FilterControl> = Brand<OperatorListErrors<Row, Field, Control>>;
194
169
  /**
195
- * `unknown` when the field holds a `Value`, otherwise a `FilterTypeError`
196
- * saying what it holds instead. For a helper that only makes sense on one kind
197
- * of column — a numeric range, a text search — brand its field parameter with
198
- * this:
170
+ * `unknown` when the field is on the row and holds a `Value`, otherwise a
171
+ * `DslTypeError` saying what is wrong. A filter helper that takes its field from
172
+ * the caller brands its field parameter with this, so the caller's field is
173
+ * checked even though the checks inside the helper cannot run while `Row` is a
174
+ * type parameter:
199
175
  *
200
- * function numberRange<Row, const Field extends FilterFieldPath<Row>>(args: {
176
+ * function numberRange<Row, const Field extends FilterField>(args: {
201
177
  * rowType: Row;
202
178
  * field: Field & ValidateFilterFieldType<Row, Field, number>;
203
179
  * }) { ... }
204
180
  *
205
- * This resolves the type of the *one* field it is given. Selecting the row's
206
- * fields by type instead — enumerating every path and resolving each one —
207
- * costs work proportional to the size of the row, and exceeded TypeScript's
208
- * instantiation limit on real generated rows of ~900 lines. Every field of an
209
- * `and`/`or` group is checked, and nullability is ignored: filtering a nullable
210
- * column filters the values it does have.
181
+ * `Value` is what the helper's control produces (`string` for a text search,
182
+ * `number` for a range); `unknown` accepts any field on the row. A helper can
183
+ * hand the field on to another such helper, as for columns (see
184
+ * ./columnTyping): its brand is accepted where the same or a wider `Value` is
185
+ * asked for. A plain `string`, or a `Field` nothing has checked, is rejected.
186
+ *
187
+ * This resolves the type of the *one* field it is given. Constraining it to
188
+ * `FilterFieldPath<Row>` or selecting the row's fields by type instead —
189
+ * enumerating every path and resolving each one — costs work proportional to
190
+ * the size of the row, and exceeded TypeScript's instantiation limit on real
191
+ * generated rows of ~900 lines. Every field of an `and`/`or` group is checked,
192
+ * and nullability is ignored: filtering a nullable column filters the values it
193
+ * does have.
211
194
  */
212
- export type ValidateFilterFieldType<Row, Field, Value> = Brand<FieldTypeErrors<Row, Field, Value>>;
195
+ export type ValidateFilterFieldType<Row, Field, Value> = [
196
+ Row,
197
+ Field
198
+ ] extends [infer R, infer F] ? Brand<PathErrors<R, F> | FieldTypeErrors<R, F, Value>> : CheckedAs<Value>;
213
199
  type FieldTypeErrors<Row, Field, Value> = PathsOf<Field>[number] extends infer Path ? Path extends string ? CheckableValue<Row, Path> extends infer Held ? [Held] extends [never] ? never : Accepts<Held, Value> extends true ? never : `field '${Path}' holds ${DescribeType<Held>}, and this filter needs ${DescribeType<Value>}` : never : never : never;
214
200
  /**
215
201
  * `unknown` when `Expr` is a legal filter over `Row`, otherwise a
216
- * `FilterTypeError` naming what is wrong. Intended to be intersected with the
202
+ * `DslTypeError` naming what is wrong. Intended to be intersected with the
217
203
  * expression's own inferred type at the `filter()` boundary:
218
204
  *
219
205
  * expression: Expr & ValidateFilterExprForRow<Row, Expr>
220
206
  *
221
207
  * The checks cannot be evaluated while `Row` is still a type parameter; there
222
208
  * they yield no errors rather than false ones, so a generic helper that builds
223
- * filters for a row type it hasn't been given yet keeps compiling. Constrain
224
- * such a helper's own arguments with `FilterFieldPath<Row>` to keep its
209
+ * filters for a row type it hasn't been given yet keeps compiling. Brand such
210
+ * a helper's field parameter with `ValidateFilterFieldType` to keep its
225
211
  * callers checked. See ./filters.
226
212
  */
227
213
  export type ValidateFilterExprForRow<Row, Expr extends FilterExpr> = Brand<ExprErrors<Row, Expr>>;
@@ -58,11 +58,11 @@ export declare function filterGroup(args: {
58
58
  *
59
59
  * The checks need a `Row` that is already known. Inside a generic helper that
60
60
  * builds filters for a row type it hasn't been given yet, they cannot be
61
- * evaluated and are skipped; constrain the helper's own arguments with
62
- * `FilterFieldPath<Row>` so its callers are still checked:
61
+ * evaluated and are skipped; brand the helper's field parameter with
62
+ * `ValidateFilterFieldType` so its callers are still checked:
63
63
  *
64
- * function textFilter<Row, const Field extends FilterFieldPath<Row>>(
65
- * args: { rowType: Row; id: string; label: string; field: Field }
64
+ * function textFilter<Row, const Field extends FilterField>(
65
+ * args: { rowType: Row; id: string; label: string; field: Field & ValidateFilterFieldType<Row, Field, string> }
66
66
  * ) {
67
67
  * return filter({
68
68
  * rowType: args.rowType,
@@ -6,6 +6,8 @@ export * from './filterExpr';
6
6
  export * from './filterExprForRow';
7
7
  export * from './filters';
8
8
  export * from './filterTyping';
9
+ export type { ColumnFieldValue, ValidateColumnFieldType } from './columnTyping';
10
+ export type { DslTypeError } from './typeErrors';
9
11
  export * from './hasura';
10
12
  export * from './queryForRow';
11
13
  export * from './view';
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Shared machinery of the DSL's type-level checks (./filterTyping,
3
+ * ./columnTyping, ./filterExpr). Only `DslTypeError` is part of the public API;
4
+ * the rest is internal to the checks.
5
+ */
6
+ /**
7
+ * A failed check. The message is the property name so that tsc reports
8
+ * "Property '<message>' is missing ..." instead of a structural diff.
9
+ */
10
+ export type DslTypeError<Message extends string> = {
11
+ [K in Message]: never;
12
+ };
13
+ /** `unknown` when there are no errors, otherwise a `DslTypeError` carrying them. */
14
+ export type Brand<Errors> = [Errors] extends [never] ? unknown : DslTypeError<Extract<Errors, string>>;
15
+ declare const checkedAs: unique symbol;
16
+ /**
17
+ * The unreachable branch of a field validator (`ValidateColumnFieldType`,
18
+ * `ValidateFilterFieldType`), there only for the variance of `Value`:
19
+ *
20
+ * export type ValidateXFieldType<Row, Field, Value> =
21
+ * [Row, Field] extends [infer R, infer F] ? Brand<Errors<R, F, Value>> : CheckedAs<Value>;
22
+ *
23
+ * Inside a helper the row is a type parameter and the errors cannot be
24
+ * evaluated, so a field one helper hands on to another is compared by its
25
+ * brand alone: one checked to hold `Account` is accepted where one holding
26
+ * `Account | null` is asked for, and not where `string` is. TypeScript compares
27
+ * the two brands' type arguments by the variance it measures for each, and the
28
+ * unevaluated errors measure as independent of `Value` — on their own they
29
+ * would let any brand through. `infer` always matches, so this branch is never
30
+ * taken; it makes `Value` measure as covariant.
31
+ *
32
+ * Two details are load-bearing, and pinned down by the forwarding tests in
33
+ * columnTyping.rowTyping.test.ts and filters.rowTyping.test.ts. The errors are
34
+ * written against the inferred `R` and `F`: against `Row` and `Field`, a field
35
+ * handed on without naming the type arguments is not recognised. And the
36
+ * conditional is written out in each validator: behind a shared generic alias,
37
+ * tsc resolves it early and the branch is lost.
38
+ */
39
+ export type CheckedAs<Value> = {
40
+ readonly [checkedAs]: Value;
41
+ };
42
+ export type IsAny<T> = 0 extends 1 & T ? true : false;
43
+ /** Value types nothing can be concluded from: json/jsonb columns, widened rows. */
44
+ export type Opaque<Value> = IsAny<Value> extends true ? true : unknown extends Value ? true : false;
45
+ /** Non-distributive so that literal unions (Hasura enums) describe as one word. */
46
+ export type DescribeType<Value> = [
47
+ Value
48
+ ] extends [string] ? 'string' : [Value] extends [number] ? 'number' : [Value] extends [boolean] ? 'boolean' : [Value] extends [Date] ? 'Date' : [Value] extends [readonly unknown[]] ? 'a list' : [Value] extends [object] ? 'an object' : 'unknown';
49
+ /** Decrementing counter that bounds type-level recursion. */
50
+ export type NestingDepth = {
51
+ 0: never;
52
+ 1: 0;
53
+ 2: 1;
54
+ 3: 2;
55
+ 4: 3;
56
+ 5: 4;
57
+ 6: 5;
58
+ 7: 6;
59
+ 8: 7;
60
+ };
61
+ export {};
@@ -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