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 +84 -6
- package/dist/conformance/index.d.mts +46 -0
- package/dist/conformance/index.d.mts.map +1 -0
- package/dist/conformance/index.mjs +293 -0
- package/dist/conformance/index.mjs.map +1 -0
- package/dist/index.d.mts +93 -2
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +191 -3
- package/dist/index.mjs.map +1 -1
- package/package.json +7 -3
package/README.md
CHANGED
|
@@ -51,7 +51,32 @@ not when `a === b`.
|
|
|
51
51
|
pnpm add effect foldkit-entity
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
-
##
|
|
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
|
|
334
|
-
> elsewhere — `foldkit-remote-drizzle` compiles a body to SQL
|
|
335
|
-
>
|
|
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":"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"}
|
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<
|
|
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
|
|
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;
|