foldkit-entity 0.11.0 → 0.13.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 +296 -15
- package/dist/conformance/index.d.mts +221 -4
- package/dist/conformance/index.d.mts.map +1 -1
- package/dist/conformance/index.mjs +466 -5
- package/dist/conformance/index.mjs.map +1 -1
- package/dist/{index-BhI_DA2S.d.mts → index-hu8IYlNc.d.mts} +999 -50
- package/dist/index-hu8IYlNc.d.mts.map +1 -0
- package/dist/index.d.mts +2 -2
- package/dist/index.mjs +1 -1
- package/dist/{src-DwKdHZDu.mjs → src-DBAilaDV.mjs} +1299 -150
- package/dist/src-DBAilaDV.mjs.map +1 -0
- package/package.json +1 -1
- package/dist/index-BhI_DA2S.d.mts.map +0 -1
- package/dist/src-DwKdHZDu.mjs.map +0 -1
|
@@ -1,6 +1,5 @@
|
|
|
1
|
-
import { Array, Option, Pipeable, Schema, SchemaAST } from "effect";
|
|
1
|
+
import { Array, Data, Option, Pipeable, Schema, SchemaAST } from "effect";
|
|
2
2
|
import { Metadata } from "foldkit-metadata";
|
|
3
|
-
//#region src/collation.d.ts
|
|
4
3
|
type Collation =
|
|
5
4
|
/** By code point: SQLite `BINARY`, Postgres `COLLATE "C"`. */
|
|
6
5
|
{
|
|
@@ -23,9 +22,274 @@ declare const Collation: {
|
|
|
23
22
|
of: (collation: Collation) => Metadata;
|
|
24
23
|
/** The collation a member's metadata declares, if any. */
|
|
25
24
|
declared: (metadata: Metadata) => Option.Option<Collation>;
|
|
25
|
+
/**
|
|
26
|
+
* Text as `asciiFold` compares it: ASCII letters lowercased, every other
|
|
27
|
+
* character as it is, which is what SQLite's `lower` does without ICU and so
|
|
28
|
+
* what compiled SQL folds to. `toLowerCase` would fold `É` to `é` here and not
|
|
29
|
+
* there. An operator implementing `asciiFold` folds with this.
|
|
30
|
+
*/
|
|
31
|
+
foldAscii: (text: string) => string;
|
|
32
|
+
};
|
|
33
|
+
/** An operator a law names as a witness: the inverse, or the operator distributed over. */
|
|
34
|
+
type AnyOperator = Operator<ReadonlyArray<Schema.Top>, Schema.Top>;
|
|
35
|
+
/** Which argument a witness stands in. */
|
|
36
|
+
type Side = 'left' | 'right' | 'both';
|
|
37
|
+
/**
|
|
38
|
+
* A law, over its domain: by default every non-null value of the operator's
|
|
39
|
+
* input schemas; narrowed by `Law.within`.
|
|
40
|
+
*/
|
|
41
|
+
type Law = Data.TaggedEnum<{
|
|
42
|
+
/** `op(op(a, b), c) = op(a, op(b, c))` */
|
|
43
|
+
Associative: {
|
|
44
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
45
|
+
};
|
|
46
|
+
/** `op(a, b) = op(b, a)` */
|
|
47
|
+
Commutative: {
|
|
48
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
49
|
+
};
|
|
50
|
+
/** `op(a, a) = a` */
|
|
51
|
+
Idempotent: {
|
|
52
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
53
|
+
};
|
|
54
|
+
/** `op(e, a) = a` (left), `op(a, e) = a` (right), or both. */
|
|
55
|
+
Identity: {
|
|
56
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
57
|
+
readonly value: unknown;
|
|
58
|
+
readonly side: Side;
|
|
59
|
+
};
|
|
60
|
+
/** `op(z, a) = z` (left), `op(a, z) = z` (right), or both. */
|
|
61
|
+
Absorbing: {
|
|
62
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
63
|
+
readonly value: unknown;
|
|
64
|
+
readonly side: Side;
|
|
65
|
+
};
|
|
66
|
+
/** `op(a, other(a)) = identity` */
|
|
67
|
+
Inverse: {
|
|
68
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
69
|
+
readonly other: AnyOperator;
|
|
70
|
+
readonly identity: unknown;
|
|
71
|
+
};
|
|
72
|
+
/** `op(a, over(b, c)) = over(op(a, b), op(a, c))` */
|
|
73
|
+
Distributes: {
|
|
74
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
75
|
+
readonly over: AnyOperator;
|
|
76
|
+
};
|
|
77
|
+
/** `a ≤ b` at `position` implies `op(…a…) ≤ op(…b…)`, or `≥` when decreasing. */
|
|
78
|
+
Monotonic: {
|
|
79
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
80
|
+
readonly direction: 'increasing' | 'decreasing';
|
|
81
|
+
readonly position: number;
|
|
82
|
+
};
|
|
83
|
+
/** Folding the result equals folding the arguments first: its text keeps their collation (§7). */
|
|
84
|
+
PreservesCollation: {
|
|
85
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
86
|
+
};
|
|
87
|
+
}>;
|
|
88
|
+
/**
|
|
89
|
+
* A law as JSON says it: what `Operators.describe` lists and evidence names.
|
|
90
|
+
* Its witnesses are values as stored and operators by name; its domain is a
|
|
91
|
+
* JSON Schema, or `null` for the operator's whole input.
|
|
92
|
+
*/
|
|
93
|
+
declare const LawDescription: Schema.Struct<{
|
|
94
|
+
readonly kind: Schema.String;
|
|
95
|
+
readonly witnesses: Schema.$Record<Schema.String, Schema.Unknown>;
|
|
96
|
+
readonly domain: Schema.Unknown;
|
|
97
|
+
}>;
|
|
98
|
+
type LawDescription = typeof LawDescription.Type;
|
|
99
|
+
declare const Law: {
|
|
100
|
+
associative: {
|
|
101
|
+
readonly _tag: "Associative";
|
|
102
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
103
|
+
};
|
|
104
|
+
commutative: {
|
|
105
|
+
readonly _tag: "Commutative";
|
|
106
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
107
|
+
};
|
|
108
|
+
idempotent: {
|
|
109
|
+
readonly _tag: "Idempotent";
|
|
110
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
111
|
+
};
|
|
112
|
+
preservesCollation: {
|
|
113
|
+
readonly _tag: "PreservesCollation";
|
|
114
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
115
|
+
};
|
|
116
|
+
/** `value` leaves the other argument as it is, from `side` (both by default). */
|
|
117
|
+
identity: (value: unknown, side?: Side) => Law;
|
|
118
|
+
/** `value` is the answer whatever the other argument, from `side` (both by default). */
|
|
119
|
+
absorbing: (value: unknown, side?: Side) => Law;
|
|
120
|
+
/** `other` undoes the operator: `op(a, other(a))` is `identity`. */
|
|
121
|
+
inverse: <In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(other: Operator<In, Out>, identity: unknown) => Law;
|
|
122
|
+
/** The operator distributes over `over`, from the left. */
|
|
123
|
+
distributes: <In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(over: Operator<In, Out>) => Law;
|
|
124
|
+
/** Moving the argument at `position` up moves the result up (or down, decreasing). */
|
|
125
|
+
monotonic: (direction: 'increasing' | 'decreasing', position: number) => Law;
|
|
126
|
+
/**
|
|
127
|
+
* The law over the values `domain` accepts only: a law that holds of the
|
|
128
|
+
* integers and not of every number, say, narrowed so it is tested where it
|
|
129
|
+
* is claimed.
|
|
130
|
+
*/
|
|
131
|
+
within: (law: Law, domain: Schema.Top) => Law;
|
|
132
|
+
$match: {
|
|
133
|
+
<Cases extends { readonly [Tag in "Absorbing" | "Associative" | "Commutative" | "Distributes" | "Idempotent" | "Identity" | "Inverse" | "Monotonic" | "PreservesCollation"]: (args: Extract<{
|
|
134
|
+
readonly _tag: "Absorbing";
|
|
135
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
136
|
+
readonly value: unknown;
|
|
137
|
+
readonly side: Side;
|
|
138
|
+
} | {
|
|
139
|
+
readonly _tag: "Associative";
|
|
140
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
141
|
+
} | {
|
|
142
|
+
readonly _tag: "Commutative";
|
|
143
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
144
|
+
} | {
|
|
145
|
+
readonly _tag: "Distributes";
|
|
146
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
147
|
+
readonly over: AnyOperator;
|
|
148
|
+
} | {
|
|
149
|
+
readonly _tag: "Idempotent";
|
|
150
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
151
|
+
} | {
|
|
152
|
+
readonly _tag: "Identity";
|
|
153
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
154
|
+
readonly value: unknown;
|
|
155
|
+
readonly side: Side;
|
|
156
|
+
} | {
|
|
157
|
+
readonly _tag: "Inverse";
|
|
158
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
159
|
+
readonly other: AnyOperator;
|
|
160
|
+
readonly identity: unknown;
|
|
161
|
+
} | {
|
|
162
|
+
readonly _tag: "Monotonic";
|
|
163
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
164
|
+
readonly direction: 'increasing' | 'decreasing';
|
|
165
|
+
readonly position: number;
|
|
166
|
+
} | {
|
|
167
|
+
readonly _tag: "PreservesCollation";
|
|
168
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
169
|
+
}, {
|
|
170
|
+
readonly _tag: Tag;
|
|
171
|
+
}>) => any; }>(cases: Cases): (value: {
|
|
172
|
+
readonly _tag: "Absorbing";
|
|
173
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
174
|
+
readonly value: unknown;
|
|
175
|
+
readonly side: Side;
|
|
176
|
+
} | {
|
|
177
|
+
readonly _tag: "Associative";
|
|
178
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
179
|
+
} | {
|
|
180
|
+
readonly _tag: "Commutative";
|
|
181
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
182
|
+
} | {
|
|
183
|
+
readonly _tag: "Distributes";
|
|
184
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
185
|
+
readonly over: AnyOperator;
|
|
186
|
+
} | {
|
|
187
|
+
readonly _tag: "Idempotent";
|
|
188
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
189
|
+
} | {
|
|
190
|
+
readonly _tag: "Identity";
|
|
191
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
192
|
+
readonly value: unknown;
|
|
193
|
+
readonly side: Side;
|
|
194
|
+
} | {
|
|
195
|
+
readonly _tag: "Inverse";
|
|
196
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
197
|
+
readonly other: AnyOperator;
|
|
198
|
+
readonly identity: unknown;
|
|
199
|
+
} | {
|
|
200
|
+
readonly _tag: "Monotonic";
|
|
201
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
202
|
+
readonly direction: 'increasing' | 'decreasing';
|
|
203
|
+
readonly position: number;
|
|
204
|
+
} | {
|
|
205
|
+
readonly _tag: "PreservesCollation";
|
|
206
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
207
|
+
}) => import("effect/Unify").Unify<ReturnType<Cases["Absorbing" | "Associative" | "Commutative" | "Distributes" | "Idempotent" | "Identity" | "Inverse" | "Monotonic" | "PreservesCollation"]>>;
|
|
208
|
+
<Cases extends { readonly [Tag in "Absorbing" | "Associative" | "Commutative" | "Distributes" | "Idempotent" | "Identity" | "Inverse" | "Monotonic" | "PreservesCollation"]: (args: Extract<{
|
|
209
|
+
readonly _tag: "Absorbing";
|
|
210
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
211
|
+
readonly value: unknown;
|
|
212
|
+
readonly side: Side;
|
|
213
|
+
} | {
|
|
214
|
+
readonly _tag: "Associative";
|
|
215
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
216
|
+
} | {
|
|
217
|
+
readonly _tag: "Commutative";
|
|
218
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
219
|
+
} | {
|
|
220
|
+
readonly _tag: "Distributes";
|
|
221
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
222
|
+
readonly over: AnyOperator;
|
|
223
|
+
} | {
|
|
224
|
+
readonly _tag: "Idempotent";
|
|
225
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
226
|
+
} | {
|
|
227
|
+
readonly _tag: "Identity";
|
|
228
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
229
|
+
readonly value: unknown;
|
|
230
|
+
readonly side: Side;
|
|
231
|
+
} | {
|
|
232
|
+
readonly _tag: "Inverse";
|
|
233
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
234
|
+
readonly other: AnyOperator;
|
|
235
|
+
readonly identity: unknown;
|
|
236
|
+
} | {
|
|
237
|
+
readonly _tag: "Monotonic";
|
|
238
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
239
|
+
readonly direction: 'increasing' | 'decreasing';
|
|
240
|
+
readonly position: number;
|
|
241
|
+
} | {
|
|
242
|
+
readonly _tag: "PreservesCollation";
|
|
243
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
244
|
+
}, {
|
|
245
|
+
readonly _tag: Tag;
|
|
246
|
+
}>) => any; }>(value: {
|
|
247
|
+
readonly _tag: "Absorbing";
|
|
248
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
249
|
+
readonly value: unknown;
|
|
250
|
+
readonly side: Side;
|
|
251
|
+
} | {
|
|
252
|
+
readonly _tag: "Associative";
|
|
253
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
254
|
+
} | {
|
|
255
|
+
readonly _tag: "Commutative";
|
|
256
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
257
|
+
} | {
|
|
258
|
+
readonly _tag: "Distributes";
|
|
259
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
260
|
+
readonly over: AnyOperator;
|
|
261
|
+
} | {
|
|
262
|
+
readonly _tag: "Idempotent";
|
|
263
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
264
|
+
} | {
|
|
265
|
+
readonly _tag: "Identity";
|
|
266
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
267
|
+
readonly value: unknown;
|
|
268
|
+
readonly side: Side;
|
|
269
|
+
} | {
|
|
270
|
+
readonly _tag: "Inverse";
|
|
271
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
272
|
+
readonly other: AnyOperator;
|
|
273
|
+
readonly identity: unknown;
|
|
274
|
+
} | {
|
|
275
|
+
readonly _tag: "Monotonic";
|
|
276
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
277
|
+
readonly direction: 'increasing' | 'decreasing';
|
|
278
|
+
readonly position: number;
|
|
279
|
+
} | {
|
|
280
|
+
readonly _tag: "PreservesCollation";
|
|
281
|
+
readonly domain: Option.Option<Schema.Top>;
|
|
282
|
+
}, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Absorbing" | "Associative" | "Commutative" | "Distributes" | "Idempotent" | "Identity" | "Inverse" | "Monotonic" | "PreservesCollation"]>>;
|
|
283
|
+
};
|
|
284
|
+
/**
|
|
285
|
+
* The operators a law, as JSON, calls besides its own (`inverse`'s and
|
|
286
|
+
* `distributes`' witnesses), by name: evidence of it is of their
|
|
287
|
+
* implementations too, and goes when one of them is replaced.
|
|
288
|
+
*/
|
|
289
|
+
witnessesNamed: (law: LawDescription) => ReadonlyArray<string>;
|
|
290
|
+
/** The law as JSON: its kind, its witnesses (operators by name) and its domain's JSON Schema. */
|
|
291
|
+
describe: (law: Law) => LawDescription;
|
|
26
292
|
};
|
|
27
|
-
//#endregion
|
|
28
|
-
//#region src/expr.d.ts
|
|
29
293
|
/** A constant the query was written with. */
|
|
30
294
|
interface LiteralExpr<T> {
|
|
31
295
|
readonly _tag: 'Literal';
|
|
@@ -67,8 +331,75 @@ interface NextExpr<T> {
|
|
|
67
331
|
readonly _tag: 'Next';
|
|
68
332
|
readonly field: FieldExpr<T>;
|
|
69
333
|
}
|
|
334
|
+
/**
|
|
335
|
+
* What an operator is, as the nodes that call it hold it: its identity, the
|
|
336
|
+
* stored form of what it takes and gives, and, for an operator defined by an
|
|
337
|
+
* expression, how to build that expression. It computes nothing itself.
|
|
338
|
+
* Identity is this object; `id` and `version` name it.
|
|
339
|
+
*/
|
|
340
|
+
interface OperatorDescriptor {
|
|
341
|
+
readonly _tag: 'Operator';
|
|
342
|
+
readonly id: string;
|
|
343
|
+
readonly version: number;
|
|
344
|
+
readonly description: Option.Option<string>;
|
|
345
|
+
/** One schema per argument, read as the stored form. */
|
|
346
|
+
readonly input: ReadonlyArray<Schema.Top>;
|
|
347
|
+
readonly output: Schema.Top;
|
|
348
|
+
/**
|
|
349
|
+
* Builds the expression a call means, from its arguments: an operator defined
|
|
350
|
+
* by an expression. None for a primitive operator, which each interpreter
|
|
351
|
+
* implements (`Operators`).
|
|
352
|
+
*/
|
|
353
|
+
readonly definedAs: Option.Option<(...args: ReadonlyArray<Operandish>) => Operandish>;
|
|
354
|
+
/**
|
|
355
|
+
* A primitive operator's null rule. `strict`: a null argument gives null, or
|
|
356
|
+
* unknown for a predicate, and the implementation never sees one. `handled`:
|
|
357
|
+
* the implementation is given nulls and answers for them.
|
|
358
|
+
*/
|
|
359
|
+
readonly nulls: 'strict' | 'handled';
|
|
360
|
+
/**
|
|
361
|
+
* How a call compares text. `operands`: it carries the collation its collated
|
|
362
|
+
* text arguments share, so its text result compares under it. `required`: the
|
|
363
|
+
* same, refused where none is declared (it compares text itself, as
|
|
364
|
+
* `Text.startsWith` does). `none`: it carries none.
|
|
365
|
+
*/
|
|
366
|
+
readonly collation: 'none' | 'operands' | 'required';
|
|
367
|
+
/** The equations every implementation keeps (`Law`), checked where declared, tested by `Conformance.laws`. */
|
|
368
|
+
readonly laws: ReadonlyArray<Law>;
|
|
369
|
+
}
|
|
370
|
+
/** What an interpreter runs, as far as a check of a body needs to know. */
|
|
371
|
+
interface OperatorTable {
|
|
372
|
+
/** Whether this table implements the operator. */
|
|
373
|
+
readonly has: (operator: OperatorDescriptor) => boolean;
|
|
374
|
+
/**
|
|
375
|
+
* The versions of the operator `id` it implements: what a refusal of a call
|
|
376
|
+
* to another version names, since a client and a server on different
|
|
377
|
+
* deploys can disagree on one.
|
|
378
|
+
*/
|
|
379
|
+
readonly versions: (id: string) => ReadonlyArray<number>;
|
|
380
|
+
}
|
|
381
|
+
/** A table implementing nothing: every primitive operator is unsupported by it. */
|
|
382
|
+
declare const noOperators: OperatorTable;
|
|
383
|
+
/**
|
|
384
|
+
* An operator `operators` does not implement, by name, with the versions of it
|
|
385
|
+
* the table does implement: `acme.slug@2 (this table has acme.slug)`.
|
|
386
|
+
*/
|
|
387
|
+
declare const missingName: (operator: OperatorDescriptor, operators: OperatorTable) => string;
|
|
388
|
+
/**
|
|
389
|
+
* A call of an operator whose result is a scalar. `expansion` is the
|
|
390
|
+
* expression it means, built from its arguments when it was called: an
|
|
391
|
+
* interpreter runs that, and needs nothing of its own for the operator.
|
|
392
|
+
*/
|
|
393
|
+
interface CallExpr<T> {
|
|
394
|
+
readonly _tag: 'Call';
|
|
395
|
+
readonly operator: OperatorDescriptor;
|
|
396
|
+
readonly args: ReadonlyArray<Operandish>;
|
|
397
|
+
readonly expansion: Option.Option<Expr<T>>;
|
|
398
|
+
/** How its text result compares, from its operator's `collation` rule. */
|
|
399
|
+
readonly collation: Option.Option<Collation>;
|
|
400
|
+
}
|
|
70
401
|
/** A typed scalar: what a comparison compares. */
|
|
71
|
-
type Expr<T> = LiteralExpr<T> | FieldExpr<T> | InputExpr<T> | NextExpr<T>;
|
|
402
|
+
type Expr<T> = LiteralExpr<T> | FieldExpr<T> | InputExpr<T> | NextExpr<T> | CallExpr<T>;
|
|
72
403
|
/** Any scalar, for the places that hold operands without caring what they are. */
|
|
73
404
|
type AnyExpr = Expr<unknown>;
|
|
74
405
|
/**
|
|
@@ -79,7 +410,7 @@ type AnyExpr = Expr<unknown>;
|
|
|
79
410
|
* then be confused, which a structural phantom would allow. A scalar-valued
|
|
80
411
|
* operation, if one is ever needed, joins `Expr` instead.
|
|
81
412
|
*/
|
|
82
|
-
type Predicate = EqPredicate | NullPredicate | ContainsPredicate | InPredicate | AndPredicate | OrPredicate | NotPredicate | ComparePredicate;
|
|
413
|
+
type Predicate = EqPredicate | NullPredicate | ContainsPredicate | InPredicate | AndPredicate | OrPredicate | NotPredicate | ComparePredicate | TestPredicate;
|
|
83
414
|
/** Two values are the same. */
|
|
84
415
|
interface EqPredicate {
|
|
85
416
|
readonly _tag: 'Eq';
|
|
@@ -154,6 +485,19 @@ interface ComparePredicate {
|
|
|
154
485
|
readonly right: AnyExpr;
|
|
155
486
|
readonly collation: Option.Option<Collation>;
|
|
156
487
|
}
|
|
488
|
+
/**
|
|
489
|
+
* A call of an operator whose result is a boolean, so it stands where any
|
|
490
|
+
* predicate does: in `and`, `or` and `not`, a guard, an invariant. `expansion`
|
|
491
|
+
* is the predicate it means, built when it was called.
|
|
492
|
+
*/
|
|
493
|
+
interface TestPredicate {
|
|
494
|
+
readonly _tag: 'Test';
|
|
495
|
+
readonly operator: OperatorDescriptor;
|
|
496
|
+
readonly args: ReadonlyArray<Operandish>;
|
|
497
|
+
readonly expansion: Option.Option<Predicate>;
|
|
498
|
+
/** The collation it compares text under, from its operator's `collation` rule. */
|
|
499
|
+
readonly collation: Option.Option<Collation>;
|
|
500
|
+
}
|
|
157
501
|
/**
|
|
158
502
|
* Anything an operation can be given: a scalar, or a predicate where a boolean
|
|
159
503
|
* is wanted. `Expr.eq(Expr.isNotNull(archivedAt), input.archived)` is the
|
|
@@ -243,6 +587,8 @@ interface Dependencies {
|
|
|
243
587
|
readonly inputs: ReadonlyArray<string>;
|
|
244
588
|
/** One entry per distinct operation, so an interpreter can refuse what it cannot run. */
|
|
245
589
|
readonly operations: ReadonlyArray<Operation>;
|
|
590
|
+
/** Each operator it calls, once per descriptor, defined or not. */
|
|
591
|
+
readonly operators: ReadonlyArray<OperatorDescriptor>;
|
|
246
592
|
}
|
|
247
593
|
/**
|
|
248
594
|
* What a query reads, with each field's role. A change to a `predicate` field
|
|
@@ -266,7 +612,112 @@ interface Connective<Node extends Predicate> {
|
|
|
266
612
|
<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]>>;
|
|
267
613
|
(...operands: Array.NonEmptyReadonlyArray<Predicate>): Predicate;
|
|
268
614
|
}
|
|
615
|
+
/** A schema's stored form, which is what an operator takes and gives. */
|
|
616
|
+
type StoredOf$1<S extends Schema.Top> = Schema.Codec.Encoded<S>;
|
|
617
|
+
/**
|
|
618
|
+
* One argument an operator may be called with: a field or scalar stored as the
|
|
619
|
+
* input's stored type, a predicate where it takes a boolean, or a plain value.
|
|
620
|
+
*/
|
|
621
|
+
type ArgumentOf<S extends Schema.Top> = EntityField<string, string, Schema.Constraint & Schema.Codec<any, StoredOf$1<S>, any, any>> | Expr<StoredOf$1<S>> | (boolean extends StoredOf$1<S> ? Predicate : never) | StoredOf$1<S>;
|
|
622
|
+
/** What `definedAs` is handed for one argument: the argument as a node. */
|
|
623
|
+
type ParameterOf<S extends Schema.Top> = Expr<StoredOf$1<S>> | (boolean extends StoredOf$1<S> ? Predicate : never);
|
|
624
|
+
/** A call's node: a predicate for a boolean result, a scalar for anything else. */
|
|
625
|
+
type CallOf<Out extends Schema.Top> = [StoredOf$1<Out>] extends [boolean] ? TestPredicate : CallExpr<StoredOf$1<Out>>;
|
|
626
|
+
/** What `definedAs` builds: a predicate for a boolean result, a scalar otherwise. */
|
|
627
|
+
type BodyOf<Out extends Schema.Top> = [StoredOf$1<Out>] extends [boolean] ? Predicate : Expr<StoredOf$1<Out>>;
|
|
628
|
+
/**
|
|
629
|
+
* An operator: called like a function, it builds a node that holds `descriptor`
|
|
630
|
+
* and its arguments. See `Expr.operator`.
|
|
631
|
+
*/
|
|
632
|
+
interface Operator<In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top> {
|
|
633
|
+
<const A extends { readonly [K in keyof In]: ArgumentOf<In[K]>; }>(...args: A): CallOf<Out> & Reads<ReadsOf<A[number]>>;
|
|
634
|
+
/**
|
|
635
|
+
* A call comparing text under the collation given, rather than its text
|
|
636
|
+
* arguments' declared one: for an operator whose `collation` is `operands`
|
|
637
|
+
* or `required`, as `Expr.lt(field, value, { collation })` is.
|
|
638
|
+
*/
|
|
639
|
+
<const A extends { readonly [K in keyof In]: ArgumentOf<In[K]>; }>(...args: [...A, CallOptions]): CallOf<Out> & Reads<ReadsOf<A[number]>>;
|
|
640
|
+
readonly descriptor: OperatorDescriptor;
|
|
641
|
+
}
|
|
642
|
+
/** What a call may say past its arguments. */
|
|
643
|
+
interface CallOptions {
|
|
644
|
+
/** The collation it compares text under, in place of its arguments' declared one. */
|
|
645
|
+
readonly collation: Collation;
|
|
646
|
+
}
|
|
269
647
|
declare const Expr: {
|
|
648
|
+
/**
|
|
649
|
+
* An operator, defined by what a call of it means: `definedAs` builds that
|
|
650
|
+
* expression from the call's arguments, once per call, and every interpreter
|
|
651
|
+
* runs it, so the operator needs no implementation anywhere. What it adds is
|
|
652
|
+
* a name: a query, a guard and an invariant that mean the same thing say so,
|
|
653
|
+
* and print it.
|
|
654
|
+
*
|
|
655
|
+
* ```ts
|
|
656
|
+
* const published = Expr.operator('cms.published', {
|
|
657
|
+
* input: [Schema.Unknown],
|
|
658
|
+
* output: Schema.Boolean,
|
|
659
|
+
* definedAs: publishedAt => Expr.isNotNull(publishedAt),
|
|
660
|
+
* })
|
|
661
|
+
* Query.where(published(Post.fields.publishedAt))
|
|
662
|
+
* ```
|
|
663
|
+
*
|
|
664
|
+
* Arguments are checked by their stored form: a field, scalar or plain value
|
|
665
|
+
* of the input's stored type, or a predicate where it takes a boolean. A
|
|
666
|
+
* boolean output makes a call a predicate. `definedAs` may read only what its
|
|
667
|
+
* arguments hold: a field or input it closes over instead is refused when
|
|
668
|
+
* called, since nothing asking what the call reads would see it. The id is
|
|
669
|
+
* namespaced (`cms.published`); `foldkit.` is reserved; `version` (default 1)
|
|
670
|
+
* changes when what it means does.
|
|
671
|
+
*
|
|
672
|
+
* **Without `definedAs` it is primitive**: each interpreter implements it
|
|
673
|
+
* (`Operators.implement` in memory), and one without an implementation
|
|
674
|
+
* refuses the body by the operator's id. `nulls` (default `strict`: a null
|
|
675
|
+
* argument gives null, the implementation never sees one) and `collation`
|
|
676
|
+
* (`operands`: a text result carries its text arguments' shared collation;
|
|
677
|
+
* `required`: it compares text itself and needs one) are a primitive
|
|
678
|
+
* operator's; a defined one means its body for both.
|
|
679
|
+
*/
|
|
680
|
+
operator: <const In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(id: string, options: {
|
|
681
|
+
readonly input: In;
|
|
682
|
+
readonly output: Out;
|
|
683
|
+
readonly version?: number | undefined;
|
|
684
|
+
readonly description?: string | undefined;
|
|
685
|
+
/** Equations every implementation keeps (`Law.commutative`, `Law.identity('')`, …). */
|
|
686
|
+
readonly laws?: ReadonlyArray<Law> | undefined;
|
|
687
|
+
} & ({
|
|
688
|
+
readonly definedAs: (...args: { readonly [K in keyof In]: ParameterOf<In[K]>; }) => BodyOf<Out>;
|
|
689
|
+
readonly nulls?: undefined;
|
|
690
|
+
readonly collation?: undefined;
|
|
691
|
+
} | {
|
|
692
|
+
readonly definedAs?: undefined;
|
|
693
|
+
readonly nulls?: OperatorDescriptor['nulls'] | undefined;
|
|
694
|
+
readonly collation?: OperatorDescriptor['collation'] | undefined;
|
|
695
|
+
})) => Operator<In, Out>;
|
|
696
|
+
/**
|
|
697
|
+
* The predicate or scalar (an order term's, say) with every call of a
|
|
698
|
+
* defined operator replaced by what it means, deeply. An interpreter that
|
|
699
|
+
* compiles a body expands it first, and compiles exactly what was written
|
|
700
|
+
* out. A call with no definition stays, for the interpreter to run or refuse
|
|
701
|
+
* by name.
|
|
702
|
+
*/
|
|
703
|
+
/**
|
|
704
|
+
* Whether a constant written in these expressions is text holding a NUL, or
|
|
705
|
+
* a list holding one: SQL refuses such a parameter wherever it compiles, so
|
|
706
|
+
* an interpreter refuses the run, not one row.
|
|
707
|
+
*/
|
|
708
|
+
givesNul: (...nodes: ReadonlyArray<AnyExpr | Predicate>) => boolean;
|
|
709
|
+
expanded: <N extends Predicate | AnyExpr>(node: N) => N extends Predicate ? Predicate : AnyExpr;
|
|
710
|
+
/**
|
|
711
|
+
* What these expressions need that an interpreter lacks, as `Query.unsupported`
|
|
712
|
+
* says it for a query: each kernel operation `supported` does not list, then
|
|
713
|
+
* each primitive operator `operators` does not implement, by name (`id`, or
|
|
714
|
+
* `id@version` past the first). For anything holding expressions that is not a
|
|
715
|
+
* query: a guard's rule, an invariant, a write's `when`.
|
|
716
|
+
*/
|
|
717
|
+
unsupported: (nodes: ReadonlyArray<AnyExpr | Predicate | Ordering>, interpreter: {
|
|
718
|
+
readonly operations: ReadonlyArray<Operation>;
|
|
719
|
+
readonly operators: OperatorTable;
|
|
720
|
+
}) => ReadonlyArray<string>;
|
|
270
721
|
/** A constant. Comparisons coerce a plain value, so this is rarely written. */
|
|
271
722
|
literal: typeof literal;
|
|
272
723
|
/**
|
|
@@ -316,7 +767,7 @@ declare const Expr: {
|
|
|
316
767
|
* nullable column that should match everything on an empty search says so:
|
|
317
768
|
* `Expr.or(Expr.isNull(field), Expr.contains(field, input.search))`.
|
|
318
769
|
*/
|
|
319
|
-
contains: <L extends TextOperand>(value: L, search: string |
|
|
770
|
+
contains: <L extends TextOperand>(value: L, search: string | LiteralExpr<string> | InputExpr<string> | InputExpr<string | null>) => ContainsPredicate & Reads<ReadsOf<L>>;
|
|
320
771
|
/**
|
|
321
772
|
* Whether a value is one of `among`: a list written out, or an input whose
|
|
322
773
|
* value is one. Each element is compared as `eq` compares.
|
|
@@ -447,7 +898,7 @@ type ChosenSort<By extends string> = {
|
|
|
447
898
|
interface ChosenOrder {
|
|
448
899
|
readonly _tag: 'Chosen';
|
|
449
900
|
readonly sort: InputExpr<ChosenSort<string>>;
|
|
450
|
-
readonly choices: Readonly<Record<string, FieldExpr<unknown>>>;
|
|
901
|
+
readonly choices: Readonly<Record<string, FieldExpr<unknown> | CallExpr<unknown>>>;
|
|
451
902
|
}
|
|
452
903
|
/** One entry of a body's ordering: fixed, or chosen by the input. */
|
|
453
904
|
type Ordering = OrderTerm | ChosenOrder;
|
|
@@ -458,8 +909,8 @@ declare const Order: {
|
|
|
458
909
|
desc: <E extends Operand<any>>(expr: E, options?: TermOptions) => OrderTerm & Reads<ReadsOf<E>>;
|
|
459
910
|
/**
|
|
460
911
|
* The order the input names, among `choices`: every name the sort can hold
|
|
461
|
-
* maps to a field, so a name left out is a type error
|
|
462
|
-
* silently orders by nothing. A `null` sort chooses none, and the terms after
|
|
912
|
+
* maps to a field or a call that orders, so a name left out is a type error
|
|
913
|
+
* here, not a query that silently orders by nothing. A `null` sort chooses none, and the terms after
|
|
463
914
|
* it decide.
|
|
464
915
|
*
|
|
465
916
|
* ```ts
|
|
@@ -549,10 +1000,19 @@ declare const Query: {
|
|
|
549
1000
|
/**
|
|
550
1001
|
* Whether a client can order this query's rows exactly as the server does,
|
|
551
1002
|
* for one input: every term over a number or a boolean (a row may lack it), or over text with a
|
|
552
|
-
* portable collation (`binary`, `asciiFold`)
|
|
553
|
-
*
|
|
1003
|
+
* portable collation (`binary`, `asciiFold`), or a call whose primitive
|
|
1004
|
+
* operators the client's table (`operators`; none when not given) runs. A
|
|
1005
|
+
* body that names no order leaves it to the server, and is never placeable.
|
|
1006
|
+
*/
|
|
1007
|
+
placement: (self: AnyQuery, input: Readonly<Record<string, unknown>>, options?: {
|
|
1008
|
+
readonly operators?: OperatorTable | undefined;
|
|
1009
|
+
}) => Placement;
|
|
1010
|
+
/**
|
|
1011
|
+
* Each operator the body calls, by name (`id`, or `id@version` past the
|
|
1012
|
+
* first), in the order it first calls them: a defined one, and each
|
|
1013
|
+
* primitive one its expansion calls.
|
|
554
1014
|
*/
|
|
555
|
-
|
|
1015
|
+
operators: (self: AnyQuery) => ReadonlyArray<string>;
|
|
556
1016
|
/**
|
|
557
1017
|
* What the whole query reads: the fields and inputs of every predicate and
|
|
558
1018
|
* every ordering term, and the operations it uses, with the fields also
|
|
@@ -561,8 +1021,10 @@ declare const Query: {
|
|
|
561
1021
|
dependencies: (self: AnyQuery) => QueryDependencies;
|
|
562
1022
|
/**
|
|
563
1023
|
* The operations this query needs that `supported` does not list, in the
|
|
564
|
-
* order the query uses them
|
|
565
|
-
* `
|
|
1024
|
+
* order the query uses them, then each primitive operator `operators` does
|
|
1025
|
+
* not implement, by name. Without `operators`, every primitive operator is
|
|
1026
|
+
* named: a list of operations implements none. Empty means an interpreter
|
|
1027
|
+
* declaring both can answer it.
|
|
566
1028
|
*
|
|
567
1029
|
* An interpreter declares what it runs and refuses the rest, rather than
|
|
568
1030
|
* ignoring an operation it does not implement — which would answer a
|
|
@@ -576,7 +1038,7 @@ declare const Query: {
|
|
|
576
1038
|
* if (missing.length > 0) throw new Error(`cannot run ${missing.join(', ')}`)
|
|
577
1039
|
* ```
|
|
578
1040
|
*/
|
|
579
|
-
unsupported: (self: AnyQuery, supported: ReadonlyArray<Operation
|
|
1041
|
+
unsupported: (self: AnyQuery, supported: ReadonlyArray<Operation>, operators?: OperatorTable) => ReadonlyArray<string>;
|
|
580
1042
|
/**
|
|
581
1043
|
* The whole query as readable text, one clause per line:
|
|
582
1044
|
*
|
|
@@ -593,15 +1055,290 @@ declare const Query: {
|
|
|
593
1055
|
*/
|
|
594
1056
|
show: (self: AnyQuery) => string;
|
|
595
1057
|
};
|
|
596
|
-
|
|
597
|
-
|
|
1058
|
+
declare const testedByRunner: (record: Evidence) => boolean;
|
|
1059
|
+
/** What an implementation is told besides its arguments. */
|
|
1060
|
+
interface OperatorContext {
|
|
1061
|
+
/** The collation the call compares text under, from its operator's `collation` rule. */
|
|
1062
|
+
readonly collation: Option.Option<Collation>;
|
|
1063
|
+
}
|
|
1064
|
+
/** One operator's in-memory implementation: a pure function of stored values. */
|
|
1065
|
+
interface MemoryImplementation {
|
|
1066
|
+
readonly operator: OperatorDescriptor;
|
|
1067
|
+
readonly run: (args: ReadonlyArray<unknown>, context: OperatorContext) => unknown;
|
|
1068
|
+
}
|
|
1069
|
+
/**
|
|
1070
|
+
* What is known of a law of an implementation, past its operator claiming it
|
|
1071
|
+
* (expr-operations-DESIGN §10.3): `Tested`, it passed `Conformance.laws`'
|
|
1072
|
+
* cases; `Proven`, a proof elsewhere says so under its assumptions, recorded
|
|
1073
|
+
* and never checked here.
|
|
1074
|
+
*/
|
|
1075
|
+
type Evidence = Data.TaggedEnum<{
|
|
1076
|
+
Tested: {
|
|
1077
|
+
readonly operator: string;
|
|
1078
|
+
readonly law: LawDescription;
|
|
1079
|
+
readonly implementation: string;
|
|
1080
|
+
readonly cases: number;
|
|
1081
|
+
readonly seed: number;
|
|
1082
|
+
};
|
|
1083
|
+
Proven: {
|
|
1084
|
+
readonly operator: string;
|
|
1085
|
+
readonly law: LawDescription;
|
|
1086
|
+
readonly reference: string;
|
|
1087
|
+
readonly assumptions: ReadonlyArray<string>;
|
|
1088
|
+
};
|
|
1089
|
+
}>;
|
|
1090
|
+
declare const Evidence: {
|
|
1091
|
+
readonly $is: <Tag extends "Proven" | "Tested">(tag: Tag) => (u: unknown) => u is Extract<{
|
|
1092
|
+
readonly _tag: "Proven";
|
|
1093
|
+
readonly operator: string;
|
|
1094
|
+
readonly law: LawDescription;
|
|
1095
|
+
readonly reference: string;
|
|
1096
|
+
readonly assumptions: ReadonlyArray<string>;
|
|
1097
|
+
}, {
|
|
1098
|
+
readonly _tag: Tag;
|
|
1099
|
+
}> | Extract<{
|
|
1100
|
+
readonly _tag: "Tested";
|
|
1101
|
+
readonly operator: string;
|
|
1102
|
+
readonly law: LawDescription;
|
|
1103
|
+
readonly implementation: string;
|
|
1104
|
+
readonly cases: number;
|
|
1105
|
+
readonly seed: number;
|
|
1106
|
+
}, {
|
|
1107
|
+
readonly _tag: Tag;
|
|
1108
|
+
}>;
|
|
1109
|
+
readonly $match: {
|
|
1110
|
+
<Cases extends { readonly [Tag in "Proven" | "Tested"]: (args: Extract<{
|
|
1111
|
+
readonly _tag: "Proven";
|
|
1112
|
+
readonly operator: string;
|
|
1113
|
+
readonly law: LawDescription;
|
|
1114
|
+
readonly reference: string;
|
|
1115
|
+
readonly assumptions: ReadonlyArray<string>;
|
|
1116
|
+
} | {
|
|
1117
|
+
readonly _tag: "Tested";
|
|
1118
|
+
readonly operator: string;
|
|
1119
|
+
readonly law: LawDescription;
|
|
1120
|
+
readonly implementation: string;
|
|
1121
|
+
readonly cases: number;
|
|
1122
|
+
readonly seed: number;
|
|
1123
|
+
}, {
|
|
1124
|
+
readonly _tag: Tag;
|
|
1125
|
+
}>) => any; }>(cases: Cases): (value: {
|
|
1126
|
+
readonly _tag: "Proven";
|
|
1127
|
+
readonly operator: string;
|
|
1128
|
+
readonly law: LawDescription;
|
|
1129
|
+
readonly reference: string;
|
|
1130
|
+
readonly assumptions: ReadonlyArray<string>;
|
|
1131
|
+
} | {
|
|
1132
|
+
readonly _tag: "Tested";
|
|
1133
|
+
readonly operator: string;
|
|
1134
|
+
readonly law: LawDescription;
|
|
1135
|
+
readonly implementation: string;
|
|
1136
|
+
readonly cases: number;
|
|
1137
|
+
readonly seed: number;
|
|
1138
|
+
}) => import("effect/Unify").Unify<ReturnType<Cases["Proven" | "Tested"]>>;
|
|
1139
|
+
<Cases extends { readonly [Tag in "Proven" | "Tested"]: (args: Extract<{
|
|
1140
|
+
readonly _tag: "Proven";
|
|
1141
|
+
readonly operator: string;
|
|
1142
|
+
readonly law: LawDescription;
|
|
1143
|
+
readonly reference: string;
|
|
1144
|
+
readonly assumptions: ReadonlyArray<string>;
|
|
1145
|
+
} | {
|
|
1146
|
+
readonly _tag: "Tested";
|
|
1147
|
+
readonly operator: string;
|
|
1148
|
+
readonly law: LawDescription;
|
|
1149
|
+
readonly implementation: string;
|
|
1150
|
+
readonly cases: number;
|
|
1151
|
+
readonly seed: number;
|
|
1152
|
+
}, {
|
|
1153
|
+
readonly _tag: Tag;
|
|
1154
|
+
}>) => any; }>(value: {
|
|
1155
|
+
readonly _tag: "Proven";
|
|
1156
|
+
readonly operator: string;
|
|
1157
|
+
readonly law: LawDescription;
|
|
1158
|
+
readonly reference: string;
|
|
1159
|
+
readonly assumptions: ReadonlyArray<string>;
|
|
1160
|
+
} | {
|
|
1161
|
+
readonly _tag: "Tested";
|
|
1162
|
+
readonly operator: string;
|
|
1163
|
+
readonly law: LawDescription;
|
|
1164
|
+
readonly implementation: string;
|
|
1165
|
+
readonly cases: number;
|
|
1166
|
+
readonly seed: number;
|
|
1167
|
+
}, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Proven" | "Tested"]>>;
|
|
1168
|
+
};
|
|
1169
|
+
readonly Proven: Data.TaggedEnum.ConstructorFrom<{
|
|
1170
|
+
readonly _tag: "Proven";
|
|
1171
|
+
readonly operator: string;
|
|
1172
|
+
readonly law: LawDescription;
|
|
1173
|
+
readonly reference: string;
|
|
1174
|
+
readonly assumptions: ReadonlyArray<string>;
|
|
1175
|
+
}, "_tag">;
|
|
1176
|
+
readonly Tested: Data.TaggedEnum.ConstructorFrom<{
|
|
1177
|
+
readonly _tag: "Tested";
|
|
1178
|
+
readonly operator: string;
|
|
1179
|
+
readonly law: LawDescription;
|
|
1180
|
+
readonly implementation: string;
|
|
1181
|
+
readonly cases: number;
|
|
1182
|
+
readonly seed: number;
|
|
1183
|
+
}, "_tag">;
|
|
1184
|
+
};
|
|
1185
|
+
/** A record of a law passing `Conformance.laws`' cases. */
|
|
1186
|
+
type TestedEvidence = Extract<Evidence, {
|
|
1187
|
+
readonly _tag: 'Tested';
|
|
1188
|
+
}>;
|
|
1189
|
+
/**
|
|
1190
|
+
* An operator as JSON, by its signature and never its body (a defined
|
|
1191
|
+
* operator says `defined`, not what it means): what a server can publish of
|
|
1192
|
+
* what a body may call, and a client compare with what it runs. Its schemas
|
|
1193
|
+
* are each argument's and the result's stored side, as JSON Schemas.
|
|
1194
|
+
*/
|
|
1195
|
+
declare const OperatorDescription: Schema.Struct<{
|
|
1196
|
+
/** By id, and `@version` past the first: what tables, evidence and refusals name. */
|
|
1197
|
+
readonly name: Schema.String;
|
|
1198
|
+
readonly id: Schema.String;
|
|
1199
|
+
readonly version: Schema.Int;
|
|
1200
|
+
readonly description: Schema.NullOr<Schema.String>;
|
|
1201
|
+
readonly input: Schema.$Array<Schema.$Record<Schema.String, Schema.Unknown>>;
|
|
1202
|
+
readonly output: Schema.$Record<Schema.String, Schema.Unknown>;
|
|
1203
|
+
readonly nulls: Schema.Literals<readonly ["strict", "handled"]>;
|
|
1204
|
+
readonly collation: Schema.Literals<readonly ["none", "operands", "required"]>;
|
|
1205
|
+
readonly laws: Schema.$Array<Schema.Struct<{
|
|
1206
|
+
readonly kind: Schema.String;
|
|
1207
|
+
readonly witnesses: Schema.$Record<Schema.String, Schema.Unknown>;
|
|
1208
|
+
readonly domain: Schema.Unknown;
|
|
1209
|
+
}>>;
|
|
1210
|
+
readonly defined: Schema.Boolean;
|
|
1211
|
+
}>;
|
|
1212
|
+
type OperatorDescription = typeof OperatorDescription.Type;
|
|
1213
|
+
/** One operator a table implements, as `Operators.describeTable` lists it: described, with its evidence. */
|
|
1214
|
+
interface ImplementedOperator extends OperatorDescription {
|
|
1215
|
+
readonly evidence: ReadonlyArray<Evidence>;
|
|
1216
|
+
}
|
|
1217
|
+
/** The in-memory interpreter's implementations, by operator. */
|
|
1218
|
+
interface MemoryOperators extends OperatorTable {
|
|
1219
|
+
readonly _tag: 'MemoryOperators';
|
|
1220
|
+
readonly get: (operator: OperatorDescriptor) => Option.Option<MemoryImplementation['run']>;
|
|
1221
|
+
/**
|
|
1222
|
+
* The operator it implements under a name (`id`, or `id@version` past the
|
|
1223
|
+
* first): how a computed assignment carried as data finds what to run.
|
|
1224
|
+
*/
|
|
1225
|
+
readonly named: (name: string) => Option.Option<OperatorDescriptor>;
|
|
1226
|
+
/** Whether each answer is checked against its operator's output schema: for tests. */
|
|
1227
|
+
readonly checked: boolean;
|
|
1228
|
+
readonly implementations: ReadonlyArray<MemoryImplementation>;
|
|
1229
|
+
/** What is known of its implementations' laws: `Operators.withEvidence`. */
|
|
1230
|
+
readonly evidence: ReadonlyArray<Evidence>;
|
|
1231
|
+
}
|
|
1232
|
+
type StoredOf<S extends Schema.Top> = Schema.Codec.Encoded<S>;
|
|
1233
|
+
declare const Operators: {
|
|
1234
|
+
/**
|
|
1235
|
+
* An implementation of a strict operator: a pure function of its arguments'
|
|
1236
|
+
* stored values, never given a null (the kernel answers null, or unknown, for
|
|
1237
|
+
* one first), and told the call's collation last.
|
|
1238
|
+
*
|
|
1239
|
+
* ```ts
|
|
1240
|
+
* Operators.implement(startsWith, (text, prefix, { collation }) => text.startsWith(prefix))
|
|
1241
|
+
* ```
|
|
1242
|
+
*/
|
|
1243
|
+
implement: <In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(operator: Operator<In, Out>, run: (...args: [...{ readonly [K in keyof In]: NonNullable<StoredOf<In[K]>>; }, OperatorContext]) => StoredOf<Out>) => MemoryImplementation;
|
|
1244
|
+
/**
|
|
1245
|
+
* An implementation of an operator declared `nulls: 'handled'`: given nulls
|
|
1246
|
+
* as they are, it answers for them; a predicate answers `null` for unknown.
|
|
1247
|
+
*/
|
|
1248
|
+
implementHandlingNulls: <In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(operator: Operator<In, Out>, run: (...args: [...{ readonly [K in keyof In]: StoredOf<In[K]>; }, OperatorContext]) => StoredOf<Out> | null) => MemoryImplementation;
|
|
1249
|
+
/** A table of implementations. One operator implemented twice, or two under one name, is refused. */
|
|
1250
|
+
memory: (...implementations: ReadonlyArray<MemoryImplementation>) => MemoryOperators;
|
|
1251
|
+
/** Both tables' implementations. An operator both implement is refused: say which wins with `override`. */
|
|
1252
|
+
merge: (left: MemoryOperators, right: MemoryOperators) => MemoryOperators;
|
|
1253
|
+
/**
|
|
1254
|
+
* The table with these implementations in place of its own for the same
|
|
1255
|
+
* operators. Evidence of a replaced implementation goes with it: it was
|
|
1256
|
+
* that implementation's.
|
|
1257
|
+
*/
|
|
1258
|
+
override: (base: MemoryOperators, ...implementations: ReadonlyArray<MemoryImplementation>) => MemoryOperators;
|
|
1259
|
+
/**
|
|
1260
|
+
* The table with what is known of its implementations' laws recorded: each
|
|
1261
|
+
* record of an operator it implements and a law that operator declares.
|
|
1262
|
+
* `Conformance.laws` gives `Tested` records, each of the implementation it
|
|
1263
|
+
* ran, and a table takes only those of its own; `Evidence.Proven` says a
|
|
1264
|
+
* proof elsewhere covers one.
|
|
1265
|
+
*/
|
|
1266
|
+
withEvidence: (base: MemoryOperators, evidence: ReadonlyArray<Evidence>) => MemoryOperators;
|
|
1267
|
+
/**
|
|
1268
|
+
* The memory implementation `Conformance.laws` tested a record on; none for
|
|
1269
|
+
* a record of a runner (`Conformance.lawsBy`) or a proof.
|
|
1270
|
+
*/
|
|
1271
|
+
testedOn: (record: Evidence) => Option.Option<MemoryImplementation>;
|
|
1272
|
+
/**
|
|
1273
|
+
* Whether `Conformance.lawsBy` made a record, through a runner: what an SQL
|
|
1274
|
+
* table takes. Which runner it was, the database's or another, is the
|
|
1275
|
+
* caller's word; a record built by hand, copied, or tested in memory is not.
|
|
1276
|
+
*/
|
|
1277
|
+
testedByRunner: typeof testedByRunner;
|
|
1278
|
+
/**
|
|
1279
|
+
* Each operator the table implements, by name, with the laws it declares and
|
|
1280
|
+
* the evidence the table records of them: what a server can publish of how
|
|
1281
|
+
* it runs a body. JSON as it is.
|
|
1282
|
+
*/
|
|
1283
|
+
describeTable: (base: MemoryOperators) => ReadonlyArray<ImplementedOperator>;
|
|
1284
|
+
/**
|
|
1285
|
+
* An operator as JSON (`OperatorDescription`): its name, version and
|
|
1286
|
+
* description, each argument's and its result's stored side as a JSON
|
|
1287
|
+
* Schema (as JSON carries it: a number also admits the strings `"Infinity"`,
|
|
1288
|
+
* `"-Infinity"` and `"NaN"`), its null and collation rules, its laws, and
|
|
1289
|
+
* whether it is defined. Its signature, never its body.
|
|
1290
|
+
*/
|
|
1291
|
+
describe: (operator: {
|
|
1292
|
+
readonly descriptor: OperatorDescriptor;
|
|
1293
|
+
}) => OperatorDescription;
|
|
1294
|
+
/**
|
|
1295
|
+
* The table, checking every answer against its operator's output schema, so
|
|
1296
|
+
* an implementation that answers the wrong kind fails where it answered. For
|
|
1297
|
+
* tests: it costs a decode per call.
|
|
1298
|
+
*/
|
|
1299
|
+
checked: (base: MemoryOperators) => MemoryOperators;
|
|
1300
|
+
/** The kernel's own operators (`Text.startsWith`): every memory interpreter's default. */
|
|
1301
|
+
kernel: MemoryOperators;
|
|
1302
|
+
};
|
|
598
1303
|
/** A row as this interpreter reads one: values by field key. */
|
|
599
1304
|
type Row = Readonly<Record<string, unknown>>;
|
|
600
1305
|
declare class QueryEvaluateError extends Error {
|
|
601
1306
|
constructor(message: string);
|
|
602
1307
|
}
|
|
1308
|
+
/**
|
|
1309
|
+
* A call of a primitive operator the table does not implement. Its own class,
|
|
1310
|
+
* because a form judging an invariant reads it as a judgement it cannot make
|
|
1311
|
+
* (`Undecided`), not as a failure.
|
|
1312
|
+
*/
|
|
1313
|
+
declare class OperatorMissingError extends QueryEvaluateError {
|
|
1314
|
+
readonly operator: OperatorDescriptor;
|
|
1315
|
+
/** The operator by its id, and its version past the first. */
|
|
1316
|
+
readonly named: string;
|
|
1317
|
+
/** `operators`, the table that lacks it, names the versions of it that it does hold. */
|
|
1318
|
+
constructor(operator: OperatorDescriptor, operators?: OperatorTable);
|
|
1319
|
+
}
|
|
1320
|
+
/**
|
|
1321
|
+
* A primitive operator over stored values, as a call of it is run: what a
|
|
1322
|
+
* computed assignment comes to (`Write.apply`). Refused, as a call is, when
|
|
1323
|
+
* `operators` does not implement it.
|
|
1324
|
+
*/
|
|
1325
|
+
declare const applyOperator: (operator: OperatorDescriptor, values: ReadonlyArray<unknown>, options: {
|
|
1326
|
+
readonly collation: Option.Option<Collation>;
|
|
1327
|
+
readonly operators: MemoryOperators;
|
|
1328
|
+
}) => unknown;
|
|
603
1329
|
/** SQL's unknown: neither true nor false, and a row is kept only on true. */
|
|
604
1330
|
type Truth = boolean | 'unknown';
|
|
1331
|
+
/**
|
|
1332
|
+
* What an operand comes to over no row: a call of literals and inputs, run by
|
|
1333
|
+
* `operators` (the kernel's when not given), a predicate as its truth with
|
|
1334
|
+
* unknown as null. How a conformance check asks an implementation one
|
|
1335
|
+
* question; refuses what `evaluate` refuses (an operator the table lacks,
|
|
1336
|
+
* text holding NUL).
|
|
1337
|
+
*/
|
|
1338
|
+
declare const valueOfOperand: (node: Operandish, options?: {
|
|
1339
|
+
readonly input?: Row | undefined;
|
|
1340
|
+
readonly operators?: MemoryOperators | undefined;
|
|
1341
|
+
}) => unknown;
|
|
605
1342
|
/** What a predicate comes to: SQL's three values, of which a row is kept only on `true`. */
|
|
606
1343
|
type PredicateTruth = Truth;
|
|
607
1344
|
/**
|
|
@@ -610,17 +1347,22 @@ type PredicateTruth = Truth;
|
|
|
610
1347
|
* before it builds anything: `isNull($status)` is known before any row is.
|
|
611
1348
|
* Refuses what `evaluate` refuses (text holding a NUL).
|
|
612
1349
|
*/
|
|
613
|
-
declare const decided: (node: Predicate, input: Row) => Option.Option<PredicateTruth>;
|
|
1350
|
+
declare const decided: (node: Predicate, input: Row, operators?: MemoryOperators) => Option.Option<PredicateTruth>;
|
|
614
1351
|
/** A predicate's truth over one row (and, for an invariant, the row after a write): SQL's three values. */
|
|
615
|
-
declare const truthOver: (node: Predicate, row: Row, input?: Row, next?: Row) => PredicateTruth;
|
|
1352
|
+
declare const truthOver: (node: Predicate, row: Row, input?: Row, next?: Row, operators?: MemoryOperators) => PredicateTruth;
|
|
616
1353
|
/**
|
|
617
1354
|
* Where `left` sorts against `right` under these terms (`Query.orderFor`'s),
|
|
618
|
-
* as `evaluate` sorts: negative when it comes first.
|
|
619
|
-
*
|
|
620
|
-
*
|
|
1355
|
+
* as `evaluate` sorts: negative when it comes first. A call among them runs
|
|
1356
|
+
* over each row with `input` and `operators` (the kernel's when not given).
|
|
1357
|
+
* Refuses what `evaluate` refuses, for these two rows: a term over neither a
|
|
1358
|
+
* field nor a call, a locale collation, keys of different kinds, or an
|
|
1359
|
+
* operator the table lacks. For a client placing one row among others it
|
|
621
1360
|
* holds.
|
|
622
1361
|
*/
|
|
623
|
-
declare const compareRows: (terms: ReadonlyArray<OrderTerm>, left: Row, right: Row, query: string
|
|
1362
|
+
declare const compareRows: (terms: ReadonlyArray<OrderTerm>, left: Row, right: Row, query: string, options?: {
|
|
1363
|
+
readonly input?: Row | undefined;
|
|
1364
|
+
readonly operators?: MemoryOperators | undefined;
|
|
1365
|
+
}) => number;
|
|
624
1366
|
/**
|
|
625
1367
|
* The operations this interpreter runs. It is the reference, so this is the
|
|
626
1368
|
* whole kernel — but it is declared rather than assumed, because an
|
|
@@ -633,7 +1375,7 @@ declare const supported: ReadonlyArray<Operation>;
|
|
|
633
1375
|
* than skipping it and answering a different question. Called by `evaluate`;
|
|
634
1376
|
* call it directly to check a body once instead of on every run.
|
|
635
1377
|
*/
|
|
636
|
-
declare const assertSupported: (body: AnyQuery) => void;
|
|
1378
|
+
declare const assertSupported: (body: AnyQuery, operators?: MemoryOperators) => void;
|
|
637
1379
|
/**
|
|
638
1380
|
* The rows the body matches, in the order it asks for. Pure: it reads the rows
|
|
639
1381
|
* it is given and nothing else.
|
|
@@ -642,9 +1384,28 @@ declare const assertSupported: (body: AnyQuery) => void;
|
|
|
642
1384
|
* placeholders were built with — the same record the query would be called
|
|
643
1385
|
* with anywhere else.
|
|
644
1386
|
*/
|
|
645
|
-
declare const evaluate: (body: AnyQuery, input: Row, rows: ReadonlyArray<Row
|
|
646
|
-
|
|
647
|
-
|
|
1387
|
+
declare const evaluate: (body: AnyQuery, input: Row, rows: ReadonlyArray<Row>, options?: {
|
|
1388
|
+
readonly operators?: MemoryOperators | undefined;
|
|
1389
|
+
}) => ReadonlyArray<Row>;
|
|
1390
|
+
/** What `evaluateEach` made of each row: those it matched, in order, and those it refused. */
|
|
1391
|
+
interface Evaluated {
|
|
1392
|
+
readonly matched: ReadonlyArray<Row>;
|
|
1393
|
+
readonly refused: ReadonlyArray<Row>;
|
|
1394
|
+
}
|
|
1395
|
+
/**
|
|
1396
|
+
* As `evaluate`, with each row judged alone: a row whose own values are
|
|
1397
|
+
* refused (text holding a NUL, a value an operator fails on) is set aside in
|
|
1398
|
+
* `refused` and the others are still answered. A client judging the rows it
|
|
1399
|
+
* holds wants this, since one bad stored row says nothing about the rest.
|
|
1400
|
+
*
|
|
1401
|
+
* What no single row causes still refuses the run: an operation or operator
|
|
1402
|
+
* the table lacks, an order by a locale collation, an input the body reads
|
|
1403
|
+
* holding a NUL (every row would refuse, and no row is the cause), and order
|
|
1404
|
+
* keys of different kinds across rows.
|
|
1405
|
+
*/
|
|
1406
|
+
declare const evaluateEach: (body: AnyQuery, input: Row, rows: ReadonlyArray<Row>, options?: {
|
|
1407
|
+
readonly operators?: MemoryOperators | undefined;
|
|
1408
|
+
}) => Evaluated;
|
|
648
1409
|
/** One invariant of an Entity, as its interpreters read it. */
|
|
649
1410
|
interface Invariant {
|
|
650
1411
|
/** Stable, unique within its Entity: what a refusal names, and forms and logs key on. */
|
|
@@ -676,10 +1437,14 @@ type Judgement = {
|
|
|
676
1437
|
readonly _tag: 'Invalid';
|
|
677
1438
|
readonly failures: ReadonlyArray<Invariant>;
|
|
678
1439
|
} |
|
|
679
|
-
/**
|
|
1440
|
+
/**
|
|
1441
|
+
* Validity is not known: some invariant reads a field the row does not have
|
|
1442
|
+
* (`fields`), or calls an operator the table does not run (`operators`, by name).
|
|
1443
|
+
*/
|
|
680
1444
|
{
|
|
681
1445
|
readonly _tag: 'Undecided';
|
|
682
1446
|
readonly fields: ReadonlyArray<string>;
|
|
1447
|
+
readonly operators: ReadonlyArray<string>;
|
|
683
1448
|
};
|
|
684
1449
|
/** Whether an invariant reads the row before, and so is judged only where there is one. */
|
|
685
1450
|
declare const readsBefore: (held: Invariant) => boolean;
|
|
@@ -701,7 +1466,7 @@ declare const invariant: <E extends AnyEntity>(id: string, build: (rows: {
|
|
|
701
1466
|
}) => DeclaredInvariant<E>;
|
|
702
1467
|
declare const invariantsOf: (entity: AnyEntity) => ReadonlyArray<Invariant>;
|
|
703
1468
|
/** `judge` with the invariants given, as a binding that keeps them holds them. */
|
|
704
|
-
declare const judgeAgainst: (invariants: ReadonlyArray<Invariant>, change: Change) => Judgement;
|
|
1469
|
+
declare const judgeAgainst: (invariants: ReadonlyArray<Invariant>, change: Change, operators?: MemoryOperators) => Judgement;
|
|
705
1470
|
/**
|
|
706
1471
|
* A row, or a change, under every invariant (each row as the store holds it,
|
|
707
1472
|
* encoded): valid only when each is true. SQL's unknown, from a null, fails
|
|
@@ -709,7 +1474,7 @@ declare const judgeAgainst: (invariants: ReadonlyArray<Invariant>, change: Chang
|
|
|
709
1474
|
* undecided, never valid. Without `before` (a create), transition invariants
|
|
710
1475
|
* are not judged.
|
|
711
1476
|
*/
|
|
712
|
-
declare const judge: (entity: AnyEntity, change: Change) => Judgement;
|
|
1477
|
+
declare const judge: (entity: AnyEntity, change: Change, operators?: MemoryOperators) => Judgement;
|
|
713
1478
|
/**
|
|
714
1479
|
* The row an input's value describes, judged under its Entity's state
|
|
715
1480
|
* invariants: each key mapped to a field, encoded as the store holds it. An
|
|
@@ -717,23 +1482,44 @@ declare const judge: (entity: AnyEntity, change: Change) => Judgement;
|
|
|
717
1482
|
* key left out) is undecided, so a partial input is never called valid on its
|
|
718
1483
|
* account. It has no row before, so it judges no transition.
|
|
719
1484
|
*/
|
|
720
|
-
declare const judgeInput: (input: EntityInput<AnyEntity, any, any>, value: Readonly<Record<string, unknown
|
|
1485
|
+
declare const judgeInput: (input: EntityInput<AnyEntity, any, any>, value: Readonly<Record<string, unknown>>, operators?: MemoryOperators) => Judgement;
|
|
721
1486
|
/**
|
|
722
1487
|
* The Entity's state invariants as an Effect Schema check over its row type:
|
|
723
1488
|
* each failure at its path, with its message. The value is encoded first,
|
|
724
1489
|
* field by field, so it is judged as the store would hold it.
|
|
725
1490
|
*/
|
|
726
|
-
declare const check: <E extends AnyEntity>(entity: E
|
|
727
|
-
|
|
728
|
-
|
|
1491
|
+
declare const check: <E extends AnyEntity>(entity: E, options?: {
|
|
1492
|
+
readonly operators?: MemoryOperators | undefined;
|
|
1493
|
+
}) => SchemaAST.Filter<Schema.Schema.Type<E['schema']>>;
|
|
1494
|
+
declare const Text: {
|
|
1495
|
+
/**
|
|
1496
|
+
* Whether the first text begins with the second, under the first's collation.
|
|
1497
|
+
*
|
|
1498
|
+
* | Case | Answer |
|
|
1499
|
+
* | --- | --- |
|
|
1500
|
+
* | either is null | unknown |
|
|
1501
|
+
* | the prefix is `''` | true |
|
|
1502
|
+
* | otherwise | whether it begins so, compared under the collation |
|
|
1503
|
+
*
|
|
1504
|
+
* The collation is the one its text operands share (a field's declared one,
|
|
1505
|
+
* or a call's), or one given to the call. `binary` compares exactly;
|
|
1506
|
+
* `asciiFold` folds ASCII letters on both sides. Operands declaring
|
|
1507
|
+
* different collations, text with none, or a backend's locale are refused
|
|
1508
|
+
* where the call is written.
|
|
1509
|
+
* Prefixes are by character, so non-ASCII and astral text begin as they read.
|
|
1510
|
+
*
|
|
1511
|
+
* ```ts
|
|
1512
|
+
* Query.where(Text.startsWith(Product.fields.upc, input.search))
|
|
1513
|
+
* ```
|
|
1514
|
+
*/
|
|
1515
|
+
startsWith: Operator<readonly [Schema.NullOr<Schema.String>, Schema.NullOr<Schema.String>], Schema.Boolean>;
|
|
1516
|
+
};
|
|
729
1517
|
declare const ReadFilter: {
|
|
730
1518
|
/** Entity metadata: the rows the server lists depend on these members. */
|
|
731
1519
|
of: (members: ReadonlyArray<string>) => Metadata;
|
|
732
1520
|
/** The members an Entity's metadata names, every attachment's together. */
|
|
733
1521
|
members: (metadata: Metadata) => ReadonlyArray<string>;
|
|
734
1522
|
};
|
|
735
|
-
//#endregion
|
|
736
|
-
//#region src/words.d.ts
|
|
737
1523
|
/** What a schema says of itself to a person: its `title` and `description`. */
|
|
738
1524
|
interface SchemaWords {
|
|
739
1525
|
readonly title: Option.Option<string>;
|
|
@@ -749,8 +1535,6 @@ declare const Words: {
|
|
|
749
1535
|
*/
|
|
750
1536
|
of: (schema: Schema.Top) => SchemaWords;
|
|
751
1537
|
};
|
|
752
|
-
//#endregion
|
|
753
|
-
//#region src/shape.d.ts
|
|
754
1538
|
declare const isNullish: (ast: SchemaAST.AST) => boolean;
|
|
755
1539
|
declare const isText: (ast: SchemaAST.AST) => boolean;
|
|
756
1540
|
/** What a schema's AST holds, read through Effect's own guards. */
|
|
@@ -764,9 +1548,13 @@ declare const SchemaShape: {
|
|
|
764
1548
|
present: (ast: SchemaAST.AST) => ReadonlyArray<SchemaAST.AST>;
|
|
765
1549
|
/** True when every value the schema admits is a string. */
|
|
766
1550
|
isText: typeof isText;
|
|
1551
|
+
/**
|
|
1552
|
+
* True when the AST is checked to hold integers (`Schema.isInt`, alone or in
|
|
1553
|
+
* a group such as `isInt32`). Read it from a schema's encoded side to ask
|
|
1554
|
+
* what the store holds.
|
|
1555
|
+
*/
|
|
1556
|
+
holdsIntegers: (ast: SchemaAST.AST) => boolean;
|
|
767
1557
|
};
|
|
768
|
-
//#endregion
|
|
769
|
-
//#region src/write.d.ts
|
|
770
1558
|
type AnyField = EntityField<string, string, Schema.Constraint>;
|
|
771
1559
|
type OneRelation = EntityRelation<string, string, AnyEntity, 'one', boolean>;
|
|
772
1560
|
/** One input key the write sets, and the field it sets. */
|
|
@@ -774,6 +1562,129 @@ interface WriteSet {
|
|
|
774
1562
|
readonly key: string;
|
|
775
1563
|
readonly field: AnyField;
|
|
776
1564
|
}
|
|
1565
|
+
/**
|
|
1566
|
+
* One input key holding an amount, and the field it moves. `integer` is whether
|
|
1567
|
+
* the amount's schema holds it to an integer (`Schema.isInt`): a writer over an
|
|
1568
|
+
* integer column refuses an increment without it, which the Entity cannot see.
|
|
1569
|
+
*/
|
|
1570
|
+
interface WriteIncrement extends WriteSet {
|
|
1571
|
+
readonly integer: boolean;
|
|
1572
|
+
}
|
|
1573
|
+
/**
|
|
1574
|
+
* One field the write computes (`label := concat(title, ' draft')`): an
|
|
1575
|
+
* expression over the row before the write and the input, every defined
|
|
1576
|
+
* operator in it expanded, so what is carried is primitive calls alone.
|
|
1577
|
+
*/
|
|
1578
|
+
interface WriteAssignment {
|
|
1579
|
+
readonly field: AnyField;
|
|
1580
|
+
readonly expr: AnyExpr;
|
|
1581
|
+
}
|
|
1582
|
+
/**
|
|
1583
|
+
* A computed assignment as data, bound to one input: what travels to a server
|
|
1584
|
+
* and sits in a client's pending patch, which holds no descriptor and no
|
|
1585
|
+
* function. A field of the row before the write, a stored value, or a call of
|
|
1586
|
+
* a primitive operator by name (`id`, or `id@version`), with the collation it
|
|
1587
|
+
* compares text under (`null` for none: this is JSON).
|
|
1588
|
+
*/
|
|
1589
|
+
type Computation = Data.TaggedEnum<{
|
|
1590
|
+
Field: {
|
|
1591
|
+
readonly key: string;
|
|
1592
|
+
};
|
|
1593
|
+
Value: {
|
|
1594
|
+
readonly value: unknown;
|
|
1595
|
+
};
|
|
1596
|
+
Call: {
|
|
1597
|
+
readonly operator: string;
|
|
1598
|
+
readonly args: ReadonlyArray<Computation>;
|
|
1599
|
+
readonly collation: Collation | null;
|
|
1600
|
+
};
|
|
1601
|
+
}>;
|
|
1602
|
+
declare const Computation: {
|
|
1603
|
+
readonly $is: <Tag extends "Call" | "Field" | "Value">(tag: Tag) => (u: unknown) => u is Extract<{
|
|
1604
|
+
readonly _tag: "Call";
|
|
1605
|
+
readonly operator: string;
|
|
1606
|
+
readonly args: ReadonlyArray<Computation>;
|
|
1607
|
+
readonly collation: Collation | null;
|
|
1608
|
+
}, {
|
|
1609
|
+
readonly _tag: Tag;
|
|
1610
|
+
}> | Extract<{
|
|
1611
|
+
readonly _tag: "Field";
|
|
1612
|
+
readonly key: string;
|
|
1613
|
+
}, {
|
|
1614
|
+
readonly _tag: Tag;
|
|
1615
|
+
}> | Extract<{
|
|
1616
|
+
readonly _tag: "Value";
|
|
1617
|
+
readonly value: unknown;
|
|
1618
|
+
}, {
|
|
1619
|
+
readonly _tag: Tag;
|
|
1620
|
+
}>;
|
|
1621
|
+
readonly $match: {
|
|
1622
|
+
<Cases extends { readonly [Tag in "Call" | "Field" | "Value"]: (args: Extract<{
|
|
1623
|
+
readonly _tag: "Call";
|
|
1624
|
+
readonly operator: string;
|
|
1625
|
+
readonly args: ReadonlyArray<Computation>;
|
|
1626
|
+
readonly collation: Collation | null;
|
|
1627
|
+
} | {
|
|
1628
|
+
readonly _tag: "Field";
|
|
1629
|
+
readonly key: string;
|
|
1630
|
+
} | {
|
|
1631
|
+
readonly _tag: "Value";
|
|
1632
|
+
readonly value: unknown;
|
|
1633
|
+
}, {
|
|
1634
|
+
readonly _tag: Tag;
|
|
1635
|
+
}>) => any; }>(cases: Cases): (value: {
|
|
1636
|
+
readonly _tag: "Call";
|
|
1637
|
+
readonly operator: string;
|
|
1638
|
+
readonly args: ReadonlyArray<Computation>;
|
|
1639
|
+
readonly collation: Collation | null;
|
|
1640
|
+
} | {
|
|
1641
|
+
readonly _tag: "Field";
|
|
1642
|
+
readonly key: string;
|
|
1643
|
+
} | {
|
|
1644
|
+
readonly _tag: "Value";
|
|
1645
|
+
readonly value: unknown;
|
|
1646
|
+
}) => import("effect/Unify").Unify<ReturnType<Cases["Call" | "Field" | "Value"]>>;
|
|
1647
|
+
<Cases extends { readonly [Tag in "Call" | "Field" | "Value"]: (args: Extract<{
|
|
1648
|
+
readonly _tag: "Call";
|
|
1649
|
+
readonly operator: string;
|
|
1650
|
+
readonly args: ReadonlyArray<Computation>;
|
|
1651
|
+
readonly collation: Collation | null;
|
|
1652
|
+
} | {
|
|
1653
|
+
readonly _tag: "Field";
|
|
1654
|
+
readonly key: string;
|
|
1655
|
+
} | {
|
|
1656
|
+
readonly _tag: "Value";
|
|
1657
|
+
readonly value: unknown;
|
|
1658
|
+
}, {
|
|
1659
|
+
readonly _tag: Tag;
|
|
1660
|
+
}>) => any; }>(value: {
|
|
1661
|
+
readonly _tag: "Call";
|
|
1662
|
+
readonly operator: string;
|
|
1663
|
+
readonly args: ReadonlyArray<Computation>;
|
|
1664
|
+
readonly collation: Collation | null;
|
|
1665
|
+
} | {
|
|
1666
|
+
readonly _tag: "Field";
|
|
1667
|
+
readonly key: string;
|
|
1668
|
+
} | {
|
|
1669
|
+
readonly _tag: "Value";
|
|
1670
|
+
readonly value: unknown;
|
|
1671
|
+
}, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Call" | "Field" | "Value"]>>;
|
|
1672
|
+
};
|
|
1673
|
+
readonly Call: Data.TaggedEnum.ConstructorFrom<{
|
|
1674
|
+
readonly _tag: "Call";
|
|
1675
|
+
readonly operator: string;
|
|
1676
|
+
readonly args: ReadonlyArray<Computation>;
|
|
1677
|
+
readonly collation: Collation | null;
|
|
1678
|
+
}, "_tag">;
|
|
1679
|
+
readonly Field: Data.TaggedEnum.ConstructorFrom<{
|
|
1680
|
+
readonly _tag: "Field";
|
|
1681
|
+
readonly key: string;
|
|
1682
|
+
}, "_tag">;
|
|
1683
|
+
readonly Value: Data.TaggedEnum.ConstructorFrom<{
|
|
1684
|
+
readonly _tag: "Value";
|
|
1685
|
+
readonly value: unknown;
|
|
1686
|
+
}, "_tag">;
|
|
1687
|
+
};
|
|
777
1688
|
/** One input key the write points at another row with: a `one` relation, by the target's id. */
|
|
778
1689
|
interface WriteLink {
|
|
779
1690
|
readonly key: string;
|
|
@@ -809,7 +1720,9 @@ interface Write<E extends AnyEntity, Fields extends Schema.Struct.Fields> {
|
|
|
809
1720
|
* The fields it moves by an amount the input holds (`stock + quantity`),
|
|
810
1721
|
* computed where the write commits: the input key, and the field it moves.
|
|
811
1722
|
*/
|
|
812
|
-
readonly increments: ReadonlyArray<
|
|
1723
|
+
readonly increments: ReadonlyArray<WriteIncrement>;
|
|
1724
|
+
/** The fields it computes, each from the row before the write and the input. */
|
|
1725
|
+
readonly assignments: ReadonlyArray<WriteAssignment>;
|
|
813
1726
|
/** The `one` relations it points elsewhere, in the input's order. */
|
|
814
1727
|
readonly links: ReadonlyArray<WriteLink>;
|
|
815
1728
|
}
|
|
@@ -826,9 +1739,19 @@ interface RowOptions<Fields extends Schema.Struct.Fields> {
|
|
|
826
1739
|
type NumberKeys<Fields> = { [K in keyof Fields & string]: Fields[K] extends Schema.Top ? Schema.Schema.Type<Fields[K]> extends number ? K : never : never; }[keyof Fields & string];
|
|
827
1740
|
/** An update's increments: a number field of the Entity, by the input key holding the amount. */
|
|
828
1741
|
type WriteIncrements<E extends AnyEntity, Fields extends Schema.Struct.Fields> = { readonly [K in NumberKeys<{ [F in keyof E['fields']]: E['fields'][F]['schema']; }>]?: NumberKeys<Fields>; };
|
|
829
|
-
/**
|
|
1742
|
+
/**
|
|
1743
|
+
* An update's computed fields: each a field of the Entity, by what it comes
|
|
1744
|
+
* to over the row before the write (`row`, each field as `Expr.field`) and
|
|
1745
|
+
* the input. Its kind is checked against the field's where it is declared.
|
|
1746
|
+
*/
|
|
1747
|
+
type WriteComputations<E extends AnyEntity, Fields extends Schema.Struct.Fields> = { readonly [F in keyof E['fields'] & string]?: (context: {
|
|
1748
|
+
readonly row: BeforeRow<E>;
|
|
1749
|
+
readonly input: { readonly [K in keyof Fields & string]: InputExpr<Schema.Schema.Type<Fields[K]>>; };
|
|
1750
|
+
}) => AnyExpr; };
|
|
1751
|
+
/** An update's options: a row's, what it moves by an amount, and what it computes. */
|
|
830
1752
|
type UpdateOptions<E extends AnyEntity, Fields extends Schema.Struct.Fields> = RowOptions<Fields> & {
|
|
831
1753
|
readonly increment?: WriteIncrements<E, Fields>;
|
|
1754
|
+
readonly compute?: WriteComputations<E, Fields>;
|
|
832
1755
|
};
|
|
833
1756
|
/** `update`: conditioned when given `when`, which the overloads tell apart. */
|
|
834
1757
|
interface UpdateWrite {
|
|
@@ -869,6 +1792,8 @@ interface BoundWrite {
|
|
|
869
1792
|
readonly links: Readonly<Record<string, Option.Option<EntityRef>>>;
|
|
870
1793
|
/** Each field it moves, by the amount, encoded: added by the server, and predicted over what a client holds. */
|
|
871
1794
|
readonly increments: Readonly<Record<string, number>>;
|
|
1795
|
+
/** Each field it computes, as data: run by the server where it writes, predicted by a client. */
|
|
1796
|
+
readonly assignments: Readonly<Record<string, Computation>>;
|
|
872
1797
|
}
|
|
873
1798
|
declare const Write: {
|
|
874
1799
|
/**
|
|
@@ -888,6 +1813,12 @@ declare const Write: {
|
|
|
888
1813
|
* `when` is what the row must hold for the update to land, checked where it
|
|
889
1814
|
* commits (`({ input }) => Expr.eq(Post.fields.status, 'draft')`); a row it
|
|
890
1815
|
* does not hold of is refused as unmet.
|
|
1816
|
+
*
|
|
1817
|
+
* `compute` sets a field to what an expression comes to over the row before
|
|
1818
|
+
* the write and the input, run where it commits
|
|
1819
|
+
* (`{ label: ({ row }) => concat(row.title, ' draft') }`). It is refused for
|
|
1820
|
+
* a field another key writes, an expression over the row after the write or
|
|
1821
|
+
* another Entity, or one of a kind the field does not store.
|
|
891
1822
|
*/
|
|
892
1823
|
update: UpdateWrite;
|
|
893
1824
|
/**
|
|
@@ -919,8 +1850,9 @@ declare const Write: {
|
|
|
919
1850
|
writes: (write: AnyWrite) => ReadonlyArray<AnyField | OneRelation>;
|
|
920
1851
|
/**
|
|
921
1852
|
* The fields a write reads from the row it writes: those its `when` reads,
|
|
922
|
-
* each it increments, and the revision it
|
|
923
|
-
* must read, and what a startup check judges
|
|
1853
|
+
* each it increments, each its assignments read, and the revision it
|
|
1854
|
+
* expects. What an interpreter must read, and what a startup check judges
|
|
1855
|
+
* it could disclose.
|
|
924
1856
|
*/
|
|
925
1857
|
reads: (write: AnyWrite) => ReadonlyArray<AnyField>;
|
|
926
1858
|
/**
|
|
@@ -930,9 +1862,27 @@ declare const Write: {
|
|
|
930
1862
|
* the input is still the whole, validated value.
|
|
931
1863
|
*/
|
|
932
1864
|
bind: <Fields extends Schema.Struct.Fields>(write: Write<AnyEntity, Fields>, value: Schema.Struct.Type<Fields>, keys?: ReadonlyArray<string>) => BoundWrite;
|
|
1865
|
+
/**
|
|
1866
|
+
* The fields of the row before it that a bound write's amounts and
|
|
1867
|
+
* assignments read: what to read to work out the row it leaves.
|
|
1868
|
+
*/
|
|
1869
|
+
boundReads: (bound: Pick<BoundWrite, 'increments' | 'assignments'>) => ReadonlyArray<string>;
|
|
1870
|
+
/**
|
|
1871
|
+
* The row a bound write leaves over `row`, the row before it: its values
|
|
1872
|
+
* set, each amount added (a null stays null, as in SQL), and each
|
|
1873
|
+
* assignment computed by `operators` over the row before. `unknown` names
|
|
1874
|
+
* each field it could not work out: one `row` lacks, or holds as no number
|
|
1875
|
+
* for an amount, or an assignment calling an operator the table lacks. That
|
|
1876
|
+
* field keeps what `row` holds. The one computation of this row: a guard
|
|
1877
|
+
* judges it, a writer explains a miss with it, a client predicts it.
|
|
1878
|
+
*/
|
|
1879
|
+
apply: (row: Readonly<Record<string, unknown>>, bound: Pick<BoundWrite, 'values' | 'increments' | 'assignments'>, options: {
|
|
1880
|
+
readonly operators: MemoryOperators;
|
|
1881
|
+
}) => {
|
|
1882
|
+
readonly row: Readonly<Record<string, unknown>>;
|
|
1883
|
+
readonly unknown: ReadonlyArray<string>;
|
|
1884
|
+
};
|
|
933
1885
|
};
|
|
934
|
-
//#endregion
|
|
935
|
-
//#region src/index.d.ts
|
|
936
1886
|
declare const EntityTypeId: unique symbol;
|
|
937
1887
|
type EntityTypeId = typeof EntityTypeId;
|
|
938
1888
|
/**
|
|
@@ -1274,6 +2224,5 @@ declare const Relation: {
|
|
|
1274
2224
|
declare const Derived: {
|
|
1275
2225
|
make: <S extends Schema.Constraint>(schema: S) => DerivedSpec<S>;
|
|
1276
2226
|
};
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
//# sourceMappingURL=index-BhI_DA2S.d.mts.map
|
|
2227
|
+
export { Text as $, Operator as $t, SelectionPage as A, AnyQuery as At, Computation as B, EqPredicate as Bt, Relation as C, Law as Cn, MemoryOperators as Ct, RelationSpecs as D, TestedEvidence as Dt, RelationSpec as E, Collation as En, Operators as Et, WrittenAs as F, ChosenSort as Ft, WriteCondition as G, InputExpr as Gt, Write as H, FieldDependency as Ht, WrittenKey as I, CompareOperator as It, WriteSet as J, NextExpr as Jt, WriteIncrement as K, Invalid as Kt, WrittenSpec as L, ComparePredicate as Lt, SelectionTypeId as M, CallExpr as Mt, TargetKey as N, CallOptions as Nt, Selected as O, AndPredicate as Ot, Unmapped as P, ChosenOrder as Pt, ReadFilter as Q, Operation as Qt, AnyWrite as R, ContainsPredicate as Rt, RelatedSpecs as S, noOperators as Sn, MemoryImplementation as St, RelationMap as T, Side as Tn, OperatorDescription as Tt, WriteAssignment as U, FieldExpr as Ut, ConditionedWrite as V, Expr as Vt, WriteComputations as W, InPredicate as Wt, SchemaWords as X, NullPredicate as Xt, SchemaShape as Y, NotPredicate as Yt, Words as Z, Operandish as Zt, IdSchemaOf as _, ValueOf as _n, supported as _t, DerivedSpecs as a, OrderedOperand as an, Judgement as at, PageWindow as b, maxQueryNodes as bn, Evidence as bt, EntityDerived as c, Placement as cn, PredicateTruth as ct, EntityInput as d, QueryDependencies as dn, applyOperator as dt, OperatorDescriptor as en, AfterRow as et, EntityMember as f, Reads as fn, assertSupported as ft, IdOf as g, TextOperand as gn, evaluateEach as gt, EntityTypeId as h, TestPredicate as hn, evaluate as ht, DerivedSpec as i, OrderTerm as in, Invariant as it, SelectionPageTypeId as j, ArgumentOf as jt, Selection as k, AnyExpr as kt, EntityField as l, Predicate as ln, QueryEvaluateError as lt, EntityRelation as m, TermOptions as mn, decided as mt, Cardinality as n, OrPredicate as nn, Change as nt, Entities as o, Ordering as on, Evaluated as ot, EntityRef as p, ReadsOf as pn, compareRows as pt, WriteLink as q, LiteralExpr as qt, Derived as r, Order as rn, DeclaredInvariant as rt, Entity as s, ParameterOf as sn, OperatorMissingError as st, AnyEntity as t, OperatorTable as tn, BeforeRow as tt, EntityIdentity as u, Query as un, Row as ut, InputMember as v, dependenciesOf as vn, truthOver as vt, RelationInput as w, LawDescription as wn, OperatorContext as wt, Related as x, missingName as xn, ImplementedOperator as xt, NestedInput as y, isPredicate as yn, valueOfOperand as yt, BoundWrite as z, Dependencies as zt };
|
|
2228
|
+
//# sourceMappingURL=index-hu8IYlNc.d.mts.map
|