foldkit-entity 0.13.0 → 0.15.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.
Files changed (119) hide show
  1. package/README.md +962 -512
  2. package/dist/collation.d.ts +33 -0
  3. package/dist/collation.d.ts.map +1 -0
  4. package/dist/collation.js +46 -0
  5. package/dist/collation.js.map +1 -0
  6. package/dist/conformance/index.d.ts +66 -0
  7. package/dist/conformance/index.d.ts.map +1 -0
  8. package/dist/conformance/{index.mjs → index.js} +22 -360
  9. package/dist/conformance/index.js.map +1 -0
  10. package/dist/conformance/operator.d.ts +115 -0
  11. package/dist/conformance/operator.d.ts.map +1 -0
  12. package/dist/conformance/operator.js +354 -0
  13. package/dist/conformance/operator.js.map +1 -0
  14. package/dist/conformance/relational.d.ts +240 -0
  15. package/dist/conformance/relational.d.ts.map +1 -0
  16. package/dist/conformance/relational.js +425 -0
  17. package/dist/conformance/relational.js.map +1 -0
  18. package/dist/conformance/tuples.d.ts +8 -0
  19. package/dist/conformance/tuples.d.ts.map +1 -0
  20. package/dist/conformance/tuples.js +43 -0
  21. package/dist/conformance/tuples.js.map +1 -0
  22. package/dist/conformance/variants.d.ts +47 -0
  23. package/dist/conformance/variants.d.ts.map +1 -0
  24. package/dist/conformance/variants.js +126 -0
  25. package/dist/conformance/variants.js.map +1 -0
  26. package/dist/context.d.ts +60 -0
  27. package/dist/context.d.ts.map +1 -0
  28. package/dist/context.js +36 -0
  29. package/dist/context.js.map +1 -0
  30. package/dist/descriptor.d.ts +33 -0
  31. package/dist/descriptor.d.ts.map +1 -0
  32. package/dist/descriptor.js +137 -0
  33. package/dist/descriptor.js.map +1 -0
  34. package/dist/entity.d.ts +231 -0
  35. package/dist/entity.d.ts.map +1 -0
  36. package/dist/entity.js +435 -0
  37. package/dist/entity.js.map +1 -0
  38. package/dist/evaluate.d.ts +204 -0
  39. package/dist/evaluate.d.ts.map +1 -0
  40. package/dist/evaluate.js +765 -0
  41. package/dist/evaluate.js.map +1 -0
  42. package/dist/expr.d.ts +915 -0
  43. package/dist/expr.d.ts.map +1 -0
  44. package/dist/expr.js +1630 -0
  45. package/dist/expr.js.map +1 -0
  46. package/dist/held.d.ts +112 -0
  47. package/dist/held.d.ts.map +1 -0
  48. package/dist/held.js +155 -0
  49. package/dist/held.js.map +1 -0
  50. package/dist/ids.d.ts +8 -0
  51. package/dist/ids.d.ts.map +1 -0
  52. package/dist/ids.js +8 -0
  53. package/dist/ids.js.map +1 -0
  54. package/dist/index.d.ts +380 -0
  55. package/dist/index.d.ts.map +1 -0
  56. package/dist/index.js +110 -0
  57. package/dist/index.js.map +1 -0
  58. package/dist/invariant.d.ts +123 -0
  59. package/dist/invariant.d.ts.map +1 -0
  60. package/dist/invariant.js +236 -0
  61. package/dist/invariant.js.map +1 -0
  62. package/dist/jsonSchema.d.ts +3 -0
  63. package/dist/jsonSchema.d.ts.map +1 -0
  64. package/dist/jsonSchema.js +17 -0
  65. package/dist/jsonSchema.js.map +1 -0
  66. package/dist/law.d.ts +264 -0
  67. package/dist/law.d.ts.map +1 -0
  68. package/dist/law.js +111 -0
  69. package/dist/law.js.map +1 -0
  70. package/dist/operators.d.ts +170 -0
  71. package/dist/operators.d.ts.map +1 -0
  72. package/dist/operators.js +207 -0
  73. package/dist/operators.js.map +1 -0
  74. package/dist/readFilter.d.ts +8 -0
  75. package/dist/readFilter.d.ts.map +1 -0
  76. package/dist/readFilter.js +23 -0
  77. package/dist/readFilter.js.map +1 -0
  78. package/dist/record.d.ts +11 -0
  79. package/dist/record.d.ts.map +1 -0
  80. package/dist/record.js +21 -0
  81. package/dist/record.js.map +1 -0
  82. package/dist/sets.d.ts +18 -0
  83. package/dist/sets.d.ts.map +1 -0
  84. package/dist/sets.js +57 -0
  85. package/dist/sets.js.map +1 -0
  86. package/dist/shape.d.ts +23 -0
  87. package/dist/shape.d.ts.map +1 -0
  88. package/dist/shape.js +30 -0
  89. package/dist/shape.js.map +1 -0
  90. package/dist/tested.d.ts +8 -0
  91. package/dist/tested.d.ts.map +1 -0
  92. package/dist/tested.js +25 -0
  93. package/dist/tested.js.map +1 -0
  94. package/dist/text.d.ts +27 -0
  95. package/dist/text.d.ts.map +1 -0
  96. package/dist/text.js +39 -0
  97. package/dist/text.js.map +1 -0
  98. package/dist/variants.d.ts +72 -0
  99. package/dist/variants.d.ts.map +1 -0
  100. package/dist/variants.js +76 -0
  101. package/dist/variants.js.map +1 -0
  102. package/dist/words.d.ts +17 -0
  103. package/dist/words.d.ts.map +1 -0
  104. package/dist/words.js +22 -0
  105. package/dist/words.js.map +1 -0
  106. package/dist/write.d.ts +312 -0
  107. package/dist/write.d.ts.map +1 -0
  108. package/dist/write.js +520 -0
  109. package/dist/write.js.map +1 -0
  110. package/package.json +8 -8
  111. package/dist/conformance/index.d.mts +0 -274
  112. package/dist/conformance/index.d.mts.map +0 -1
  113. package/dist/conformance/index.mjs.map +0 -1
  114. package/dist/index-hu8IYlNc.d.mts +0 -2228
  115. package/dist/index-hu8IYlNc.d.mts.map +0 -1
  116. package/dist/index.d.mts +0 -2
  117. package/dist/index.mjs +0 -1
  118. package/dist/src-DBAilaDV.mjs +0 -3061
  119. package/dist/src-DBAilaDV.mjs.map +0 -1
package/dist/expr.d.ts ADDED
@@ -0,0 +1,915 @@
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