@typeonce/effect-machine 0.15.0 → 0.17.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 (85) hide show
  1. package/README.md +115 -95
  2. package/dist/Machine.d.ts +464 -337
  3. package/dist/Machine.d.ts.map +1 -1
  4. package/dist/Machine.js +72 -107
  5. package/dist/Machine.js.map +1 -1
  6. package/dist/internal/machine/activities.d.ts +2 -0
  7. package/dist/internal/machine/activities.d.ts.map +1 -1
  8. package/dist/internal/machine/activities.js +4 -0
  9. package/dist/internal/machine/activities.js.map +1 -1
  10. package/dist/internal/machine/atom.d.ts +7 -7
  11. package/dist/internal/machine/atom.d.ts.map +1 -1
  12. package/dist/internal/machine/atom.js.map +1 -1
  13. package/dist/internal/machine/cluster.d.ts +2 -2
  14. package/dist/internal/machine/cluster.d.ts.map +1 -1
  15. package/dist/internal/machine/cluster.js +6 -5
  16. package/dist/internal/machine/cluster.js.map +1 -1
  17. package/dist/internal/machine/executionPlan.d.ts.map +1 -1
  18. package/dist/internal/machine/executionPlan.js +16 -4
  19. package/dist/internal/machine/executionPlan.js.map +1 -1
  20. package/dist/internal/machine/invocation.d.ts +1 -1
  21. package/dist/internal/machine/invocation.d.ts.map +1 -1
  22. package/dist/internal/machine/invocation.js +25 -3
  23. package/dist/internal/machine/invocation.js.map +1 -1
  24. package/dist/internal/machine/invocationEvent.d.ts +8 -0
  25. package/dist/internal/machine/invocationEvent.d.ts.map +1 -1
  26. package/dist/internal/machine/invocationEvent.js +8 -0
  27. package/dist/internal/machine/invocationEvent.js.map +1 -1
  28. package/dist/internal/machine/machine.d.ts +8 -6
  29. package/dist/internal/machine/machine.d.ts.map +1 -1
  30. package/dist/internal/machine/machine.js +308 -71
  31. package/dist/internal/machine/machine.js.map +1 -1
  32. package/dist/internal/machine/planner.d.ts +26 -4
  33. package/dist/internal/machine/planner.d.ts.map +1 -1
  34. package/dist/internal/machine/planner.js +76 -31
  35. package/dist/internal/machine/planner.js.map +1 -1
  36. package/dist/internal/machine/runtime.d.ts +1 -0
  37. package/dist/internal/machine/runtime.d.ts.map +1 -1
  38. package/dist/internal/machine/runtime.js +25 -16
  39. package/dist/internal/machine/runtime.js.map +1 -1
  40. package/dist/internal/machine/stateDefinition.d.ts.map +1 -1
  41. package/dist/internal/machine/stateDefinition.js +14 -0
  42. package/dist/internal/machine/stateDefinition.js.map +1 -1
  43. package/dist/internal/machine/topology.d.ts +20 -0
  44. package/dist/internal/machine/topology.d.ts.map +1 -1
  45. package/dist/internal/machine/topology.js +33 -6
  46. package/dist/internal/machine/topology.js.map +1 -1
  47. package/dist/internal/testing/machine/finiteModel.d.ts.map +1 -1
  48. package/dist/internal/testing/machine/finiteModel.js +15 -20
  49. package/dist/internal/testing/machine/finiteModel.js.map +1 -1
  50. package/dist/internal/testing/machine/transitionCoverage.d.ts.map +1 -1
  51. package/dist/internal/testing/machine/transitionCoverage.js +8 -2
  52. package/dist/internal/testing/machine/transitionCoverage.js.map +1 -1
  53. package/dist/internal/testing/machine/verification.d.ts.map +1 -1
  54. package/dist/internal/testing/machine/verification.js +6 -0
  55. package/dist/internal/testing/machine/verification.js.map +1 -1
  56. package/dist/testing/MachineTest.d.ts +13 -12
  57. package/dist/testing/MachineTest.d.ts.map +1 -1
  58. package/dist/testing/MachineTest.js +5 -8
  59. package/dist/testing/MachineTest.js.map +1 -1
  60. package/dist/unstable/cluster/ClusterMachine.d.ts +2 -2
  61. package/dist/unstable/cluster/ClusterMachine.d.ts.map +1 -1
  62. package/dist/unstable/cluster/ClusterMachine.js.map +1 -1
  63. package/dist/unstable/reactivity/AtomMachine.d.ts +12 -12
  64. package/dist/unstable/reactivity/AtomMachine.d.ts.map +1 -1
  65. package/dist/unstable/reactivity/AtomMachine.js.map +1 -1
  66. package/docs/agent-guide.md +182 -159
  67. package/package.json +1 -1
  68. package/src/Machine.ts +1073 -700
  69. package/src/internal/machine/activities.ts +7 -0
  70. package/src/internal/machine/atom.ts +20 -15
  71. package/src/internal/machine/cluster.ts +14 -9
  72. package/src/internal/machine/executionPlan.ts +14 -4
  73. package/src/internal/machine/invocation.ts +39 -4
  74. package/src/internal/machine/invocationEvent.ts +16 -0
  75. package/src/internal/machine/machine.ts +460 -86
  76. package/src/internal/machine/planner.ts +106 -30
  77. package/src/internal/machine/runtime.ts +61 -25
  78. package/src/internal/machine/stateDefinition.ts +39 -0
  79. package/src/internal/machine/topology.ts +59 -2
  80. package/src/internal/testing/machine/finiteModel.ts +18 -21
  81. package/src/internal/testing/machine/transitionCoverage.ts +8 -2
  82. package/src/internal/testing/machine/verification.ts +11 -0
  83. package/src/testing/MachineTest.ts +16 -11
  84. package/src/unstable/cluster/ClusterMachine.ts +8 -4
  85. package/src/unstable/reactivity/AtomMachine.ts +19 -12
package/src/Machine.ts CHANGED
@@ -53,7 +53,9 @@ declare const MachineTypeId: unique symbol
53
53
  declare const EventConstructionTypeId: unique symbol
54
54
  declare const EmittedEventConstructionTypeId: unique symbol
55
55
  declare const EventProtocolTypeId: unique symbol
56
- declare const TransitionCaseTypeId: unique symbol
56
+ declare const ParentModeTypeId: unique symbol
57
+
58
+ const ParentTypeId = "~effect/Machine/Parent"
57
59
 
58
60
  const ChildMachineLogicTypeId: typeof internal.ChildMachineLogicTypeId = internal.ChildMachineLogicTypeId
59
61
 
@@ -185,16 +187,16 @@ export interface Machine<
185
187
  readonly emittedEvents: Machine.EventProtocol<"emitted", Emits>
186
188
 
187
189
  /**
188
- * Public input events accepted by an owning machine when this machine is
189
- * running as a child.
190
+ * Declared owning-machine protocol, or `undefined` when this machine does
191
+ * not communicate with its owner.
190
192
  *
191
- * The protocol types the optional `parent` machine target exposed to
192
- * handlers and is checked against a concrete parent's public events at
193
- * composition boundaries.
193
+ * Required parents make the machine child-only and expose a non-optional
194
+ * `parent` target to handlers. Optional parents keep root execution valid
195
+ * and expose `parent` as possibly absent.
194
196
  *
195
- * @since 0.10.0
197
+ * @since 0.17.0
196
198
  */
197
- readonly parentEvents: Machine.EventProtocol<"public", ParentEvents>
199
+ readonly parent: Machine.ParentDeclarationOf<ParentEvents>
198
200
 
199
201
  /**
200
202
  * Optional schema used to decode the machine input before initialization.
@@ -221,15 +223,6 @@ export interface Machine<
221
223
  /** @internal */
222
224
  readonly handlers: Machine.StateConfigs<States, Events, Emits, UnhandledStates, Machine.TagOf<Events[number]>, E, R>
223
225
 
224
- /**
225
- * Machine-bound equivalent of {@link invoke}. Both forms preserve this
226
- * machine's public input and parent protocols in invocation callbacks;
227
- * `Machine.invoke(...)` inside `handle(...)` is the canonical inline form.
228
- *
229
- * @since 0.11.0
230
- */
231
- readonly invoke: Invoker<States, Events, Emits, InputEvents, ParentEvents>
232
-
233
226
  /** @internal */
234
227
  readonly initial: (...args: [...Machine.InputArgs<Input>]) => Machine.InitialResult<States, InitialE, InitialR>
235
228
  /** @internal */
@@ -472,22 +465,61 @@ export interface MachineTarget<in Event> {
472
465
  readonly send: (event: Event) => Effect.Effect<void, StoppedError>
473
466
  }
474
467
 
468
+ /**
469
+ * Availability declared for an owning-machine target.
470
+ *
471
+ * @category models
472
+ * @since 0.17.0
473
+ */
474
+ export type ParentMode = "required" | "optional"
475
+
476
+ /**
477
+ * Owning-machine protocol declared by {@link parent} or
478
+ * {@link optionalParent}.
479
+ *
480
+ * @category models
481
+ * @since 0.17.0
482
+ */
483
+ export interface Parent<Mode extends ParentMode, Events extends ReadonlyArray<Machine.TaggedSchema>> {
484
+ readonly [ParentTypeId]: typeof ParentTypeId
485
+ readonly mode: Mode
486
+ readonly events: Machine.EventProtocol<"public", Events>
487
+ }
488
+
489
+ /**
490
+ * Namespace containing type-level members associated with {@link Parent}.
491
+ *
492
+ * @category models
493
+ * @since 0.17.0
494
+ */
495
+ export declare namespace Parent {
496
+ /** Any owning-machine protocol declaration. */
497
+ export type Any = Parent<ParentMode, ReadonlyArray<Machine.TaggedSchema>>
498
+ }
499
+
475
500
  /**
476
501
  * Machine targets available while evaluating machine behavior.
477
502
  *
478
503
  * @category models
479
504
  * @since 0.12.0
480
505
  */
481
- export interface MachineReferences<
506
+ export type MachineReferences<
482
507
  InputEvents extends ReadonlyArray<Machine.TaggedSchema>,
483
508
  ParentEvents extends ReadonlyArray<Machine.TaggedSchema>
484
- > {
485
- /** Target for the current machine. Sending queues a later mailbox event. */
486
- readonly self: MachineTarget<Machine.EventInputOf<InputEvents>>
487
-
488
- /** Target for the owning machine, or `undefined` when running as a root. */
489
- readonly parent: MachineTarget<Machine.EventInputOf<ParentEvents>> | undefined
490
- }
509
+ > =
510
+ & {
511
+ /** Target for the current machine. Sending queues a later mailbox event. */
512
+ readonly self: MachineTarget<Machine.EventInputOf<InputEvents>>
513
+ }
514
+ & (Machine.ParentModeOf<ParentEvents> extends "required" ? {
515
+ /** Required target for the machine that owns this child. */
516
+ readonly parent: MachineTarget<Machine.EventInputOf<ParentEvents>>
517
+ } :
518
+ Machine.ParentModeOf<ParentEvents> extends "optional" ? {
519
+ /** Target for the owning machine, or `undefined` when running as a root. */
520
+ readonly parent: MachineTarget<Machine.EventInputOf<ParentEvents>> | undefined
521
+ } :
522
+ {})
491
523
 
