foldkit-entity 0.17.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.
Files changed (62) hide show
  1. package/README.md +466 -227
  2. package/dist/conformance/index.d.ts.map +1 -1
  3. package/dist/conformance/index.js +10 -4
  4. package/dist/conformance/index.js.map +1 -1
  5. package/dist/descriptor.d.ts +5 -1
  6. package/dist/descriptor.d.ts.map +1 -1
  7. package/dist/descriptor.js +6 -2
  8. package/dist/descriptor.js.map +1 -1
  9. package/dist/entity.d.ts +3 -2
  10. package/dist/entity.d.ts.map +1 -1
  11. package/dist/entity.js +5 -3
  12. package/dist/entity.js.map +1 -1
  13. package/dist/enumerate.d.ts +44 -0
  14. package/dist/enumerate.d.ts.map +1 -0
  15. package/dist/enumerate.js +128 -0
  16. package/dist/enumerate.js.map +1 -0
  17. package/dist/evaluate.d.ts +11 -5
  18. package/dist/evaluate.d.ts.map +1 -1
  19. package/dist/evaluate.js +27 -6
  20. package/dist/evaluate.js.map +1 -1
  21. package/dist/expr.d.ts +8 -2
  22. package/dist/expr.d.ts.map +1 -1
  23. package/dist/expr.js +19 -10
  24. package/dist/expr.js.map +1 -1
  25. package/dist/footprint.d.ts +120 -0
  26. package/dist/footprint.d.ts.map +1 -0
  27. package/dist/footprint.js +41 -0
  28. package/dist/footprint.js.map +1 -0
  29. package/dist/index.d.ts +8 -3
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +6 -3
  32. package/dist/index.js.map +1 -1
  33. package/dist/invariant.d.ts +41 -11
  34. package/dist/invariant.d.ts.map +1 -1
  35. package/dist/invariant.js +83 -38
  36. package/dist/invariant.js.map +1 -1
  37. package/dist/lawIds.d.ts +15 -0
  38. package/dist/lawIds.d.ts.map +1 -0
  39. package/dist/lawIds.js +13 -0
  40. package/dist/lawIds.js.map +1 -0
  41. package/dist/laws.d.ts +308 -0
  42. package/dist/laws.d.ts.map +1 -0
  43. package/dist/laws.js +566 -0
  44. package/dist/laws.js.map +1 -0
  45. package/dist/operators.d.ts +1 -1
  46. package/dist/refine.d.ts +64 -0
  47. package/dist/refine.d.ts.map +1 -0
  48. package/dist/refine.js +104 -0
  49. package/dist/refine.js.map +1 -0
  50. package/dist/rows.d.ts +15 -0
  51. package/dist/rows.d.ts.map +1 -0
  52. package/dist/rows.js +23 -0
  53. package/dist/rows.js.map +1 -0
  54. package/dist/uncollated.d.ts +10 -0
  55. package/dist/uncollated.d.ts.map +1 -0
  56. package/dist/uncollated.js +18 -0
  57. package/dist/uncollated.js.map +1 -0
  58. package/dist/write.d.ts +64 -6
  59. package/dist/write.d.ts.map +1 -1
  60. package/dist/write.js +88 -12
  61. package/dist/write.js.map +1 -1
  62. package/package.json +3 -3
