@smthrs/plan 0.0.0-stage → 1.0.0-rc.4

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 (199) hide show
  1. package/CHANGELOG.md +183 -0
  2. package/LICENSE +21 -0
  3. package/README.md +228 -2
  4. package/dist/cjs/CachePolicy.d.ts +131 -0
  5. package/dist/cjs/CachePolicy.d.ts.map +1 -0
  6. package/dist/cjs/CachePolicy.js +50 -0
  7. package/dist/cjs/CachePolicy.js.map +7 -0
  8. package/dist/cjs/Effects.d.ts +240 -0
  9. package/dist/cjs/Effects.d.ts.map +1 -0
  10. package/dist/cjs/Effects.js +76 -0
  11. package/dist/cjs/Effects.js.map +7 -0
  12. package/dist/cjs/FileSet.d.ts +288 -0
  13. package/dist/cjs/FileSet.d.ts.map +1 -0
  14. package/dist/cjs/FileSet.js +191 -0
  15. package/dist/cjs/FileSet.js.map +7 -0
  16. package/dist/cjs/GraphBuildError.d.ts +122 -0
  17. package/dist/cjs/GraphBuildError.d.ts.map +1 -0
  18. package/dist/cjs/GraphBuildError.js +71 -0
  19. package/dist/cjs/GraphBuildError.js.map +7 -0
  20. package/dist/cjs/KeyMaterial.d.ts +102 -0
  21. package/dist/cjs/KeyMaterial.d.ts.map +1 -0
  22. package/dist/cjs/KeyMaterial.js +64 -0
  23. package/dist/cjs/KeyMaterial.js.map +7 -0
  24. package/dist/cjs/Node.d.ts +606 -0
  25. package/dist/cjs/Node.d.ts.map +1 -0
  26. package/dist/cjs/Node.js +207 -0
  27. package/dist/cjs/Node.js.map +7 -0
  28. package/dist/cjs/Placement.d.ts +117 -0
  29. package/dist/cjs/Placement.d.ts.map +1 -0
  30. package/dist/cjs/Placement.js +46 -0
  31. package/dist/cjs/Placement.js.map +7 -0
  32. package/dist/cjs/Plan.d.ts +440 -0
  33. package/dist/cjs/Plan.d.ts.map +1 -0
  34. package/dist/cjs/Plan.js +508 -0
  35. package/dist/cjs/Plan.js.map +7 -0
  36. package/dist/cjs/PlanDiff.d.ts +58 -0
  37. package/dist/cjs/PlanDiff.d.ts.map +1 -0
  38. package/dist/cjs/PlanDiff.js +124 -0
  39. package/dist/cjs/PlanDiff.js.map +7 -0
  40. package/dist/cjs/Planned.d.ts +121 -0
  41. package/dist/cjs/Planned.d.ts.map +1 -0
  42. package/dist/cjs/Planned.js +72 -0
  43. package/dist/cjs/Planned.js.map +7 -0
  44. package/dist/cjs/Repetition.d.ts +31 -0
  45. package/dist/cjs/Repetition.d.ts.map +1 -0
  46. package/dist/cjs/Repetition.js +36 -0
  47. package/dist/cjs/Repetition.js.map +7 -0
  48. package/dist/cjs/Scheduling.d.ts +89 -0
  49. package/dist/cjs/Scheduling.d.ts.map +1 -0
  50. package/dist/cjs/Scheduling.js +76 -0
  51. package/dist/cjs/Scheduling.js.map +7 -0
  52. package/dist/cjs/StepKey.d.ts +333 -0
  53. package/dist/cjs/StepKey.d.ts.map +1 -0
  54. package/dist/cjs/StepKey.js +311 -0
  55. package/dist/cjs/StepKey.js.map +7 -0
  56. package/dist/cjs/index.d.ts +91 -0
  57. package/dist/cjs/index.d.ts.map +1 -0
  58. package/dist/cjs/index.js +59 -0
  59. package/dist/cjs/index.js.map +7 -0
  60. package/dist/cjs/internal/ConflictAnnotation.d.ts +59 -0
  61. package/dist/cjs/internal/ConflictAnnotation.d.ts.map +1 -0
  62. package/dist/cjs/internal/ConflictAnnotation.js +247 -0
  63. package/dist/cjs/internal/ConflictAnnotation.js.map +7 -0
  64. package/dist/cjs/internal/EffectCandidates.d.ts +19 -0
  65. package/dist/cjs/internal/EffectCandidates.d.ts.map +1 -0
  66. package/dist/cjs/internal/EffectCandidates.js +92 -0
  67. package/dist/cjs/internal/EffectCandidates.js.map +7 -0
  68. package/dist/cjs/internal/JsonMirror.d.ts +34 -0
  69. package/dist/cjs/internal/JsonMirror.d.ts.map +1 -0
  70. package/dist/cjs/internal/JsonMirror.js +195 -0
  71. package/dist/cjs/internal/JsonMirror.js.map +7 -0
  72. package/dist/cjs/internal/effects.d.ts +245 -0
  73. package/dist/cjs/internal/effects.d.ts.map +1 -0
  74. package/dist/cjs/internal/effects.js +290 -0
  75. package/dist/cjs/internal/effects.js.map +7 -0
  76. package/dist/cjs/internal/node.d.ts +526 -0
  77. package/dist/cjs/internal/node.d.ts.map +1 -0
  78. package/dist/cjs/internal/node.js +312 -0
  79. package/dist/cjs/internal/node.js.map +7 -0
  80. package/dist/cjs/package.json +1 -0
  81. package/dist/cjs/test/PlanFixtures.d.ts +127 -0
  82. package/dist/cjs/test/PlanFixtures.d.ts.map +1 -0
  83. package/dist/cjs/test/PlanFixtures.js +59 -0
  84. package/dist/cjs/test/PlanFixtures.js.map +7 -0
  85. package/dist/esm/CachePolicy.d.ts +131 -0
  86. package/dist/esm/CachePolicy.d.ts.map +1 -0
  87. package/dist/esm/CachePolicy.js +117 -0
  88. package/dist/esm/CachePolicy.js.map +1 -0
  89. package/dist/esm/Effects.d.ts +240 -0
  90. package/dist/esm/Effects.d.ts.map +1 -0
  91. package/dist/esm/Effects.js +167 -0
  92. package/dist/esm/Effects.js.map +1 -0
  93. package/dist/esm/FileSet.d.ts +288 -0
  94. package/dist/esm/FileSet.d.ts.map +1 -0
  95. package/dist/esm/FileSet.js +324 -0
  96. package/dist/esm/FileSet.js.map +1 -0
  97. package/dist/esm/GraphBuildError.d.ts +122 -0
  98. package/dist/esm/GraphBuildError.d.ts.map +1 -0
  99. package/dist/esm/GraphBuildError.js +146 -0
  100. package/dist/esm/GraphBuildError.js.map +1 -0
  101. package/dist/esm/KeyMaterial.d.ts +102 -0
  102. package/dist/esm/KeyMaterial.d.ts.map +1 -0
  103. package/dist/esm/KeyMaterial.js +85 -0
  104. package/dist/esm/KeyMaterial.js.map +1 -0
  105. package/dist/esm/Node.d.ts +606 -0
  106. package/dist/esm/Node.d.ts.map +1 -0
  107. package/dist/esm/Node.js +521 -0
  108. package/dist/esm/Node.js.map +1 -0
  109. package/dist/esm/Placement.d.ts +117 -0
  110. package/dist/esm/Placement.d.ts.map +1 -0
  111. package/dist/esm/Placement.js +65 -0
  112. package/dist/esm/Placement.js.map +1 -0
  113. package/dist/esm/Plan.d.ts +440 -0
  114. package/dist/esm/Plan.d.ts.map +1 -0
  115. package/dist/esm/Plan.js +673 -0
  116. package/dist/esm/Plan.js.map +1 -0
  117. package/dist/esm/PlanDiff.d.ts +58 -0
  118. package/dist/esm/PlanDiff.d.ts.map +1 -0
  119. package/dist/esm/PlanDiff.js +159 -0
  120. package/dist/esm/PlanDiff.js.map +1 -0
  121. package/dist/esm/Planned.d.ts +121 -0
  122. package/dist/esm/Planned.d.ts.map +1 -0
  123. package/dist/esm/Planned.js +147 -0
  124. package/dist/esm/Planned.js.map +1 -0
  125. package/dist/esm/Repetition.d.ts +31 -0
  126. package/dist/esm/Repetition.d.ts.map +1 -0
  127. package/dist/esm/Repetition.js +24 -0
  128. package/dist/esm/Repetition.js.map +1 -0
  129. package/dist/esm/Scheduling.d.ts +89 -0
  130. package/dist/esm/Scheduling.d.ts.map +1 -0
  131. package/dist/esm/Scheduling.js +82 -0
  132. package/dist/esm/Scheduling.js.map +1 -0
  133. package/dist/esm/StepKey.d.ts +333 -0
  134. package/dist/esm/StepKey.d.ts.map +1 -0
  135. package/dist/esm/StepKey.js +478 -0
  136. package/dist/esm/StepKey.js.map +1 -0
  137. package/dist/esm/index.d.ts +91 -0
  138. package/dist/esm/index.d.ts.map +1 -0
  139. package/dist/esm/index.js +91 -0
  140. package/dist/esm/index.js.map +1 -0
  141. package/dist/esm/internal/ConflictAnnotation.d.ts +59 -0
  142. package/dist/esm/internal/ConflictAnnotation.d.ts.map +1 -0
  143. package/dist/esm/internal/ConflictAnnotation.js +332 -0
  144. package/dist/esm/internal/ConflictAnnotation.js.map +1 -0
  145. package/dist/esm/internal/EffectCandidates.d.ts +19 -0
  146. package/dist/esm/internal/EffectCandidates.d.ts.map +1 -0
  147. package/dist/esm/internal/EffectCandidates.js +86 -0
  148. package/dist/esm/internal/EffectCandidates.js.map +1 -0
  149. package/dist/esm/internal/JsonMirror.d.ts +34 -0
  150. package/dist/esm/internal/JsonMirror.d.ts.map +1 -0
  151. package/dist/esm/internal/JsonMirror.js +204 -0
  152. package/dist/esm/internal/JsonMirror.js.map +1 -0
  153. package/dist/esm/internal/effects.d.ts +245 -0
  154. package/dist/esm/internal/effects.d.ts.map +1 -0
  155. package/dist/esm/internal/effects.js +459 -0
  156. package/dist/esm/internal/effects.js.map +1 -0
  157. package/dist/esm/internal/node.d.ts +526 -0
  158. package/dist/esm/internal/node.d.ts.map +1 -0
  159. package/dist/esm/internal/node.js +564 -0
  160. package/dist/esm/internal/node.js.map +1 -0
  161. package/dist/esm/test/PlanFixtures.d.ts +127 -0
  162. package/dist/esm/test/PlanFixtures.d.ts.map +1 -0
  163. package/dist/esm/test/PlanFixtures.js +60 -0
  164. package/dist/esm/test/PlanFixtures.js.map +1 -0
  165. package/docs/README.md +165 -0
  166. package/docs/api.md +1475 -0
  167. package/docs/concepts/authoring-ast.md +203 -0
  168. package/docs/concepts/effects-and-conflicts.md +135 -0
  169. package/docs/concepts/plan-value.md +168 -0
  170. package/docs/concepts/step-keys.md +179 -0
  171. package/docs/guides/author-a-node-graph.md +182 -0
  172. package/docs/guides/compile-a-plan.md +146 -0
  173. package/docs/guides/declare-file-effects.md +143 -0
  174. package/docs/guides/diff-two-plans.md +101 -0
  175. package/docs/installation.md +71 -0
  176. package/docs/quickstart.md +128 -0
  177. package/docs/testing.md +73 -0
  178. package/docs/troubleshooting.md +314 -0
  179. package/package.json +254 -3
  180. package/src/CachePolicy.ts +143 -0
  181. package/src/Effects.ts +284 -0
  182. package/src/FileSet.ts +411 -0
  183. package/src/GraphBuildError.ts +158 -0
  184. package/src/KeyMaterial.ts +106 -0
  185. package/src/Node.ts +871 -0
  186. package/src/Placement.ts +99 -0
  187. package/src/Plan.ts +868 -0
  188. package/src/PlanDiff.ts +199 -0
  189. package/src/Planned.ts +208 -0
  190. package/src/Repetition.ts +33 -0
  191. package/src/Scheduling.ts +154 -0
  192. package/src/StepKey.ts +710 -0
  193. package/src/index.ts +103 -0
  194. package/src/internal/ConflictAnnotation.ts +374 -0
  195. package/src/internal/EffectCandidates.ts +89 -0
  196. package/src/internal/JsonMirror.ts +255 -0
  197. package/src/internal/effects.ts +543 -0
  198. package/src/internal/node.ts +858 -0
  199. package/src/test/PlanFixtures.ts +76 -0
