@typeonce/effect-machine 0.4.0 → 0.5.1

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 (90) hide show
  1. package/README.md +166 -588
  2. package/dist/Machine.d.ts +426 -240
  3. package/dist/Machine.d.ts.map +1 -1
  4. package/dist/Machine.js +219 -43
  5. package/dist/Machine.js.map +1 -1
  6. package/dist/internal/machine/activities.d.ts +1 -1
  7. package/dist/internal/machine/activities.js +1 -1
  8. package/dist/internal/machine/atom.d.ts +1 -1
  9. package/dist/internal/machine/atom.js +1 -1
  10. package/dist/internal/machine/cluster.d.ts +2 -2
  11. package/dist/internal/machine/cluster.js +1 -1
  12. package/dist/internal/machine/command.d.ts +1 -1
  13. package/dist/internal/machine/command.js +1 -1
  14. package/dist/internal/machine/commandRuntime.d.ts +1 -1
  15. package/dist/internal/machine/commandRuntime.js +1 -1
  16. package/dist/internal/machine/configuration.d.ts +1 -1
  17. package/dist/internal/machine/configuration.js +1 -1
  18. package/dist/internal/machine/errors.d.ts +7 -7
  19. package/dist/internal/machine/errors.js +7 -7
  20. package/dist/internal/machine/executionPlan.d.ts +2 -2
  21. package/dist/internal/machine/executionPlan.d.ts.map +1 -1
  22. package/dist/internal/machine/executionPlan.js +17 -8
  23. package/dist/internal/machine/executionPlan.js.map +1 -1
  24. package/dist/internal/machine/invocation.d.ts +1 -1
  25. package/dist/internal/machine/invocation.js +1 -1
  26. package/dist/internal/machine/planner.d.ts +1 -1
  27. package/dist/internal/machine/planner.js +1 -1
  28. package/dist/internal/machine/process.d.ts +1 -1
  29. package/dist/internal/machine/process.d.ts.map +1 -1
  30. package/dist/internal/machine/process.js +76 -24
  31. package/dist/internal/machine/process.js.map +1 -1
  32. package/dist/internal/machine/protocol.d.ts +1 -1
  33. package/dist/internal/machine/protocol.js +1 -1
  34. package/dist/internal/machine/runtime.d.ts +32 -4
  35. package/dist/internal/machine/runtime.d.ts.map +1 -1
  36. package/dist/internal/machine/runtime.js +120 -12
  37. package/dist/internal/machine/runtime.js.map +1 -1
  38. package/dist/internal/machine/serialization.d.ts +1 -1
  39. package/dist/internal/machine/serialization.js +1 -1
  40. package/dist/internal/machine/topology.d.ts +1 -1
  41. package/dist/internal/machine/topology.js +1 -1
  42. package/dist/internal/testing/machine/arbitrary.d.ts +3 -3
  43. package/dist/internal/testing/machine/exploration.d.ts +30 -0
  44. package/dist/internal/testing/machine/exploration.d.ts.map +1 -0
  45. package/dist/internal/testing/machine/exploration.js +237 -0
  46. package/dist/internal/testing/machine/exploration.js.map +1 -0
  47. package/dist/internal/testing/machine/finiteModel.d.ts +20 -20
  48. package/dist/internal/testing/machine/finiteModel.js +2 -2
  49. package/dist/internal/testing/machine/invariant.d.ts +31 -0
  50. package/dist/internal/testing/machine/invariant.d.ts.map +1 -0
  51. package/dist/internal/testing/machine/invariant.js +214 -0
  52. package/dist/internal/testing/machine/invariant.js.map +1 -0
  53. package/dist/internal/testing/machine/probe.d.ts +26 -0
  54. package/dist/internal/testing/machine/probe.d.ts.map +1 -0
  55. package/dist/internal/testing/machine/probe.js +45 -0
  56. package/dist/internal/testing/machine/probe.js.map +1 -0
  57. package/dist/internal/testing/machine/referenceModel.d.ts +14 -14
  58. package/dist/internal/testing/machine/referenceModel.js +2 -2
  59. package/dist/internal/testing/machine/runtime.d.ts +329 -26
  60. package/dist/internal/testing/machine/runtime.d.ts.map +1 -1
  61. package/dist/internal/testing/machine/runtime.js +303 -14
  62. package/dist/internal/testing/machine/runtime.js.map +1 -1
  63. package/dist/internal/testing/machine/runtimeInvariant.d.ts +32 -0
  64. package/dist/internal/testing/machine/runtimeInvariant.d.ts.map +1 -0
  65. package/dist/internal/testing/machine/runtimeInvariant.js +334 -0
  66. package/dist/internal/testing/machine/runtimeInvariant.js.map +1 -0
  67. package/dist/internal/testing/machine/trace.d.ts +17 -0
  68. package/dist/internal/testing/machine/trace.d.ts.map +1 -0
  69. package/dist/internal/testing/machine/trace.js +94 -0
  70. package/dist/internal/testing/machine/trace.js.map +1 -0
  71. package/dist/internal/testing/machine/verification.d.ts +9 -6
  72. package/dist/internal/testing/machine/verification.d.ts.map +1 -1
  73. package/dist/internal/testing/machine/verification.js +8 -79
  74. package/dist/internal/testing/machine/verification.js.map +1 -1
  75. package/dist/testing/MachineTest.d.ts +1029 -47
  76. package/dist/testing/MachineTest.d.ts.map +1 -1
  77. package/dist/testing/MachineTest.js +315 -11
  78. package/dist/testing/MachineTest.js.map +1 -1
  79. package/dist/testing/index.d.ts +1 -1
  80. package/dist/testing/index.js +1 -1
  81. package/dist/unstable/cluster/ClusterMachine.d.ts +38 -19
  82. package/dist/unstable/cluster/ClusterMachine.d.ts.map +1 -1
  83. package/dist/unstable/cluster/ClusterMachine.js +27 -9
  84. package/dist/unstable/cluster/ClusterMachine.js.map +1 -1
  85. package/dist/unstable/reactivity/AtomMachine.d.ts +82 -31
  86. package/dist/unstable/reactivity/AtomMachine.d.ts.map +1 -1
  87. package/dist/unstable/reactivity/AtomMachine.js +63 -12
  88. package/dist/unstable/reactivity/AtomMachine.js.map +1 -1
  89. package/docs/agent-guide.md +160 -18
  90. package/package.json +11 -2
