foldkit-entity 0.1.0 → 0.3.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
@@ -8,8 +8,8 @@ packages interpret that declaration; this one only describes.
8
8
  > [registers Entities and reads Selections as they are](../remote/README.md#entities-declared-with-foldkit-entity).
9
9
  > `foldkit-remote-drizzle` binds a related set to tables with
10
10
  > [`bind`](../remote-drizzle/README.md#binding-a-foldkit-entity-domain), and
11
- > [`foldkit-form`](../form/README.md) builds a form from `Entity.input`. Admin
12
- > is planned in [entity-DESIGN.md](../../docs/design/entity-DESIGN.md).
11
+ > [`foldkit-form`](../form/README.md) builds a form from `Entity.input`, and
12
+ > [`foldkit-crud`](../crud/README.md) joins one to a Remote operation.
13
13
 
14
14
  For the whole path in one runnable trace, domain to client to SQL, see
15
15
  [`examples/entity`](../../examples/entity).
@@ -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'
@@ -110,6 +135,43 @@ each entity declared its own relations, `Post` would be typed in terms of
110
135
  constants that way. Declaring the relations over entities that already exist
111
136
  avoids the cycle, and lets `relate` check every target up front.
112
137
 
138
+ ## Ids of their own
139
+
140
+ An Entity is identified by its `id` field, and the id keeps the type you give
141
+ it. Brand it, and a ref to an Author can no longer stand in for a Post's:
142
+
143
+ ```ts
144
+ const AuthorId = Schema.String.pipe(Schema.brand('AuthorId'))
145
+ const PostId = Schema.String.pipe(Schema.brand('PostId'))
146
+
147
+ const Writer = Entity.define('Author', Schema.Struct({ id: AuthorId, name: Schema.String }))
148
+ const Article = Entity.define('Post', Schema.Struct({ id: PostId, title: Schema.String }))
149
+ const Press = Entity.relate({ Writer, Article }, { Article: { author: Relation.one(Writer) } })
150
+
151
+ type WriterId = import('foldkit-entity').IdOf<typeof Press.Writer> // AuthorId
152
+
153
+ const ByLine = Entity.select(Press.Article, { author: true })
154
+ // { author: EntityRef<'Author', AuthorId> }
155
+
156
+ Entity.input(Press.Article, Schema.Struct({ authorId: AuthorId }), {
157
+ authorId: Relation.input(Press.Article.relations.author), // a PostId, or any text, is a type error
158
+ })
159
+ ```
160
+
161
+ - `IdOf<E>` is the type of the `id` field; `EntityRef<Name, Id>` carries it, and
162
+ `Relation.input` takes it (`Id | null` for an optional `one`, a list for a
163
+ `many`).
164
+ - A ref's schema is the id's own, so a pattern or a check on the id holds for
165
+ every ref to it.
166
+ - **An id is text.** A ref travels and is stored as text, so an Entity whose `id`
167
+ is a number (or has no `id` field) has refs with a plain `string` id: the
168
+ number as text.
169
+ - A Selection carries its Entity's id type, so `foldkit-remote`'s
170
+ `Data.get(PostPage, id)` takes a `PostId` and refuses an `AuthorId`, or plain
171
+ text.
172
+ - Nothing here is new API to opt into. An Entity with `id: Schema.String` types
173
+ exactly as before.
174
+
113
175
  ## Selecting a view
114
176
 
115
177
  A Selection names the members a consumer wants and carries the schema of the
@@ -142,7 +204,7 @@ PostRow.schema.Type
142
204
  | Field, Derived | `true` | the member's own schema, checks included |
143
205
  | Relation | `true` | an `EntityRef`: `{ entity, id }` |
144
206
  | Relation | a Selection of its target | that Selection's value |
145
- | `many` Relation | `Entity.page(selection, window)` | a `Page` of that Selection's values |
207
+ | `many` Relation | `Entity.page(selection, window)` | a page of that Selection's values: `{ items, hasNext, hasPrevious }` |
146
208
 
147
209
  A `many` relation yields an array, and an optional `one` is nullable. A
148
210
  Selection is an ordinary value, so `AuthorOption` above is declared once and
@@ -206,6 +268,12 @@ CreatePost.members.notify // Entity.unmapped: about the operation, not the Post
206
268
  - Every other key needs an entry: a Field under another name, a relation's ids
207
269
  with `Relation.input(relation)`, or `Entity.unmapped`. Nothing is inferred
208
270
  from a name like `authorId`.
271
+ - An entry may name the member by its key: `{ headline: 'title', authorId: 'author' }`
272
+ is the `title` Field and `Relation.input` of `author`. It is the same reading,
273
+ checked the same way; a name that is no field or relation is a type error.
274
+ - `Entity.fields(Post, 'id', 'title')` is those fields' schemas, to spread into
275
+ the input's struct, so the input keeps the field's rules without repeating
276
+ `Post.fields.title.schema` per key.
209
277
  - `Relation.input` expects one id for a `one`, `id | null` for an optional
210
278
  `one`, and an array of ids for a `many`.
211
279
  - A derived member cannot be written, and a member of another Entity cannot be
@@ -280,6 +348,172 @@ Entity.same(CmsPost, Blog.Post) // true: the metadata changed, the entity did no
280
348
 
281
349
  Annotating again combines with what is there, using the key's own `merge`.
282
350
 
351
+ ## Saying something about a row: `Expr`
352
+
353
+ An Entity says what a domain has. An `Expr` says something about one row of it,
354
+ as a value:
355
+
356
+ > **Why query semantics live in this package.** They describe and interpret
357
+ > nothing, which is the line this package already draws: an `Expr` says which
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
369
+ > `Entity` pays for them: they are ordinary consts in a `sideEffects: false`
370
+ > package, so a bundler drops them, and a package like `foldkit-form` imports
371
+ > only types from here in any case.
372
+
373
+ ```ts
374
+ import { Expr, Order } from 'foldkit-entity'
375
+
376
+ const byTitle = Expr.eq(Blog.Post.fields.title, Expr.input('title', Schema.String))
377
+ const published = Expr.eq(Blog.Post.fields.published, true)
378
+ const newest = [Order.desc(Blog.Post.fields.title), Order.asc(Blog.Post.fields.id)]
379
+ ```
380
+
381
+ Building one performs no work: it reads nothing, names no database, and runs no
382
+ query. An interpreter compiles it — `foldkit-remote-drizzle` to SQL, an
383
+ in-memory evaluator to a predicate over rows — which is what lets one query mean
384
+ the same thing in more than one place.
385
+
386
+ A comparison coerces what it is given, so the common forms read as they mean: a
387
+ field becomes a reference, a plain value becomes a literal, and an `Expr` is
388
+ already one. What it will not do is compare a field to the wrong kind of value —
389
+ `Expr.eq(Blog.Post.fields.title, 42)` is an error where it is written, rather
390
+ than a row that never matches.
391
+
392
+ **An input is a placeholder, not a value.** A query's body is built once, so
393
+ `Expr.input('title', …)` stands for whatever the query is given when it runs —
394
+ there is nothing there yet to branch on. An `InputExpr` is an object, so a
395
+ `condition ? a : b` over one is always truthy and decides itself once, forever.
396
+ A query that depends on what it was passed says so with a comparison over the
397
+ placeholder instead of a branch around it.
398
+
399
+ `dependenciesOf(...)` says which fields and inputs an expression reads and which
400
+ operations it uses, so a planner knows what it needs and an interpreter can
401
+ refuse a query it cannot run.
402
+
403
+ ### Asking a question that depends on an input, without branching on it
404
+
405
+ Since an input is a placeholder, a query cannot choose between two shapes based
406
+ on what it was given. It does not need to: a question that looks like a branch
407
+ is usually a comparison waiting to be written.
408
+
409
+ ```ts
410
+ // A list that shows archived entries or unarchived ones, as the reader asks:
411
+ Expr.eq(Expr.isNotNull(Entry.fields.archivedAt), input.archived)
412
+
413
+ // A search box that filters when something is typed and not when nothing is:
414
+ Expr.contains(Entry.fields.label, input.search)
415
+ ```
416
+
417
+ The first is "is-archived equals what you asked for". The second relies on
418
+ everything containing the empty string. Both are one static body, and both ask
419
+ exactly what `archived ? … : …` and `search === '' ? … : …` asked.
420
+
421
+ `isNull` and `isNotNull` are the same node with the answer absence gives
422
+ flipped, so nothing has to negate a predicate to get the other.
423
+
424
+ **`contains` is case-insensitive**, which is what a search means — and which
425
+ has to be said, not left to the interpreter: SQLite's `like` ignores case and
426
+ Postgres's does not, so a body that left it open would mean two things. Folding
427
+ is ASCII-only, since that is what `lower` does in SQLite without ICU.
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
+
435
+ **Over a column that can be null it is not the same as no filter.** A null
436
+ contains nothing, not even the empty string, so its rows drop out. The column
437
+ the CMS searches is declared not-null, which is what makes an empty search
438
+ exactly everything there.
439
+
440
+ ### Which rows: `Query`
441
+
442
+ A `Query` is an Entity to read, the predicates every row must hold, and the
443
+ order to read them in — composed with `pipe`, one immutable value per step:
444
+
445
+ ```ts
446
+ const published = Query.where(Expr.eq(Blog.Post.fields.published, true))
447
+ const newest = Query.orderBy(Order.desc(Blog.Post.fields.title))
448
+
449
+ const recent = Query.from(Blog.Post).pipe(published, newest)
450
+ const oneOf = Query.from(Blog.Post).pipe(published, Query.where(byTitle))
451
+ ```
452
+
453
+ `published` and `newest` are fragments: written once, piped into any query over
454
+ the same Entity. Composing performs no work — no table is named, no connection
455
+ opened, nothing read.
456
+
457
+ **Two `where`s conjoin and two `orderBy`s append.** Neither replaces what came
458
+ before, so piping a fragment can only ever narrow a query, never silently undo
459
+ part of it. An earlier ordering term stays the more significant one, which is
460
+ what makes a later `Query.orderBy(Order.asc(id))` a tie-breaker. Neither ever replaces what a fragment added.
461
+
462
+ The list of predicates **is** the conjunction — which is why no `Expr.and`
463
+ exists. A query wanting three conditions writes three `where`s. An `and`
464
+ operator is only needed for a conjunction nested inside something else, and no
465
+ query here has one yet.
466
+
467
+ A query reads one Entity, so a predicate or ordering term naming a different
468
+ one is refused where it is piped: an interpreter would otherwise be asked for a
469
+ column of a table it was never told to read. Entities are compared by identity,
470
+ so two declared with the same name are two Entities here as everywhere else.
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
+
509
+ A `Query` says which rows. It does not say which fields — that is a Selection —
510
+ and it does not say how many, whether absence is an error, or whether to watch
511
+ for changes: those belong to the consumer doing the reading, not to the
512
+ relation.
513
+
514
+ Only the operations a real query in this repository needs exist. The set grows
515
+ from queries, not from what a database could express.
516
+
283
517
  ## API
284
518
 
285
519
  | Call | Meaning |
@@ -287,7 +521,8 @@ Annotating again combines with what is there, using the key's own `merge`.
287
521
  | `Entity.define(name, struct)` | A new Entity with a Field per property. |
288
522
  | `Entity.relate(entities, { Owner: { key: Relation.one(Target) } })` | The entities with their relations declared; targets resolve to the returned entities. |
289
523
  | `Entity.select(entity, { key: true or Selection })` | A Selection: what was selected (`members`) and the `schema` of the result. |
290
- | `Entity.page(selection, { first, after } or { last, before })` | In a Selection, a `many` relation read as a `Page`: `items`, `hasNext`, `hasPrevious`. |
524
+ | `Entity.page(selection, { first, after } or { last, before })` | In a Selection, a `many` relation read as a page: `items`, `hasNext`, `hasPrevious`. |
525
+ | `Entity.fields(entity, ...keys)` | The schemas of those fields, by key, to spread into an input's struct. |
291
526
  | `Entity.input(entity, struct, mapping?)` | Experimental. Which member each key of an operation's input writes. |
292
527
  | `Relation.nested(relation, input)` | In an input mapping: the key holds the target itself, written through `input`. |
293
528
  | `Entity.selectFor(input)` | The Selection of the members an input writes: what an edit screen loads. |
@@ -297,11 +532,25 @@ Annotating again combines with what is there, using the key's own `merge`.
297
532
  | `Entity.annotateMembers({ key: metadata })` | Pipe step attaching metadata to members by key. |
298
533
  | `Entity.same(a, b)` | Whether two descriptors are versions of one Entity. |
299
534
  | `Entity.is(value)` | Whether a value is an Entity descriptor. |
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. |
536
+ | `Expr.isNull(field)` / `Expr.isNotNull(field)` | Whether a value is absent; one node, with the answer absence gives flipped. |
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. |
538
+ | `Expr.field(field)` | One field of one Entity, as a scalar. |
539
+ | `Expr.input(key, schema)` | A value the query is given when it runs, as a placeholder. |
540
+ | `Expr.literal(value)` | A constant. Comparisons coerce one, so this is rarely written. |
541
+ | `Order.asc(expr)` / `Order.desc(expr)` | One term of an ordering, over a field or a scalar. |
542
+ | `dependenciesOf(...nodes)` | The distinct fields, inputs, and operations those expressions use. |
543
+ | `Query.from(entity)` | Every row of an Entity: the query each step narrows. |
544
+ | `Query.where(...predicates)` | Pipe step keeping the rows those hold for; conjoins with what is there. |
545
+ | `Query.orderBy(...terms)` | Pipe step reading in that order; appends after existing terms. |
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. |
300
549
 
301
550
  ## Limits
302
551
 
303
- - IDs are untyped; nothing marks which field is the identifier yet, and an
304
- `EntityRef` id is a `string`.
552
+ - The identifier is the field named `id`; no other field can be declared as it,
553
+ because Remote keys its store by `id`.
305
554
  - A Selection has no filtering or ordering, and a page has no total; those
306
555
  belong to the interpreter that fetches.
307
556
  - Relations reach only the entities of one `Entity.relate` call; relating the
@@ -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