foldkit-entity 0.2.0 → 0.4.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 CHANGED
@@ -51,7 +51,32 @@ not when `a === b`.
51
51
  pnpm add effect foldkit-entity
52
52
  ```
53
53
 
54
- ## Example
54
+ ## Sixty seconds: describe one read
55
+
56
+ ```ts
57
+ import { Schema } from 'effect'
58
+ import { Entity } from 'foldkit-entity'
59
+
60
+ const Task = Entity.define('Task', Schema.Struct({
61
+ id: Schema.String,
62
+ title: Schema.String,
63
+ done: Schema.Boolean,
64
+ }))
65
+ const TaskTitle = Entity.select(Task, { id: true, title: true })
66
+ type TaskTitle = typeof TaskTitle.schema.Type
67
+ const value: TaskTitle = { id: 't1', title: 'Read the guide' }
68
+ ```
69
+
70
+ `Task` describes the domain. `TaskTitle` describes one consumer's result shape;
71
+ it does not query a database or allocate a cache. Its schema validates that
72
+ shape when an interpreter produces data. A selection does not include `done`
73
+ unless you select it.
74
+
75
+ Next, hand the Entity to Remote for client reads or bind it to Drizzle tables
76
+ on the server. Declare operation input separately when adding a form: selecting
77
+ readable fields does not grant permission to write them.
78
+
79
+ ## Relations and derived values
55
80
 
56
81
  ```ts
57
82
  import { Schema } from 'effect'