package/dist/laws.d.ts ADDED
@@ -0,0 +1,308 @@
1
+ import { Data, Option } from "effect";
2
+ import { Evidence } from "foldkit-metadata";
3
+ import { AnyEntity } from "./index.js";
4
+ import { MemoryOperators as MemoryOperators$1 } from "./operators.js";
5
+ import { Footprint } from "./footprint.js";
6
+ import { lawId, transitionId } from "./lawIds.js";
7
+ import { AnyWrite } from "./write.js";
8
+ import { Step } from "./enumerate.js";
9
+ /** A declared write, as `Mutation.write` returns one. */
10
+ export interface WriteEntry {
11
+ readonly name: string;
12
+ readonly write: AnyWrite;
13
+ }
14
+ /** A transition that is no declared write: what it touches is the author's word, or unknown. */
15
+ export interface FootprintEntry<E extends AnyEntity = AnyEntity> {
16
+ readonly name: string;
17
+ readonly entity: E;
18
+ readonly footprint: Footprint;
19
+ }
20
+ export type LawEntry = WriteEntry | FootprintEntry;
21
+ /** Refuses, at the entry, a declared footprint over another Entity than the entry's. */
22
+ type Checked<X> = X extends {
23
+ readonly entity: infer E extends AnyEntity;
24
+ readonly footprint: infer F;
25
+ } ? F extends {
26
+ readonly _tag: 'Declared';
27
+ readonly entity: infer Name;
28
+ } ? Name extends E['name'] ? X : {
29
+ readonly entity: E;
30
+ readonly footprint: Footprint & {
31
+ readonly entity: E['name'];
32
+ };
33
+ } : X : X;
34
+ /** How one transition stands against one invariant. */
35
+ export type LawVerdict = Data.TaggedEnum<{
36
+ /**
37
+ * It cannot break it. `by`: it writes nothing the (state) invariant reads,
38
+ * its author says so, every row it can start from was enumerated, or there
39
+ * is no row to judge (a create and a transition, a delete).
40
+ */
41
+ Kept: {
42
+ readonly by: 'disjointness' | 'declared' | 'enumeration' | 'create' | 'delete';
43
+ readonly rows: number;
44
+ };
45
+ /** These steps leave a row that breaks it. */
46
+ Refused: {
47
+ readonly steps: ReadonlyArray<Step>;
48
+ };
49
+ /** Nothing here can say, and why. */
50
+ Undecided: {
51
+ readonly reason: string;
52
+ };
53
+ }>;
54
+ export declare const LawVerdict: Data.TaggedEnum.Constructor<{
55
+ readonly _tag: "Kept";
56
+ readonly by: 'disjointness' | 'declared' | 'enumeration' | 'create' | 'delete';
57
+ readonly rows: number;
58
+ } | {
59
+ readonly _tag: "Refused";
60
+ readonly steps: ReadonlyArray<Step>;
61
+ } | {
62
+ readonly _tag: "Undecided";
63
+ readonly reason: string;
64
+ }>;
65
+ /** One transition against one invariant of its Entity. */
66
+ export interface LawPair {
67
+ readonly write: string;
68
+ readonly entity: string;
69
+ readonly invariant: string;
70
+ /** The members the invariant reads, before and after, by field key. */
71
+ readonly reads: ReadonlyArray<string>;
72
+ /**
73
+ * True for a transition invariant, which reads the row before: a write that
74
+ * leaves every member it reads alone can still break it, so the graph reads
75
+ * it as reading the whole row.
76
+ */
77
+ readonly readsBefore: boolean;
78
+ readonly footprint: Footprint;
79
+ readonly verdict: LawVerdict;
80
+ /** True for a write's own `ensures`: a law of that write alone, held where it commits. */
81
+ readonly postcondition: boolean;
82
+ /**
83
+ * An `Enumerated` record for a pair the check kept by reading the
84
+ * declarations; none for an author's word (`declared`), a refusal, or an
85
+ * undecided pair.
86
+ */
87
+ readonly evidence: Option.Option<Evidence>;
88
+ }
89
+ /** A write taking a row from one state of its Entity to another. */
90
+ export interface Arrow {
91
+ readonly entity: string;
92
+ readonly write: string;
93
+ readonly from: string;
94
+ readonly to: string;
95
+ }
96
+ /** What the check says of an arrow or a state. A report, never a fault. */
97
+ export type Finding = Data.TaggedEnum<{
98
+ /** The arrow into the state its write declared it `becomes`. */
99
+ Holds: Arrow;
100
+ /** A write with no such `becomes` makes the arrow. */
101
+ Undeclared: Arrow;
102
+ /**
103
+ * The write's `becomes` enumeration could not decide, kept where it commits
104
+ * by its postcondition: every row it lands is in `to`, from whatever state.
105
+ */
106
+ Enforced: {
107
+ readonly entity: string;
108
+ readonly write: string;
109
+ readonly to: string;
110
+ };
111
+ /** Every row the arrow leaves breaks `invariant`, which refuses the write there. */
112
+ Refused: Arrow & {
113
+ readonly invariant: string;
114
+ };
115
+ /** No write leaves a row in the state. */
116
+ Unreached: {
117
+ readonly entity: string;
118
+ readonly state: string;
119
+ };
120
+ /** No write starts from it. */
121
+ Terminal: {
122
+ readonly entity: string;
123
+ readonly state: string;
124
+ };
125
+ }>;
126
+ export declare const Finding: Data.TaggedEnum.Constructor<{
127
+ readonly _tag: "Enforced";
128
+ readonly entity: string;
129
+ readonly write: string;
130
+ readonly to: string;
131
+ } | {
132
+ readonly _tag: "Holds";
133
+ readonly entity: string;
134
+ readonly write: string;
135
+ readonly from: string;
136
+ readonly to: string;
137
+ } | {
138
+ readonly _tag: "Refused";
139
+ readonly entity: string;
140
+ readonly write: string;
141
+ readonly from: string;
142
+ readonly to: string;
143
+ readonly invariant: string;
144
+ } | {
145
+ readonly _tag: "Terminal";
146
+ readonly entity: string;
147
+ readonly state: string;
148
+ } | {
149
+ readonly _tag: "Undeclared";
150
+ readonly entity: string;
151
+ readonly write: string;
152
+ readonly from: string;
153
+ readonly to: string;
154
+ } | {
155
+ readonly _tag: "Unreached";
156
+ readonly entity: string;
157
+ readonly state: string;
158
+ }>;
159
+ export interface LawReport {
160
+ readonly pairs: ReadonlyArray<LawPair>;
161
+ readonly arrows: ReadonlyArray<Arrow>;
162
+ /** Each Entity's local states, by name. */
163
+ readonly states: ReadonlyArray<{
164
+ readonly entity: string;
165
+ readonly names: ReadonlyArray<string>;
166
+ }>;
167
+ readonly findings: ReadonlyArray<Finding>;
168
+ }
169
+ /**
170
+ * Checks each transition against each invariant of its Entity, and the arrows
171
+ * its writes make between the Entity's declared states. An entry is a
172
+ * declared write (`{ name, write }`, as `Mutation.write` returns), or a
173
+ * transition known by its footprint (`{ name, entity, footprint }`). Pure, and
174
+ * what it finds is a report, never a fault; it throws only for two entries of
175
+ * one name, which its report could not tell apart.
176
+ */
177
+ declare const check: <const W extends ReadonlyArray<LawEntry>>(options: {
178
+ readonly writes: W & { readonly [K in keyof W]: Checked<W[K]>; };
179
+ readonly operators?: MemoryOperators$1 | undefined;
180
+ }) => LawReport;
181
+ /** The report as text: each Entity's states and arrows, then each pair. */
182
+ declare const show: (report: LawReport) => string;
183
+ /** A node of the law half of `foldkit-surface`'s graph, as plain data. */
184
+ export type LawNode = Data.TaggedEnum<{
185
+ /** A member of an Entity (`['Product', 'reserved']`), or its whole row (`['Product']`), which a transition invariant reads. */
186
+ Path: {
187
+ readonly space: 'entity';
188
+ readonly path: ReadonlyArray<string>;
189
+ };
190
+ /** A transition over one Entity's rows: a delete, which writes no member, is still of its Entity. */
191
+ Transition: {
192
+ readonly id: string;
193
+ readonly kind: 'write';
194
+ readonly entity: string;
195
+ };
196
+ Law: {
197
+ readonly id: string;
198
+ };
199
+ State: {
200
+ readonly entity: string;
201
+ readonly name: string;
202
+ };
203
+ }>;
204
+ export declare const LawNode: Data.TaggedEnum.Constructor<{
205
+ readonly _tag: "Law";
206
+ readonly id: string;
207
+ } | {
208
+ readonly _tag: "Path";
209
+ readonly space: 'entity';
210
+ readonly path: ReadonlyArray<string>;
211
+ } | {
212
+ readonly _tag: "State";
213
+ readonly entity: string;
214
+ readonly name: string;
215
+ } | {
216
+ readonly _tag: "Transition";
217
+ readonly id: string;
218
+ readonly kind: 'write';
219
+ readonly entity: string;
220
+ }>;
221
+ /** An edge of the law half of the graph, naming its nodes by id or path, each path an Entity member. */
222
+ export type LawEdge = Data.TaggedEnum<{
223
+ Reads: {
224
+ readonly law: string;
225
+ readonly space: 'entity';
226
+ readonly path: ReadonlyArray<string>;
227
+ };
228
+ Writes: {
229
+ readonly transition: string;
230
+ readonly space: 'entity';
231
+ readonly path: ReadonlyArray<string>;
232
+ };
233
+ From: {
234
+ readonly transition: string;
235
+ readonly entity: string;
236
+ readonly state: string;
237
+ };
238
+ To: {
239
+ readonly transition: string;
240
+ readonly entity: string;
241
+ readonly state: string;
242
+ };
243
+ Keeps: {
244
+ readonly transition: string;
245
+ readonly law: string;
246
+ readonly evidence: Evidence;
247
+ };
248
+ }>;
249
+ export declare const LawEdge: Data.TaggedEnum.Constructor<{
250
+ readonly _tag: "From";
251
+ readonly transition: string;
252
+ readonly entity: string;
253
+ readonly state: string;
254
+ } | {
255
+ readonly _tag: "Keeps";
256
+ readonly transition: string;
257
+ readonly law: string;
258
+ readonly evidence: Evidence;
259
+ } | {
260
+ readonly _tag: "Reads";
261
+ readonly law: string;
262
+ readonly space: 'entity';
263
+ readonly path: ReadonlyArray<string>;
264
+ } | {
265
+ readonly _tag: "To";
266
+ readonly transition: string;
267
+ readonly entity: string;
268
+ readonly state: string;
269
+ } | {
270
+ readonly _tag: "Writes";
271
+ readonly transition: string;
272
+ readonly space: 'entity';
273
+ readonly path: ReadonlyArray<string>;
274
+ }>;
275
+ export interface LawFacts {
276
+ readonly nodes: ReadonlyArray<LawNode>;
277
+ readonly edges: ReadonlyArray<LawEdge>;
278
+ }
279
+ /**
280
+ * The report as graph facts: a Law per invariant, a Transition per write in
281
+ * a pair or an arrow (one judged against nothing and moving no state has no
282
+ * law to keep), a State per local state, what each law reads and each transition writes,
283
+ * each arrow's `from` and `to`, and a `keeps` edge per transition and law whose every
284
+ * pair carries an `Enumerated` record.
285
+ * A write's own `ensures` is no law of its Entity and is left out. An
286
+ * `Unknown` footprint writes every member, so it has a `writes` edge to each
287
+ * member a law of its Entity reads: every edge a rule of the graph can ask of.
288
+ */
289
+ declare const facts: (report: LawReport) => LawFacts;
290
+ /**
291
+ * Declared transitions as graph facts, read off the declarations alone: a
292
+ * transition per entry and the members it writes (an `Unknown` footprint
293
+ * every field), a law per invariant of its Entity and the members it reads,
294
+ * the Entity's states, and a write's `from` and `becomes`. Nothing is
295
+ * enumerated, since whether a transition keeps a law is evidence. What
296
+ * `foldkit-surface`'s `Graph.of` derives a contract's `laws.entities`
297
+ * with; a function by name, so that path does not carry `Laws.check`.
298
+ */
299
+ export declare const lawFactsOf: (entries: ReadonlyArray<LawEntry>) => LawFacts;
300
+ export declare const Laws: {
301
+ check: typeof check;
302
+ show: typeof show;
303
+ facts: typeof facts;
304
+ transition: typeof transitionId;
305
+ law: typeof lawId;
306
+ };
307
+ export {};
308
+ //# sourceMappingURL=laws.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"laws.d.ts","names":["MemoryOperators"],"sources":["../src/laws.ts"],"mappings":";;;;;;;;;iBAsBiB;WACN;WACA,OAAO;;;iBAID,eAAe,UAAU,YAAY;WAC3C;WACA,QAAQ;WACR,WAAW;;YAGV,WAAW,aAAa;;KAG/B,QAAQ,KAAK;WACP,cAAc,UAAU;WACxB,iBAAiB;IAExB;WAAqB;WAA2B,cAAc;IAC5D,aAAa,YACX;WACW,QAAQ;WAAY,WAAW;aAAuB,QAAQ;;IAC3E,IACF;;YAGQ,aAAa,KAAK;;;;;;EAM5B;aACW;aACA;;;EAGX;aAAoB,OAAO,cAAc;;;EAEzC;aAAsB;;;qBAEX,YAAU,KAAA,WAAA;;WARN;WACE;;;WAGU,OAAA,cAAc;;;WAEX;;;iBAKf;WACN;WACA;WACA;;WAEA,OAAO;;;;;;WAMP;WACA,WAAW;WACX,SAAS;;WAET;;;;;;WAMA,UAAU,OAAO,OAAO;;;iBAIlB;WACN;WACA;WACA;WACA;;;YAIC,UAAU,KAAK;;EAEzB,OAAO;;EAEP,YAAY;;;;;EAKZ;aAAqB;aAAyB;aAAwB;;;EAEtE,SAAS;aAAmB;;;EAE5B;aAAsB;aAAyB;;;EAE/C;aAAqB;aAAyB;;;qBAEnC,SAAO,KAAA,WAAA;;WARW;WAAwB;WAAqB;;;WAhBzD;WACD;WACD;WACF;;;WAHI;WACD;WACD;WACF;WAe0B;;;WAIV;WAAwB;;;WAtBpC;WACD;WACD;WACF;;;WAiBiB;WAAwB;;iBAMvC;WACN,OAAO,cAAc;WACrB,QAAQ,cAAc;;WAEtB,QAAQ;aAAyB;aAAyB,OAAO;;WACjE,UAAU,cAAc;;;;;;;;;;cAkN7B,cAAe,UAAU,cAAc,WAAS;WAC3C,QAAQ,gBAAgB,WAAW,IAAI,QAAQ,EAAE;WACjD,YAAYA;MACnB;;cA8HE,OAAI,QAAY;;YAcV,UAAU,KAAK;;EAEzB;aAAiB;aAA0B,MAAM;;;EAEjD;aAAuB;aAAqB;aAAwB;;EACpE;aAAgB;;EAChB;aAAkB;aAAyB;;;qBAEhC,SAAO,KAAA,WAAA;;WAHE;;;WAHI;WAAyB,MAAA;;;WAIvB;WAAuB;;;WAFtB;WAAuB;WAA0B;;;YAOlE,UAAU,KAAK;EACzB;aAAkB;aAAsB;aAA0B,MAAM;;EACxE;aACW;aACA;aACA,MAAM;;EAEjB;aAAiB;aAA6B;aAAyB;;EACvE;aAAe;aAA6B;aAAyB;;EACrE;aAAkB;aAA6B;aAAsB,UAAU;;;qBAEpE,SAAO,KAAA,WAAA;;WAJW;WAAyB;WAAwB;;;WAEhD;WAAsB;WAA2B,UAAA;;;WARxD;WAAwB;WAAyB,MAAA;;;WAO7C;WAAyB;WAAwB;;;WALrD;WACL;WACD,MAAA;;iBAQF;WACN,OAAO,cAAc;WACrB,OAAO,cAAc;;;;;;;;;;;;cAa1B,QAAK,QAAY,cAAY;;;;;;;;;;qBA0FtB,aAAU,SAAa,cAAc,cAAY;qBAkCjD"}