@kronor/dtv 7.7.3 → 8.0.1

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,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
- export type { FilterField, FilterSchema, FilterGroup, FilterGroups, FilterTransform };
4
- type MutableTuple<T extends readonly unknown[]> = [...T];
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
- export type FilterFieldForRow<Row> = FieldPath<Row> | {
13
- and: FieldPath<Row>[];
14
- } | {
15
- or: FieldPath<Row>[];
16
- } | {
17
- or: [];
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) => FilterField & {
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) => FilterField & {
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
- export declare function filter(args: {
54
- rowType?: never;
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: FilterExpr;
79
+ expression: Expr & ValidateFilterExprForRow<Row, Expr>;
58
80
  aiGenerated?: boolean;
59
81
  }): FilterSchema;
60
- export declare function filter<Row, const Expr extends FilterExpr>(args: {
61
- rowType: Row;
82
+ export declare function filter(args: {
83
+ rowType?: never;
62
84
  id: string;
63
85
  label: string;
64
- expression: Expr & FilterExprForRow<Row>;
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
- export type ConditionOnlyTransform = {
38
- toQuery: (input: unknown, context: QueryTransformContext) => TransformConditionResult;
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
- export type QueryTransformContext = {
41
- field: FilterField;
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
- export type FilterTransform = {
48
- toQuery?: (input: unknown, context: QueryTransformContext) => TransformResult;
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
- transform?: FilterTransform;
167
+ fieldLabel?: string;
168
+ transform?: FilterTransform<any>;
115
169
  } | {
116
170
  type: 'notEquals';
117
171
  field: FilterField;
118
172
  value: FilterControl;
119
- transform?: FilterTransform;
173
+ fieldLabel?: string;
174
+ transform?: FilterTransform<any>;
120
175
  } | {
121
176
  type: 'greaterThan';
122
177
  field: FilterField;
123
178
  value: FilterControl;
124
- transform?: FilterTransform;
179
+ fieldLabel?: string;
180
+ transform?: FilterTransform<any>;
125
181
  } | {
126
182
  type: 'lessThan';
127
183
  field: FilterField;
128
184
  value: FilterControl;
129
- transform?: FilterTransform;
185
+ fieldLabel?: string;
186
+ transform?: FilterTransform<any>;
130
187
  } | {
131
188
  type: 'greaterThanOrEqual';
132
189
  field: FilterField;
133
190
  value: FilterControl;
134
- transform?: FilterTransform;
191
+ fieldLabel?: string;
192
+ transform?: FilterTransform<any>;
135
193
  } | {
136
194
  type: 'lessThanOrEqual';
137
195
  field: FilterField;
138
196
  value: FilterControl;
139
- transform?: FilterTransform;
197
+ fieldLabel?: string;
198
+ transform?: FilterTransform<any>;
140
199
  } | {
141
200
  type: 'in';
142
201
  field: FilterField;
143
202
  value: FilterControl;
144
- transform?: FilterTransform;
203
+ fieldLabel?: string;
204
+ transform?: FilterTransform<any>;
145
205
  } | {
146
206
  type: 'notIn';
147
207
  field: FilterField;
148
208
  value: FilterControl;
149
- transform?: FilterTransform;
209
+ fieldLabel?: string;
210
+ transform?: FilterTransform<any>;
150
211
  } | {
151
212
  type: 'like';
152
213
  field: FilterField;
153
214
  value: FilterControl;
154
- transform?: FilterTransform;
215
+ fieldLabel?: string;
216
+ transform?: FilterTransform<any>;
155
217
  } | {
156
218
  type: 'iLike';
157
219
  field: FilterField;
158
220
  value: FilterControl;
159
- transform?: FilterTransform;
221
+ fieldLabel?: string;
222
+ transform?: FilterTransform<any>;
160
223
  } | {
161
224
  type: 'isNull';
162
225
  field: FilterField;
163
226
  value: FilterControl;
164
- transform?: FilterTransform;
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
- export type SuggestionFetcher = (query: string, client: GraphQLClient) => Promise<SuggestionItem[]>;
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';
@@ -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