foldkit-entity 0.16.0 → 0.18.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 +582 -240
- package/dist/conformance/index.d.ts.map +1 -1
- package/dist/conformance/index.js +30 -4
- package/dist/conformance/index.js.map +1 -1
- package/dist/conformance/operator.d.ts.map +1 -1
- package/dist/conformance/operator.js +13 -4
- package/dist/conformance/operator.js.map +1 -1
- package/dist/descriptor.d.ts +5 -1
- package/dist/descriptor.d.ts.map +1 -1
- package/dist/descriptor.js +6 -2
- package/dist/descriptor.js.map +1 -1
- package/dist/entity.d.ts +16 -3
- package/dist/entity.d.ts.map +1 -1
- package/dist/entity.js +44 -14
- package/dist/entity.js.map +1 -1
- package/dist/enumerate.d.ts +44 -0
- package/dist/enumerate.d.ts.map +1 -0
- package/dist/enumerate.js +128 -0
- package/dist/enumerate.js.map +1 -0
- package/dist/evaluate.d.ts +12 -6
- package/dist/evaluate.d.ts.map +1 -1
- package/dist/evaluate.js +48 -23
- package/dist/evaluate.js.map +1 -1
- package/dist/expr.d.ts +78 -22
- package/dist/expr.d.ts.map +1 -1
- package/dist/expr.js +86 -57
- package/dist/expr.js.map +1 -1
- package/dist/footprint.d.ts +120 -0
- package/dist/footprint.d.ts.map +1 -0
- package/dist/footprint.js +41 -0
- package/dist/footprint.js.map +1 -0
- package/dist/held.js +11 -3
- package/dist/held.js.map +1 -1
- package/dist/index.d.ts +24 -7
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -6
- package/dist/index.js.map +1 -1
- package/dist/invariant.d.ts +41 -11
- package/dist/invariant.d.ts.map +1 -1
- package/dist/invariant.js +102 -51
- package/dist/invariant.js.map +1 -1
- package/dist/law.d.ts.map +1 -1
- package/dist/law.js +3 -9
- package/dist/law.js.map +1 -1
- package/dist/lawCore.d.ts +42 -0
- package/dist/lawCore.d.ts.map +1 -0
- package/dist/lawCore.js +12 -0
- package/dist/lawCore.js.map +1 -0
- package/dist/lawIds.d.ts +15 -0
- package/dist/lawIds.d.ts.map +1 -0
- package/dist/lawIds.js +13 -0
- package/dist/lawIds.js.map +1 -0
- package/dist/laws.d.ts +308 -0
- package/dist/laws.d.ts.map +1 -0
- package/dist/laws.js +566 -0
- package/dist/laws.js.map +1 -0
- package/dist/memoryTable.d.ts +11 -0
- package/dist/memoryTable.d.ts.map +1 -0
- package/dist/memoryTable.js +69 -0
- package/dist/memoryTable.js.map +1 -0
- package/dist/operators.d.ts +1 -1
- package/dist/operators.d.ts.map +1 -1
- package/dist/operators.js +2 -66
- package/dist/operators.js.map +1 -1
- package/dist/refine.d.ts +64 -0
- package/dist/refine.d.ts.map +1 -0
- package/dist/refine.js +104 -0
- package/dist/refine.js.map +1 -0
- package/dist/rows.d.ts +15 -0
- package/dist/rows.d.ts.map +1 -0
- package/dist/rows.js +23 -0
- package/dist/rows.js.map +1 -0
- package/dist/sets.js.map +1 -1
- package/dist/uncollated.d.ts +10 -0
- package/dist/uncollated.d.ts.map +1 -0
- package/dist/uncollated.js +18 -0
- package/dist/uncollated.js.map +1 -0
- package/dist/write.d.ts +65 -7
- package/dist/write.d.ts.map +1 -1
- package/dist/write.js +128 -30
- package/dist/write.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,23 +1,15 @@
|
|
|
1
1
|
# foldkit-entity
|
|
2
2
|
|
|
3
|
-
A domain declared once as typed values
|
|
4
|
-
relations
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
> and judges the rows it holds by them. `foldkit-remote-drizzle` binds a related
|
|
14
|
-
> set to tables with
|
|
15
|
-
> [`bind`](../remote-drizzle/README.md#binding-a-foldkit-entity-domain) and
|
|
16
|
-
> compiles bodies, writes and invariants to SQL. [`foldkit-form`](../form/README.md)
|
|
17
|
-
> builds a form from `Entity.input`, [`foldkit-crud`](../crud/README.md) joins
|
|
18
|
-
> one to a Remote operation, and `foldkit-guard` writes its rules as `Expr`.
|
|
19
|
-
|
|
20
|
-
For the whole path in one runnable trace, domain to client to SQL, see
|
|
3
|
+
A domain declared once as typed values, which other packages interpret: each
|
|
4
|
+
Entity's fields, relations and derived members, and over them a small language
|
|
5
|
+
for which rows (`Expr`, `Query`), what a write does to one (`Write`), and what
|
|
6
|
+
every stored row must hold (invariants). This package only describes, and
|
|
7
|
+
gives the language its reference meaning over rows already in hand.
|
|
8
|
+
|
|
9
|
+
New to the idea of one declared domain? Start with the guide,
|
|
10
|
+
[One domain declaration](../../docs/entity.md), which carries a small domain
|
|
11
|
+
through every reader; this README is the reference for each declaration. For
|
|
12
|
+
the whole path in one runnable trace, domain to client to SQL, see
|
|
21
13
|
[`examples/entity`](../../examples/entity).
|
|
22
14
|
|
|
23
15
|
## What it owns
|
|
@@ -42,46 +34,37 @@ It does not own:
|
|
|
42
34
|
- **Who may.** Authorization is `foldkit-guard`'s, written in the same `Expr`.
|
|
43
35
|
- **Application state.** Nothing here touches a Model or dispatches a Message.
|
|
44
36
|
|
|
37
|
+
Its readers are the neighbouring packages. `foldkit-remote`
|
|
38
|
+
[registers Entities and reads Selections and query bodies](../remote/README.md#entities-declared-with-foldkit-entity),
|
|
39
|
+
and judges the rows it holds by them. `foldkit-remote-drizzle` binds a related
|
|
40
|
+
set to tables with
|
|
41
|
+
[`bind`](../remote-drizzle/README.md#binding-a-foldkit-entity-domain) and
|
|
42
|
+
compiles bodies, writes and invariants to SQL. [`foldkit-form`](../form/README.md)
|
|
43
|
+
builds a form from `Entity.input`, [`foldkit-crud`](../crud/README.md) joins
|
|
44
|
+
one to a Remote operation, and `foldkit-guard` writes its rules as `Expr`.
|
|
45
|
+
|
|
45
46
|
## Mental model
|
|
46
47
|
|
|
47
|
-
|
|
48
|
-
Entity
|
|
49
|
-
├── fields intrinsic values: the properties of entity.schema
|
|
50
|
-
├── relations navigation edges: one / many of another Entity (Entity.relate)
|
|
51
|
-
├── derived readable values an interpreter supplies, counts or finds
|
|
52
|
-
├── members all three under one namespace; keys never collide
|
|
53
|
-
├── sets members the write's context fills (who asks, when)
|
|
54
|
-
└── invariants what every stored row must hold (kept in its metadata)
|
|
55
|
-
|
|
56
|
-
over it, as data:
|
|
57
|
-
Selection which members a consumer reads Entity.select
|
|
58
|
-
Query which rows, in which order Query.from · Expr
|
|
59
|
-
Write what one operation does to one row Write.update / insert / delete
|
|
60
|
-
|
|
61
|
-
interpreter ──(foldkit-metadata)──► Entity / member attaches what it needs
|
|
62
|
-
interpreter ◄── reads all of the above, and runs it (SQL, the client's store)
|
|
63
|
-
```
|
|
48
|
+
An Entity is declared once, as data. It has:
|
|
64
49
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
descriptors with `Entity.same(a, b)`, not `a === b`.
|
|
50
|
+
- **fields**: intrinsic values, the properties of `entity.schema`;
|
|
51
|
+
- **relations**: navigation edges, one or many of another Entity (`Entity.relate`);
|
|
52
|
+
- **derived** values: readable values an interpreter supplies, such as counts or finds;
|
|
53
|
+
- **members**: all three under one namespace, so keys never collide;
|
|
54
|
+
- **sets**: members the write's context fills (who asks, when);
|
|
55
|
+
- **invariants**: what every stored row must hold (`Entity.invariant`).
|
|
72
56
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
```
|
|
57
|
+
Over an Entity, also as data, a **Selection** says which members a consumer reads
|
|
58
|
+
(`Entity.select`), a **Query** says which rows in which order (`Query.from` and
|
|
59
|
+
`Expr`), and a **Write** says what one operation does to one row (`Write.update`,
|
|
60
|
+
`insert`, `delete`).
|
|
78
61
|
|
|
79
|
-
|
|
80
|
-
|
|
62
|
+
An interpreter reads all of that and runs it: SQL, or the client's store. Through
|
|
63
|
+
`foldkit-metadata` it can attach to an Entity or a member what it needs.
|
|
81
64
|
|
|
82
|
-
|
|
83
|
-
can see it,
|
|
84
|
-
something refuses it by name rather than skipping it.
|
|
65
|
+
A declaration is checked where it is made wherever it can be: a type error
|
|
66
|
+
where the types can see it, a throw for what they cannot. An interpreter that
|
|
67
|
+
cannot run something refuses it by name rather than skipping it.
|
|
85
68
|
|
|
86
69
|
## Install
|
|
87
70
|
|
|
@@ -114,6 +97,16 @@ Next, hand the Entity to Remote for client reads or bind it to Drizzle tables
|
|
|
114
97
|
on the server. Declare operation input separately when adding a form: selecting
|
|
115
98
|
readable fields does not grant permission to write them.
|
|
116
99
|
|
|
100
|
+
## Where to go next
|
|
101
|
+
|
|
102
|
+
| To | Reference, here | Taught in |
|
|
103
|
+
| --- | --- | --- |
|
|
104
|
+
| Declare Entities, relations and derived members, and select what a reader wants | [Relations and derived values](#relations-and-derived-values), [Selecting a view](#selecting-a-view), [variants](#rows-of-several-shapes-variants) | [One domain declaration](../../docs/entity.md) |
|
|
105
|
+
| Say which rows, and judge one you hold | [`Expr`, `Query`, `Judge`](#saying-something-about-a-row-expr) | [Expressions](../../docs/expressions.md) |
|
|
106
|
+
| Read an operation's input and declare what it writes | [Reading an operation's input](#reading-an-operations-input), [Declaring what an input writes](#declaring-what-an-input-writes) | [Declared writes](../../docs/declared-writes.md) |
|
|
107
|
+
| Say what every row must hold, and check every write against it | [Invariants](#what-every-row-and-change-must-hold-invariants), [States and `Laws.check`](#states-of-a-row-and-what-every-write-does-to-them) | [Laws](../../docs/laws.md) |
|
|
108
|
+
| Name a question an interpreter answers its own way | [Operators](#naming-a-question-operators) | [Operators](../../docs/operators.md) |
|
|
109
|
+
|
|
117
110
|
## Relations and derived values
|
|
118
111
|
|
|
119
112
|
```ts
|
|
@@ -159,7 +152,7 @@ Object.keys(Blog.Post.members) // id, title, published, author, editor, comments
|
|
|
159
152
|
Entity's relation, so it is added after `Entity.relate`:
|
|
160
153
|
|
|
161
154
|
```ts
|
|
162
|
-
const
|
|
155
|
+
const CountedPost = Blog.Post.pipe(
|
|
163
156
|
Entity.derived({ commentTotal: Derived.count(Blog.Comment.relations.post) }),
|
|
164
157
|
)
|
|
165
158
|
```
|
|
@@ -173,7 +166,7 @@ Object.keys(Blog.Post.members) // id, title, published, author, editor, comments
|
|
|
173
166
|
relation of the same Entity: "did I comment on this post?"
|
|
174
167
|
|
|
175
168
|
```ts
|
|
176
|
-
const
|
|
169
|
+
const PostWithMyComment = Blog.Post.pipe(
|
|
177
170
|
Entity.derived({
|
|
178
171
|
myComment: Derived.exists(Blog.Comment.relations.post, {
|
|
179
172
|
viewer: Blog.Comment.relations.author,
|
|
@@ -188,12 +181,44 @@ Object.keys(Blog.Post.members) // id, title, published, author, editor, comments
|
|
|
188
181
|
- `Entity.relate` takes the entities and every relation between them, adds
|
|
189
182
|
the relations to them, and returns them typed with their relations. Use the
|
|
190
183
|
returned ones (`Blog.Post`) for their types; the `Post` you passed in has the
|
|
191
|
-
same relations at runtime.
|
|
184
|
+
same relations at runtime. It is one step over Entities that already
|
|
185
|
+
exist because Entities point at each other, and TypeScript cannot infer two
|
|
186
|
+
constants each typed by the other.
|
|
192
187
|
- `Relation.one` / `Relation.many` state what the owner sees. `Post.author: one`
|
|
193
188
|
and `Author.posts: many` together are the familiar one-to-many; neither side
|
|
194
189
|
names it.
|
|
195
190
|
- `target()` returns the related entity, so relations can be followed from
|
|
196
191
|
there, around a cycle too.
|
|
192
|
+
`Entity.relate` throws for a relation key that is already a member, an owner
|
|
193
|
+
that is not in the first argument, and a target that is not in the first
|
|
194
|
+
argument. The types reject the first two where they are written; a stray
|
|
195
|
+
target is found when `relate` runs.
|
|
196
|
+
|
|
197
|
+
### One Entity, several descriptors
|
|
198
|
+
|
|
199
|
+
An Entity has **one set of members**, and one set of invariants.
|
|
200
|
+
`Entity.relate`, `Entity.derived`, `Entity.sets` and `Entity.invariant` add
|
|
201
|
+
to it, and every descriptor of the Entity reads it: the one declared before
|
|
202
|
+
`relate`, the one a relation's `target()` returns, the one a query captured.
|
|
203
|
+
Metadata is the exception: `Entity.annotate` and `Entity.annotateMembers`
|
|
204
|
+
return a new descriptor that carries its own, so one reader's view (a form's
|
|
205
|
+
labels) stays its own. Compare descriptors with `Entity.same(a, b)`, not
|
|
206
|
+
`a === b`.
|
|
207
|
+
|
|
208
|
+
```text
|
|
209
|
+
identity ── relations, derived, sets, invariants one per Entity; relate / derived / sets / invariant add
|
|
210
|
+
├── descriptor fields, metadata define, relate, derived, sets, invariant return it
|
|
211
|
+
└── descriptor fields, metadata' annotate / annotateMembers make one
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
A descriptor's *type* still shows only the steps it came through: read typed
|
|
215
|
+
members from the descriptor `relate` returned, or a later one.
|
|
216
|
+
|
|
217
|
+
### What a delete does to the rows pointing at it
|
|
218
|
+
|
|
219
|
+
A `one` relation may say what happens to its row when the row it points at
|
|
220
|
+
is deleted.
|
|
221
|
+
|
|
197
222
|
- `Relation.one(Post, { onDelete: 'cascade' })` says a row goes when the row
|
|
198
223
|
it points at is deleted: a comment with its post, a reply with the post it
|
|
199
224
|
answers. It is declared on the link the row holds, as its foreign key is,
|
|
@@ -201,8 +226,19 @@ Object.keys(Blog.Post.members) // id, title, published, author, editor, comments
|
|
|
201
226
|
that takes rows with a deleted post (`{ relation, owner }`), so Remote
|
|
202
227
|
removes those it holds while the delete is pending, counts and lists with
|
|
203
228
|
them, and `remote-drizzle`'s writer removes them where it deletes, on a store
|
|
204
|
-
without foreign keys too.
|
|
205
|
-
|
|
229
|
+
without foreign keys too.
|
|
230
|
+
- `Relation.one(Topic, { onDelete: 'restrict' })` says the row it points at
|
|
231
|
+
cannot be deleted while it points there: a topic with notes under it.
|
|
232
|
+
`Entity.restricting(Topic)` lists those relations; `remote-drizzle`'s
|
|
233
|
+
writer finds such a delete and `RemoteServer.write` refuses it as
|
|
234
|
+
`Refusal.referenced` (`foldkit-remote`), naming the relation and none of
|
|
235
|
+
the rows.
|
|
236
|
+
- `Relation.one(Folder, { optional: true, onDelete: 'setNull' })` says the
|
|
237
|
+
row stays and points nowhere when the row it points at is deleted: a doc
|
|
238
|
+
whose folder went. Only a link that may point nowhere can say it, and the
|
|
239
|
+
types refuse it without `optional: true`. `Entity.clearing(Folder)` lists
|
|
240
|
+
those relations; clearing a link is an update of the row, so each is held
|
|
241
|
+
to its own `Update` rules, as unlinking it in an update would be.
|
|
206
242
|
- Who may let a cascade take a row is said beside it. By default each row it
|
|
207
243
|
takes is held to its own `Delete` rule, for whoever deletes the row it
|
|
208
244
|
points at: a delete that would take a row they may not delete is refused
|
|
@@ -210,19 +246,10 @@ Object.keys(Blog.Post.members) // id, title, published, author, editor, comments
|
|
|
210
246
|
onDelete: 'cascade', authorizedBy: 'parent' })` says whoever may delete the
|
|
211
247
|
post may take these rows with it, whoever wrote them: a post's author
|
|
212
248
|
removing everyone's likes of it. `authorizedBy` is said only beside
|
|
213
|
-
`onDelete`, and reads back as the relation's `authorizedBy`.
|
|
214
|
-
|
|
215
|
-
`
|
|
216
|
-
|
|
217
|
-
in the first argument.
|
|
218
|
-
|
|
219
|
-
### Why relations are declared in one step
|
|
220
|
-
|
|
221
|
-
Entities point at each other: a Post has Comments and a Comment has a Post. If
|
|
222
|
-
each entity declared its own relations, `Post` would be typed in terms of
|
|
223
|
-
`Comment` and `Comment` in terms of `Post`, and TypeScript cannot infer two
|
|
224
|
-
constants that way. Declaring the relations over entities that already exist
|
|
225
|
-
avoids the cycle, and lets `relate` check every target up front.
|
|
249
|
+
`onDelete: 'cascade'`, and reads back as the relation's `authorizedBy`.
|
|
250
|
+
- A cascade may not reach an Entity whose rows are themselves pointed at
|
|
251
|
+
through a `setNull` or `restrict` relation: `RemoteServer.write` refuses
|
|
252
|
+
such a delete where the server is defined.
|
|
226
253
|
|
|
227
254
|
## Ids of their own
|
|
228
255
|
|
|
@@ -258,8 +285,8 @@ Entity.input(Press.Article, Schema.Struct({ authorId: AuthorId }), {
|
|
|
258
285
|
- A Selection carries its Entity's id type, so `foldkit-remote`'s
|
|
259
286
|
`Data.get(PostPage, id)` takes a `PostId` and refuses an `AuthorId`, or plain
|
|
260
287
|
text.
|
|
261
|
-
-
|
|
262
|
-
|
|
288
|
+
- An Entity with `id: Schema.String` has plain `string` ids and refs: a brand
|
|
289
|
+
is opt-in.
|
|
263
290
|
|
|
264
291
|
## Selecting a view
|
|
265
292
|
|
|
@@ -314,7 +341,9 @@ const PostWithComments = Entity.select(Blog.Post, {
|
|
|
314
341
|
// { title: string, comments: { items: { body: string }[], hasNext: boolean, hasPrevious: boolean } }
|
|
315
342
|
```
|
|
316
343
|
|
|
317
|
-
The window is `first`
|
|
344
|
+
The window is `first` with an optional `after`, or `last` with an optional
|
|
345
|
+
`before`, each cursor a string and each size a non-negative integer;
|
|
346
|
+
`Entity.page` throws for any other combination. A page is a
|
|
318
347
|
view's shape, as neutral as "`many` means an array", so it is declared here.
|
|
319
348
|
What a cursor is and how the rows are ordered belong to whoever fetches: the
|
|
320
349
|
cursor is an opaque string an earlier answer handed out. Reading on is another
|
|
@@ -322,7 +351,9 @@ Selection with another window.
|
|
|
322
351
|
|
|
323
352
|
An unknown member, a nested Selection on a field, a page of a `one` relation,
|
|
324
353
|
and a Selection of the wrong
|
|
325
|
-
Entity are type errors, and `Entity.select` throws for untyped callers.
|
|
354
|
+
Entity are type errors, and `Entity.select` throws for untyped callers. The
|
|
355
|
+
types tell Entities apart by name, so a Selection of another Entity that
|
|
356
|
+
shares the name is caught only by the throw.
|
|
326
357
|
|
|
327
358
|
## Attaching metadata
|
|
328
359
|
|
|
@@ -370,37 +401,28 @@ Words.of(Schema.String.annotate({ title: 'Name' }).check(Schema.isMinLength(1)))
|
|
|
370
401
|
## Saying something about a row: `Expr`
|
|
371
402
|
|
|
372
403
|
An Entity says what a domain has. An `Expr` says something about one row of it,
|
|
373
|
-
as a value
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
> nothing, which is the line this package already draws: an `Expr` says which
|
|
377
|
-
> rows and fetches none of them, and the interpreters that *fetch* live
|
|
378
|
-
> elsewhere — `foldkit-remote-drizzle` compiles a body to SQL against a
|
|
379
|
-
> database.
|
|
380
|
-
>
|
|
381
|
-
> `evaluate` is here rather than there because it is the **reference
|
|
382
|
-
> semantics** of the IR: what the operator definitions mean, operationally, over
|
|
383
|
-
> rows already in hand. A specification's reference implementation belongs with
|
|
384
|
-
> the specification, and it reaches nothing — no database, no transport, no
|
|
385
|
-
> Remote concept. The rule that keeps it honest is that **it may depend on the
|
|
386
|
-
> IR and nothing else**; the moment it wants one of those it has moved to the
|
|
387
|
-
> wrong place. Nothing that imports only
|
|
388
|
-
> `Entity` pays for them: they are ordinary consts in a `sideEffects: false`
|
|
389
|
-
> package, so a bundler drops them, and a package like `foldkit-form` imports
|
|
390
|
-
> only types from here in any case.
|
|
404
|
+
as a value. This section is the reference; the
|
|
405
|
+
[Expressions guide](../../docs/expressions.md) teaches the language in order,
|
|
406
|
+
with one body answered by SQL, by `evaluate` and by `Judge`.
|
|
391
407
|
|
|
392
408
|
```ts
|
|
409
|
+
import { Schema } from 'effect'
|
|
393
410
|
import { Expr, Order } from 'foldkit-entity'
|
|
394
411
|
|
|
395
412
|
const byTitle = Expr.eq(Blog.Post.fields.title, Expr.input('title', Schema.String))
|
|
396
|
-
const
|
|
397
|
-
const
|
|
413
|
+
const isPublished = Expr.eq(Blog.Post.fields.published, true)
|
|
414
|
+
const newestTerms = [Order.desc(Blog.Post.fields.title), Order.asc(Blog.Post.fields.id)]
|
|
398
415
|
```
|
|
399
416
|
|
|
400
417
|
Building one performs no work: it reads nothing, names no database, and runs no
|
|
401
|
-
query. An interpreter
|
|
402
|
-
|
|
403
|
-
|
|
418
|
+
query. An interpreter runs it (`foldkit-remote-drizzle` compiles it to SQL,
|
|
419
|
+
`evaluate` judges rows in memory), which is what lets one query mean the same
|
|
420
|
+
thing in more than one place.
|
|
421
|
+
|
|
422
|
+
> **Why `evaluate` lives here.** It is the reference semantics of the
|
|
423
|
+
> language: what each operation means over rows already in hand. It may depend
|
|
424
|
+
> on the language and nothing else (no database, no transport, no Remote
|
|
425
|
+
> concept), and a page importing only `Entity` does not carry it.
|
|
404
426
|
|
|
405
427
|
A comparison coerces what it is given, so the common forms read as they mean: a
|
|
406
428
|
field becomes a reference, a plain value becomes a literal, and an `Expr` is
|
|
@@ -411,13 +433,6 @@ the field on the left; `Expr.eq('Hello', Blog.Post.fields.title)` is refused wit
|
|
|
411
433
|
that sentence. The comparisons (`lt`, `gte`, …) also take a field second,
|
|
412
434
|
wrapped in `Expr.field(…)`.
|
|
413
435
|
|
|
414
|
-
**An input is a placeholder, not a value.** A query's body is built once, so
|
|
415
|
-
`Expr.input('title', …)` stands for whatever the query is given when it runs —
|
|
416
|
-
there is nothing there yet to branch on. An `InputExpr` is an object, so a
|
|
417
|
-
`condition ? a : b` over one is always truthy and decides itself once, forever.
|
|
418
|
-
A query that depends on what it was passed says so with a comparison over the
|
|
419
|
-
placeholder instead of a branch around it.
|
|
420
|
-
|
|
421
436
|
`dependenciesOf(...)` says which fields and inputs an expression reads and which
|
|
422
437
|
operations it uses, so a planner knows what it needs and an interpreter can
|
|
423
438
|
refuse a query it cannot run. Each field names its `owner`, the Entity's
|
|
@@ -434,6 +449,41 @@ query whose predicates and order terms expand past `maxQueryNodes` (1,000)
|
|
|
434
449
|
nodes, counting a shared node on each path that reaches it, is refused where
|
|
435
450
|
it is built.
|
|
436
451
|
|
|
452
|
+
### Data-last: `step` with Effect's `pipe` and `flow`
|
|
453
|
+
|
|
454
|
+
Every comparison (`eq`, `lt`, `lte`, `gt`, `gte`, `contains`, `in`) and every
|
|
455
|
+
operator has a `step` member: the call without its subject. It builds exactly the
|
|
456
|
+
node the data-first call builds, so it is a spelling, not a second meaning.
|
|
457
|
+
|
|
458
|
+
```ts standalone
|
|
459
|
+
import { Schema, flow, pipe } from 'effect'
|
|
460
|
+
import { Collation, Entity, Expr, Text } from 'foldkit-entity'
|
|
461
|
+
|
|
462
|
+
const Post = Entity.define(
|
|
463
|
+
'Post',
|
|
464
|
+
Schema.Struct({ id: Schema.String, status: Schema.Literals(['draft', 'live']), upc: Schema.String }),
|
|
465
|
+
).pipe(Entity.annotateMembers({ upc: Collation.of(Collation.binary) }))
|
|
466
|
+
|
|
467
|
+
const isDraft = pipe(Post.fields.status, Expr.eq.step('draft'))
|
|
468
|
+
// the same node as Expr.eq(Post.fields.status, 'draft')
|
|
469
|
+
const startsWithA = pipe(Post.fields.upc, Text.startsWith.step('A'))
|
|
470
|
+
const draftOrLive = flow(Expr.in.step(['draft', 'live']))
|
|
471
|
+
const anyStatus = draftOrLive(Post.fields.status)
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
- `step` has one signature, so reads stay exact through `pipe` and `flow`
|
|
475
|
+
(`isDraft` reads `'Post'`, and `Query.where` still refuses a predicate over
|
|
476
|
+
another Entity). An overloaded callable would lose them, which is why it is a
|
|
477
|
+
member and not the function's own data-last form.
|
|
478
|
+
- A wrong value is refused at the step: `pipe(Post.fields.status, Expr.eq.step(42))`
|
|
479
|
+
is an error where it is written. `Expr.eq(Post.fields.status)` is still an arity error.
|
|
480
|
+
- The `step` of `lt`, `lte`, `gt` and `gte` takes the options its builder takes
|
|
481
|
+
(`Expr.lt.step('m', { collation })`); an operator's takes none, so a call that
|
|
482
|
+
needs a collation is written data-first. A step takes the arguments past the
|
|
483
|
+
first, then the first: an operator of one argument has a `step()` that takes
|
|
484
|
+
nothing, and `Text.startsWith.step(prefix)` takes one.
|
|
485
|
+
- Data-first stays the form to learn first; a step earns its place in a chain.
|
|
486
|
+
|
|
437
487
|
### Asking a question that depends on an input, without branching on it
|
|
438
488
|
|
|
439
489
|
Since an input is a placeholder, a query cannot choose between two shapes based
|
|
@@ -472,23 +522,20 @@ not match `é`, though each matches itself. Text holding a NUL character is
|
|
|
472
522
|
refused by every interpreter here, in `contains`, `eq` and `in` alike, since
|
|
473
523
|
Postgres text cannot hold one and SQLite compares only up to it.
|
|
474
524
|
|
|
475
|
-
**`in` asks whether a value is one of a list**, written out
|
|
476
|
-
|
|
525
|
+
**`in` asks whether a value is one of a list**, written out
|
|
526
|
+
(`Expr.in(Post.fields.status, ['draft', 'live'])`) or given as an input of a
|
|
527
|
+
list. Each element is
|
|
477
528
|
compared as `eq` compares, and it reads as SQL's `in`: a null value is
|
|
478
529
|
unknown, so is no match against a list holding a null, and an empty list
|
|
479
530
|
matches no row (on Postgres too, which refuses `in ()`; the compiler says
|
|
480
531
|
`false` instead).
|
|
481
532
|
|
|
482
|
-
|
|
483
|
-
number would compile to `lower(rank) like …`, which SQLite coerces into an
|
|
484
|
-
answer and Postgres rejects at runtime
|
|
485
|
-
error where it is written
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
**Over a column that can be null it is not the same as no filter.** A null
|
|
489
|
-
contains nothing, not even the empty string, so its rows drop out. The column
|
|
490
|
-
the CMS searches is declared not-null, which is what makes an empty search
|
|
491
|
-
exactly everything there.
|
|
533
|
+
**`contains` searches text, and its operand is constrained to text.** Over a
|
|
534
|
+
number it would compile to `lower(rank) like …`, which SQLite coerces into an
|
|
535
|
+
answer and Postgres rejects at runtime, so a non-text operand is a compile
|
|
536
|
+
error where it is written. Nullable text is allowed, and there an empty search
|
|
537
|
+
is not the same as no filter: a null contains nothing, not even the empty
|
|
538
|
+
string, so its rows drop out.
|
|
492
539
|
|
|
493
540
|
### Who asks, and when: the context
|
|
494
541
|
|
|
@@ -498,15 +545,18 @@ a comparison with it holds of no row. `Expr.now` is the time, in milliseconds.
|
|
|
498
545
|
Neither is a field or an input: each interpreter reads them from the context
|
|
499
546
|
it is given.
|
|
500
547
|
|
|
501
|
-
```ts
|
|
548
|
+
```ts standalone
|
|
549
|
+
import { Option, Schema } from 'effect'
|
|
550
|
+
import { Entity, Expr, Query, evaluate } from 'foldkit-entity'
|
|
551
|
+
|
|
502
552
|
const User = Entity.define('User', Schema.Struct({ id: Schema.String }))
|
|
503
553
|
const Note = Entity.define('Note', Schema.Struct({ id: Schema.String, ownerId: Schema.String }))
|
|
504
554
|
|
|
505
|
-
const
|
|
555
|
+
const MyNotes = Query.from(Note).pipe(
|
|
506
556
|
Query.where(Expr.eq(Note.fields.ownerId, Expr.viewer(User))),
|
|
507
557
|
)
|
|
508
558
|
const ada = { entity: 'User', id: 'ada' }
|
|
509
|
-
evaluate(
|
|
559
|
+
evaluate(MyNotes, {}, [{ id: 'n1', ownerId: 'ada' }, { id: 'n2', ownerId: 'bo' }], {
|
|
510
560
|
context: { viewer: Option.some(ada), now: Option.none() },
|
|
511
561
|
})
|
|
512
562
|
// [{ id: 'n1', ownerId: 'ada' }]
|
|
@@ -524,10 +574,36 @@ declared with `Entity.sets`.
|
|
|
524
574
|
|
|
525
575
|
### Which rows: `Query`
|
|
526
576
|
|
|
577
|
+
<!-- docs-check standalone
|
|
578
|
+
import { Schema } from 'effect'
|
|
579
|
+
import { Collation, Derived, Entity, Expr, Order, Query, Relation } from 'foldkit-entity'
|
|
580
|
+
|
|
581
|
+
const BlogAuthor = Entity.define('Author', Schema.Struct({ id: Schema.String, name: Schema.String }))
|
|
582
|
+
const BlogComment = Entity.define('Comment', Schema.Struct({ id: Schema.String, body: Schema.String }))
|
|
583
|
+
const BlogPost = Entity.define(
|
|
584
|
+
'Post',
|
|
585
|
+
Schema.Struct({ id: Schema.String, title: Schema.String, published: Schema.Boolean }),
|
|
586
|
+
).pipe(Entity.derived({ commentCount: Derived.make(Schema.Number) }))
|
|
587
|
+
const Blog = Entity.relate(
|
|
588
|
+
{ Author: BlogAuthor, Post: BlogPost, Comment: BlogComment },
|
|
589
|
+
{
|
|
590
|
+
Post: {
|
|
591
|
+
author: Relation.one(BlogAuthor),
|
|
592
|
+
editor: Relation.one(BlogAuthor, { optional: true }),
|
|
593
|
+
comments: Relation.many(BlogComment),
|
|
594
|
+
},
|
|
595
|
+
Comment: { post: Relation.one(BlogPost), author: Relation.one(BlogAuthor) },
|
|
596
|
+
},
|
|
597
|
+
)
|
|
598
|
+
const byTitle = Expr.eq(Blog.Post.fields.title, Expr.input('title', Schema.String))
|
|
599
|
+
-->
|
|
600
|
+
|
|
527
601
|
A `Query` is an Entity to read, the predicates every row must hold, and the
|
|
528
602
|
order to read them in — composed with `pipe`, one immutable value per step:
|
|
529
603
|
|
|
530
604
|
```ts
|
|
605
|
+
import { Query } from 'foldkit-entity'
|
|
606
|
+
|
|
531
607
|
const published = Query.where(Expr.eq(Blog.Post.fields.published, true))
|
|
532
608
|
const newest = Query.orderBy(Order.desc(Blog.Post.fields.title))
|
|
533
609
|
|
|
@@ -556,6 +632,8 @@ declaration of what `title` means, and the client can tell which edits may move
|
|
|
556
632
|
a row:
|
|
557
633
|
|
|
558
634
|
```ts
|
|
635
|
+
import { type InputExpr } from 'foldkit-entity'
|
|
636
|
+
|
|
559
637
|
const PostSort = Schema.NullOr(
|
|
560
638
|
Schema.Struct({ by: Schema.Literals(['title', 'id']), direction: Schema.Literals(['asc', 'desc']) }),
|
|
561
639
|
)
|
|
@@ -575,9 +653,15 @@ unless the terms already read the id, so rows with equal keys come out in one
|
|
|
575
653
|
order on every interpreter rather than each breaking ties its own way.
|
|
576
654
|
|
|
577
655
|
**How text orders is declared, or left to the server.** Left unsaid, SQLite
|
|
578
|
-
compares bytes, Postgres follows the database's locale and a JavaScript
|
|
579
|
-
follows UTF-16 code units. A field declares its collation,
|
|
580
|
-
|
|
656
|
+
compares bytes, Postgres follows the database's locale and a plain JavaScript
|
|
657
|
+
sort follows UTF-16 code units. A field declares its collation, which SQL
|
|
658
|
+
compiles, and `Query.placement` says whether a client can order the same way.
|
|
659
|
+
`evaluate` refuses an order over text with no declared collation, with the
|
|
660
|
+
reason `Query.placement` gives, so a page and the reference agree on whether
|
|
661
|
+
the question can be answered; a database orders such text by its own default,
|
|
662
|
+
which differs between SQLite and Postgres. `evaluateEach`, which only judges
|
|
663
|
+
membership, does not refuse, and its `matched` list is then in code point
|
|
664
|
+
order:
|
|
581
665
|
|
|
582
666
|
```ts
|
|
583
667
|
const Tagged = Entity.define('Tagged', Schema.Struct({ id: Schema.String, name: Schema.String })).pipe(
|
|
@@ -658,11 +742,11 @@ Expr.and(
|
|
|
658
742
|
```
|
|
659
743
|
|
|
660
744
|
Numbers compare as numbers, and nothing compares across kinds or for a value
|
|
661
|
-
stored as neither a number nor text. Text orders by a collation, and
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
745
|
+
stored as neither a number nor text. Text orders by a collation, and the
|
|
746
|
+
defaults disagree (above), so text is compared only under `Collation.binary`
|
|
747
|
+
or `Collation.asciiFold`, passed or declared on a side that carries one (a
|
|
748
|
+
field, a path to one, an operator call with a collation): anything else
|
|
749
|
+
throws where the comparison is built. A value is
|
|
666
750
|
compared in its encoded form, which is why a date stored as an ISO string is
|
|
667
751
|
text here. A null on either side is unknown, as in SQL. There is no `between`;
|
|
668
752
|
it is the `and` above.
|
|
@@ -673,6 +757,15 @@ A predicate may read the row a `one` relation points at, and ask whether any
|
|
|
673
757
|
row points at this one. Both start on the query's own row, so they belong in
|
|
674
758
|
its `where`:
|
|
675
759
|
|
|
760
|
+
<!-- docs-check
|
|
761
|
+
const UserFields = Entity.define('User', Schema.Struct({ id: Schema.String, handle: Schema.String }))
|
|
762
|
+
const PostFields = Entity.define('Post', Schema.Struct({ id: Schema.String, body: Schema.String }))
|
|
763
|
+
const FollowFields = Entity.define(
|
|
764
|
+
'Follow',
|
|
765
|
+
Schema.Struct({ id: Schema.String, followerId: Schema.String }),
|
|
766
|
+
)
|
|
767
|
+
-->
|
|
768
|
+
|
|
676
769
|
```ts
|
|
677
770
|
const { Post, User, Follow } = Entity.relate(
|
|
678
771
|
{ Post: PostFields, User: UserFields, Follow: FollowFields },
|
|
@@ -703,8 +796,9 @@ it declares.)
|
|
|
703
796
|
does. At most four relations.
|
|
704
797
|
- `Expr.exists(relation, where?)` names the pointing edge, a `one` relation of
|
|
705
798
|
another Entity (`Follow.followee`), as `Derived.count` does. Only rows the
|
|
706
|
-
reader may see count. `where` reads the pointing row's own fields
|
|
707
|
-
input
|
|
799
|
+
reader may see count. `where` reads the pointing row's own fields, the
|
|
800
|
+
input and the context (`Expr.viewer`, `Expr.now`); another Entity's field or
|
|
801
|
+
a further path or exists is refused where it is written.
|
|
708
802
|
- A list does not order by a path.
|
|
709
803
|
|
|
710
804
|
A `one` relation is itself an operand: the id it points at, typed as the
|
|
@@ -722,7 +816,7 @@ does not order by a link: a client holds it as a ref, not as the id it would
|
|
|
722
816
|
order by.
|
|
723
817
|
|
|
724
818
|
`foldkit-remote-drizzle` compiles both to subqueries under each reached
|
|
725
|
-
table's `visible` rule. `evaluate`, given one
|
|
819
|
+
table's `visible` rule. `evaluate`, given one table's rows, cannot follow them: it
|
|
726
820
|
refuses such a body, as it refuses any operation it does not run. `Judge`,
|
|
727
821
|
below, reads them from what a holder has.
|
|
728
822
|
|
|
@@ -734,6 +828,9 @@ never sent it" are different answers. `Judge` reads a row as a holder has it
|
|
|
734
828
|
(`HeldRow`) and keeps the two apart:
|
|
735
829
|
|
|
736
830
|
```ts
|
|
831
|
+
import { Option } from 'effect'
|
|
832
|
+
import { Held, Judge } from 'foldkit-entity'
|
|
833
|
+
|
|
737
834
|
const holder = Held.rows([
|
|
738
835
|
{ entity: Post, rows: [{ id: 'p1', body: 'hi', author: 'u1' }, { id: 'p2', body: 'yo', author: 'u2' }] },
|
|
739
836
|
// Ada is held; u2 is not, and this holder may lack users.
|
|
@@ -768,6 +865,7 @@ an interpreter does not have:
|
|
|
768
865
|
|
|
769
866
|
```ts
|
|
770
867
|
const missing = Query.unsupported(ByHandle, ['eq', 'isNull', 'isNotNull'])
|
|
868
|
+
// ['path']: ByHandle reads a path, which this interpreter does not list
|
|
771
869
|
if (missing.length > 0) throw new Error(`cannot run ${missing.join(', ')}`)
|
|
772
870
|
```
|
|
773
871
|
|
|
@@ -789,21 +887,15 @@ WHERE Post.slug = $slug
|
|
|
789
887
|
ORDER BY Post.updatedAt DESC
|
|
790
888
|
```
|
|
791
889
|
|
|
792
|
-
|
|
793
|
-
predicate at once
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
actually ran is whatever that backend compiled, which is not this.
|
|
798
|
-
`Expr.show(node)` does the same for one expression.
|
|
799
|
-
|
|
800
|
-
A `Query` says which rows. It does not say which fields — that is a Selection —
|
|
801
|
-
and it does not say how many, whether absence is an error, or whether to watch
|
|
802
|
-
for changes: those belong to the consumer doing the reading, not to the
|
|
803
|
-
relation.
|
|
890
|
+
It is for a person (an explanation, a diagnostic, a test asserting on a whole
|
|
891
|
+
predicate at once), never for an interpreter: an input is `$slug` rather than
|
|
892
|
+
a bound parameter, `contains` is named rather than rendered as somebody's
|
|
893
|
+
`like`, and no dialect's escaping or collation is implied. `Expr.show(node)`
|
|
894
|
+
does the same for one expression.
|
|
804
895
|
|
|
805
|
-
|
|
806
|
-
|
|
896
|
+
A `Query` says which rows. It does not say which fields (a Selection does),
|
|
897
|
+
how many, whether absence is an error, or whether to watch for changes: those
|
|
898
|
+
belong to the consumer doing the reading.
|
|
807
899
|
|
|
808
900
|
## Rows of several shapes: variants
|
|
809
901
|
|
|
@@ -845,9 +937,11 @@ stored row Domain.fields { _tag, id, name, price | null, years | null }
|
|
|
845
937
|
reading which fields are null. `Entity.variantsOf(Domain)` holds the codec
|
|
846
938
|
between the two (`stored`): a stored row, encoded, decodes to its case, and
|
|
847
939
|
one holding another case's field is refused.
|
|
848
|
-
- **Each case says what it holds.** A case
|
|
849
|
-
|
|
850
|
-
|
|
940
|
+
- **Each case says what it holds.** A case gets an invariant wherever a stored
|
|
941
|
+
row could break it: it has a field of its own that may not be null, or
|
|
942
|
+
another case has a field it must not hold (`variant_Available`: an Available
|
|
943
|
+
holds `price` and `years`; `variant_Unconfirmed`: an Unconfirmed holds none
|
|
944
|
+
of them), so `Entity.judge`
|
|
851
945
|
and a form refuse a row that mixes cases, and `foldkit-remote-drizzle`
|
|
852
946
|
writes each as a CHECK.
|
|
853
947
|
|
|
@@ -877,6 +971,8 @@ tagged union whose cases hold the selected fields they have, typed as the
|
|
|
877
971
|
case holds them, and every selected relation and derived member.
|
|
878
972
|
|
|
879
973
|
```ts
|
|
974
|
+
import { type Selected } from 'foldkit-entity'
|
|
975
|
+
|
|
880
976
|
const Quote = Entity.select(Domain, { _tag: true, name: true, price: true })
|
|
881
977
|
type Quote = Selected<typeof Quote>
|
|
882
978
|
// { _tag: 'Available', name: string, price: number } | { _tag: 'Unconfirmed', name: string }
|
|
@@ -905,17 +1001,18 @@ const CreatePostInput = Schema.Struct({
|
|
|
905
1001
|
notify: Schema.Boolean,
|
|
906
1002
|
})
|
|
907
1003
|
|
|
908
|
-
const
|
|
1004
|
+
const CreatePostById = Entity.input(Blog.Post, CreatePostInput, {
|
|
909
1005
|
authorId: Relation.input(Blog.Post.relations.author),
|
|
910
1006
|
notify: Entity.unmapped,
|
|
911
1007
|
})
|
|
912
1008
|
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
1009
|
+
CreatePostById.members.title // Blog.Post.fields.title: it names a field, so it maps itself
|
|
1010
|
+
CreatePostById.members.authorId.relation.target() // Blog.Author: what a picker chooses from
|
|
1011
|
+
CreatePostById.members.notify // Entity.unmapped: about the operation, not the Post
|
|
916
1012
|
```
|
|
917
1013
|
|
|
918
|
-
- A key that names a field, with a value that fits it, maps itself
|
|
1014
|
+
- A key that names a field, with a value that fits it, maps itself (the fit is
|
|
1015
|
+
the types' to check; at run time any key naming a field maps). Only the
|
|
919
1016
|
present value has to fit: a key may be optional (a partial update), admit
|
|
920
1017
|
`null` (clearing it), or hold an `Option` (an id absent for something new),
|
|
921
1018
|
which is the input schema's rule to make.
|
|
@@ -951,9 +1048,9 @@ const CreatePost = Entity.input(
|
|
|
951
1048
|
)
|
|
952
1049
|
```
|
|
953
1050
|
|
|
954
|
-
A `one` holds the nested input's value, a `many` a list of them
|
|
955
|
-
input must be of the relation's target,
|
|
956
|
-
runtime. `Entity.selectFor` then loads what the nested input writes of the
|
|
1051
|
+
A `one` holds the nested input's value, a `many` a list of them, which the
|
|
1052
|
+
types check; the nested input must be of the relation's target, checked by
|
|
1053
|
+
type and at runtime. `Entity.selectFor` then loads what the nested input writes of the
|
|
957
1054
|
target, and `Entity.valuesFor` turns the loaded target back into nested values.
|
|
958
1055
|
What a nested write *does* (insert, update, replace the list) is the
|
|
959
1056
|
operation's handler to decide.
|
|
@@ -964,10 +1061,10 @@ An edit screen has to load the current values and turn them into input values.
|
|
|
964
1061
|
Both follow from the reading, so neither is written by hand:
|
|
965
1062
|
|
|
966
1063
|
```ts
|
|
967
|
-
const PostForEdit = Entity.selectFor(
|
|
1064
|
+
const PostForEdit = Entity.selectFor(CreatePostById)
|
|
968
1065
|
// a Selection of `title` and `author`, the members the input writes; `author` as a ref
|
|
969
1066
|
|
|
970
|
-
Entity.valuesFor(
|
|
1067
|
+
Entity.valuesFor(CreatePostById, { title: 'Hello', author: { entity: 'Author', id: 'a1' } })
|
|
971
1068
|
// { title: 'Hello', authorId: 'a1' }
|
|
972
1069
|
```
|
|
973
1070
|
|
|
@@ -1019,7 +1116,7 @@ relation. A value is a term of the write's context, `Expr.viewer` or
|
|
|
1019
1116
|
`Expr.now`, and `on` says which writes set it:
|
|
1020
1117
|
|
|
1021
1118
|
```ts
|
|
1022
|
-
const AuthoredPost = Blog.Post.pipe(Entity.sets({ author: Expr.viewer(Author) }, { on: 'create' }))
|
|
1119
|
+
const AuthoredPost = Blog.Post.pipe(Entity.sets({ author: Expr.viewer(Blog.Author) }, { on: 'create' }))
|
|
1023
1120
|
```
|
|
1024
1121
|
|
|
1025
1122
|
`Expr.viewer(Author)` is whoever asks: a `one` relation to an Author pointed
|
|
@@ -1053,8 +1150,11 @@ An update or a delete may also say when it makes sense: `when` is what the row
|
|
|
1053
1150
|
must hold for it to land, written as a query body is: `() =>
|
|
1054
1151
|
Expr.eq(Post.fields.title, 'Draft')`, or with the input, `({ input }) =>
|
|
1055
1152
|
Expr.eq(Post.fields.title, input.from)`. It reads the row as it is before the write and the input,
|
|
1056
|
-
|
|
1057
|
-
|
|
1153
|
+
and only its own Entity: a field of another is a type error, and refused where
|
|
1154
|
+
the write is declared. Who is asking is a guard's: a `when` reading
|
|
1155
|
+
`Expr.viewer` or `Expr.now` (also through a path from the viewer or an exists)
|
|
1156
|
+
is refused where the write is declared; a writer, given neither, refuses a
|
|
1157
|
+
hand-built one again where it is served. It is held as
|
|
1058
1158
|
a query body (`write.when`), so an interpreter checks it in the statement that
|
|
1059
1159
|
writes, and a row it does not hold of is refused as unmet. A write declared with
|
|
1060
1160
|
one is a `ConditionedWrite`, which is how `Mutation.write` knows it may be
|
|
@@ -1069,10 +1169,13 @@ writes, so no concurrent change is lost. A retry must not add twice, so either i
|
|
|
1069
1169
|
expects a revision (a retry of a write that landed is then a conflict), or its
|
|
1070
1170
|
writer keeps a ledger, which answers the retry from its record and lets two
|
|
1071
1171
|
concurrent increments both land. `RemoteServer.write` refuses one with neither,
|
|
1072
|
-
and one of a real number with no revision even under a ledger
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1172
|
+
and one of a real number with no revision even under a ledger, unless its
|
|
1173
|
+
writer pins the row it read (`foldkit-guard`'s writer with a `revision`):
|
|
1174
|
+
floating-point addition does not associate, so two concurrent sums could land
|
|
1175
|
+
as two results. The field must be stored as a number that is never null, and
|
|
1176
|
+
may not be the id, the revision, or set by another key; the amount is an
|
|
1177
|
+
unmapped key, and an integer field takes an integer amount. Each is refused
|
|
1178
|
+
where the write is declared. `Write.bind` gives the amounts apart from the values (`increments`), so a
|
|
1076
1179
|
client can add them to the value it holds as it reads it (Remote does), never
|
|
1077
1180
|
fixing a sum over a row that may since have moved. `Write.reads(write)` is what a write
|
|
1078
1181
|
reads from its row: what its `when` reads, each field it increments, what its
|
|
@@ -1103,8 +1206,9 @@ value for each implementation the writer runs (`Conformance.laws` in memory,
|
|
|
1103
1206
|
the row before it: values set, amounts added (a null stays null, as in SQL),
|
|
1104
1207
|
assignments computed. It is the one computation of that row: a guard judges
|
|
1105
1208
|
it, a writer explains a miss by it, a client predicts it. `unknown` names each
|
|
1106
|
-
field it could not work out (one the row lacks,
|
|
1107
|
-
which keeps what the row
|
|
1209
|
+
field it could not work out (one the row lacks, an amount added to a value
|
|
1210
|
+
that is no number, or an operator the table lacks), which keeps what the row
|
|
1211
|
+
holds.
|
|
1108
1212
|
|
|
1109
1213
|
### What a client foresees of a supplied member
|
|
1110
1214
|
|
|
@@ -1133,7 +1237,7 @@ the row a write leaves: with `quantity = 10, reserved = 5`, an update setting
|
|
|
1133
1237
|
An **invariant** is what every stored row must hold, read over the row after a
|
|
1134
1238
|
write (`after`):
|
|
1135
1239
|
|
|
1136
|
-
```ts
|
|
1240
|
+
```ts standalone
|
|
1137
1241
|
import { Schema } from 'effect'
|
|
1138
1242
|
import { Entity, Expr } from 'foldkit-entity'
|
|
1139
1243
|
|
|
@@ -1220,13 +1324,38 @@ A row judged holds each relation it reads as that id (null where an optional
|
|
|
1220
1324
|
one points nowhere); `Entity.judgeInput` reads an input key mapped to the
|
|
1221
1325
|
relation as it. A `many` relation holds no one value, so it is not there.
|
|
1222
1326
|
|
|
1327
|
+
An input describes a whole row only when it creates one. An edit sets a few
|
|
1328
|
+
fields of a row that exists, so `Entity.judgeInput(input, value, { over })`
|
|
1329
|
+
takes that row, encoded (`Entity.rowFrom(entity, value)` gives it from a
|
|
1330
|
+
read value): the input's keys are laid over it, and it is the row before, so
|
|
1331
|
+
an invariant over a field the input does not set, and a transition, are
|
|
1332
|
+
judged. Without `over` such an invariant is `Undecided`. `Entity.judgedBy(input)`
|
|
1333
|
+
names the members outside the input that its invariants read beside a key it
|
|
1334
|
+
sets (`{ approvedBy: true }`), for `Entity.selectFor(input, { also })` to load:
|
|
1335
|
+
`foldkit-crud`'s editor does both.
|
|
1336
|
+
|
|
1223
1337
|
`Entity.invariant` returns the step that attaches it, carrying its `id` and,
|
|
1224
1338
|
once attached, its Entity's name as `entity`: an id is unique only within an
|
|
1225
1339
|
Entity, so a refusal names both. A declaration attaches to one Entity; reading
|
|
1226
|
-
`entity` before it is attached throws
|
|
1340
|
+
`entity` before it is attached throws, and applying it to that Entity again
|
|
1341
|
+
adds nothing. The invariant is the Entity's, so `InventoryFields` below judges
|
|
1342
|
+
it as `Inventory` does: a form, a write or a server binding made from either
|
|
1343
|
+
name holds it. Hoist it to export it, naming the
|
|
1227
1344
|
Entity's type (what it reads is checked against it), and match a refusal
|
|
1228
1345
|
against it rather than spelling the id again:
|
|
1229
1346
|
|
|
1347
|
+
<!-- docs-check standalone
|
|
1348
|
+
import { Schema } from 'effect'
|
|
1349
|
+
import { Entity, Expr } from 'foldkit-entity'
|
|
1350
|
+
import { Refusal } from 'foldkit-remote'
|
|
1351
|
+
|
|
1352
|
+
const InventoryFields = Entity.define(
|
|
1353
|
+
'Inventory',
|
|
1354
|
+
Schema.Struct({ id: Schema.String, quantity: Schema.Number, reserved: Schema.Number }),
|
|
1355
|
+
)
|
|
1356
|
+
declare const refusal: unknown
|
|
1357
|
+
-->
|
|
1358
|
+
|
|
1230
1359
|
```ts
|
|
1231
1360
|
export const reservedWithinQuantity = Entity.invariant<typeof InventoryFields>(
|
|
1232
1361
|
'reservedWithinQuantity',
|
|
@@ -1240,17 +1369,19 @@ Refusal.isInvalidBy(refusal, reservedWithinQuantity)
|
|
|
1240
1369
|
```
|
|
1241
1370
|
|
|
1242
1371
|
- `before` is each field as the row before holds it (`Expr.field`), and `after`
|
|
1243
|
-
each as the row after holds it (`Expr.next`), both typed as the field
|
|
1244
|
-
is an expression already, so it goes on either
|
|
1245
|
-
wraps an Entity's own field, and
|
|
1372
|
+
each as the row after holds it (`Expr.next`), both typed as the field's
|
|
1373
|
+
encoded, stored form. Each is an expression already, so it goes on either
|
|
1374
|
+
side as it is; `Expr.field` wraps an Entity's own field, and one of these is
|
|
1375
|
+
a type error there:
|
|
1246
1376
|
|
|
1247
1377
|
| Write | Not |
|
|
1248
1378
|
| --- | --- |
|
|
1249
1379
|
| `Expr.gte(after.quantity, before.quantity)` | `Expr.gte(after.quantity, Expr.field(before.quantity))` |
|
|
1250
|
-
- It is declared once, on the Entity
|
|
1380
|
+
- It is declared once, on the Entity itself, and attaching more adds to it;
|
|
1251
1381
|
the Entity stays the same (`Entity.same`). Its interpreters read it from there.
|
|
1252
1382
|
- It reads stored rows only: one over another Entity, or reading an input, is
|
|
1253
|
-
refused
|
|
1383
|
+
refused when it is attached to its Entity (a `DeclaredInvariant` held apart
|
|
1384
|
+
is checked when it is piped on), as is an id declared twice or a `path` naming
|
|
1254
1385
|
neither a field nor a `one` relation. So is one reading nothing of `after`: which rows a write may start from
|
|
1255
1386
|
is its `when`. Who may write is a guard's; whether a write applies now is its `when`'s.
|
|
1256
1387
|
- `Entity.judge(entity, { after, before? })` judges rows as the store holds them
|
|
@@ -1269,6 +1400,234 @@ needs `{ collation: Collation.binary }` on its comparison. An interpreter that
|
|
|
1269
1400
|
judges stored rows alone refuses `after`'s nodes as the operation `next`;
|
|
1270
1401
|
`Expr.substituteNext` reads the ones a write sets as their values.
|
|
1271
1402
|
|
|
1403
|
+
## States of a row, and what every write does to them
|
|
1404
|
+
|
|
1405
|
+
An invariant says what every row holds. A row also passes through states a
|
|
1406
|
+
reader names (a draft, a published product), and a write makes sense from some
|
|
1407
|
+
and leads to others. `Entity.refine` names one, as a value: a predicate over
|
|
1408
|
+
the row, declared once on the Entity (every descriptor of it lists it, as it
|
|
1409
|
+
judges its invariants). It is not another descriptor: a store, a compiler or a
|
|
1410
|
+
guard given `Draft` where it wants `Product` would read every product.
|
|
1411
|
+
|
|
1412
|
+
<!-- docs-check standalone
|
|
1413
|
+
import { Schema } from 'effect'
|
|
1414
|
+
import { Entity, Expr, Query, Write } from 'foldkit-entity'
|
|
1415
|
+
-->
|
|
1416
|
+
|
|
1417
|
+
```ts
|
|
1418
|
+
const Product = Entity.define(
|
|
1419
|
+
'Product',
|
|
1420
|
+
Schema.Struct({
|
|
1421
|
+
id: Schema.String,
|
|
1422
|
+
status: Schema.Literals(['draft', 'published', 'archived']),
|
|
1423
|
+
stock: Schema.Number,
|
|
1424
|
+
}),
|
|
1425
|
+
)
|
|
1426
|
+
|
|
1427
|
+
const Draft = Entity.refine(Product, 'Draft', { status: 'draft' }) // a value per field
|
|
1428
|
+
const Published = Entity.refine(Product, 'Published', { status: 'published' })
|
|
1429
|
+
const InStock = Entity.refine(Product, 'InStock', ({ row }) => Expr.gt(row.stock, 0)) // any predicate
|
|
1430
|
+
|
|
1431
|
+
const drafts = Query.from(Draft) // every product in the state: its predicate in `where`
|
|
1432
|
+
Expr.show(Draft.predicate) // 'Product.Draft'
|
|
1433
|
+
Entity.inState(Draft, { status: 'draft' }) // Option.some(true); none for a row without `status`
|
|
1434
|
+
```
|
|
1435
|
+
|
|
1436
|
+
- The literal form is one `Expr.eq` per key (`Expr.isNull` for a `null`), each typed by what its field
|
|
1437
|
+
stores: a key that is no field, or a value the field cannot hold, does not
|
|
1438
|
+
compile. Its `is(row)` is a type guard narrowing the fields it names
|
|
1439
|
+
(`row.status` is `'draft'` inside `if (Draft.is(row))`); the predicate form's
|
|
1440
|
+
narrows nothing. A Selection is never narrowed by state: a held row is
|
|
1441
|
+
updated in place, and goes on being read after it left the state.
|
|
1442
|
+
- `build` is given `row` alone, so a state cannot read the past: "was ever
|
|
1443
|
+
published" is a field.
|
|
1444
|
+
- A state may reach another row (`Expr.path`, `Expr.exists`). It is queried
|
|
1445
|
+
as any predicate is, but it is not `local`: `inState` and `is` cannot judge
|
|
1446
|
+
it from one row, and it is no write's `from` or `becomes`, since a writer
|
|
1447
|
+
judges the row it writes alone.
|
|
1448
|
+
|
|
1449
|
+
A write says which state it starts from and which it leaves:
|
|
1450
|
+
|
|
1451
|
+
```ts
|
|
1452
|
+
const Publish = Write.update(
|
|
1453
|
+
Entity.input(Product, Schema.Struct({ id: Schema.String, status: Schema.Literal('published') })),
|
|
1454
|
+
{ id: 'id', from: Draft, becomes: Published },
|
|
1455
|
+
)
|
|
1456
|
+
```
|
|
1457
|
+
|
|
1458
|
+
- `from: Draft` joins the state's predicate to the write's `when`, so a row in
|
|
1459
|
+
another state is refused as unmet, as any `when` refuses, and the write is a
|
|
1460
|
+
`ConditionedWrite`.
|
|
1461
|
+
- `becomes: Published` claims every row the write can start from is published
|
|
1462
|
+
once it lands. It is decided where the write is declared, by enumerating
|
|
1463
|
+
those rows: a claim the patch cannot keep throws there, naming a row it
|
|
1464
|
+
breaks. A claim enumeration cannot decide (a sale `becomes: InStock` moves a
|
|
1465
|
+
number) is the write's postcondition, `ensures`: an invariant of that write
|
|
1466
|
+
alone, id `becomes:InStock`, which each writer judges where the write commits
|
|
1467
|
+
and refuses as `Invalid`. `Write.ensured(Sell.write)` is that invariant, for
|
|
1468
|
+
`Refusal.isInvalidBy`; `Laws.check` reports the arrow `enforced`.
|
|
1469
|
+
|
|
1470
|
+
### Checking every write: `Laws.check`
|
|
1471
|
+
|
|
1472
|
+
`Laws.check` judges each write against each invariant of its Entity, and
|
|
1473
|
+
reports the arrows the writes make between its states. It is pure, needs no
|
|
1474
|
+
database, and reads declarations only:
|
|
1475
|
+
|
|
1476
|
+
<!-- docs-check standalone
|
|
1477
|
+
import { Schema } from 'effect'
|
|
1478
|
+
import { Entity, Footprint, Laws, Write } from 'foldkit-entity'
|
|
1479
|
+
|
|
1480
|
+
const Product = Entity.define(
|
|
1481
|
+
'Product',
|
|
1482
|
+
Schema.Struct({
|
|
1483
|
+
id: Schema.String,
|
|
1484
|
+
name: Schema.String,
|
|
1485
|
+
status: Schema.Literals(['draft', 'published', 'archived']),
|
|
1486
|
+
stock: Schema.Number,
|
|
1487
|
+
}),
|
|
1488
|
+
)
|
|
1489
|
+
const Draft = Entity.refine(Product, 'Draft', { status: 'draft' })
|
|
1490
|
+
const Published = Entity.refine(Product, 'Published', { status: 'published' })
|
|
1491
|
+
const ToPublished = Entity.input(
|
|
1492
|
+
Product,
|
|
1493
|
+
Schema.Struct({ id: Schema.String, status: Schema.Literal('published') }),
|
|
1494
|
+
)
|
|
1495
|
+
const ToDraft = Entity.input(
|
|
1496
|
+
Product,
|
|
1497
|
+
Schema.Struct({ id: Schema.String, status: Schema.Literal('draft') }),
|
|
1498
|
+
)
|
|
1499
|
+
const Rename = {
|
|
1500
|
+
name: 'Rename',
|
|
1501
|
+
write: Write.update(
|
|
1502
|
+
Entity.input(Product, Schema.Struct({ id: Schema.String, name: Schema.String })),
|
|
1503
|
+
{ id: 'id' },
|
|
1504
|
+
),
|
|
1505
|
+
}
|
|
1506
|
+
const Publish = {
|
|
1507
|
+
name: 'Publish',
|
|
1508
|
+
write: Write.update(ToPublished, { id: 'id', from: Draft, becomes: Published }),
|
|
1509
|
+
}
|
|
1510
|
+
const Revert = { name: 'Revert', write: Write.update(ToDraft, { id: 'id' }) }
|
|
1511
|
+
const Sell = {
|
|
1512
|
+
name: 'Sell',
|
|
1513
|
+
write: Write.update(
|
|
1514
|
+
Entity.input(Product, Schema.Struct({ id: Schema.String, quantity: Schema.Int }), {
|
|
1515
|
+
quantity: Entity.unmapped,
|
|
1516
|
+
}),
|
|
1517
|
+
{ id: 'id', increment: { stock: 'quantity' } },
|
|
1518
|
+
),
|
|
1519
|
+
}
|
|
1520
|
+
-->
|
|
1521
|
+
|
|
1522
|
+
```ts
|
|
1523
|
+
const report = Laws.check({ writes: [Rename, Publish, Revert, Sell] })
|
|
1524
|
+
Laws.show(report)
|
|
1525
|
+
```
|
|
1526
|
+
|
|
1527
|
+
|
|
1528
|
+
For the writes example, whose domain has a `reservedWithinStock` state
|
|
1529
|
+
invariant, a `publishedStaysPublished` transition invariant and an `Archived`
|
|
1530
|
+
state that the snippet above does not, it prints lines such as these (abridged;
|
|
1531
|
+
[`examples/writes/LAWS.md`](https://github.com/doeixd/foldkit-plus/blob/main/examples/writes/LAWS.md)
|
|
1532
|
+
keeps the whole report, so a write added changes a checked-in file):
|
|
1533
|
+
|
|
1534
|
+
```text
|
|
1535
|
+
Product
|
|
1536
|
+
Draft -> Published Publish holds
|
|
1537
|
+
Published -> Draft Revert refused by publishedStaysPublished
|
|
1538
|
+
Archived -> Draft Revert undeclared
|
|
1539
|
+
Archived unreached
|
|
1540
|
+
|
|
1541
|
+
Rename x reservedWithinStock kept: writes no member it reads
|
|
1542
|
+
Revert x publishedStaysPublished refused: from {"status":"published"} it leaves {"status":"draft"}
|
|
1543
|
+
Sell x reservedWithinStock undecided: stock is incremented
|
|
1544
|
+
```
|
|
1545
|
+
|
|
1546
|
+
One write against one invariant comes to one of three verdicts:
|
|
1547
|
+
|
|
1548
|
+
| Case | Verdict |
|
|
1549
|
+
| --- | --- |
|
|
1550
|
+
| A state invariant, and the write writes no member it reads | `Kept`, by disjointness |
|
|
1551
|
+
| Every member it reads is finite (a literal, a union of literals, a boolean, with or without null), and the write changes each only by setting it | Enumerated: `Kept`, or `Refused` with the rows that break it |
|
|
1552
|
+
| Anything else: a number, free text, an increment, a computed field, a link, an operator the table lacks, more than 4,096 rows | `Undecided`, with the reason |
|
|
1553
|
+
|
|
1554
|
+
A transition invariant is never kept by disjointness: `after.count >
|
|
1555
|
+
before.count` is broken by every write that leaves `count` alone. Rows are not
|
|
1556
|
+
filtered by the invariants before enumeration, since a row may be invalid
|
|
1557
|
+
before a write; a row the write's `when` (and `from`) definitely refuses is
|
|
1558
|
+
dropped, and one it cannot judge stays.
|
|
1559
|
+
|
|
1560
|
+
The findings (`holds`, `enforced`, `undeclared`, `refused`, `unreached`,
|
|
1561
|
+
`terminal`) are reports, never faults: a write an invariant can refuse is
|
|
1562
|
+
legitimate. `enforced` (`* -> InStock Sell enforced`) is a `becomes` held by
|
|
1563
|
+
its postcondition where the write commits, and that postcondition is a pair of
|
|
1564
|
+
the write alone (`Sell x becomes:InStock`).
|
|
1565
|
+
|
|
1566
|
+
A transition that is no declared write (another package's command, an
|
|
1567
|
+
import) is an entry with a `Footprint`: what its author says it writes, or
|
|
1568
|
+
`Footprint.unknown`, which writes every member and is `Undecided` against
|
|
1569
|
+
every invariant:
|
|
1570
|
+
|
|
1571
|
+
```ts
|
|
1572
|
+
Laws.check({
|
|
1573
|
+
writes: [
|
|
1574
|
+
{ name: 'Touch', entity: Product, footprint: Footprint.declared({ writes: [Product.fields.name], by: 'the import' }) },
|
|
1575
|
+
{ name: 'Import', entity: Product, footprint: Footprint.unknown },
|
|
1576
|
+
],
|
|
1577
|
+
})
|
|
1578
|
+
```
|
|
1579
|
+
|
|
1580
|
+
A declared footprint names fields by reference, so one of another Entity is a
|
|
1581
|
+
type error where the entry names its Entity. It keeps a state invariant only
|
|
1582
|
+
by disjointness, and decides no transition invariant. `Write.footprint(write)`
|
|
1583
|
+
is a declared write's own.
|
|
1584
|
+
|
|
1585
|
+
#### Evidence, and the graph's facts
|
|
1586
|
+
|
|
1587
|
+
A pair the check keeps by reading the declarations (by disjointness, by
|
|
1588
|
+
enumeration, a create against a transition invariant, a delete) carries an
|
|
1589
|
+
`Enumerated` record in `evidence`, issued by `foldkit-entity/laws`. A pair
|
|
1590
|
+
kept on its author's word (`declared`), refused or undecided carries none:
|
|
1591
|
+
for those, the evidence is a walk through the writer, a scenario, or
|
|
1592
|
+
`Evidence.runtimeOnly` with its reason. These records are
|
|
1593
|
+
`foldkit-metadata`'s `Evidence`; the `Evidence` this package exports is an
|
|
1594
|
+
operator law's (`Tested`, `Proven`, [below](#laws-and-holding-an-implementation-to-them)).
|
|
1595
|
+
|
|
1596
|
+
```ts
|
|
1597
|
+
import { Option } from 'effect'
|
|
1598
|
+
import { lawFactsOf } from 'foldkit-entity'
|
|
1599
|
+
import { Evidence } from 'foldkit-metadata'
|
|
1600
|
+
|
|
1601
|
+
const records = report.pairs.flatMap(pair => Option.toArray(pair.evidence))
|
|
1602
|
+
records.map(Evidence.issuedBy) // some('foldkit-entity/laws') for each kept pair
|
|
1603
|
+
Laws.transition(Rename) // 'write:Rename'
|
|
1604
|
+
const { nodes, edges } = Laws.facts(report)
|
|
1605
|
+
lawFactsOf([Rename]) // the same shape, read off the declarations, with no check run
|
|
1606
|
+
```
|
|
1607
|
+
|
|
1608
|
+
Records and the graph name a transition `write:<name>` (`Laws.transition`)
|
|
1609
|
+
and a law `<Entity>.<id>` (`Laws.law(invariant)`), so `Laws.check` throws for
|
|
1610
|
+
two entries of one name. `lawId` and `transitionId` are the same two
|
|
1611
|
+
functions by name, in a module of their own, for code that must not carry the
|
|
1612
|
+
check.
|
|
1613
|
+
`Laws.facts(report)` is the law half of `foldkit-surface`'s graph as plain
|
|
1614
|
+
data in that graph's own shape (`GraphFacts`), since this package does not
|
|
1615
|
+
import Surface: a `Law` per invariant, a `Transition` per write in a pair or an
|
|
1616
|
+
arrow, a `State` per local state, `Reads` and `Writes` over `space: 'entity'`
|
|
1617
|
+
paths such as `['Product', 'stock']`, `From` and `To` per arrow, and a `Keeps`
|
|
1618
|
+
edge per transition and law whose every pair carries a record. A write's own
|
|
1619
|
+
`ensures` is marked `postcondition` on its pair and is no law of the Entity,
|
|
1620
|
+
so the facts leave it out; an `Unknown` footprint writes every member, so it
|
|
1621
|
+
has a `Writes` edge to each member a law of its Entity reads. A transition
|
|
1622
|
+
invariant (`pair.readsBefore`) also reads its whole row (`['Product']`), since
|
|
1623
|
+
a write leaving every member it reads alone can still break it.
|
|
1624
|
+
`lawFactsOf(entries)` gives the same shape from `Laws.check`'s entries without
|
|
1625
|
+
judging them, so not the same facts: a `State` for every state, local or not,
|
|
1626
|
+
`From` and `To` from each write's declared `from` and `becomes`, a `Writes`
|
|
1627
|
+
edge to every field for an `Unknown` footprint, and no `Keeps`. It is what Surface's `Graph.of` derives a contract's
|
|
1628
|
+
`laws.entities` with (a Remote domain declares its writes there), so only a
|
|
1629
|
+
page that asks for the graph carries it, and never the check.
|
|
1630
|
+
|
|
1272
1631
|
## Naming a question: operators
|
|
1273
1632
|
|
|
1274
1633
|
What operators make possible, end to end (a rule named once, search and order
|
|
@@ -1280,7 +1639,7 @@ A predicate an application asks in many places (in a public query, a
|
|
|
1280
1639
|
visitor's Read rule, an invariant) can be given a name. `Expr.operator`
|
|
1281
1640
|
declares one by what a call of it means:
|
|
1282
1641
|
|
|
1283
|
-
```ts
|
|
1642
|
+
```ts standalone
|
|
1284
1643
|
import { Schema } from 'effect'
|
|
1285
1644
|
import { Entity, Expr, Query } from 'foldkit-entity'
|
|
1286
1645
|
|
|
@@ -1301,16 +1660,14 @@ Query.show(PublicStories)
|
|
|
1301
1660
|
// WHERE acme.published(Story.publishedAt)
|
|
1302
1661
|
```
|
|
1303
1662
|
|
|
1304
|
-
- **It computes nothing of its own
|
|
1305
|
-
call's arguments, once per call, and
|
|
1306
|
-
(`Expr.expanded` writes a predicate's
|
|
1307
|
-
|
|
1308
|
-
|
|
1309
|
-
|
|
1310
|
-
|
|
1311
|
-
|
|
1312
|
-
input, instead of taking it, is refused when called: nothing asking what the
|
|
1313
|
-
call reads (Guard's checks, Remote's matching) would see it.
|
|
1663
|
+
- **It computes nothing of its own, and reads only its arguments.**
|
|
1664
|
+
`definedAs` builds an expression from a call's arguments, once per call, and
|
|
1665
|
+
every interpreter runs that expression (`Expr.expanded` writes a predicate's
|
|
1666
|
+
calls out); one that closes over a field or an input instead of taking it is
|
|
1667
|
+
refused when called. `Query.show` prints the call, and
|
|
1668
|
+
`Query.dependencies(body).operators` lists each operator a body uses. The
|
|
1669
|
+
guide's [What the calls mean](../../docs/operators.md#what-the-calls-mean)
|
|
1670
|
+
says why.
|
|
1314
1671
|
- **Arguments are checked by their stored form**, at compile time and when
|
|
1315
1672
|
called: a field, scalar or plain value of the input's stored type, or a
|
|
1316
1673
|
predicate where it takes a boolean. A boolean `output` makes a call a
|
|
@@ -1329,7 +1686,7 @@ interpreter's implementation does, and every implementation is held to the
|
|
|
1329
1686
|
same statement of it. The kernel ships one, `Text.startsWith`; an application
|
|
1330
1687
|
declares its own and implements it, here for the in-memory interpreter:
|
|
1331
1688
|
|
|
1332
|
-
```ts
|
|
1689
|
+
```ts standalone
|
|
1333
1690
|
import { Schema } from 'effect'
|
|
1334
1691
|
import { Collation, Entity, Expr, Operators, Query, Text, evaluate } from 'foldkit-entity'
|
|
1335
1692
|
|
|
@@ -1366,7 +1723,8 @@ refused where it is written.
|
|
|
1366
1723
|
twice, or two under one name; `merge` refuses an overlap, and `override`
|
|
1367
1724
|
replaces on purpose. `Operators.checked(table)` checks each answer against
|
|
1368
1725
|
the operator's output schema, for tests. Nothing registers globally:
|
|
1369
|
-
`evaluate`, `evaluateEach`, `decided`, `truthOver`, `Entity.judge`,
|
|
1726
|
+
`evaluate`, `evaluateEach`, `decided`, `truthOver`, `Entity.judge`,
|
|
1727
|
+
`Entity.judgeInput(input, value, { operators })` and
|
|
1370
1728
|
`Entity.check(entity, { operators })` each take the table, `Operators.kernel`
|
|
1371
1729
|
by default.
|
|
1372
1730
|
- **Null is strict by default.** A null argument gives null (unknown for a
|
|
@@ -1444,7 +1802,7 @@ Operators.describeTable(recorded) // [{ name: 'acme.concat', …, laws, evidence
|
|
|
1444
1802
|
first `Counterexample` with both sides and its collation: declaring `concat` commutative
|
|
1445
1803
|
finds `"a"` and `"A"`, which give `"aA"` and `"Aa"`. Two sides that both refuse agree,
|
|
1446
1804
|
but are no case: a record counts only cases whose sides both answered, and a law with
|
|
1447
|
-
none is `Unanswered`, with the first
|
|
1805
|
+
none is `Unanswered`, with the reason the first left side refused for, and records nothing.
|
|
1448
1806
|
- **Evidence is an implementation's.** `Operators.withEvidence` refuses a record
|
|
1449
1807
|
of an operator the table lacks or a law it does not declare, and a `Tested`
|
|
1450
1808
|
record `Conformance.laws` did not make of this table's own implementation
|
|
@@ -1469,42 +1827,16 @@ generated from each argument's samples, null where its schema admits one, and
|
|
|
1469
1827
|
text holding NUL, under `binary` and `asciiFold` where the operator compares
|
|
1470
1828
|
text. `Conformance.memory(table)` is the reference interpreter's runner; a
|
|
1471
1829
|
defined operator's expansion runs beside the others as `expansion`, a name an
|
|
1472
|
-
implementation of
|
|
1830
|
+
implementation of a defined operator may not take. `foldkit-remote-drizzle`
|
|
1473
1831
|
runs the kernel's operators and an application's through it on SQLite and
|
|
1474
1832
|
Postgres.
|
|
1475
1833
|
|
|
1476
|
-
###
|
|
1477
|
-
|
|
1478
|
-
The `concat` above, as an application ships it: declared once, implemented for
|
|
1479
|
-
each interpreter that runs it, held to itself, and described for whoever asks
|
|
1480
|
-
what a server runs.
|
|
1834
|
+
### Describing what a table runs
|
|
1481
1835
|
|
|
1482
|
-
|
|
1483
|
-
|
|
1484
|
-
|
|
1485
|
-
|
|
1486
|
-
import { DrizzleOperators } from 'foldkit-remote-drizzle'
|
|
1487
|
-
|
|
1488
|
-
// In memory, as above; in SQL, for a binding (`bind(…, { operators: { memory, sql } })`).
|
|
1489
|
-
const memory = Operators.memory(Operators.implement(concat, (left, right) => `${left}${right}`))
|
|
1490
|
-
const sqlTable = DrizzleOperators.make(
|
|
1491
|
-
DrizzleOperators.implement(concat, ({ args: [left, right] }) => sql`(${left} || ${right})`),
|
|
1492
|
-
)
|
|
1493
|
-
|
|
1494
|
-
// Its laws, against the memory implementation.
|
|
1495
|
-
const held = Conformance.laws(concat, memory)
|
|
1496
|
-
|
|
1497
|
-
// The two implementations against each other: an SQL runner selects
|
|
1498
|
-
// `compileCall(call, binding, name)` from a database (foldkit-remote-drizzle's
|
|
1499
|
-
// test/operatorConformance.test.ts has one); here the memory one alone.
|
|
1500
|
-
const report = await Conformance.operator(concat, {
|
|
1501
|
-
implementations: { memory: Conformance.memory(memory) },
|
|
1502
|
-
})
|
|
1503
|
-
|
|
1504
|
-
// Its signature as JSON: name, version, each argument and the result as a JSON
|
|
1505
|
-
// Schema of what is stored, its null and collation rules, its laws.
|
|
1506
|
-
Operators.describe(concat)
|
|
1507
|
-
```
|
|
1836
|
+
Declared once, implemented per interpreter, held to its laws and described for
|
|
1837
|
+
whoever asks what a server runs: the guide carries one operator the whole way
|
|
1838
|
+
([An operator of your own](../../docs/operators.md#an-operator-of-your-own) to
|
|
1839
|
+
[Publishing what a server runs](../../docs/operators.md#publishing-what-a-server-runs)).
|
|
1508
1840
|
|
|
1509
1841
|
`Operators.describe` gives an `OperatorDescription`, a Schema whose decoder
|
|
1510
1842
|
checks a description another server publishes; it says what an operator takes
|
|
@@ -1516,6 +1848,24 @@ holding `acme.slug` does not answer a body calling `acme.slug@2`, and the
|
|
|
1516
1848
|
refusal names both (`acme.slug@2 (this table has acme.slug)`), so a client and a
|
|
1517
1849
|
server on different deploys see which side is behind.
|
|
1518
1850
|
|
|
1851
|
+
## Limits
|
|
1852
|
+
|
|
1853
|
+
- The identifier is the field named `id`; no other field can be declared as it,
|
|
1854
|
+
because Remote keys its store by `id`.
|
|
1855
|
+
- A Selection has no filtering or ordering, and a page has no total; those
|
|
1856
|
+
belong to the interpreter that fetches.
|
|
1857
|
+
- A relation reaches only the entities of its own `Entity.relate` call; relate
|
|
1858
|
+
them again to add relations between them.
|
|
1859
|
+
- `target()` returns the entity as `relate` returned it: every member added
|
|
1860
|
+
since is on it (`likeCount`), but metadata annotated afterwards (`CmsPost`
|
|
1861
|
+
above) is on that new descriptor only, so annotate before relating when a
|
|
1862
|
+
target should carry it. Its type shows the members as related; read a later
|
|
1863
|
+
one as an `AnyEntity`.
|
|
1864
|
+
- A member is added once per Entity: two pipe chains from one descriptor that
|
|
1865
|
+
each add `score` are refused, as one chain adding it twice is. Adding the very
|
|
1866
|
+
spec again (`Guards.may` on a second view) is the member it added.
|
|
1867
|
+
- No registry: nothing checks that two different entities share a name.
|
|
1868
|
+
|
|
1519
1869
|
## API
|
|
1520
1870
|
|
|
1521
1871
|
| Call | Meaning |
|
|
@@ -1528,8 +1878,17 @@ server on different deploys see which side is behind.
|
|
|
1528
1878
|
| `Entity.select(entity, { key: true or Selection })` | A Selection: what was selected (`members`) and the `schema` of the result; a tagged union of cases for a variant Entity whose `_tag` is selected. |
|
|
1529
1879
|
| `Entity.page(selection, { first, after } or { last, before })` | In a Selection, a `many` relation read as a page: `items`, `hasNext`, `hasPrevious`. |
|
|
1530
1880
|
| `Entity.fields(entity, ...keys)` | The schemas of those fields, by key, to spread into an input's struct. |
|
|
1531
|
-
| `Write.update(input, { id, expect?, when?, increment? })` | A declared update of one row: every key the input maps to a field, but the id and the expected revision; `when`, what the row must hold for it to land; `increment`, the number fields it moves by an input amount. |
|
|
1532
|
-
| `Write.insert(input, { id })` / `Write.delete(input, { id, expect?, when? })` | A declared insert under an id the client chose; a declared delete of one row, which sets nothing. |
|
|
1881
|
+
| `Write.update(input, { id, expect?, when?, from?, becomes?, increment? })` | A declared update of one row: every key the input maps to a field, but the id and the expected revision; `when`, what the row must hold for it to land; `from`, a state whose predicate joins the `when`; `becomes`, the state every row it starts from is in once it lands, proved where declared or else held where it commits (`ensures`); `increment`, the number fields it moves by an input amount. |
|
|
1882
|
+
| `Write.insert(input, { id, becomes? })` / `Write.delete(input, { id, expect?, when?, from? })` | A declared insert under an id the client chose; a declared delete of one row, which sets nothing. |
|
|
1883
|
+
| `Write.ensured(write)` | The postcondition a `becomes` enumeration could not decide holds the write to where it commits (`becomes:<State>`), for `Refusal.isInvalidBy`; throws for a write with none. |
|
|
1884
|
+
| `Write.footprint(write)` | What a write reads and writes of its row, by field key, as a `Footprint.Derived`. |
|
|
1885
|
+
| `Entity.refine(entity, name, { field: value } or ({ row }) => predicate)` | A named state of the row, declared on the Entity: `predicate`, `after`, `local`, `reads`, `is(row)`. |
|
|
1886
|
+
| `Entity.states(entity)` / `Entity.inState(state, row, operators?)` | Every state declared on an Entity; whether a stored row is in one (`Option`, none where it lacks a field the state reads). |
|
|
1887
|
+
| `Query.from(state)` | Every row in a state: the Entity's query with its predicate in `where`. |
|
|
1888
|
+
| `Laws.check({ writes, operators? })` / `Laws.show(report)` | Each write (`{ name, write }` or `{ name, entity, footprint }`) against each invariant of its Entity, and the arrows between its states, by enumeration over finite fields: a `LawReport` of `pairs` (each with its `Enumerated` `evidence`, if decided kept), `arrows`, `states` and `findings`; the report as text. |
|
|
1889
|
+
| `Laws.facts(report)` / `Laws.transition(entry)` / `Laws.law(invariant)` | The report as graph facts (`LawFacts`: `LawNode`s and `LawEdge`s); a transition's id (`write:Sell`) and a law's (`Product.reservedWithinStock`) in evidence and the graph. |
|
|
1890
|
+
| `lawFactsOf(entries)` | `Laws.check`'s entries as graph facts, read off the declarations with no check run: what `Graph.of` derives a contract's `laws.entities` with. |
|
|
1891
|
+
| `Footprint.declared({ reads?, writes, by })` / `Footprint.unknown` | What a transition that is no declared write reads and writes, on whose word; or nothing known, which writes every member. |
|
|
1533
1892
|
| `Write.reads(write)` | The fields a write reads from its row: its `when`'s, each it increments, its assignments', the revision. |
|
|
1534
1893
|
| `Write.update(input, { …, compute })` / `Computation` | A field computed from the row before the write and the input, carried as data. |
|
|
1535
1894
|
| `Write.apply(row, bound, { operators })` / `Write.boundReads(bound)` | The row a bound write leaves, and what of the row before it that needs. |
|
|
@@ -1571,10 +1930,11 @@ server on different deploys see which side is behind.
|
|
|
1571
1930
|
| `Expr.operator(id, { input, output, definedAs?, version?, description?, nulls?, collation?, laws? })` | An operator: defined by what a call means (`definedAs`, whose expansion every interpreter runs) or primitive (each interpreter's table implements it). Calling it builds a `Test` predicate (a boolean output) or a `Call` scalar. |
|
|
1572
1931
|
| `Expr.unsupported(nodes, { operations, operators })` | What these expressions need that an interpreter lacks: operations, then primitive operators by name. |
|
|
1573
1932
|
| `Text.startsWith(text, prefix, { collation? })` | Whether text begins with a prefix, under its collation; the kernel's primitive operator. |
|
|
1933
|
+
| `Expr.eq.step(value)` / `lt` / `lte` / `gt` / `gte.step(value, { collation? })` / `contains.step(search)` / `in.step(list)`; `operator.step(...rest)` | The call without its subject, for `pipe` and `flow`: `pipe(Post.fields.status, Expr.eq.step('draft'))` builds the node `Expr.eq(Post.fields.status, 'draft')` builds. One signature, so reads stay exact. |
|
|
1574
1934
|
| `Operators.memory(...)` / `implement` / `implementHandlingNulls` / `merge` / `override` / `checked` / `kernel` | Tables of in-memory implementations of primitive operators, passed to `evaluate` and every judge. |
|
|
1575
1935
|
| `Law.associative` / `commutative` / `idempotent` / `identity` / `absorbing` / `inverse` / `distributes` / `monotonic` / `preservesCollation` / `within` / `describe` | Laws an operator declares (`Expr.operator(id, { laws })`), checked where declared, described as JSON. |
|
|
1576
1936
|
| `Operators.withEvidence(table, evidence)` / `describeTable(table)` / `Evidence.Proven` | What is known of a table's implementations' laws, and the table as JSON. |
|
|
1577
|
-
| `Conformance.laws(op, table)` / `lawsBy(op, runner)` / `operator(op, { implementations })` / `memory(table)` (`foldkit-entity/conformance`) | Test an implementation's laws, in memory or through any runner; run one set of calls through several implementations. |
|
|
1937
|
+
| `Conformance.laws(op, table)` / `lawsBy(op, runner, { implementation })` (a Promise) / `operator(op, { implementations })` / `memory(table)` (`foldkit-entity/conformance`) | Test an implementation's laws, in memory or through any runner; run one set of calls through several implementations. |
|
|
1578
1938
|
| `Operators.describe(op)` / `OperatorDescription` / `Query.operators(body)` | An operator's signature as JSON, the Schema it keeps, and the operators a body calls, by name. |
|
|
1579
1939
|
| `valueOfOperand(node, { operators })` | What an operand, a call of literals say, comes to over no row. |
|
|
1580
1940
|
| `Expr.expanded(predicate)` | The predicate with every call of a defined operator written out as what it means, deeply; what an interpreter compiles. |
|
|
@@ -1594,21 +1954,3 @@ server on different deploys see which side is behind.
|
|
|
1594
1954
|
| `Query.dependencies(query)` | What the whole query reads, with its fields also split by role: `predicate` (can change which rows match) and `order` (can change where a row sits). |
|
|
1595
1955
|
| `Query.unsupported(query, supported)` | The operations it needs that an interpreter does not run. |
|
|
1596
1956
|
| `Query.show(query)` / `Expr.show(node)` | The query or expression as readable text, for a person and not for an interpreter. |
|
|
1597
|
-
|
|
1598
|
-
## Limits
|
|
1599
|
-
|
|
1600
|
-
- The identifier is the field named `id`; no other field can be declared as it,
|
|
1601
|
-
because Remote keys its store by `id`.
|
|
1602
|
-
- A Selection has no filtering or ordering, and a page has no total; those
|
|
1603
|
-
belong to the interpreter that fetches.
|
|
1604
|
-
- A relation reaches only the entities of its own `Entity.relate` call; relate
|
|
1605
|
-
them again to add relations between them.
|
|
1606
|
-
- `target()` returns the entity as `relate` returned it: every member added
|
|
1607
|
-
since is on it (`likeCount`), but metadata annotated afterwards (`CmsPost`
|
|
1608
|
-
above) is on that new descriptor only, so annotate before relating when a
|
|
1609
|
-
target should carry it. Its type shows the members as related; read a later
|
|
1610
|
-
one as an `AnyEntity`.
|
|
1611
|
-
- A member is added once per Entity: two pipe chains from one descriptor that
|
|
1612
|
-
each add `score` are refused, as one chain adding it twice is. Adding the very
|
|
1613
|
-
spec again (`Guards.may` on a second view) is the member it added.
|
|
1614
|
-
- No registry: nothing checks that two different entities share a name.
|