@kronor/dtv 8.1.1 → 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 +5842 -5796
- 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/dist/types/framework/data.d.ts +7 -1
- 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 {};
|
|
@@ -20,7 +20,7 @@ export declare const buildGraphQLQueryVariables: (view: View, filterState: Filte
|
|
|
20
20
|
rowLimit: number;
|
|
21
21
|
orderBy: HasuraOrderBy[];
|
|
22
22
|
};
|
|
23
|
-
export declare const fetchData: ({ client, view, query, filterState, rowLimit, cursor, ordering }: {
|
|
23
|
+
export declare const fetchData: ({ client, view, query, filterState, rowLimit, cursor, ordering, signal }: {
|
|
24
24
|
client: GraphQLClient;
|
|
25
25
|
view: View;
|
|
26
26
|
query: string;
|
|
@@ -28,7 +28,13 @@ export declare const fetchData: ({ client, view, query, filterState, rowLimit, c
|
|
|
28
28
|
rowLimit: number;
|
|
29
29
|
cursor: PaginationCursor;
|
|
30
30
|
ordering?: DataOrdering | null;
|
|
31
|
+
/**
|
|
32
|
+
* Cancels the request. Once it is aborted, fetchData rejects with an AbortError
|
|
33
|
+
* instead of returning rows, even when the response has already arrived.
|
|
34
|
+
*/
|
|
35
|
+
signal?: AbortSignal;
|
|
31
36
|
}) => Promise<FetchDataResult>;
|
|
37
|
+
export declare const isAbortError: (error: unknown) => boolean;
|
|
32
38
|
export declare const flattenFields: (rows: Record<string, unknown>[], columns: ColumnDefinition[]) => FlattenedDataRow[];
|
|
33
39
|
export declare const flattenFieldQueries: (row: Record<string, unknown>, fieldQueries: readonly FieldQuery[]) => Record<string, unknown>;
|
|
34
40
|
export declare const flattenColumnFields: (row: Record<string, unknown>, column: ColumnDefinition) => Record<string, unknown>;
|