package/dist/Machine.js CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Schema-first machine definitions.
3
3
  *
4
- * @since 4.0.0
4
+ * @since 0.4.0
5
5
  */
6
6
  import { hasProperty } from "effect/Predicate";
7
7
  import * as internal from "./internal/machine/machine.js";
@@ -10,7 +10,7 @@ import { InitialEventTypeId } from "./internal/machine/machine.js";
10
10
  * Runtime type identifier attached to `Machine` values.
11
11
  *
12
12
  * @category type IDs
13
- * @since 4.0.0
13
+ * @since 0.4.0
14
14
  */
15
15
  export const TypeId = "~effect/Machine";
16
16
  /**
@@ -18,21 +18,21 @@ export const TypeId = "~effect/Machine";
18
18
  * actions.
19
19
  *
20
20
  * @category type IDs
21
- * @since 4.0.0
21
+ * @since 0.4.0
22
22
  */
23
23
  export { InitialEventTypeId };
24
24
  /**
25
25
  * Synthetic event value used while the machine settles its initial state.
26
26
  *
27
27
  * @category constructors
28
- * @since 4.0.0
28
+ * @since 0.4.0
29
29
  */
30
30
  export const InitialEvent = { _tag: InitialEventTypeId };
31
31
  /**
32
32
  * Returns `true` if a value is the synthetic machine initial event.
33
33
  *
34
34
  * @category guards
35
- * @since 4.0.0
35
+ * @since 0.4.0
36
36
  */
37
37
  export const isInitialEvent = (u) => hasProperty(u, "_tag") && u._tag === InitialEventTypeId;
