@kronor/dtv 7.7.3 → 8.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -0
- package/dist/cli/typegen/runTypegen.js +169 -74
- package/dist/index.es.js +4689 -4698
- package/dist/types/dsl/filterControl.d.ts +125 -33
- package/dist/types/dsl/filterExpr.d.ts +88 -139
- package/dist/types/dsl/filterExprForRow.d.ts +111 -0
- package/dist/types/dsl/filterTransform.d.ts +1 -1
- package/dist/types/dsl/filterTyping.d.ts +228 -0
- package/dist/types/dsl/filters.d.ts +41 -19
- package/dist/types/dsl/index.d.ts +2 -0
- package/dist/types/framework/filters.d.ts +87 -18
- package/dist/types/framework/view-parser.d.ts +11 -0
- package/dist/types/lib/index.d.ts +2 -0
- package/docs/api/README.md +1 -0
- package/docs/api/row-typed-views.md +315 -0
- package/docs/typegen.md +35 -1
- package/package.json +1 -1
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Type-level validation of a filter expression against a row type.
|
|
3
|
+
*
|
|
4
|
+
* Every leaf's `field` has to name a real path on the row — and beyond that,
|
|
5
|
+
* the two things a path alone cannot express:
|
|
6
|
+
*
|
|
7
|
+
* - the *control* must be able to produce a value of the field's type — a
|
|
8
|
+
* `text` control cannot filter a numeric column, and a dropdown's item
|
|
9
|
+
* values must be values the column can hold;
|
|
10
|
+
* - the *operator* must be one Hasura offers for that type — `iLike` on a
|
|
11
|
+
* number, `greaterThan` on a boolean.
|
|
12
|
+
*
|
|
13
|
+
* Both derive from the same source of truth as the row-scoped Hasura DSL:
|
|
14
|
+
* `HasuraOperatorFor<Value>` decides which operators exist for a value type,
|
|
15
|
+
* so `FilterExpr.iLike({ field: 'amount' })` and `H.condition('amount',
|
|
16
|
+
* H.ilike(...))` now agree.
|
|
17
|
+
*
|
|
18
|
+
* Failures surface as a `FilterTypeError`, whose single property *name* is the
|
|
19
|
+
* message, so tsc prints it verbatim at the `filter()` call.
|
|
20
|
+
*
|
|
21
|
+
* Deliberate escape hatches — all of them cases where the declared shape no
|
|
22
|
+
* longer describes what reaches the query:
|
|
23
|
+
* - a leaf carrying a `transform` is exempt from the control and operator
|
|
24
|
+
* checks (a transform may re-map the value, the field, or return a whole
|
|
25
|
+
* condition). Its `customOperator` operator list is still checked, since
|
|
26
|
+
* the built-in transform passes those operators straight to Hasura.
|
|
27
|
+
* - `json`/`jsonb` columns (typed `any`) and rows with an index signature
|
|
28
|
+
* accept anything.
|
|
29
|
+
* - `custom` and `autocomplete` controls have transform-defined values, so
|
|
30
|
+
* only their operator is checked.
|
|
31
|
+
* - `dropdown`/`multiselect` item lists and `customOperator` operator lists
|
|
32
|
+
* are only checked when written inline (a tuple); a list built at runtime
|
|
33
|
+
* is widened and cannot be inspected.
|
|
34
|
+
*/
|
|
35
|
+
import type { HasuraOperatorFor, PathValue } from '@kronor/hasura-graphql';
|
|
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
|
+
};
|
|
44
|
+
/** Mutable counterpart of an inferred `readonly` tuple. */
|
|
45
|
+
export type MutableTuple<T extends readonly unknown[]> = [...T];
|
|
46
|
+
type IsAny<T> = 0 extends 1 & T ? true : false;
|
|
47
|
+
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
|
+
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
|
+
type ShowValue<Value> = [
|
|
56
|
+
Value
|
|
57
|
+
] extends [string] ? `'${Value}'` : [Value] extends [number] ? `${Value}` : [Value] extends [boolean] ? `${Value}` : DescribeType<Value>;
|
|
58
|
+
/** Leaf operator -> the Hasura operator `buildHasuraConditions` emits for it. */
|
|
59
|
+
type LeafHasuraOperator = {
|
|
60
|
+
equals: '_eq';
|
|
61
|
+
notEquals: '_neq';
|
|
62
|
+
greaterThan: '_gt';
|
|
63
|
+
lessThan: '_lt';
|
|
64
|
+
greaterThanOrEqual: '_gte';
|
|
65
|
+
lessThanOrEqual: '_lte';
|
|
66
|
+
in: '_in';
|
|
67
|
+
notIn: '_nin';
|
|
68
|
+
like: '_like';
|
|
69
|
+
iLike: '_ilike';
|
|
70
|
+
isNull: '_isNull';
|
|
71
|
+
};
|
|
72
|
+
/** The operators a leaf filter expression can carry. */
|
|
73
|
+
export type FilterLeafOperator = keyof LeafHasuraOperator;
|
|
74
|
+
/** Every field path a leaf filters on: one for a plain field, N for and/or groups. */
|
|
75
|
+
type PathsOf<Field> = Field extends string ? readonly [Field] : Field extends {
|
|
76
|
+
and: infer Paths extends readonly string[];
|
|
77
|
+
} ? Paths : Field extends {
|
|
78
|
+
or: infer Paths extends readonly string[];
|
|
79
|
+
} ? Paths : readonly [];
|
|
80
|
+
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;
|
|
82
|
+
type ControlError<Path extends string, Value, Control extends FilterControl> = Control extends {
|
|
83
|
+
type: 'dropdown' | 'multiselect';
|
|
84
|
+
items: infer Items;
|
|
85
|
+
} ? ItemValueError<Path, Value, Items> : ControlAccepts<Value, Control> extends true ? never : `control '${Control['type']}' cannot produce a value for '${Path}' (type ${DescribeType<Value>})`;
|
|
86
|
+
type ControlAccepts<Value, Control extends FilterControl> = Control extends {
|
|
87
|
+
type: 'text';
|
|
88
|
+
} ? Accepts<Value, string> : Control extends {
|
|
89
|
+
type: 'number';
|
|
90
|
+
} ? Accepts<Value, number> : Control extends {
|
|
91
|
+
type: 'date';
|
|
92
|
+
} ? Accepts<Value, string | number | Date> : true;
|
|
93
|
+
/**
|
|
94
|
+
* An item stands for one value of the field, so a list column is compared
|
|
95
|
+
* against its element type: a multiselect over `text[]` offers the individual
|
|
96
|
+
* strings, not lists of them.
|
|
97
|
+
*/
|
|
98
|
+
type ItemTarget<Value> = Value extends readonly (infer Element)[] ? NonNullable<Element> : Value;
|
|
99
|
+
type ItemValueError<Path extends string, Value, Items> = IsTuple<Items> extends false ? never : Items extends readonly {
|
|
100
|
+
value: infer ItemValue;
|
|
101
|
+
}[] ? IsAny<ItemValue> extends true ? never : Exclude<ItemValue, ItemTarget<Value>> extends infer Rejected ? [Rejected] extends [never] ? never : `item value ${ShowValue<Rejected>} is not a possible value of field '${Path}'` : never : never;
|
|
102
|
+
type ToQueryResult<Transform> = Transform extends {
|
|
103
|
+
toQuery?: (input: any, context: any) => infer Result;
|
|
104
|
+
} ? Result : never;
|
|
105
|
+
/**
|
|
106
|
+
* A `customOperator` control stores the operator alongside the value, which
|
|
107
|
+
* only a transform can turn into a condition — `buildHasuraConditions` throws
|
|
108
|
+
* for both of these, so they are worth saying up front. `ConditionOnlyTransform`
|
|
109
|
+
* is the type to annotate such a transform with.
|
|
110
|
+
*/
|
|
111
|
+
type CustomOperatorTransformError<Leaf, Control> = Control extends {
|
|
112
|
+
type: 'customOperator';
|
|
113
|
+
} ? Leaf extends {
|
|
114
|
+
transform: infer Transform;
|
|
115
|
+
} ? [ToQueryResult<Transform>] extends [TransformConditionResult] ? never : "a 'customOperator' control needs a query transform that returns a condition" : "a 'customOperator' control needs a query transform" : never;
|
|
116
|
+
/**
|
|
117
|
+
* `toQuery` is optional on `FilterTransform` — which is what lets the leaf
|
|
118
|
+
* builders tell an omitted transform from a real one, see
|
|
119
|
+
* filterExpr's `IsTransformed` — so a transform object carrying nothing at all
|
|
120
|
+
* type-checks while doing nothing at query time, and would take the checks
|
|
121
|
+
* below down with it.
|
|
122
|
+
*/
|
|
123
|
+
type EmptyTransformError<Leaf> = Leaf extends {
|
|
124
|
+
transform: infer Transform;
|
|
125
|
+
} ? 'toQuery' extends keyof Transform ? never : 'a transform needs a toQuery function' : never;
|
|
126
|
+
type OperatorError<Type extends FilterLeafOperator, Path extends string, Value> = LeafHasuraOperator[Type] extends keyof HasuraOperatorFor<Value> ? never : `operator '${Type}' is not available for field '${Path}' (type ${DescribeType<Value>})`;
|
|
127
|
+
/**
|
|
128
|
+
* A multiselect yields a list of values, which only `in`/`notIn` can consume —
|
|
129
|
+
* unless the column itself is a list.
|
|
130
|
+
*/
|
|
131
|
+
type ListControlError<Type extends FilterLeafOperator, Path extends string, Value, Control extends FilterControl> = Control extends {
|
|
132
|
+
type: 'multiselect';
|
|
133
|
+
} ? Type extends 'in' | 'notIn' ? never : [Value] extends [readonly unknown[]] ? never : `control 'multiselect' produces a list of values for '${Path}'; use 'in' or 'notIn' rather than '${Type}'` : never;
|
|
134
|
+
/**
|
|
135
|
+
* `customOperator` operators reach Hasura verbatim through the built-in
|
|
136
|
+
* transform, so a recognised operator must be one the column supports.
|
|
137
|
+
* Anything that is not a Hasura operator name is left to the transform.
|
|
138
|
+
*/
|
|
139
|
+
type CustomOperatorError<Path extends string, Value, Control extends FilterControl> = Control extends {
|
|
140
|
+
type: 'customOperator';
|
|
141
|
+
operators: infer Operators;
|
|
142
|
+
} ? IsTuple<Operators> extends false ? never : Operators extends readonly {
|
|
143
|
+
value: infer Operator;
|
|
144
|
+
}[] ? Operator extends string ? Operator extends keyof HasuraOperatorFor<any> ? Operator extends keyof HasuraOperatorFor<Value> ? never : `operator '${Operator}' is not available for field '${Path}' (type ${DescribeType<Value>})` : never : never : never : never;
|
|
145
|
+
/**
|
|
146
|
+
* The type of the field at `Path`, with nullability removed — `never` when
|
|
147
|
+
* nothing can be checked against it, either because the path does not exist
|
|
148
|
+
* (`PathError` reports that) or because its type is opaque.
|
|
149
|
+
*/
|
|
150
|
+
type CheckableValue<Row, Path extends string> = PathValue<Row, Path> extends infer Raw ? [Raw] extends [never] ? never : Opaque<Raw> extends true ? never : NonNullable<Raw> : never;
|
|
151
|
+
type PathErrors<Row, Field> = PathsOf<Field>[number] extends infer Path ? Path extends string ? PathError<Row, Path> : never : never;
|
|
152
|
+
type ControlErrors<Row, Type extends FilterLeafOperator, Field, Control extends FilterControl> = PathsOf<Field>[number] extends infer Path ? Path extends string ? CheckableValue<Row, Path> extends infer Value ? [Value] extends [never] ? never : ControlError<Path, Value, Control> | ListControlError<Type, Path, Value, Control> : never : never : never;
|
|
153
|
+
type OperatorErrors<Row, Type extends FilterLeafOperator, Field> = PathsOf<Field>[number] extends infer Path ? Path extends string ? CheckableValue<Row, Path> extends infer Value ? [Value] extends [never] ? never : OperatorError<Type, Path, Value> : never : never : never;
|
|
154
|
+
type OperatorListErrors<Row, Field, Control extends FilterControl> = PathsOf<Field>[number] extends infer Path ? Path extends string ? CheckableValue<Row, Path> extends infer Value ? [Value] extends [never] ? never : CustomOperatorError<Path, Value, Control> : never : never : never;
|
|
155
|
+
type LeafErrors<Row, Leaf> = Leaf extends {
|
|
156
|
+
type: infer Type extends FilterLeafOperator;
|
|
157
|
+
field: infer Field;
|
|
158
|
+
value: infer Control extends FilterControl;
|
|
159
|
+
} ? 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
|
+
/**
|
|
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").
|
|
165
|
+
*/
|
|
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
|
+
type ExprErrors<Row, Expr, Depth extends keyof NestingDepth = 8> = Depth extends 0 ? never : Expr extends {
|
|
178
|
+
type: 'and' | 'or';
|
|
179
|
+
filters: infer Filters;
|
|
180
|
+
} ? Filters extends readonly unknown[] ? ExprErrors<Row, Filters[number], NestingDepth[Depth]> : never : Expr extends {
|
|
181
|
+
type: 'not';
|
|
182
|
+
filter: infer Child;
|
|
183
|
+
} ? ExprErrors<Row, Child, NestingDepth[Depth]> : LeafErrors<Row, Expr>;
|
|
184
|
+
type Brand<Errors> = [Errors] extends [never] ? unknown : FilterTypeError<Extract<Errors, string>>;
|
|
185
|
+
/**
|
|
186
|
+
* The checks above, addressed one argument at a time so that a row-scoped
|
|
187
|
+
* builder (./filterExprForRow) can report each on the property that caused it
|
|
188
|
+
* rather than on the whole `filter()` call. Each is `unknown` when it passes.
|
|
189
|
+
*/
|
|
190
|
+
export type ValidateOperatorForRow<Row, Type extends FilterLeafOperator, Field> = Brand<OperatorErrors<Row, Type, Field>>;
|
|
191
|
+
export type ValidateControlForRow<Row, Type extends FilterLeafOperator, Field, Control extends FilterControl> = Brand<ControlErrors<Row, Type, Field, Control> | OperatorListErrors<Row, Field, Control>>;
|
|
192
|
+
/** Only what still applies once a transform decides the value (see above). */
|
|
193
|
+
export type ValidateOperatorListForRow<Row, Field, Control extends FilterControl> = Brand<OperatorListErrors<Row, Field, Control>>;
|
|
194
|
+
/**
|
|
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:
|
|
199
|
+
*
|
|
200
|
+
* function numberRange<Row, const Field extends FilterFieldPath<Row>>(args: {
|
|
201
|
+
* rowType: Row;
|
|
202
|
+
* field: Field & ValidateFilterFieldType<Row, Field, number>;
|
|
203
|
+
* }) { ... }
|
|
204
|
+
*
|
|
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.
|
|
211
|
+
*/
|
|
212
|
+
export type ValidateFilterFieldType<Row, Field, Value> = Brand<FieldTypeErrors<Row, Field, Value>>;
|
|
213
|
+
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
|
+
/**
|
|
215
|
+
* `unknown` when `Expr` is a legal filter over `Row`, otherwise a
|
|
216
|
+
* `FilterTypeError` naming what is wrong. Intended to be intersected with the
|
|
217
|
+
* expression's own inferred type at the `filter()` boundary:
|
|
218
|
+
*
|
|
219
|
+
* expression: Expr & ValidateFilterExprForRow<Row, Expr>
|
|
220
|
+
*
|
|
221
|
+
* The checks cannot be evaluated while `Row` is still a type parameter; there
|
|
222
|
+
* 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
|
|
225
|
+
* callers checked. See ./filters.
|
|
226
|
+
*/
|
|
227
|
+
export type ValidateFilterExprForRow<Row, Expr extends FilterExpr> = Brand<ExprErrors<Row, Expr>>;
|
|
228
|
+
export {};
|
|
@@ -1,21 +1,20 @@
|
|
|
1
|
-
import type { FilterExpr, FilterField, FilterSchema, FilterGroup, FilterGroups, FilterTransform } from '../framework/filters';
|
|
1
|
+
import type { FilterExpr, FilterField, FilterFieldForRow, FilterSchema, FilterGroup, FilterGroups, FilterTransform } from '../framework/filters';
|
|
2
2
|
import type { FilterControl } from '../framework/filters';
|
|
3
|
-
|
|
4
|
-
type
|
|
3
|
+
import type { MutableTuple, ValidateFilterExprForRow } from './filterTyping';
|
|
4
|
+
export type { FilterField, FilterFieldForRow, FilterSchema, FilterGroup, FilterGroups, FilterTransform };
|
|
5
5
|
/**
|
|
6
6
|
* All valid dotted field paths for a given row type, and the value type each
|
|
7
7
|
* path resolves to. Both come from @kronor/hasura-graphql; the aliases keep
|
|
8
8
|
* DTV's filter-oriented names.
|
|
9
9
|
*/
|
|
10
|
-
import type { FieldPath } from '@kronor/hasura-graphql';
|
|
11
10
|
export type { FieldPath as FilterFieldPath, PathValue } from '@kronor/hasura-graphql';
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
11
|
+
/**
|
|
12
|
+
* A filter expression whose leaves all name real paths on `Row`.
|
|
13
|
+
*
|
|
14
|
+
* `filter({ rowType })` checks more than this (the control and the operator
|
|
15
|
+
* have to suit the field's type as well, see ./filterTyping); the type stays
|
|
16
|
+
* exported for callers who want to constrain an expression by field alone.
|
|
17
|
+
*/
|
|
19
18
|
export type FilterExprForRow<Row> = ({
|
|
20
19
|
type: 'and';
|
|
21
20
|
filters: FilterExprForRow<Row>[];
|
|
@@ -38,10 +37,10 @@ export type FilterExprForRow<Row> = ({
|
|
|
38
37
|
field: FilterFieldForRow<Row>;
|
|
39
38
|
});
|
|
40
39
|
export declare const filterField: {
|
|
41
|
-
and: <const Fields extends readonly string[]>(...fields: Fields) =>
|
|
40
|
+
and: <const Fields extends readonly string[]>(...fields: Fields) => {
|
|
42
41
|
and: MutableTuple<Fields>;
|
|
43
42
|
};
|
|
44
|
-
or: <const Fields extends readonly string[]>(...fields: Fields) =>
|
|
43
|
+
or: <const Fields extends readonly string[]>(...fields: Fields) => {
|
|
45
44
|
or: MutableTuple<Fields>;
|
|
46
45
|
};
|
|
47
46
|
};
|
|
@@ -50,17 +49,40 @@ export declare function filterGroup(args: {
|
|
|
50
49
|
label: string | null;
|
|
51
50
|
filters: FilterSchema[];
|
|
52
51
|
}): FilterGroup;
|
|
53
|
-
|
|
54
|
-
|
|
52
|
+
/**
|
|
53
|
+
* Checks `expression` against `Row`: every field path has to exist, and the
|
|
54
|
+
* control and the operator of each leaf have to suit the type of the field
|
|
55
|
+
* they filter — `FilterControl.text()` cannot filter a numeric column, `iLike`
|
|
56
|
+
* is not available on one. See `ValidateFilterExprForRow` for the full set of
|
|
57
|
+
* checks and the escape hatches.
|
|
58
|
+
*
|
|
59
|
+
* The checks need a `Row` that is already known. Inside a generic helper that
|
|
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:
|
|
63
|
+
*
|
|
64
|
+
* function textFilter<Row, const Field extends FilterFieldPath<Row>>(
|
|
65
|
+
* args: { rowType: Row; id: string; label: string; field: Field }
|
|
66
|
+
* ) {
|
|
67
|
+
* return filter({
|
|
68
|
+
* rowType: args.rowType,
|
|
69
|
+
* id: args.id,
|
|
70
|
+
* label: args.label,
|
|
71
|
+
* expression: FilterExpr.equals({ field: args.field, control: FilterControl.text() })
|
|
72
|
+
* });
|
|
73
|
+
* }
|
|
74
|
+
*/
|
|
75
|
+
export declare function filter<Row, const Expr extends FilterExpr>(args: {
|
|
76
|
+
rowType: Row;
|
|
55
77
|
id: string;
|
|
56
78
|
label: string;
|
|
57
|
-
expression:
|
|
79
|
+
expression: Expr & ValidateFilterExprForRow<Row, Expr>;
|
|
58
80
|
aiGenerated?: boolean;
|
|
59
81
|
}): FilterSchema;
|
|
60
|
-
export declare function filter
|
|
61
|
-
rowType
|
|
82
|
+
export declare function filter(args: {
|
|
83
|
+
rowType?: never;
|
|
62
84
|
id: string;
|
|
63
85
|
label: string;
|
|
64
|
-
expression:
|
|
86
|
+
expression: FilterExpr;
|
|
65
87
|
aiGenerated?: boolean;
|
|
66
88
|
}): FilterSchema;
|
|
@@ -3,7 +3,9 @@ export * from './cellRenderer';
|
|
|
3
3
|
export * from './reference';
|
|
4
4
|
export * from './filterControl';
|
|
5
5
|
export * from './filterExpr';
|
|
6
|
+
export * from './filterExprForRow';
|
|
6
7
|
export * from './filters';
|
|
8
|
+
export * from './filterTyping';
|
|
7
9
|
export * from './hasura';
|
|
8
10
|
export * from './queryForRow';
|
|
9
11
|
export * from './view';
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import * as React from 'react';
|
|
2
2
|
import { GraphQLClient } from 'graphql-request';
|
|
3
|
+
import type { FieldPath } from '@kronor/hasura-graphql';
|
|
3
4
|
import { HasuraFilterExpression } from './graphql';
|
|
4
5
|
import * as FilterValue from './filterValue';
|
|
5
6
|
export type FilterField = string | {
|
|
@@ -7,6 +8,18 @@ export type FilterField = string | {
|
|
|
7
8
|
} | {
|
|
8
9
|
or: string[];
|
|
9
10
|
};
|
|
11
|
+
/**
|
|
12
|
+
* `FilterField` narrowed to the paths of a known row. `Row` is often not known
|
|
13
|
+
* — a runtime's `queryTransforms`, a JSON view — and then this is `FilterField`
|
|
14
|
+
* unchanged.
|
|
15
|
+
*/
|
|
16
|
+
export type FilterFieldForRow<Row> = unknown extends Row ? FilterField : FieldPath<Row> | {
|
|
17
|
+
and: FieldPath<Row>[];
|
|
18
|
+
} | {
|
|
19
|
+
or: FieldPath<Row>[];
|
|
20
|
+
} | {
|
|
21
|
+
or: [];
|
|
22
|
+
};
|
|
10
23
|
export type TransformResult = {
|
|
11
24
|
field?: FilterField;
|
|
12
25
|
value: FilterValue.FilterValue;
|
|
@@ -34,18 +47,52 @@ export declare const TransformResult: {
|
|
|
34
47
|
export type TransformConditionResult = Extract<TransformResult, {
|
|
35
48
|
condition: HasuraFilterExpression;
|
|
36
49
|
}>;
|
|
37
|
-
|
|
38
|
-
|
|
50
|
+
/**
|
|
51
|
+
* The `TransformResult` builders, with `fieldValue` restricted to the row a
|
|
52
|
+
* transform is filtering. Handed to transforms on their context, so redirecting
|
|
53
|
+
* a filter to another field is checked the same way the filter's own `field`
|
|
54
|
+
* is.
|
|
55
|
+
*/
|
|
56
|
+
export type TransformResultForRow<Row> = Omit<typeof TransformResult, 'fieldValue'> & {
|
|
57
|
+
fieldValue: (field: FilterFieldForRow<Row>, value: unknown) => Extract<TransformResult, {
|
|
58
|
+
field?: FilterField;
|
|
59
|
+
value: FilterValue.FilterValue;
|
|
60
|
+
}>;
|
|
39
61
|
};
|
|
40
|
-
|
|
41
|
-
|
|
62
|
+
/**
|
|
63
|
+
* What a transform is told about the filter it belongs to.
|
|
64
|
+
*
|
|
65
|
+
* `Row` and `Field` are filled in by the DSL from the leaf being built, so
|
|
66
|
+
* `context.field` is the very path the filter declares and
|
|
67
|
+
* `context.result.fieldValue` only accepts paths of the row. Both default to
|
|
68
|
+
* unknown for transforms declared away from a filter, such as a runtime's
|
|
69
|
+
* `queryTransforms`.
|
|
70
|
+
*/
|
|
71
|
+
export type QueryTransformContext<Row = unknown, Field extends FilterField = FilterField> = {
|
|
72
|
+
field: Field;
|
|
42
73
|
FilterValue: typeof FilterValue;
|
|
74
|
+
result: TransformResultForRow<Row>;
|
|
43
75
|
transform: {
|
|
44
76
|
hasuraCustomOperator: ConditionOnlyTransform;
|
|
45
77
|
};
|
|
46
78
|
};
|
|
47
|
-
|
|
48
|
-
|
|
79
|
+
/**
|
|
80
|
+
* `Input` is the value the filter's control produces. The DSL fills it in from
|
|
81
|
+
* the control a leaf declares (see dsl/filterControl's `ControlValue`), so a
|
|
82
|
+
* transform's `input` arrives typed instead of needing a cast; it defaults to
|
|
83
|
+
* `unknown` for transforms declared away from a control.
|
|
84
|
+
*
|
|
85
|
+
* `Row` and `Field` reach the context, and default to `any` so that types which
|
|
86
|
+
* merely *hold* a transform accept one written against a narrower context. For
|
|
87
|
+
* the same reason a holder uses `FilterTransform<any>`: a transform taking a
|
|
88
|
+
* narrower input is not assignable to one taking `unknown`, and the holder
|
|
89
|
+
* cannot know which control it will end up next to.
|
|
90
|
+
*/
|
|
91
|
+
export type ConditionOnlyTransform<Input = unknown, Row = any, Field extends FilterField = any> = {
|
|
92
|
+
toQuery: (input: Input, context: QueryTransformContext<Row, Field>) => TransformConditionResult;
|
|
93
|
+
};
|
|
94
|
+
export type FilterTransform<Input = unknown, Row = any, Field extends FilterField = any> = {
|
|
95
|
+
toQuery?: (input: Input, context: QueryTransformContext<Row, Field>) => TransformResult;
|
|
49
96
|
};
|
|
50
97
|
export type FilterControl = {
|
|
51
98
|
type: 'text';
|
|
@@ -107,61 +154,78 @@ export type FilterControl = {
|
|
|
107
154
|
label?: string;
|
|
108
155
|
initialValue?: any;
|
|
109
156
|
};
|
|
157
|
+
/**
|
|
158
|
+
* `fieldLabel` is what the applied-filter pill shows in place of the field
|
|
159
|
+
* path. Without it a filter whose transform owns the query has no way to read
|
|
160
|
+
* nicely in the pill except by putting a display string in `field`, which the
|
|
161
|
+
* row-typed checks then have to reject.
|
|
162
|
+
*/
|
|
110
163
|
export type FilterExpr = {
|
|
111
164
|
type: 'equals';
|
|
112
165
|
field: FilterField;
|
|
113
166
|
value: FilterControl;
|
|
114
|
-
|
|
167
|
+
fieldLabel?: string;
|
|
168
|
+
transform?: FilterTransform<any>;
|
|
115
169
|
} | {
|
|
116
170
|
type: 'notEquals';
|
|
117
171
|
field: FilterField;
|
|
118
172
|
value: FilterControl;
|
|
119
|
-
|
|
173
|
+
fieldLabel?: string;
|
|
174
|
+
transform?: FilterTransform<any>;
|
|
120
175
|
} | {
|
|
121
176
|
type: 'greaterThan';
|
|
122
177
|
field: FilterField;
|
|
123
178
|
value: FilterControl;
|
|
124
|
-
|
|
179
|
+
fieldLabel?: string;
|
|
180
|
+
transform?: FilterTransform<any>;
|
|
125
181
|
} | {
|
|
126
182
|
type: 'lessThan';
|
|
127
183
|
field: FilterField;
|
|
128
184
|
value: FilterControl;
|
|
129
|
-
|
|
185
|
+
fieldLabel?: string;
|
|
186
|
+
transform?: FilterTransform<any>;
|
|
130
187
|
} | {
|
|
131
188
|
type: 'greaterThanOrEqual';
|
|
132
189
|
field: FilterField;
|
|
133
190
|
value: FilterControl;
|
|
134
|
-
|
|
191
|
+
fieldLabel?: string;
|
|
192
|
+
transform?: FilterTransform<any>;
|
|
135
193
|
} | {
|
|
136
194
|
type: 'lessThanOrEqual';
|
|
137
195
|
field: FilterField;
|
|
138
196
|
value: FilterControl;
|
|
139
|
-
|
|
197
|
+
fieldLabel?: string;
|
|
198
|
+
transform?: FilterTransform<any>;
|
|
140
199
|
} | {
|
|
141
200
|
type: 'in';
|
|
142
201
|
field: FilterField;
|
|
143
202
|
value: FilterControl;
|
|
144
|
-
|
|
203
|
+
fieldLabel?: string;
|
|
204
|
+
transform?: FilterTransform<any>;
|
|
145
205
|
} | {
|
|
146
206
|
type: 'notIn';
|
|
147
207
|
field: FilterField;
|
|
148
208
|
value: FilterControl;
|
|
149
|
-
|
|
209
|
+
fieldLabel?: string;
|
|
210
|
+
transform?: FilterTransform<any>;
|
|
150
211
|
} | {
|
|
151
212
|
type: 'like';
|
|
152
213
|
field: FilterField;
|
|
153
214
|
value: FilterControl;
|
|
154
|
-
|
|
215
|
+
fieldLabel?: string;
|
|
216
|
+
transform?: FilterTransform<any>;
|
|
155
217
|
} | {
|
|
156
218
|
type: 'iLike';
|
|
157
219
|
field: FilterField;
|
|
158
220
|
value: FilterControl;
|
|
159
|
-
|
|
221
|
+
fieldLabel?: string;
|
|
222
|
+
transform?: FilterTransform<any>;
|
|
160
223
|
} | {
|
|
161
224
|
type: 'isNull';
|
|
162
225
|
field: FilterField;
|
|
163
226
|
value: FilterControl;
|
|
164
|
-
|
|
227
|
+
fieldLabel?: string;
|
|
228
|
+
transform?: FilterTransform<any>;
|
|
165
229
|
} | {
|
|
166
230
|
type: 'and';
|
|
167
231
|
filters: FilterExpr[];
|
|
@@ -179,7 +243,12 @@ export declare const SUPPORTED_OPERATORS: {
|
|
|
179
243
|
export type SuggestionItem = {
|
|
180
244
|
label: string;
|
|
181
245
|
};
|
|
182
|
-
|
|
246
|
+
/**
|
|
247
|
+
* Suggestions reach the filter's transform as they come back from here — the
|
|
248
|
+
* item type is preserved so a fetcher returning `{ label, value }` gives its
|
|
249
|
+
* transform that shape rather than the bare `SuggestionItem`.
|
|
250
|
+
*/
|
|
251
|
+
export type SuggestionFetcher<Item extends SuggestionItem = SuggestionItem> = (query: string, client: GraphQLClient) => Promise<Item[]>;
|
|
183
252
|
export declare function isLeaf(expr: FilterExpr): expr is Extract<FilterExpr, {
|
|
184
253
|
field: FilterField;
|
|
185
254
|
value: FilterControl;
|
|
@@ -79,56 +79,67 @@ export type FilterExprJson = {
|
|
|
79
79
|
type: 'equals';
|
|
80
80
|
field: FilterFieldJson;
|
|
81
81
|
value: FilterControlJson;
|
|
82
|
+
fieldLabel?: string;
|
|
82
83
|
transform?: RuntimeReference;
|
|
83
84
|
} | {
|
|
84
85
|
type: 'notEquals';
|
|
85
86
|
field: FilterFieldJson;
|
|
86
87
|
value: FilterControlJson;
|
|
88
|
+
fieldLabel?: string;
|
|
87
89
|
transform?: RuntimeReference;
|
|
88
90
|
} | {
|
|
89
91
|
type: 'greaterThan';
|
|
90
92
|
field: FilterFieldJson;
|
|
91
93
|
value: FilterControlJson;
|
|
94
|
+
fieldLabel?: string;
|
|
92
95
|
transform?: RuntimeReference;
|
|
93
96
|
} | {
|
|
94
97
|
type: 'lessThan';
|
|
95
98
|
field: FilterFieldJson;
|
|
96
99
|
value: FilterControlJson;
|
|
100
|
+
fieldLabel?: string;
|
|
97
101
|
transform?: RuntimeReference;
|
|
98
102
|
} | {
|
|
99
103
|
type: 'greaterThanOrEqual';
|
|
100
104
|
field: FilterFieldJson;
|
|
101
105
|
value: FilterControlJson;
|
|
106
|
+
fieldLabel?: string;
|
|
102
107
|
transform?: RuntimeReference;
|
|
103
108
|
} | {
|
|
104
109
|
type: 'lessThanOrEqual';
|
|
105
110
|
field: FilterFieldJson;
|
|
106
111
|
value: FilterControlJson;
|
|
112
|
+
fieldLabel?: string;
|
|
107
113
|
transform?: RuntimeReference;
|
|
108
114
|
} | {
|
|
109
115
|
type: 'in';
|
|
110
116
|
field: FilterFieldJson;
|
|
111
117
|
value: FilterControlJson;
|
|
118
|
+
fieldLabel?: string;
|
|
112
119
|
transform?: RuntimeReference;
|
|
113
120
|
} | {
|
|
114
121
|
type: 'notIn';
|
|
115
122
|
field: FilterFieldJson;
|
|
116
123
|
value: FilterControlJson;
|
|
124
|
+
fieldLabel?: string;
|
|
117
125
|
transform?: RuntimeReference;
|
|
118
126
|
} | {
|
|
119
127
|
type: 'like';
|
|
120
128
|
field: FilterFieldJson;
|
|
121
129
|
value: FilterControlJson;
|
|
130
|
+
fieldLabel?: string;
|
|
122
131
|
transform?: RuntimeReference;
|
|
123
132
|
} | {
|
|
124
133
|
type: 'iLike';
|
|
125
134
|
field: FilterFieldJson;
|
|
126
135
|
value: FilterControlJson;
|
|
136
|
+
fieldLabel?: string;
|
|
127
137
|
transform?: RuntimeReference;
|
|
128
138
|
} | {
|
|
129
139
|
type: 'isNull';
|
|
130
140
|
field: FilterFieldJson;
|
|
131
141
|
value: FilterControlJson;
|
|
142
|
+
fieldLabel?: string;
|
|
132
143
|
transform?: RuntimeReference;
|
|
133
144
|
} | {
|
|
134
145
|
type: 'and';
|
|
@@ -27,6 +27,8 @@ export type { OrderDirection } from '../framework/order-direction';
|
|
|
27
27
|
export { hasuraFilterExpressionToObject, hasuraFilterExpressionsAreEqual, buildHasuraConditions, hasuraOperatorsAreEqual, generateSelectionSetFromColumns, generateGraphQLQueryAST, generateGraphQLQuery, renderGraphQLQuery, } from '../framework/graphql';
|
|
28
28
|
export { hasuraDSLforRowType } from '../dsl/hasura';
|
|
29
29
|
export type { HasuraForRow } from '../dsl/hasura';
|
|
30
|
+
export { filterExprForRowType } from '../dsl/filterExprForRow';
|
|
31
|
+
export type { FilterExprBuilderForRow } from '../dsl/filterExprForRow';
|
|
30
32
|
export { queryForRowType } from '../dsl/queryForRow';
|
|
31
33
|
export type { QueryBuilder } from '../dsl/queryForRow';
|
|
32
34
|
export type { Query, ValueQuery, ObjectQuery, ArrayQuery, FieldAlias, OrderByConfig } from '@kronor/hasura-graphql';
|
package/docs/api/README.md
CHANGED
|
@@ -39,6 +39,7 @@ Resolution precedence: External (per-app) runtime overrides Built-in runtime. If
|
|
|
39
39
|
- `cell-renderers.md` — How to write cell renderer functions and available helper components.
|
|
40
40
|
- `runtime.md` — Structure of the `Runtime` object and how runtime references are resolved.
|
|
41
41
|
- `no-rows-component.md` — Authoring components shown when a view returns zero rows.
|
|
42
|
+
- `row-typed-views.md` — Checking a TS view's columns and filters against its GraphQL row type.
|
|
42
43
|
|
|
43
44
|
Add additional docs here for transforms, custom filters, etc. as needed.
|
|
44
45
|
|