492
524
  /**
493
525
  * Synchronous commands available while a machine transition is being
@@ -601,6 +633,8 @@ type IncompatibleRuntime<Requirements, Events, Emits> = Requirements extends Run
601
633
 
602
634
  const InvokeTypeId: typeof internal.InvokeTypeId = internal.InvokeTypeId
603
635
  const TransitionTypeId: typeof internal.TransitionTypeId = internal.TransitionTypeId
636
+ declare const TransitionBuilderTypeId: unique symbol
637
+ declare const InitialBuilderTypeId: unique symbol
604
638
 
605
639
  type StateDefinitionError<
606
640
  Message extends string,
@@ -726,6 +760,29 @@ type ValidateOutputSchema<Node> = "output" extends keyof Node ? Node extends { r
726
760
  : StateDefinitionError<"State output must be a schema">
727
761
  : unknown
728
762
 
763
+ type SelectorChildKey<Children extends Machine.StateSchemas> = ActiveStateKey<Children> | ChoiceStateKey<Children>
764
+
765
+ type ValidateInitialSelectorChild<Children extends Machine.StateSchemas, Path extends PropertyKey> = "initial" extends
766
+ SelectorChildKey<Children> ? StateDefinitionError<
767
+ "Active and choice child states cannot use the reserved target selector key \"initial\"",
768
+ StateDefinitionPath<Extract<Path, string>, "initial">,
769
+ "initial"
770
+ >
771
+ : unknown
772
+
773
+ type ValidateWithSelectorChild<
774
+ Node extends Machine.StateNodeConfig,
775
+ Children extends Machine.StateSchemas,
776
+ Path extends PropertyKey
777
+ > = Node extends { readonly schema: Machine.TaggedSchema } ?
778
+ "with" extends SelectorChildKey<Children> ? StateDefinitionError<
779
+ "Schema-backed compound child states cannot use the reserved local target selector key \"with\"",
780
+ StateDefinitionPath<Extract<Path, string>, "with">,
781
+ "with"
782
+ >
783
+ : unknown
784
+ : unknown
785
+
729
786
  type ValidateStateNodeWithChildren<
730
787
  Node extends Machine.StateNodeConfig,
731
788
  Children,
@@ -733,8 +790,9 @@ type ValidateStateNodeWithChildren<
733
790
  > = Children extends Machine.StateSchemas ?
734
791
  Node extends { readonly type: "final" } ? StateDefinitionError<"Final states cannot declare child states">
735
792
  : Node extends { readonly type: "parallel" } ?
736
- "initial" extends keyof Node ? StateDefinitionError<"Parallel states cannot declare an initial child">
737
- : { readonly states: ValidateStateTree<Children, true, Extract<Path, string>> } & ValidateOutputSchema<Node>
793
+ & ValidateInitialSelectorChild<Children, Path>
794
+ & ("initial" extends keyof Node ? StateDefinitionError<"Parallel states cannot declare an initial child">
795
+ : { readonly states: ValidateStateTree<Children, true, Extract<Path, string>> } & ValidateOutputSchema<Node>)
738
796
  : "output" extends keyof Node ? StateDefinitionError<"Only final and parallel states can declare output">
739
797
  : ValidateCompoundStateNode<Node, Children, Path>
740
798
  : StateDefinitionError<"Child states must be a state tree">
@@ -744,9 +802,12 @@ type ValidateCompoundStateNode<
744
802
  Children extends Machine.StateSchemas,
745
803
  Path extends PropertyKey
746
804
  > = Node extends { readonly initial: infer Initial } ?
747
- Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children> ? {
748
- readonly states: ValidateStateTree<Children, true, Extract<Path, string>>
749
- }
805
+ Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children> ?
806
+ & ValidateInitialSelectorChild<Children, Path>
807
+ & ValidateWithSelectorChild<Node, Children, Path>
808
+ & {
809
+ readonly states: ValidateStateTree<Children, true, Extract<Path, string>>
810
+ }
750
811
  : StateDefinitionError<
751
812
  "Compound initial must be one of its direct child keys",
752
813
  Path,
@@ -1953,10 +2014,10 @@ export declare namespace Inspection {
1953
2014
  readonly sessionId: string
1954
2015
  readonly owner: Subject
1955
2016
  readonly ownerPath: string
1956
- readonly kind: "Effect" | "Timer"
2017
+ readonly kind: "Effect" | "Stream" | "Timer"
1957
2018
  }
1958
2019
 
1959
- /** Announces an Effect or timer invocation starting. */
2020
+ /** Announces an Effect, Stream, or timer invocation starting. */
1960
2021
  export interface ActivityStarted extends Base {
1961
2022
  readonly _tag: "ActivityStarted"
1962
2023
  readonly activity: Activity
@@ -2466,6 +2527,35 @@ export declare namespace Machine {
2466
2527
  readonly parentEvents: ParentEvents
2467
2528
  }
2468
2529
 
2530
+ /** @internal Carries parent availability without widening the event tuple. */
2531
+ export type ParentEventSchemas<
2532
+ Mode extends ParentMode,
2533
+ Events extends ReadonlyArray<TaggedSchema>
2534
+ > = Events & { readonly [ParentModeTypeId]: Mode }
2535
+
2536
+ /** Extracts the parent availability encoded in a machine event tuple. */
2537
+ export type ParentModeOf<Events extends ReadonlyArray<TaggedSchema>> = Events extends
2538
+ { readonly [ParentModeTypeId]: infer Mode extends ParentMode } ? Mode
2539
+ : Events extends readonly [] ? "none"
2540
+ : "optional"
2541
+
2542
+ /** Extracts the event schemas declared by an owning-machine protocol. */
2543
+ export type ParentEventsOf<Declaration extends Parent.Any | undefined> = Declaration extends Parent<
2544
+ infer Mode,
2545
+ infer Events
2546
+ > ? ParentEventSchemas<Mode, Events>
2547
+ : readonly []
2548
+
2549
+ /** Extracts the owning-machine declaration carried by a machine. */
2550
+ export type ParentDeclarationOf<Events extends ReadonlyArray<TaggedSchema>> = ParentModeOf<Events> extends
2551
+ infer Mode ? Mode extends ParentMode ? Parent<Mode, Events> : undefined
2552
+ : never
2553
+
2554
+ /** Constraint applied to APIs that create an independent root runtime. */
2555
+ export type RootCompatible<Events extends ReadonlyArray<TaggedSchema>> = ParentModeOf<Events> extends "required"
2556
+ ? never
2557
+ : unknown
2558
+
2469
2559
  /**
2470
2560
  * Any schema-first machine.
2471
2561
  *
@@ -2486,7 +2576,7 @@ export declare namespace Machine {
2486
2576
  readonly events: EventProtocol.Any<"public">
2487
2577
  readonly internalEvents: EventProtocol.Any<"internal">
2488
2578
  readonly emittedEvents: EventProtocol.Any<"emitted">
2489
- readonly parentEvents: EventProtocol.Any<"public">
2579
+ readonly parent: Parent.Any | undefined
2490
2580
  readonly input: Schema.Top | undefined
2491
2581
  readonly id: string | undefined
2492
2582
  /** @internal */
@@ -2496,8 +2586,6 @@ export declare namespace Machine {
2496
2586
  /** @internal */
2497
2587
  readonly handlers: any
2498
2588
  /** @internal */
2499
- readonly invoke: any
2500
- /** @internal */
2501
2589
  readonly initial: any
2502
2590
  /** @internal */
2503
2591
  readonly initialDefinition: InitialDefinition
@@ -2613,6 +2701,9 @@ export declare namespace Machine {
2613
2701
  /** Extracts the public input protocol required from an owning machine. */
2614
2702
  export type ParentEvents<M extends Any> = M[typeof MachineTypeId]["parentEvents"]
2615
2703
 
2704
+ /** Extracts whether a machine requires or optionally accepts an owner. */
2705
+ export type ParentAvailability<M extends Any> = ParentModeOf<M[typeof MachineTypeId]["parentEvents"]>
2706
+
2616
2707
  /** Extracts an internal event schema tuple from the complete and public protocols. */
2617
2708
  export type InternalEventSchemas<
2618
2709
  Events extends ReadonlyArray<TaggedSchema>,
@@ -3252,7 +3343,7 @@ export declare namespace Machine {
3252
3343
  | {
3253
3344
  readonly type: "invoke"
3254
3345
  readonly id: string
3255
- readonly outcome: "done" | "failure" | "snapshot"
3346
+ readonly outcome: "element" | "done" | "failure" | "snapshot"
3256
3347
  }
3257
3348
 
3258
3349
  /** Static topology selected by a transition branch. */
@@ -3274,16 +3365,12 @@ export declare namespace Machine {
3274
3365
  readonly selection: TransitionTargetSelection<Path | undefined>
3275
3366
  }
3276
3367
  | {
3277
- readonly type: "case"
3368
+ readonly type: "branch"
3369
+ readonly key: string
3278
3370
  readonly title: string
3279
3371
  readonly target: Path | undefined
3280
3372
  readonly selection: TransitionTargetSelection<Path | undefined>
3281
3373
  }
3282
- | {
3283
- readonly type: "otherwise"
3284
- readonly target: Path | undefined
3285
- readonly selection: TransitionTargetSelection<Path | undefined>
3286
- }
3287
3374
 
3288
3375
  /** The statically selected root entry for machine startup. */
3289
3376
  export interface InitialDefinition<Path extends string = string> {
@@ -3296,8 +3383,8 @@ export declare namespace Machine {
3296
3383
  *
3297
3384
  * **Details**
3298
3385
  *
3299
- * Every branch exposes its selected target without executing its predicate
3300
- * or resolver. A compound local or branch target covers its descendants;
3386
+ * Every branch exposes its selected target without executing its resolver.
3387
+ * A compound local or branch target covers its descendants;
3301
3388
  * `undefined` identifies an explicitly targetless branch.
3302
3389
  *
3303
3390
  * @category models
@@ -3311,6 +3398,7 @@ export declare namespace Machine {
3311
3398
  readonly source: SourcePath
3312
3399
  readonly trigger: TransitionTrigger<EventTag>
3313
3400
  readonly reenter: boolean
3401
+ readonly acceptance: TransitionAcceptance
3314
3402
  readonly branches: ReadonlyArray<TransitionBranch<TargetPath>>
3315
3403
  }
3316
3404
 
@@ -3343,6 +3431,8 @@ export declare namespace Machine {
3343
3431
  readonly reenter: boolean
3344
3432
  /** Zero-based index of the selected static branch. */
3345
3433
  readonly branchIndex: number
3434
+ /** Stable key of a named branch, or `undefined` for a direct transition. */
3435
+ readonly branchKey: string | undefined
3346
3436
  /** Path returned by the handler, including a choice or history pseudo-state. */
3347
3437
  readonly target: TargetPath | undefined
3348
3438
  /**
@@ -4187,6 +4277,24 @@ export declare namespace Machine {
4187
4277
  readonly [Topology.NoTargetTypeId]: typeof Topology.NoTargetTypeId
4188
4278
  }
4189
4279
 
4280
+ /**
4281
+ * Opaque result returned when a declinable transition does not accept the
4282
+ * current event or lifecycle outcome.
4283
+ *
4284
+ * Declining selects no transition and discards operations enqueued by that
4285
+ * resolver. Hierarchical event and eventless dispatch continues with the
4286
+ * next eligible ancestor candidate.
4287
+ *
4288
+ * @category models
4289
+ * @since 0.17.0
4290
+ */
4291
+ export interface Declined {
4292
+ readonly [Topology.DeclinedTypeId]: typeof Topology.DeclinedTypeId
4293
+ }
4294
+
4295
+ /** Static acceptance contract of one transition definition. */
4296
+ export type TransitionAcceptance = "required" | "declinable"
4297
+
4190
4298
  /**
4191
4299
  * Transition instruction that restores a history pseudo-state's parent.
4192
4300
  *
@@ -4396,11 +4504,14 @@ export declare namespace Machine {
4396
4504
  readonly "~effect/Machine/TargetSelectionResult"?: Types.Covariant<Result>
4397
4505
  }
4398
4506
 
4399
- type SelectionMethod<Builder, Path extends string, Kind extends Topology.TargetSelectionKind = "state"> = () =>
4507
+ type SelectionValue<Builder, Path extends string, Kind extends Topology.TargetSelectionKind = "state"> =
4400
4508
  TargetSelection<Builder, Path, Kind>
4401
4509
 
4510
+ type SelectionMethod<Builder, Path extends string, Kind extends Topology.TargetSelectionKind = "state"> = () =>
4511
+ SelectionValue<Builder, Path, Kind>
4512
+
4402
4513
  type InitialSelectionMethod<Builder, Path extends string> = Builder extends { readonly initial: infer Initial } ? {
4403
- readonly initial: SelectionMethod<Initial, Path, "initial">
4514
+ readonly initial: SelectionValue<Initial, Path, "initial">
4404
4515
  }
4405
4516
  : {}
4406
4517
 
@@ -4480,7 +4591,7 @@ export declare namespace Machine {
4480
4591
  LocalTargetBuilder<States, Source> extends infer Builder ?
4481
4592
  & SelectionTreeWithPrefix<States, Children, Scope, "local", Builder>
4482
4593
  & ("with" extends keyof Builder ? {
4483
- readonly with: SelectionMethod<Builder["with"], Scope>
4594
+ readonly with: SelectionValue<Builder["with"], Scope>
4484
4595
  }
4485
4596
  : {})
4486
4597
  : {}
@@ -4494,7 +4605,7 @@ export declare namespace Machine {
4494
4605
  Builder
4495
4606
  > = {
4496
4607
  readonly [Key in Extract<HistoryContainingKey<States>, keyof Builder>]: States[Key] extends HistoryStateNodeConfig ?
4497
- SelectionMethod<
4608
+ SelectionValue<
4498
4609
  Builder[Key],
4499
4610
  JoinPath<Prefix, Key>,
4500
4611
  "history"
@@ -4508,12 +4619,17 @@ export declare namespace Machine {
4508
4619
  : never
4509
4620
  }
4510
4621
 
4511
- /** Definition-time topology selector available to an ordinary transition. */
4622
+ /**
4623
+ * Definition-time topology selector available to an ordinary transition.
4624
+ * Topology-only instructions (`none`, declared `initial` and history
4625
+ * selections, and `local.with`) are values. State and choice destinations
4626
+ * remain callable selection methods.
4627
+ */
4512
4628
  export interface TargetSelector<
4513
4629
  States extends StateSchemas,
4514
4630
  Source extends StateNodeIdentifier<States>
4515
4631
  > {
4516
- readonly none: SelectionMethod<TargetBuilder<States, Source>["none"], never, "none">
4632
+ readonly none: SelectionValue<TargetBuilder<States, Source>["none"], never, "none">
4517
4633
  readonly local: LocalTargetSelector<States, Source>
4518
4634
  readonly branch: BranchTargetSelector<States, Source>
4519
4635
  readonly full: FullTargetSelector<States>
@@ -4521,10 +4637,10 @@ export declare namespace Machine {
4521
4637
  }
4522
4638
 
4523
4639
  /** Definition-time selector that can choose only a valid top-level initial entry. */
4524
- export type InitialSelector<States extends StateSchemas> = {
4640
+ type InitialTargetSelector<States extends StateSchemas> = {
4525
4641
  readonly [Key in Extract<ActiveStateKey<States>, keyof InitialBuilder<States>>]: States[Key] extends
4526
4642
  { readonly states: StateSchemas } ? {
4527
- readonly initial: SelectionMethod<InitialBuilder<States>[Key], Key, "initial">
4643
+ readonly initial: SelectionValue<InitialBuilder<States>[Key], Key, "initial">
4528
4644
  }
4529
4645
  : SelectionMethod<InitialBuilder<States>[Key], Key>
4530
4646
  }
@@ -4535,7 +4651,7 @@ export declare namespace Machine {
4535
4651
  * @category models
4536
4652
  * @since 0.4.0
4537
4653
  */
4538
- export interface HandlerContext<
4654
+ export type HandlerContext<
4539
4655
  States extends StateSchemas,
4540
4656
  Events extends ReadonlyArray<TaggedSchema>,
4541
4657
  Emits extends ReadonlyArray<TaggedSchema>,
@@ -4545,7 +4661,7 @@ export declare namespace Machine {
4545
4661
  R,
4546
4662
  InputEvents extends ReadonlyArray<TaggedSchema> = Events,
4547
4663
  ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
4548
- > extends MachineReferences<InputEvents, ParentEvents> {
4664
+ > = MachineReferences<InputEvents, ParentEvents> & {
4549
4665
  readonly state: StateByIdentifier<States, StateId>
4550
4666
  readonly containingState: ParentStateValue<States, StateId>
4551
4667
  readonly ancestors: ParentStateValues<States, StateId>
@@ -4568,14 +4684,14 @@ export declare namespace Machine {
4568
4684
  * @category models
4569
4685
  * @since 0.4.0
4570
4686
  */
4571
- export interface StateActionContext<
4687
+ export type StateActionContext<
4572
4688
  States extends StateSchemas,
4573
4689
  Events extends ReadonlyArray<TaggedSchema>,
4574
4690
  Emits extends ReadonlyArray<TaggedSchema>,
4575
4691
  StateId extends StateIdentifier<States>,
4576
4692
  InputEvents extends ReadonlyArray<TaggedSchema> = Events,
4577
4693
  ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
4578
- > extends MachineReferences<InputEvents, ParentEvents> {
4694
+ > = MachineReferences<InputEvents, ParentEvents> & {
4579
4695
  readonly state: StateByIdentifier<States, StateId>
4580
4696
  readonly containingState: ParentStateValue<States, StateId>
4581
4697
  readonly ancestors: ParentStateValues<States, StateId>
@@ -4588,14 +4704,14 @@ export declare namespace Machine {
4588
4704
  * @category models
4589
4705
  * @since 0.4.0
4590
4706
  */
4591
- export interface InvokeContext<
4707
+ export type InvokeContext<
4592
4708
  States extends StateSchemas,
4593
4709
  Events extends ReadonlyArray<TaggedSchema>,
4594
4710
  Emits extends ReadonlyArray<TaggedSchema>,
4595
4711
  StateId extends StateIdentifier<States>,
4596
4712
  InputEvents extends ReadonlyArray<TaggedSchema> = Events,
4597
4713
  ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
4598
- > extends MachineReferences<InputEvents, ParentEvents> {
4714
+ > = MachineReferences<InputEvents, ParentEvents> & {
4599
4715
  readonly state: StateByIdentifier<States, StateId>
4600
4716
  readonly containingState: ParentStateValue<States, StateId>
4601
4717
  readonly ancestors: ParentStateValues<States, StateId>
@@ -4608,7 +4724,7 @@ export declare namespace Machine {
4608
4724
  * @category models
4609
4725
  * @since 0.4.0
4610
4726
  */
4611
- export interface InvokeSnapshotContext<
4727
+ export type InvokeSnapshotContext<
4612
4728
  States extends StateSchemas,
4613
4729
  Events extends ReadonlyArray<TaggedSchema>,
4614
4730
  Emits extends ReadonlyArray<TaggedSchema>,
@@ -4618,7 +4734,7 @@ export declare namespace Machine {
4618
4734
  Output,
4619
4735
  InputEvents extends ReadonlyArray<TaggedSchema> = Events,
4620
4736
  ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
4621
- > extends MachineReferences<InputEvents, ParentEvents> {
4737
+ > = MachineReferences<InputEvents, ParentEvents> & {
4622
4738
  readonly id: string
4623
4739
  readonly state: StateByIdentifier<States, StateId>
4624
4740
  readonly containingState: ParentStateValue<States, StateId>
@@ -4633,7 +4749,7 @@ export declare namespace Machine {
4633
4749
  * @category models
4634
4750
  * @since 0.4.0
4635
4751
  */
4636
- export interface InvokeDoneContext<
4752
+ export type InvokeDoneContext<
4637
4753
  States extends StateSchemas,
4638
4754
  Events extends ReadonlyArray<TaggedSchema>,
4639
4755
  Emits extends ReadonlyArray<TaggedSchema>,
@@ -4641,7 +4757,7 @@ export declare namespace Machine {
4641
4757
  Output,
4642
4758
  InputEvents extends ReadonlyArray<TaggedSchema> = Events,
4643
4759
  ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
4644
- > extends MachineReferences<InputEvents, ParentEvents> {
4760
+ > = MachineReferences<InputEvents, ParentEvents> & {
4645
4761
  readonly id: string
4646
4762
  readonly state: StateByIdentifier<States, StateId>
4647
4763
  readonly containingState: ParentStateValue<States, StateId>
@@ -4651,8 +4767,27 @@ export declare namespace Machine {
4651
4767
  readonly output: Output
4652
4768
  }
4653
4769
 
4770
+ /** Context passed to a Stream invocation's element transition. */
4771
+ export type InvokeElementContext<
4772
+ States extends StateSchemas,
4773
+ Events extends ReadonlyArray<TaggedSchema>,
4774
+ Emits extends ReadonlyArray<TaggedSchema>,
4775
+ StateId extends StateIdentifier<States>,
4776
+ Element,
4777
+ InputEvents extends ReadonlyArray<TaggedSchema> = Events,
4778
+ ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
4779
+ > = MachineReferences<InputEvents, ParentEvents> & {
4780
+ readonly id: string
4781
+ readonly state: StateByIdentifier<States, StateId>
4782
+ readonly containingState: ParentStateValue<States, StateId>
4783
+ readonly ancestors: ParentStateValues<States, StateId>
4784
+ readonly snapshot: Snapshot<States>
4785
+ readonly target: TargetBuilder<States, StateId>
4786
+ readonly element: Element
4787
+ }
4788
+
4654
4789
  /** Context passed to an invocation typed-failure transition. */
4655
- export interface InvokeFailureContext<
4790
+ export type InvokeFailureContext<
4656
4791
  States extends StateSchemas,
4657
4792
  Events extends ReadonlyArray<TaggedSchema>,
4658
4793
  Emits extends ReadonlyArray<TaggedSchema>,
@@ -4660,7 +4795,7 @@ export declare namespace Machine {
4660
4795
  Error,
4661
4796
  InputEvents extends ReadonlyArray<TaggedSchema> = Events,
4662
4797
  ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
4663
- > extends MachineReferences<InputEvents, ParentEvents> {
4798
+ > = MachineReferences<InputEvents, ParentEvents> & {
4664
4799
  readonly id: string
4665
4800
  readonly state: StateByIdentifier<States, StateId>
4666
4801
  readonly containingState: ParentStateValue<States, StateId>
@@ -4676,14 +4811,14 @@ export declare namespace Machine {
4676
4811
  * @category models
4677
4812
  * @since 0.4.0
4678
4813
  */
4679
- export interface AlwaysContext<
4814
+ export type AlwaysContext<
4680
4815
  States extends StateSchemas,
4681
4816
  Events extends ReadonlyArray<TaggedSchema>,
4682
4817
  Emits extends ReadonlyArray<TaggedSchema>,
4683
4818
  StateId extends StateIdentifier<States>,
4684
4819
  InputEvents extends ReadonlyArray<TaggedSchema> = Events,
4685
4820
  ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
4686
- > extends MachineReferences<InputEvents, ParentEvents> {
4821
+ > = MachineReferences<InputEvents, ParentEvents> & {
4687
4822
  readonly state: StateByIdentifier<States, StateId>
4688
4823
  readonly containingState: ParentStateValue<States, StateId>
4689
4824
  readonly ancestors: ParentStateValues<States, StateId>
@@ -4707,14 +4842,14 @@ export declare namespace Machine {
4707
4842
  * @category models
4708
4843
  * @since 0.4.0
4709
4844
  */
4710
- export interface DoneContext<
4845
+ export type DoneContext<
4711
4846
  States extends StateSchemas,
4712
4847
  Events extends ReadonlyArray<TaggedSchema>,
4713
4848
  Emits extends ReadonlyArray<TaggedSchema>,
4714
4849
  StateId extends StateIdentifier<States>,
4715
4850
  InputEvents extends ReadonlyArray<TaggedSchema> = Events,
4716
4851
  ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
4717
- > extends MachineReferences<InputEvents, ParentEvents> {
4852
+ > = MachineReferences<InputEvents, ParentEvents> & {
4718
4853
  readonly state: StateByIdentifier<States, StateId>
4719
4854
  readonly containingState: ParentStateValue<States, StateId>
4720
4855
  readonly ancestors: ParentStateValues<States, StateId>
@@ -4734,14 +4869,14 @@ export declare namespace Machine {
4734
4869
  }
4735
4870
 
4736
4871
  /** Context passed to a transient choice resolver. There is no `state` value. */
4737
- export interface ChoiceContext<
4872
+ export type ChoiceContext<
4738
4873
  States extends StateSchemas,
4739
4874
  Events extends ReadonlyArray<TaggedSchema>,
4740
4875
  Emits extends ReadonlyArray<TaggedSchema>,
4741
4876
  ChoiceId extends ChoiceIdentifier<States>,
4742
4877
  InputEvents extends ReadonlyArray<TaggedSchema> = Events,
4743
4878
  ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
4744
- > extends MachineReferences<InputEvents, ParentEvents> {
4879
+ > = MachineReferences<InputEvents, ParentEvents> & {
4745
4880
  readonly containingState: StateByIdentifier<
4746
4881
  States,
4747
4882
  Extract<ImmediateParentStateIdentifier<ChoiceId>, StateIdentifier<States>>
@@ -4931,14 +5066,11 @@ export declare namespace Machine {
4931
5066
  * @category utility types
4932
5067
  * @since 0.4.0
4933
5068
  */
4934
- export type EventTransitionReturn<Transition> =
4935
- | (Transition extends { readonly resolve?: infer Resolve } ?
5069
+ export type EventTransitionReturn<Transition> = Transition extends (...args: any) => infer Authored ?
5070
+ Authored extends TransitionBuilderEvidence<infer Result, any> ? Result : never
5071
+ : Transition extends { readonly resolve?: infer Resolve } ?
4936
5072
  NonNullable<Resolve> extends (...args: any) => infer Ret ? Ret : never
4937
- : never)
4938
- | (Transition extends { readonly cases: infer Cases extends ReadonlyArray<unknown> } ?
4939
- EventTransitionReturn<Cases[number]>
4940
- : never)
4941
- | (Transition extends { readonly otherwise: infer Otherwise } ? EventTransitionReturn<Otherwise> : never)
5073
+ : never
4942
5074
  /**
4943
5075
  * Extracts the return value from a state's event handlers.
4944
5076
  *
@@ -5003,6 +5135,15 @@ export declare namespace Machine {
5003
5135
  Effect.Success<Fx>
5004
5136
  >
5005
5137
  : never
5138
+ : Invoke extends { readonly stream: infer Source } ?
5139
+ InvokeFactoryResult<Source> extends infer SourceStream extends Stream.Stream<any, any, any> ? Logic<
5140
+ void,
5141
+ never,
5142
+ Stream.Error<SourceStream>,
5143
+ Stream.Services<SourceStream>,
5144
+ void
5145
+ >
5146
+ : never
5006
5147
  : Invoke extends { readonly after: unknown } ? Logic<void, never, never, never, void>
5007
5148
  : Invoke extends { readonly logic: infer Source } ? InvokeResolvedSource<Source>
5008
5149
  : Invoke extends { readonly child: infer Child } ? ChildMachineLogic<Child>
@@ -5074,6 +5215,7 @@ export declare namespace Machine {
5074
5215
  export type InvokeOutcomeReturn<Invoke> = Invoke extends unknown ?
5075
5216
  | (Invoke extends { readonly onDone?: infer Handler } ? EventTransitionReturn<NonNullable<Handler>> : never)
5076
5217
  | (Invoke extends { readonly onFailure?: infer Handler } ? EventTransitionReturn<NonNullable<Handler>> : never)
5218
+ | (Invoke extends { readonly onElement?: infer Handler } ? EventTransitionReturn<NonNullable<Handler>> : never)
5077
5219
  | (Invoke extends { readonly onSnapshot?: infer Handler } ? EventTransitionReturn<NonNullable<Handler>> : never)
5078
5220
  : never
5079
5221
  /**
@@ -5144,26 +5286,19 @@ export declare namespace Machine {
5144
5286
  | Effect.Services<ChoiceReturn<Config>>
5145
5287
  | InvokeRequirements<Config>
5146
5288
 
5147
- type TransitionWhenContext<Context> = Omit<Context, "target">
5148
-
5149
- /** Type evidence retained by {@link transition} without affecting runtime data. */
5289
+ /** Type evidence retained by an authored transition without affecting runtime data. */
5150
5290
  export interface TransitionTyped<
5151
5291
  States extends StateSchemas,
5152
5292
  Events extends ReadonlyArray<TaggedSchema>,
5153
5293
  Emits extends ReadonlyArray<TaggedSchema>,
5154
5294
  StateId extends StateNodeIdentifier<States>,
5155
5295
  Context,
5156
- Reenter extends boolean
5296
+ Reenter extends boolean,
5297
+ Acceptance extends TransitionAcceptance = "required"
5157
5298
  > {
5158
5299
  readonly [TransitionTypeId]: {
5159
5300
  readonly owner: Types.Covariant<readonly [States, Events, Emits, StateId, Context]>
5160
- }
5161
- }
5162
-
5163
- /** Type evidence for a targetless transition reusable in every owning context. */
5164
- export interface TargetlessTransitionTyped {
5165
- readonly [TransitionTypeId]: {
5166
- readonly targetless: true
5301
+ readonly acceptance: Types.Covariant<Acceptance>
5167
5302
  }
5168
5303
  }
5169
5304
 
@@ -5174,12 +5309,9 @@ export declare namespace Machine {
5174
5309
  Emits extends ReadonlyArray<TaggedSchema>,
5175
5310
  StateId extends StateNodeIdentifier<States>,
5176
5311
  Context,
5177
- Reenter extends boolean = false
5178
- > =
5179
- & (TransitionTyped<States, Events, Emits, StateId, Context, Reenter> | TargetlessTransitionTyped)
5180
- & {
5181
- readonly reenter?: [Reenter] extends [true] ? boolean : never
5182
- }
5312
+ Reenter extends boolean = false,
5313
+ Acceptance extends TransitionAcceptance = "required"
5314
+ > = TransitionBuilderInput<States, Events, Emits, StateId, Context, Reenter, Acceptance>
5183
5315
 
5184
5316
  export type SelectionBuilder<Selection> = Selection extends TargetSelection<infer Builder, any, any> ? Builder : never
5185
5317
  export type SelectionKind<Selection> = Selection extends TargetSelection<any, any, infer Kind> ? Kind : never
@@ -5191,138 +5323,529 @@ export declare namespace Machine {
5191
5323
  TargetBuilderResult<Builder>
5192
5324
  : never
5193
5325
 
5326
+ type SelectionSupportsDefaultConstruction<Selection> = SelectionKind<Selection> extends "none" ? true
5327
+ : SelectionBuilder<Selection> extends { readonly from: (...args: infer Args) => any } ? [] extends Args ? true
5328
+ : false
5329
+ : SelectionBuilder<Selection> extends (...args: infer Args) => any ? [] extends Args ? true
5330
+ : false
5331
+ : false
5332
+
5194
5333
  export type TransitionResolveContext<
5195
5334
  Context,
5196
- Selection,
5197
- Match = never
5335
+ Selection
5198
5336
  > =
5199
5337
  & Omit<Context, "target">
5200
- & ([Match] extends [never] ? {} : { readonly match: Match })
5201
5338
  & (SelectionKind<Selection> extends "none" ? {} : { readonly target: SelectionBuilder<Selection> })
5202
5339
 
5340
+ /** Context capability available only to explicitly declinable resolvers. */
5341
+ export interface DeclineCapability {
5342
+ readonly decline: () => Declined
5343
+ }
5344
+
5203
5345
  export type TransitionResolver<
5204
5346
  Events extends ReadonlyArray<TaggedSchema>,
5205
5347
  Emits extends ReadonlyArray<TaggedSchema>,
5206
5348
  Context,
5207
- Selection,
5208
- Match = never
5349
+ Selection
5209
5350
  > = (
5210
- context: TransitionResolveContext<Context, Selection, Match>,
5351
+ context: TransitionResolveContext<Context, Selection>,
5211
5352
  enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>
5212
5353
  ) => SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined
5213
5354
 
5214
- export type TransitionDirectInput<
5355
+ export type DeclinableTransitionResolver<
5356
+ Events extends ReadonlyArray<TaggedSchema>,
5357
+ Emits extends ReadonlyArray<TaggedSchema>,
5358
+ Context,
5359
+ Selection
5360
+ > = (
5361
+ context: TransitionResolveContext<Context, Selection> & DeclineCapability,
5362
+ enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>
5363
+ ) =>
5364
+ | (SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined)
5365
+ | Declined
5366
+
5367
+ /** One named destination declared by a branching transition. */
5368
+ export interface TransitionBranchInput<
5369
+ Selection extends TargetSelection<any, any, any> = TargetSelection<any, any, any>
5370
+ > {
5371
+ readonly target: Selection
5372
+ readonly title?: string
5373
+ }
5374
+
5375
+ /** Opaque evidence that a branching resolver selected one declared branch. */
5376
+ export interface SelectedBranch<out Key extends string, out Result> {
5377
+ readonly [Topology.SelectedBranchTypeId]: {
5378
+ readonly key: Types.Covariant<Key>
5379
+ readonly result: Types.Covariant<Result>
5380
+ }
5381
+ }
5382
+
5383
+ type SelectedBranchCallable<Callable, Key extends string> = Callable extends {
5384
+ (...args: infer Arguments1): infer Result1
5385
+ (...args: infer Arguments2): infer Result2
5386
+ } ? {
5387
+ (...args: Arguments1): SelectedBranch<Key, Result1>
5388
+ (...args: Arguments2): SelectedBranch<Key, Result2>
5389
+ }
5390
+ : Callable extends (...args: infer Arguments) => infer Result ? (...args: Arguments) => SelectedBranch<Key, Result>
5391
+ : {}
5392
+
5393
+ type SelectedBranchBuilderProperties<Builder, Key extends string> = {
5394
+ readonly [Property in keyof Builder]: Builder[Property] extends (...args: any) => any ?
5395
+ SelectedBranchCallable<Builder[Property], Key>
5396
+ : Builder[Property]
5397
+ }
5398
+
5399
+ /** Target-specific builder that brands every construction with its branch key. */
5400
+ export type SelectedBranchBuilder<Builder, Key extends string> =
5401
+ & SelectedBranchCallable<Builder, Key>
5402
+ & SelectedBranchBuilderProperties<Builder, Key>
5403
+
5404
+ export type BranchSelectors<Branches extends Readonly<Record<string, TransitionBranchInput>>> = {
5405
+ readonly [Key in Extract<keyof Branches, string>]: SelectedBranchBuilder<
5406
+ SelectionBuilder<Branches[Key]["target"]>,
5407
+ Key
5408
+ >
5409
+ }
5410
+
5411
+ export type BranchSelectionResult<Branches extends Readonly<Record<string, TransitionBranchInput>>> = {
5412
+ readonly [Key in Extract<keyof Branches, string>]: SelectedBranch<
5413
+ Key,
5414
+ SelectedTargetResult<Branches[Key]["target"]>
5415
+ >
5416
+ }[Extract<keyof Branches, string>]
5417
+
5418
+ export type TransitionBranchesResolveContext<
5419
+ Context,
5420
+ Branches extends Readonly<Record<string, TransitionBranchInput>>
5421
+ > = Omit<Context, "target"> & { readonly select: BranchSelectors<Branches> }
5422
+
5423
+ export type TransitionBranchesResolver<
5424
+ Events extends ReadonlyArray<TaggedSchema>,
5425
+ Emits extends ReadonlyArray<TaggedSchema>,
5426
+ Context,
5427
+ Branches extends Readonly<Record<string, TransitionBranchInput>>
5428
+ > = (
5429
+ context: TransitionBranchesResolveContext<Context, Branches>,
5430
+ enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>
5431
+ ) => BranchSelectionResult<Branches>
5432
+
5433
+ export type DeclinableTransitionBranchesResolver<
5434
+ Events extends ReadonlyArray<TaggedSchema>,
5435
+ Emits extends ReadonlyArray<TaggedSchema>,
5436
+ Context,
5437
+ Branches extends Readonly<Record<string, TransitionBranchInput>>
5438
+ > = (
5439
+ context: TransitionBranchesResolveContext<Context, Branches> & DeclineCapability,
5440
+ enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>
5441
+ ) => BranchSelectionResult<Branches> | Declined
5442
+
5443
+ /** @internal Type evidence retained by a transition authored through its bound selector. */
5444
+ export interface TransitionBuilderEvidence<out Result, out Acceptance extends TransitionAcceptance> {
5445
+ readonly [TransitionBuilderTypeId]: {
5446
+ readonly result: Types.Covariant<Result>
5447
+ readonly acceptance: Types.Covariant<Acceptance>
5448
+ }
5449
+ }
5450
+
5451
+ type TransitionReenterOption<Reenter extends boolean> = [Reenter] extends [true] ? { readonly reenter?: boolean }
5452
+ : { readonly reenter?: never }
5453
+
5454
+ type TransitionRequiredOptions<Reenter extends boolean> =
5455
+ & TransitionReenterOption<Reenter>
5456
+ & { readonly declinable?: false }
5457
+
5458
+ type TransitionDeclinableOptions<Reenter extends boolean> =
5459
+ & TransitionReenterOption<Reenter>
5460
+ & { readonly declinable: true }
5461
+
5462
+ type BuiltTransition<
5215
5463
  States extends StateSchemas,
5216
5464
  Events extends ReadonlyArray<TaggedSchema>,
5217
5465
  Emits extends ReadonlyArray<TaggedSchema>,
5218
5466
  StateId extends StateNodeIdentifier<States>,
5219
5467
  Context,
5220
5468
  Reenter extends boolean,
5221
- Selection extends TargetSelection<any, any, any>
5222
- > = {
5223
- readonly target: (to: TargetSelector<States, StateId>) => Selection
5224
- readonly resolve?: TransitionResolver<Events, Emits, Context, Selection>
5225
- readonly cases?: never
5226
- readonly otherwise?: never
5227
- readonly reenter?: Reenter
5228
- }
5469
+ Result,
5470
+ Acceptance extends TransitionAcceptance
5471
+ > =
5472
+ & TransitionTyped<States, Events, Emits, StateId, Context, Reenter, Acceptance>
5473
+ & TransitionBuilderEvidence<Result, Acceptance>
5229
5474
 
5230
- export type TransitionCaseInput<
5475
+ interface TransitionResolveRequired<
5231
5476
  States extends StateSchemas,
5232
5477
  Events extends ReadonlyArray<TaggedSchema>,
5233
5478
  Emits extends ReadonlyArray<TaggedSchema>,
5234
5479
  StateId extends StateNodeIdentifier<States>,
5235
5480
  Context,
5236
- Selection extends TargetSelection<any, any, any>,
5237
- Match
5238
- > = {
5239
- readonly title: string
5240
- readonly when: (context: TransitionWhenContext<Context>) => Option.Option<Match>
5241
- readonly target: (to: TargetSelector<States, StateId>) => Selection
5242
- readonly resolve?: TransitionResolver<Events, Emits, Context, Selection, NoInfer<Match>>
5243
- readonly cases?: never
5244
- readonly otherwise?: never
5245
- readonly reenter?: never
5481
+ Reenter extends boolean,
5482
+ Selection extends TargetSelection<any, any, any>
5483
+ > {
5484
+ (
5485
+ resolve: TransitionResolver<Events, Emits, Context, Selection>,
5486
+ options?: TransitionRequiredOptions<Reenter>
5487
+ ): BuiltTransition<
5488
+ States,
5489
+ Events,
5490
+ Emits,
5491
+ StateId,
5492
+ Context,
5493
+ Reenter,
5494
+ SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined,
5495
+ "required"
5496
+ >
5246
5497
  }
5247
5498
 
5248
- export type TransitionConditionalInput<
5499
+ interface TransitionResolveDeclinable<
5249
5500
  States extends StateSchemas,
5250
5501
  Events extends ReadonlyArray<TaggedSchema>,
5251
5502
  Emits extends ReadonlyArray<TaggedSchema>,
5252
5503
  StateId extends StateNodeIdentifier<States>,
5253
5504
  Context,
5254
5505
  Reenter extends boolean,
5255
- Cases extends readonly [TransitionCaseTyped, ...ReadonlyArray<TransitionCaseTyped>],
5256
- OtherwiseSelection extends TargetSelection<any, any, any>
5257
- > = {
5258
- readonly target?: never
5259
- readonly resolve?: never
5260
- readonly cases: (branch: TransitionCaseConstructor<States, Events, Emits, StateId, Context>) => Cases
5261
- readonly otherwise: TransitionDirectInput<
5506
+ Selection extends TargetSelection<any, any, any>
5507
+ > {
5508
+ (
5509
+ resolve: DeclinableTransitionResolver<Events, Emits, Context, Selection>,
5510
+ options: TransitionDeclinableOptions<Reenter>
5511
+ ): BuiltTransition<
5262
5512
  States,
5263
5513
  Events,
5264
5514
  Emits,
5265
5515
  StateId,
5266
5516
  Context,
5267
- never,
5268
- OtherwiseSelection
5517
+ Reenter,
5518
+ | (SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined)
5519
+ | Declined,
5520
+ "declinable"
5269
5521
  >
5270
- readonly reenter?: Reenter
5271
5522
  }
5272
5523
 
5273
- export type InvokeTransition<
5524
+ /** A selected transition target with target-specific resolver operations. */
5525
+ export type TransitionTarget<
5274
5526
  States extends StateSchemas,
5275
5527
  Events extends ReadonlyArray<TaggedSchema>,
5276
5528
  Emits extends ReadonlyArray<TaggedSchema>,
5277
5529
  StateId extends StateNodeIdentifier<States>,
5278
- Context
5279
- > = TransitionConfig<States, Events, Emits, StateId, Context, true>
5530
+ Context,
5531
+ Reenter extends boolean,
5532
+ Acceptance extends TransitionAcceptance,
5533
+ Selection extends TargetSelection<any, any, any>
5534
+ > =
5535
+ & Selection
5536
+ & (SelectionSupportsDefaultConstruction<Selection> extends true ? BuiltTransition<
5537
+ States,
5538
+ Events,
5539
+ Emits,
5540
+ StateId,
5541
+ Context,
5542
+ Reenter,
5543
+ SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined,
5544
+ "required"
5545
+ >
5546
+ : {})
5547
+ & {
5548
+ readonly resolve:
5549
+ & TransitionResolveRequired<States, Events, Emits, StateId, Context, Reenter, Selection>
5550
+ & ("declinable" extends Acceptance ? TransitionResolveDeclinable<
5551
+ States,
5552
+ Events,
5553
+ Emits,
5554
+ StateId,
5555
+ Context,
5556
+ Reenter,
5557
+ Selection
5558
+ >
5559
+ : {})
5560
+ }
5561
+ & ([Reenter] extends [true] ? SelectionSupportsDefaultConstruction<Selection> extends true ? {
5562
+ readonly reenter: () => BuiltTransition<
5563
+ States,
5564
+ Events,
5565
+ Emits,
5566
+ StateId,
5567
+ Context,
5568
+ Reenter,
5569
+ SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined,
5570
+ "required"
5571
+ >
5572
+ }
5573
+ : {}
5574
+ : {})
5280
5575
 
5281
- export type InvokeSource<Value, Context> = Value | ((context: Context) => Value)
5576
+ /** @internal Type evidence retained by a machine initial-entry declaration. */
5577
+ export interface InitialBuilderEvidence<out Selection> {
5578
+ readonly [InitialBuilderTypeId]: Types.Covariant<Selection>
5579
+ }
5282
5580
 
5283
- /** Inline state-owned work that runs for the lifetime of its active state. */
5284
- export interface InvokeOwned<
5581
+ /** A selected machine initial entry with its exact resolver target. */
5582
+ export type InitialTransitionTarget<Input, Selection extends TargetSelection<any, any, any>> =
5583
+ & Selection
5584
+ & (SelectionSupportsDefaultConstruction<Selection> extends true ? InitialBuilderEvidence<Selection> : {})
5585
+ & {
5586
+ readonly resolve: (
5587
+ resolve: (context: {
5588
+ readonly input: Input
5589
+ readonly target: SelectionBuilder<Selection>
5590
+ }) => SelectedTargetResult<Selection>
5591
+ ) => InitialBuilderEvidence<Selection>
5592
+ }
5593
+
5594
+ type InitialSelectorNode<Input, Node> = Node extends (...args: infer Args) => infer Selection ?
5595
+ Selection extends TargetSelection<any, any, any> ?
5596
+ & ((...args: Args) => InitialTransitionTarget<Input, Selection>)
5597
+ & {
5598
+ readonly [Key in keyof Node]: InitialSelectorNode<Input, Node[Key]>
5599
+ }
5600
+ : never
5601
+ : Node extends TargetSelection<any, any, any> ? InitialTransitionTarget<Input, Node>
5602
+ : {
5603
+ readonly [Key in keyof Node]: InitialSelectorNode<Input, Node[Key]>
5604
+ }
5605
+
5606
+ /** Definition-time selector for a machine's top-level initial entry. */
5607
+ export type InitialSelector<States extends StateSchemas, Input = void> = InitialSelectorNode<
5608
+ Input,
5609
+ InitialTargetSelector<States>
5610
+ >
5611
+
5612
+ /** Target-first initial-entry declaration accepted by {@link make}. */
5613
+ export type InitialBuilderInput<States extends StateSchemas, Input> = (
5614
+ to: InitialSelector<States, Input>
5615
+ ) => InitialBuilderEvidence<TargetSelection<any, any, any>>
5616
+
5617
+ type TransitionSelectorNode<
5285
5618
  States extends StateSchemas,
5286
5619
  Events extends ReadonlyArray<TaggedSchema>,
5287
5620
  Emits extends ReadonlyArray<TaggedSchema>,
5288
- StateId extends StateIdentifier<States>
5289
- > {
5290
- readonly "~effect/Machine/InvokeOwner"?: Types.Covariant<readonly [States, Events, Emits, StateId]>
5291
- }
5292
-
5293
- /** Type evidence retained by {@link invoke} without affecting runtime data. */
5294
- export interface InvokeTyped<Output, Error, Requirements, InitialError, Emits = never, ParentEvent = never> {
5295
- readonly [InvokeTypeId]: {
5296
- readonly output: Types.Covariant<Output>
5297
- readonly error: Types.Covariant<Error>
5298
- readonly requirements: Types.Covariant<Requirements>
5299
- readonly initialError: Types.Covariant<InitialError>
5300
- readonly emits: Types.Covariant<Emits>
5301
- readonly parentEvents: Types.Covariant<ParentEvent>
5621
+ StateId extends StateNodeIdentifier<States>,
5622
+ Context,
5623
+ Reenter extends boolean,
5624
+ Acceptance extends TransitionAcceptance,
5625
+ Node
5626
+ > = Node extends (...args: infer Args) => infer Selection ? Selection extends TargetSelection<any, any, any> ?
5627
+ & ((...args: Args) => TransitionTarget<
5628
+ States,
5629
+ Events,
5630
+ Emits,
5631
+ StateId,
5632
+ Context,
5633
+ Reenter,
5634
+ Acceptance,
5635
+ Selection
5636
+ >)
5637
+ & {
5638
+ readonly [Key in keyof Node]: TransitionSelectorNode<
5639
+ States,
5640
+ Events,
5641
+ Emits,
5642
+ StateId,
5643
+ Context,
5644
+ Reenter,
5645
+ Acceptance,
5646
+ Node[Key]
5647
+ >
5648
+ }
5649
+ : never
5650
+ : Node extends TargetSelection<any, any, any> ? TransitionTarget<
5651
+ States,
5652
+ Events,
5653
+ Emits,
5654
+ StateId,
5655
+ Context,
5656
+ Reenter,
5657
+ Acceptance,
5658
+ Node
5659
+ >
5660
+ : {
5661
+ readonly [Key in keyof Node]: TransitionSelectorNode<
5662
+ States,
5663
+ Events,
5664
+ Emits,
5665
+ StateId,
5666
+ Context,
5667
+ Reenter,
5668
+ Acceptance,
5669
+ Node[Key]
5670
+ >
5302
5671
  }
5303
- }
5304
5672
 
5305
- export type InvokeConfig<
5673
+ interface TransitionBranchesResolveRequired<
5306
5674
  States extends StateSchemas,
5307
5675
  Events extends ReadonlyArray<TaggedSchema>,
5308
5676
  Emits extends ReadonlyArray<TaggedSchema>,
5309
- StateId extends StateIdentifier<States>,
5310
- InputEvents extends ReadonlyArray<TaggedSchema> = Events,
5311
- ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
5312
- > =
5313
- & InvokeOwned<States, Events, Emits, StateId>
5314
- & (
5677
+ StateId extends StateNodeIdentifier<States>,
5678
+ Context,
5679
+ Reenter extends boolean,
5680
+ Branches extends Readonly<Record<string, TransitionBranchInput>>
5681
+ > {
5682
+ (
5683
+ resolve: TransitionBranchesResolver<Events, Emits, Context, Branches>,
5684
+ options?: TransitionRequiredOptions<Reenter>
5685
+ ): BuiltTransition<
5686
+ States,
5687
+ Events,
5688
+ Emits,
5689
+ StateId,
5690
+ Context,
5691
+ Reenter,
5692
+ BranchSelectionResult<Branches>,
5693
+ "required"
5694
+ >
5695
+ }
5696
+
5697
+ interface TransitionBranchesResolveDeclinable<
5698
+ States extends StateSchemas,
5699
+ Events extends ReadonlyArray<TaggedSchema>,
5700
+ Emits extends ReadonlyArray<TaggedSchema>,
5701
+ StateId extends StateNodeIdentifier<States>,
5702
+ Context,
5703
+ Reenter extends boolean,
5704
+ Branches extends Readonly<Record<string, TransitionBranchInput>>
5705
+ > {
5706
+ (
5707
+ resolve: DeclinableTransitionBranchesResolver<Events, Emits, Context, Branches>,
5708
+ options: TransitionDeclinableOptions<Reenter>
5709
+ ): BuiltTransition<
5710
+ States,
5711
+ Events,
5712
+ Emits,
5713
+ StateId,
5714
+ Context,
5715
+ Reenter,
5716
+ BranchSelectionResult<Branches> | Declined,
5717
+ "declinable"
5718
+ >
5719
+ }
5720
+
5721
+ /** Selector supplied to inline transition declarations. */
5722
+ export type TransitionSelector<
5723
+ States extends StateSchemas,
5724
+ Events extends ReadonlyArray<TaggedSchema>,
5725
+ Emits extends ReadonlyArray<TaggedSchema>,
5726
+ StateId extends StateNodeIdentifier<States>,
5727
+ Context,
5728
+ Reenter extends boolean,
5729
+ Acceptance extends TransitionAcceptance
5730
+ > =
5731
+ & TransitionSelectorNode<
5732
+ States,
5733
+ Events,
5734
+ Emits,
5735
+ StateId,
5736
+ Context,
5737
+ Reenter,
5738
+ Acceptance,
5739
+ TargetSelector<States, StateId>
5740
+ >
5741
+ & {
5742
+ readonly branches: <const Branches extends Readonly<Record<string, TransitionBranchInput>>>(
5743
+ branches: Branches & ValidateTransitionBranchRecord<NoInfer<Branches>>
5744
+ ) => {
5745
+ readonly resolve:
5746
+ & TransitionBranchesResolveRequired<States, Events, Emits, StateId, Context, Reenter, Branches>
5747
+ & ("declinable" extends Acceptance ? TransitionBranchesResolveDeclinable<
5748
+ States,
5749
+ Events,
5750
+ Emits,
5751
+ StateId,
5752
+ Context,
5753
+ Reenter,
5754
+ Branches
5755
+ >
5756
+ : {})
5757
+ }
5758
+ }
5759
+
5760
+ /** Inline transition declaration accepted by state and invocation handlers. */
5761
+ export type TransitionBuilderInput<
5762
+ States extends StateSchemas,
5763
+ Events extends ReadonlyArray<TaggedSchema>,
5764
+ Emits extends ReadonlyArray<TaggedSchema>,
5765
+ StateId extends StateNodeIdentifier<States>,
5766
+ Context,
5767
+ Reenter extends boolean,
5768
+ Acceptance extends TransitionAcceptance
5769
+ > = (
5770
+ to: TransitionSelector<States, Events, Emits, StateId, Context, Reenter, Acceptance>
5771
+ ) =>
5772
+ & TransitionTyped<States, Events, Emits, StateId, Context, Reenter, Acceptance>
5773
+ & TransitionBuilderEvidence<any, Acceptance>
5774
+
5775
+ export type InvokeTransition<
5776
+ States extends StateSchemas,
5777
+ Events extends ReadonlyArray<TaggedSchema>,
5778
+ Emits extends ReadonlyArray<TaggedSchema>,
5779
+ StateId extends StateNodeIdentifier<States>,
5780
+ Context
5781
+ > = TransitionConfig<States, Events, Emits, StateId, Context, true, TransitionAcceptance>
5782
+
5783
+ export type InvokeSource<Value, Context> = Value | ((context: Context) => Value)
5784
+
5785
+ /** Inline state-owned work that runs for the lifetime of its active state. */
5786
+ export interface InvokeOwned<
5787
+ States extends StateSchemas,
5788
+ Events extends ReadonlyArray<TaggedSchema>,
5789
+ Emits extends ReadonlyArray<TaggedSchema>,
5790
+ StateId extends StateIdentifier<States>,
5791
+ InputEvents extends ReadonlyArray<TaggedSchema> = Events,
5792
+ ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
5793
+ > {
5794
+ readonly "~effect/Machine/InvokeOwner"?: Types.Covariant<
5795
+ readonly [States, Events, Emits, StateId, InputEvents, ParentEvents]
5796
+ >
5797
+ }
5798
+
5799
+ /** Type evidence retained by {@link invoke} without affecting runtime data. */
5800
+ export interface InvokeTyped<Output, Error, Requirements, InitialError, Emits = never, ParentEvent = never> {
5801
+ readonly [InvokeTypeId]: {
5802
+ readonly output: Types.Covariant<Output>
5803
+ readonly error: Types.Covariant<Error>
5804
+ readonly requirements: Types.Covariant<Requirements>
5805
+ readonly initialError: Types.Covariant<InitialError>
5806
+ readonly emits: Types.Covariant<Emits>
5807
+ readonly parentEvents: Types.Covariant<ParentEvent>
5808
+ }
5809
+ }
5810
+
5811
+ export type InvokeConfig<
5812
+ States extends StateSchemas,
5813
+ Events extends ReadonlyArray<TaggedSchema>,
5814
+ Emits extends ReadonlyArray<TaggedSchema>,
5815
+ StateId extends StateIdentifier<States>,
5816
+ InputEvents extends ReadonlyArray<TaggedSchema> = Events,
5817
+ ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
5818
+ > =
5819
+ & InvokeOwned<States, Events, Emits, StateId, InputEvents, ParentEvents>
5820
+ & (
5315
5821
  | {
5316
5822
  readonly id: string
5317
5823
  readonly effect: (
5318
5824
  context: InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
5319
5825
  ) => Effect.Effect<any, any, any>
5826
+ readonly stream?: never
5320
5827
  readonly after?: never
5321
5828
  readonly logic?: never
5322
5829
  readonly child?: never
5323
5830
  readonly address?: never
5324
5831
  readonly onDone?: unknown
5325
5832
  readonly onFailure?: unknown
5833
+ readonly onElement?: never
5834
+ readonly onSnapshot?: never
5835
+ }
5836
+ | {
5837
+ readonly id: string
5838
+ readonly stream: (
5839
+ context: InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
5840
+ ) => Stream.Stream<any, any, any>
5841
+ readonly effect?: never
5842
+ readonly after?: never
5843
+ readonly logic?: never
5844
+ readonly child?: never
5845
+ readonly address?: never
5846
+ readonly onElement?: unknown
5847
+ readonly onDone: unknown
5848
+ readonly onFailure?: unknown
5326
5849
  readonly onSnapshot?: never
5327
5850
  }
5328
5851
  | {
@@ -5332,11 +5855,13 @@ export declare namespace Machine {
5332
5855
  InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
5333
5856
  >
5334
5857
  readonly effect?: never
5858
+ readonly stream?: never
5335
5859
  readonly logic?: never
5336
5860
  readonly child?: never
5337
5861
  readonly address?: never
5338
5862
  readonly onDone: unknown
5339
5863
  readonly onFailure?: never
5864
+ readonly onElement?: never
5340
5865
  readonly onSnapshot?: never
5341
5866
  }
5342
5867
  | {
@@ -5347,10 +5872,12 @@ export declare namespace Machine {
5347
5872
  InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
5348
5873
  >
5349
5874
  readonly effect?: never
5875
+ readonly stream?: never
5350
5876
  readonly after?: never
5351
5877
  readonly child?: never
5352
5878
  readonly onDone?: unknown
5353
5879
  readonly onFailure?: unknown
5880
+ readonly onElement?: never
5354
5881
  readonly onSnapshot?: unknown
5355
5882
  }
5356
5883
  | {
@@ -5362,10 +5889,12 @@ export declare namespace Machine {
5362
5889
  readonly id?: never
5363
5890
  readonly address?: never
5364
5891
  readonly effect?: never
5892
+ readonly stream?: never
5365
5893
  readonly after?: never
5366
5894
  readonly logic?: never
5367
5895
  readonly onDone?: unknown
5368
5896
  readonly onFailure?: unknown
5897
+ readonly onElement?: never
5369
5898
  readonly onSnapshot?: unknown
5370
5899
  }
5371
5900
  )
@@ -5400,6 +5929,11 @@ export declare namespace Machine {
5400
5929
  : { readonly onFailure?: never }
5401
5930
  : never
5402
5931
 
5932
+ export type InvokeElementRequirement<Value, Handler> = InvokeHandlerRequirement<Value, Handler> extends
5933
+ infer Requirement ? Requirement extends { readonly handler: infer Required } ? { readonly onElement: Required }
5934
+ : { readonly onElement?: never }
5935
+ : never
5936
+
5403
5937
  export type TimerInvokeArgs<
5404
5938
  States extends StateSchemas,
5405
5939
  Events extends ReadonlyArray<TaggedSchema>,
@@ -5414,10 +5948,12 @@ export declare namespace Machine {
5414
5948
  InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
5415
5949
  >
5416
5950
  readonly effect?: never
5951
+ readonly stream?: never
5417
5952
  readonly logic?: never
5418
5953
  readonly child?: never
5419
5954
  readonly address?: never
5420
5955
  readonly onFailure?: never
5956
+ readonly onElement?: never
5421
5957
  readonly onSnapshot?: never
5422
5958
  readonly onDone: InvokeTransition<
5423
5959
  States,
@@ -5449,8 +5985,10 @@ export declare namespace Machine {
5449
5985
  readonly address: Address & ChildAddress.Compatibility<Address, ChildEvent>
5450
5986
  readonly logic: Source
5451
5987
  readonly effect?: never
5988
+ readonly stream?: never
5452
5989
  readonly after?: never
5453
5990
  readonly child?: never
5991
+ readonly onElement?: never
5454
5992
  readonly onSnapshot?: InvokeTransition<
5455
5993
  States,
5456
5994
  Events,
@@ -5512,8 +6050,10 @@ export declare namespace Machine {
5512
6050
  readonly id?: never
5513
6051
  readonly address?: never
5514
6052
  readonly effect?: never
6053
+ readonly stream?: never
5515
6054
  readonly after?: never
5516
6055
  readonly logic?: never
6056
+ readonly onElement?: never
5517
6057
  readonly onSnapshot?: InvokeTransition<
5518
6058
  States,
5519
6059
  Events,
@@ -5603,6 +6143,7 @@ export declare namespace Machine {
5603
6143
  ParentEvents extends ReadonlyArray<TaggedSchema>,
5604
6144
  Raw
5605
6145
  > = Raw extends InvokeTyped<any, any, any, any, any> ? unknown
6146
+ : [Extract<keyof Raw, "onDone" | "onFailure" | "onElement" | "onSnapshot">] extends [never] ? unknown
5606
6147
  : Raw extends { readonly effect: infer Source } ?
5607
6148
  InvokeFactoryResult<Source> extends infer Fx extends Effect.Effect<any, any, any> ?
5608
6149
  & InvokeDoneRequirement<
@@ -5627,6 +6168,55 @@ export declare namespace Machine {
5627
6168
  >
5628
6169
  & { readonly onSnapshot?: never }
5629
6170
  : never
6171
+ : Raw extends { readonly stream: infer Source } ?
6172
+ InvokeFactoryResult<Source> extends infer SourceStream extends Stream.Stream<any, any, any> ?
6173
+ & InvokeElementRequirement<
6174
+ Stream.Success<SourceStream>,
6175
+ InvokeTransition<
6176
+ States,
6177
+ Events,
6178
+ Emits,
6179
+ StateId,
6180
+ InvokeElementContext<
6181
+ States,
6182
+ Events,
6183
+ Emits,
6184
+ StateId,
6185
+ Stream.Success<SourceStream>,
6186
+ InputEvents,
6187
+ ParentEvents
6188
+ >
6189
+ >
6190
+ >
6191
+ & {
6192
+ readonly onDone: InvokeTransition<
6193
+ States,
6194
+ Events,
6195
+ Emits,
6196
+ StateId,
6197
+ InvokeDoneContext<States, Events, Emits, StateId, void, InputEvents, ParentEvents>
6198
+ >
6199
+ }
6200
+ & InvokeFailureRequirement<
6201
+ Stream.Error<SourceStream>,
6202
+ InvokeTransition<
6203
+ States,
6204
+ Events,
6205
+ Emits,
6206
+ StateId,
6207
+ InvokeFailureContext<
6208
+ States,
6209
+ Events,
6210
+ Emits,
6211
+ StateId,
6212
+ Stream.Error<SourceStream>,
6213
+ InputEvents,
6214
+ ParentEvents
6215
+ >
6216
+ >
6217
+ >
6218
+ & { readonly onSnapshot?: never }
6219
+ : never
5630
6220
  : Raw extends { readonly after: unknown } ? {
5631
6221
  readonly onDone: InvokeTransition<
5632
6222
  States,
@@ -5839,14 +6429,18 @@ export declare namespace Machine {
5839
6429
  Events,
5840
6430
  Emits,
5841
6431
  StateId,
5842
- AlwaysContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
6432
+ AlwaysContext<States, Events, Emits, StateId, InputEvents, ParentEvents>,
6433
+ false,
6434
+ TransitionAcceptance
5843
6435
  >
5844
6436
  readonly onDone?: TransitionConfig<
5845
6437
  States,
5846
6438
  Events,
5847
6439
  Emits,
5848
6440
  StateId,
5849
- DoneContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
6441
+ DoneContext<States, Events, Emits, StateId, InputEvents, ParentEvents>,
6442
+ false,
6443
+ TransitionAcceptance
5850
6444
  >
5851
6445
  readonly on?: {
5852
6446
  readonly [EventTag in TagOf<Events[number]>]?: TransitionConfig<
@@ -5855,7 +6449,8 @@ export declare namespace Machine {
5855
6449
  Emits,
5856
6450
  StateId,
5857
6451
  HandlerContext<States, Events, Emits, StateId, EventTag, E, R, InputEvents, ParentEvents>,
5858
- true
6452
+ true,
6453
+ TransitionAcceptance
5859
6454
  >
5860
6455
  }
5861
6456
  readonly initialize?: StateInitializeHandler<States, Events, Emits, StateId, InputEvents, ParentEvents>
@@ -6374,6 +6969,7 @@ export declare namespace Machine {
6374
6969
 
6375
6970
  type TransitionResultInitialTargetPath<Result> = IsAny<Result> extends true ? never
6376
6971
  : Result extends Effect.Effect<infer Success, any, any> ? TransitionResultInitialTargetPath<Success>
6972
+ : Result extends SelectedBranch<any, infer Selected> ? TransitionResultInitialTargetPath<Selected>
6377
6973
  : Result extends StateConstruction<infer Constructed> ? TransitionResultInitialTargetPath<Constructed>
6378
6974
  : Result extends {
6379
6975
  readonly [Topology.InitialTargetTypeId]: typeof Topology.InitialTargetTypeId
@@ -6849,7 +7445,8 @@ export declare namespace Machine {
6849
7445
  Emits,
6850
7446
  StateId,
6851
7447
  HandlerContext<States, Events, Emits, StateId, EventTag, E, R>,
6852
- true
7448
+ true,
7449
+ TransitionAcceptance
6853
7450
  >
6854
7451
  >
6855
7452
  >
@@ -6883,14 +7480,18 @@ export declare namespace Machine {
6883
7480
  Events,
6884
7481
  Emits,
6885
7482
  StateId,
6886
- AlwaysContext<States, Events, Emits, StateId>
7483
+ AlwaysContext<States, Events, Emits, StateId>,
7484
+ false,
7485
+ TransitionAcceptance
6887
7486
  >
6888
7487
  readonly onDone?: TransitionConfig<
6889
7488
  States,
6890
7489
  Events,
6891
7490
  Emits,
6892
7491
  StateId,
6893
- DoneContext<States, Events, Emits, StateId>
7492
+ DoneContext<States, Events, Emits, StateId>,
7493
+ false,
7494
+ TransitionAcceptance
6894
7495
  >
6895
7496
  readonly output?:
6896
7497
  | ((context: FinalOutputContext<States, Events, StateId>) => unknown)
@@ -7047,10 +7648,7 @@ export const state: StateConstructor = internal.state as StateConstructor
7047
7648
  * Machine.make({
7048
7649
  * states: States.states,
7049
7650
  * events: Machine.events(),
7050
- * initial: {
7051
- * target: (to) => to.idle(),
7052
- * resolve: ({ target }) => target.from()
7053
- * }
7651
+ * initial: (to) => to.idle().resolve(({ target }) => target.from())
7054
7652
  * })
7055
7653
  * ```
7056
7654
  *
@@ -7059,20 +7657,6 @@ export const state: StateConstructor = internal.state as StateConstructor
7059
7657
  */
7060
7658
  export const states: StatesConstructor = internal.states
7061
7659
 
7062
- type InitialDirectInput<
7063
- States extends Machine.StateSchemas,
7064
- Input,
7065
- Selection extends Machine.TargetSelection<any, any, any>
7066
- > = {
7067
- readonly target: (to: Machine.InitialSelector<States>) => Selection
7068
- readonly resolve?: (context: {
7069
- readonly input: Input
7070
- readonly target: Machine.SelectionBuilder<Selection>
7071
- }) => Machine.SelectedTargetResult<Selection>
7072
- readonly cases?: never
7073
- readonly otherwise?: never
7074
- }
7075
-
7076
7660
  type MakeConfig<
7077
7661
  States extends Machine.StateSchemas,
7078
7662
  InputEvents extends ReadonlyArray<Machine.TaggedSchema>,
@@ -7081,7 +7665,7 @@ type MakeConfig<
7081
7665
  InitialE,
7082
7666
  InitialR,
7083
7667
  InternalEvents extends ReadonlyArray<Machine.TaggedSchema>,
7084
- ParentEvents extends ReadonlyArray<Machine.TaggedSchema>
7668
+ ParentDeclaration extends Parent.Any | undefined
7085
7669
  > = {
7086
7670
  readonly id?: string
7087
7671
  readonly states: States & DefineStateTreeInput<NoInfer<States>>
@@ -7095,7 +7679,7 @@ type MakeConfig<
7095
7679
  NoInfer<InternalEvents>
7096
7680
  >
7097
7681
  readonly emittedEvents?: Machine.EventProtocol<"emitted", Emits>
7098
- readonly parentEvents?: Machine.EventProtocol<"public", ParentEvents>
7682
+ readonly parent?: ParentDeclaration
7099
7683
  readonly input?: Input
7100
7684
  readonly initial: unknown
7101
7685
  }
@@ -7108,7 +7692,7 @@ type MakeResult<
7108
7692
  InitialE,
7109
7693
  InitialR,
7110
7694
  InternalEvents extends ReadonlyArray<Machine.TaggedSchema>,
7111
- ParentEvents extends ReadonlyArray<Machine.TaggedSchema>
7695
+ ParentDeclaration extends Parent.Any | undefined
7112
7696
  > = Definition<
7113
7697
  States,
7114
7698
  readonly [...InputEvents, ...InternalEvents],
@@ -7119,7 +7703,7 @@ type MakeResult<
7119
7703
  Machine.TerminalOutput<States>,
7120
7704
  Emits,
7121
7705
  InputEvents,
7122
- ParentEvents
7706
+ Machine.ParentEventsOf<ParentDeclaration>
7123
7707
  >
7124
7708
 
7125
7709
  interface Make {
@@ -7131,17 +7715,16 @@ interface Make {
7131
7715
  InitialE = never,
7132
7716
  InitialR = never,
7133
7717
  const InternalEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
7134
- const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
7135
- const InitialSelection extends Machine.TargetSelection<any, any, any> = Machine.TargetSelection<any, any, any>
7718
+ const ParentDeclaration extends Parent.Any | undefined = undefined
7136
7719
  >(
7137
7720
  config:
7138
7721
  & Omit<
7139
- MakeConfig<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentEvents>,
7722
+ MakeConfig<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentDeclaration>,
7140
7723
  "initial"
7141
7724
  >
7142
- & { readonly initial: InitialDirectInput<States, Input["Type"], InitialSelection> },
7725
+ & { readonly initial: Machine.InitialBuilderInput<States, Input["Type"]> },
7143
7726
  ..._validation: ValidateDefinedStates<NoInfer<States>>
7144
- ): MakeResult<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentEvents>
7727
+ ): MakeResult<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentDeclaration>
7145
7728
  <
7146
7729
  const States extends Machine.StateSchemas,
7147
7730
  const InputEvents extends ReadonlyArray<Machine.TaggedSchema>,
@@ -7150,10 +7733,13 @@ interface Make {
7150
7733
  InitialE = never,
7151
7734
  InitialR = never,
7152
7735
  const InternalEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
7153
- const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
7736
+ const ParentDeclaration extends Parent.Any | undefined = undefined
7154
7737
  >(
7155
7738
  config:
7156
- & Omit<MakeConfig<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentEvents>, "states">
7739
+ & Omit<
7740
+ MakeConfig<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentDeclaration>,
7741
+ "states"
7742
+ >
7157
7743
  & { readonly states: InvalidDefinedStateTreeInput<States> }
7158
7744
  ): never
7159
7745
  }
@@ -7169,11 +7755,17 @@ interface Make {
7169
7755
  * `states` or is passed inline. Call `handle` on the returned definition
7170
7756
  * to implement state behavior with ordinary TypeScript control flow.
7171
7757
  *
7758
+ * `initial` is a target-first callback. Its outer selector runs once while the
7759
+ * definition is captured; an attached `.resolve(...)` callback remains lazy
7760
+ * until initial planning. Return a bare selected state when its schema supports
7761
+ * default construction.
7762
+ *
7172
7763
  * `Machine.events` defines the public input protocol. `Machine.internalEvents`
7173
7764
  * adds raised events and other machine-local deliveries.
7174
- * `Machine.emittedEvents` defines outward ephemeral notifications, while
7175
- * `parentEvents` declares the inputs a child may explicitly send to its owning
7176
- * machine. All descriptors expose deferred constructors while retaining their
7765
+ * `Machine.emittedEvents` defines outward ephemeral notifications. The
7766
+ * `parent` configuration accepts `Machine.parent(events)` for a required owner
7767
+ * or `Machine.optionalParent(events)` for a root-capable machine. All
7768
+ * descriptors expose deferred constructors while retaining their
7177
7769
  * schemas opaquely for runtime validation. Public and internal tags must be
7178
7770
  * disjoint.
7179
7771
  *
@@ -7197,18 +7789,13 @@ interface Make {
7197
7789
  * const counter = Machine.make({
7198
7790
  * states: States.states,
7199
7791
  * events: Events,
7200
- * initial: {
7201
- * target: (to) => to.Count(),
7202
- * resolve: ({ target }) => target(new Count({ value: 0 }))
7203
- * }
7792
+ * initial: (to) => to.Count().resolve(({ target }) => target(new Count({ value: 0 })))
7204
7793
  * }).handle({
7205
7794
  * Count: {
7206
7795
  * on: {
7207
- * Increment: Machine.transition({
7208
- * target: (to) => to.full.Count(),
7209
- * resolve: ({ event, state, target }) =>
7210
- * target(new Count({ value: state.value + event.by }))
7211
- * })
7796
+ * Increment: (to) =>
7797
+ * to.full.Count().resolve(({ event, state, target }) =>
7798
+ * target(new Count({ value: state.value + event.by })))
7212
7799
  * }
7213
7800
  * }
7214
7801
  * })
@@ -7264,6 +7851,33 @@ export const events: {
7264
7851
  ): Machine.EventProtocol<"public", Machine.EventProtocolInputSchemasOf<"public", Inputs>>
7265
7852
  } = internal.events as any
7266
7853
 
7854
+ /**
7855
+ * Requires the machine to run as an owned child whose parent accepts the
7856
+ * supplied public event protocol.
7857
+ *
7858
+ * Required-parent machines expose a non-optional `parent` target in behavior
7859
+ * contexts and are rejected by root execution APIs.
7860
+ *
7861
+ * @category constructors
7862
+ * @since 0.17.0
7863
+ */
7864
+ export const parent: <const Events extends ReadonlyArray<Machine.TaggedSchema>>(
7865
+ events: Machine.EventProtocol<"public", Events>
7866
+ ) => Parent<"required", Events> = internal.parent
7867
+
7868
+ /**
7869
+ * Declares public events a machine may send to its owner while preserving the
7870
+ * ability to run that machine as a root.
7871
+ *
7872
+ * Optional-parent machines expose `parent` as a possibly absent target.
7873
+ *
7874
+ * @category constructors
7875
+ * @since 0.17.0
7876
+ */
7877
+ export const optionalParent: <const Events extends ReadonlyArray<Machine.TaggedSchema>>(
7878
+ events: Machine.EventProtocol<"public", Events>
7879
+ ) => Parent<"optional", Events> = internal.optionalParent
7880
+
7267
7881
  /**
7268
7882
  * Defines an internal event protocol and returns deferred constructors for
7269
7883
  * every statically finite configured event tag.
@@ -7362,10 +7976,7 @@ export const emittedEvents: {
7362
7976
  * const machine = Machine.make({
7363
7977
  * states: States.states,
7364
7978
  * events: Machine.events(),
7365
- * initial: {
7366
- * target: (to) => to.Idle(),
7367
- * resolve: ({ target }) => target.from()
7368
- * }
7979
+ * initial: (to) => to.Idle().resolve(({ target }) => target.from())
7369
7980
  * }).handle({ Idle: {} })
7370
7981
  *
7371
7982
  * const encoded = Effect.gen(function*() {
@@ -7447,10 +8058,7 @@ export const encodeSnapshot: <
7447
8058
  * const machine = Machine.make({
7448
8059
  * states: States.states,
7449
8060
  * events: Machine.events(),
7450
- * initial: {
7451
- * target: (to) => to.Idle(),
7452
- * resolve: ({ target }) => target.from()
7453
- * }
8061
+ * initial: (to) => to.Idle().resolve(({ target }) => target.from())
7454
8062
  * }).handle({ Idle: {} })
7455
8063
  *
7456
8064
  * const roundTrip = Effect.gen(function*() {
@@ -7516,10 +8124,12 @@ type EffectInvokeSource<
7516
8124
  > = {
7517
8125
  readonly id: InvokeLifecycleId
7518
8126
  readonly effect: Source
8127
+ readonly stream?: never
7519
8128
  readonly after?: never
7520
8129
  readonly logic?: never
7521
8130
  readonly child?: never
7522
8131
  readonly address?: never
8132
+ readonly onElement?: never
7523
8133
  readonly onSnapshot?: never
7524
8134
  }
7525
8135
 
@@ -7580,7 +8190,7 @@ type EffectInvokeResult<
7580
8190
  StateId extends Machine.StateIdentifier<States>,
7581
8191
  Source extends (...args: ReadonlyArray<never>) => Effect.Effect<unknown, unknown, unknown>
7582
8192
  > =
7583
- & Machine.InvokeConfig<States, Events, Emits, StateId, InputEvents, ParentEvents>
8193
+ & Machine.InvokeOwned<States, Events, Emits, StateId, InputEvents, ParentEvents>
7584
8194
  & Machine.InvokeTyped<
7585
8195
  Effect.Success<ReturnType<Source>>,
7586
8196
  Effect.Error<ReturnType<Source>>,
@@ -7588,21 +8198,20 @@ type EffectInvokeResult<
7588
8198
  never
7589
8199
  >
7590
8200
 
7591
- type InvokeChannelIsNever<Value> = IsAny<Value> extends true ? false : [Value] extends [never] ? true : false
7592
-
7593
- type BoundEffectInvokeSource<
8201
+ type StreamInvokeSource<
7594
8202
  States extends Machine.StateSchemas,
7595
8203
  Events extends ReadonlyArray<Machine.TaggedSchema>,
7596
8204
  Emits extends ReadonlyArray<Machine.TaggedSchema>,
7597
8205
  InputEvents extends ReadonlyArray<Machine.TaggedSchema>,
7598
8206
  ParentEvents extends ReadonlyArray<Machine.TaggedSchema>,
7599
8207
  StateId extends Machine.StateIdentifier<States>,
7600
- Source extends (
7601
- context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
7602
- ) => Effect.Effect<unknown, unknown, unknown>
8208
+ Source extends (...args: ReadonlyArray<any>) => unknown
7603
8209
  > = {
7604
8210
  readonly id: InvokeLifecycleId
7605
- readonly effect: Source
8211
+ readonly stream:
8212
+ & Source
8213
+ & ((context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>) => unknown)
8214
+ readonly effect?: never
7606
8215
  readonly after?: never
7607
8216
  readonly logic?: never
7608
8217
  readonly child?: never
@@ -7610,38 +8219,56 @@ type BoundEffectInvokeSource<
7610
8219
  readonly onSnapshot?: never
7611
8220
  }
7612
8221
 
7613
- type BoundEffectDoneHandler<
8222
+ type StreamSourceResult<Source extends (...args: ReadonlyArray<any>) => unknown> = ReturnType<Source> extends
8223
+ infer Result extends Stream.Stream<any, any, any> ? Result : never
8224
+
8225
+ type StreamElementHandler<
7614
8226
  States extends Machine.StateSchemas,
7615
8227
  Events extends ReadonlyArray<Machine.TaggedSchema>,
7616
8228
  Emits extends ReadonlyArray<Machine.TaggedSchema>,
7617
8229
  InputEvents extends ReadonlyArray<Machine.TaggedSchema>,
7618
8230
  ParentEvents extends ReadonlyArray<Machine.TaggedSchema>,
7619
8231
  StateId extends Machine.StateIdentifier<States>,
7620
- Source extends (...args: ReadonlyArray<never>) => Effect.Effect<unknown, unknown, unknown>
8232
+ Source extends (...args: ReadonlyArray<any>) => unknown
7621
8233
  > = Machine.InvokeTransition<
7622
8234
  States,
7623
8235
  Events,
7624
8236
  Emits,
7625
8237
  StateId,
7626
- Machine.InvokeDoneContext<
8238
+ Machine.InvokeElementContext<
7627
8239
  States,
7628
8240
  Events,
7629
8241
  Emits,
7630
8242
  StateId,
7631
- Effect.Success<ReturnType<NoInfer<Source>>>,
8243
+ Stream.Success<StreamSourceResult<NoInfer<Source>>>,
7632
8244
  InputEvents,
7633
8245
  ParentEvents
7634
8246
  >
7635
8247
  >
7636
8248
 
7637
- type BoundEffectFailureHandler<
8249
+ type StreamDoneHandler<
8250
+ States extends Machine.StateSchemas,
8251
+ Events extends ReadonlyArray<Machine.TaggedSchema>,
8252
+ Emits extends ReadonlyArray<Machine.TaggedSchema>,
8253
+ InputEvents extends ReadonlyArray<Machine.TaggedSchema>,
8254
+ ParentEvents extends ReadonlyArray<Machine.TaggedSchema>,
8255
+ StateId extends Machine.StateIdentifier<States>
8256
+ > = Machine.InvokeTransition<
8257
+ States,
8258
+ Events,
8259
+ Emits,
8260
+ StateId,
8261
+ Machine.InvokeDoneContext<States, Events, Emits, StateId, void, InputEvents, ParentEvents>
8262
+ >
8263
+
8264
+ type StreamFailureHandler<
7638
8265
  States extends Machine.StateSchemas,
7639
8266
  Events extends ReadonlyArray<Machine.TaggedSchema>,
7640
8267
  Emits extends ReadonlyArray<Machine.TaggedSchema>,
7641
8268
  InputEvents extends ReadonlyArray<Machine.TaggedSchema>,
7642
8269
  ParentEvents extends ReadonlyArray<Machine.TaggedSchema>,
7643
8270
  StateId extends Machine.StateIdentifier<States>,
7644
- Source extends (...args: ReadonlyArray<never>) => Effect.Effect<unknown, unknown, unknown>
8271
+ Source extends (...args: ReadonlyArray<any>) => unknown
7645
8272
  > = Machine.InvokeTransition<
7646
8273
  States,
7647
8274
  Events,
@@ -7652,226 +8279,111 @@ type BoundEffectFailureHandler<
7652
8279
  Events,
7653
8280
  Emits,
7654
8281
  StateId,
7655
- Effect.Error<ReturnType<NoInfer<Source>>>,
8282
+ Stream.Error<StreamSourceResult<NoInfer<Source>>>,
7656
8283
  InputEvents,
7657
8284
  ParentEvents
7658
8285
  >
7659
8286
  >
7660
8287
 
7661
- type BoundEffectInvokeResult<
8288
+ type StreamInvokeResult<
7662
8289
  States extends Machine.StateSchemas,
7663
8290
  Events extends ReadonlyArray<Machine.TaggedSchema>,
7664
8291
  Emits extends ReadonlyArray<Machine.TaggedSchema>,
7665
8292
  InputEvents extends ReadonlyArray<Machine.TaggedSchema>,
7666
8293
  ParentEvents extends ReadonlyArray<Machine.TaggedSchema>,
7667
8294
  StateId extends Machine.StateIdentifier<States>,
7668
- Source extends (...args: ReadonlyArray<never>) => Effect.Effect<unknown, unknown, unknown>
8295
+ Source extends (...args: ReadonlyArray<any>) => unknown
7669
8296
  > =
7670
- & Machine.InvokeConfig<States, Events, Emits, StateId, InputEvents, ParentEvents>
8297
+ & Machine.InvokeOwned<States, Events, Emits, StateId, InputEvents, ParentEvents>
7671
8298
  & Machine.InvokeTyped<
7672
- Effect.Success<ReturnType<Source>>,
7673
- Effect.Error<ReturnType<Source>>,
7674
- Effect.Services<ReturnType<Source>>,
8299
+ void,
8300
+ Stream.Error<StreamSourceResult<Source>>,
8301
+ Stream.Services<StreamSourceResult<Source>>,
7675
8302
  never
7676
8303
  >
7677
8304
 
7678
- /** Type evidence retained for a case created by a conditional transition's local builder. */
7679
- interface TransitionCaseTyped {
7680
- readonly [TransitionCaseTypeId]: true
7681
- }
8305
+ type InvokeChannelIsNever<Value> = IsAny<Value> extends true ? false : [Value] extends [never] ? true : false
7682
8306
 
7683
- /** Locally bound constructor that preserves each conditional transition case independently. */
7684
- interface TransitionCaseConstructor<
7685
- States extends Machine.StateSchemas,
7686
- Events extends ReadonlyArray<Machine.TaggedSchema>,
7687
- Emits extends ReadonlyArray<Machine.TaggedSchema>,
7688
- StateId extends Machine.StateNodeIdentifier<States>,
7689
- Context
7690
- > {
7691
- <
7692
- const Selection extends Machine.TargetSelection<any, any, any>,
7693
- const Match
7694
- >(
7695
- config: Machine.TransitionCaseInput<States, Events, Emits, StateId, Context, Selection, Match>
7696
- ):
7697
- & Machine.TransitionCaseInput<States, Events, Emits, StateId, Context, Selection, Match>
7698
- & TransitionCaseTyped
8307
+ type TransitionBranchRecordError<Message extends string, Key extends PropertyKey = never> = {
8308
+ readonly "~effect/Machine/TransitionBranchRecordError": Message
8309
+ readonly key: Key
7699
8310
  }
7700
8311
 
7701
- /**
7702
- * Captures one exact transition topology while preserving handler inference.
7703
- *
7704
- * @category constructors
7705
- * @since 0.14.0
7706
- */
7707
- type ConditionalTransitionResult<
7708
- States extends Machine.StateSchemas,
7709
- Events extends ReadonlyArray<Machine.TaggedSchema>,
7710
- Emits extends ReadonlyArray<Machine.TaggedSchema>,
7711
- StateId extends Machine.StateNodeIdentifier<States>,
7712
- Context,
7713
- Reenter extends boolean,
7714
- Cases extends readonly [
7715
- TransitionCaseTyped,
7716
- ...ReadonlyArray<TransitionCaseTyped>
7717
- ],
7718
- OtherwiseSelection extends Machine.TargetSelection<any, any, any>
7719
- > =
7720
- & Omit<
7721
- Machine.TransitionConditionalInput<
7722
- States,
7723
- Events,
7724
- Emits,
7725
- StateId,
7726
- Context,
7727
- Reenter,
7728
- Cases,
7729
- OtherwiseSelection
7730
- >,
7731
- "cases"
8312
+ type InvalidStaticTransitionBranchKey<Branches> = Extract<keyof Branches, "" | number | symbol>
8313
+
8314
+ type ValidateTransitionBranchRecord<Branches> = [keyof Branches] extends [never] ?
8315
+ TransitionBranchRecordError<"Branch records must contain at least one branch">
8316
+ : [InvalidStaticTransitionBranchKey<Branches>] extends [never] ? unknown
8317
+ : TransitionBranchRecordError<
8318
+ "Branch keys must be non-empty, non-index strings",
8319
+ InvalidStaticTransitionBranchKey<Branches>
7732
8320
  >
7733
- & { readonly cases: Cases }
7734
- & Machine.TransitionTyped<States, Events, Emits, StateId, Context, Reenter>
7735
8321
 
7736
8322
  /**
7737
- * Contextually types direct and conditional transition definitions.
8323
+ * Preserves inference for a state-owned invocation configuration.
7738
8324
  *
7739
- * @category constructors
7740
- * @since 0.14.0
7741
- */
7742
- export interface TransitionConstructor {
7743
- <
7744
- const States extends Machine.StateSchemas,
7745
- const Events extends ReadonlyArray<Machine.TaggedSchema>,
7746
- const Emits extends ReadonlyArray<Machine.TaggedSchema>,
7747
- StateId extends Machine.StateNodeIdentifier<States>,
7748
- Context,
7749
- const Selection extends Machine.TargetSelection<any, any, any>,
7750
- Reenter extends boolean = never
7751
- >(
7752
- config: Machine.TransitionDirectInput<States, Events, Emits, StateId, Context, Reenter, Selection>
7753
- ):
7754
- & Machine.TransitionDirectInput<States, Events, Emits, StateId, Context, Reenter, Selection>
7755
- & (Machine.SelectionKind<Selection> extends "none" ? Machine.TargetlessTransitionTyped
7756
- : Machine.TransitionTyped<States, Events, Emits, StateId, Context, Reenter>)
7757
- <
7758
- const States extends Machine.StateSchemas,
7759
- const Events extends ReadonlyArray<Machine.TaggedSchema>,
7760
- const Emits extends ReadonlyArray<Machine.TaggedSchema>,
7761
- StateId extends Machine.StateNodeIdentifier<States>,
7762
- Context,
7763
- const Cases extends readonly [
7764
- TransitionCaseTyped,
7765
- ...ReadonlyArray<TransitionCaseTyped>
7766
- ],
7767
- const OtherwiseSelection extends Machine.TargetSelection<any, any, any>,
7768
- Reenter extends boolean = never
7769
- >(
7770
- config: Machine.TransitionConditionalInput<
7771
- States,
7772
- Events,
7773
- Emits,
7774
- StateId,
7775
- Context,
7776
- Reenter,
7777
- Cases,
7778
- OtherwiseSelection
7779
- >
7780
- ): ConditionalTransitionResult<
7781
- States,
7782
- Events,
7783
- Emits,
7784
- StateId,
7785
- Context,
7786
- Reenter,
7787
- Cases,
7788
- OtherwiseSelection
7789
- >
7790
- }
7791
-
7792
- /**
7793
- * Defines a statically inspectable transition.
8325
+ * Use `effect` for one-shot work, `stream` for repeated values, `after` for a
8326
+ * cancellable timer, `logic` for reusable process logic, or `child` for a
8327
+ * complete child machine. Stream elements are handled by `onElement` before
8328
+ * the next element is pulled. `onDone` is required whenever the source can
8329
+ * complete, while `onFailure` is required only when the source has a typed
8330
+ * failure channel.
8331
+ *
8332
+ * This constructor is an identity at runtime, but preserves lifecycle callback
8333
+ * inference through published declarations. Effect and Stream factories run
8334
+ * when their owning state is entered and infer the owner context, value,
8335
+ * output, error, and service channels together without a return annotation.
8336
+ * Durations may be
8337
+ * supplied directly or derived from the owning state's entry context. Logic
8338
+ * invocations require both a lifecycle `id` and a typed communication
8339
+ * `address`. Child descriptors already own their identity, so `id` and
8340
+ * `address` must not be repeated.
7794
8341
  *
7795
- * It is required for every event, lifecycle, choice, and invocation transition
7796
- * so the destination selected by `target` can contextually type the
7797
- * corresponding resolver. Conditional transitions use the locally bound
7798
- * `branch` constructor so every case independently infers its matched value and
7799
- * selected destination, with no limit on the number of cases.
8342
+ * Inside `handle(...)`, the owning definition contextually supplies its public
8343
+ * input and declared parent protocols. Invocation sources and lifecycle handlers
8344
+ * can therefore send through `self` and `parent` without naming the definition.
8345
+ * The standard `Machine.invoke(...)` constructor preserves these contexts
8346
+ * directly; no intermediate definition method is required.
7800
8347
  *
7801
8348
  * ```ts
7802
- * Machine.transition({
7803
- * target: (to) => to.full.Ready(),
7804
- * resolve: ({ target }) => target.from()
7805
- * })
7806
- *
7807
- * Machine.transition({
7808
- * cases: (branch) => [
7809
- * branch({
7810
- * title: "has cached data",
7811
- * when: ({ event }) => event.cached,
7812
- * target: (to) => to.full.Ready(),
7813
- * resolve: ({ match, target }) => target.from({ data: match })
7814
- * })
7815
- * ],
7816
- * otherwise: {
7817
- * target: (to) => to.full.Loading(),
7818
- * resolve: ({ target }) => target.from()
7819
- * }
8349
+ * invoke: Machine.invoke({
8350
+ * id: "load",
8351
+ * effect: () =>
8352
+ * Effect.tryPromise({
8353
+ * try: () => fetch("/api/data").then((response) => response.json()),
8354
+ * catch: (cause) => new LoadError({ cause })
8355
+ * }),
8356
+ * onDone: (to) =>
8357
+ * to.full.Ready().resolve(({ output, target }) =>
8358
+ * target.from({ data: output })),
8359
+ * onFailure: (to) =>
8360
+ * to.full.Failed().resolve(({ error, target }) =>
8361
+ * target.from({ error }))
7820
8362
  * })
7821
8363
  * ```
7822
8364
  *
7823
8365
  * @category constructors
7824
- * @since 0.14.0
7825
- */
7826
- export const transition: TransitionConstructor = ((config: unknown) => {
7827
- if (!hasProperty(config, "cases") || typeof config.cases !== "function") return config
7828
- return {
7829
- ...config,
7830
- cases: config.cases(<Case extends object>(branch: Case): Case => branch)
7831
- }
7832
- }) as TransitionConstructor
7833
-
7834
- /**
7835
- * Machine-bound invocation constructor that preserves the owning machine's
7836
- * public input and parent protocols in every invocation callback.
7837
- *
7838
- * @category constructors
7839
- * @since 0.11.0
8366
+ * @since 0.9.0
7840
8367
  */
7841
- export interface Invoker<
7842
- States extends Machine.StateSchemas,
7843
- Events extends ReadonlyArray<Machine.TaggedSchema>,
7844
- Emits extends ReadonlyArray<Machine.TaggedSchema>,
7845
- InputEvents extends ReadonlyArray<Machine.TaggedSchema>,
7846
- ParentEvents extends ReadonlyArray<Machine.TaggedSchema>
7847
- > {
8368
+ export const invoke: {
7848
8369
  <
8370
+ const States extends Machine.StateSchemas,
8371
+ const Events extends ReadonlyArray<Machine.TaggedSchema>,
8372
+ const Emits extends ReadonlyArray<Machine.TaggedSchema>,
7849
8373
  StateId extends Machine.StateIdentifier<States>,
7850
8374
  const Source extends (
7851
8375
  context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
7852
- ) => Effect.Effect<unknown, unknown, unknown>
8376
+ ) => Effect.Effect<unknown, unknown, unknown>,
8377
+ const Config extends object,
8378
+ const InputEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
8379
+ const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
7853
8380
  >(
7854
8381
  config:
7855
- & BoundEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8382
+ & Config
8383
+ & EffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7856
8384
  & {
7857
- readonly onDone: BoundEffectDoneHandler<
7858
- States,
7859
- Events,
7860
- Emits,
7861
- InputEvents,
7862
- ParentEvents,
7863
- StateId,
7864
- Source
7865
- >
7866
- readonly onFailure: BoundEffectFailureHandler<
7867
- States,
7868
- Events,
7869
- Emits,
7870
- InputEvents,
7871
- ParentEvents,
7872
- StateId,
7873
- Source
7874
- >
8385
+ readonly onDone: EffectDoneHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8386
+ readonly onFailure: EffectFailureHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7875
8387
  },
7876
8388
  ..._validation: InvokeChannelIsNever<Effect.Success<ReturnType<Source>>> extends true ? [
7877
8389
  "onDone must be omitted when the Effect output is never"
@@ -7880,218 +8392,75 @@ export interface Invoker<
7880
8392
  "onFailure must be omitted when the Effect error is never"
7881
8393
  ]
7882
8394
  : []
7883
- ): BoundEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8395
+ ): NoInfer<Config> & EffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7884
8396
  <
8397
+ const States extends Machine.StateSchemas,
8398
+ const Events extends ReadonlyArray<Machine.TaggedSchema>,
8399
+ const Emits extends ReadonlyArray<Machine.TaggedSchema>,
7885
8400
  StateId extends Machine.StateIdentifier<States>,
7886
8401
  const Source extends (
7887
8402
  context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
7888
- ) => Effect.Effect<unknown, never, unknown>
8403
+ ) => Effect.Effect<unknown, never, unknown>,
8404
+ const Config extends object,
8405
+ const InputEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
8406
+ const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
7889
8407
  >(
7890
8408
  config:
7891
- & BoundEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8409
+ & Config
8410
+ & EffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7892
8411
  & {
7893
- readonly onDone: BoundEffectDoneHandler<
7894
- States,
7895
- Events,
7896
- Emits,
7897
- InputEvents,
7898
- ParentEvents,
7899
- StateId,
7900
- Source
7901
- >
8412
+ readonly onDone: EffectDoneHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7902
8413
  readonly onFailure?: never
7903
8414
  },
7904
8415
  ..._validation: InvokeChannelIsNever<Effect.Success<ReturnType<Source>>> extends true ? [
7905
8416
  "onDone must be omitted when the Effect output is never"
7906
8417
  ]
7907
8418
  : []
7908
- ): BoundEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8419
+ ): NoInfer<Config> & EffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7909
8420
  <
8421
+ const States extends Machine.StateSchemas,
8422
+ const Events extends ReadonlyArray<Machine.TaggedSchema>,
8423
+ const Emits extends ReadonlyArray<Machine.TaggedSchema>,
7910
8424
  StateId extends Machine.StateIdentifier<States>,
7911
8425
  const Source extends (
7912
8426
  context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
7913
- ) => Effect.Effect<never, unknown, unknown>
8427
+ ) => Effect.Effect<never, unknown, unknown>,
8428
+ const Config extends object,
8429
+ const InputEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
8430
+ const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
7914
8431
  >(
7915
8432
  config:
7916
- & BoundEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8433
+ & Config
8434
+ & EffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7917
8435
  & {
7918
8436
  readonly onDone?: never
7919
- readonly onFailure: BoundEffectFailureHandler<
7920
- States,
7921
- Events,
7922
- Emits,
7923
- InputEvents,
7924
- ParentEvents,
7925
- StateId,
7926
- Source
7927
- >
8437
+ readonly onFailure: EffectFailureHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7928
8438
  },
7929
8439
  ..._validation: InvokeChannelIsNever<Effect.Error<ReturnType<Source>>> extends true ? [
7930
8440
  "onFailure must be omitted when the Effect error is never"
7931
8441
  ]
7932
8442
  : []
7933
- ): BoundEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8443
+ ): NoInfer<Config> & EffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7934
8444
  <
8445
+ const States extends Machine.StateSchemas,
8446
+ const Events extends ReadonlyArray<Machine.TaggedSchema>,
8447
+ const Emits extends ReadonlyArray<Machine.TaggedSchema>,
7935
8448
  StateId extends Machine.StateIdentifier<States>,
7936
8449
  const Source extends (
7937
8450
  context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
7938
- ) => Effect.Effect<never, never, unknown>
8451
+ ) => Effect.Effect<never, never, unknown>,
8452
+ const Config extends object,
8453
+ const InputEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
8454
+ const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
7939
8455
  >(
7940
8456
  config:
7941
- & BoundEffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8457
+ & Config
8458
+ & EffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7942
8459
  & {
7943
8460
  readonly onDone?: never
7944
8461
  readonly onFailure?: never
7945
8462
  }
7946
- ): BoundEffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
7947
- <StateId extends Machine.StateIdentifier<States>, const Config extends object>(
7948
- config: Config & Machine.TimerInvokeArgs<States, Events, Emits, StateId, InputEvents, ParentEvents>
7949
- ): Config & Machine.InvokeOwned<States, Events, Emits, StateId> & Machine.InvokeTyped<void, never, never, never>
7950
- <
7951
- StateId extends Machine.StateIdentifier<States>,
7952
- const Source extends (
7953
- context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
7954
- ) => unknown,
7955
- Address extends ChildAddress<never>
7956
- >(
7957
- config:
7958
- & { readonly logic: Source }
7959
- & Machine.LogicInvokeArgs<
7960
- States,
7961
- Events,
7962
- Emits,
7963
- StateId,
7964
- Machine.LogicStateOf<ReturnType<Source>>,
7965
- Machine.LogicEventOf<ReturnType<Source>>,
7966
- Machine.LogicErrorOf<ReturnType<Source>>,
7967
- Machine.LogicServicesOf<ReturnType<Source>>,
7968
- Machine.LogicOutputOf<ReturnType<Source>>,
7969
- Machine.LogicInitialErrorOf<ReturnType<Source>>,
7970
- Address,
7971
- Source,
7972
- InputEvents,
7973
- ParentEvents
7974
- >,
7975
- ..._validation: ReturnType<Source> extends { readonly initial: unknown; readonly run: unknown } ? [] : [
7976
- "logic factory must return Machine.Logic"
7977
- ]
7978
- ):
7979
- & Machine.InvokeConfig<States, Events, Emits, StateId, InputEvents, ParentEvents>
7980
- & Machine.InvokeTyped<
7981
- Machine.LogicOutputOf<ReturnType<Source>>,
7982
- Machine.LogicErrorOf<ReturnType<Source>>,
7983
- Machine.LogicServicesOf<ReturnType<Source>>,
7984
- Machine.LogicInitialErrorOf<ReturnType<Source>>
7985
- >
7986
- <
7987
- StateId extends Machine.StateIdentifier<States>,
7988
- const Source,
7989
- Address extends ChildAddress<never>
7990
- >(
7991
- config:
7992
- & { readonly logic: Source }
7993
- & Machine.LogicInvokeArgs<
7994
- States,
7995
- Events,
7996
- Emits,
7997
- StateId,
7998
- Machine.LogicStateOf<Source>,
7999
- Machine.LogicEventOf<Source>,
8000
- Machine.LogicErrorOf<Source>,
8001
- Machine.LogicServicesOf<Source>,
8002
- Machine.LogicOutputOf<Source>,
8003
- Machine.LogicInitialErrorOf<Source>,
8004
- Address,
8005
- Source,
8006
- InputEvents,
8007
- ParentEvents
8008
- >,
8009
- ..._validation: Source extends { readonly initial: unknown; readonly run: unknown } ? [] : [
8010
- "logic must implement Machine.Logic"
8011
- ]
8012
- ):
8013
- & Machine.InvokeConfig<States, Events, Emits, StateId, InputEvents, ParentEvents>
8014
- & Machine.InvokeTyped<
8015
- Machine.LogicOutputOf<Source>,
8016
- Machine.LogicErrorOf<Source>,
8017
- Machine.LogicServicesOf<Source>,
8018
- Machine.LogicInitialErrorOf<Source>
8019
- >
8020
- <
8021
- StateId extends Machine.StateIdentifier<States>,
8022
- const Child extends ChildMachine.Any,
8023
- const Config extends object
8024
- >(
8025
- config:
8026
- & Config
8027
- & Machine.ChildInvokeArgs<
8028
- States,
8029
- Events,
8030
- Emits,
8031
- StateId,
8032
- Child["machine"],
8033
- Child,
8034
- InputEvents,
8035
- ParentEvents
8036
- >
8037
- ):
8038
- & Config
8039
- & Machine.InvokeOwned<States, Events, Emits, StateId>
8040
- & Machine.InvokeTyped<
8041
- Machine.Output<Child["machine"]>,
8042
- Machine.Error<Child["machine"]> | ActionError<Machine.Services<Child["machine"]>>,
8043
- Machine.Services<Child["machine"]>,
8044
- Machine.InitialError<Child["machine"]>,
8045
- Machine.Emit<Child["machine"]>,
8046
- Machine.EventOf<Machine.ParentEvents<Child["machine"]>>
8047
- >
8048
- }
8049
-
8050
- /**
8051
- * Preserves inference for a state-owned invocation configuration.
8052
- *
8053
- * Use `effect` for one-shot work, `after` for a cancellable timer, `logic` for
8054
- * reusable process logic, or `child` for a complete child machine. `onDone` is
8055
- * required whenever the source can complete with an output, while `onFailure`
8056
- * is required only when the source has a typed failure channel.
8057
- *
8058
- * This constructor is an identity at runtime, but preserves lifecycle callback
8059
- * inference through published declarations. Effect factories run when their
8060
- * owning state is entered and infer the owner context, output, error, and
8061
- * service channels together without a return annotation. Durations may be
8062
- * supplied directly or derived from the owning state's entry context. Logic
8063
- * invocations require both a lifecycle `id` and a typed communication
8064
- * `address`. Child descriptors already own their identity, so `id` and
8065
- * `address` must not be repeated.
8066
- *
8067
- * Inside `handle(...)`, the owning definition contextually supplies its public
8068
- * input and `parentEvents` protocols. Invocation sources and lifecycle handlers
8069
- * can therefore send through `self` and `parent` without naming the definition.
8070
- * The bound `definition.invoke(...)` constructor remains an equivalent form.
8071
- *
8072
- * ```ts
8073
- * invoke: Machine.invoke({
8074
- * id: "load",
8075
- * effect: () =>
8076
- * Effect.tryPromise({
8077
- * try: () => fetch("/api/data").then((response) => response.json()),
8078
- * catch: (cause) => new LoadError({ cause })
8079
- * }),
8080
- * onDone: Machine.transition({
8081
- * target: (to) => to.full.Ready(),
8082
- * resolve: ({ output, target }) => target.from({ data: output })
8083
- * }),
8084
- * onFailure: Machine.transition({
8085
- * target: (to) => to.full.Failed(),
8086
- * resolve: ({ error, target }) => target.from({ error })
8087
- * })
8088
- * })
8089
- * ```
8090
- *
8091
- * @category constructors
8092
- * @since 0.9.0
8093
- */
8094
- export const invoke: {
8463
+ ): NoInfer<Config> & EffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8095
8464
  <
8096
8465
  const States extends Machine.StateSchemas,
8097
8466
  const Events extends ReadonlyArray<Machine.TaggedSchema>,
@@ -8099,24 +8468,27 @@ export const invoke: {
8099
8468
  StateId extends Machine.StateIdentifier<States>,
8100
8469
  const Source extends (
8101
8470
  context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
8102
- ) => Effect.Effect<unknown, unknown, unknown>,
8471
+ ) => Stream.Stream<unknown, unknown, any>,
8472
+ const Config extends object,
8103
8473
  const InputEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
8104
8474
  const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
8105
8475
  >(
8106
8476
  config:
8107
- & EffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8477
+ & Config
8478
+ & StreamInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8108
8479
  & {
8109
- readonly onDone: EffectDoneHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8110
- readonly onFailure: EffectFailureHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8480
+ readonly onElement: StreamElementHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8481
+ readonly onDone: StreamDoneHandler<States, Events, Emits, InputEvents, ParentEvents, StateId>
8482
+ readonly onFailure: StreamFailureHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8111
8483
  },
8112
- ..._validation: InvokeChannelIsNever<Effect.Success<ReturnType<Source>>> extends true ? [
8113
- "onDone must be omitted when the Effect output is never"
8484
+ ..._validation: InvokeChannelIsNever<Stream.Success<ReturnType<Source>>> extends true ? [
8485
+ "onElement must be omitted when the Stream element is never"
8114
8486
  ]
8115
- : InvokeChannelIsNever<Effect.Error<ReturnType<Source>>> extends true ? [
8116
- "onFailure must be omitted when the Effect error is never"
8487
+ : InvokeChannelIsNever<Stream.Error<ReturnType<Source>>> extends true ? [
8488
+ "onFailure must be omitted when the Stream error is never"
8117
8489
  ]
8118
8490
  : []
8119
- ): EffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8491
+ ): NoInfer<Config> & StreamInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8120
8492
  <
8121
8493
  const States extends Machine.StateSchemas,
8122
8494
  const Events extends ReadonlyArray<Machine.TaggedSchema>,
@@ -8124,21 +8496,24 @@ export const invoke: {
8124
8496
  StateId extends Machine.StateIdentifier<States>,
8125
8497
  const Source extends (
8126
8498
  context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
8127
- ) => Effect.Effect<unknown, never, unknown>,
8499
+ ) => Stream.Stream<never, unknown, any>,
8500
+ const Config extends object,
8128
8501
  const InputEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
8129
8502
  const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
8130
8503
  >(
8131
8504
  config:
8132
- & EffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8505
+ & Config
8506
+ & StreamInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8133
8507
  & {
8134
- readonly onDone: EffectDoneHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8135
- readonly onFailure?: never
8508
+ readonly onElement?: never
8509
+ readonly onDone: StreamDoneHandler<States, Events, Emits, InputEvents, ParentEvents, StateId>
8510
+ readonly onFailure: StreamFailureHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8136
8511
  },
8137
- ..._validation: InvokeChannelIsNever<Effect.Success<ReturnType<Source>>> extends true ? [
8138
- "onDone must be omitted when the Effect output is never"
8512
+ ..._validation: InvokeChannelIsNever<Stream.Error<ReturnType<Source>>> extends true ? [
8513
+ "onFailure must be omitted when the Stream error is never"
8139
8514
  ]
8140
8515
  : []
8141
- ): EffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8516
+ ): NoInfer<Config> & StreamInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8142
8517
  <
8143
8518
  const States extends Machine.StateSchemas,
8144
8519
  const Events extends ReadonlyArray<Machine.TaggedSchema>,
@@ -8146,21 +8521,20 @@ export const invoke: {
8146
8521
  StateId extends Machine.StateIdentifier<States>,
8147
8522
  const Source extends (
8148
8523
  context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
8149
- ) => Effect.Effect<never, unknown, unknown>,
8524
+ ) => Stream.Stream<never, never, any>,
8525
+ const Config extends object,
8150
8526
  const InputEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
8151
8527
  const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
8152
8528
  >(
8153
8529
  config:
8154
- & EffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8530
+ & Config
8531
+ & StreamInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8155
8532
  & {
8156
- readonly onDone?: never
8157
- readonly onFailure: EffectFailureHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8158
- },
8159
- ..._validation: InvokeChannelIsNever<Effect.Error<ReturnType<Source>>> extends true ? [
8160
- "onFailure must be omitted when the Effect error is never"
8161
- ]
8162
- : []
8163
- ): EffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8533
+ readonly onElement?: never
8534
+ readonly onDone: StreamDoneHandler<States, Events, Emits, InputEvents, ParentEvents, StateId>
8535
+ readonly onFailure?: never
8536
+ }
8537
+ ): NoInfer<Config> & StreamInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8164
8538
  <
8165
8539
  const States extends Machine.StateSchemas,
8166
8540
  const Events extends ReadonlyArray<Machine.TaggedSchema>,
@@ -8168,17 +8542,20 @@ export const invoke: {
8168
8542
  StateId extends Machine.StateIdentifier<States>,
8169
8543
  const Source extends (
8170
8544
  context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
8171
- ) => Effect.Effect<never, never, unknown>,
8545
+ ) => Stream.Stream<unknown, never, any>,
8546
+ const Config extends object,
8172
8547
  const InputEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
8173
8548
  const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
8174
8549
  >(
8175
8550
  config:
8176
- & EffectInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8551
+ & Config
8552
+ & StreamInvokeSource<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8177
8553
  & {
8178
- readonly onDone?: never
8554
+ readonly onElement: StreamElementHandler<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8555
+ readonly onDone: StreamDoneHandler<States, Events, Emits, InputEvents, ParentEvents, StateId>
8179
8556
  readonly onFailure?: never
8180
8557
  }
8181
- ): EffectInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8558
+ ): NoInfer<Config> & StreamInvokeResult<States, Events, Emits, InputEvents, ParentEvents, StateId, Source>
8182
8559
  <
8183
8560
  const States extends Machine.StateSchemas,
8184
8561
  const Events extends ReadonlyArray<Machine.TaggedSchema>,
@@ -8189,64 +8566,60 @@ export const invoke: {
8189
8566
  const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
8190
8567
  >(
8191
8568
  config: Config & Machine.TimerInvokeArgs<States, Events, Emits, StateId, InputEvents, ParentEvents>
8192
- ): Config & Machine.InvokeOwned<States, Events, Emits, StateId> & Machine.InvokeTyped<void, never, never, never>
8569
+ ):
8570
+ & NoInfer<Config>
8571
+ & Machine.InvokeOwned<States, Events, Emits, StateId, InputEvents, ParentEvents>
8572
+ & Machine.InvokeTyped<void, never, never, never>
8193
8573
  <
8194
8574
  const States extends Machine.StateSchemas,
8195
8575
  const Events extends ReadonlyArray<Machine.TaggedSchema>,
8196
8576
  const Emits extends ReadonlyArray<Machine.TaggedSchema>,
8197
8577
  StateId extends Machine.StateIdentifier<States>,
8198
- ChildState,
8199
- ChildEvent,
8200
- ChildError,
8201
- ChildRequirements,
8202
- ChildOutput,
8203
- ChildInitialError,
8578
+ const Source extends (
8579
+ context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>
8580
+ ) => unknown,
8204
8581
  Address extends ChildAddress<never>,
8582
+ const Config extends object,
8205
8583
  const InputEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
8206
8584
  const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
8207
8585
  >(
8208
- config: Machine.LogicInvokeArgs<
8209
- States,
8210
- Events,
8211
- Emits,
8212
- StateId,
8213
- ChildState,
8214
- ChildEvent,
8215
- ChildError,
8216
- ChildRequirements,
8217
- ChildOutput,
8218
- ChildInitialError,
8219
- Address,
8220
- (context: Machine.InvokeContext<States, Events, Emits, StateId, InputEvents, ParentEvents>) => Logic<
8221
- ChildState,
8222
- ChildEvent,
8223
- ChildError,
8224
- ChildRequirements,
8225
- ChildOutput,
8226
- ChildInitialError
8586
+ config:
8587
+ & Config
8588
+ & { readonly logic: Source }
8589
+ & Machine.LogicInvokeArgs<
8590
+ States,
8591
+ Events,
8592
+ Emits,
8593
+ StateId,
8594
+ Machine.LogicStateOf<ReturnType<Source>>,
8595
+ Machine.LogicEventOf<ReturnType<Source>>,
8596
+ Machine.LogicErrorOf<ReturnType<Source>>,
8597
+ Machine.LogicServicesOf<ReturnType<Source>>,
8598
+ Machine.LogicOutputOf<ReturnType<Source>>,
8599
+ Machine.LogicInitialErrorOf<ReturnType<Source>>,
8600
+ Address,
8601
+ Source,
8602
+ InputEvents,
8603
+ ParentEvents
8227
8604
  >,
8228
- InputEvents,
8229
- ParentEvents
8230
- >
8605
+ ..._validation: ReturnType<Source> extends { readonly initial: unknown; readonly run: unknown } ? [] : [
8606
+ "logic factory must return Machine.Logic"
8607
+ ]
8231
8608
  ):
8232
- & Machine.InvokeConfig<States, Events, Emits, StateId, InputEvents, ParentEvents>
8609
+ & NoInfer<Config>
8610
+ & Machine.InvokeOwned<States, Events, Emits, StateId, InputEvents, ParentEvents>
8233
8611
  & Machine.InvokeTyped<
8234
- ChildOutput,
8235
- ChildError,
8236
- ChildRequirements,
8237
- ChildInitialError
8612
+ Machine.LogicOutputOf<ReturnType<Source>>,
8613
+ Machine.LogicErrorOf<ReturnType<Source>>,
8614
+ Machine.LogicServicesOf<ReturnType<Source>>,
8615
+ Machine.LogicInitialErrorOf<ReturnType<Source>>
8238
8616
  >
8239
8617
  <
8240
8618
  const States extends Machine.StateSchemas,
8241
8619
  const Events extends ReadonlyArray<Machine.TaggedSchema>,
8242
8620
  const Emits extends ReadonlyArray<Machine.TaggedSchema>,
8243
8621
  StateId extends Machine.StateIdentifier<States>,
8244
- ChildState,
8245
- ChildEvent,
8246
- ChildError,
8247
- ChildRequirements,
8248
- ChildOutput,
8249
- ChildInitialError,
8622
+ const Source,
8250
8623
  Address extends ChildAddress<never>,
8251
8624
  const Config extends object,
8252
8625
  const InputEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
@@ -8254,30 +8627,34 @@ export const invoke: {
8254
8627
  >(
8255
8628
  config:
8256
8629
  & Config
8630
+ & { readonly logic: Source }
8257
8631
  & Machine.LogicInvokeArgs<
8258
8632
  States,
8259
8633
  Events,
8260
8634
  Emits,
8261
8635
  StateId,
8262
- ChildState,
8263
- ChildEvent,
8264
- ChildError,
8265
- ChildRequirements,
8266
- ChildOutput,
8267
- ChildInitialError,
8636
+ Machine.LogicStateOf<Source>,
8637
+ Machine.LogicEventOf<Source>,
8638
+ Machine.LogicErrorOf<Source>,
8639
+ Machine.LogicServicesOf<Source>,
8640
+ Machine.LogicOutputOf<Source>,
8641
+ Machine.LogicInitialErrorOf<Source>,
8268
8642
  Address,
8269
- Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>,
8643
+ Source,
8270
8644
  InputEvents,
8271
8645
  ParentEvents
8272
- >
8646
+ >,
8647
+ ..._validation: Source extends { readonly initial: unknown; readonly run: unknown } ? [] : [
8648
+ "logic must implement Machine.Logic"
8649
+ ]
8273
8650
  ):
8274
- & Config
8275
- & Machine.InvokeOwned<States, Events, Emits, StateId>
8651
+ & NoInfer<Config>
8652
+ & Machine.InvokeOwned<States, Events, Emits, StateId, InputEvents, ParentEvents>
8276
8653
  & Machine.InvokeTyped<
8277
- ChildOutput,
8278
- ChildError,
8279
- ChildRequirements,
8280
- ChildInitialError
8654
+ Machine.LogicOutputOf<Source>,
8655
+ Machine.LogicErrorOf<Source>,
8656
+ Machine.LogicServicesOf<Source>,
8657
+ Machine.LogicInitialErrorOf<Source>
8281
8658
  >
8282
8659
  <
8283
8660
  const States extends Machine.StateSchemas,
@@ -8294,7 +8671,7 @@ export const invoke: {
8294
8671
  & Machine.ChildInvokeArgs<States, Events, Emits, StateId, Child["machine"], Child, InputEvents, ParentEvents>
8295
8672
  ):
8296
8673
  & Config
8297
- & Machine.InvokeOwned<States, Events, Emits, StateId>
8674
+ & Machine.InvokeOwned<States, Events, Emits, StateId, InputEvents, ParentEvents>
8298
8675
  & Machine.InvokeTyped<
8299
8676
  Machine.Output<Child["machine"]>,
8300
8677
  Machine.Error<Child["machine"]> | ActionError<Machine.Services<Child["machine"]>>,
@@ -8333,10 +8710,7 @@ export const invoke: {
8333
8710
  * const machine = Machine.make({
8334
8711
  * states: States.states,
8335
8712
  * events: Machine.events(),
8336
- * initial: {
8337
- * target: (to) => to.Idle(),
8338
- * resolve: ({ target }) => target.from()
8339
- * }
8713
+ * initial: (to) => to.Idle().resolve(({ target }) => target.from())
8340
8714
  * }).handle({ Idle: {} })
8341
8715
  *
8342
8716
  * const initialState = Effect.map(Machine.planInitial(machine), (plan) => plan.state)
@@ -8380,7 +8754,8 @@ export const planInitial: <
8380
8754
  InputEvents,
8381
8755
  ParentEvents
8382
8756
  >
8383
- & EnsureExecutable<States, UnhandledStates, OutputStates>,
8757
+ & EnsureExecutable<States, UnhandledStates, OutputStates>
8758
+ & Machine.RootCompatible<ParentEvents>,
8384
8759
  ...args: [...Machine.InputArgs<Input>]
8385
8760
  ) => Effect.Effect<
8386
8761
  & {
@@ -8464,9 +8839,9 @@ export const initialDefinition: <M extends Machine.Any>(machine: M) => Machine.I
8464
8839
  *
8465
8840
  * Event handlers retain their handler-key order within each source state and
8466
8841
  * are followed by eventless and completion handlers. This function does not
8467
- * execute predicates or resolvers. Every direct, conditional, fallback, and
8468
- * targetless branch exposes the destination selected by its required static
8469
- * `target` declaration.
8842
+ * execute resolvers. Every direct, named, and targetless branch exposes the
8843
+ * destination selected by its required static `target` declaration, while
8844
+ * `acceptance` reports whether the resolver may decline the transition.
8470
8845
  *
8471
8846
  * @category getters
8472
8847
  * @since 0.4.0
@@ -8519,7 +8894,12 @@ export const configuration: <M extends Machine.Any>(
8519
8894
  > = internal.configuration
8520
8895
 
8521
8896
  /**
8522
- * Returns the event tags handled by the current state snapshot.
8897
+ * Returns event tags with at least one structurally eligible handler in the
8898
+ * current state snapshot.
8899
+ *
8900
+ * A `declinable` handler may still reject a concrete event at planning time,
8901
+ * so this is a static candidate query rather than a guarantee that every value
8902
+ * with the returned tag will be handled.
8523
8903
  *
8524
8904
  * @category getters
8525
8905
  * @since 0.4.0
@@ -8589,17 +8969,12 @@ export const enabled: <
8589
8969
  * const machine = Machine.make({
8590
8970
  * states: States.states,
8591
8971
  * events: Machine.events(Toggle),
8592
- * initial: {
8593
- * target: (to) => to.Off(),
8594
- * resolve: ({ target }) => target.from()
8595
- * }
8972
+ * initial: (to) => to.Off().resolve(({ target }) => target.from())
8596
8973
  * }).handle({
8597
8974
  * Off: {
8598
8975
  * on: {
8599
- * Toggle: Machine.transition({
8600
- * target: (to) => to.full.On(),
8601
- * resolve: ({ target }) => target.from()
8602
- * })
8976
+ * Toggle: (to) =>
8977
+ * to.full.On().resolve(({ target }) => target.from())
8603
8978
  * }
8604
8979
  * },
8605
8980
  * On: {}
@@ -8649,7 +9024,8 @@ export const plan: <
8649
9024
  InputEvents,
8650
9025
  ParentEvents
8651
9026
  >
8652
- & EnsureExecutable<States, UnhandledStates, OutputStates>,
9027
+ & EnsureExecutable<States, UnhandledStates, OutputStates>
9028
+ & Machine.RootCompatible<ParentEvents>,
8653
9029
  state: Machine.Snapshot<States>,
8654
9030
  event: Machine.EventInputOf<InputEvents>
8655
9031
  ) => Effect.Effect<
@@ -8911,7 +9287,8 @@ export const prepare: <
8911
9287
  InputEvents,
8912
9288
  ParentEvents
8913
9289
  >
8914
- & EnsureExecutable<States, UnhandledStates, OutputStates>,
9290
+ & EnsureExecutable<States, UnhandledStates, OutputStates>
9291
+ & Machine.RootCompatible<ParentEvents>,
8915
9292
  ...args: [...Machine.InputArgs<Input>]
8916
9293
  ) => Effect.Effect<
8917
9294
  Prepared<
@@ -8972,10 +9349,7 @@ export const prepare: <
8972
9349
  * const machine = Machine.make({
8973
9350
  * states: States.states,
8974
9351
  * events: Machine.events(),
8975
- * initial: {
8976
- * target: (to) => to.Idle(),
8977
- * resolve: ({ target }) => target.from()
8978
- * }
9352
+ * initial: (to) => to.Idle().resolve(({ target }) => target.from())
8979
9353
  * }).handle({ Idle: {} })
8980
9354
  *
8981
9355
  * const state = Effect.gen(function*() {
@@ -9022,7 +9396,8 @@ export const start: <
9022
9396
  InputEvents,
9023
9397
  ParentEvents
9024
9398
  >
9025
- & EnsureExecutable<States, UnhandledStates, OutputStates>,
9399
+ & EnsureExecutable<States, UnhandledStates, OutputStates>
9400
+ & Machine.RootCompatible<ParentEvents>,
9026
9401
  ...args: [...Machine.InputArgs<Input>]
9027
9402
  ) => Effect.Effect<
9028
9403
  MachineRef<
@@ -9085,10 +9460,7 @@ export const start: <
9085
9460
  * const machine = Machine.make({
9086
9461
  * states: States.states,
9087
9462
  * events: Machine.events(),
9088
- * initial: {
9089
- * target: (to) => to.Idle(),
9090
- * resolve: ({ target }) => target.from()
9091
- * }
9463
+ * initial: (to) => to.Idle().resolve(({ target }) => target.from())
9092
9464
  * }).handle({ Idle: {} })
9093
9465
  *
9094
9466
  * const resumed = Effect.gen(function*() {
@@ -9137,7 +9509,8 @@ export const resume: <
9137
9509
  InputEvents,
9138
9510
  ParentEvents
9139
9511
  >
9140
- & EnsureExecutable<States, UnhandledStates, OutputStates>,
9512
+ & EnsureExecutable<States, UnhandledStates, OutputStates>
9513
+ & Machine.RootCompatible<ParentEvents>,
9141
9514
  snapshot: Machine.Snapshot<States>
9142
9515
  ) => Effect.Effect<
9143
9516
  MachineRef<