38
38
  export {
@@ -41,7 +41,7 @@ export {
41
41
  * exists for the current machine.
42
42
  *
43
43
  * @category errors
44
- * @since 4.0.0
44
+ * @since 0.4.0
45
45
  */
46
46
  ChildAlreadyExistsError,
47
47
  /**
@@ -49,7 +49,7 @@ ChildAlreadyExistsError,
49
49
  * number of macrostep iterations.
50
50
  *
51
51
  * @category errors
52
- * @since 4.0.0
52
+ * @since 0.4.0
53
53
  */
54
54
  InfiniteTransitionError,
55
55
  /**
@@ -57,7 +57,7 @@ InfiniteTransitionError,
57
57
  * structural configuration declared for a machine boundary.
58
58
  *
59
59
  * @category errors
60
- * @since 4.0.0
60
+ * @since 0.4.0
61
61
  */
62
62
  MachineSchemaDecodeError,
63
63
  /**
@@ -65,7 +65,7 @@ MachineSchemaDecodeError,
65
65
  * its declared state or output schemas.
66
66
  *
67
67
  * @category errors
68
- * @since 4.0.0
68
+ * @since 0.4.0
69
69
  */
70
70
  MachineSchemaEncodeError,
71
71
  /**
@@ -73,7 +73,7 @@ MachineSchemaEncodeError,
73
73
  * requires a managed machine process.
74
74
  *
75
75
  * @category errors
76
- * @since 4.0.0
76
+ * @since 0.4.0
77
77
  */
78
78
  ProcessLocalError,
79
79
  /**
@@ -81,7 +81,7 @@ ProcessLocalError,
81
81
  * logic after the initial state has been computed.
82
82
  *
83
83
  * @category errors
84
- * @since 4.0.0
84
+ * @since 0.4.0
85
85
  */
86
86
  StartupError,
87
87
  /**
@@ -89,7 +89,7 @@ StartupError,
89
89
  * producing an output.
90
90
  *
91
91
  * @category errors
92
- * @since 4.0.0
92
+ * @since 0.4.0
93
93
  */
94
94
  StoppedError } from "./internal/machine/machine.js";
95
95
  const RuntimeRequirementTypeId = "~effect/Machine/RuntimeRequirement";
@@ -104,14 +104,14 @@ const ChildMachineTypeId = "~effect/Machine/ChildMachine";
104
104
  * Returns `true` if a value is a `Machine`.
105
105
  *
106
106
  * @category guards
107
- * @since 4.0.0
107
+ * @since 0.4.0
108
108
  */
109
109
  export const isMachine = internal.isMachine;
110
110
  /**
111
111
  * Returns `true` if a state snapshot is final for a machine.
112
112
  *
113
113
  * @category guards
114
- * @since 4.0.0
114
+ * @since 0.4.0
115
115
  */
116
116
  export const isFinal = internal.isFinal;
117
117
  /**
@@ -146,7 +146,7 @@ export const isFinal = internal.isFinal;
146
146
  * ```
147
147
  *
148
148
  * @category constructors
149
- * @since 4.0.0
149
+ * @since 0.4.0
150
150
  */
151
151
  export const defineStates = internal.defineStates;
152
152
  /**
@@ -197,7 +197,7 @@ export const defineStates = internal.defineStates;
197
197
  *
198
198
  * @see {@link defineStates} for typed initial snapshot builders.
199
199
  * @category constructors
200
- * @since 4.0.0
200
+ * @since 0.4.0
201
201
  */
202
202
  export const make = internal.make;
203
203
  /**
@@ -218,12 +218,26 @@ export const make = internal.make;
218
218
  * **Example**
219
219
  *
220
220
  * ```ts
221
+ * import { Schema } from "effect"
222
+ * import { Machine } from "@typeonce/effect-machine"
223
+ *
224
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
225
+ * class Increment extends Schema.TaggedClass<Increment>("Increment")("Increment", {
226
+ * by: Schema.Number
227
+ * }) {}
228
+ *
229
+ * const States = Machine.defineStates({ Idle })
230
+ * const counter = Machine.make({
231
+ * states: States.states,
232
+ * events: [Increment],
233
+ * initial: () => States.initial.Idle.from()
234
+ * }).handle({ Idle: { on: { Increment: () => States.initial.Idle.from() } } })
235
+ *
221
236
  * const increment = Machine.event(counter, Increment, { by: 1 })
222
- * yield* ref.send(increment)
223
237
  * ```
224
238
  *
225
239
  * @category constructors
226
- * @since 4.0.0
240
+ * @since 0.4.0
227
241
  */
228
242
  export const event = internal.event;
229
243
  /**
@@ -249,9 +263,29 @@ export const event = internal.event;
249
263
  * guarantee JSON-compatible values; schemas used with JSON-backed storage must
250
264
  * have JSON-compatible encoded representations.
251
265
  *
266
+ * **Example**
267
+ *
268
+ * ```ts
269
+ * import { Effect, Schema } from "effect"
270
+ * import { Machine } from "@typeonce/effect-machine"
271
+ *
272
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
273
+ * const States = Machine.defineStates({ Idle })
274
+ * const machine = Machine.make({
275
+ * states: States.states,
276
+ * events: [],
277
+ * initial: () => States.initial.Idle.from()
278
+ * }).handle({ Idle: {} })
279
+ *
280
+ * const encoded = Effect.gen(function*() {
281
+ * const initial = yield* Machine.planInitial(machine)
282
+ * return yield* Machine.encodeSnapshot(machine, initial.state)
283
+ * })
284
+ * ```
285
+ *
252
286
  * @see {@link decodeSnapshot} for restoring an encoded snapshot.
253
287
  * @category encoding
254
- * @since 4.0.0
288
+ * @since 0.4.0
255
289
  */
256
290
  export const encodeSnapshot = internal.encodeSnapshot;
257
291
  /**
@@ -273,9 +307,30 @@ export const encodeSnapshot = internal.encodeSnapshot;
273
307
  * Decoding restores logical statechart data only. It does not restart invoked
274
308
  * processes, recreate spawned children, or restore a previous `MachineRef`.
275
309
  *
310
+ * **Example**
311
+ *
312
+ * ```ts
313
+ * import { Effect, Schema } from "effect"
314
+ * import { Machine } from "@typeonce/effect-machine"
315
+ *
316
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
317
+ * const States = Machine.defineStates({ Idle })
318
+ * const machine = Machine.make({
319
+ * states: States.states,
320
+ * events: [],
321
+ * initial: () => States.initial.Idle.from()
322
+ * }).handle({ Idle: {} })
323
+ *
324
+ * const roundTrip = Effect.gen(function*() {
325
+ * const initial = yield* Machine.planInitial(machine)
326
+ * const encoded = yield* Machine.encodeSnapshot(machine, initial.state)
327
+ * return yield* Machine.decodeSnapshot(machine, encoded)
328
+ * })
329
+ * ```
330
+ *
276
331
  * @see {@link encodeSnapshot} for creating the normalized representation.
277
332
  * @category decoding
278
- * @since 4.0.0
333
+ * @since 0.4.0
279
334
  */
280
335
  export const decodeSnapshot = internal.decodeSnapshot;
281
336
  /**
@@ -319,7 +374,7 @@ export const decodeSnapshot = internal.decodeSnapshot;
319
374
  * @see {@link effect} for one-shot child effects.
320
375
  * @see {@link spawn} for children whose lifetime is controlled by actions.
321
376
  * @category constructors
322
- * @since 4.0.0
377
+ * @since 0.4.0
323
378
  */
324
379
  export const invoke = internal.invoke;
325
380
  /**
@@ -335,10 +390,27 @@ export const invoke = internal.invoke;
335
390
  * Declare mapped outcomes in `internalEvents` unless they are also legitimate
336
391
  * public commands.
337
392
  *
393
+ * **Example**
394
+ *
395
+ * ```ts
396
+ * import { Effect, Schema } from "effect"
397
+ * import { Machine } from "@typeonce/effect-machine"
398
+ *
399
+ * class Loaded extends Schema.TaggedClass<Loaded>("Loaded")("Loaded", {
400
+ * value: Schema.String
401
+ * }) {}
402
+ *
403
+ * const load = Machine.invokeEffect({
404
+ * id: "load",
405
+ * effect: Effect.succeed("ready"),
406
+ * onSuccess: (value) => new Loaded({ value })
407
+ * })
408
+ * ```
409
+ *
338
410
  * @see {@link invoke} for arbitrary child process logic.
339
411
  * @see {@link after} for a state-scoped delayed event.
340
412
  * @category constructors
341
- * @since 4.0.0
413
+ * @since 0.4.0
342
414
  */
343
415
  export const invokeEffect = internal.invokeEffect;
344
416
  /**
@@ -348,8 +420,19 @@ export const invokeEffect = internal.invokeEffect;
348
420
  * that state exits. The delayed value should normally be declared in
349
421
  * `internalEvents`.
350
422
  *
423
+ * **Example**
424
+ *
425
+ * ```ts
426
+ * import { Schema } from "effect"
427
+ * import { Machine } from "@typeonce/effect-machine"
428
+ *
429
+ * class TimedOut extends Schema.TaggedClass<TimedOut>("TimedOut")("TimedOut", {}) {}
430
+ *
431
+ * const timeout = Machine.after("5 seconds", new TimedOut({}))
432
+ * ```
433
+ *
351
434
  * @category constructors
352
- * @since 4.0.0
435
+ * @since 0.4.0
353
436
  */
354
437
  export const after = internal.after;
355
438
  /**
@@ -363,7 +446,7 @@ export const after = internal.after;
363
446
  * remains authoritative at runtime.
364
447
  *
365
448
  * @category constructors
366
- * @since 4.0.0
449
+ * @since 0.4.0
367
450
  */
368
451
  export const retag = internal.retag;
369
452
  /**
@@ -389,7 +472,7 @@ export const retag = internal.retag;
389
472
  * @see {@link invoke} for invoking lower-level process logic.
390
473
  * @see {@link sendTo} for sending events to the invoked machine.
391
474
  * @category constructors
392
- * @since 4.0.0
475
+ * @since 0.4.0
393
476
  */
394
477
  export const invokeMachine = internal.invokeMachine;
395
478
  /**
@@ -410,10 +493,27 @@ export const invokeMachine = internal.invokeMachine;
410
493
  * protocol. Manual planners may inspect commands but need a running actor scope
411
494
  * to execute child-addressed operations.
412
495
  *
496
+ * **Example**
497
+ *
498
+ * ```ts
499
+ * import { Effect, Schema } from "effect"
500
+ * import { Machine } from "@typeonce/effect-machine"
501
+ *
502
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
503
+ * const States = Machine.defineStates({ Idle })
504
+ * const machine = Machine.make({
505
+ * states: States.states,
506
+ * events: [],
507
+ * initial: () => States.initial.Idle.from()
508
+ * }).handle({ Idle: {} })
509
+ *
510
+ * const initialState = Effect.map(Machine.planInitial(machine), (plan) => plan.state)
511
+ * ```
512
+ *
413
513
  * @see {@link plan} for planning a received event.
414
514
  * @see {@link start} for the managed runtime protocol.
415
515
  * @category constructors
416
- * @since 4.0.0
516
+ * @since 0.4.0
417
517
  */
418
518
  export const planInitial = internal.planInitial;
419
519
  /**
@@ -428,7 +528,7 @@ export const planInitial = internal.planInitial;
428
528
  * active configuration.
429
529
  *
430
530
  * @category getters
431
- * @since 4.0.0
531
+ * @since 0.4.0
432
532
  */
433
533
  export const stateNodes = internal.stateNodes;
434
534
  /**
@@ -443,7 +543,7 @@ export const stateNodes = internal.stateNodes;
443
543
  * remain dynamic.
444
544
  *
445
545
  * @category getters
446
- * @since 4.0.0
546
+ * @since 0.4.0
447
547
  */
448
548
  export const transitionDefinitions = internal.transitionDefinitions;
449
549
  /**
@@ -457,7 +557,7 @@ export const transitionDefinitions = internal.transitionDefinitions;
457
557
  * never evaluated during inspection.
458
558
  *
459
559
  * @category getters
460
- * @since 4.0.0
560
+ * @since 0.4.0
461
561
  */
462
562
  export const activityDefinitions = internal.activityDefinitions;
463
563
  /**
@@ -470,14 +570,14 @@ export const activityDefinitions = internal.activityDefinitions;
470
570
  * and are not returned.
471
571
  *
472
572
  * @category getters
473
- * @since 4.0.0
573
+ * @since 0.4.0
474
574
  */
475
575
  export const configuration = internal.configuration;
476
576
  /**
477
577
  * Returns the event tags handled by the current state snapshot.
478
578
  *
479
579
  * @category getters
480
- * @since 4.0.0
580
+ * @since 0.4.0
481
581
  */
482
582
  export const enabled = internal.enabled;
483
583
  /**
@@ -497,10 +597,32 @@ export const enabled = internal.enabled;
497
597
  * `emittedEvents`. Events with no enabled transition are ignored and produce
498
598
  * an unchanged plan.
499
599
  *
600
+ * **Example**
601
+ *
602
+ * ```ts
603
+ * import { Effect, Schema } from "effect"
604
+ * import { Machine } from "@typeonce/effect-machine"
605
+ *
606
+ * class Off extends Schema.TaggedClass<Off>("Off")("Off", {}) {}
607
+ * class On extends Schema.TaggedClass<On>("On")("On", {}) {}
608
+ * class Toggle extends Schema.TaggedClass<Toggle>("Toggle")("Toggle", {}) {}
609
+ * const States = Machine.defineStates({ Off, On })
610
+ * const machine = Machine.make({
611
+ * states: States.states,
612
+ * events: [Toggle],
613
+ * initial: () => States.initial.Off.from()
614
+ * }).handle({ Off: { on: { Toggle: () => States.initial.On.from() } }, On: {} })
615
+ *
616
+ * const nextState = Effect.gen(function*() {
617
+ * const initial = yield* Machine.planInitial(machine)
618
+ * return (yield* Machine.plan(machine, initial.state, new Toggle({}))).next
619
+ * })
620
+ * ```
621
+ *
500
622
  * @see {@link planInitial} for planning machine startup.
501
623
  * @see {@link start} for managed execution and lifecycle observation.
502
624
  * @category combinators
503
- * @since 4.0.0
625
+ * @since 0.4.0
504
626
  */
505
627
  export const plan = internal.plan;
506
628
  /**
@@ -543,7 +665,7 @@ export const plan = internal.plan;
543
665
  * @see {@link transition} for event-driven state.
544
666
  * @see {@link logic} for direct control over intermediate snapshots.
545
667
  * @category constructors
546
- * @since 4.0.0
668
+ * @since 0.4.0
547
669
  */
548
670
  export const effect = internal.effect;
549
671
  /**
@@ -572,7 +694,7 @@ export const effect = internal.effect;
572
694
  * @see {@link effect} for one-shot work.
573
695
  * @see {@link transition} for event-driven state.
574
696
  * @category constructors
575
- * @since 4.0.0
697
+ * @since 0.4.0
576
698
  */
577
699
  export const logic = internal.logic;
578
700
  /**
@@ -588,10 +710,22 @@ export const logic = internal.logic;
588
710
  * Each received event runs the transition Effect against the latest state. The
589
711
  * resulting state is published before the next queued event is processed.
590
712
  *
713
+ * **Example**
714
+ *
715
+ * ```ts
716
+ * import { Effect } from "effect"
717
+ * import { Machine } from "@typeonce/effect-machine"
718
+ *
719
+ * const counter = Machine.transition(
720
+ * 0,
721
+ * (count, event: { readonly by: number }) => Effect.succeed(count + event.by)
722
+ * )
723
+ * ```
724
+ *
591
725
  * @see {@link effect} for one-shot work.
592
726
  * @see {@link logic} for direct process lifecycle control.
593
727
  * @category constructors
594
- * @since 4.0.0
728
+ * @since 0.4.0
595
729
  */
596
730
  export const transition = internal.transition;
597
731
  /**
@@ -601,7 +735,7 @@ export const transition = internal.transition;
601
735
  * constructed descriptors for the same pair address the same invoked child.
602
736
  *
603
737
  * @category constructors
604
- * @since 4.0.0
738
+ * @since 0.4.0
605
739
  */
606
740
  export const child = internal.child;
607
741
  /**
@@ -611,7 +745,7 @@ export const child = internal.child;
611
745
  * the address with `spawn`, `invoke`, or `sendTo`.
612
746
  *
613
747
  * @category constructors
614
- * @since 4.0.0
748
+ * @since 0.4.0
615
749
  */
616
750
  export const childAddress = internal.childAddress;
617
751
  /**
@@ -631,28 +765,28 @@ export const childAddress = internal.childAddress;
631
765
  * @see {@link invoke} for children that start and stop with a state.
632
766
  * @see {@link sendTo} for sending events to named children.
633
767
  * @category runtime
634
- * @since 4.0.0
768
+ * @since 0.4.0
635
769
  */
636
770
  export const spawn = internal.spawn;
637
771
  /**
638
772
  * Sends an event to a named child process of the running machine.
639
773
  *
640
774
  * @category runtime
641
- * @since 4.0.0
775
+ * @since 0.4.0
642
776
  */
643
777
  export const sendTo = internal.sendTo;
644
778
  /**
645
779
  * Stops a named child process of the running machine.
646
780
  *
647
781
  * @category runtime
648
- * @since 4.0.0
782
+ * @since 0.4.0
649
783
  */
650
784
  export const stopChild = internal.stopChild;
651
785
  /**
652
786
  * Returns a stream of terminal lifecycle outcomes for a running machine.
653
787
  *
654
788
  * @category combinators
655
- * @since 4.0.0
789
+ * @since 0.4.0
656
790
  */
657
791
  export const watch = internal.watch;
658
792
  /**
@@ -677,10 +811,30 @@ export const watch = internal.watch;
677
811
  * rather than being returned by `send`. Sending after the machine reaches any
678
812
  * terminal state fails immediately with `StoppedError`.
679
813
  *
814
+ * **Example**
815
+ *
816
+ * ```ts
817
+ * import { Effect, Schema } from "effect"
818
+ * import { Machine } from "@typeonce/effect-machine"
819
+ *
820
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
821
+ * const States = Machine.defineStates({ Idle })
822
+ * const machine = Machine.make({
823
+ * states: States.states,
824
+ * events: [],
825
+ * initial: () => States.initial.Idle.from()
826
+ * }).handle({ Idle: {} })
827
+ *
828
+ * const state = Effect.gen(function*() {
829
+ * const ref = yield* Machine.start(machine)
830
+ * return yield* ref.state
831
+ * })
832
+ * ```
833
+ *
680
834
  * @see {@link plan} for inspecting the same transition plan without executing it.
681
835
  * @see {@link watch} for classified terminal outcomes.
682
836
  * @category constructors
683
- * @since 4.0.0
837
+ * @since 0.4.0
684
838
  */
685
839
  export const start = internal.start;
686
840
  /**
@@ -707,10 +861,32 @@ export const start = internal.start;
707
861
  * evaluated merely because the runtime was resumed; only ordinary subsequent
708
862
  * transition planning can enter and stabilize states.
709
863
  *
864
+ * **Example**
865
+ *
866
+ * ```ts
867
+ * import { Effect, Schema } from "effect"
868
+ * import { Machine } from "@typeonce/effect-machine"
869
+ *
870
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
871
+ * const States = Machine.defineStates({ Idle })
872
+ * const machine = Machine.make({
873
+ * states: States.states,
874
+ * events: [],
875
+ * initial: () => States.initial.Idle.from()
876
+ * }).handle({ Idle: {} })
877
+ *
878
+ * const resumed = Effect.gen(function*() {
879
+ * const initial = yield* Machine.planInitial(machine)
880
+ * const encoded = yield* Machine.encodeSnapshot(machine, initial.state)
881
+ * const snapshot = yield* Machine.decodeSnapshot(machine, encoded)
882
+ * return yield* Machine.resume(machine, snapshot)
883
+ * })
884
+ * ```
885
+ *
710
886
  * @see {@link decodeSnapshot} for the schema and transport boundary.
711
887
  * @see {@link start} for ordinary initial startup.
712
888
  * @category constructors
713
- * @since 4.0.0
889
+ * @since 0.4.0
714
890
  */
715
891
  export const resume = internal.resume;
716
892
  //# sourceMappingURL=Machine.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"Machine.js","sourceRoot":"","sources":["../src/Machine.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Machine.js","sourceRoot":"","sources":["../src/Machine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAc9C,OAAO,KAAK,QAAQ,MAAM,+BAA+B,CAAA;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAelE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAW,iBAAiB,CAAA;AAK/C;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAa7B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAiB,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAA;AAEtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAU,EAAqB,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,kBAAkB,CAAA;AA8IxH,OAAO;AACL;;;;;;GAMG;AACH,uBAAuB;AACvB;;;;;;GAMG;AACH,uBAAuB;AACvB;;;;;;GAMG;AACH,wBAAwB;AACxB;;;;;;GAMG;AACH,wBAAwB;AACxB;;;;;;GAMG;AACH,iBAAiB;AACjB;;;;;;GAMG;AACH,YAAY;AACZ;;;;;;GAMG;AACH,YAAY,EACb,MAAM,+BAA+B,CAAA;AAEtC,MAAM,wBAAwB,GAAG,oCAAoC,CAAA;AACrE,MAAM,uBAAuB,GAAG,mCAAmC,CAAA;AAuLnE,MAAM,YAAY,GAAiC,QAAQ,CAAC,YAAY,CAAA;AA8NxE,MAAM,0BAA0B,GAA+C,QAAQ,CAAC,0BAA0B,CAAA;AAClH,MAAM,iCAAiC,GAAkB,MAAM,CAAC,4CAA4C,CAAC,CAAA;AAqlC7G,MAAM,kBAAkB,GAAG,8BAA8B,CAAA;AACzD,MAAM,oCAAoC,GAAG,gDAAgD,CAAA;AAC7F,MAAM,kBAAkB,GAAG,8BAA8B,CAAA;AA60GzD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAqC,QAAQ,CAAC,SAAS,CAAA;AAE7E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GA+BiD,QAAQ,CAAC,OAAO,CAAA;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,MAAM,YAAY,GAAiB,QAAQ,CAAC,YAAY,CAAA;AA6E/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,CAAC,MAAM,IAAI,GAAS,QAAQ,CAAC,IAAI,CAAA;AAMvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,MAAM,KAAK,GAIS,QAAQ,CAAC,KAAK,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,CAAC,MAAM,cAAc,GAmCvB,QAAQ,CAAC,cAAc,CAAA;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,CAAC,MAAM,cAAc,GAmCvB,QAAQ,CAAC,cAAc,CAAA;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,CAAC,MAAM,MAAM,GA2Cf,QAAQ,CAAC,MAAM,CAAA;AAuCnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,MAAM,YAAY,GAKrB,QAAQ,CAAC,YAAY,CAAA;AAEzB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,KAAK,GAIsB,QAAQ,CAAC,KAAK,CAAA;AAkCtD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,KAAK,GAII,QAAQ,CAAC,KAAK,CAAA;AASpC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,aAAa,GA2JtB,QAAQ,CAAC,aAAa,CAAA;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,MAAM,WAAW,GAsEpB,QAAQ,CAAC,WAAW,CAAA;AAExB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,UAAU,GAMnB,QAAQ,CAAC,UAAU,CAAA;AAEvB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAM9B,QAAQ,CAAC,qBAAqB,CAAA;AAElC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAG9B,QAAQ,CAAC,mBAAmB,CAAA;AAE9B;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,aAAa,GAQtB,QAAQ,CAAC,aAAa,CAAA;AAE1B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GA+BgC,QAAQ,CAAC,OAAO,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,CAAC,MAAM,IAAI,GAqEb,QAAQ,CAAC,IAAI,CAAA;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,MAAM,MAAM,GAEoC,QAAQ,CAAC,MAAM,CAAA;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,KAAK,GAiB2E,QAAQ,CAAC,KAAK,CAAA;AAE3G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,UAAU,GAGgC,QAAQ,CAAC,UAAU,CAAA;AAE1E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,KAAK,GAChB,QAAQ,CAAC,KAAK,CAAA;AAEhB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAAuD,QAAQ,CAAC,YAAY,CAAA;AAErG;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,KAAK,GAsCd,QAAQ,CAAC,KAAK,CAAA;AAElB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GASf,QAAQ,CAAC,MAAM,CAAA;AAEnB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAGlB,QAAQ,CAAC,SAAS,CAAA;AAEtB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAEyC,QAAQ,CAAC,KAAK,CAAA;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,CAAC,MAAM,KAAK,GAwDd,QAAQ,CAAC,KAAK,CAAA;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,CAAC,MAAM,MAAM,GAkDf,QAAQ,CAAC,MAAM,CAAA"}
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Serializable structural metadata for state-owned machine activities.
3
3
  *
4
- * @since 4.0.0
4
+ * @since 0.4.0
5
5
  */
6
6
  /** @internal */
7
7
  export declare const ActivityMetadataTypeId: unique symbol;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Serializable structural metadata for state-owned machine activities.
3
3
  *
4
- * @since 4.0.0
4
+ * @since 0.4.0
5
5
  */
6
6
  /** @internal */
7
7
  export const ActivityMetadataTypeId = Symbol.for("effect/Machine/ActivityMetadata");
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Atom bridge for running machines.
3
3
  *
4
- * @since 4.0.0
4
+ * @since 0.4.0
5
5
  */
6
6
  import * as Option from "effect/Option";
7
7
  import type * as Schema from "effect/Schema";
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Atom bridge for running machines.
3
3
  *
4
- * @since 4.0.0
4
+ * @since 0.4.0
5
5
  */
6
6
  import * as Data from "effect/Data";
7
7
  import * as Effect from "effect/Effect";
@@ -19,7 +19,7 @@ export declare namespace CommitResult {
19
19
  * Indicates that the request id and checkpoint were committed atomically.
20
20
  *
21
21
  * @category models
22
- * @since 4.0.0
22
+ * @since 0.4.0
23
23
  */
24
24
  interface Committed {
25
25
  readonly _tag: "Committed";
@@ -28,7 +28,7 @@ export declare namespace CommitResult {
28
28
  * Indicates that the request id was already committed.
29
29
  *
30
30
  * @category models
31
- * @since 4.0.0
31
+ * @since 0.4.0
32
32
  */
33
33
  interface Duplicate {
34
34
  readonly _tag: "Duplicate";
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Runs Effect machines as persisted Cluster entities.
3
3
  *
4
- * @since 4.0.0
4
+ * @since 0.4.0
5
5
  */
6
6
  import * as Cause from "effect/Cause";
7
7
  import * as Context from "effect/Context";
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Internal machine command collection.
3
3
  *
4
- * @since 4.0.0
4
+ * @since 0.4.0
5
5
  */
6
6
  import type { Command, Enqueue, Machine } from "../../Machine.js";
7
7
  export type RuntimeCommand = Command;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Internal machine command collection.
3
3
  *
4
- * @since 4.0.0
4
+ * @since 0.4.0
5
5
  */
6
6
  import { decodeEmitSync, decodeEventSync } from "./protocol.js";
7
7
  const targetBuilderCache = new WeakMap();
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Internal process-side machine command execution.
3
3
  *
4
- * @since 4.0.0
4
+ * @since 0.4.0
5
5
  */
6
6
  import * as Effect from "effect/Effect";
7
7
  import type { Machine, Runtime } from "../../Machine.js";
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Internal process-side machine command execution.
3
3
  *
4
- * @since 4.0.0
4
+ * @since 0.4.0
5
5
  */
6
6
  import * as Effect from "effect/Effect";
7
7
  import { decodeEmit, decodeEvent } from "./protocol.js";