@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.
@@ -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 {};
@@ -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>;