foldkit-entity 0.14.0 → 0.16.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 +147 -5
- package/dist/collation.d.ts +33 -2
- package/dist/collation.d.ts.map +1 -0
- package/dist/conformance/index.d.ts +4 -4
- package/dist/conformance/index.d.ts.map +1 -1
- package/dist/conformance/index.js +5 -7
- package/dist/conformance/index.js.map +1 -1
- package/dist/conformance/operator.d.ts +1 -2
- package/dist/conformance/operator.d.ts.map +1 -1
- package/dist/conformance/operator.js +2 -6
- package/dist/conformance/operator.js.map +1 -1
- package/dist/conformance/relational.d.ts +17 -17
- package/dist/conformance/relational.d.ts.map +1 -1
- package/dist/conformance/relational.js +1 -3
- package/dist/conformance/relational.js.map +1 -1
- package/dist/conformance/variants.d.ts +47 -0
- package/dist/conformance/variants.d.ts.map +1 -0
- package/dist/conformance/variants.js +126 -0
- package/dist/conformance/variants.js.map +1 -0
- package/dist/context.d.ts +60 -2
- package/dist/context.d.ts.map +1 -0
- package/dist/descriptor.d.ts +33 -0
- package/dist/descriptor.d.ts.map +1 -0
- package/dist/descriptor.js +137 -0
- package/dist/descriptor.js.map +1 -0
- package/dist/entity.d.ts +231 -0
- package/dist/entity.d.ts.map +1 -0
- package/dist/entity.js +436 -0
- package/dist/entity.js.map +1 -0
- package/dist/evaluate.d.ts +204 -2
- package/dist/evaluate.d.ts.map +1 -0
- package/dist/evaluate.js +51 -7
- package/dist/evaluate.js.map +1 -1
- package/dist/expr.d.ts +915 -2
- package/dist/expr.d.ts.map +1 -0
- package/dist/expr.js +50 -10
- package/dist/expr.js.map +1 -1
- package/dist/held.d.ts +112 -2
- package/dist/held.d.ts.map +1 -0
- package/dist/held.js +13 -2
- package/dist/held.js.map +1 -1
- package/dist/ids.d.ts +8 -0
- package/dist/ids.d.ts.map +1 -0
- package/dist/ids.js +8 -0
- package/dist/ids.js.map +1 -0
- package/dist/index.d.ts +400 -6
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +113 -12
- package/dist/index.js.map +1 -0
- package/dist/invariant.d.ts +123 -2
- package/dist/invariant.d.ts.map +1 -0
- package/dist/invariant.js +236 -1
- package/dist/invariant.js.map +1 -0
- package/dist/law.d.ts +264 -2
- package/dist/law.d.ts.map +1 -0
- package/dist/law.js +1 -1
- package/dist/operators.d.ts +170 -2
- package/dist/operators.d.ts.map +1 -0
- package/dist/operators.js +3 -3
- package/dist/readFilter.d.ts +8 -2
- package/dist/readFilter.d.ts.map +1 -0
- package/dist/sets.d.ts +18 -2
- package/dist/sets.d.ts.map +1 -0
- package/dist/sets.js +1 -1
- package/dist/shape.d.ts +23 -2
- package/dist/shape.d.ts.map +1 -0
- package/dist/tested.d.ts +8 -2
- package/dist/tested.d.ts.map +1 -0
- package/dist/text.d.ts +27 -2
- package/dist/text.d.ts.map +1 -0
- package/dist/text.js +1 -1
- package/dist/variants.d.ts +72 -0
- package/dist/variants.d.ts.map +1 -0
- package/dist/variants.js +76 -0
- package/dist/variants.js.map +1 -0
- package/dist/words.d.ts +17 -2
- package/dist/words.d.ts.map +1 -0
- package/dist/write.d.ts +312 -2
- package/dist/write.d.ts.map +1 -0
- package/dist/write.js +3 -3
- package/package.json +3 -3
- package/dist/collation-BB4YTIbY.d.ts +0 -34
- package/dist/collation-BB4YTIbY.d.ts.map +0 -1
- package/dist/index-48JeXG0A.d.ts +0 -2585
- package/dist/index-48JeXG0A.d.ts.map +0 -1
- package/dist/readFilter-CWMnFRVw.d.ts +0 -9
- package/dist/readFilter-CWMnFRVw.d.ts.map +0 -1
- package/dist/shape-LAowRf9f.d.ts +0 -23
- package/dist/shape-LAowRf9f.d.ts.map +0 -1
- package/dist/src-DKhUqLoC.js +0 -731
- package/dist/src-DKhUqLoC.js.map +0 -1
- package/dist/words-a4e9o-TK.d.ts +0 -18
- package/dist/words-a4e9o-TK.d.ts.map +0 -1
package/dist/expr.d.ts
CHANGED
|
@@ -1,2 +1,915 @@
|
|
|
1
|
-
import {
|
|
2
|
-
|
|
1
|
+
import { Array, Option, Pipeable, Schema } from "effect";
|
|
2
|
+
import { AnyEntity, AnyVariantEntity, EntityField, EntityIdentity, EntityRelation, IdOf } from "./index.js";
|
|
3
|
+
import { Collation as Collation$1 } from "./collation.js";
|
|
4
|
+
import { NowExpr, ViewerExpr, ViewerPathExpr, viewer } from "./context.js";
|
|
5
|
+
import { Law as Law$1 } from "./law.js";
|
|
6
|
+
/** A constant the query was written with. */
|
|
7
|
+
export interface LiteralExpr<T> {
|
|
8
|
+
readonly _tag: 'Literal';
|
|
9
|
+
readonly value: T;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* One field of one Entity. `owner` is the Entity's identity rather than its
|
|
13
|
+
* name, so two Entities defined with the same name are not one column.
|
|
14
|
+
*/
|
|
15
|
+
export interface FieldExpr<T> {
|
|
16
|
+
readonly _tag: 'Field';
|
|
17
|
+
readonly owner: EntityIdentity<string>;
|
|
18
|
+
readonly key: string;
|
|
19
|
+
readonly schema: Schema.Codec<T, unknown>;
|
|
20
|
+
/**
|
|
21
|
+
* How it compares when ordered by, as the field declares (`Collation.of`).
|
|
22
|
+
* An id is `binary` unless it says otherwise: its order need only be total
|
|
23
|
+
* and agreed, and every order ends on it.
|
|
24
|
+
*/
|
|
25
|
+
readonly collation: Option.Option<Collation$1>;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* A value the query is given when it runs. A definition's body is built once,
|
|
29
|
+
* so inside it an input is this placeholder and never the value: there is
|
|
30
|
+
* nothing yet to branch on, and a query that wants to depend on what was passed
|
|
31
|
+
* says so with an operation over the placeholder.
|
|
32
|
+
*/
|
|
33
|
+
export interface InputExpr<T> {
|
|
34
|
+
readonly _tag: 'Input';
|
|
35
|
+
readonly key: string;
|
|
36
|
+
readonly schema: Schema.Codec<T, unknown>;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* A field as the row a write would leave holds it: what an invariant reads
|
|
40
|
+
* (`after.status`, beside `before.status` over a change). An interpreter that judges stored
|
|
41
|
+
* rows alone refuses it, as the operation `next`.
|
|
42
|
+
*/
|
|
43
|
+
export interface NextExpr<T> {
|
|
44
|
+
readonly _tag: 'Next';
|
|
45
|
+
readonly field: FieldExpr<T>;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* What an operator is, as the nodes that call it hold it: its identity, the
|
|
49
|
+
* stored form of what it takes and gives, and, for an operator defined by an
|
|
50
|
+
* expression, how to build that expression. It computes nothing itself.
|
|
51
|
+
* Identity is this object; `id` and `version` name it.
|
|
52
|
+
*/
|
|
53
|
+
export interface OperatorDescriptor {
|
|
54
|
+
readonly _tag: 'Operator';
|
|
55
|
+
readonly id: string;
|
|
56
|
+
readonly version: number;
|
|
57
|
+
readonly description: Option.Option<string>;
|
|
58
|
+
/** One schema per argument, read as the stored form. */
|
|
59
|
+
readonly input: ReadonlyArray<Schema.Top>;
|
|
60
|
+
readonly output: Schema.Top;
|
|
61
|
+
/**
|
|
62
|
+
* Builds the expression a call means, from its arguments: an operator defined
|
|
63
|
+
* by an expression. None for a primitive operator, which each interpreter
|
|
64
|
+
* implements (`Operators`).
|
|
65
|
+
*/
|
|
66
|
+
readonly definedAs: Option.Option<(...args: ReadonlyArray<Operandish>) => Operandish>;
|
|
67
|
+
/**
|
|
68
|
+
* A primitive operator's null rule. `strict`: a null argument gives null, or
|
|
69
|
+
* unknown for a predicate, and the implementation never sees one. `handled`:
|
|
70
|
+
* the implementation is given nulls and answers for them.
|
|
71
|
+
*/
|
|
72
|
+
readonly nulls: 'strict' | 'handled';
|
|
73
|
+
/**
|
|
74
|
+
* How a call compares text. `operands`: it carries the collation its collated
|
|
75
|
+
* text arguments share, so its text result compares under it. `required`: the
|
|
76
|
+
* same, refused where none is declared (it compares text itself, as
|
|
77
|
+
* `Text.startsWith` does). `none`: it carries none.
|
|
78
|
+
*/
|
|
79
|
+
readonly collation: 'none' | 'operands' | 'required';
|
|
80
|
+
/** The equations every implementation keeps (`Law`), checked where declared, tested by `Conformance.laws`. */
|
|
81
|
+
readonly laws: ReadonlyArray<Law$1>;
|
|
82
|
+
}
|
|
83
|
+
/** What an interpreter runs, as far as a check of a body needs to know. */
|
|
84
|
+
export interface OperatorTable {
|
|
85
|
+
/** Whether this table implements the operator. */
|
|
86
|
+
readonly has: (operator: OperatorDescriptor) => boolean;
|
|
87
|
+
/**
|
|
88
|
+
* The versions of the operator `id` it implements: what a refusal of a call
|
|
89
|
+
* to another version names, since a client and a server on different
|
|
90
|
+
* deploys can disagree on one.
|
|
91
|
+
*/
|
|
92
|
+
readonly versions: (id: string) => ReadonlyArray<number>;
|
|
93
|
+
}
|
|
94
|
+
/** A table implementing nothing: every primitive operator is unsupported by it. */
|
|
95
|
+
export declare const noOperators: OperatorTable;
|
|
96
|
+
/**
|
|
97
|
+
* An operator `operators` does not implement, by name, with the versions of it
|
|
98
|
+
* the table does implement: `acme.slug@2 (this table has acme.slug)`.
|
|
99
|
+
*/
|
|
100
|
+
export declare const missingName: (operator: OperatorDescriptor, operators: OperatorTable) => string;
|
|
101
|
+
/**
|
|
102
|
+
* A call of an operator whose result is a scalar. `expansion` is the
|
|
103
|
+
* expression it means, built from its arguments when it was called: an
|
|
104
|
+
* interpreter runs that, and needs nothing of its own for the operator.
|
|
105
|
+
*/
|
|
106
|
+
export interface CallExpr<T> {
|
|
107
|
+
readonly _tag: 'Call';
|
|
108
|
+
readonly operator: OperatorDescriptor;
|
|
109
|
+
readonly args: ReadonlyArray<Operandish>;
|
|
110
|
+
readonly expansion: Option.Option<Expr<T>>;
|
|
111
|
+
/** How its text result compares, from its operator's `collation` rule. */
|
|
112
|
+
readonly collation: Option.Option<Collation$1>;
|
|
113
|
+
}
|
|
114
|
+
/** A `one` relation of any Entity: what a path follows and an exists points through. */
|
|
115
|
+
export type OneRelation = EntityRelation<string, string, AnyEntity, 'one', boolean>;
|
|
116
|
+
/**
|
|
117
|
+
* A field of the row reached from the row judged by following `one`
|
|
118
|
+
* relations (`Expr.path`). A null link, or a row the reader may not see,
|
|
119
|
+
* reaches no row, and the path reads null.
|
|
120
|
+
*/
|
|
121
|
+
export interface PathExpr<T> {
|
|
122
|
+
readonly _tag: 'Path';
|
|
123
|
+
/** The relations followed, in order, the first one the judged row's own. */
|
|
124
|
+
readonly via: Array.NonEmptyReadonlyArray<OneRelation>;
|
|
125
|
+
/** What is read on the row reached: a field of the last relation's target. */
|
|
126
|
+
readonly field: FieldExpr<T>;
|
|
127
|
+
}
|
|
128
|
+
/** A typed scalar: what a comparison compares. */
|
|
129
|
+
export type Expr<T> = LiteralExpr<T> | FieldExpr<T> | InputExpr<T> | NextExpr<T> | CallExpr<T> | ViewerExpr<T> | NowExpr<T> | PathExpr<T> | ViewerPathExpr<T>;
|
|
130
|
+
/** Any scalar, for the places that hold operands without caring what they are. */
|
|
131
|
+
export type AnyExpr = Expr<unknown>;
|
|
132
|
+
/**
|
|
133
|
+
* `Expr<boolean>`, in the shape the operations that exist can actually take.
|
|
134
|
+
* The design's kernel is all boolean-valued (`eq`, `and`, `isNull`,
|
|
135
|
+
* `contains`, …), so a predicate is its own type rather than a phantom
|
|
136
|
+
* parameter on a general operation node: `Predicate` and `Expr<string>` cannot
|
|
137
|
+
* then be confused, which a structural phantom would allow. A scalar-valued
|
|
138
|
+
* operation, if one is ever needed, joins `Expr` instead.
|
|
139
|
+
*/
|
|
140
|
+
export type Predicate = EqPredicate | NullPredicate | ContainsPredicate | InPredicate | AndPredicate | OrPredicate | NotPredicate | ComparePredicate | TestPredicate | ExistsPredicate;
|
|
141
|
+
/**
|
|
142
|
+
* Some row points at the row asked about through `relation`, a `one` relation
|
|
143
|
+
* of another Entity, and holds `where` (`Expr.exists`). The row asked about is
|
|
144
|
+
* the one judged, or the one `via` reaches from it; a path that reaches none
|
|
145
|
+
* makes this unknown, as a path's field reads null. Only rows the reader may
|
|
146
|
+
* see are sought.
|
|
147
|
+
*/
|
|
148
|
+
export interface ExistsPredicate {
|
|
149
|
+
readonly _tag: 'Exists';
|
|
150
|
+
/** The relations followed to the row asked about; empty for the row judged itself. */
|
|
151
|
+
readonly via: ReadonlyArray<OneRelation>;
|
|
152
|
+
readonly relation: OneRelation;
|
|
153
|
+
/** What the pointing row must hold, over its own fields and the input. */
|
|
154
|
+
readonly where: Option.Option<Predicate>;
|
|
155
|
+
}
|
|
156
|
+
/** Two values are the same. */
|
|
157
|
+
export interface EqPredicate {
|
|
158
|
+
readonly _tag: 'Eq';
|
|
159
|
+
readonly left: Operandish;
|
|
160
|
+
readonly right: Operandish;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* Whether a value is absent. `present` says which answer absence gives, so one
|
|
164
|
+
* node covers `is null` and `is not null` rather than two that differ by a
|
|
165
|
+
* negation nothing else can express.
|
|
166
|
+
*/
|
|
167
|
+
export interface NullPredicate {
|
|
168
|
+
readonly _tag: 'Null';
|
|
169
|
+
readonly operand: AnyExpr;
|
|
170
|
+
readonly present: boolean;
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* Whether a text value contains another. Containing the empty string is
|
|
174
|
+
* everything, which is what lets a search box with nothing typed in it be the
|
|
175
|
+
* same query as one with something — see `Expr.contains`.
|
|
176
|
+
*/
|
|
177
|
+
export interface ContainsPredicate {
|
|
178
|
+
readonly _tag: 'Contains';
|
|
179
|
+
readonly value: AnyExpr;
|
|
180
|
+
readonly search: Operandish;
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Whether a value is one of a list. The list is a scalar whose value is an
|
|
184
|
+
* array: a literal, or an input (a principal's `projectIds`, a picker's
|
|
185
|
+
* chosen ids). Read as SQL's `in`: a null value is unknown, and so is no
|
|
186
|
+
* match against a list holding a null; an empty list matches nothing.
|
|
187
|
+
*/
|
|
188
|
+
export interface InPredicate {
|
|
189
|
+
readonly _tag: 'In';
|
|
190
|
+
readonly value: AnyExpr;
|
|
191
|
+
readonly among: AnyExpr;
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Every operand holds. `Query.where`'s list is already a conjunction; this is
|
|
195
|
+
* one inside something else, `or(and(a, b), c)`. Never empty, and never holding
|
|
196
|
+
* another `and`: `Expr.and` flattens one into its parent.
|
|
197
|
+
*/
|
|
198
|
+
export interface AndPredicate {
|
|
199
|
+
readonly _tag: 'And';
|
|
200
|
+
readonly operands: Array.NonEmptyReadonlyArray<Predicate>;
|
|
201
|
+
}
|
|
202
|
+
/** At least one operand holds. Never empty, and never holding another `or`. */
|
|
203
|
+
export interface OrPredicate {
|
|
204
|
+
readonly _tag: 'Or';
|
|
205
|
+
readonly operands: Array.NonEmptyReadonlyArray<Predicate>;
|
|
206
|
+
}
|
|
207
|
+
/**
|
|
208
|
+
* The operand does not hold. As SQL's `not`, an unknown stays unknown, so a row
|
|
209
|
+
* whose operand is unknown (a null compared) is matched by neither the operand
|
|
210
|
+
* nor its `not`.
|
|
211
|
+
*/
|
|
212
|
+
export interface NotPredicate {
|
|
213
|
+
readonly _tag: 'Not';
|
|
214
|
+
readonly operand: Predicate;
|
|
215
|
+
}
|
|
216
|
+
/** Which way a comparison orders its two sides: `left < right` for `lt`. */
|
|
217
|
+
export type CompareOperator = 'lt' | 'lte' | 'gt' | 'gte';
|
|
218
|
+
/**
|
|
219
|
+
* One scalar orders before, or after, the other. A null on either side is
|
|
220
|
+
* unknown. `collation` is how text compares, decided where the comparison is
|
|
221
|
+
* written (see `Expr.lt`); none for values that order intrinsically, numbers.
|
|
222
|
+
*/
|
|
223
|
+
export interface ComparePredicate {
|
|
224
|
+
readonly _tag: 'Compare';
|
|
225
|
+
readonly operator: CompareOperator;
|
|
226
|
+
readonly left: AnyExpr;
|
|
227
|
+
readonly right: AnyExpr;
|
|
228
|
+
readonly collation: Option.Option<Collation$1>;
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* A call of an operator whose result is a boolean, so it stands where any
|
|
232
|
+
* predicate does: in `and`, `or` and `not`, a guard, an invariant. `expansion`
|
|
233
|
+
* is the predicate it means, built when it was called.
|
|
234
|
+
*/
|
|
235
|
+
export interface TestPredicate {
|
|
236
|
+
readonly _tag: 'Test';
|
|
237
|
+
readonly operator: OperatorDescriptor;
|
|
238
|
+
readonly args: ReadonlyArray<Operandish>;
|
|
239
|
+
readonly expansion: Option.Option<Predicate>;
|
|
240
|
+
/** The collation it compares text under, from its operator's `collation` rule. */
|
|
241
|
+
readonly collation: Option.Option<Collation$1>;
|
|
242
|
+
}
|
|
243
|
+
/**
|
|
244
|
+
* Anything an operation can be given: a scalar, or a predicate where a boolean
|
|
245
|
+
* is wanted. `Expr.eq(Expr.isNotNull(archivedAt), input.archived)` is the
|
|
246
|
+
* second case, and it is how a query depends on an input without branching on
|
|
247
|
+
* it.
|
|
248
|
+
*/
|
|
249
|
+
export type Operandish = AnyExpr | Predicate;
|
|
250
|
+
/**
|
|
251
|
+
* A field, a `one` relation (the id it points at), a scalar already built from
|
|
252
|
+
* one, or a predicate used as a boolean.
|
|
253
|
+
*/
|
|
254
|
+
type Operand<T> = OwnOperand<T> | OneRelation;
|
|
255
|
+
/** A field, a scalar, or a predicate: what an order term takes, since no list orders by a link. */
|
|
256
|
+
type OwnOperand<T> = EntityField<string, string, Schema.Constraint> | Expr<T> | Predicate;
|
|
257
|
+
/**
|
|
258
|
+
* Type-only: the Entities a predicate's fields belong to, by name, so
|
|
259
|
+
* `Query.where` can refuse one over another Entity where it is written. Never
|
|
260
|
+
* set at run time; a predicate built without it (typed plain `Predicate`)
|
|
261
|
+
* reads as unknown and is checked at run time only.
|
|
262
|
+
*/
|
|
263
|
+
export interface Reads<Names extends string> {
|
|
264
|
+
readonly '~reads'?: Names;
|
|
265
|
+
}
|
|
266
|
+
/**
|
|
267
|
+
* The Entity names an operand reads: a field's own, a marked node's, none for
|
|
268
|
+
* a value or an input. A node with no marker (a `Predicate` typed plainly)
|
|
269
|
+
* reads as `string`, unknown.
|
|
270
|
+
*/
|
|
271
|
+
export type ReadsOf<X> = X extends EntityField<infer Name, string, Schema.Constraint> ? Name : X extends EntityRelation<infer Name, string, AnyEntity, 'one', boolean> ? Name : X extends PlainValue | {
|
|
272
|
+
readonly _tag: 'Literal' | 'Input' | 'Viewer' | 'Now';
|
|
273
|
+
} ? never : X extends {
|
|
274
|
+
readonly '~reads'?: infer Names;
|
|
275
|
+
} ? unknown extends Names ? string : Names extends string ? Names : never : never;
|
|
276
|
+
/**
|
|
277
|
+
* Nothing when a query's predicates read its own Entity, none, or one unknown
|
|
278
|
+
* to the type (checked at run time instead); else a failure naming both.
|
|
279
|
+
*/
|
|
280
|
+
type OverEntity<Names extends string, Name extends string, What extends string> = string extends Names ? unknown : [Names] extends [Name] ? unknown : Invalid<`foldkit-entity: ${What} reads ${Exclude<Names, Name>}, but the query is from ${Name}`>;
|
|
281
|
+
/** A plain value, which `Expr.eq` takes on the right only. */
|
|
282
|
+
type PlainValue = string | number | boolean | bigint | null;
|
|
283
|
+
/** A compile-time failure whose type is the sentence that says what to do. */
|
|
284
|
+
export interface Invalid<Message extends string> {
|
|
285
|
+
readonly '~invalid': Message;
|
|
286
|
+
}
|
|
287
|
+
/** What an operand is worth, so a comparison's other side is checked against it. */
|
|
288
|
+
export type ValueOf<E> = E extends EntityField<string, string, infer S> ? Schema.Schema.Type<S> : E extends EntityRelation<string, string, infer Target, 'one', infer Optional> ? IdOf<Target> | (Optional extends true ? null : never) : E extends Predicate ? boolean : E extends Expr<infer T> ? T : never;
|
|
289
|
+
/**
|
|
290
|
+
* A field or scalar whose value is text, or absent text.
|
|
291
|
+
*
|
|
292
|
+
* `Expr.contains` is a case-insensitive **text** search that compiles to
|
|
293
|
+
* `lower(column) like lower(?)`. Over a number that is nonsense which reaches
|
|
294
|
+
* the database — SQLite coerces and answers something, Postgres raises — so
|
|
295
|
+
* the operand is constrained here rather than discovered there.
|
|
296
|
+
*
|
|
297
|
+
* Null belongs in the type, because a nullable text column is a real and
|
|
298
|
+
* documented case: a null contains nothing, not even the empty string, so its
|
|
299
|
+
* rows drop out of a search that would otherwise match everything.
|
|
300
|
+
*
|
|
301
|
+
* Written as a **constraint on the type parameter** rather than as a check
|
|
302
|
+
* intersected onto the parameter (the `Invalid` idiom `foldkit-remote` uses for
|
|
303
|
+
* an unregistered descriptor). That idiom compares an already-resolved indexed
|
|
304
|
+
* access; here the check would be a conditional over the type being inferred,
|
|
305
|
+
* and inference falls back to the constraint — whose `Expr<any>` branch makes
|
|
306
|
+
* the check vacuously true, so every operand passes. A constraint cannot be
|
|
307
|
+
* defeated that way.
|
|
308
|
+
*/
|
|
309
|
+
export type TextOperand = EntityField<string, string, Schema.Constraint & Schema.Codec<string | null, any, any, any>> | Expr<string> | Expr<string | null>;
|
|
310
|
+
declare const literal: <T>(value: T) => LiteralExpr<T>;
|
|
311
|
+
/** Whether a value is a predicate, and so usable where a boolean is wanted. */
|
|
312
|
+
export declare const isPredicate: (value: unknown) => value is Predicate;
|
|
313
|
+
/**
|
|
314
|
+
* Every operation the kernel has. An interpreter declares which of them it
|
|
315
|
+
* runs, and a body needing one it does not is refused rather than answered
|
|
316
|
+
* wrongly — see `Query.unsupported`.
|
|
317
|
+
*/
|
|
318
|
+
export type Operation = 'eq' | 'isNull' | 'isNotNull' | 'contains' | 'in' | 'and' | 'or' | 'not' | 'compare' | 'next' | 'viewer' | 'now' | 'path' | 'exists';
|
|
319
|
+
/** One field an expression reads: its Entity's name and key, and the identity that owns it. */
|
|
320
|
+
export interface FieldDependency {
|
|
321
|
+
/** The owning Entity's name, for display; two Entities may share one. */
|
|
322
|
+
readonly entity: string;
|
|
323
|
+
readonly key: string;
|
|
324
|
+
/** Which Entity it is. Two defined with the same name are two entries. */
|
|
325
|
+
readonly owner: EntityIdentity<string>;
|
|
326
|
+
}
|
|
327
|
+
/** Which fields and inputs an expression reads, and which operations it uses. */
|
|
328
|
+
export interface Dependencies {
|
|
329
|
+
/** One entry per distinct field of each Entity identity. */
|
|
330
|
+
readonly fields: ReadonlyArray<FieldDependency>;
|
|
331
|
+
/** Each field read as the row a write would leave holds it (`Next`), one entry each. */
|
|
332
|
+
readonly next: ReadonlyArray<FieldDependency>;
|
|
333
|
+
/** One entry per distinct input key. */
|
|
334
|
+
readonly inputs: ReadonlyArray<string>;
|
|
335
|
+
/** One entry per distinct operation, so an interpreter can refuse what it cannot run. */
|
|
336
|
+
readonly operations: ReadonlyArray<Operation>;
|
|
337
|
+
/** Each operator it calls, once per descriptor, defined or not. */
|
|
338
|
+
readonly operators: ReadonlyArray<OperatorDescriptor>;
|
|
339
|
+
/**
|
|
340
|
+
* Each path, exists and path from the viewer, once each: what it reads lies
|
|
341
|
+
* in other rows, so none of it is in `fields`. An exists' filter's inputs,
|
|
342
|
+
* operations and operators are in the lists above.
|
|
343
|
+
*/
|
|
344
|
+
readonly reaches: ReadonlyArray<PathExpr<unknown> | ExistsPredicate | ViewerPathExpr<unknown>>;
|
|
345
|
+
}
|
|
346
|
+
/**
|
|
347
|
+
* What a query reads, with each field's role. A change to a `predicate` field
|
|
348
|
+
* can move a row into or out of the result; a change to an `order` field can
|
|
349
|
+
* move it within. A field in both is in both; `fields` is their union.
|
|
350
|
+
*/
|
|
351
|
+
export interface QueryDependencies extends Dependencies {
|
|
352
|
+
readonly predicate: ReadonlyArray<FieldDependency>;
|
|
353
|
+
readonly order: ReadonlyArray<FieldDependency>;
|
|
354
|
+
}
|
|
355
|
+
/**
|
|
356
|
+
* A field or scalar whose value orders: a number, text, a date (which orders by
|
|
357
|
+
* its encoded form), or one of those absent. A boolean does not order here.
|
|
358
|
+
* A constraint on the type parameter, as `TextOperand` is, so inference cannot
|
|
359
|
+
* fall back past it.
|
|
360
|
+
*/
|
|
361
|
+
export type OrderedOperand = EntityField<string, string, Schema.Constraint & Schema.Codec<number | string | Date | null, any, any, any>> | Expr<number> | Expr<number | null> | Expr<string> | Expr<string | null> | Expr<Date> | Expr<Date | null>;
|
|
362
|
+
/** `Expr.and` and `Expr.or`: one operand is that operand, and two or more are one node. */
|
|
363
|
+
interface Connective<Node extends Predicate> {
|
|
364
|
+
<P extends Predicate>(only: P): P;
|
|
365
|
+
<A extends Predicate, B extends Predicate, Rest extends ReadonlyArray<Predicate>>(first: A, second: B, ...rest: Rest): Node & Reads<ReadsOf<A> | ReadsOf<B> | ReadsOf<Rest[number]>>;
|
|
366
|
+
(...operands: Array.NonEmptyReadonlyArray<Predicate>): Predicate;
|
|
367
|
+
}
|
|
368
|
+
/** A schema's stored form, which is what an operator takes and gives. */
|
|
369
|
+
type StoredOf<S extends Schema.Top> = Schema.Codec.Encoded<S>;
|
|
370
|
+
/**
|
|
371
|
+
* One argument an operator may be called with: a field or scalar stored as the
|
|
372
|
+
* input's stored type, a predicate where it takes a boolean, or a plain value.
|
|
373
|
+
*/
|
|
374
|
+
export type ArgumentOf<S extends Schema.Top> = EntityField<string, string, Schema.Constraint & Schema.Codec<any, StoredOf<S>, any, any>> | Expr<StoredOf<S>> | (boolean extends StoredOf<S> ? Predicate : never) | StoredOf<S>;
|
|
375
|
+
/** What `definedAs` is handed for one argument: the argument as a node. */
|
|
376
|
+
export type ParameterOf<S extends Schema.Top> = Expr<StoredOf<S>> | (boolean extends StoredOf<S> ? Predicate : never);
|
|
377
|
+
/** A call's node: a predicate for a boolean result, a scalar for anything else. */
|
|
378
|
+
type CallOf<Out extends Schema.Top> = [StoredOf<Out>] extends [boolean] ? TestPredicate : CallExpr<StoredOf<Out>>;
|
|
379
|
+
/** What `definedAs` builds: a predicate for a boolean result, a scalar otherwise. */
|
|
380
|
+
type BodyOf<Out extends Schema.Top> = [StoredOf<Out>] extends [boolean] ? Predicate : Expr<StoredOf<Out>>;
|
|
381
|
+
/**
|
|
382
|
+
* An operator: called like a function, it builds a node that holds `descriptor`
|
|
383
|
+
* and its arguments. See `Expr.operator`.
|
|
384
|
+
*/
|
|
385
|
+
export interface Operator<In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top> {
|
|
386
|
+
<const A extends { readonly [K in keyof In]: ArgumentOf<In[K]>; }>(...args: A): CallOf<Out> & Reads<ReadsOf<A[number]>>;
|
|
387
|
+
/**
|
|
388
|
+
* A call comparing text under the collation given, rather than its text
|
|
389
|
+
* arguments' declared one: for an operator whose `collation` is `operands`
|
|
390
|
+
* or `required`, as `Expr.lt(field, value, { collation })` is.
|
|
391
|
+
*/
|
|
392
|
+
<const A extends { readonly [K in keyof In]: ArgumentOf<In[K]>; }>(...args: [...A, CallOptions]): CallOf<Out> & Reads<ReadsOf<A[number]>>;
|
|
393
|
+
readonly descriptor: OperatorDescriptor;
|
|
394
|
+
}
|
|
395
|
+
/** What a call may say past its arguments. */
|
|
396
|
+
export interface CallOptions {
|
|
397
|
+
/** The collation it compares text under, in place of its arguments' declared one. */
|
|
398
|
+
readonly collation: Collation$1;
|
|
399
|
+
}
|
|
400
|
+
/** `Expr.path`'s two starts: a relation of the judged row, or the viewer's row. */
|
|
401
|
+
interface PathOf {
|
|
402
|
+
<Owner extends string, Target extends AnyEntity, E extends PathEnd<Target['name']>>(relation: EntityRelation<Owner, string, Target, 'one', boolean>, end: E): (E extends ExistsPredicate ? ExistsPredicate : PathExpr<ValueOf<E> | null>) & Reads<Owner>;
|
|
403
|
+
<Name extends string, E extends Exclude<PathEnd<Name>, ExistsPredicate>>(viewer: ViewerExpr<any, Name>, end: E): ViewerPathExpr<ValueOf<E> | null>;
|
|
404
|
+
}
|
|
405
|
+
/**
|
|
406
|
+
* The most relations one path follows. Each is a subquery in SQL and a lookup
|
|
407
|
+
* in memory; the deepest rule a real app here writes follows two.
|
|
408
|
+
*/
|
|
409
|
+
export declare const maxPathLength = 4;
|
|
410
|
+
/** What a path may end at on a row of `Name`: a field, a further path, or an exists. */
|
|
411
|
+
export type PathEnd<Name extends string> = EntityField<Name, string, Schema.Constraint> | (PathExpr<any> & Reads<Name>) | (ExistsPredicate & Reads<Name>);
|
|
412
|
+
/** The case names of an Entity with variants. */
|
|
413
|
+
type TagOf<E extends AnyVariantEntity> = keyof E['variants']['cases'] & string;
|
|
414
|
+
/** A case's schemas, `_tag` aside. */
|
|
415
|
+
type CaseSchemas<E extends AnyVariantEntity, T extends string> = Omit<E['variants']['cases'][T]['fields'], '_tag'>;
|
|
416
|
+
/** A case's fields as `Expr.is` hands them out: typed as the case holds them, never null. */
|
|
417
|
+
export type CaseFields<E extends AnyVariantEntity, T extends string> = { readonly [K in keyof CaseSchemas<E, T> & string]: EntityField<E['name'], K, CaseSchemas<E, T>[K]>; };
|
|
418
|
+
/** A case's fields as read through a `one` relation to its Entity: a path to each. */
|
|
419
|
+
export type CasePaths<Owner extends string, E extends AnyVariantEntity, T extends string> = { readonly [K in keyof CaseSchemas<E, T> & string]: PathExpr<Schema.Schema.Type<CaseSchemas<E, T>[K]>> & Reads<Owner>; };
|
|
420
|
+
/** `Expr.is`'s two subjects: the row judged, or the row a `one` relation of it reaches. */
|
|
421
|
+
interface IsOf {
|
|
422
|
+
<E extends AnyVariantEntity, const T extends TagOf<E>, P extends Predicate = never>(entity: E, tag: T, build?: (fields: CaseFields<E, T>) => P): Predicate & Reads<E['name'] | ReadsOf<P>>;
|
|
423
|
+
<Owner extends string, Target extends AnyVariantEntity, const T extends TagOf<Target>, P extends Predicate = never>(relation: EntityRelation<Owner, string, Target, 'one', boolean>, tag: T, build?: (fields: CasePaths<Owner, Target, T>) => P): Predicate & Reads<Owner | ReadsOf<P>>;
|
|
424
|
+
}
|
|
425
|
+
/** `Expr.field`: an Entity field, or an expression refused with what to write instead. */
|
|
426
|
+
interface FieldOf {
|
|
427
|
+
<Name extends string, Key extends string, S extends Schema.Constraint>(field: EntityField<Name, Key, S>): FieldExpr<Schema.Schema.Type<S>> & Reads<Name>;
|
|
428
|
+
(expression: Expr<unknown> & Invalid<'foldkit-entity: Expr.field takes an Entity field (Post.fields.title); before.x and after.x are expressions already, so compare them as they are'>): never;
|
|
429
|
+
}
|
|
430
|
+
interface NextOf {
|
|
431
|
+
<Name extends string, Key extends string, S extends Schema.Constraint>(field: EntityField<Name, Key, S>): NextExpr<Schema.Schema.Type<S>> & Reads<Name>;
|
|
432
|
+
<Name extends string, Key extends string, Optional extends boolean>(relation: EntityRelation<Name, Key, AnyEntity, 'one', Optional>): NextExpr<Optional extends true ? string | null : string> & Reads<Name>;
|
|
433
|
+
}
|
|
434
|
+
export declare const Expr: {
|
|
435
|
+
/**
|
|
436
|
+
* An operator, defined by what a call of it means: `definedAs` builds that
|
|
437
|
+
* expression from the call's arguments, once per call, and every interpreter
|
|
438
|
+
* runs it, so the operator needs no implementation anywhere. What it adds is
|
|
439
|
+
* a name: a query, a guard and an invariant that mean the same thing say so,
|
|
440
|
+
* and print it.
|
|
441
|
+
*
|
|
442
|
+
* ```ts
|
|
443
|
+
* const published = Expr.operator('cms.published', {
|
|
444
|
+
* input: [Schema.Unknown],
|
|
445
|
+
* output: Schema.Boolean,
|
|
446
|
+
* definedAs: publishedAt => Expr.isNotNull(publishedAt),
|
|
447
|
+
* })
|
|
448
|
+
* Query.where(published(Post.fields.publishedAt))
|
|
449
|
+
* ```
|
|
450
|
+
*
|
|
451
|
+
* Arguments are checked by their stored form: a field, scalar or plain value
|
|
452
|
+
* of the input's stored type, or a predicate where it takes a boolean. A
|
|
453
|
+
* boolean output makes a call a predicate. `definedAs` may read only what its
|
|
454
|
+
* arguments hold: a field or input it closes over instead is refused when
|
|
455
|
+
* called, since nothing asking what the call reads would see it. The id is
|
|
456
|
+
* namespaced (`cms.published`); `foldkit.` is reserved; `version` (default 1)
|
|
457
|
+
* changes when what it means does.
|
|
458
|
+
*
|
|
459
|
+
* **Without `definedAs` it is primitive**: each interpreter implements it
|
|
460
|
+
* (`Operators.implement` in memory), and one without an implementation
|
|
461
|
+
* refuses the body by the operator's id. `nulls` (default `strict`: a null
|
|
462
|
+
* argument gives null, the implementation never sees one) and `collation`
|
|
463
|
+
* (`operands`: a text result carries its text arguments' shared collation;
|
|
464
|
+
* `required`: it compares text itself and needs one) are a primitive
|
|
465
|
+
* operator's; a defined one means its body for both.
|
|
466
|
+
*/
|
|
467
|
+
operator: <const In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(id: string, options: {
|
|
468
|
+
readonly input: In;
|
|
469
|
+
readonly output: Out;
|
|
470
|
+
readonly version?: number | undefined;
|
|
471
|
+
readonly description?: string | undefined;
|
|
472
|
+
/** Equations every implementation keeps (`Law.commutative`, `Law.identity('')`, …). */
|
|
473
|
+
readonly laws?: ReadonlyArray<Law$1> | undefined;
|
|
474
|
+
} & ({
|
|
475
|
+
readonly definedAs: (...args: { readonly [K in keyof In]: ParameterOf<In[K]>; }) => BodyOf<Out>;
|
|
476
|
+
readonly nulls?: undefined;
|
|
477
|
+
readonly collation?: undefined;
|
|
478
|
+
} | {
|
|
479
|
+
readonly definedAs?: undefined;
|
|
480
|
+
readonly nulls?: OperatorDescriptor['nulls'] | undefined;
|
|
481
|
+
readonly collation?: OperatorDescriptor['collation'] | undefined;
|
|
482
|
+
})) => Operator<In, Out>;
|
|
483
|
+
/**
|
|
484
|
+
* The predicate or scalar (an order term's, say) with every call of a
|
|
485
|
+
* defined operator replaced by what it means, deeply. An interpreter that
|
|
486
|
+
* compiles a body expands it first, and compiles exactly what was written
|
|
487
|
+
* out. A call with no definition stays, for the interpreter to run or refuse
|
|
488
|
+
* by name.
|
|
489
|
+
*/
|
|
490
|
+
/**
|
|
491
|
+
* Whether a constant written in these expressions is one no two backends
|
|
492
|
+
* agree on, text holding a NUL or NaN, or a list holding one: SQL refuses
|
|
493
|
+
* such a parameter wherever it compiles, so an interpreter refuses the run,
|
|
494
|
+
* not one row.
|
|
495
|
+
*/
|
|
496
|
+
givesUnportable: (...nodes: ReadonlyArray<AnyExpr | Predicate>) => boolean;
|
|
497
|
+
expanded: <N extends Predicate | AnyExpr>(node: N) => N extends Predicate ? Predicate : AnyExpr;
|
|
498
|
+
/**
|
|
499
|
+
* What these expressions need that an interpreter lacks, as `Query.unsupported`
|
|
500
|
+
* says it for a query: each kernel operation `supported` does not list, then
|
|
501
|
+
* each primitive operator `operators` does not implement, by name (`id`, or
|
|
502
|
+
* `id@version` past the first). For anything holding expressions that is not a
|
|
503
|
+
* query: a guard's rule, an invariant, a write's `when`.
|
|
504
|
+
*/
|
|
505
|
+
unsupported: (nodes: ReadonlyArray<AnyExpr | Predicate | Ordering>, interpreter: {
|
|
506
|
+
readonly operations: ReadonlyArray<Operation>;
|
|
507
|
+
readonly operators: OperatorTable;
|
|
508
|
+
}) => ReadonlyArray<string>;
|
|
509
|
+
/** A constant. Comparisons coerce a plain value, so this is rarely written. */
|
|
510
|
+
literal: typeof literal;
|
|
511
|
+
/**
|
|
512
|
+
* A value the query is given when it runs. A definition builds these from its
|
|
513
|
+
* `Input` schema; written by hand only when constructing a body directly.
|
|
514
|
+
*/
|
|
515
|
+
input: <T>(key: string, schema: Schema.Codec<T, unknown>) => InputExpr<T>;
|
|
516
|
+
/**
|
|
517
|
+
* A field, or a `one` relation as the id it points at, as the row a write
|
|
518
|
+
* would leave holds it: what `Entity.invariant`'s builder hands out as `after`.
|
|
519
|
+
*/
|
|
520
|
+
next: NextOf;
|
|
521
|
+
/**
|
|
522
|
+
* One field of one Entity, as a scalar. An expression is one already: an
|
|
523
|
+
* invariant's `before.x` and `after.x` compare as they are, so wrapping one
|
|
524
|
+
* is refused with that sentence.
|
|
525
|
+
*/
|
|
526
|
+
field: FieldOf;
|
|
527
|
+
/**
|
|
528
|
+
* What the row reached through a `one` relation holds: a field of it, a
|
|
529
|
+
* further path from it, or an exists asked of it. The first relation is the
|
|
530
|
+
* judged row's own.
|
|
531
|
+
*
|
|
532
|
+
* ```ts
|
|
533
|
+
* Expr.eq(Expr.path(Post.relations.author, User.fields.handle), input.handle)
|
|
534
|
+
* Expr.path(Note.relations.project, Expr.path(Project.relations.org, Org.fields.plan))
|
|
535
|
+
* ```
|
|
536
|
+
*
|
|
537
|
+
* A null link, or a row the reader may not see, reaches no row: the field
|
|
538
|
+
* reads null, and an exists at the end is unknown, as SQL's scalar subquery
|
|
539
|
+
* is. At most `maxPathLength` relations.
|
|
540
|
+
*/
|
|
541
|
+
path: PathOf;
|
|
542
|
+
/**
|
|
543
|
+
* Some row points at this one through `relation`, a `one` relation of
|
|
544
|
+
* another Entity, and holds `where`, a predicate over that row's own fields
|
|
545
|
+
* and the input:
|
|
546
|
+
*
|
|
547
|
+
* ```ts
|
|
548
|
+
* // Posts whose author the reader follows.
|
|
549
|
+
* Expr.path(Post.relations.author,
|
|
550
|
+
* Expr.exists(Follow.relations.followee, Expr.eq(Follow.fields.followerId, input.me)))
|
|
551
|
+
* ```
|
|
552
|
+
*
|
|
553
|
+
* Only rows the reader may see are sought. Never unknown in SQL; in memory,
|
|
554
|
+
* unknown when no held row holds and the holder may lack one that would.
|
|
555
|
+
*/
|
|
556
|
+
exists: <Owner extends string, Target extends AnyEntity, W extends Predicate & Reads<Owner> = never>(relation: EntityRelation<Owner, string, Target, 'one', boolean>, where?: W) => ExistsPredicate & Reads<Target['name']>;
|
|
557
|
+
/**
|
|
558
|
+
* The row is of case `tag` of an Entity declared with
|
|
559
|
+
* `Entity.defineVariants`, and holds what `build` asks of that case's
|
|
560
|
+
* fields, each typed as the case holds it:
|
|
561
|
+
*
|
|
562
|
+
* ```ts
|
|
563
|
+
* Expr.is(Domain, 'Unconfirmed')
|
|
564
|
+
* Expr.is(Domain, 'Available', ({ price }) => Expr.lt(price, 20))
|
|
565
|
+
* // Through a one relation, the row it reaches.
|
|
566
|
+
* Expr.is(Order.relations.domain, 'Available', ({ price }) => Expr.lt(price, 20))
|
|
567
|
+
* ```
|
|
568
|
+
*
|
|
569
|
+
* It is `_tag = tag` and the predicate, so a row of another case is false,
|
|
570
|
+
* never unknown, and `Expr.not` of it holds there. Through a relation, a null
|
|
571
|
+
* link reaches no row and the test is unknown, as a path's field reads null.
|
|
572
|
+
* Use the fields inside `build`: outside it a case's field is the stored
|
|
573
|
+
* column, null on rows of other cases.
|
|
574
|
+
*/
|
|
575
|
+
is: IsOf;
|
|
576
|
+
/**
|
|
577
|
+
* Whoever asks, as a row of `entity`: `Expr.eq(Like.fields.userId,
|
|
578
|
+
* Expr.viewer(User))`. Shaped as a `one` relation to `entity`. Its value is
|
|
579
|
+
* the row's id, and null for a visitor or a viewer of another Entity, so a
|
|
580
|
+
* comparison with it holds of no row. A server reads it from
|
|
581
|
+
* `RemoteServer.make`'s `viewer`, a client from `Remote.make`'s.
|
|
582
|
+
*/
|
|
583
|
+
viewer: typeof viewer;
|
|
584
|
+
/**
|
|
585
|
+
* The time of the write, in milliseconds since the epoch, as a number field
|
|
586
|
+
* stores it. A server reads its clock. A client judging a list has no
|
|
587
|
+
* reading of the time the server judged it at, so such a list is the
|
|
588
|
+
* server's to say.
|
|
589
|
+
*/
|
|
590
|
+
now: NowExpr<number>;
|
|
591
|
+
/**
|
|
592
|
+
* Two scalars are the same value: a field (or an expression) on the left,
|
|
593
|
+
* and the value on the right, typed from it. Fields and plain values are
|
|
594
|
+
* coerced, so the common form reads as it means:
|
|
595
|
+
*
|
|
596
|
+
* ```ts
|
|
597
|
+
* Expr.eq(Post.fields.slug, input.slug)
|
|
598
|
+
* Expr.eq(Post.fields.status, 'active')
|
|
599
|
+
* ```
|
|
600
|
+
*/
|
|
601
|
+
eq: <L extends Operand<any> | PlainValue, R extends (L extends PlainValue ? Invalid<'foldkit-entity: Expr.eq takes the field on the left and the value on the right'> : ValueOf<L> | Expr<ValueOf<L>> | PathExpr<ValueOf<L> | null> | ViewerPathExpr<ValueOf<L> | null> | (boolean extends ValueOf<L> ? Predicate : never))>(left: L, right: R) => EqPredicate & Reads<ReadsOf<L> | ReadsOf<R>>;
|
|
602
|
+
/**
|
|
603
|
+
* Whether a field holds no value. Its opposite is `isNotNull`; both are the
|
|
604
|
+
* one node, since a query asks which of the two it means, and `is not null`
|
|
605
|
+
* has no unknown for a `not` to keep.
|
|
606
|
+
*/
|
|
607
|
+
isNull: <L extends Operand<any>>(operand: L) => NullPredicate & Reads<ReadsOf<L>>;
|
|
608
|
+
/** Whether a field holds a value. */
|
|
609
|
+
isNotNull: <L extends Operand<any>>(operand: L) => NullPredicate & Reads<ReadsOf<L>>;
|
|
610
|
+
/**
|
|
611
|
+
* Whether a text value contains `search`, anywhere in it. Containing the
|
|
612
|
+
* empty string is everything, so a search box with nothing typed in it is the
|
|
613
|
+
* same query as one with something — no branch, and no second query.
|
|
614
|
+
*
|
|
615
|
+
* **Case-insensitive**, which is what a search means, and which has to be
|
|
616
|
+
* said rather than left to the interpreter: SQLite's `like` ignores case and
|
|
617
|
+
* Postgres's does not, so a body that left it open would mean two things.
|
|
618
|
+
* Folding is ASCII-only, because that is what `lower` does in SQLite without
|
|
619
|
+
* ICU.
|
|
620
|
+
*
|
|
621
|
+
* **Over a column that can be null this is not the same as no filter.** A
|
|
622
|
+
* null contains nothing, not even the empty string, so its rows drop out. A
|
|
623
|
+
* nullable column that should match everything on an empty search says so:
|
|
624
|
+
* `Expr.or(Expr.isNull(field), Expr.contains(field, input.search))`.
|
|
625
|
+
*/
|
|
626
|
+
contains: <L extends TextOperand>(value: L, search: string | LiteralExpr<string> | InputExpr<string> | InputExpr<string | null>) => ContainsPredicate & Reads<ReadsOf<L>>;
|
|
627
|
+
/**
|
|
628
|
+
* Whether a value is one of `among`: a list written out, or an input whose
|
|
629
|
+
* value is one. Each element is compared as `eq` compares.
|
|
630
|
+
*
|
|
631
|
+
* ```ts
|
|
632
|
+
* Expr.in(Todo.fields.projectId, input.projectIds)
|
|
633
|
+
* Expr.in(Todo.fields.status, ['open', 'blocked'])
|
|
634
|
+
* ```
|
|
635
|
+
*
|
|
636
|
+
* As SQL's `in`: a null value is unknown, as is no match against a list
|
|
637
|
+
* holding a null, and an empty list matches no row. A list written out is
|
|
638
|
+
* copied, so changing the array afterwards does not change the query.
|
|
639
|
+
*/
|
|
640
|
+
in: <L extends Operand<any>>(value: L, among: ReadonlyArray<ValueOf<L>> | Expr<ReadonlyArray<ValueOf<L>>>) => InPredicate & Reads<ReadsOf<L>>;
|
|
641
|
+
/**
|
|
642
|
+
* `left` orders before `right`. Numbers compare as numbers; text compares
|
|
643
|
+
* under a collation, the one given or the field's declared one, which must be
|
|
644
|
+
* `binary` or `asciiFold` (so every backend agrees), and text needs a field on
|
|
645
|
+
* one side. A date compares by its encoded form: as text when it is stored as
|
|
646
|
+
* an ISO string, so its field declares `Collation.binary`. A null on either
|
|
647
|
+
* side is unknown, so the row is matched by neither this nor its `not`.
|
|
648
|
+
*
|
|
649
|
+
* ```ts
|
|
650
|
+
* Expr.lt(fields.cents, 1000)
|
|
651
|
+
* Expr.and(Expr.gte(fields.at, input.from), Expr.lt(fields.at, input.until))
|
|
652
|
+
* ```
|
|
653
|
+
*/
|
|
654
|
+
lt: <L extends OrderedOperand, R extends ValueOf<L> | Expr<ValueOf<L>>>(left: L, right: R, options?: {
|
|
655
|
+
readonly collation?: Collation$1 | undefined;
|
|
656
|
+
}) => ComparePredicate & Reads<ReadsOf<L> | ReadsOf<R>>;
|
|
657
|
+
/** `left` orders before `right`, or with it; see `Expr.lt`. */
|
|
658
|
+
lte: <L extends OrderedOperand, R extends ValueOf<L> | Expr<ValueOf<L>>>(left: L, right: R, options?: {
|
|
659
|
+
readonly collation?: Collation$1 | undefined;
|
|
660
|
+
}) => ComparePredicate & Reads<ReadsOf<L> | ReadsOf<R>>;
|
|
661
|
+
/** `left` orders after `right`; see `Expr.lt`. */
|
|
662
|
+
gt: <L extends OrderedOperand, R extends ValueOf<L> | Expr<ValueOf<L>>>(left: L, right: R, options?: {
|
|
663
|
+
readonly collation?: Collation$1 | undefined;
|
|
664
|
+
}) => ComparePredicate & Reads<ReadsOf<L> | ReadsOf<R>>;
|
|
665
|
+
/** `left` orders after `right`, or with it; see `Expr.lt`. */
|
|
666
|
+
gte: <L extends OrderedOperand, R extends ValueOf<L> | Expr<ValueOf<L>>>(left: L, right: R, options?: {
|
|
667
|
+
readonly collation?: Collation$1 | undefined;
|
|
668
|
+
}) => ComparePredicate & Reads<ReadsOf<L> | ReadsOf<R>>;
|
|
669
|
+
/**
|
|
670
|
+
* Every operand holds, as one predicate to place inside another: `where`'s
|
|
671
|
+
* list is already a conjunction, so this is for `or(and(a, b), c)`.
|
|
672
|
+
* Unknown as SQL's `and` is: false wins over unknown, which wins over true.
|
|
673
|
+
* Needs an operand; a list built at run time is checked non-empty first
|
|
674
|
+
* (`Array.isReadonlyArrayNonEmpty`), since an empty `and` would match every row.
|
|
675
|
+
*/
|
|
676
|
+
and: Connective<AndPredicate>;
|
|
677
|
+
/**
|
|
678
|
+
* At least one operand holds:
|
|
679
|
+
*
|
|
680
|
+
* ```ts
|
|
681
|
+
* Expr.or(Expr.contains(fields.description, input.search), Expr.contains(fields.upc, input.search))
|
|
682
|
+
* ```
|
|
683
|
+
*
|
|
684
|
+
* Unknown as SQL's `or` is: true wins over unknown, which wins over false.
|
|
685
|
+
* Needs an operand, since an empty `or` would match no row.
|
|
686
|
+
*/
|
|
687
|
+
or: Connective<OrPredicate>;
|
|
688
|
+
/**
|
|
689
|
+
* The operand does not hold. **A null is matched by neither side**:
|
|
690
|
+
* `not(eq(status, 'draft'))` leaves out a row whose `status` is null, since
|
|
691
|
+
* `null = 'draft'` is unknown and so is its `not`, as in SQL. "Everything
|
|
692
|
+
* but drafts" over a nullable column is
|
|
693
|
+
* `Expr.or(Expr.isNull(status), Expr.not(Expr.eq(status, 'draft')))`.
|
|
694
|
+
*/
|
|
695
|
+
not: <P extends Predicate>(operand: P) => NotPredicate & Reads<ReadsOf<P>>;
|
|
696
|
+
/**
|
|
697
|
+
* A filter that applies only when its input is given: `or(isNull($x), …)`,
|
|
698
|
+
* with the predicate built from the input as never null.
|
|
699
|
+
*
|
|
700
|
+
* ```ts
|
|
701
|
+
* // Every product, or those of the chosen status.
|
|
702
|
+
* Expr.whenGiven(input.status, status => Expr.eq(fields.status, status))
|
|
703
|
+
* ```
|
|
704
|
+
*
|
|
705
|
+
* An interpreter that runs per request, as the Drizzle compiler does, decides
|
|
706
|
+
* `isNull($x)` before writing SQL, so this compiles to `true`, which filters
|
|
707
|
+
* nothing, or to the predicate alone.
|
|
708
|
+
*/
|
|
709
|
+
whenGiven: <T, P extends Predicate>(input: InputExpr<T>, build: (given: InputExpr<NonNullable<T>>) => P) => Predicate & Reads<ReadsOf<P>>;
|
|
710
|
+
/** An expression as readable text; see `showExpr` for what it is and is not. */
|
|
711
|
+
show: (node: Operandish) => string;
|
|
712
|
+
/**
|
|
713
|
+
* The predicate with each field after a write (`Next`) that `values` names,
|
|
714
|
+
* by key, read as that value: how an invariant is judged where the
|
|
715
|
+
* write's new values are known. A field it does not name stays `Next`, for
|
|
716
|
+
* the interpreter to read as the row after holds it.
|
|
717
|
+
*/
|
|
718
|
+
substituteNext: (predicate: Predicate, values: Readonly<Record<string, unknown>>) => Predicate;
|
|
719
|
+
};
|
|
720
|
+
/** One term of an ordering: a scalar and the direction to read it in. */
|
|
721
|
+
export interface OrderTerm {
|
|
722
|
+
readonly _tag: 'Term';
|
|
723
|
+
readonly direction: 'asc' | 'desc';
|
|
724
|
+
readonly expr: AnyExpr;
|
|
725
|
+
/**
|
|
726
|
+
* Where rows without a value go, in the term's own direction. Databases
|
|
727
|
+
* disagree when it is left unsaid (Postgres puts them last ascending, SQLite
|
|
728
|
+
* first), so it is always said: last ascending and first descending unless
|
|
729
|
+
* a term asks otherwise, which is Postgres's.
|
|
730
|
+
*/
|
|
731
|
+
readonly nulls: 'first' | 'last';
|
|
732
|
+
/**
|
|
733
|
+
* How text compares, when the term orders text: the term's own, or its
|
|
734
|
+
* field's. None leaves it to the backend, which a client cannot match.
|
|
735
|
+
*/
|
|
736
|
+
readonly collation: Option.Option<Collation$1>;
|
|
737
|
+
}
|
|
738
|
+
/** What a term may say besides its operand. */
|
|
739
|
+
export interface TermOptions {
|
|
740
|
+
readonly nulls?: 'first' | 'last' | undefined;
|
|
741
|
+
/** Overrides the field's declared collation for this term. */
|
|
742
|
+
readonly collation?: Collation$1 | undefined;
|
|
743
|
+
}
|
|
744
|
+
/** How a list is sorted, as its input holds it: one of its named orders, which way, or none. */
|
|
745
|
+
export type ChosenSort<By extends string> = {
|
|
746
|
+
readonly by: By;
|
|
747
|
+
readonly direction: 'asc' | 'desc';
|
|
748
|
+
} | null;
|
|
749
|
+
/**
|
|
750
|
+
* An ordering the input chooses: one of several named fields, which way, or
|
|
751
|
+
* none. It is how a list sorts by what its reader picked, said in the body, so
|
|
752
|
+
* the server and the client read one declaration of what each name means.
|
|
753
|
+
*/
|
|
754
|
+
export interface ChosenOrder {
|
|
755
|
+
readonly _tag: 'Chosen';
|
|
756
|
+
readonly sort: InputExpr<ChosenSort<string>>;
|
|
757
|
+
readonly choices: Readonly<Record<string, FieldExpr<unknown> | CallExpr<unknown>>>;
|
|
758
|
+
}
|
|
759
|
+
/** One entry of a body's ordering: fixed, or chosen by the input. */
|
|
760
|
+
export type Ordering = OrderTerm | ChosenOrder;
|
|
761
|
+
export declare const Order: {
|
|
762
|
+
/** Smallest first; rows without a value last, unless `nulls` says first. */
|
|
763
|
+
asc: <E extends OwnOperand<any>>(expr: E, options?: TermOptions) => OrderTerm & Reads<ReadsOf<E>>;
|
|
764
|
+
/** Largest first; rows without a value first, unless `nulls` says last. */
|
|
765
|
+
desc: <E extends OwnOperand<any>>(expr: E, options?: TermOptions) => OrderTerm & Reads<ReadsOf<E>>;
|
|
766
|
+
/**
|
|
767
|
+
* The order the input names, among `choices`: every name the sort can hold
|
|
768
|
+
* maps to a field or a call that orders, so a name left out is a type error
|
|
769
|
+
* here, not a query that silently orders by nothing. A `null` sort chooses none, and the terms after
|
|
770
|
+
* it decide.
|
|
771
|
+
*
|
|
772
|
+
* ```ts
|
|
773
|
+
* Query.orderBy(Order.chosen(input.sort, { title: Post.fields.title }))
|
|
774
|
+
* ```
|
|
775
|
+
*/
|
|
776
|
+
chosen: <By extends string, const Choices extends { readonly [K in By]: OwnOperand<any>; }>(sort: InputExpr<ChosenSort<By>>, choices: Choices) => ChosenOrder & Reads<ReadsOf<Choices[keyof Choices]>>;
|
|
777
|
+
};
|
|
778
|
+
/**
|
|
779
|
+
* Whether a client can order rows the way the server does, for one input: the
|
|
780
|
+
* answer `Query.placement` gives, and the reason when it cannot.
|
|
781
|
+
*/
|
|
782
|
+
export type Placement = {
|
|
783
|
+
readonly _tag: 'Placeable';
|
|
784
|
+
} | {
|
|
785
|
+
readonly _tag: 'NotPlaceable';
|
|
786
|
+
readonly reason: string;
|
|
787
|
+
};
|
|
788
|
+
/**
|
|
789
|
+
* What an expression reads and uses, for the planner and for an interpreter
|
|
790
|
+
* deciding whether it can run this query at all. Distinct entries only, in the
|
|
791
|
+
* order first seen, so the answer is stable enough to assert on.
|
|
792
|
+
*/
|
|
793
|
+
export declare const dependenciesOf: (...nodes: ReadonlyArray<AnyExpr | Predicate | Ordering>) => Dependencies;
|
|
794
|
+
/**
|
|
795
|
+
* Which rows a query is about, as a value: an Entity to read, the predicates
|
|
796
|
+
* every row must satisfy, and the order to read them in. It says nothing about
|
|
797
|
+
* which fields to return — that is a Selection — and nothing about pagination,
|
|
798
|
+
* liveness, or whether absence is an error, which belong to the consumer's read
|
|
799
|
+
* rather than to the relation.
|
|
800
|
+
*
|
|
801
|
+
* Composing one performs no work. `Query.from(Post)` names no table and opens
|
|
802
|
+
* no connection; an interpreter turns the value into a query when something
|
|
803
|
+
* asks it to.
|
|
804
|
+
*/
|
|
805
|
+
export interface Query<E extends AnyEntity> extends Pipeable.Pipeable {
|
|
806
|
+
readonly _tag: 'Query';
|
|
807
|
+
readonly entity: E;
|
|
808
|
+
/**
|
|
809
|
+
* Every predicate holds: the list *is* the conjunction. Keeping it a list
|
|
810
|
+
* rather than folding it into one `and` is what makes each `where` a reusable
|
|
811
|
+
* fragment, and it means no `Expr.and` exists until a query needs a
|
|
812
|
+
* conjunction nested inside something else.
|
|
813
|
+
*/
|
|
814
|
+
readonly where: ReadonlyArray<Predicate>;
|
|
815
|
+
/** In order of significance; a later `orderBy` appends less significant terms. */
|
|
816
|
+
readonly orderBy: ReadonlyArray<Ordering>;
|
|
817
|
+
}
|
|
818
|
+
/** A `Query` over any Entity, for the places that hold one without caring which. */
|
|
819
|
+
export type AnyQuery = Query<AnyEntity>;
|
|
820
|
+
/**
|
|
821
|
+
* The most nodes a query's predicates may hold once every shared node is
|
|
822
|
+
* counted on each path that reaches it. Interpreters read a predicate as a
|
|
823
|
+
* tree: `evaluate` once per row, and the SQL compiler into text that repeats a
|
|
824
|
+
* shared operand wherever it appears. So `eq(n, n)` nested thirty deep is
|
|
825
|
+
* thirty-one objects and a billion nodes of work. Real queries are tens.
|
|
826
|
+
*/
|
|
827
|
+
export declare const maxQueryNodes = 1000;
|
|
828
|
+
export declare const Query: {
|
|
829
|
+
/** Every row of an Entity: the query each transformation narrows. */
|
|
830
|
+
from: <E extends AnyEntity>(entity: E) => Query<E>;
|
|
831
|
+
/**
|
|
832
|
+
* Narrows to the rows the predicate holds for. Two `where`s conjoin — the
|
|
833
|
+
* second never replaces the first — so a fragment can be written once and
|
|
834
|
+
* piped into any query over the same Entity:
|
|
835
|
+
*
|
|
836
|
+
* ```ts
|
|
837
|
+
* const published = Query.where(Expr.eq(Post.fields.published, true))
|
|
838
|
+
* Query.from(Post).pipe(published, Query.where(byTitle))
|
|
839
|
+
* ```
|
|
840
|
+
*/
|
|
841
|
+
where: <const P extends ReadonlyArray<Predicate>>(...predicates: P) => <E extends AnyEntity>(self: Query<E> & OverEntity<ReadsOf<P[number]>, E['name'], 'a predicate'>) => Query<E>;
|
|
842
|
+
/**
|
|
843
|
+
* Reads the rows in this order. Two `orderBy`s append, so an earlier term
|
|
844
|
+
* stays the more significant one and a later call adds a tie-breaker rather
|
|
845
|
+
* than silently winning.
|
|
846
|
+
*/
|
|
847
|
+
orderBy: <const T extends ReadonlyArray<Ordering>>(...terms: T) => <E extends AnyEntity>(self: Query<E> & OverEntity<ReadsOf<T[number]>, E['name'], 'an ordering term'>) => Query<E>;
|
|
848
|
+
/**
|
|
849
|
+
* The fixed terms this query orders by for one input: each chosen order
|
|
850
|
+
* resolved to the field its input names, or to nothing for a `null` sort,
|
|
851
|
+
* and the Entity's id last, ascending, unless the terms already read it. So
|
|
852
|
+
* the order is total, and every interpreter breaks ties the same way: one
|
|
853
|
+
* that broke them its own way would place rows a step apart from another.
|
|
854
|
+
*/
|
|
855
|
+
orderFor: (self: AnyQuery, input: Readonly<Record<string, unknown>>) => ReadonlyArray<OrderTerm>;
|
|
856
|
+
/**
|
|
857
|
+
* Whether a client can order this query's rows exactly as the server does,
|
|
858
|
+
* for one input: every term over a number or a boolean (a row may lack it), or over text with a
|
|
859
|
+
* portable collation (`binary`, `asciiFold`), or a call whose primitive
|
|
860
|
+
* operators the client's table (`operators`; none when not given) runs. A
|
|
861
|
+
* body that names no order leaves it to the server, and is never placeable.
|
|
862
|
+
*/
|
|
863
|
+
placement: (self: AnyQuery, input: Readonly<Record<string, unknown>>, options?: {
|
|
864
|
+
readonly operators?: OperatorTable | undefined;
|
|
865
|
+
}) => Placement;
|
|
866
|
+
/**
|
|
867
|
+
* Each operator the body calls, by name (`id`, or `id@version` past the
|
|
868
|
+
* first), in the order it first calls them: a defined one, and each
|
|
869
|
+
* primitive one its expansion calls.
|
|
870
|
+
*/
|
|
871
|
+
operators: (self: AnyQuery) => ReadonlyArray<string>;
|
|
872
|
+
/**
|
|
873
|
+
* What the whole query reads: the fields and inputs of every predicate and
|
|
874
|
+
* every ordering term, and the operations it uses, with the fields also
|
|
875
|
+
* split by role.
|
|
876
|
+
*/
|
|
877
|
+
dependencies: (self: AnyQuery) => QueryDependencies;
|
|
878
|
+
/**
|
|
879
|
+
* The operations this query needs that `supported` does not list, in the
|
|
880
|
+
* order the query uses them, then each primitive operator `operators` does
|
|
881
|
+
* not implement, by name. Without `operators`, every primitive operator is
|
|
882
|
+
* named: a list of operations implements none. Empty means an interpreter
|
|
883
|
+
* declaring both can answer it.
|
|
884
|
+
*
|
|
885
|
+
* An interpreter declares what it runs and refuses the rest, rather than
|
|
886
|
+
* ignoring an operation it does not implement — which would answer a
|
|
887
|
+
* different question and say nothing. The refusal is the interpreter's to
|
|
888
|
+
* raise: this only says what is missing, because what to do about it differs
|
|
889
|
+
* between one that compiles at registration and one that runs a body
|
|
890
|
+
* directly.
|
|
891
|
+
*
|
|
892
|
+
* ```ts
|
|
893
|
+
* const missing = Query.unsupported(body, ['eq', 'isNull', 'isNotNull'])
|
|
894
|
+
* if (missing.length > 0) throw new Error(`cannot run ${missing.join(', ')}`)
|
|
895
|
+
* ```
|
|
896
|
+
*/
|
|
897
|
+
unsupported: (self: AnyQuery, supported: ReadonlyArray<Operation>, operators?: OperatorTable) => ReadonlyArray<string>;
|
|
898
|
+
/**
|
|
899
|
+
* The whole query as readable text, one clause per line:
|
|
900
|
+
*
|
|
901
|
+
* ```text
|
|
902
|
+
* FROM Post
|
|
903
|
+
* WHERE Post.slug = $slug
|
|
904
|
+
* AND Post.published = true
|
|
905
|
+
* ORDER BY Post.updatedAt DESC
|
|
906
|
+
* ```
|
|
907
|
+
*
|
|
908
|
+
* For an explanation or a diagnostic, never for an interpreter — see
|
|
909
|
+
* `Expr.show`. A query with no `where` or no `orderBy` omits that line rather
|
|
910
|
+
* than printing an empty one, so what is shown is what was written.
|
|
911
|
+
*/
|
|
912
|
+
show: (self: AnyQuery) => string;
|
|
913
|
+
};
|
|
914
|
+
export {};
|
|
915
|
+
//# sourceMappingURL=expr.d.ts.map
|