foldkit-surface 0.14.0 → 0.15.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 +205 -6
- package/dist/closure.d.ts +75 -0
- package/dist/closure.d.ts.map +1 -0
- package/dist/closure.js +95 -0
- package/dist/closure.js.map +1 -0
- package/dist/graph.d.ts +238 -0
- package/dist/graph.d.ts.map +1 -0
- package/dist/graph.js +350 -0
- package/dist/graph.js.map +1 -0
- package/dist/index.d.ts +56 -14
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +31 -23
- package/dist/index.js.map +1 -1
- package/dist/messageTags.d.ts +9 -0
- package/dist/messageTags.d.ts.map +1 -0
- package/dist/messageTags.js +14 -0
- package/dist/messageTags.js.map +1 -0
- package/dist/text.d.ts +6 -0
- package/dist/text.d.ts.map +1 -0
- package/dist/text.js +8 -0
- package/dist/text.js.map +1 -0
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -17,11 +17,12 @@ of its own.
|
|
|
17
17
|
|
|
18
18
|
## The mental model
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
20
|
+
A Surface is derived in three steps from the application's Model Schema: the
|
|
21
|
+
Schema gives typed field references, a Projection picks the fields a feature
|
|
22
|
+
reads, and a named Surface pairs that Projection with the Messages the feature
|
|
23
|
+
may send. At run time the application's Model is read through the Projection to
|
|
24
|
+
give the feature its input, and the feature's Message goes to the application's
|
|
25
|
+
`update`, which produces the next Model.
|
|
25
26
|
|
|
26
27
|
Declaring or reading a Surface does not dispatch a Message, fetch data, or
|
|
27
28
|
create a state owner. Its Message list constrains consumers; the application's
|
|
@@ -183,6 +184,23 @@ was last given, and an empty `on` throws, since nothing could tell it to work
|
|
|
183
184
|
the value out again. What it returns is `{ dependencies, read }`, which
|
|
184
185
|
`foldkit-mixins`' `SlotView.region` takes, and a region uses the same rule.
|
|
185
186
|
|
|
187
|
+
A Derived can be an entry of `Projection.struct` when it names the Schema of its
|
|
188
|
+
value, `Projection.derive(on, derive, { Model: Schema.Number })`. The struct then
|
|
189
|
+
reads the memoized value, declares the Derived's paths and checks the value
|
|
190
|
+
against `Model` like any entry, so a Surface can show it:
|
|
191
|
+
|
|
192
|
+
```ts
|
|
193
|
+
const Count = Projection.derive([App.model.todos], model => model.todos.length, {
|
|
194
|
+
Model: Schema.Number,
|
|
195
|
+
})
|
|
196
|
+
const Board = Projection.struct({ count: Count, selected: App.model.selectedTodoId })
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
A Derived carries no metadata, so the struct plans no requirements for it,
|
|
200
|
+
whatever `on` holds: a Remote read it works from is planned by the Remote read
|
|
201
|
+
itself, not by the struct that shows the value. A Derived without `Model` is a
|
|
202
|
+
type error in a `struct`, and throws if the type is bypassed.
|
|
203
|
+
|
|
186
204
|
### Metadata
|
|
187
205
|
|
|
188
206
|
`Metadata` is [`foldkit-metadata`](../metadata/README.md), re-exported so an
|
|
@@ -210,6 +228,92 @@ opaque and its entries frozen; only a key's `of` and composition make one.
|
|
|
210
228
|
Surface never interprets them; `Surface.inspect` and `Module` show them through
|
|
211
229
|
`summarize`.
|
|
212
230
|
|
|
231
|
+
### Closure
|
|
232
|
+
|
|
233
|
+
A projection is **closed** when its value after a Message depends only on the
|
|
234
|
+
projection before it and the Message. Sync replays a durable Message over the
|
|
235
|
+
shared slice alone, so the slice has to be closed for it. `Closure.reads` is
|
|
236
|
+
the check: it runs `update` on the Model, and again with every top-level field
|
|
237
|
+
the projection does not depend on reset to `initial`, compares the two
|
|
238
|
+
projections with the projection's codec, and names the fields whose reset
|
|
239
|
+
changed the answer. It returns `[]` for a closed step. Nothing else runs:
|
|
240
|
+
Commands `update` returns are ignored, and nothing is written.
|
|
241
|
+
|
|
242
|
+
```ts standalone
|
|
243
|
+
import { Schema } from 'effect'
|
|
244
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
245
|
+
import { Closure, Projection, Surface } from 'foldkit-surface'
|
|
246
|
+
|
|
247
|
+
const Model = Schema.Struct({
|
|
248
|
+
todos: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })),
|
|
249
|
+
filter: Schema.String,
|
|
250
|
+
})
|
|
251
|
+
type Model = typeof Model.Type
|
|
252
|
+
const Message = defineMessageUnion({ ClearedShown: {} })
|
|
253
|
+
const initial: Model = { todos: [], filter: '' }
|
|
254
|
+
const update = (model: Model, _message: typeof Message.Type) => ({
|
|
255
|
+
// Removes the todos whose title is the local `filter`.
|
|
256
|
+
model: { ...model, todos: model.todos.filter(todo => todo.title !== model.filter) },
|
|
257
|
+
})
|
|
258
|
+
|
|
259
|
+
const App = Surface.application({ Model, Message })
|
|
260
|
+
const shown: Model = { todos: [{ id: 'a', title: 'x' }], filter: 'x' }
|
|
261
|
+
|
|
262
|
+
Closure.reads({ initial, update }, Projection.pick(App.model.todos), shown, Message.ClearedShown())
|
|
263
|
+
// ['filter']: the slice after ClearedShown depends on it
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
It takes a read-only `Projection` as well as a `WritableProjection`, and a
|
|
267
|
+
field that holds any path of the projection is never named. `Sync.mount` runs it
|
|
268
|
+
on every durable dispatch; see the
|
|
269
|
+
[Sync README](https://github.com/doeixd/foldkit-plus/blob/main/packages/sync/README.md#what-makes-a-message-durable).
|
|
270
|
+
|
|
271
|
+
### A closed Surface
|
|
272
|
+
|
|
273
|
+
`closed: true` on a Surface declares the same property of the whole Surface: for
|
|
274
|
+
a Message in its `messages`, the projection after depends only on the projection
|
|
275
|
+
before and the Message, and no other Message changes it. Declaring it enforces
|
|
276
|
+
nothing at run time; it is a law of the application, tested in a walk.
|
|
277
|
+
`Closure.violations(app, surfaces)` returns a step check,
|
|
278
|
+
`(before, message, after) => violations`, to call at every step of a walk. It
|
|
279
|
+
tests only the Surfaces declared closed, and refuses a closed Surface with
|
|
280
|
+
params, which has no one projection.
|
|
281
|
+
|
|
282
|
+
```ts standalone
|
|
283
|
+
import { Schema } from 'effect'
|
|
284
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
285
|
+
import { Closure, Surface } from 'foldkit-surface'
|
|
286
|
+
|
|
287
|
+
const Model = Schema.Struct({ todos: Schema.Array(Schema.String), tally: Schema.Number })
|
|
288
|
+
type Model = typeof Model.Type
|
|
289
|
+
const Message = defineMessageUnion({ Emptied: {}, Counted: {} })
|
|
290
|
+
const initial: Model = { todos: ['a'], tally: 0 }
|
|
291
|
+
const update = (model: Model, message: typeof Message.Type) => ({
|
|
292
|
+
model: Message.match(message, {
|
|
293
|
+
Emptied: () => ({ ...model, todos: [] }),
|
|
294
|
+
Counted: () => ({ ...model, tally: model.tally + 1 }),
|
|
295
|
+
}),
|
|
296
|
+
})
|
|
297
|
+
|
|
298
|
+
const App = Surface.application({ Model, Message, initial, update })
|
|
299
|
+
const Shown = App.surface('Shown', {
|
|
300
|
+
model: ({ model }) => ({ todos: model.todos }),
|
|
301
|
+
messages: [Message.Emptied],
|
|
302
|
+
closed: true,
|
|
303
|
+
})
|
|
304
|
+
|
|
305
|
+
const check = Closure.violations(App, [Shown])
|
|
306
|
+
const counted = Message.Counted()
|
|
307
|
+
check(initial, counted, update(initial, counted).model)
|
|
308
|
+
// []: Counted is outside the Surface and leaves its projection alone
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
A violation is a `ClosureViolation`: `Reads({ surface, fields })` for a Message
|
|
312
|
+
in the set that reads fields outside the Surface (the fields are named), or
|
|
313
|
+
`Outside({ surface })` for a Message outside the set that changed the
|
|
314
|
+
projection. Read one through `ClosureViolation.$match`.
|
|
315
|
+
`Surface.contract` carries `closed: true` for such a Surface.
|
|
316
|
+
|
|
213
317
|
## Applications
|
|
214
318
|
|
|
215
319
|
`Surface.application({ Model, Message })` returns an `Application`: the schemas
|
|
@@ -229,7 +333,7 @@ returns a `RunnableApplication` with the same references and the same owner.
|
|
|
229
333
|
A second `Surface.application` for the update would be another application,
|
|
230
334
|
whose references `Projection.pick` refuses to mix with the first's:
|
|
231
335
|
|
|
232
|
-
<!-- docs-check standalone
|
|
336
|
+
<!-- docs-check standalone define todoApp
|
|
233
337
|
import { Option, Schema } from 'effect'
|
|
234
338
|
import { defineMessageUnion } from 'foldkit/message'
|
|
235
339
|
import { ModelRef, Projection, Surface } from 'foldkit-surface'
|
|
@@ -389,6 +493,90 @@ recorded by two replication contracts, and a path or Message the application
|
|
|
389
493
|
does not declare. `Module.add(module, ...more)` returns a new Module, so feature
|
|
390
494
|
modules can contribute their contracts independently.
|
|
391
495
|
|
|
496
|
+
### Laws in the graph
|
|
497
|
+
|
|
498
|
+
A contract may also say which laws it holds and which transitions can break
|
|
499
|
+
them. `Contract.laws` holds the declarations themselves, and `Graph.of`
|
|
500
|
+
derives their nodes and edges only when it is asked. `Graph` is apart from
|
|
501
|
+
`Module`: a page that reads only `Module` (to draw who owns what) carries
|
|
502
|
+
none of the graph's code. `laws.entities` lists transitions over
|
|
503
|
+
Entities as `Laws.check` takes them: Remote declares each declared write, which
|
|
504
|
+
becomes `write:Sell` beside a law per invariant of its Entity
|
|
505
|
+
(`Product.reservedWithinStock`). `laws.model` names laws over the contract's
|
|
506
|
+
Model slice: Sync declares its document's, each `sync:<name>.<id>` reading the
|
|
507
|
+
whole slice, and each of its Messages is `durable:<tag>` writing it. A closed
|
|
508
|
+
Surface is a level with a `closure:<name>` law over its paths.
|
|
509
|
+
`Graph.of(module, { evidence })` joins them.
|
|
510
|
+
|
|
511
|
+
```text
|
|
512
|
+
transition --writes--> path <--reads-- law
|
|
513
|
+
transition ----------keeps(evidence)--> law
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
A transition that writes a path a law reads could break it. The graph does not
|
|
517
|
+
decide whether it does; evidence says so: `Laws.check`'s `Enumerated` records,
|
|
518
|
+
what a walk or a scenario returns, or `Evidence.runtimeOnly` for a pair only
|
|
519
|
+
the writer or the journal refuses. `Graph.validate(module, { evidence })` asks
|
|
520
|
+
the one question of the graph; with no `evidence`, every pair a transition can
|
|
521
|
+
break is unwitnessed. `Module.validate` asks none of these rules, and
|
|
522
|
+
`Graph.validate` none of `Module`'s, so a test that wants both asks both.
|
|
523
|
+
|
|
524
|
+
```ts standalone
|
|
525
|
+
import { Schema } from 'effect'
|
|
526
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
527
|
+
import { Evidence, Graph, Module, Surface } from 'foldkit-surface'
|
|
528
|
+
|
|
529
|
+
const App = Surface.application({
|
|
530
|
+
Model: Schema.Struct({ todos: Schema.Array(Schema.String) }),
|
|
531
|
+
Message: defineMessageUnion({ Added: { title: Schema.String } }),
|
|
532
|
+
})
|
|
533
|
+
|
|
534
|
+
// What `Sync.forApplication(App).make` declares for a document with one law.
|
|
535
|
+
const todos = {
|
|
536
|
+
kind: 'sync',
|
|
537
|
+
name: 'todos',
|
|
538
|
+
owner: App.owner,
|
|
539
|
+
owns: [['todos']],
|
|
540
|
+
observes: [['todos']],
|
|
541
|
+
messages: ['Added'],
|
|
542
|
+
metadata: [],
|
|
543
|
+
laws: { model: ['capped'] },
|
|
544
|
+
}
|
|
545
|
+
const Todos = Module.make(App, [todos])
|
|
546
|
+
|
|
547
|
+
Module.validate(Todos) // []: one owner per path, every name declared
|
|
548
|
+
Graph.validate(Todos)
|
|
549
|
+
// [{ rule: 'law-unwitnessed', message: 'durable:Added writes todos, which sync:todos.capped reads, …' }]
|
|
550
|
+
|
|
551
|
+
const judged = Evidence.runtimeOnly({
|
|
552
|
+
transition: 'durable:Added',
|
|
553
|
+
law: 'sync:todos.capped',
|
|
554
|
+
why: 'the journal judges every append, and refuses one past the cap',
|
|
555
|
+
})
|
|
556
|
+
Graph.validate(Todos, { evidence: [judged] }) // []
|
|
557
|
+
Graph.breakersOf(Graph.of(Todos, { evidence: [judged] }), 'sync:todos.capped')
|
|
558
|
+
// [{ transition: 'durable:Added', paths: [['todos']], evidence: [judged] }]
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
The rules over the graph:
|
|
562
|
+
|
|
563
|
+
| Rule | Reported when |
|
|
564
|
+
| --- | --- |
|
|
565
|
+
| `law-unwitnessed` | A transition writes a path a law reads (one within the other), and no evidence joins them. A pair sharing no path is never reported, but a law over a row's change (one reading `before`) reads the whole row, since a write leaving its members alone can still break it. |
|
|
566
|
+
| `evidence-unmatched` | A record was issued by no producer (typed by hand, or a copy of one), or names a transition or law no contract declares, or a pair the graph does not join: a write and a law of two Entities, or a Message and a law over Model paths that do not overlap (two documents'). |
|
|
567
|
+
| `level-declared-twice` | Two closed Surfaces observe the same paths and list the same Messages. |
|
|
568
|
+
| `transition-declared-twice` | Two contracts declare a write of one name (`write:Sell` in two Remote domains): the graph and evidence name a write by its name, so neither can tell them apart. |
|
|
569
|
+
|
|
570
|
+
So a durable Message added to a document, or a write added to a domain, is
|
|
571
|
+
reported until a walk or a scenario draws it, or a line says why only
|
|
572
|
+
production refuses it. `Graph.toMarkdown` takes the same options and writes a
|
|
573
|
+
Laws section, to set beside `Module.toMarkdown`'s: each law, each transition
|
|
574
|
+
that can break it, its evidence, then `Graph.validate`'s findings.
|
|
575
|
+
`Graph.toMermaid` draws the same as a flowchart of its own. The graph holds no transition for a local Message: what
|
|
576
|
+
`modifyFields` writes is known only at run time, so a law over the local Model
|
|
577
|
+
has no `law-unwitnessed` yet, though a walk over it still runs.
|
|
578
|
+
`examples/writes` keeps its table in `LAWS.md`.
|
|
579
|
+
|
|
392
580
|
## Diagnostics
|
|
393
581
|
|
|
394
582
|
`Diagnostics` is the one channel every Foldkit Plus package reports into what
|
|
@@ -470,6 +658,10 @@ Submodel = state-machine ownership boundary
|
|
|
470
658
|
They compose; none replaces the others. Each line below changes
|
|
471
659
|
or reads the same field, `todos` (`restoredTodos` is an already-decoded value):
|
|
472
660
|
|
|
661
|
+
<!-- docs-check standalone use todoApp
|
|
662
|
+
const App = Surface.application({ Model, Message }).runnable({ initial, update })
|
|
663
|
+
-->
|
|
664
|
+
|
|
473
665
|
```ts
|
|
474
666
|
import { modifyFields } from 'foldkit/struct'
|
|
475
667
|
|
|
@@ -651,6 +843,13 @@ that may observe across those runtime boundaries without creating another one.
|
|
|
651
843
|
interpreter metadata (`Metadata.key`).
|
|
652
844
|
- Application scopes (`Surface.application`) and their identity token.
|
|
653
845
|
- Typed Message subsets (`MessageSet.make`, `MessageSet.union`).
|
|
846
|
+
- `Closure.reads`: whether a projection after a Message depends on the rest of the Model.
|
|
847
|
+
- `Closure.violations`: the closed Surfaces a step broke, as `ClosureViolation`s; `Surface.make`'s and `App.surface`'s `closed`.
|
|
848
|
+
- The law half of the contract graph: `Contract.laws`, and `Graph`: `Graph.of`,
|
|
849
|
+
`Graph.validate` (`law-unwitnessed`, `evidence-unmatched`,
|
|
850
|
+
`level-declared-twice`, `transition-declared-twice`), `Graph.breakersOf`,
|
|
851
|
+
`Graph.toMarkdown` and `Graph.toMermaid`. It owns the question, not the answers: each contract
|
|
852
|
+
owns its declared laws, and the producers of `Evidence` own its records.
|
|
654
853
|
- Actions (`Action.define`, `Action.run`): a named capability ending in a Message.
|
|
655
854
|
- Named Surfaces and their renderer binding.
|
|
656
855
|
- The `Diagnostics` channel and its default reporter; each package owns its own
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import { Data, Schema } from "effect";
|
|
2
|
+
import { DependencyTree, Projection } from "./index.js";
|
|
3
|
+
/** A read-only `Projection` or a `WritableProjection`: `Closure` needs only the codec, the paths and the read. */
|
|
4
|
+
export type ClosureProjection<Root, Value> = {
|
|
5
|
+
readonly Model: Schema.Schema<Value>;
|
|
6
|
+
readonly dependencies: DependencyTree;
|
|
7
|
+
readonly read: (root: Root) => Value;
|
|
8
|
+
} | {
|
|
9
|
+
readonly schema: Schema.Schema<Value>;
|
|
10
|
+
readonly dependencies: DependencyTree;
|
|
11
|
+
readonly get: (root: Root) => Value;
|
|
12
|
+
};
|
|
13
|
+
/**
|
|
14
|
+
* The top-level Model fields outside `projection` that its value after `message` depends on;
|
|
15
|
+
* empty when the projection is closed for this step. `update` runs on `model` and on `model`
|
|
16
|
+
* with those fields reset to `app.initial`, and the two projections are compared with the
|
|
17
|
+
* projection's codec. Only a field that differs from `initial` can be named, and a field that
|
|
18
|
+
* holds the projection's own paths (even in part) is never one.
|
|
19
|
+
*
|
|
20
|
+
* It runs `update` again and so does what `update` does: no Command it returns is run.
|
|
21
|
+
*/
|
|
22
|
+
declare const reads: <Root, Value, Message>(app: {
|
|
23
|
+
readonly initial: Root;
|
|
24
|
+
readonly update: (model: Root, message: Message) => {
|
|
25
|
+
readonly model: Root;
|
|
26
|
+
};
|
|
27
|
+
}, projection: ClosureProjection<Root, Value>, model: Root, message: Message) => ReadonlyArray<string>;
|
|
28
|
+
/**
|
|
29
|
+
* A closed Surface a step broke: `Reads` names the fields outside it that a Message in its
|
|
30
|
+
* set read, `Outside` says a Message outside its set moved it.
|
|
31
|
+
*/
|
|
32
|
+
export type ClosureViolation = Data.TaggedEnum<{
|
|
33
|
+
Reads: {
|
|
34
|
+
readonly surface: string;
|
|
35
|
+
readonly fields: ReadonlyArray<string>;
|
|
36
|
+
};
|
|
37
|
+
Outside: {
|
|
38
|
+
readonly surface: string;
|
|
39
|
+
};
|
|
40
|
+
}>;
|
|
41
|
+
export declare const ClosureViolation: Data.TaggedEnum.Constructor<{
|
|
42
|
+
readonly _tag: "Outside";
|
|
43
|
+
readonly surface: string;
|
|
44
|
+
} | {
|
|
45
|
+
readonly _tag: "Reads";
|
|
46
|
+
readonly surface: string;
|
|
47
|
+
readonly fields: ReadonlyArray<string>;
|
|
48
|
+
}>;
|
|
49
|
+
/**
|
|
50
|
+
* A step check over the Surfaces declared `closed: true`, for a walk. For a Message in a
|
|
51
|
+
* Surface's `messages`, `Closure.reads` must be empty; for any other Message the projection
|
|
52
|
+
* must not change from `before` to `after`. A Surface not declared closed is never tested.
|
|
53
|
+
* A Surface with params is refused here: it has no one projection to test.
|
|
54
|
+
*/
|
|
55
|
+
declare const violations: <Root, Message>(app: {
|
|
56
|
+
readonly initial: Root;
|
|
57
|
+
readonly update: (model: Root, message: Message) => {
|
|
58
|
+
readonly model: Root;
|
|
59
|
+
};
|
|
60
|
+
}, surfaces: ReadonlyArray<{
|
|
61
|
+
readonly name: string;
|
|
62
|
+
readonly closed: boolean;
|
|
63
|
+
readonly messages: readonly unknown[];
|
|
64
|
+
/** Read only to refuse a Surface with params. */
|
|
65
|
+
readonly Params: unknown;
|
|
66
|
+
/** `never`: whatever params a Surface takes, it is only ever called with none. */
|
|
67
|
+
readonly projection: (params: never) => Projection<Root, unknown>;
|
|
68
|
+
}>) => ((before: Root, message: Message, after: Root) => ReadonlyArray<ClosureViolation>);
|
|
69
|
+
/** Checks that a projection is closed under `update`: `Closure.reads` names what it still depends on. */
|
|
70
|
+
export declare const Closure: {
|
|
71
|
+
reads: typeof reads;
|
|
72
|
+
violations: typeof violations;
|
|
73
|
+
};
|
|
74
|
+
export {};
|
|
75
|
+
//# sourceMappingURL=closure.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"closure.d.ts","names":[],"sources":["../src/closure.ts"],"mappings":";;;YAKY,kBAAkB,MAAM;WAErB,OAAO,OAAO,OAAO;WACrB,cAAc;WACd,OAAO,MAAM,SAAS;;WAGtB,QAAQ,OAAO,OAAO;WACtB,cAAc;WACd,MAAM,MAAM,SAAS;;;;;;;;;;;cAwC9B,QAAS,MAAM,OAAO,SAAO;WAEtB,SAAS;WACT,SAAS,OAAO,MAAM,SAAS;aAAuB,OAAO;;GACvE,YACW,kBAAkB,MAAM,QAAM,OACnC,MAAI,SACF,YACR;;;;;YA8BS,mBAAmB,KAAK;EAClC;aAAkB;aAA0B,QAAQ;;EACpD;aAAoB;;;qBAET,kBAAgB,KAAA,WAAA;;WAFE;;;WADF;WAAyB,QAAA;;;;;;;;cAWhD,aAAc,MAAM,SAAO;WAEpB,SAAS;WACT,SAAS,OAAO,MAAM,SAAS;aAAuB,OAAO;;GACvE,UACS;WACC;WACA;WACA;;WAEA;;WAEA,aAAa,kBAAkB,WAAW;SAElD,QAAQ,MAAM,SAAS,SAAS,OAAO,SAAS,cAAc;;qBA2BtD"}
|
package/dist/closure.js
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import { Data, Schema } from "effect";
|
|
2
|
+
import { hasTagIn, messageTags } from "./messageTags.js";
|
|
3
|
+
// src/closure.ts
|
|
4
|
+
const ownedBy = /* @__PURE__ */ new WeakMap();
|
|
5
|
+
const equivalenceOf = /* @__PURE__ */ new WeakMap();
|
|
6
|
+
const owned = (dependencies) => {
|
|
7
|
+
let fields = ownedBy.get(dependencies);
|
|
8
|
+
if (fields === void 0) {
|
|
9
|
+
fields = new Set(dependencies.map((path) => path[0]).filter((key) => key !== void 0));
|
|
10
|
+
ownedBy.set(dependencies, fields);
|
|
11
|
+
}
|
|
12
|
+
return fields;
|
|
13
|
+
};
|
|
14
|
+
const partsOf = (projection) => "schema" in projection ? {
|
|
15
|
+
codec: projection.schema,
|
|
16
|
+
read: projection.get
|
|
17
|
+
} : {
|
|
18
|
+
codec: projection.Model,
|
|
19
|
+
read: projection.read
|
|
20
|
+
};
|
|
21
|
+
const equivalence = (codec) => {
|
|
22
|
+
let equal = equivalenceOf.get(codec);
|
|
23
|
+
if (equal === void 0) {
|
|
24
|
+
equal = Schema.toEquivalence(codec);
|
|
25
|
+
equivalenceOf.set(codec, equal);
|
|
26
|
+
}
|
|
27
|
+
return equal;
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* The top-level Model fields outside `projection` that its value after `message` depends on;
|
|
31
|
+
* empty when the projection is closed for this step. `update` runs on `model` and on `model`
|
|
32
|
+
* with those fields reset to `app.initial`, and the two projections are compared with the
|
|
33
|
+
* projection's codec. Only a field that differs from `initial` can be named, and a field that
|
|
34
|
+
* holds the projection's own paths (even in part) is never one.
|
|
35
|
+
*
|
|
36
|
+
* It runs `update` again and so does what `update` does: no Command it returns is run.
|
|
37
|
+
*/
|
|
38
|
+
const reads = (app, projection, model, message) => {
|
|
39
|
+
const live = model;
|
|
40
|
+
const baseline = app.initial;
|
|
41
|
+
const own = owned(projection.dependencies);
|
|
42
|
+
const outside = Object.keys(live).filter((key) => !own.has(key) && !Object.is(live[key], baseline[key]));
|
|
43
|
+
if (outside.length === 0) return [];
|
|
44
|
+
const { codec, read } = partsOf(projection);
|
|
45
|
+
const equal = equivalence(codec);
|
|
46
|
+
const after = read(app.update(model, message).model);
|
|
47
|
+
const differs = (fields) => {
|
|
48
|
+
const reset = { ...live };
|
|
49
|
+
for (const key of fields) reset[key] = baseline[key];
|
|
50
|
+
const other = read(app.update(reset, message).model);
|
|
51
|
+
return !Object.is(after, other) && !equal(after, other);
|
|
52
|
+
};
|
|
53
|
+
if (!differs(outside)) return [];
|
|
54
|
+
if (outside.length === 1) return outside;
|
|
55
|
+
const named = outside.filter((key) => differs([key]));
|
|
56
|
+
return named.length === 0 ? outside : named;
|
|
57
|
+
};
|
|
58
|
+
const ClosureViolation = Data.taggedEnum();
|
|
59
|
+
/**
|
|
60
|
+
* A step check over the Surfaces declared `closed: true`, for a walk. For a Message in a
|
|
61
|
+
* Surface's `messages`, `Closure.reads` must be empty; for any other Message the projection
|
|
62
|
+
* must not change from `before` to `after`. A Surface not declared closed is never tested.
|
|
63
|
+
* A Surface with params is refused here: it has no one projection to test.
|
|
64
|
+
*/
|
|
65
|
+
const violations = (app, surfaces) => {
|
|
66
|
+
const closed = surfaces.filter((surface) => surface.closed).map((surface) => {
|
|
67
|
+
if (surface.Params !== void 0) throw new Error(`Closure.violations: Surface "${surface.name}" declares params`);
|
|
68
|
+
const projection = surface.projection(void 0);
|
|
69
|
+
return {
|
|
70
|
+
name: surface.name,
|
|
71
|
+
projection,
|
|
72
|
+
tags: new Set(messageTags(surface))
|
|
73
|
+
};
|
|
74
|
+
});
|
|
75
|
+
return (before, message, after) => closed.flatMap(({ name, projection, tags }) => {
|
|
76
|
+
if (hasTagIn(tags, message)) {
|
|
77
|
+
const fields = reads(app, projection, before, message);
|
|
78
|
+
return fields.length === 0 ? [] : [ClosureViolation.Reads({
|
|
79
|
+
surface: name,
|
|
80
|
+
fields
|
|
81
|
+
})];
|
|
82
|
+
}
|
|
83
|
+
const { codec, read } = partsOf(projection);
|
|
84
|
+
const [was, now] = [read(before), read(after)];
|
|
85
|
+
return Object.is(was, now) || equivalence(codec)(was, now) ? [] : [ClosureViolation.Outside({ surface: name })];
|
|
86
|
+
});
|
|
87
|
+
};
|
|
88
|
+
/** Checks that a projection is closed under `update`: `Closure.reads` names what it still depends on. */
|
|
89
|
+
const Closure = {
|
|
90
|
+
reads,
|
|
91
|
+
violations
|
|
92
|
+
};
|
|
93
|
+
export { Closure, ClosureViolation };
|
|
94
|
+
|
|
95
|
+
//# sourceMappingURL=closure.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"closure.js","names":[],"sources":["../src/closure.ts"],"sourcesContent":["import { Data, Schema } from 'effect'\nimport type { DependencyTree, Projection } from './index.js'\nimport { hasTagIn, messageTags } from './messageTags.js'\n\n/** A read-only `Projection` or a `WritableProjection`: `Closure` needs only the codec, the paths and the read. */\nexport type ClosureProjection<Root, Value> =\n | {\n readonly Model: Schema.Schema<Value>\n readonly dependencies: DependencyTree\n readonly read: (root: Root) => Value\n }\n | {\n readonly schema: Schema.Schema<Value>\n readonly dependencies: DependencyTree\n readonly get: (root: Root) => Value\n }\n\nconst ownedBy = new WeakMap<DependencyTree, ReadonlySet<string>>()\nconst equivalenceOf = new WeakMap<object, (a: never, b: never) => boolean>()\n\nconst owned = (dependencies: DependencyTree): ReadonlySet<string> => {\n let fields = ownedBy.get(dependencies)\n if (fields === undefined) {\n fields = new Set(dependencies.map(path => path[0]).filter(key => key !== undefined))\n ownedBy.set(dependencies, fields)\n }\n return fields\n}\n\nconst partsOf = <Root, Value>(\n projection: ClosureProjection<Root, Value>,\n): { readonly codec: Schema.Schema<Value>; readonly read: (root: Root) => Value } =>\n 'schema' in projection\n ? { codec: projection.schema, read: projection.get }\n : { codec: projection.Model, read: projection.read }\n\nconst equivalence = <Value>(codec: Schema.Schema<Value>): ((a: Value, b: Value) => boolean) => {\n let equal = equivalenceOf.get(codec)\n if (equal === undefined) {\n equal = Schema.toEquivalence(codec) as never\n equivalenceOf.set(codec, equal)\n }\n return equal as (a: Value, b: Value) => boolean\n}\n\n/**\n * The top-level Model fields outside `projection` that its value after `message` depends on;\n * empty when the projection is closed for this step. `update` runs on `model` and on `model`\n * with those fields reset to `app.initial`, and the two projections are compared with the\n * projection's codec. Only a field that differs from `initial` can be named, and a field that\n * holds the projection's own paths (even in part) is never one.\n *\n * It runs `update` again and so does what `update` does: no Command it returns is run.\n */\nconst reads = <Root, Value, Message>(\n app: {\n readonly initial: Root\n readonly update: (model: Root, message: Message) => { readonly model: Root }\n },\n projection: ClosureProjection<Root, Value>,\n model: Root,\n message: Message,\n): ReadonlyArray<string> => {\n const live = model as Readonly<Record<string, unknown>>\n const baseline = app.initial as Readonly<Record<string, unknown>>\n const own = owned(projection.dependencies)\n const outside = Object.keys(live).filter(\n key => !own.has(key) && !Object.is(live[key], baseline[key]),\n )\n if (outside.length === 0) return []\n\n const { codec, read } = partsOf(projection)\n const equal = equivalence(codec)\n const after = read(app.update(model, message).model)\n const differs = (fields: ReadonlyArray<string>): boolean => {\n const reset = { ...live }\n for (const key of fields) reset[key] = baseline[key]\n const other = read(app.update(reset as Root, message).model)\n return !Object.is(after, other) && !equal(after, other)\n }\n\n if (!differs(outside)) return []\n if (outside.length === 1) return outside\n const named = outside.filter(key => differs([key]))\n // When each of several fields is enough alone, resetting one changes nothing: all are named.\n return named.length === 0 ? outside : named\n}\n\n/**\n * A closed Surface a step broke: `Reads` names the fields outside it that a Message in its\n * set read, `Outside` says a Message outside its set moved it.\n */\nexport type ClosureViolation = Data.TaggedEnum<{\n Reads: { readonly surface: string; readonly fields: ReadonlyArray<string> }\n Outside: { readonly surface: string }\n}>\nexport const ClosureViolation = Data.taggedEnum<ClosureViolation>()\n\n/**\n * A step check over the Surfaces declared `closed: true`, for a walk. For a Message in a\n * Surface's `messages`, `Closure.reads` must be empty; for any other Message the projection\n * must not change from `before` to `after`. A Surface not declared closed is never tested.\n * A Surface with params is refused here: it has no one projection to test.\n */\nconst violations = <Root, Message>(\n app: {\n readonly initial: Root\n readonly update: (model: Root, message: Message) => { readonly model: Root }\n },\n surfaces: ReadonlyArray<{\n readonly name: string\n readonly closed: boolean\n readonly messages: readonly unknown[]\n /** Read only to refuse a Surface with params. */\n readonly Params: unknown\n /** `never`: whatever params a Surface takes, it is only ever called with none. */\n readonly projection: (params: never) => Projection<Root, unknown>\n }>,\n): ((before: Root, message: Message, after: Root) => ReadonlyArray<ClosureViolation>) => {\n const closed = surfaces\n .filter(surface => surface.closed)\n .map(surface => {\n if (surface.Params !== undefined) {\n throw new Error(`Closure.violations: Surface \"${surface.name}\" declares params`)\n }\n // No params schema, checked above: the Surface takes none.\n const projection: ClosureProjection<Root, unknown> = surface.projection(undefined as never)\n return { name: surface.name, projection, tags: new Set(messageTags(surface)) }\n })\n return (before, message, after) =>\n closed.flatMap(({ name, projection, tags }): ReadonlyArray<ClosureViolation> => {\n // tag-check: open, `Message` is the application's own, which this cannot name\n if (hasTagIn(tags, message)) {\n const fields = reads(app, projection, before, message)\n return fields.length === 0 ? [] : [ClosureViolation.Reads({ surface: name, fields })]\n }\n const { codec, read } = partsOf(projection)\n const [was, now] = [read(before), read(after)]\n return Object.is(was, now) || equivalence(codec)(was, now)\n ? []\n : [ClosureViolation.Outside({ surface: name })]\n })\n}\n\n/** Checks that a projection is closed under `update`: `Closure.reads` names what it still depends on. */\nexport const Closure = { reads, violations }\n"],"mappings":"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"}
|