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 +256 -7
- 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 +344 -21
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +469 -6
- package/dist/index.mjs.map +1 -1
- package/package.json +5 -1
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
|
|
12
|
-
>
|
|
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
|
-
##
|
|
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
|
|
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
|
|
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
|
-
-
|
|
304
|
-
|
|
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
|