@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.
- package/dist/cli/typegen/runTypegen.js +4 -4
- package/dist/index.es.js +2983 -2948
- 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/docs/api/row-typed-views.md +91 -25
- package/docs/typegen.md +5 -5
- package/package.json +1 -1
|
@@ -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
|
|
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
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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?:
|
|
34
|
-
cellRenderer:
|
|
35
|
-
}): TableColumnDefinition
|
|
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
|
|
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 `
|
|
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
|
-
*
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
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
|
|
196
|
-
* saying what
|
|
197
|
-
*
|
|
198
|
-
*
|
|
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
|
|
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
|
-
*
|
|
206
|
-
*
|
|
207
|
-
*
|
|
208
|
-
*
|
|
209
|
-
* `
|
|
210
|
-
*
|
|
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> =
|
|
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
|
-
* `
|
|
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.
|
|
224
|
-
*
|
|
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;
|
|
62
|
-
* `
|
|
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
|
|
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
|
-
`
|
|
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
|