@@ -0,0 +1,526 @@
1
+ /**
2
+ * The node AST, and the side tables the functions hang off.
3
+ *
4
+ * Two invariants shape every declaration here. The AST is **closure-free**
5
+ * and keeps payloads as inert JSON mirrors, so a valid plan can be shipped,
6
+ * stored, diffed, and rendered without the process that built it; control flow is
7
+ * **structure**, so a branch stores both arms as ASTs rather than a function
8
+ * that would have to be run to find out what comes next.
9
+ *
10
+ * The functions an author does write — a mapper, a continuation, a branch
11
+ * predicate — live in `WeakMap`s keyed by the AST node they belong to, and the
12
+ * AST keeps only a {@link FunctionIdentity} digest of their source. The digest
13
+ * is what enters content identity (https://smithers.sh/docs/concepts/content-addressing); the
14
+ * `WeakMap` is what the run reaches for when it has the real value in hand, and
15
+ * it drops with the AST it is keyed by.
16
+ *
17
+ * Adapted from `@smthrs/core` (`packages/smithers/flows/core`)
18
+ * `internal/node.ts`. `Dynamic` does not come across — a model call is an
19
+ * ordinary action here — and neither do annotations, which are `Context`
20
+ * values and would break serializability. Scheduling priority is the one thing that does cross, as
21
+ * the plain JSON field {@link Scheduled.priority} rather than as an
22
+ * annotation, because the scheduler has to read it out of a stored plan.
23
+ *
24
+ * @since 0.1.0
25
+ */
26
+ import * as Schema from "effect/Schema";
27
+ import type { Node } from "../Node.ts";
28
+ /**
29
+ * The runtime type identifier every node carries.
30
+ *
31
+ * @since 0.1.0
32
+ * @private
33
+ * @slop
34
+ */
35
+ export declare const TypeId: "~@smthrs/plan/Node";
36
+ /**
37
+ * The type-level form of {@link TypeId}.
38
+ *
39
+ * @since 0.1.0
40
+ * @private
41
+ * @slop
42
+ */
43
+ export type TypeId = typeof TypeId;
44
+ /**
45
+ * What every AST variant carries besides its own shape: an optional scheduling
46
+ * priority.
47
+ *
48
+ * A priority is JSON, not a `Context` annotation, which is why it can live in
49
+ * the AST at all: the whole point of dropping core's annotations was to keep a
50
+ * plan shippable, storable, and diffable. It is a scheduling HINT — the plan
51
+ * compiler copies it onto the node draft and the scheduler orders ready work by
52
+ * it, while key material never reads it, so raising a priority reorders work
53
+ * without re-keying a single step.
54
+ *
55
+ * @since 0.1.0
56
+ * @private
57
+ * @slop
58
+ */
59
+ export interface Scheduled {
60
+ readonly priority?: number | undefined;
61
+ }
62
+ /**
63
+ * A constant, known before anything runs.
64
+ *
65
+ * @since 0.1.0
66
+ * @private
67
+ * @slop
68
+ */
69
+ export interface Succeed extends Scheduled {
70
+ readonly _tag: "Succeed";
71
+ readonly value: unknown;
72
+ }
73
+ /**
74
+ * A constant typed failure, known before anything runs.
75
+ *
76
+ * The error is an inert JSON mirror for the same reason {@link Succeed.value}
77
+ * is: a stored plan has to carry what the node produces without the process
78
+ * that built it.
79
+ *
80
+ * @since 1.0.0
81
+ * @private
82
+ * @slop
83
+ */
84
+ export interface Fail extends Scheduled {
85
+ readonly _tag: "Fail";
86
+ readonly error: unknown;
87
+ }
88
+ /**
89
+ * Independent children, combined by name. Width is fixed here, at plan time:
90
+ * there is no dynamic fan-out.
91
+ *
92
+ * @since 0.1.0
93
+ * @private
94
+ * @slop
95
+ */
96
+ export interface All extends Scheduled {
97
+ readonly _tag: "All";
98
+ readonly nodes: Readonly<Record<string, NodeAst>>;
99
+ }
100
+ /**
101
+ * How a {@link Race} settles: `race` on the first member to settle, `any` on
102
+ * the first member to succeed, and `quorum` once `count` members succeed.
103
+ *
104
+ * @since 1.0.0
105
+ * @private
106
+ */
107
+ export type RaceMode = "race" | "any" | "quorum";
108
+ /**
109
+ * Independent children that settle early: the join decides as soon as its
110
+ * {@link RaceMode} can, and the members it did not wait for are interrupted.
111
+ * `count` is the successes a quorum needs, and 1 for `race` and `any`.
112
+ *
113
+ * @since 1.0.0
114
+ * @private
115
+ */
116
+ export interface Race extends Scheduled {
117
+ readonly _tag: "Race";
118
+ readonly mode: RaceMode;
119
+ readonly count: number;
120
+ readonly nodes: Readonly<Record<string, NodeAst>>;
121
+ }
122
+ /**
123
+ * A deferred pure transformation of an upstream result. `map` transforms; it
124
+ * never decides.
125
+ *
126
+ * @since 0.1.0
127
+ * @private
128
+ * @slop
129
+ */
130
+ export interface Map extends Scheduled {
131
+ readonly _tag: "Map";
132
+ readonly first: NodeAst;
133
+ readonly mapper: FunctionIdentity;
134
+ }
135
+ /**
136
+ * A continuation after an upstream node. `next` is present when the author
137
+ * supplied a node directly instead of a builder, in which case the topology is
138
+ * already known and nothing has to be evaluated to reveal it.
139
+ *
140
+ * @since 0.1.0
141
+ * @private
142
+ * @slop
143
+ */
144
+ export interface AndThen extends Scheduled {
145
+ readonly _tag: "AndThen";
146
+ readonly first: NodeAst;
147
+ readonly continuation: FunctionIdentity;
148
+ readonly next?: NodeAst | undefined;
149
+ }
150
+ /**
151
+ * A decision whose arms are static topology. The predicate runs at run time on
152
+ * the real value; both arms are already ASTs, so the exit condition and the
153
+ * handoff site are visible before anything runs.
154
+ *
155
+ * @since 0.1.0
156
+ * @private
157
+ * @slop
158
+ */
159
+ export interface Branch extends Scheduled {
160
+ readonly _tag: "Branch";
161
+ readonly subject: string;
162
+ readonly first: NodeAst;
163
+ readonly predicate: FunctionIdentity;
164
+ readonly then: NodeAst;
165
+ readonly else: NodeAst;
166
+ }
167
+ /**
168
+ * A protected graph and its statically planned typed-failure continuation.
169
+ *
170
+ * The symbolic error `subject` is minted per catch node rather than shared,
171
+ * mirroring {@link Branch}. Failure arms are built before the graph assigns
172
+ * ids, so a nested arm that captured an outer error would resolve it to the
173
+ * inner catch's protected node under one shared token.
174
+ *
175
+ * An absent filter catches the entire typed error channel, while a present
176
+ * schema catches only values it accepts. This mirrors Effect's typed-error
177
+ * boundary and keeps defects outside normal recovery. The serializable AST carries the schema identity; the live schema
178
+ * remains in a side table beside the AST.
179
+ *
180
+ * @since 0.1.0
181
+ * @private
182
+ * @slop
183
+ */
184
+ export interface Catch extends Scheduled {
185
+ readonly _tag: "Catch";
186
+ readonly subject: string;
187
+ readonly protected: NodeAst;
188
+ readonly failure: NodeAst;
189
+ readonly filter?: unknown | undefined;
190
+ readonly filterIdentity?: FunctionIdentity | undefined;
191
+ }
192
+ /**
193
+ * How a flow call joins the caller's plan: `inline` splices the callee's body
194
+ * in, `boundary` makes it one child execution, and `handoff` names the next
195
+ * trampoline round. Why the child call is a mode rather than a second AST tag
196
+ * is in `docs/concepts/authoring-ast.md`.
197
+ *
198
+ * @since 0.1.0
199
+ * @private
200
+ * @slop
201
+ */
202
+ export declare const CallMode: Schema.Literals<readonly ["inline", "boundary", "handoff"]>;
203
+ /**
204
+ * How a flow call joins the caller's plan.
205
+ *
206
+ * @since 0.1.0
207
+ * @private
208
+ * @slop
209
+ */
210
+ export type CallMode = typeof CallMode.Type;
211
+ /**
212
+ * A call to another flow. The AST keeps the callee's tag and the payload;
213
+ * the declaration itself is in the side table, because a flow value carries
214
+ * schemas and a body and is not JSON.
215
+ *
216
+ * @since 0.1.0
217
+ * @private
218
+ * @slop
219
+ */
220
+ export interface FlowCall extends Scheduled {
221
+ readonly _tag: "FlowCall";
222
+ readonly flow: string;
223
+ readonly mode: CallMode;
224
+ readonly payload: unknown;
225
+ }
226
+ /**
227
+ * A call to an action: the atom that does work. Same split as
228
+ * {@link FlowCall}, and no mode — an action is always one node.
229
+ *
230
+ * @since 0.1.0
231
+ * @private
232
+ * @slop
233
+ */
234
+ export interface ActionCall extends Scheduled {
235
+ readonly _tag: "ActionCall";
236
+ readonly action: string;
237
+ readonly payload: unknown;
238
+ }
239
+ /**
240
+ * The algorithms a {@link FunctionIdentity} may name. The tag is versioned so a
241
+ * change to identity semantics re-keys everything derived from one, rather than
242
+ * colliding with it.
243
+ *
244
+ * @since 0.1.0
245
+ * @private
246
+ * @slop
247
+ */
248
+ export declare const IdentityAlgorithm: Schema.Literals<readonly ["sha256-source-ephemeral/v4", "sha256-source-captures/v5", "static-node/v1"]>;
249
+ /**
250
+ * The algorithms a {@link FunctionIdentity} may name.
251
+ *
252
+ * @since 0.1.0
253
+ * @private
254
+ * @slop
255
+ */
256
+ export type IdentityAlgorithm = typeof IdentityAlgorithm.Type;
257
+ /**
258
+ * The serializable stand-in for a function. Captured functions digest their
259
+ * exact source and declared inert captures. Unannotated functions additionally
260
+ * carry process-local, per-object entropy so indistinguishable closure sources
261
+ * fail closed instead of sharing a cache key. The tag it names is
262
+ * {@link IdentityAlgorithm}.
263
+ *
264
+ * @since 0.1.0
265
+ * @private
266
+ * @slop
267
+ */
268
+ export interface FunctionIdentity {
269
+ readonly _tag: "FunctionIdentity";
270
+ readonly algorithm: IdentityAlgorithm;
271
+ readonly digest: string;
272
+ }
273
+ /**
274
+ * Brands an operation with every inert value it closes over, so its identity
275
+ * covers what it computes with and not only its source.
276
+ *
277
+ * `@smthrs/crypto` owns the captures, nested metadata, and freezing contract.
278
+ *
279
+ * @since 0.1.0
280
+ * @private
281
+ */
282
+ export declare const capture: <C extends Readonly<Record<string, unknown>>, Args extends ReadonlyArray<unknown>, A>(captures: C, operation: (this: Readonly<C>, ...args: Args) => A) => (...args: Args) => A;
283
+ /**
284
+ * The serializable form of a planned value embedded in an AST value or
285
+ * payload. The strict proxy itself cannot enter the AST because serializing it
286
+ * is deliberately a build error.
287
+ *
288
+ * @since 0.1.0
289
+ * @private
290
+ * @slop
291
+ */
292
+ export interface PlannedReference {
293
+ readonly _tag: "PlannedReference";
294
+ readonly node: string;
295
+ readonly path: ReadonlyArray<string>;
296
+ }
297
+ /**
298
+ * Reads an AST-owned planned reference without trusting its public data shape.
299
+ *
300
+ * @since 1.0.0
301
+ * @private
302
+ */
303
+ export declare const plannedReference: (value: unknown) => PlannedReference | undefined;
304
+ /**
305
+ * Every AST variant.
306
+ *
307
+ * @since 0.1.0
308
+ * @private
309
+ * @slop
310
+ */
311
+ export type NodeAst = Succeed | Fail | All | Race | Map | AndThen | Branch | Catch | FlowCall | ActionCall;
312
+ type Operation = (value: unknown) => unknown;
313
+ type Predicate = (value: unknown) => boolean;
314
+ /**
315
+ * Digests a function's exact source as UTF-8 with SHA-256. Exact source matters:
316
+ * whitespace inside a string literal is behavior, and normalizing it before
317
+ * hashing can make different functions share an identity. Unless its inert
318
+ * captures were declared with {@link capture}, the digest also includes
319
+ * process-local, per-function entropy: JavaScript cannot inspect a closure, so
320
+ * source-only identity would permit incorrect cache hits.
321
+ *
322
+ * @since 0.1.0
323
+ * @private
324
+ * @slop
325
+ */
326
+ export declare const functionIdentity: (operation: unknown) => FunctionIdentity;
327
+ /**
328
+ * The prototype every node shares, so `pipe` is one function rather than one
329
+ * closure per node.
330
+ *
331
+ * @since 0.1.0
332
+ * @private
333
+ * @slop
334
+ */
335
+ export declare const NodeProto: {
336
+ "~@smthrs/plan/Node": {
337
+ _A: <A>(a: A) => A;
338
+ _E: <A>(a: A) => A;
339
+ _R: <A>(a: A) => A;
340
+ };
341
+ pipe(): unknown;
342
+ };
343
+ /**
344
+ * Whether `count` is a successes target a {@link Race} of `members` can reach:
345
+ * a quorum needs between one and every member, and the other modes need one.
346
+ *
347
+ * @since 1.0.0
348
+ * @private
349
+ */
350
+ export declare const isRaceCount: (mode: RaceMode, count: unknown, members: number) => boolean;
351
+ /**
352
+ * Checks whether a value has the shape of a {@link NodeAst}: what a JSON round
353
+ * trip of a genuine AST produces, and nothing looser. Every variant's own
354
+ * fields are checked, and every child is walked. The walk is an explicit stack
355
+ * rather than recursion, so an arbitrarily deep AST cannot overflow the native
356
+ * stack, and it tracks the ancestors of the position it has reached, so a
357
+ * cyclic object is refused rather than walked forever while a shared sub-AST
358
+ * still passes.
359
+ *
360
+ * @since 1.0.0
361
+ * @private
362
+ */
363
+ export declare const isNodeAst: (value: unknown) => value is NodeAst;
364
+ /**
365
+ * Checks whether a value is a node.
366
+ *
367
+ * A node this module built is recognized by registration. A node that crossed
368
+ * a serialization boundary, an object whose prototype is {@link NodeProto} and
369
+ * whose own `ast` data property passes {@link isNodeAst}, is recognized by that
370
+ * shape: `@smthrs/flow` hands a rehydrated AST back as a node, and the side
371
+ * tables are all a round trip loses. The {@link TypeId} marker is an exported
372
+ * string any object can carry, so it counts for nothing on its own, and an
373
+ * `ast` that is missing, malformed, cyclic, or an accessor is refused because
374
+ * every combinator reads it as trusted topology. A proxy is judged by the
375
+ * shape it forwards.
376
+ *
377
+ * @since 1.0.0
378
+ * @private
379
+ */
380
+ export declare const isNode: (value: unknown) => value is Node<unknown, unknown, any>;
381
+ /**
382
+ * Wraps an AST as a node.
383
+ *
384
+ * @since 0.1.0
385
+ * @private
386
+ * @slop
387
+ */
388
+ export declare const makeNode: <A = unknown, E = never, R = never>(ast: NodeAst) => Node<A, E, R>;
389
+ /**
390
+ * Constructs a {@link Succeed}.
391
+ *
392
+ * @since 0.1.0
393
+ * @private
394
+ * @slop
395
+ */
396
+ export declare const succeed: (input: unknown) => Succeed;
397
+ /**
398
+ * Constructs a {@link Fail}.
399
+ *
400
+ * @since 1.0.0
401
+ * @private
402
+ * @slop
403
+ */
404
+ export declare const fail: (error: unknown) => Fail;
405
+ /**
406
+ * Constructs an {@link All}.
407
+ *
408
+ * @since 0.1.0
409
+ * @private
410
+ * @slop
411
+ */
412
+ export declare const all: (nodes: Readonly<Record<string, NodeAst>>) => All;
413
+ /**
414
+ * Constructs a {@link Race}.
415
+ *
416
+ * @since 1.0.0
417
+ * @private
418
+ */
419
+ export declare const race: (mode: RaceMode, count: number, nodes: Readonly<Record<string, NodeAst>>) => Race;
420
+ /**
421
+ * Constructs a {@link Map}, filing the mapper under the AST it belongs to.
422
+ *
423
+ * @since 0.1.0
424
+ * @private
425
+ * @slop
426
+ */
427
+ export declare const map: (first: NodeAst, operation: Operation, source: unknown) => Map;
428
+ /**
429
+ * Constructs an {@link AndThen} from a builder. The builder is evaluated once
430
+ * against a planned value when the graph is built, never here.
431
+ *
432
+ * @since 0.1.0
433
+ * @private
434
+ * @slop
435
+ */
436
+ export declare const andThen: (first: NodeAst, operation: Operation, source: unknown) => AndThen;
437
+ /**
438
+ * Constructs an {@link AndThen} from a node the author supplied directly. There
439
+ * is no function to digest, so the continuation carries a fixed marker.
440
+ *
441
+ * @since 0.1.0
442
+ * @private
443
+ * @slop
444
+ */
445
+ export declare const andThenNode: (first: NodeAst, next: NodeAst) => AndThen;
446
+ /**
447
+ * Constructs a {@link Branch}. Both arms arrive already evaluated, because a
448
+ * branch that had to be run to reveal its topology would not be a plan.
449
+ *
450
+ * @since 0.1.0
451
+ * @private
452
+ * @slop
453
+ */
454
+ export declare const branch: (subject: string, first: NodeAst, predicate: Predicate, source: unknown, then: NodeAst, otherwise: NodeAst) => Branch;
455
+ /**
456
+ * Constructs a {@link Catch} whose failure topology is already evaluated.
457
+ *
458
+ * @since 0.1.0
459
+ * @private
460
+ * @slop
461
+ */
462
+ export declare const catch_: (subject: string, protectedAst: NodeAst, failure: NodeAst, filter?: Schema.Top) => Catch;
463
+ /**
464
+ * Constructs a {@link FlowCall}, filing the flow declaration beside it.
465
+ *
466
+ * @since 0.1.0
467
+ * @private
468
+ * @slop
469
+ */
470
+ export declare const flowCall: (declaration: unknown, flow: string, mode: CallMode, payload: unknown) => FlowCall;
471
+ /**
472
+ * Constructs an {@link ActionCall}, filing the action declaration beside
473
+ * it.
474
+ *
475
+ * @since 0.1.0
476
+ * @private
477
+ * @slop
478
+ */
479
+ export declare const actionCall: (declaration: unknown, action: string, payload: unknown) => ActionCall;
480
+ /**
481
+ * The deferred function of a map or a continuation.
482
+ *
483
+ * @since 0.1.0
484
+ * @private
485
+ * @slop
486
+ */
487
+ export declare const operation: (ast: AndThen | Map) => Operation | undefined;
488
+ /**
489
+ * The run-time predicate of a branch.
490
+ *
491
+ * @since 0.1.0
492
+ * @private
493
+ * @slop
494
+ */
495
+ export declare const predicate: (ast: Branch) => Predicate | undefined;
496
+ /**
497
+ * The optional error schema filter of a catch node.
498
+ *
499
+ * @since 0.1.0
500
+ * @private
501
+ * @slop
502
+ */
503
+ export declare const filter: (ast: Catch) => Schema.Top | undefined;
504
+ /**
505
+ * The flow or action declaration a call node names.
506
+ *
507
+ * @since 0.1.0
508
+ * @private
509
+ * @slop
510
+ */
511
+ export declare const declaration: (ast: ActionCall | FlowCall) => unknown;
512
+ /**
513
+ * Copies an AST with a scheduling priority attached.
514
+ *
515
+ * The copy is shallow and the side tables are re-filed against it, because a
516
+ * function, a predicate, a filter schema, and a declaration are keyed by the
517
+ * exact AST object they belong to: a copy that left them behind would silently
518
+ * lose the continuation the graph walk has to evaluate.
519
+ *
520
+ * @since 0.1.0
521
+ * @private
522
+ * @slop
523
+ */
524
+ export declare const withPriority: (ast: NodeAst, priority: number) => NodeAst;
525
+ export {};
526
+ //# sourceMappingURL=node.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/internal/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAOH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAItC;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,EAAG,oBAA6B,CAAA;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAA;AAElC;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAQ,SAAQ,SAAS;IACxC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,IAAK,SAAQ,SAAS;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,GAAI,SAAQ,SAAS;IACpC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAClD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,WAAW,IAAK,SAAQ,SAAS;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAClD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,GAAI,SAAQ,SAAS;IACpC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CAClC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAQ,SAAQ,SAAS;IACxC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAA;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CACpC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,MAAO,SAAQ,SAAS;IACvC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,KAAM,SAAQ,SAAS;IACtC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAA;CACvD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,6DAAqD,CAAA;AAE1E;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,yGAI5B,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAA;AAE7D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,oIA4LX,GAAI,sBAAqB,GAAG,gBA5LE,CAAA;AAEvC;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACrC;AAqCD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,gBAAgB,GAAG,SAGtD,CAAA;AAEf;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,UAAU,CAAA;AAE1G,KAAK,SAAS,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;AAE5C,KAAK,SAAS,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;AAgB5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,gBAA4C,CAAA;AAEnG;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS;;;;;;;CAUrB,CAAA;AAiBD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,QAAQ,EAAE,OAAO,OAAO,EAAE,SAAS,MAAM,KAAG,OAEc,CAAA;AAU5F;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAqEnD,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAM1E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,KAAK,OAAO,KAAG,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAItF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,KAAG,OAA6D,CAAA;AAEtG;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,KAAG,IAAuD,CAAA;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,GAAG,GAAI,OAAO,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAAG,GAA+B,CAAA;AAE9F;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,QAAQ,EAAE,OAAO,MAAM,EAAE,OAAO,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAAG,IAK7F,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,GAAG,GAAI,OAAO,OAAO,EAAE,WAAW,SAAS,EAAE,QAAQ,OAAO,KAAG,GAI3E,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,EAAE,WAAW,SAAS,EAAE,QAAQ,OAAO,KAAG,OAI/E,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,EAAE,MAAM,OAAO,KAAG,OAK1D,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GACjB,SAAS,MAAM,EACf,OAAO,OAAO,EACd,WAAW,SAAS,EACpB,QAAQ,OAAO,EACf,MAAM,OAAO,EACb,WAAW,OAAO,KACjB,MAWF,CAAA;AAwCD;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,SAAS,MAAM,EAAE,cAAc,OAAO,EAAE,SAAS,OAAO,EAAE,SAAS,MAAM,CAAC,GAAG,KAAG,KAetG,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,aAAa,OAAO,EAAE,MAAM,MAAM,EAAE,MAAM,QAAQ,EAAE,SAAS,OAAO,KAAG,QAI/F,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAI,aAAa,OAAO,EAAE,QAAQ,MAAM,EAAE,SAAS,OAAO,KAAG,UAInF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,OAAO,GAAG,GAAG,KAAG,SAAS,GAAG,SAAgC,CAAA;AAE3F;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,KAAG,SAAS,GAAG,SAAgC,CAAA;AAEpF;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,KAAK,KAAK,KAAG,MAAM,CAAC,GAAG,GAAG,SAA6B,CAAA;AAE9E;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,UAAU,GAAG,QAAQ,KAAG,OAAgC,CAAA;AAEzF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,OAAO,EAAE,UAAU,MAAM,KAAG,OAmB7D,CAAA"}