@@ -123,7 +148,7 @@ const Writer = Entity.define('Author', Schema.Struct({ id: AuthorId, name: Schem
123
148
  const Article = Entity.define('Post', Schema.Struct({ id: PostId, title: Schema.String }))
124
149
  const Press = Entity.relate({ Writer, Article }, { Article: { author: Relation.one(Writer) } })
125
150
 
126
- type WriterId = IdOf<typeof Press.Writer> // AuthorId
151
+ type WriterId = import('foldkit-entity').IdOf<typeof Press.Writer> // AuthorId
127
152
 
128
153
  const ByLine = Entity.select(Press.Article, { author: true })
129
154
  // { author: EntityRef<'Author', AuthorId> }
@@ -330,9 +355,17 @@ as a value:
330
355
 
331
356
  > **Why query semantics live in this package.** They describe and interpret
332
357
  > nothing, which is the line this package already draws: an `Expr` says which
333
- > rows and fetches none of them, and the interpreters that run one live
334
- > elsewhere — `foldkit-remote-drizzle` compiles a body to SQL,
335
- > `foldkit-remote-server` evaluates one over rows. Nothing that imports only
358
+ > rows and fetches none of them, and the interpreters that *fetch* live
359
+ > elsewhere — `foldkit-remote-drizzle` compiles a body to SQL against a
360
+ > database.
361
+ >
362
+ > `evaluate` is here rather than there because it is the **reference
363
+ > semantics** of the IR: what the operator definitions mean, operationally, over
364
+ > rows already in hand. A specification's reference implementation belongs with
365
+ > the specification, and it reaches nothing — no database, no transport, no
366
+ > Remote concept. The rule that keeps it honest is that **it may depend on the
367
+ > IR and nothing else**; the moment it wants one of those it has moved to the
368
+ > wrong place. Nothing that imports only
336
369
  > `Entity` pays for them: they are ordinary consts in a `sideEffects: false`
337
370
  > package, so a bundler drops them, and a package like `foldkit-form` imports
338
371
  > only types from here in any case.
@@ -393,6 +426,12 @@ has to be said, not left to the interpreter: SQLite's `like` ignores case and
393
426
  Postgres's does not, so a body that left it open would mean two things. Folding
394
427
  is ASCII-only, since that is what `lower` does in SQLite without ICU.
395
428
 
429
+ **It searches text, and the operand is constrained to text.** `contains` over a
430
+ number would compile to `lower(rank) like …`, which SQLite coerces into an
431
+ answer and Postgres rejects at runtime — so a non-text operand is a compile
432
+ error where it is written rather than a surprise where it runs. Nullable text is
433
+ allowed, because it is a real case with a real meaning:
434
+
396
435
  **Over a column that can be null it is not the same as no filter.** A null
397
436
  contains nothing, not even the empty string, so its rows drop out. The column
398
437
  the CMS searches is declared not-null, which is what makes an empty search
@@ -430,6 +469,43 @@ one is refused where it is piped: an interpreter would otherwise be asked for a
430
469
  column of a table it was never told to read. Entities are compared by identity,
431
470
  so two declared with the same name are two Entities here as everywhere else.
432
471
 
472
+ ### Saying what an interpreter can run
473
+
474
+ An `Expr` is only portable if the thing running it says what it runs.
475
+ `Query.unsupported(query, supported)` names the operations a query needs that
476
+ an interpreter does not have:
477
+
478
+ ```ts
479
+ const missing = Query.unsupported(body, ['eq', 'isNull', 'isNotNull'])
480
+ if (missing.length > 0) throw new Error(`cannot run ${missing.join(', ')}`)
481
+ ```
482
+
483
+ The refusal belongs to the interpreter, not here: one that compiles at
484
+ registration and one that runs a body directly fail at different moments. What
485
+ matters is that it refuses rather than skipping the operation — an interpreter
486
+ that quietly drops a `contains` it cannot compile answers a different question
487
+ in full confidence, and every test it does support still passes.
488
+
489
+ ### Reading one back
490
+
491
+ `Query.show(query)` renders a body as text, one clause per line:
492
+
493
+ ```ts
494
+ Query.show(body)
495
+ // FROM Post
496
+ // WHERE Post.slug = $slug
497
+ // AND Post.published = true
498
+ // ORDER BY Post.updatedAt DESC
499
+ ```
500
+
501
+ For a person — an explanation, a diagnostic, a test asserting on a whole
502
+ predicate at once — and never for an interpreter. It is close enough to SQL to
503
+ read at a glance and unlike it everywhere that matters: an input is `$slug`
504
+ rather than a bound parameter, `contains` is named rather than rendered as
505
+ somebody's `like`, and no dialect's escaping or collation is implied. What
506
+ actually ran is whatever that backend compiled, which is not this.
507
+ `Expr.show(node)` does the same for one expression.
508
+
433
509
  A `Query` says which rows. It does not say which fields — that is a Selection —
434
510
  and it does not say how many, whether absence is an error, or whether to watch
435
511
  for changes: those belong to the consumer doing the reading, not to the
@@ -458,7 +534,7 @@ from queries, not from what a database could express.
458
534
  | `Entity.is(value)` | Whether a value is an Entity descriptor. |
459
535
  | `Expr.eq(left, right)` | Two values are the same; a field or a plain value on either side is coerced, and a predicate may stand where a boolean is wanted. |
460
536
  | `Expr.isNull(field)` / `Expr.isNotNull(field)` | Whether a value is absent; one node, with the answer absence gives flipped. |
461
- | `Expr.contains(field, search)` | Whether text contains text. Containing the empty string is everything, but a null contains nothing. |
537
+ | `Expr.contains(field, search)` | Whether text contains text, over a text or nullable-text operand only. Containing the empty string is everything, but a null contains nothing. |
462
538
  | `Expr.field(field)` | One field of one Entity, as a scalar. |
463
539
  | `Expr.input(key, schema)` | A value the query is given when it runs, as a placeholder. |
464
540
  | `Expr.literal(value)` | A constant. Comparisons coerce one, so this is rarely written. |
@@ -468,6 +544,8 @@ from queries, not from what a database could express.
468
544
  | `Query.where(...predicates)` | Pipe step keeping the rows those hold for; conjoins with what is there. |
469
545
  | `Query.orderBy(...terms)` | Pipe step reading in that order; appends after existing terms. |
470
546
  | `Query.dependencies(query)` | What the whole query reads: every predicate and ordering term. |
547
+ | `Query.unsupported(query, supported)` | The operations it needs that an interpreter does not run. |
548
+ | `Query.show(query)` / `Expr.show(node)` | The query or expression as readable text, for a person and not for an interpreter. |
471
549
 
472
550
  ## Limits
473
551
 
@@ -0,0 +1,46 @@
1
+ import { AnyQuery, Entity } from "../index.mjs";
2
+ import { Schema } from "effect";
3
+ //#region src/conformance/index.d.ts
4
+ /** The one Entity every case reads, with a column of each kind that matters. */
5
+ export declare const Subject: Entity<"Subject", {
6
+ readonly id: Schema.String;
7
+ /** Mixed case on purpose: a case-blind `contains` must be caught. */
8
+ readonly label: Schema.String;
9
+ readonly rank: Schema.Number;
10
+ /** Nullable on purpose: three-valued logic has to be exercised. */
11
+ readonly tag: Schema.String;
12
+ /** Encoded and decoded forms differ on purpose: see `Timestamp`. */
13
+ readonly at: Schema.decodeTo<Schema.Date, Schema.String, never, never>;
14
+ }, {}, {}>;
15
+ /**
16
+ * How a row looks to an interpreter reading values, and to SQL as a table. The
17
+ * index signature is what lets one be read by key without a cast, which is how
18
+ * an interpreter over plain rows reads one.
19
+ */
20
+ export interface ConformanceRow {
21
+ readonly id: string;
22
+ readonly label: string;
23
+ readonly rank: number;
24
+ readonly tag: string | null;
25
+ /** The **encoded** form: what a store holds and an interpreter compares. */
26
+ readonly at: string;
27
+ readonly [key: string]: unknown;
28
+ }
29
+ export declare const rows: ReadonlyArray<ConformanceRow>;
30
+ export interface ConformanceCase {
31
+ /** What the case pins, as a sentence an interpreter fails by name. */
32
+ readonly what: string;
33
+ readonly body: AnyQuery;
34
+ /**
35
+ * The inputs, **encoded** — the space a store's rows are in, not the domain
36
+ * space the body's types describe. For every column but `at` the two are the
37
+ * same value, which is exactly why this has to be said rather than inferred
38
+ * from the fixtures.
39
+ */
40
+ readonly input: Readonly<Record<string, unknown>>;
41
+ /** The ids the body matches, in the order it asks for. */
42
+ readonly expected: ReadonlyArray<string>;
43
+ }
44
+ export declare const cases: ReadonlyArray<ConformanceCase>;
45
+ //#endregion
46
+ //# sourceMappingURL=index.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../../src/conformance/index.ts"],"mappings":";;;;qBA4Ca,SAAO;;;;;;;;;;;;;;;iBAmBH;WACN;WACA;WACA;WACA;;WAEA;YACC;;qBAGC,MAAM,cAAc;iBAQhB;;WAEN;WACA,MAAM;;;;;;;WAON,OAAO,SAAS;;WAEhB,UAAU;;qBAUR,OAAO,cAAc"}
@@ -0,0 +1,293 @@
1
+ import { Entity, Expr, Order, Query } from "../index.mjs";
2
+ import { Schema, SchemaGetter } from "effect";
3
+ //#region src/conformance/index.ts
4
+ /**
5
+ * The conformance suite for a query body: what
6
+ * [data-query-DESIGN §6.0.1](../../../docs/design/data-query-DESIGN.md) says
7
+ * each operator means, as cases an interpreter can be run against.
8
+ *
9
+ * Exported rather than kept in this repository's tests, because the interpreter
10
+ * most worth checking against it is one written elsewhere: run every case
11
+ * through yours and compare the ids, in order, against `expected`.
12
+ *
13
+ * §18 names portable-kernel conformance as what the reference interpreter is
14
+ * for. This is that, extracted: one set of cases, run against every interpreter
15
+ * rather than each interpreter having its own tests that happen to agree.
16
+ * `foldkit-remote-server` runs them over rows in memory;
17
+ * `foldkit-remote-drizzle` compiles them to SQL and runs them against a real
18
+ * SQLite. A body that means two things fails in whichever is wrong.
19
+ *
20
+ * The cases are chosen to make interpreters *disagree*, which is the only kind
21
+ * that tests anything. A fixture whose values are all lowercase cannot tell a
22
+ * case-sensitive `contains` from a case-insensitive one — that is not a
23
+ * hypothetical, it is how `contains` reached a released package meaning three
24
+ * different things.
25
+ */
26
+ /**
27
+ * A `Date` on the way in, an ISO string on the wire — the one fixture whose
28
+ * **encoded form differs from its decoded form**.
29
+ *
30
+ * Every other column here encodes to itself, which is why the suite could not
31
+ * previously see an interpreter comparing a decoded value against an encoded
32
+ * row. That is not a hypothetical bug: a store holds wire values and decodes at
33
+ * read, while a `QueryRef`'s input and a body's literals are written in domain
34
+ * terms, so anything that runs a body over stored rows has to reconcile the two
35
+ * and nothing was checking that it did.
36
+ */
37
+ const Timestamp = Schema.Date.pipe(Schema.encodeTo(Schema.String, {
38
+ decode: SchemaGetter.transform((iso) => new Date(iso)),
39
+ encode: SchemaGetter.transform((at) => at.toISOString())
40
+ }));
41
+ /** The one Entity every case reads, with a column of each kind that matters. */
42
+ const Subject = Entity.define("Subject", Schema.Struct({
43
+ id: Schema.String,
44
+ /** Mixed case on purpose: a case-blind `contains` must be caught. */
45
+ label: Schema.String,
46
+ rank: Schema.Number,
47
+ /** Nullable on purpose: three-valued logic has to be exercised. */
48
+ tag: Schema.String,
49
+ /** Encoded and decoded forms differ on purpose: see `Timestamp`. */
50
+ at: Timestamp
51
+ }));
52
+ const rows = [
53
+ {
54
+ id: "a",
55
+ label: "Intro",
56
+ rank: 2,
57
+ tag: null,
58
+ at: "2026-01-01T00:00:00.000Z"
59
+ },
60
+ {
61
+ id: "b",
62
+ label: "intro to sql",
63
+ rank: 1,
64
+ tag: "x",
65
+ at: "2026-01-02T00:00:00.000Z"
66
+ },
67
+ {
68
+ id: "c",
69
+ label: "Other",
70
+ rank: 3,
71
+ tag: null,
72
+ at: "2026-01-02T00:00:00.000Z"
73
+ },
74
+ {
75
+ id: "d",
76
+ label: "100% cotton",
77
+ rank: 3,
78
+ tag: "x",
79
+ at: "2026-01-03T00:00:00.000Z"
80
+ },
81
+ {
82
+ id: "e",
83
+ label: "snake_case",
84
+ rank: 4,
85
+ tag: "y",
86
+ at: "2026-01-04T00:00:00.000Z"
87
+ }
88
+ ];
89
+ const from = Query.from(Subject);
90
+ const byId = Query.orderBy(Order.asc(Subject.fields.id));
91
+ const label = Expr.input("label", Schema.String);
92
+ const tag = Expr.input("tag", Schema.String);
93
+ const present = Expr.input("present", Schema.Boolean);
94
+ const at = Expr.input("at", Timestamp);
95
+ const cases = [
96
+ {
97
+ what: "eq matches a field against a literal",
98
+ body: from.pipe(Query.where(Expr.eq(Subject.fields.rank, 3)), byId),
99
+ input: {},
100
+ expected: ["c", "d"]
101
+ },
102
+ {
103
+ what: "eq matches a field against the value the request supplies",
104
+ body: from.pipe(Query.where(Expr.eq(Subject.fields.label, label)), byId),
105
+ input: { label: "Other" },
106
+ expected: ["c"]
107
+ },
108
+ {
109
+ what: "eq is exact: a value that differs only by case does not match",
110
+ body: from.pipe(Query.where(Expr.eq(Subject.fields.label, label)), byId),
111
+ input: { label: "other" },
112
+ expected: []
113
+ },
114
+ {
115
+ what: "eq against null matches nothing, not even the rows that are null",
116
+ body: from.pipe(Query.where(Expr.eq(Subject.fields.tag, tag)), byId),
117
+ input: { tag: null },
118
+ expected: []
119
+ },
120
+ {
121
+ what: "eq against a value skips the rows whose column is null",
122
+ body: from.pipe(Query.where(Expr.eq(Subject.fields.tag, "x")), byId),
123
+ input: {},
124
+ expected: ["b", "d"]
125
+ },
126
+ {
127
+ what: "isNull finds exactly the rows with no value",
128
+ body: from.pipe(Query.where(Expr.isNull(Subject.fields.tag)), byId),
129
+ input: {},
130
+ expected: ["a", "c"]
131
+ },
132
+ {
133
+ what: "isNotNull finds exactly the rest",
134
+ body: from.pipe(Query.where(Expr.isNotNull(Subject.fields.tag)), byId),
135
+ input: {},
136
+ expected: [
137
+ "b",
138
+ "d",
139
+ "e"
140
+ ]
141
+ },
142
+ {
143
+ what: "a predicate compared to a true input is that predicate",
144
+ body: from.pipe(Query.where(Expr.eq(Expr.isNotNull(Subject.fields.tag), present)), byId),
145
+ input: { present: true },
146
+ expected: [
147
+ "b",
148
+ "d",
149
+ "e"
150
+ ]
151
+ },
152
+ {
153
+ what: "a predicate compared to a false input is its negation",
154
+ body: from.pipe(Query.where(Expr.eq(Expr.isNotNull(Subject.fields.tag), present)), byId),
155
+ input: { present: false },
156
+ expected: ["a", "c"]
157
+ },
158
+ ...[true, false].map((value) => ({
159
+ what: `a ${value} input compared to a predicate works in reverse order`,
160
+ body: from.pipe(Query.where(Expr.eq(present, Expr.isNotNull(Subject.fields.tag))), byId),
161
+ input: { present: value },
162
+ expected: value ? [
163
+ "b",
164
+ "d",
165
+ "e"
166
+ ] : ["a", "c"]
167
+ })),
168
+ ...[true, false].map((value) => ({
169
+ what: `an unknown equality compared to ${value} stays unknown`,
170
+ body: from.pipe(Query.where(Expr.eq(Expr.eq(Subject.fields.tag, tag), present)), byId),
171
+ input: {
172
+ tag: null,
173
+ present: value
174
+ },
175
+ expected: []
176
+ })),
177
+ {
178
+ what: "contains ignores case, which is stated rather than left to the backend",
179
+ body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),
180
+ input: { label: "INTRO" },
181
+ expected: ["a", "b"]
182
+ },
183
+ {
184
+ what: "contains matches anywhere in the value, not only at the start",
185
+ body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),
186
+ input: { label: "to sql" },
187
+ expected: ["b"]
188
+ },
189
+ {
190
+ what: "containing the empty string is everything",
191
+ body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),
192
+ input: { label: "" },
193
+ expected: [
194
+ "a",
195
+ "b",
196
+ "c",
197
+ "d",
198
+ "e"
199
+ ]
200
+ },
201
+ {
202
+ what: "a percent is searched for literally, not as a wildcard",
203
+ body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),
204
+ input: { label: "%" },
205
+ expected: ["d"]
206
+ },
207
+ {
208
+ what: "an underscore is searched for literally, not as a single-character wildcard",
209
+ body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),
210
+ input: { label: "_" },
211
+ expected: ["e"]
212
+ },
213
+ {
214
+ what: "contains over a null column drops those rows, so it is not the same as no filter",
215
+ body: from.pipe(Query.where(Expr.contains(Subject.fields.tag, label)), byId),
216
+ input: { label: "" },
217
+ expected: [
218
+ "b",
219
+ "d",
220
+ "e"
221
+ ]
222
+ },
223
+ {
224
+ what: "contains with a null search is unknown for every row",
225
+ body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),
226
+ input: { label: null },
227
+ expected: []
228
+ },
229
+ {
230
+ what: "an unknown containment compared to false stays unknown",
231
+ body: from.pipe(Query.where(Expr.eq(Expr.contains(Subject.fields.label, label), false)), byId),
232
+ input: { label: null },
233
+ expected: []
234
+ },
235
+ {
236
+ what: "two predicates conjoin: every one must hold",
237
+ body: from.pipe(Query.where(Expr.eq(Subject.fields.rank, 3), Expr.isNotNull(Subject.fields.tag)), byId),
238
+ input: {},
239
+ expected: ["d"]
240
+ },
241
+ {
242
+ what: "no predicate at all is every row",
243
+ body: from.pipe(byId),
244
+ input: {},
245
+ expected: [
246
+ "a",
247
+ "b",
248
+ "c",
249
+ "d",
250
+ "e"
251
+ ]
252
+ },
253
+ {
254
+ what: "an input whose encoded form differs from its decoded one matches on the encoded one",
255
+ body: from.pipe(Query.where(Expr.eq(Subject.fields.at, at)), byId),
256
+ input: { at: "2026-01-02T00:00:00.000Z" },
257
+ expected: ["b", "c"]
258
+ },
259
+ {
260
+ what: "a literal is encoded too, or it has the same problem as an input",
261
+ body: from.pipe(Query.where(Expr.eq(Subject.fields.at, "2026-01-03T00:00:00.000Z")), byId),
262
+ input: {},
263
+ expected: ["d"]
264
+ },
265
+ {
266
+ what: "orders ascending by a number",
267
+ body: from.pipe(Query.orderBy(Order.asc(Subject.fields.rank), Order.asc(Subject.fields.id))),
268
+ input: {},
269
+ expected: [
270
+ "b",
271
+ "a",
272
+ "c",
273
+ "d",
274
+ "e"
275
+ ]
276
+ },
277
+ {
278
+ what: "orders descending, and a later term breaks the tie",
279
+ body: from.pipe(Query.orderBy(Order.desc(Subject.fields.rank), Order.asc(Subject.fields.id))),
280
+ input: {},
281
+ expected: [
282
+ "e",
283
+ "c",
284
+ "d",
285
+ "a",
286
+ "b"
287
+ ]
288
+ }
289
+ ];
290
+ //#endregion
291
+ export { Subject, cases, rows };
292
+
293
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.mjs","names":[],"sources":["../../src/conformance/index.ts"],"sourcesContent":["/**\n * The conformance suite for a query body: what\n * [data-query-DESIGN §6.0.1](../../../docs/design/data-query-DESIGN.md) says\n * each operator means, as cases an interpreter can be run against.\n *\n * Exported rather than kept in this repository's tests, because the interpreter\n * most worth checking against it is one written elsewhere: run every case\n * through yours and compare the ids, in order, against `expected`.\n *\n * §18 names portable-kernel conformance as what the reference interpreter is\n * for. This is that, extracted: one set of cases, run against every interpreter\n * rather than each interpreter having its own tests that happen to agree.\n * `foldkit-remote-server` runs them over rows in memory;\n * `foldkit-remote-drizzle` compiles them to SQL and runs them against a real\n * SQLite. A body that means two things fails in whichever is wrong.\n *\n * The cases are chosen to make interpreters *disagree*, which is the only kind\n * that tests anything. A fixture whose values are all lowercase cannot tell a\n * case-sensitive `contains` from a case-insensitive one — that is not a\n * hypothetical, it is how `contains` reached a released package meaning three\n * different things.\n */\nimport { Schema, SchemaGetter } from 'effect'\nimport { Entity, Expr, Order, Query, type AnyQuery } from '../index.js'\n\n/**\n * A `Date` on the way in, an ISO string on the wire — the one fixture whose\n * **encoded form differs from its decoded form**.\n *\n * Every other column here encodes to itself, which is why the suite could not\n * previously see an interpreter comparing a decoded value against an encoded\n * row. That is not a hypothetical bug: a store holds wire values and decodes at\n * read, while a `QueryRef`'s input and a body's literals are written in domain\n * terms, so anything that runs a body over stored rows has to reconcile the two\n * and nothing was checking that it did.\n */\nconst Timestamp = Schema.Date.pipe(\n Schema.encodeTo(Schema.String, {\n decode: SchemaGetter.transform((iso: string) => new Date(iso)),\n encode: SchemaGetter.transform((at: Date) => at.toISOString()),\n }),\n)\n\n/** The one Entity every case reads, with a column of each kind that matters. */\nexport const Subject = Entity.define(\n 'Subject',\n Schema.Struct({\n id: Schema.String,\n /** Mixed case on purpose: a case-blind `contains` must be caught. */\n label: Schema.String,\n rank: Schema.Number,\n /** Nullable on purpose: three-valued logic has to be exercised. */\n tag: Schema.String,\n /** Encoded and decoded forms differ on purpose: see `Timestamp`. */\n at: Timestamp,\n }),\n)\n\n/**\n * How a row looks to an interpreter reading values, and to SQL as a table. The\n * index signature is what lets one be read by key without a cast, which is how\n * an interpreter over plain rows reads one.\n */\nexport interface ConformanceRow {\n readonly id: string\n readonly label: string\n readonly rank: number\n readonly tag: string | null\n /** The **encoded** form: what a store holds and an interpreter compares. */\n readonly at: string\n readonly [key: string]: unknown\n}\n\nexport const rows: ReadonlyArray<ConformanceRow> = [\n { id: 'a', label: 'Intro', rank: 2, tag: null, at: '2026-01-01T00:00:00.000Z' },\n { id: 'b', label: 'intro to sql', rank: 1, tag: 'x', at: '2026-01-02T00:00:00.000Z' },\n { id: 'c', label: 'Other', rank: 3, tag: null, at: '2026-01-02T00:00:00.000Z' },\n { id: 'd', label: '100% cotton', rank: 3, tag: 'x', at: '2026-01-03T00:00:00.000Z' },\n { id: 'e', label: 'snake_case', rank: 4, tag: 'y', at: '2026-01-04T00:00:00.000Z' },\n]\n\nexport interface ConformanceCase {\n /** What the case pins, as a sentence an interpreter fails by name. */\n readonly what: string\n readonly body: AnyQuery\n /**\n * The inputs, **encoded** — the space a store's rows are in, not the domain\n * space the body's types describe. For every column but `at` the two are the\n * same value, which is exactly why this has to be said rather than inferred\n * from the fixtures.\n */\n readonly input: Readonly<Record<string, unknown>>\n /** The ids the body matches, in the order it asks for. */\n readonly expected: ReadonlyArray<string>\n}\n\nconst from = Query.from(Subject)\nconst byId = Query.orderBy(Order.asc(Subject.fields.id))\nconst label = Expr.input('label', Schema.String)\nconst tag = Expr.input('tag', Schema.String)\nconst present = Expr.input('present', Schema.Boolean)\nconst at = Expr.input('at', Timestamp)\n\nexport const cases: ReadonlyArray<ConformanceCase> = [\n // ---- eq ------------------------------------------------------------------\n {\n what: 'eq matches a field against a literal',\n body: from.pipe(Query.where(Expr.eq(Subject.fields.rank, 3)), byId),\n input: {},\n expected: ['c', 'd'],\n },\n {\n what: 'eq matches a field against the value the request supplies',\n body: from.pipe(Query.where(Expr.eq(Subject.fields.label, label)), byId),\n input: { label: 'Other' },\n expected: ['c'],\n },\n {\n what: 'eq is exact: a value that differs only by case does not match',\n body: from.pipe(Query.where(Expr.eq(Subject.fields.label, label)), byId),\n input: { label: 'other' },\n expected: [],\n },\n {\n what: 'eq against null matches nothing, not even the rows that are null',\n body: from.pipe(Query.where(Expr.eq(Subject.fields.tag, tag)), byId),\n input: { tag: null },\n expected: [],\n },\n {\n what: 'eq against a value skips the rows whose column is null',\n body: from.pipe(Query.where(Expr.eq(Subject.fields.tag, 'x')), byId),\n input: {},\n expected: ['b', 'd'],\n },\n\n // ---- isNull / isNotNull --------------------------------------------------\n {\n what: 'isNull finds exactly the rows with no value',\n body: from.pipe(Query.where(Expr.isNull(Subject.fields.tag)), byId),\n input: {},\n expected: ['a', 'c'],\n },\n {\n what: 'isNotNull finds exactly the rest',\n body: from.pipe(Query.where(Expr.isNotNull(Subject.fields.tag)), byId),\n input: {},\n expected: ['b', 'd', 'e'],\n },\n {\n what: 'a predicate compared to a true input is that predicate',\n body: from.pipe(Query.where(Expr.eq(Expr.isNotNull(Subject.fields.tag), present)), byId),\n input: { present: true },\n expected: ['b', 'd', 'e'],\n },\n {\n what: 'a predicate compared to a false input is its negation',\n body: from.pipe(Query.where(Expr.eq(Expr.isNotNull(Subject.fields.tag), present)), byId),\n input: { present: false },\n expected: ['a', 'c'],\n },\n ...[true, false].map(value => ({\n what: `a ${value} input compared to a predicate works in reverse order`,\n body: from.pipe(Query.where(Expr.eq(present, Expr.isNotNull(Subject.fields.tag))), byId),\n input: { present: value },\n expected: value ? ['b', 'd', 'e'] : ['a', 'c'],\n })),\n ...[true, false].map(value => ({\n what: `an unknown equality compared to ${value} stays unknown`,\n body: from.pipe(Query.where(Expr.eq(Expr.eq(Subject.fields.tag, tag), present)), byId),\n input: { tag: null, present: value },\n expected: [],\n })),\n\n // ---- contains ------------------------------------------------------------\n {\n what: 'contains ignores case, which is stated rather than left to the backend',\n body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),\n input: { label: 'INTRO' },\n expected: ['a', 'b'],\n },\n {\n what: 'contains matches anywhere in the value, not only at the start',\n body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),\n input: { label: 'to sql' },\n expected: ['b'],\n },\n {\n what: 'containing the empty string is everything',\n body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),\n input: { label: '' },\n expected: ['a', 'b', 'c', 'd', 'e'],\n },\n {\n what: 'a percent is searched for literally, not as a wildcard',\n body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),\n input: { label: '%' },\n expected: ['d'],\n },\n {\n what: 'an underscore is searched for literally, not as a single-character wildcard',\n body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),\n input: { label: '_' },\n expected: ['e'],\n },\n {\n what: 'contains over a null column drops those rows, so it is not the same as no filter',\n body: from.pipe(Query.where(Expr.contains(Subject.fields.tag, label)), byId),\n input: { label: '' },\n expected: ['b', 'd', 'e'],\n },\n {\n what: 'contains with a null search is unknown for every row',\n body: from.pipe(Query.where(Expr.contains(Subject.fields.label, label)), byId),\n input: { label: null },\n expected: [],\n },\n {\n what: 'an unknown containment compared to false stays unknown',\n body: from.pipe(Query.where(Expr.eq(Expr.contains(Subject.fields.label, label), false)), byId),\n input: { label: null },\n expected: [],\n },\n\n // ---- conjunction, which is the list rather than an operator ---------------\n {\n what: 'two predicates conjoin: every one must hold',\n body: from.pipe(\n Query.where(Expr.eq(Subject.fields.rank, 3), Expr.isNotNull(Subject.fields.tag)),\n byId,\n ),\n input: {},\n expected: ['d'],\n },\n {\n what: 'no predicate at all is every row',\n body: from.pipe(byId),\n input: {},\n expected: ['a', 'b', 'c', 'd', 'e'],\n },\n\n // ---- encoded values ------------------------------------------------------\n // The body's types say `Date`; a store's rows and a request's inputs are ISO\n // strings. An interpreter compares in the **encoded** space, and these are the\n // cases that say so — for every other column the two spaces hold the same\n // value, so nothing here could previously tell them apart.\n //\n // What happens when a caller passes a *decoded* value is deliberately not a\n // case, because the interpreters do not agree: the reference one matches\n // nothing, SQLite raises `datatype mismatch`, and a local engine does\n // whatever its own comparison does. `cases` are what interpreters must agree\n // about. The consequence is pinned in `packages/entity/test/encoding.test.ts`\n // instead, and it is the one that matters: **a runtime error cannot be relied\n // on to catch the mistake**, because one of the three answers is an empty\n // result that reads exactly like a correct one.\n {\n what: 'an input whose encoded form differs from its decoded one matches on the encoded one',\n body: from.pipe(Query.where(Expr.eq(Subject.fields.at, at)), byId),\n input: { at: '2026-01-02T00:00:00.000Z' },\n expected: ['b', 'c'],\n },\n {\n what: 'a literal is encoded too, or it has the same problem as an input',\n body: from.pipe(\n Query.where(Expr.eq(Subject.fields.at, '2026-01-03T00:00:00.000Z' as never)),\n byId,\n ),\n input: {},\n expected: ['d'],\n },\n\n // ---- ordering ------------------------------------------------------------\n {\n what: 'orders ascending by a number',\n body: from.pipe(Query.orderBy(Order.asc(Subject.fields.rank), Order.asc(Subject.fields.id))),\n input: {},\n expected: ['b', 'a', 'c', 'd', 'e'],\n },\n {\n what: 'orders descending, and a later term breaks the tie',\n body: from.pipe(Query.orderBy(Order.desc(Subject.fields.rank), Order.asc(Subject.fields.id))),\n input: {},\n expected: ['e', 'c', 'd', 'a', 'b'],\n },\n // Ordering by text is deliberately not here. How text compares is the\n // backend's — SQLite by code point, TanStack by locale, Postgres by whatever\n // the database was created with — and §6.0.1 puts it outside the conformant\n // subset rather than pretending one of them is the rule. A case asserting an\n // order would only pin whichever engine was written first.\n]\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,MAAM,YAAY,OAAO,KAAK,KAC5B,OAAO,SAAS,OAAO,QAAQ;CAC7B,QAAQ,aAAa,WAAW,QAAgB,IAAI,KAAK,GAAG,CAAC;CAC7D,QAAQ,aAAa,WAAW,OAAa,GAAG,YAAY,CAAC;AAC/D,CAAC,CACH;;AAGA,MAAa,UAAU,OAAO,OAC5B,WACA,OAAO,OAAO;CACZ,IAAI,OAAO;;CAEX,OAAO,OAAO;CACd,MAAM,OAAO;;CAEb,KAAK,OAAO;;CAEZ,IAAI;AACN,CAAC,CACH;AAiBA,MAAa,OAAsC;CACjD;EAAE,IAAI;EAAK,OAAO;EAAS,MAAM;EAAG,KAAK;EAAM,IAAI;CAA2B;CAC9E;EAAE,IAAI;EAAK,OAAO;EAAgB,MAAM;EAAG,KAAK;EAAK,IAAI;CAA2B;CACpF;EAAE,IAAI;EAAK,OAAO;EAAS,MAAM;EAAG,KAAK;EAAM,IAAI;CAA2B;CAC9E;EAAE,IAAI;EAAK,OAAO;EAAe,MAAM;EAAG,KAAK;EAAK,IAAI;CAA2B;CACnF;EAAE,IAAI;EAAK,OAAO;EAAc,MAAM;EAAG,KAAK;EAAK,IAAI;CAA2B;AACpF;AAiBA,MAAM,OAAO,MAAM,KAAK,OAAO;AAC/B,MAAM,OAAO,MAAM,QAAQ,MAAM,IAAI,QAAQ,OAAO,EAAE,CAAC;AACvD,MAAM,QAAQ,KAAK,MAAM,SAAS,OAAO,MAAM;AAC/C,MAAM,MAAM,KAAK,MAAM,OAAO,OAAO,MAAM;AAC3C,MAAM,UAAU,KAAK,MAAM,WAAW,OAAO,OAAO;AACpD,MAAM,KAAK,KAAK,MAAM,MAAM,SAAS;AAErC,MAAa,QAAwC;CAEnD;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,QAAQ,OAAO,MAAM,CAAC,CAAC,GAAG,IAAI;EAClE,OAAO,CAAC;EACR,UAAU,CAAC,KAAK,GAAG;CACrB;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,QAAQ,OAAO,OAAO,KAAK,CAAC,GAAG,IAAI;EACvE,OAAO,EAAE,OAAO,QAAQ;EACxB,UAAU,CAAC,GAAG;CAChB;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,QAAQ,OAAO,OAAO,KAAK,CAAC,GAAG,IAAI;EACvE,OAAO,EAAE,OAAO,QAAQ;EACxB,UAAU,CAAC;CACb;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,QAAQ,OAAO,KAAK,GAAG,CAAC,GAAG,IAAI;EACnE,OAAO,EAAE,KAAK,KAAK;EACnB,UAAU,CAAC;CACb;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,QAAQ,OAAO,KAAK,GAAG,CAAC,GAAG,IAAI;EACnE,OAAO,CAAC;EACR,UAAU,CAAC,KAAK,GAAG;CACrB;CAGA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,OAAO,QAAQ,OAAO,GAAG,CAAC,GAAG,IAAI;EAClE,OAAO,CAAC;EACR,UAAU,CAAC,KAAK,GAAG;CACrB;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,UAAU,QAAQ,OAAO,GAAG,CAAC,GAAG,IAAI;EACrE,OAAO,CAAC;EACR,UAAU;GAAC;GAAK;GAAK;EAAG;CAC1B;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,KAAK,UAAU,QAAQ,OAAO,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI;EACvF,OAAO,EAAE,SAAS,KAAK;EACvB,UAAU;GAAC;GAAK;GAAK;EAAG;CAC1B;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,KAAK,UAAU,QAAQ,OAAO,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI;EACvF,OAAO,EAAE,SAAS,MAAM;EACxB,UAAU,CAAC,KAAK,GAAG;CACrB;CACA,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,KAAI,WAAU;EAC7B,MAAM,KAAK,MAAM;EACjB,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,SAAS,KAAK,UAAU,QAAQ,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI;EACvF,OAAO,EAAE,SAAS,MAAM;EACxB,UAAU,QAAQ;GAAC;GAAK;GAAK;EAAG,IAAI,CAAC,KAAK,GAAG;CAC/C,EAAE;CACF,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,KAAI,WAAU;EAC7B,MAAM,mCAAmC,MAAM;EAC/C,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,KAAK,GAAG,QAAQ,OAAO,KAAK,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI;EACrF,OAAO;GAAE,KAAK;GAAM,SAAS;EAAM;EACnC,UAAU,CAAC;CACb,EAAE;CAGF;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,SAAS,QAAQ,OAAO,OAAO,KAAK,CAAC,GAAG,IAAI;EAC7E,OAAO,EAAE,OAAO,QAAQ;EACxB,UAAU,CAAC,KAAK,GAAG;CACrB;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,SAAS,QAAQ,OAAO,OAAO,KAAK,CAAC,GAAG,IAAI;EAC7E,OAAO,EAAE,OAAO,SAAS;EACzB,UAAU,CAAC,GAAG;CAChB;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,SAAS,QAAQ,OAAO,OAAO,KAAK,CAAC,GAAG,IAAI;EAC7E,OAAO,EAAE,OAAO,GAAG;EACnB,UAAU;GAAC;GAAK;GAAK;GAAK;GAAK;EAAG;CACpC;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,SAAS,QAAQ,OAAO,OAAO,KAAK,CAAC,GAAG,IAAI;EAC7E,OAAO,EAAE,OAAO,IAAI;EACpB,UAAU,CAAC,GAAG;CAChB;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,SAAS,QAAQ,OAAO,OAAO,KAAK,CAAC,GAAG,IAAI;EAC7E,OAAO,EAAE,OAAO,IAAI;EACpB,UAAU,CAAC,GAAG;CAChB;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,SAAS,QAAQ,OAAO,KAAK,KAAK,CAAC,GAAG,IAAI;EAC3E,OAAO,EAAE,OAAO,GAAG;EACnB,UAAU;GAAC;GAAK;GAAK;EAAG;CAC1B;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,SAAS,QAAQ,OAAO,OAAO,KAAK,CAAC,GAAG,IAAI;EAC7E,OAAO,EAAE,OAAO,KAAK;EACrB,UAAU,CAAC;CACb;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,KAAK,SAAS,QAAQ,OAAO,OAAO,KAAK,GAAG,KAAK,CAAC,GAAG,IAAI;EAC7F,OAAO,EAAE,OAAO,KAAK;EACrB,UAAU,CAAC;CACb;CAGA;EACE,MAAM;EACN,MAAM,KAAK,KACT,MAAM,MAAM,KAAK,GAAG,QAAQ,OAAO,MAAM,CAAC,GAAG,KAAK,UAAU,QAAQ,OAAO,GAAG,CAAC,GAC/E,IACF;EACA,OAAO,CAAC;EACR,UAAU,CAAC,GAAG;CAChB;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,IAAI;EACpB,OAAO,CAAC;EACR,UAAU;GAAC;GAAK;GAAK;GAAK;GAAK;EAAG;CACpC;CAgBA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,GAAG,QAAQ,OAAO,IAAI,EAAE,CAAC,GAAG,IAAI;EACjE,OAAO,EAAE,IAAI,2BAA2B;EACxC,UAAU,CAAC,KAAK,GAAG;CACrB;CACA;EACE,MAAM;EACN,MAAM,KAAK,KACT,MAAM,MAAM,KAAK,GAAG,QAAQ,OAAO,IAAI,0BAAmC,CAAC,GAC3E,IACF;EACA,OAAO,CAAC;EACR,UAAU,CAAC,GAAG;CAChB;CAGA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,QAAQ,MAAM,IAAI,QAAQ,OAAO,IAAI,GAAG,MAAM,IAAI,QAAQ,OAAO,EAAE,CAAC,CAAC;EAC3F,OAAO,CAAC;EACR,UAAU;GAAC;GAAK;GAAK;GAAK;GAAK;EAAG;CACpC;CACA;EACE,MAAM;EACN,MAAM,KAAK,KAAK,MAAM,QAAQ,MAAM,KAAK,QAAQ,OAAO,IAAI,GAAG,MAAM,IAAI,QAAQ,OAAO,EAAE,CAAC,CAAC;EAC5F,OAAO,CAAC;EACR,UAAU;GAAC;GAAK;GAAK;GAAK;GAAK;EAAG;CACpC;AAMF"}
package/dist/index.d.mts CHANGED
@@ -77,8 +77,35 @@ export type Operandish = AnyExpr | Predicate;
77
77
  type Operand<T> = EntityField<string, string, Schema.Constraint> | Expr<T> | Predicate;
78
78
  /** What an operand is worth, so a comparison's other side is checked against it. */
79
79
  export 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;
80
+ /**
81
+ * A field or scalar whose value is text, or absent text.
82
+ *
83
+ * `Expr.contains` is a case-insensitive **text** search that compiles to
84
+ * `lower(column) like lower(?)`. Over a number that is nonsense which reaches
85
+ * the database — SQLite coerces and answers something, Postgres raises — so
86
+ * the operand is constrained here rather than discovered there.
87
+ *
88
+ * Null belongs in the type, because a nullable text column is a real and
89
+ * documented case: a null contains nothing, not even the empty string, so its
90
+ * rows drop out of a search that would otherwise match everything.
91
+ *
92
+ * Written as a **constraint on the type parameter** rather than as a check
93
+ * intersected onto the parameter (the `Invalid` idiom `foldkit-remote` uses for
94
+ * an unregistered descriptor). That idiom compares an already-resolved indexed
95
+ * access; here the check would be a conditional over the type being inferred,
96
+ * and inference falls back to the constraint — whose `Expr<any>` branch makes
97
+ * the check vacuously true, so every operand passes. A constraint cannot be
98
+ * defeated that way.
99
+ */
100
+ export type TextOperand = EntityField<string, string, Schema.Constraint & Schema.Codec<string | null, any, any, any>> | Expr<string> | Expr<string | null>;
80
101
  /** Whether a value is a predicate, and so usable where a boolean is wanted. */
81
102
  export declare const isPredicate: (value: unknown) => value is Predicate;
103
+ /**
104
+ * Every operation the kernel has. An interpreter declares which of them it
105
+ * runs, and a body needing one it does not is refused rather than answered
106
+ * wrongly — see `Query.unsupported`.
107
+ */
108
+ export type Operation = 'eq' | 'isNull' | 'isNotNull' | 'contains';
82
109
  /** Which fields and inputs an expression reads, and which operations it uses. */
83
110
  export interface Dependencies {
84
111
  /** One entry per distinct field, as `Entity.key`. */
@@ -89,7 +116,7 @@ export interface Dependencies {
89
116
  /** One entry per distinct input key. */
90
117
  readonly inputs: ReadonlyArray<string>;
91
118
  /** One entry per distinct operation, so an interpreter can refuse what it cannot run. */
92
- readonly operations: ReadonlyArray<string>;
119
+ readonly operations: ReadonlyArray<Operation>;
93
120
  }
94
121
  export declare const Expr: {
95
122
  /** A constant. Comparisons coerce a plain value, so this is rarely written. */
@@ -136,7 +163,9 @@ export declare const Expr: {
136
163
  * `Expr.or` does not exist yet, so for now such a column needs its own
137
164
  * predicate or a native escape hatch.
138
165
  */
139
- contains: <L extends Operand<any>>(value: L, search: string | Expr<string>) => ContainsPredicate;
166
+ contains: <L extends TextOperand>(value: L, search: string | Expr<string>) => ContainsPredicate;
167
+ /** An expression as readable text; see `showExpr` for what it is and is not. */
168
+ show: (node: Operandish) => string;
140
169
  };
141
170
  /** One term of an ordering: a scalar and the direction to read it in. */
142
171
  export interface OrderTerm {
@@ -204,8 +233,70 @@ export declare const Query: {
204
233
  * every ordering term, and the operations it uses.
205
234
  */
206
235
  dependencies: (self: AnyQuery) => Dependencies;
236
+ /**
237
+ * The operations this query needs that `supported` does not list, in the
238
+ * order the query uses them. Empty means an interpreter declaring
239
+ * `supported` can answer it.
240
+ *
241
+ * An interpreter declares what it runs and refuses the rest, rather than
242
+ * ignoring an operation it does not implement — which would answer a
243
+ * different question and say nothing. The refusal is the interpreter's to
244
+ * raise: this only says what is missing, because what to do about it differs
245
+ * between one that compiles at registration and one that runs a body
246
+ * directly.
247
+ *
248
+ * ```ts
249
+ * const missing = Query.unsupported(body, ['eq', 'isNull', 'isNotNull'])
250
+ * if (missing.length > 0) throw new Error(`cannot run ${missing.join(', ')}`)
251
+ * ```
252
+ */
253
+ unsupported: (self: AnyQuery, supported: ReadonlyArray<Operation>) => ReadonlyArray<Operation>;
254
+ /**
255
+ * The whole query as readable text, one clause per line:
256
+ *
257
+ * ```text
258
+ * FROM Post
259
+ * WHERE Post.slug = $slug
260
+ * AND Post.published = true
261
+ * ORDER BY Post.updatedAt DESC
262
+ * ```
263
+ *
264
+ * For an explanation or a diagnostic, never for an interpreter — see
265
+ * `Expr.show`. A query with no `where` or no `orderBy` omits that line rather
266
+ * than printing an empty one, so what is shown is what was written.
267
+ */
268
+ show: (self: AnyQuery) => string;
207
269
  };
208
270
  //#endregion
271
+ //#region src/evaluate.d.ts
272
+ /** A row as this interpreter reads one: values by field key. */
273
+ export type Row = Readonly<Record<string, unknown>>;
274
+ export declare class QueryEvaluateError extends Error {
275
+ constructor(message: string);
276
+ }
277
+ /**
278
+ * The operations this interpreter runs. It is the reference, so this is the
279
+ * whole kernel — but it is declared rather than assumed, because an
280
+ * interpreter that gains an operator and forgets to say so is exactly what
281
+ * `Query.unsupported` exists to catch.
282
+ */
283
+ export declare const supported: ReadonlyArray<Operation>;
284
+ /**
285
+ * Refuses a body needing an operation this interpreter does not run, rather
286
+ * than skipping it and answering a different question. Called by `evaluate`;
287
+ * call it directly to check a body once instead of on every run.
288
+ */
289
+ export declare const assertSupported: (body: AnyQuery) => void;
290
+ /**
291
+ * The rows the body matches, in the order it asks for. Pure: it reads the rows
292
+ * it is given and nothing else.
293
+ *
294
+ * `input` holds the values this run was given, by the keys the body's
295
+ * placeholders were built with — the same record the query would be called
296
+ * with anywhere else.
297
+ */
298
+ export declare const evaluate: (body: AnyQuery, input: Row, rows: ReadonlyArray<Row>) => ReadonlyArray<Row>;
299
+ //#endregion
209
300
  //#region src/index.d.ts
210
301
  export declare const EntityTypeId: unique symbol;
211
302
  export type EntityTypeId = typeof EntityTypeId;