foldkit-entity 0.7.0 → 0.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +108 -6
- package/dist/conformance/index.d.mts +12 -1
- package/dist/conformance/index.d.mts.map +1 -1
- package/dist/conformance/index.mjs +218 -2
- package/dist/conformance/index.mjs.map +1 -1
- package/dist/index-DLz2yED-.d.mts +919 -0
- package/dist/index-DLz2yED-.d.mts.map +1 -0
- package/dist/index.d.mts +2 -642
- package/dist/index.mjs +2 -877
- package/dist/src-BAA6oWw-.mjs +1339 -0
- package/dist/src-BAA6oWw-.mjs.map +1 -0
- package/package.json +1 -1
- package/dist/index.d.mts.map +0 -1
- package/dist/index.mjs.map +0 -1
|
@@ -0,0 +1,919 @@
|
|
|
1
|
+
import { Option, Pipeable, Schema, SchemaAST } from "effect";
|
|
2
|
+
import { Metadata } from "foldkit-metadata";
|
|
3
|
+
//#region src/collation.d.ts
|
|
4
|
+
type Collation =
|
|
5
|
+
/** By code point: SQLite `BINARY`, Postgres `COLLATE "C"`. */
|
|
6
|
+
{
|
|
7
|
+
readonly _tag: 'Binary';
|
|
8
|
+
} |
|
|
9
|
+
/** ASCII letters folded to lower case, then by code point: SQLite `NOCASE`, Postgres `lower(x COLLATE "C")`. */
|
|
10
|
+
{
|
|
11
|
+
readonly _tag: 'AsciiFold';
|
|
12
|
+
} |
|
|
13
|
+
/** The backend's collation by this name: ordered by the server, never by a client. */
|
|
14
|
+
{
|
|
15
|
+
readonly _tag: 'Locale';
|
|
16
|
+
readonly locale: string;
|
|
17
|
+
};
|
|
18
|
+
declare const Collation: {
|
|
19
|
+
binary: Collation;
|
|
20
|
+
asciiFold: Collation;
|
|
21
|
+
locale: (locale: string) => Collation;
|
|
22
|
+
/** Member metadata: how a text field orders, wherever a query orders by it. */
|
|
23
|
+
of: (collation: Collation) => Metadata;
|
|
24
|
+
/** The collation a member's metadata declares, if any. */
|
|
25
|
+
declared: (metadata: Metadata) => Option.Option<Collation>;
|
|
26
|
+
};
|
|
27
|
+
//#endregion
|
|
28
|
+
//#region src/expr.d.ts
|
|
29
|
+
/** A constant the query was written with. */
|
|
30
|
+
interface LiteralExpr<T> {
|
|
31
|
+
readonly _tag: 'Literal';
|
|
32
|
+
readonly value: T;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* One field of one Entity. `owner` is the Entity's identity rather than its
|
|
36
|
+
* name, so two Entities defined with the same name are not one column.
|
|
37
|
+
*/
|
|
38
|
+
interface FieldExpr<T> {
|
|
39
|
+
readonly _tag: 'Field';
|
|
40
|
+
readonly owner: EntityIdentity<string>;
|
|
41
|
+
readonly key: string;
|
|
42
|
+
readonly schema: Schema.Codec<T, unknown>;
|
|
43
|
+
/**
|
|
44
|
+
* How it compares when ordered by, as the field declares (`Collation.of`).
|
|
45
|
+
* An id is `binary` unless it says otherwise: its order need only be total
|
|
46
|
+
* and agreed, and every order ends on it.
|
|
47
|
+
*/
|
|
48
|
+
readonly collation: Option.Option<Collation>;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* A value the query is given when it runs. A definition's body is built once,
|
|
52
|
+
* so inside it an input is this placeholder and never the value: there is
|
|
53
|
+
* nothing yet to branch on, and a query that wants to depend on what was passed
|
|
54
|
+
* says so with an operation over the placeholder.
|
|
55
|
+
*/
|
|
56
|
+
interface InputExpr<T> {
|
|
57
|
+
readonly _tag: 'Input';
|
|
58
|
+
readonly key: string;
|
|
59
|
+
readonly schema: Schema.Codec<T, unknown>;
|
|
60
|
+
}
|
|
61
|
+
/** A typed scalar: what a comparison compares. */
|
|
62
|
+
type Expr<T> = LiteralExpr<T> | FieldExpr<T> | InputExpr<T>;
|
|
63
|
+
/** Any scalar, for the places that hold operands without caring what they are. */
|
|
64
|
+
type AnyExpr = Expr<unknown>;
|
|
65
|
+
/**
|
|
66
|
+
* `Expr<boolean>`, in the shape the operations that exist can actually take.
|
|
67
|
+
* The design's kernel is all boolean-valued (`eq`, `and`, `isNull`,
|
|
68
|
+
* `contains`, …), so a predicate is its own type rather than a phantom
|
|
69
|
+
* parameter on a general operation node: `Predicate` and `Expr<string>` cannot
|
|
70
|
+
* then be confused, which a structural phantom would allow. A scalar-valued
|
|
71
|
+
* operation, if one is ever needed, joins `Expr` instead.
|
|
72
|
+
*/
|
|
73
|
+
type Predicate = EqPredicate | NullPredicate | ContainsPredicate | InPredicate;
|
|
74
|
+
/** Two values are the same. */
|
|
75
|
+
interface EqPredicate {
|
|
76
|
+
readonly _tag: 'Eq';
|
|
77
|
+
readonly left: Operandish;
|
|
78
|
+
readonly right: Operandish;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Whether a value is absent. `present` says which answer absence gives, so one
|
|
82
|
+
* node covers `is null` and `is not null` rather than two that differ by a
|
|
83
|
+
* negation nothing else can express.
|
|
84
|
+
*/
|
|
85
|
+
interface NullPredicate {
|
|
86
|
+
readonly _tag: 'Null';
|
|
87
|
+
readonly operand: AnyExpr;
|
|
88
|
+
readonly present: boolean;
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Whether a text value contains another. Containing the empty string is
|
|
92
|
+
* everything, which is what lets a search box with nothing typed in it be the
|
|
93
|
+
* same query as one with something — see `Expr.contains`.
|
|
94
|
+
*/
|
|
95
|
+
interface ContainsPredicate {
|
|
96
|
+
readonly _tag: 'Contains';
|
|
97
|
+
readonly value: AnyExpr;
|
|
98
|
+
readonly search: Operandish;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Whether a value is one of a list. The list is a scalar whose value is an
|
|
102
|
+
* array: a literal, or an input (a principal's `projectIds`, a picker's
|
|
103
|
+
* chosen ids). Read as SQL's `in`: a null value is unknown, and so is no
|
|
104
|
+
* match against a list holding a null; an empty list matches nothing.
|
|
105
|
+
*/
|
|
106
|
+
interface InPredicate {
|
|
107
|
+
readonly _tag: 'In';
|
|
108
|
+
readonly value: AnyExpr;
|
|
109
|
+
readonly among: AnyExpr;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Anything an operation can be given: a scalar, or a predicate where a boolean
|
|
113
|
+
* is wanted. `Expr.eq(Expr.isNotNull(archivedAt), input.archived)` is the
|
|
114
|
+
* second case, and it is how a query depends on an input without branching on
|
|
115
|
+
* it.
|
|
116
|
+
*/
|
|
117
|
+
type Operandish = AnyExpr | Predicate;
|
|
118
|
+
/** A field, a scalar already built from one, or a predicate used as a boolean. */
|
|
119
|
+
type Operand<T> = EntityField<string, string, Schema.Constraint> | Expr<T> | Predicate;
|
|
120
|
+
/** What an operand is worth, so a comparison's other side is checked against it. */
|
|
121
|
+
type ValueOf<E> = E extends EntityField<string, string, infer S> ? Schema.Schema.Type<S> : E extends Predicate ? boolean : E extends Expr<infer T> ? T : never;
|
|
122
|
+
/**
|
|
123
|
+
* A field or scalar whose value is text, or absent text.
|
|
124
|
+
*
|
|
125
|
+
* `Expr.contains` is a case-insensitive **text** search that compiles to
|
|
126
|
+
* `lower(column) like lower(?)`. Over a number that is nonsense which reaches
|
|
127
|
+
* the database — SQLite coerces and answers something, Postgres raises — so
|
|
128
|
+
* the operand is constrained here rather than discovered there.
|
|
129
|
+
*
|
|
130
|
+
* Null belongs in the type, because a nullable text column is a real and
|
|
131
|
+
* documented case: a null contains nothing, not even the empty string, so its
|
|
132
|
+
* rows drop out of a search that would otherwise match everything.
|
|
133
|
+
*
|
|
134
|
+
* Written as a **constraint on the type parameter** rather than as a check
|
|
135
|
+
* intersected onto the parameter (the `Invalid` idiom `foldkit-remote` uses for
|
|
136
|
+
* an unregistered descriptor). That idiom compares an already-resolved indexed
|
|
137
|
+
* access; here the check would be a conditional over the type being inferred,
|
|
138
|
+
* and inference falls back to the constraint — whose `Expr<any>` branch makes
|
|
139
|
+
* the check vacuously true, so every operand passes. A constraint cannot be
|
|
140
|
+
* defeated that way.
|
|
141
|
+
*/
|
|
142
|
+
type TextOperand = EntityField<string, string, Schema.Constraint & Schema.Codec<string | null, any, any, any>> | Expr<string> | Expr<string | null>;
|
|
143
|
+
/** Whether a value is a predicate, and so usable where a boolean is wanted. */
|
|
144
|
+
declare const isPredicate: (value: unknown) => value is Predicate;
|
|
145
|
+
/**
|
|
146
|
+
* Every operation the kernel has. An interpreter declares which of them it
|
|
147
|
+
* runs, and a body needing one it does not is refused rather than answered
|
|
148
|
+
* wrongly — see `Query.unsupported`.
|
|
149
|
+
*/
|
|
150
|
+
type Operation = 'eq' | 'isNull' | 'isNotNull' | 'contains' | 'in';
|
|
151
|
+
/** One field an expression reads: its Entity's name and key, and the identity that owns it. */
|
|
152
|
+
interface FieldDependency {
|
|
153
|
+
/** The owning Entity's name, for display; two Entities may share one. */
|
|
154
|
+
readonly entity: string;
|
|
155
|
+
readonly key: string;
|
|
156
|
+
/** Which Entity it is. Two defined with the same name are two entries. */
|
|
157
|
+
readonly owner: EntityIdentity<string>;
|
|
158
|
+
}
|
|
159
|
+
/** Which fields and inputs an expression reads, and which operations it uses. */
|
|
160
|
+
interface Dependencies {
|
|
161
|
+
/** One entry per distinct field of each Entity identity. */
|
|
162
|
+
readonly fields: ReadonlyArray<FieldDependency>;
|
|
163
|
+
/** One entry per distinct input key. */
|
|
164
|
+
readonly inputs: ReadonlyArray<string>;
|
|
165
|
+
/** One entry per distinct operation, so an interpreter can refuse what it cannot run. */
|
|
166
|
+
readonly operations: ReadonlyArray<Operation>;
|
|
167
|
+
}
|
|
168
|
+
/**
|
|
169
|
+
* What a query reads, with each field's role. A change to a `predicate` field
|
|
170
|
+
* can move a row into or out of the result; a change to an `order` field can
|
|
171
|
+
* move it within. A field in both is in both; `fields` is their union.
|
|
172
|
+
*/
|
|
173
|
+
interface QueryDependencies extends Dependencies {
|
|
174
|
+
readonly predicate: ReadonlyArray<FieldDependency>;
|
|
175
|
+
readonly order: ReadonlyArray<FieldDependency>;
|
|
176
|
+
}
|
|
177
|
+
declare const Expr: {
|
|
178
|
+
/** A constant. Comparisons coerce a plain value, so this is rarely written. */
|
|
179
|
+
literal: <T>(value: T) => LiteralExpr<T>;
|
|
180
|
+
/**
|
|
181
|
+
* A value the query is given when it runs. A definition builds these from its
|
|
182
|
+
* `Input` schema; written by hand only when constructing a body directly.
|
|
183
|
+
*/
|
|
184
|
+
input: <T>(key: string, schema: Schema.Codec<T, unknown>) => InputExpr<T>;
|
|
185
|
+
/** One field of one Entity, as a scalar. */
|
|
186
|
+
field: <Name extends string, Key extends string, S extends Schema.Constraint>(field: EntityField<Name, Key, S>) => FieldExpr<Schema.Schema.Type<S>>;
|
|
187
|
+
/**
|
|
188
|
+
* Two scalars are the same value. A field or a plain value on either side is
|
|
189
|
+
* coerced, so the common form reads as it means:
|
|
190
|
+
*
|
|
191
|
+
* ```ts
|
|
192
|
+
* Expr.eq(Post.fields.slug, input.slug)
|
|
193
|
+
* Expr.eq(Post.fields.status, 'active')
|
|
194
|
+
* ```
|
|
195
|
+
*/
|
|
196
|
+
eq: <L extends Operand<any>>(left: L, right: ValueOf<L> | Expr<ValueOf<L>> | (boolean extends ValueOf<L> ? Predicate : never)) => EqPredicate;
|
|
197
|
+
/**
|
|
198
|
+
* Whether a field holds no value. Its opposite is `isNotNull`; both are the
|
|
199
|
+
* one node, because a query asks which of the two it means and nothing here
|
|
200
|
+
* can negate a predicate.
|
|
201
|
+
*/
|
|
202
|
+
isNull: <L extends Operand<any>>(operand: L) => NullPredicate;
|
|
203
|
+
/** Whether a field holds a value. */
|
|
204
|
+
isNotNull: <L extends Operand<any>>(operand: L) => NullPredicate;
|
|
205
|
+
/**
|
|
206
|
+
* Whether a text value contains `search`, anywhere in it. Containing the
|
|
207
|
+
* empty string is everything, so a search box with nothing typed in it is the
|
|
208
|
+
* same query as one with something — no branch, and no second query.
|
|
209
|
+
*
|
|
210
|
+
* **Case-insensitive**, which is what a search means, and which has to be
|
|
211
|
+
* said rather than left to the interpreter: SQLite's `like` ignores case and
|
|
212
|
+
* Postgres's does not, so a body that left it open would mean two things.
|
|
213
|
+
* Folding is ASCII-only, because that is what `lower` does in SQLite without
|
|
214
|
+
* ICU.
|
|
215
|
+
*
|
|
216
|
+
* **Over a column that can be null this is not the same as no filter.** A
|
|
217
|
+
* null contains nothing, not even the empty string, so its rows drop out. A
|
|
218
|
+
* nullable column that should match everything on an empty search says so:
|
|
219
|
+
* `Expr.or` does not exist yet, so for now such a column needs its own
|
|
220
|
+
* predicate or a native escape hatch.
|
|
221
|
+
*/
|
|
222
|
+
contains: <L extends TextOperand>(value: L, search: string | Expr<string>) => ContainsPredicate;
|
|
223
|
+
/**
|
|
224
|
+
* Whether a value is one of `among`: a list written out, or an input whose
|
|
225
|
+
* value is one. Each element is compared as `eq` compares.
|
|
226
|
+
*
|
|
227
|
+
* ```ts
|
|
228
|
+
* Expr.in(Todo.fields.projectId, input.projectIds)
|
|
229
|
+
* Expr.in(Todo.fields.status, ['open', 'blocked'])
|
|
230
|
+
* ```
|
|
231
|
+
*
|
|
232
|
+
* As SQL's `in`: a null value is unknown, as is no match against a list
|
|
233
|
+
* holding a null, and an empty list matches no row. A list written out is
|
|
234
|
+
* copied, so changing the array afterwards does not change the query.
|
|
235
|
+
*/
|
|
236
|
+
in: <L extends Operand<any>>(value: L, among: ReadonlyArray<ValueOf<L>> | Expr<ReadonlyArray<ValueOf<L>>>) => InPredicate;
|
|
237
|
+
/** An expression as readable text; see `showExpr` for what it is and is not. */
|
|
238
|
+
show: (node: Operandish) => string;
|
|
239
|
+
};
|
|
240
|
+
/** One term of an ordering: a scalar and the direction to read it in. */
|
|
241
|
+
interface OrderTerm {
|
|
242
|
+
readonly _tag: 'Term';
|
|
243
|
+
readonly direction: 'asc' | 'desc';
|
|
244
|
+
readonly expr: AnyExpr;
|
|
245
|
+
/**
|
|
246
|
+
* Where rows without a value go, in the term's own direction. Databases
|
|
247
|
+
* disagree when it is left unsaid (Postgres puts them last ascending, SQLite
|
|
248
|
+
* first), so it is always said: last ascending and first descending unless
|
|
249
|
+
* a term asks otherwise, which is Postgres's.
|
|
250
|
+
*/
|
|
251
|
+
readonly nulls: 'first' | 'last';
|
|
252
|
+
/**
|
|
253
|
+
* How text compares, when the term orders text: the term's own, or its
|
|
254
|
+
* field's. None leaves it to the backend, which a client cannot match.
|
|
255
|
+
*/
|
|
256
|
+
readonly collation: Option.Option<Collation>;
|
|
257
|
+
}
|
|
258
|
+
/** What a term may say besides its operand. */
|
|
259
|
+
interface TermOptions {
|
|
260
|
+
readonly nulls?: 'first' | 'last' | undefined;
|
|
261
|
+
/** Overrides the field's declared collation for this term. */
|
|
262
|
+
readonly collation?: Collation | undefined;
|
|
263
|
+
}
|
|
264
|
+
/** How a list is sorted, as its input holds it: one of its named orders, which way, or none. */
|
|
265
|
+
type ChosenSort<By extends string> = {
|
|
266
|
+
readonly by: By;
|
|
267
|
+
readonly direction: 'asc' | 'desc';
|
|
268
|
+
} | null;
|
|
269
|
+
/**
|
|
270
|
+
* An ordering the input chooses: one of several named fields, which way, or
|
|
271
|
+
* none. It is how a list sorts by what its reader picked, said in the body, so
|
|
272
|
+
* the server and the client read one declaration of what each name means.
|
|
273
|
+
*/
|
|
274
|
+
interface ChosenOrder {
|
|
275
|
+
readonly _tag: 'Chosen';
|
|
276
|
+
readonly sort: InputExpr<ChosenSort<string>>;
|
|
277
|
+
readonly choices: Readonly<Record<string, FieldExpr<unknown>>>;
|
|
278
|
+
}
|
|
279
|
+
/** One entry of a body's ordering: fixed, or chosen by the input. */
|
|
280
|
+
type Ordering = OrderTerm | ChosenOrder;
|
|
281
|
+
declare const Order: {
|
|
282
|
+
/** Smallest first; rows without a value last, unless `nulls` says first. */
|
|
283
|
+
asc: <E extends Operand<any>>(expr: E, options?: TermOptions) => OrderTerm;
|
|
284
|
+
/** Largest first; rows without a value first, unless `nulls` says last. */
|
|
285
|
+
desc: <E extends Operand<any>>(expr: E, options?: TermOptions) => OrderTerm;
|
|
286
|
+
/**
|
|
287
|
+
* The order the input names, among `choices`: every name the sort can hold
|
|
288
|
+
* maps to a field, so a name left out is a type error here, not a query that
|
|
289
|
+
* silently orders by nothing. A `null` sort chooses none, and the terms after
|
|
290
|
+
* it decide.
|
|
291
|
+
*
|
|
292
|
+
* ```ts
|
|
293
|
+
* Query.orderBy(Order.chosen(input.sort, { title: Post.fields.title }))
|
|
294
|
+
* ```
|
|
295
|
+
*/
|
|
296
|
+
chosen: <By extends string>(sort: InputExpr<ChosenSort<By>>, choices: { readonly [K in By]: Operand<any>; }) => ChosenOrder;
|
|
297
|
+
};
|
|
298
|
+
/**
|
|
299
|
+
* Whether a client can order rows the way the server does, for one input: the
|
|
300
|
+
* answer `Query.placement` gives, and the reason when it cannot.
|
|
301
|
+
*/
|
|
302
|
+
type Placement = {
|
|
303
|
+
readonly _tag: 'Placeable';
|
|
304
|
+
} | {
|
|
305
|
+
readonly _tag: 'NotPlaceable';
|
|
306
|
+
readonly reason: string;
|
|
307
|
+
};
|
|
308
|
+
/**
|
|
309
|
+
* What an expression reads and uses, for the planner and for an interpreter
|
|
310
|
+
* deciding whether it can run this query at all. Distinct entries only, in the
|
|
311
|
+
* order first seen, so the answer is stable enough to assert on.
|
|
312
|
+
*/
|
|
313
|
+
declare const dependenciesOf: (...nodes: ReadonlyArray<AnyExpr | Predicate | Ordering>) => Dependencies;
|
|
314
|
+
/**
|
|
315
|
+
* Which rows a query is about, as a value: an Entity to read, the predicates
|
|
316
|
+
* every row must satisfy, and the order to read them in. It says nothing about
|
|
317
|
+
* which fields to return — that is a Selection — and nothing about pagination,
|
|
318
|
+
* liveness, or whether absence is an error, which belong to the consumer's read
|
|
319
|
+
* rather than to the relation.
|
|
320
|
+
*
|
|
321
|
+
* Composing one performs no work. `Query.from(Post)` names no table and opens
|
|
322
|
+
* no connection; an interpreter turns the value into a query when something
|
|
323
|
+
* asks it to.
|
|
324
|
+
*/
|
|
325
|
+
interface Query<E extends AnyEntity> extends Pipeable.Pipeable {
|
|
326
|
+
readonly _tag: 'Query';
|
|
327
|
+
readonly entity: E;
|
|
328
|
+
/**
|
|
329
|
+
* Every predicate holds: the list *is* the conjunction. Keeping it a list
|
|
330
|
+
* rather than folding it into one `and` is what makes each `where` a reusable
|
|
331
|
+
* fragment, and it means no `Expr.and` exists until a query needs a
|
|
332
|
+
* conjunction nested inside something else.
|
|
333
|
+
*/
|
|
334
|
+
readonly where: ReadonlyArray<Predicate>;
|
|
335
|
+
/** In order of significance; a later `orderBy` appends less significant terms. */
|
|
336
|
+
readonly orderBy: ReadonlyArray<Ordering>;
|
|
337
|
+
}
|
|
338
|
+
/** A `Query` over any Entity, for the places that hold one without caring which. */
|
|
339
|
+
type AnyQuery = Query<AnyEntity>;
|
|
340
|
+
/**
|
|
341
|
+
* The most nodes a query's predicates may hold once every shared node is
|
|
342
|
+
* counted on each path that reaches it. Interpreters read a predicate as a
|
|
343
|
+
* tree: `evaluate` once per row, and the SQL compiler into text that repeats a
|
|
344
|
+
* shared operand wherever it appears. So `eq(n, n)` nested thirty deep is
|
|
345
|
+
* thirty-one objects and a billion nodes of work. Real queries are tens.
|
|
346
|
+
*/
|
|
347
|
+
declare const maxQueryNodes = 1000;
|
|
348
|
+
declare const Query: {
|
|
349
|
+
/** Every row of an Entity: the query each transformation narrows. */
|
|
350
|
+
from: <E extends AnyEntity>(entity: E) => Query<E>;
|
|
351
|
+
/**
|
|
352
|
+
* Narrows to the rows the predicate holds for. Two `where`s conjoin — the
|
|
353
|
+
* second never replaces the first — so a fragment can be written once and
|
|
354
|
+
* piped into any query over the same Entity:
|
|
355
|
+
*
|
|
356
|
+
* ```ts
|
|
357
|
+
* const published = Query.where(Expr.eq(Post.fields.published, true))
|
|
358
|
+
* Query.from(Post).pipe(published, Query.where(byTitle))
|
|
359
|
+
* ```
|
|
360
|
+
*/
|
|
361
|
+
where: (...predicates: ReadonlyArray<Predicate>) => <E extends AnyEntity>(self: Query<E>) => Query<E>;
|
|
362
|
+
/**
|
|
363
|
+
* Reads the rows in this order. Two `orderBy`s append, so an earlier term
|
|
364
|
+
* stays the more significant one and a later call adds a tie-breaker rather
|
|
365
|
+
* than silently winning.
|
|
366
|
+
*/
|
|
367
|
+
orderBy: (...terms: ReadonlyArray<Ordering>) => <E extends AnyEntity>(self: Query<E>) => Query<E>;
|
|
368
|
+
/**
|
|
369
|
+
* The fixed terms this query orders by for one input: each chosen order
|
|
370
|
+
* resolved to the field its input names, or to nothing for a `null` sort,
|
|
371
|
+
* and the Entity's id last, ascending, unless the terms already read it. So
|
|
372
|
+
* the order is total, and every interpreter breaks ties the same way: one
|
|
373
|
+
* that broke them its own way would place rows a step apart from another.
|
|
374
|
+
*/
|
|
375
|
+
orderFor: (self: AnyQuery, input: Readonly<Record<string, unknown>>) => ReadonlyArray<OrderTerm>;
|
|
376
|
+
/**
|
|
377
|
+
* Whether a client can order this query's rows exactly as the server does,
|
|
378
|
+
* for one input: every term over a number or a boolean (a row may lack it), or over text with a
|
|
379
|
+
* portable collation (`binary`, `asciiFold`). A body that names no order
|
|
380
|
+
* leaves it to the server, and is never placeable.
|
|
381
|
+
*/
|
|
382
|
+
placement: (self: AnyQuery, input: Readonly<Record<string, unknown>>) => Placement;
|
|
383
|
+
/**
|
|
384
|
+
* What the whole query reads: the fields and inputs of every predicate and
|
|
385
|
+
* every ordering term, and the operations it uses, with the fields also
|
|
386
|
+
* split by role.
|
|
387
|
+
*/
|
|
388
|
+
dependencies: (self: AnyQuery) => QueryDependencies;
|
|
389
|
+
/**
|
|
390
|
+
* The operations this query needs that `supported` does not list, in the
|
|
391
|
+
* order the query uses them. Empty means an interpreter declaring
|
|
392
|
+
* `supported` can answer it.
|
|
393
|
+
*
|
|
394
|
+
* An interpreter declares what it runs and refuses the rest, rather than
|
|
395
|
+
* ignoring an operation it does not implement — which would answer a
|
|
396
|
+
* different question and say nothing. The refusal is the interpreter's to
|
|
397
|
+
* raise: this only says what is missing, because what to do about it differs
|
|
398
|
+
* between one that compiles at registration and one that runs a body
|
|
399
|
+
* directly.
|
|
400
|
+
*
|
|
401
|
+
* ```ts
|
|
402
|
+
* const missing = Query.unsupported(body, ['eq', 'isNull', 'isNotNull'])
|
|
403
|
+
* if (missing.length > 0) throw new Error(`cannot run ${missing.join(', ')}`)
|
|
404
|
+
* ```
|
|
405
|
+
*/
|
|
406
|
+
unsupported: (self: AnyQuery, supported: ReadonlyArray<Operation>) => ReadonlyArray<Operation>;
|
|
407
|
+
/**
|
|
408
|
+
* The whole query as readable text, one clause per line:
|
|
409
|
+
*
|
|
410
|
+
* ```text
|
|
411
|
+
* FROM Post
|
|
412
|
+
* WHERE Post.slug = $slug
|
|
413
|
+
* AND Post.published = true
|
|
414
|
+
* ORDER BY Post.updatedAt DESC
|
|
415
|
+
* ```
|
|
416
|
+
*
|
|
417
|
+
* For an explanation or a diagnostic, never for an interpreter — see
|
|
418
|
+
* `Expr.show`. A query with no `where` or no `orderBy` omits that line rather
|
|
419
|
+
* than printing an empty one, so what is shown is what was written.
|
|
420
|
+
*/
|
|
421
|
+
show: (self: AnyQuery) => string;
|
|
422
|
+
};
|
|
423
|
+
//#endregion
|
|
424
|
+
//#region src/readFilter.d.ts
|
|
425
|
+
declare const ReadFilter: {
|
|
426
|
+
/** Entity metadata: the rows the server lists depend on these members. */
|
|
427
|
+
of: (members: ReadonlyArray<string>) => Metadata;
|
|
428
|
+
/** The members an Entity's metadata names, every attachment's together. */
|
|
429
|
+
members: (metadata: Metadata) => ReadonlyArray<string>;
|
|
430
|
+
};
|
|
431
|
+
//#endregion
|
|
432
|
+
//#region src/words.d.ts
|
|
433
|
+
/** What a schema says of itself to a person: its `title` and `description`. */
|
|
434
|
+
interface SchemaWords {
|
|
435
|
+
readonly title: Option.Option<string>;
|
|
436
|
+
readonly description: Option.Option<string>;
|
|
437
|
+
}
|
|
438
|
+
declare const Words: {
|
|
439
|
+
/**
|
|
440
|
+
* A schema's words, as a label and its help text. Under Effect 4 a checked
|
|
441
|
+
* schema resolves to its last check's annotations, which say what the check
|
|
442
|
+
* expects and carry no `title`, so a title given before the check is read from
|
|
443
|
+
* the schema's own annotations. Read words through this, never through
|
|
444
|
+
* `Schema.resolveAnnotations` directly.
|
|
445
|
+
*/
|
|
446
|
+
of: (schema: Schema.Top) => SchemaWords;
|
|
447
|
+
};
|
|
448
|
+
//#endregion
|
|
449
|
+
//#region src/shape.d.ts
|
|
450
|
+
/** What a schema's AST holds, read through Effect's own guards. */
|
|
451
|
+
declare const SchemaShape: {
|
|
452
|
+
/** True for the `null` and `undefined` members that make a schema optional. */
|
|
453
|
+
isNullish: (ast: SchemaAST.AST) => boolean;
|
|
454
|
+
/**
|
|
455
|
+
* The members of a schema with `null` and `undefined` set aside, so optional
|
|
456
|
+
* text is still text; a schema that is not a union is its one member.
|
|
457
|
+
*/
|
|
458
|
+
present: (ast: SchemaAST.AST) => ReadonlyArray<SchemaAST.AST>;
|
|
459
|
+
/** True when every value the schema admits is a string. */
|
|
460
|
+
isText: (ast: SchemaAST.AST) => boolean;
|
|
461
|
+
};
|
|
462
|
+
//#endregion
|
|
463
|
+
//#region src/evaluate.d.ts
|
|
464
|
+
/** A row as this interpreter reads one: values by field key. */
|
|
465
|
+
type Row = Readonly<Record<string, unknown>>;
|
|
466
|
+
declare class QueryEvaluateError extends Error {
|
|
467
|
+
constructor(message: string);
|
|
468
|
+
}
|
|
469
|
+
/**
|
|
470
|
+
* Where `left` sorts against `right` under these terms (`Query.orderFor`'s),
|
|
471
|
+
* as `evaluate` sorts: negative when it comes first. Refuses what `evaluate`
|
|
472
|
+
* refuses, for these two rows: a term not over a field, a locale collation,
|
|
473
|
+
* or keys of different kinds. For a client placing one row among others it
|
|
474
|
+
* holds.
|
|
475
|
+
*/
|
|
476
|
+
declare const compareRows: (terms: ReadonlyArray<OrderTerm>, left: Row, right: Row, query: string) => number;
|
|
477
|
+
/**
|
|
478
|
+
* The operations this interpreter runs. It is the reference, so this is the
|
|
479
|
+
* whole kernel — but it is declared rather than assumed, because an
|
|
480
|
+
* interpreter that gains an operator and forgets to say so is exactly what
|
|
481
|
+
* `Query.unsupported` exists to catch.
|
|
482
|
+
*/
|
|
483
|
+
declare const supported: ReadonlyArray<Operation>;
|
|
484
|
+
/**
|
|
485
|
+
* Refuses a body needing an operation this interpreter does not run, rather
|
|
486
|
+
* than skipping it and answering a different question. Called by `evaluate`;
|
|
487
|
+
* call it directly to check a body once instead of on every run.
|
|
488
|
+
*/
|
|
489
|
+
declare const assertSupported: (body: AnyQuery) => void;
|
|
490
|
+
/**
|
|
491
|
+
* The rows the body matches, in the order it asks for. Pure: it reads the rows
|
|
492
|
+
* it is given and nothing else.
|
|
493
|
+
*
|
|
494
|
+
* `input` holds the values this run was given, by the keys the body's
|
|
495
|
+
* placeholders were built with — the same record the query would be called
|
|
496
|
+
* with anywhere else.
|
|
497
|
+
*/
|
|
498
|
+
declare const evaluate: (body: AnyQuery, input: Row, rows: ReadonlyArray<Row>) => ReadonlyArray<Row>;
|
|
499
|
+
//#endregion
|
|
500
|
+
//#region src/write.d.ts
|
|
501
|
+
type AnyField = EntityField<string, string, Schema.Constraint>;
|
|
502
|
+
type OneRelation = EntityRelation<string, string, AnyEntity, 'one', boolean>;
|
|
503
|
+
/** One input key the write sets, and the field it sets. */
|
|
504
|
+
interface WriteSet {
|
|
505
|
+
readonly key: string;
|
|
506
|
+
readonly field: AnyField;
|
|
507
|
+
}
|
|
508
|
+
/** One input key the write points at another row with: a `one` relation, by the target's id. */
|
|
509
|
+
interface WriteLink {
|
|
510
|
+
readonly key: string;
|
|
511
|
+
readonly relation: OneRelation;
|
|
512
|
+
}
|
|
513
|
+
/**
|
|
514
|
+
* One row of an Entity, by id, from an operation's input: updated, inserted
|
|
515
|
+
* with an id the client chose, or deleted.
|
|
516
|
+
*/
|
|
517
|
+
interface Write<E extends AnyEntity, Fields extends Schema.Struct.Fields> {
|
|
518
|
+
readonly _tag: 'Update' | 'Insert' | 'Delete';
|
|
519
|
+
readonly input: EntityInput<E, Fields, any>;
|
|
520
|
+
/** The input key holding the row's id, and the Entity's `id` field it is. */
|
|
521
|
+
readonly id: WriteSet & {
|
|
522
|
+
readonly key: keyof Fields & string;
|
|
523
|
+
};
|
|
524
|
+
/**
|
|
525
|
+
* The input key holding the revision the row was read at, and its field, when
|
|
526
|
+
* the write is refused for a row that moved on since.
|
|
527
|
+
*/
|
|
528
|
+
readonly expect: (WriteSet & {
|
|
529
|
+
readonly key: keyof Fields & string;
|
|
530
|
+
}) | undefined;
|
|
531
|
+
/** The keys it sets, in the input's order. */
|
|
532
|
+
readonly sets: ReadonlyArray<WriteSet>;
|
|
533
|
+
/** The `one` relations it points elsewhere, in the input's order. */
|
|
534
|
+
readonly links: ReadonlyArray<WriteLink>;
|
|
535
|
+
}
|
|
536
|
+
type AnyWrite = Write<AnyEntity, any>;
|
|
537
|
+
/** One row's new values, in the store's wire shape: what a client patches and a server writes. */
|
|
538
|
+
interface BoundWrite {
|
|
539
|
+
readonly entity: string;
|
|
540
|
+
readonly id: string;
|
|
541
|
+
readonly values: Readonly<Record<string, unknown>>;
|
|
542
|
+
/**
|
|
543
|
+
* Each `one` relation it points, by the relation's key: the row it points at,
|
|
544
|
+
* or none for an optional relation set to nothing. How a ref is carried (a
|
|
545
|
+
* key on the wire, a foreign key in a table) is each interpreter's.
|
|
546
|
+
*/
|
|
547
|
+
readonly links: Readonly<Record<string, Option.Option<EntityRef>>>;
|
|
548
|
+
}
|
|
549
|
+
declare const Write: {
|
|
550
|
+
/**
|
|
551
|
+
* Sets, on the row whose id is the input's `id` key, every field the input
|
|
552
|
+
* maps a key to. `expect` names the key holding the revision the row was
|
|
553
|
+
* read at: an interpreter writes only a row still at that revision.
|
|
554
|
+
*
|
|
555
|
+
* ```ts
|
|
556
|
+
* const EditPost = Write.update(EditPostInput, { id: 'id' })
|
|
557
|
+
* ```
|
|
558
|
+
*
|
|
559
|
+
* A key mapped to a `one` relation (`Relation.input`) points the row at the
|
|
560
|
+
* id it holds. Refused where it is written: an `id` that is not the Entity's
|
|
561
|
+
* `id` field, a `many` relation or a nested key (not written by an update
|
|
562
|
+
* yet), or nothing to set.
|
|
563
|
+
*/
|
|
564
|
+
update: <E extends AnyEntity, Fields extends Schema.Struct.Fields>(input: EntityInput<E, Fields, any>, options: {
|
|
565
|
+
readonly id: keyof Fields & string;
|
|
566
|
+
readonly expect?: keyof Fields & string;
|
|
567
|
+
}) => Write<E, Fields>;
|
|
568
|
+
/**
|
|
569
|
+
* Inserts the row whose id is the input's `id` key, an id the client chose,
|
|
570
|
+
* with every field and `one` relation the input maps a key to. An insert
|
|
571
|
+
* expects no revision: there is no row to have read. A row already there
|
|
572
|
+
* under that id (a retry) is left as it is.
|
|
573
|
+
*/
|
|
574
|
+
insert: <E extends AnyEntity, Fields extends Schema.Struct.Fields>(input: EntityInput<E, Fields, any>, options: {
|
|
575
|
+
readonly id: keyof Fields & string;
|
|
576
|
+
}) => Write<E, Fields>;
|
|
577
|
+
/**
|
|
578
|
+
* Deletes the row whose id is the input's `id` key, only while it is still at
|
|
579
|
+
* the revision `expect` names, when it names one. It sets nothing, so a key
|
|
580
|
+
* mapped to a member is refused where it is written. A row already gone (a
|
|
581
|
+
* retry) is gone.
|
|
582
|
+
*/
|
|
583
|
+
delete: <E extends AnyEntity, Fields extends Schema.Struct.Fields>(input: EntityInput<E, Fields, any>, options: {
|
|
584
|
+
readonly id: keyof Fields & string;
|
|
585
|
+
readonly expect?: keyof Fields & string;
|
|
586
|
+
}) => Write<E, Fields>;
|
|
587
|
+
/**
|
|
588
|
+
* The revision this input says the row was read at, encoded, with its field:
|
|
589
|
+
* what an interpreter writes only a row still at. None for a write that
|
|
590
|
+
* expects none.
|
|
591
|
+
*/
|
|
592
|
+
expected: <Fields extends Schema.Struct.Fields>(write: Write<AnyEntity, Fields>, value: Schema.Struct.Type<Fields>) => Option.Option<{
|
|
593
|
+
readonly field: string;
|
|
594
|
+
readonly revision: unknown;
|
|
595
|
+
}>;
|
|
596
|
+
/** The members any invocation may write: what a query reading none of them cannot be changed by. */
|
|
597
|
+
writes: (write: AnyWrite) => ReadonlyArray<AnyField | OneRelation>;
|
|
598
|
+
/**
|
|
599
|
+
* The row this input writes and its new values, encoded as the store holds
|
|
600
|
+
* them: the patch a client shows before the server answers. `keys`, when
|
|
601
|
+
* given, narrows it to those input keys (what an author changed); the rest of
|
|
602
|
+
* the input is still the whole, validated value.
|
|
603
|
+
*/
|
|
604
|
+
bind: <Fields extends Schema.Struct.Fields>(write: Write<AnyEntity, Fields>, value: Schema.Struct.Type<Fields>, keys?: ReadonlyArray<string>) => BoundWrite;
|
|
605
|
+
};
|
|
606
|
+
//#endregion
|
|
607
|
+
//#region src/index.d.ts
|
|
608
|
+
declare const EntityTypeId: unique symbol;
|
|
609
|
+
type EntityTypeId = typeof EntityTypeId;
|
|
610
|
+
/**
|
|
611
|
+
* What makes two descriptors the same Entity. A pipe step returns a new
|
|
612
|
+
* descriptor with the same identity, so compare `identity`, never the objects.
|
|
613
|
+
*/
|
|
614
|
+
interface EntityIdentity<Name extends string> {
|
|
615
|
+
readonly name: Name;
|
|
616
|
+
/** Distinguishes two Entities that were defined with the same name. */
|
|
617
|
+
readonly token: symbol;
|
|
618
|
+
}
|
|
619
|
+
/** An intrinsic value of the Entity: one property of `entity.schema`. */
|
|
620
|
+
interface EntityField<Name extends string, Key extends string, S extends Schema.Constraint> {
|
|
621
|
+
readonly _tag: 'Field';
|
|
622
|
+
readonly owner: EntityIdentity<Name>;
|
|
623
|
+
readonly key: Key;
|
|
624
|
+
readonly schema: S;
|
|
625
|
+
readonly metadata: Metadata;
|
|
626
|
+
}
|
|
627
|
+
type Cardinality = 'one' | 'many';
|
|
628
|
+
/** What `Relation.one` / `Relation.many` return, before `Entity.relate` binds it to an owner. */
|
|
629
|
+
interface RelationSpec<Target extends AnyEntity, C extends Cardinality, Optional extends boolean> {
|
|
630
|
+
readonly target: Target;
|
|
631
|
+
readonly cardinality: C;
|
|
632
|
+
readonly optional: Optional;
|
|
633
|
+
}
|
|
634
|
+
/**
|
|
635
|
+
* A navigation edge as its owner sees it: one or many of `target`. How the edge
|
|
636
|
+
* is stored (a foreign key, a join table, a nested document) is the
|
|
637
|
+
* interpreter's concern.
|
|
638
|
+
*/
|
|
639
|
+
interface EntityRelation<Name extends string, Key extends string, Target extends AnyEntity, C extends Cardinality, Optional extends boolean> {
|
|
640
|
+
readonly _tag: 'Relation';
|
|
641
|
+
readonly owner: EntityIdentity<Name>;
|
|
642
|
+
readonly key: Key;
|
|
643
|
+
/** The target as `Entity.relate` returned it, so its own relations can be followed. */
|
|
644
|
+
readonly target: () => Target;
|
|
645
|
+
readonly cardinality: C;
|
|
646
|
+
readonly optional: Optional;
|
|
647
|
+
readonly metadata: Metadata;
|
|
648
|
+
}
|
|
649
|
+
/** What `Derived.make` returns, before an Entity owns it. */
|
|
650
|
+
interface DerivedSpec<S extends Schema.Constraint> {
|
|
651
|
+
readonly schema: S;
|
|
652
|
+
}
|
|
653
|
+
/**
|
|
654
|
+
* A value consumers may read that is not part of `entity.schema`. It says
|
|
655
|
+
* nothing about how the value is computed; an interpreter supplies it.
|
|
656
|
+
*/
|
|
657
|
+
interface EntityDerived<Name extends string, Key extends string, S extends Schema.Constraint> {
|
|
658
|
+
readonly _tag: 'Derived';
|
|
659
|
+
readonly owner: EntityIdentity<Name>;
|
|
660
|
+
readonly key: Key;
|
|
661
|
+
readonly schema: S;
|
|
662
|
+
readonly metadata: Metadata;
|
|
663
|
+
}
|
|
664
|
+
type EntityMember = EntityField<string, string, Schema.Constraint> | EntityRelation<string, string, AnyEntity, Cardinality, boolean> | EntityDerived<string, string, Schema.Constraint>;
|
|
665
|
+
type RelationSpecs = Readonly<Record<string, RelationSpec<AnyEntity, Cardinality, boolean>>>;
|
|
666
|
+
type DerivedSpecs = Readonly<Record<string, DerivedSpec<Schema.Constraint>>>;
|
|
667
|
+
type FieldsOf<Name extends string, Fields extends Schema.Struct.Fields> = { readonly [K in keyof Fields & string]: EntityField<Name, K, Fields[K]>; };
|
|
668
|
+
type RelationsOf<Name extends string, Relations extends RelationSpecs> = { readonly [K in keyof Relations & string]: Relations[K] extends RelationSpec<infer Target, infer C, infer Optional> ? EntityRelation<Name, K, Target, C, Optional> : never; };
|
|
669
|
+
type DerivedOf<Name extends string, Derived extends DerivedSpecs> = { readonly [K in keyof Derived & string]: EntityDerived<Name, K, Derived[K]['schema']>; };
|
|
670
|
+
interface Entity<Name extends string, Fields extends Schema.Struct.Fields, Relations extends RelationSpecs = {}, Derived extends DerivedSpecs = {}> extends Pipeable.Pipeable {
|
|
671
|
+
readonly [EntityTypeId]: EntityTypeId;
|
|
672
|
+
readonly identity: EntityIdentity<Name>;
|
|
673
|
+
readonly name: Name;
|
|
674
|
+
/** The intrinsic value only: no relations, no derived members. */
|
|
675
|
+
readonly schema: Schema.Struct<Fields>;
|
|
676
|
+
readonly fields: FieldsOf<Name, Fields>;
|
|
677
|
+
readonly relations: RelationsOf<Name, Relations>;
|
|
678
|
+
readonly derived: DerivedOf<Name, Derived>;
|
|
679
|
+
/** Every readable member under one namespace; keys never collide. */
|
|
680
|
+
readonly members: FieldsOf<Name, Fields> & RelationsOf<Name, Relations> & DerivedOf<Name, Derived>;
|
|
681
|
+
readonly metadata: Metadata;
|
|
682
|
+
}
|
|
683
|
+
type AnyEntity = Entity<string, any, any, any>;
|
|
684
|
+
/** Unsatisfiable when a new key is already a member, so the pipe step is the error site. */
|
|
685
|
+
type Free<E extends AnyEntity, New> = keyof New & keyof E['members'] extends never ? unknown : {
|
|
686
|
+
readonly alreadyAMember: keyof New & keyof E['members'];
|
|
687
|
+
};
|
|
688
|
+
type WithDerived<E, New extends DerivedSpecs> = E extends Entity<infer Name, infer Fields, infer R, infer D> ? Entity<Name, Fields, R, D & New> : never;
|
|
689
|
+
type Entities = Readonly<Record<string, AnyEntity>>;
|
|
690
|
+
type RelationMap<Es extends Entities> = { readonly [K in keyof Es]?: RelationSpecs; };
|
|
691
|
+
/** The key in `Es` of the Entity a spec targets, matched by name. */
|
|
692
|
+
type TargetKey<Es extends Entities, Target extends AnyEntity> = { [K in keyof Es]: [Es[K]['name'], Target['name']] extends [Target['name'], Es[K]['name']] ? K : never; }[keyof Es];
|
|
693
|
+
type RelatedSpecs<Es extends Entities, Rs extends RelationMap<Es>, K extends keyof Es> = { readonly [R in keyof Rs[K]]: Rs[K][R] extends RelationSpec<infer Target, infer C, infer Optional> ? RelationSpec<Related<Es, Rs, TargetKey<Es, Target>>, C, Optional> : never; };
|
|
694
|
+
/**
|
|
695
|
+
* One Entity of an `Entity.relate` result. A relation's target is again a
|
|
696
|
+
* `Related`, so relations can be followed through a cycle; the recursion goes
|
|
697
|
+
* through type arguments, which TypeScript resolves only when asked.
|
|
698
|
+
*/
|
|
699
|
+
type Related<Es extends Entities, Rs extends RelationMap<Es>, K extends keyof Es> = Es[K] extends Entity<infer Name, infer Fields, infer R, infer D> ? Entity<Name, Fields, R & RelatedSpecs<Es, Rs, K>, D> : never;
|
|
700
|
+
/** Marks a relation key that is already a member of its owner, or an owner that is not listed. */
|
|
701
|
+
type CheckRelations<Es extends Entities, Rs> = { readonly [K in keyof Rs]: K extends keyof Es ? { readonly [R in keyof Rs[K]]: R extends keyof Es[K]['members'] ? `"${R & string}" is already a member of ${Es[K]['name']}` : Rs[K][R]; } : 'not one of the entities being related'; };
|
|
702
|
+
declare const SelectionTypeId: unique symbol;
|
|
703
|
+
type SelectionTypeId = typeof SelectionTypeId;
|
|
704
|
+
/**
|
|
705
|
+
* The schema that identifies one of an Entity: its `id` field when that is text
|
|
706
|
+
* (a plain string, a brand, a pattern), and plain text otherwise. An id is text
|
|
707
|
+
* because a ref travels and is stored as text; an Entity keyed by a number still
|
|
708
|
+
* has refs, and their ids are the number as text.
|
|
709
|
+
*/
|
|
710
|
+
type IdSchemaOf<E> = E extends {
|
|
711
|
+
readonly fields: {
|
|
712
|
+
readonly id: {
|
|
713
|
+
readonly schema: infer S;
|
|
714
|
+
};
|
|
715
|
+
};
|
|
716
|
+
} ? S extends Schema.Constraint ? [S['Type']] extends [string] ? S : Schema.String : Schema.String : Schema.String;
|
|
717
|
+
/** What identifies one of an Entity: `IdOf<typeof Blog.Post>` is `PostId` when its `id` field is one. */
|
|
718
|
+
type IdOf<E> = IdSchemaOf<E>['Type'];
|
|
719
|
+
/**
|
|
720
|
+
* What a relation selected with `true` yields: which Entity, and which one. `Id`
|
|
721
|
+
* is the target's own id type, so a ref to an Author cannot be used as a Post's.
|
|
722
|
+
*/
|
|
723
|
+
interface EntityRef<Name extends string = string, Id extends string = string> {
|
|
724
|
+
readonly entity: Name;
|
|
725
|
+
readonly id: Id;
|
|
726
|
+
}
|
|
727
|
+
type RefSchema<Target extends AnyEntity> = Schema.Struct<{
|
|
728
|
+
readonly entity: Schema.Literal<Target['name']>;
|
|
729
|
+
readonly id: IdSchemaOf<Target>;
|
|
730
|
+
}>;
|
|
731
|
+
/**
|
|
732
|
+
* A view of the Entity graph: which members to read, and the schema of the
|
|
733
|
+
* value that results. It says nothing about where the value comes from.
|
|
734
|
+
*/
|
|
735
|
+
interface Selection<Name extends string, Members, S extends Schema.Constraint, Id extends string = string> {
|
|
736
|
+
readonly [SelectionTypeId]: SelectionTypeId;
|
|
737
|
+
/** Type-only: the id type of the Entity selected, so a reader can ask for the right one. Never set. */
|
|
738
|
+
readonly Id?: Id;
|
|
739
|
+
readonly entity: Entity<Name, any, any, any>;
|
|
740
|
+
/** What was selected, by member key: `true`, or a relation's nested Selection. */
|
|
741
|
+
readonly members: Members;
|
|
742
|
+
readonly schema: S;
|
|
743
|
+
}
|
|
744
|
+
type AnySelection<Name extends string = string> = Selection<Name, any, any>;
|
|
745
|
+
/** The value a Selection reads: `Selected<typeof PostCard>` is one card's fields. */
|
|
746
|
+
type Selected<S extends Selection<string, unknown, Schema.Constraint>> = S['schema']['Type'];
|
|
747
|
+
/** `true` for any member; a relation also takes a Selection of its target. */
|
|
748
|
+
/**
|
|
749
|
+
* Which part of a `many` relation to read: the first or last so many, from a
|
|
750
|
+
* cursor or from the end. A cursor is whatever the interpreter handed out with an
|
|
751
|
+
* earlier page; nothing here looks inside it.
|
|
752
|
+
*/
|
|
753
|
+
interface PageWindow {
|
|
754
|
+
readonly first?: number | undefined;
|
|
755
|
+
readonly last?: number | undefined;
|
|
756
|
+
readonly after?: string | undefined;
|
|
757
|
+
readonly before?: string | undefined;
|
|
758
|
+
}
|
|
759
|
+
declare const SelectionPageTypeId: unique symbol;
|
|
760
|
+
type SelectionPageTypeId = typeof SelectionPageTypeId;
|
|
761
|
+
/** A Selection of a `many` relation's target, read a page at a time. */
|
|
762
|
+
interface SelectionPage<Name extends string, S extends Schema.Constraint> {
|
|
763
|
+
readonly [SelectionPageTypeId]: SelectionPageTypeId;
|
|
764
|
+
readonly selection: Selection<Name, any, S>;
|
|
765
|
+
readonly window: PageWindow;
|
|
766
|
+
}
|
|
767
|
+
type PageSchema<S extends Schema.Constraint> = Schema.Struct<{
|
|
768
|
+
readonly items: Schema.$Array<S>;
|
|
769
|
+
readonly hasNext: Schema.Boolean;
|
|
770
|
+
readonly hasPrevious: Schema.Boolean;
|
|
771
|
+
}>;
|
|
772
|
+
type SelectionSpec<E extends AnyEntity, Spec> = { readonly [K in keyof Spec]: K extends keyof E['relations'] ? E['relations'][K] extends EntityRelation<any, any, infer Target, infer C, any> ? true | AnySelection<Target['name']> | (C extends 'many' ? SelectionPage<Target['name'], any> : never) : never : K extends keyof E['members'] ? true : `"${K & string}" is not a member of ${E['name']}`; };
|
|
773
|
+
type RelationShape<C extends Cardinality, Optional extends boolean, S extends Schema.Constraint> = C extends 'many' ? Schema.$Array<S> : Optional extends true ? Schema.NullOr<S> : S;
|
|
774
|
+
type SelectedSchema<Member, Selected> = Member extends EntityField<any, any, infer S> | EntityDerived<any, any, infer S> ? S : Member extends EntityRelation<any, any, infer Target, infer C, infer Optional> ? Selected extends SelectionPage<any, infer S> ? PageSchema<S> : RelationShape<C, Optional, Selected extends Selection<any, any, infer S> ? S : RefSchema<Target>> : never;
|
|
775
|
+
type SelectionSchema<E extends AnyEntity, Spec> = Schema.Struct<{ readonly [K in keyof Spec & keyof E['members']]: SelectedSchema<E['members'][K], Spec[K]>; }>;
|
|
776
|
+
/** An input key that carries a relation's target: the id of a `one`, the ids of a `many`. */
|
|
777
|
+
interface RelationInput<R extends EntityRelation<any, any, any, any, any>> {
|
|
778
|
+
readonly _tag: 'RelationInput';
|
|
779
|
+
readonly relation: R;
|
|
780
|
+
}
|
|
781
|
+
/**
|
|
782
|
+
* An input key that carries the relation's target itself, written through an
|
|
783
|
+
* input of its own: a post created with a new author, an order with its lines.
|
|
784
|
+
* A `one` holds that input's value, a `many` a list of them.
|
|
785
|
+
*/
|
|
786
|
+
interface NestedInput<R extends EntityRelation<any, any, any, any, any>, I extends EntityInput<any, any, any>> {
|
|
787
|
+
readonly _tag: 'NestedInput';
|
|
788
|
+
readonly relation: R;
|
|
789
|
+
readonly input: I;
|
|
790
|
+
}
|
|
791
|
+
/** An input key that is about the operation, not the Entity: a reason, a flag, a confirmation. */
|
|
792
|
+
interface Unmapped {
|
|
793
|
+
readonly _tag: 'Unmapped';
|
|
794
|
+
}
|
|
795
|
+
/** What one key of an operation's input means in terms of the Entity. */
|
|
796
|
+
type InputMember = EntityField<string, string, Schema.Constraint> | RelationInput<EntityRelation<string, string, AnyEntity, Cardinality, boolean>> | NestedInput<EntityRelation<string, string, AnyEntity, Cardinality, boolean>, EntityInput<AnyEntity, any, any>> | Unmapped;
|
|
797
|
+
/** The ids a relation takes as input: one id, a nullable id, or a list of ids. */
|
|
798
|
+
type RelationIds<R> = R extends EntityRelation<any, any, infer Target, infer C, infer Optional> ? C extends 'many' ? ReadonlyArray<IdOf<Target>> : Optional extends true ? IdOf<Target> | null : IdOf<Target> : never;
|
|
799
|
+
/** What a nested input takes: the value of the target's input, or a list of them for a `many`. */
|
|
800
|
+
type NestedValues<R, I> = I extends EntityInput<any, infer Fields, any> ? R extends EntityRelation<any, any, any, 'many', any> ? ReadonlyArray<Schema.Struct.Type<Fields>> : Schema.Struct.Type<Fields> : never;
|
|
801
|
+
type Present<T> = Exclude<T, null | undefined>;
|
|
802
|
+
/** What an `Option` holds, else the value itself. */
|
|
803
|
+
type Held<T> = T extends Option.Some<infer A> ? Present<A> : T extends Option.None<any> ? never : Present<T>;
|
|
804
|
+
/**
|
|
805
|
+
* Whether an input value fits a field. Only the value that is present has to
|
|
806
|
+
* fit: an input may leave a key out (a partial update), send `null` to clear
|
|
807
|
+
* it, or hold an `Option` (an id absent for something new), whose value fits as
|
|
808
|
+
* it is (an `Option` field) or as what it holds. Whether it may is the input
|
|
809
|
+
* schema's rule; the fit only guards against mapping the wrong member.
|
|
810
|
+
*/
|
|
811
|
+
type Fits<Input, Field> = [Present<Input>] extends [Field] ? true : [Held<Input>] extends [Field] ? true : false;
|
|
812
|
+
type MappingFor<Name extends string, Input, M> = M extends Unmapped ? M : M extends EntityField<infer Owner, any, any> | RelationInput<EntityRelation<infer Owner, any, any, any, any>> | NestedInput<EntityRelation<infer Owner, any, any, any, any>, any> ? [Owner] extends [Name] ? M extends EntityField<any, any, infer S> ? Fits<Input, Schema.Schema.Type<S>> extends true ? M : 'the input value does not fit this field' : M extends RelationInput<infer R> ? Present<Input> extends RelationIds<R> ? M : 'the input value is not the id shape of this relation' : M extends NestedInput<infer R, infer I> ? R extends EntityRelation<any, any, infer Target, any, any> ? I extends EntityInput<infer Of, any, any> ? [Of['name']] extends [Target['name']] ? Present<Input> extends NestedValues<R, I> ? M : 'the input value is not the value of the nested input' : `the nested input is of ${Of['name']}, not ${Target['name']}` : never : never : never : `this member belongs to ${Owner}` : 'map an input key to a Field, Relation.input(relation), Relation.nested(relation, input), or Entity.unmapped';
|
|
813
|
+
/** A key that names a field whose value it fits maps itself; every other key needs an entry. */
|
|
814
|
+
type SelfMapped<E extends AnyEntity, Fields extends Schema.Struct.Fields> = { [K in keyof Fields]: K extends keyof E['fields'] ? Fits<Schema.Schema.Type<Fields[K]>, Schema.Schema.Type<E['fields'][K]['schema']>> extends true ? K : never : never; }[keyof Fields];
|
|
815
|
+
/**
|
|
816
|
+
* A mapping written as a member's key: `'title'` is that Field, and `'author'` is
|
|
817
|
+
* `Relation.input` of that relation. Nothing is inferred from the input key's own
|
|
818
|
+
* name; the member is still named, only more briefly.
|
|
819
|
+
*/
|
|
820
|
+
type Named<E extends AnyEntity, M> = M extends string ? M extends keyof E['fields'] ? E['fields'][M] : M extends keyof E['relations'] ? RelationInput<E['relations'][M]> : `"${M}" names no field or relation of ${E['name']}` : M;
|
|
821
|
+
type InputMapping<E extends AnyEntity, Fields extends Schema.Struct.Fields, Mapping> = { readonly [K in Exclude<keyof Fields, SelfMapped<E, Fields>>]: unknown; } & { readonly [K in keyof Mapping]: K extends keyof Fields ? Named<E, Mapping[K]> extends (infer Member) ? Member extends string ? Member : MappingFor<E['name'], Schema.Schema.Type<Fields[K]>, Member> extends Member ? Mapping[K] : MappingFor<E['name'], Schema.Schema.Type<Fields[K]>, Member> : never : `"${K & string}" is not a key of the input`; };
|
|
822
|
+
type InputMembers<E extends AnyEntity, Fields extends Schema.Struct.Fields, Mapping> = { readonly [K in keyof Fields]: K extends keyof Mapping ? Named<E, Mapping[K]> : K extends keyof E['fields'] ? E['fields'][K] : never; };
|
|
823
|
+
/**
|
|
824
|
+
* An operation's input read against an Entity: which member each input key
|
|
825
|
+
* writes. The operation decides what may be submitted; the Entity only says
|
|
826
|
+
* what each submitted key means.
|
|
827
|
+
*/
|
|
828
|
+
interface EntityInput<E extends AnyEntity, Fields extends Schema.Struct.Fields, Members> {
|
|
829
|
+
readonly entity: E;
|
|
830
|
+
readonly schema: Schema.Struct<Fields>;
|
|
831
|
+
readonly members: Members;
|
|
832
|
+
}
|
|
833
|
+
/** The Entity member an input key writes, by its key; nothing for an unmapped key. */
|
|
834
|
+
type WrittenKey<M> = M extends EntityField<any, infer Key, any> ? Key : M extends RelationInput<EntityRelation<any, infer Key, any, any, any>> | NestedInput<EntityRelation<any, infer Key, any, any, any>, any> ? Key : never;
|
|
835
|
+
/** A nested input reads what it writes of the target; every other member reads as it is. */
|
|
836
|
+
type WrittenAs<M> = M extends NestedInput<any, EntityInput<infer Of, any, infer Members>> ? Selection<Of['name'], WrittenSpec<Members>, SelectionSchema<Of, WrittenSpec<Members>>> : true;
|
|
837
|
+
/** Every member the input writes: what to read to show the input's current values. */
|
|
838
|
+
type WrittenSpec<Members> = { readonly [K in keyof Members as WrittenKey<Members[K]>]: WrittenAs<Members[K]>; };
|
|
839
|
+
declare const Entity: {
|
|
840
|
+
/** Declares an Entity from its intrinsic fields. Each call is a new identity. */
|
|
841
|
+
define: <const Name extends string, Fields extends Schema.Struct.Fields>(name: Name, schema: Schema.Struct<Fields>) => Entity<Name, Fields>;
|
|
842
|
+
/**
|
|
843
|
+
* Declares the relations between a set of Entities in one step, and returns
|
|
844
|
+
* them related. One step, because Entities that point at each other cannot
|
|
845
|
+
* each be declared in terms of the other.
|
|
846
|
+
*/
|
|
847
|
+
relate: <const Es extends Entities, const Rs extends RelationMap<Es>>(entities: Es, relations: Rs & CheckRelations<Es, Rs>) => { readonly [K in keyof Es]: Related<Es, Rs, K>; };
|
|
848
|
+
/**
|
|
849
|
+
* Selects members of an Entity and assembles the schema of the result. A
|
|
850
|
+
* relation selected with `true` yields an `EntityRef`; with a Selection of its
|
|
851
|
+
* target, that Selection's value. `many` yields an array, an optional `one`
|
|
852
|
+
* is nullable.
|
|
853
|
+
*/
|
|
854
|
+
select: <E extends AnyEntity, const Spec>(entity: E, spec: Spec & SelectionSpec<E, Spec>) => Selection<E["name"], Spec, SelectionSchema<E, Spec>, IdOf<E>>;
|
|
855
|
+
/**
|
|
856
|
+
* A `many` relation read a page at a time, in place of its Selection:
|
|
857
|
+
* `comments: Entity.page(CommentSummary, { first: 10 })`. The value is a page
|
|
858
|
+
* of the Selection's values: `items`, `hasNext`, `hasPrevious`. Reading on from a cursor is another window.
|
|
859
|
+
*/
|
|
860
|
+
page: <Name extends string, S extends Schema.Constraint>(selection: Selection<Name, any, S>, window: PageWindow) => SelectionPage<Name, S>;
|
|
861
|
+
/** Adds readable members that are not part of `entity.schema`. */
|
|
862
|
+
derived: <const New extends DerivedSpecs>(specs: New) => <E extends AnyEntity>(entity: E & Free<E, New>) => WithDerived<E, New>;
|
|
863
|
+
/** Attaches an interpreter's metadata to the Entity itself. */
|
|
864
|
+
annotate: (metadata: Metadata) => <E extends AnyEntity>(entity: E) => E;
|
|
865
|
+
/** Attaches an interpreter's metadata to members, by key. */
|
|
866
|
+
annotateMembers: <E extends AnyEntity>(metadata: { readonly [K in keyof E["members"]]?: Metadata; }) => (entity: E) => E;
|
|
867
|
+
/**
|
|
868
|
+
* Reads an operation's input schema against an Entity. A key that names a
|
|
869
|
+
* field maps to it; any other key is mapped explicitly, to a Field, to
|
|
870
|
+
* `Relation.input(relation)`, or to `Entity.unmapped`. Nothing is inferred
|
|
871
|
+
* from a naming convention such as `authorId`.
|
|
872
|
+
*/
|
|
873
|
+
input: <E extends AnyEntity, Fields extends Schema.Struct.Fields, const Mapping = {}>(entity: E, schema: Schema.Struct<Fields>, ...mapping: keyof InputMapping<E, Fields, Mapping> extends never ? [mapping?: Mapping & InputMapping<E, Fields, Mapping>] : [mapping: Mapping & InputMapping<E, Fields, Mapping>]) => EntityInput<E, Fields, InputMembers<E, Fields, Mapping>>;
|
|
874
|
+
/** For an input key that is about the operation rather than the Entity. */
|
|
875
|
+
unmapped: Unmapped;
|
|
876
|
+
/**
|
|
877
|
+
* The schemas of some of an Entity's fields, by key, to spread into an input's
|
|
878
|
+
* struct: `Schema.Struct({ ...Entity.fields(Post, 'id', 'title'), editorId: ... })`.
|
|
879
|
+
* The input then keeps the field's own rules, and its keys map themselves.
|
|
880
|
+
*/
|
|
881
|
+
fields: <E extends AnyEntity, const Keys extends ReadonlyArray<keyof E["fields"] & string>>(entity: E, ...keys: Keys) => { readonly [K in Keys[number]]: E["fields"][K]["schema"]; };
|
|
882
|
+
/**
|
|
883
|
+
* The Selection of every member an input writes, with each relation as refs:
|
|
884
|
+
* what an edit screen loads before it shows the input's current values.
|
|
885
|
+
*/
|
|
886
|
+
selectFor: <E extends AnyEntity, Fields extends Schema.Struct.Fields, Members>(input: EntityInput<E, Fields, Members>) => Selection<E["name"], WrittenSpec<Members>, SelectionSchema<E, WrittenSpec<Members>>, IdOf<E>>;
|
|
887
|
+
/**
|
|
888
|
+
* The input values that reproduce `value`, a value read through `selectFor`
|
|
889
|
+
* (or any Selection with those members): a field as it is, a relation as the
|
|
890
|
+
* id or ids of its refs. A key whose member `value` lacks is left out, as is
|
|
891
|
+
* an unmapped key, which the Entity knows nothing about.
|
|
892
|
+
*/
|
|
893
|
+
valuesFor: <E extends AnyEntity, Fields extends Schema.Struct.Fields, Members>(input: EntityInput<E, Fields, Members>, value: Readonly<Record<string, unknown>>) => Partial<Schema.Struct.Type<Fields>>;
|
|
894
|
+
is: (value: unknown) => value is AnyEntity;
|
|
895
|
+
/** True when both descriptors are versions of one Entity. */
|
|
896
|
+
same: (left: AnyEntity, right: AnyEntity) => boolean;
|
|
897
|
+
};
|
|
898
|
+
declare function one<Target extends AnyEntity>(target: Target): RelationSpec<Target, 'one', false>;
|
|
899
|
+
declare function one<Target extends AnyEntity, const Optional extends boolean>(target: Target, options: {
|
|
900
|
+
readonly optional: Optional;
|
|
901
|
+
}): RelationSpec<Target, 'one', Optional>;
|
|
902
|
+
/** What the owner sees: one or many of `target`. Used inside `Entity.relate`. */
|
|
903
|
+
declare const Relation: {
|
|
904
|
+
one: typeof one;
|
|
905
|
+
/** For `Entity.input`: the input key holds this relation's target id, or ids for a `many`. */
|
|
906
|
+
input: <R extends EntityRelation<any, any, any, any, any>>(relation: R) => RelationInput<R>;
|
|
907
|
+
/**
|
|
908
|
+
* For `Entity.input`: the input key holds the relation's target itself, written
|
|
909
|
+
* through `input`, an `Entity.input` of the target. A `many` holds a list.
|
|
910
|
+
*/
|
|
911
|
+
nested: <R extends EntityRelation<any, any, any, any, any>, I extends EntityInput<any, any, any>>(relation: R, input: I) => NestedInput<R, I>;
|
|
912
|
+
many: <Target extends AnyEntity>(target: Target) => RelationSpec<Target, "many", false>;
|
|
913
|
+
};
|
|
914
|
+
declare const Derived: {
|
|
915
|
+
make: <S extends Schema.Constraint>(schema: S) => DerivedSpec<S>;
|
|
916
|
+
};
|
|
917
|
+
//#endregion
|
|
918
|
+
export { AnyExpr as $, SelectionPage as A, Write as B, Relation as C, TextOperand as Ct, RelationSpecs as D, maxQueryNodes as Dt, RelationSpec as E, isPredicate as Et, WrittenAs as F, assertSupported as G, WriteSet as H, WrittenKey as I, supported as J, compareRows as K, WrittenSpec as L, SelectionTypeId as M, TargetKey as N, Selected as O, Collation as Ot, Unmapped as P, ReadFilter as Q, AnyWrite as R, RelatedSpecs as S, TermOptions as St, RelationMap as T, dependenciesOf as Tt, QueryEvaluateError as U, WriteLink as V, Row as W, SchemaWords as X, SchemaShape as Y, Words as Z, IdSchemaOf as _, Ordering as _t, DerivedSpecs as a, EqPredicate as at, PageWindow as b, Query as bt, EntityDerived as c, FieldExpr as ct, EntityInput as d, LiteralExpr as dt, AnyQuery as et, EntityMember as f, NullPredicate as ft, IdOf as g, OrderTerm as gt, EntityTypeId as h, Order as ht, DerivedSpec as i, Dependencies as it, SelectionPageTypeId as j, Selection as k, EntityField as l, InPredicate as lt, EntityRelation as m, Operation as mt, Cardinality as n, ChosenSort as nt, Entities as o, Expr as ot, EntityRef as p, Operandish as pt, evaluate as q, Derived as r, ContainsPredicate as rt, Entity as s, FieldDependency as st, AnyEntity as t, ChosenOrder as tt, EntityIdentity as u, InputExpr as ut, InputMember as v, Placement as vt, RelationInput as w, ValueOf as wt, Related as x, QueryDependencies as xt, NestedInput as y, Predicate as yt, BoundWrite as z };
|
|
919
|
+
//# sourceMappingURL=index-DLz2yED-.d.mts.map
|