@typeonce/effect-machine 0.15.0 → 0.17.0

package/src/internal/machine/topology.ts

@@ -25,8 +25,12 @@ export const ChoiceTargetTypeId: unique symbol = Symbol("effect/Machine/ChoiceTa
 
 export const NoTargetTypeId: unique symbol = Symbol("effect/Machine/NoTarget")
 
+export const DeclinedTypeId: unique symbol = Symbol("effect/Machine/Declined")
+
 export const TargetSelectionTypeId: unique symbol = Symbol("effect/Machine/TargetSelection")
 
+export const SelectedBranchTypeId: unique symbol = Symbol("effect/Machine/SelectedBranch")
+
 interface StateInput {
   readonly [StateInputTypeId]: typeof StateInputTypeId
   readonly input: unknown
@@ -64,6 +68,11 @@ export interface NoTarget {
   readonly [NoTargetTypeId]: typeof NoTargetTypeId
 }
 
+/** Internal marker returned when a declinable transition is not enabled. */
+export interface Declined {
+  readonly [DeclinedTypeId]: typeof DeclinedTypeId
+}
+
 export type TargetSelectionKind = "state" | "initial" | "history" | "choice" | "none"
 
 export type TargetSelectionScope = "local" | "branch" | "full" | "initial"
@@ -76,6 +85,15 @@ export interface TargetSelection {
   readonly path: string | undefined
 }
 
+/** One branch selection returned by a compiled branching transition. */
+export interface SelectedBranch {
+  readonly [SelectedBranchTypeId]: typeof SelectedBranchTypeId
+  readonly owner: object
+  readonly branchIndex: number
+  readonly branchKey: string
+  readonly result: unknown
+}
+
 export const makeTargetSelection = (
   kind: TargetSelectionKind,
   path?: string,
@@ -88,8 +106,27 @@ export const makeTargetSelection = (
     path
   })
 
+/** Source-independent definition-time selection for an explicitly targetless transition. */
+export const noneTargetSelection: TargetSelection = makeTargetSelection("none", undefined, "local")
+
 export const isTargetSelection = (u: unknown): u is TargetSelection => hasProperty(u, TargetSelectionTypeId)
 
+export const makeSelectedBranch = (
+  owner: object,
+  branchIndex: number,
+  branchKey: string,
+  result: unknown
+): SelectedBranch =>
+  Object.freeze({
+    [SelectedBranchTypeId]: SelectedBranchTypeId,
+    owner,
+    branchIndex,
+    branchKey,
+    result
+  })
+
+export const isSelectedBranch = (u: unknown): u is SelectedBranch => hasProperty(u, SelectedBranchTypeId)
+
 const noTarget = Object.freeze({
   [NoTargetTypeId]: NoTargetTypeId
 }) as NoTarget
@@ -98,6 +135,14 @@ export const makeNoTarget = (): Machine.NoTarget => noTarget
 
 export const isNoTarget = (u: unknown): u is Machine.NoTarget => hasProperty(u, NoTargetTypeId)
 
+const declined = Object.freeze({
+  [DeclinedTypeId]: DeclinedTypeId
+}) as Declined
+
+export const makeDeclined = (): Machine.Declined => declined
+
+export const isDeclined = (u: unknown): u is Machine.Declined => hasProperty(u, DeclinedTypeId)
+
 export const makeHistoryTarget = (path: string, parent: string): HistoryTarget => ({
   [HistoryTargetTypeId]: HistoryTargetTypeId,
   path,
@@ -414,6 +459,11 @@ const transitionBranches = (handler: unknown): ReadonlyArray<Machine.TransitionB
     ? Array.from(handler.branches as ReadonlyArray<Machine.TransitionBranch>)
     : []
 
+const transitionAcceptance = (handler: unknown): Machine.TransitionAcceptance =>
+  typeof handler === "object" && handler !== null && "declinable" in handler && handler.declinable === true
+    ? "declinable"
+    : "required"
+
 export const transitionDefinitions = (
   machine: Machine.Any
 ): ReadonlyArray<Machine.TransitionDefinition> => {
@@ -430,6 +480,7 @@ export const transitionDefinitions = (
           source: node.path,
           trigger: { type: "choice" },
           reenter: false,
+          acceptance: "required",
           branches: transitionBranches(choice)
         })
       }
@@ -441,6 +492,7 @@ export const transitionDefinitions = (
         source: node.path,
         trigger: { type: "event", event },
         reenter: hasProperty(handler, "reenter") && handler.reenter === true,
+        acceptance: transitionAcceptance(handler),
         branches: transitionBranches(handler)
       })
     }
@@ -449,6 +501,7 @@ export const transitionDefinitions = (
         source: node.path,
         trigger: { type: "always" },
         reenter: false,
+        acceptance: transitionAcceptance(config.always),
         branches: transitionBranches(config.always)
       })
     }
@@ -457,6 +510,7 @@ export const transitionDefinitions = (
         source: node.path,
         trigger: { type: "done" },
         reenter: false,
+        acceptance: transitionAcceptance(config.onDone),
         branches: transitionBranches(config.onDone)
       })
     }
@@ -467,8 +521,10 @@ export const transitionDefinitions = (
       : [config.invoke]
     for (const invoke of invokes) {
       const id = "child" in invoke ? String(invoke.child.id) : String(invoke.id)
-      for (const outcome of ["done", "failure", "snapshot"] as const) {
-        const handler = outcome === "done"
+      for (const outcome of ["element", "done", "failure", "snapshot"] as const) {
+        const handler = outcome === "element"
+          ? invoke.onElement
+          : outcome === "done"
           ? invoke.onDone
           : outcome === "failure"
           ? invoke.onFailure
@@ -478,6 +534,7 @@ export const transitionDefinitions = (
             source: node.path,
             trigger: { type: "invoke", id, outcome },
             reenter: typeof handler === "object" && handler !== null && handler.reenter === true,
+            acceptance: transitionAcceptance(handler),
             branches: transitionBranches(handler)
           })
         }

package/src/internal/testing/machine/finiteModel.ts

@@ -1316,7 +1316,7 @@ const selectHistoryTarget = (builder: Record<string, any>, path: string): unknow
   const parts = path.split(".")
   let current: any = builder
   for (let index = 0; index < parts.length - 1; index++) current = current[parts[index]!]
-  return current[parts[parts.length - 1]!]()
+  return current[parts[parts.length - 1]!]
 }
 
 const selectableDefinitionTarget = (
@@ -1356,7 +1356,7 @@ const selectDefinitionTarget = (
   const parts = selectable.split(".")
   for (const part of parts) current = current[part]
   if (typeof current === "function") return current()
-  return current.initial()
+  return current.initial
 }
 
 const resolveDefinitionTarget = (
@@ -1415,11 +1415,10 @@ const makeHandlers = (
     if (node._tag === "History") continue
     if (node._tag === "Choice") {
       handlers[node.key] = {
-        choice: (Machine.transition as any)({
-          target: (to: Record<string, any>) => selectDefinitionTarget(to, path, node.selected, byPath) as any,
-          resolve: ({ target }: { readonly target: any }) =>
-            resolveDefinitionTarget(target, path, node.selected, byPath)
-        } as any)
+        choice: (to: Record<string, any>) =>
+          (selectDefinitionTarget(to, path, node.selected, byPath) as any).resolve(
+            ({ target }: { readonly target: any }) => resolveDefinitionTarget(target, path, node.selected, byPath)
+          )
       }
       continue
     }
@@ -1432,17 +1431,16 @@ const makeHandlers = (
     let onDone: unknown
     for (const transition of transitions.values()) {
       if (transition.source !== path) continue
-      const config = (Machine.transition as any)({
-        ...("reenter" in transition ? { reenter: transition.reenter } : {}),
-        target: (to: Record<string, any>) =>
-          transition.target === undefined
-            ? to.none()
-            : selectDefinitionTarget(to, path, transition.target, byPath),
-        resolve: transition.target === undefined
+      const config = (to: Record<string, any>) => {
+        const selected = transition.target === undefined
+          ? to.none
+          : selectDefinitionTarget(to, path, transition.target, byPath)
+        const resolve = transition.target === undefined
           ? () => undefined
           : ({ target }: { readonly target: any }) =>
             resolveDefinitionTarget(target, path, transition.target!, byPath, transition.targetValue)
-      } as any)
+        return selected.resolve(resolve, "reenter" in transition ? { reenter: transition.reenter } : undefined)
+      }
       if (transition.trigger.type === "event") on[transition.trigger.event] = config
       else if (transition.trigger.type === "always") always = config
       else onDone = config
@@ -1515,13 +1513,12 @@ export const compileModel = (model: FiniteModel): Machine.Machine.Any => {
   const machine = Machine.make({
     states: defined.states as any,
     events: Machine.events(...eventSchemas) as any,
-    initial: {
-      target: (to: Record<string, any>) => {
-        const selected = to[initial.path]
-        return typeof selected === "function" ? selected() : selected.initial()
-      },
-      resolve: ({ target }: { readonly target: any }) =>
+    initial: (to: Record<string, any>) => {
+      const selected = to[initial.path]
+      const selection = typeof selected === "function" ? selected() : selected.initial
+      return selection.resolve(({ target }: { readonly target: any }) =>
         selectSnapshot({ [initial.path]: target }, initial.path, byPath, [initial.path], 0) as any
+      )
     }
   } as any)
   const transitions = new Map(model.transitions.map((transition) => [

package/src/internal/testing/machine/transitionCoverage.ts

@@ -66,6 +66,7 @@ export const makeTransitionCoverageCollector = <M extends AnyMachine>(
       source: definition.source,
       trigger: definition.trigger,
       reenter: definition.reenter,
+      acceptance: definition.acceptance,
       branches: definition.branches
     })
   )
@@ -76,13 +77,16 @@ export const makeTransitionCoverageCollector = <M extends AnyMachine>(
     branchOffsets.push(branches.length)
     const definition = definitions[definitionIndex]!
     definition.branches.forEach((branch, branchIndex) => {
+      const branchKey = branch.type === "branch" ? branch.key : undefined
       branches.push({
-        id: `transition:${definitionIndex}:branch:${branchIndex}`,
+        id: `transition:${definitionIndex}:branch:${branchKey ?? "direct"}`,
         definitionIndex,
         branchIndex,
+        branchKey,
         source: definition.source,
         trigger: definition.trigger,
         reenter: definition.reenter,
+        acceptance: definition.acceptance,
         branch
       })
     })
@@ -100,9 +104,11 @@ export const makeTransitionCoverageCollector = <M extends AnyMachine>(
         if (definitionIndex === -1) continue
         definitionHits.add(definitionIndex)
         const definition = definitions[definitionIndex]!
+        const branch = definition.branches[retained.branchIndex]
         if (
           Number.isSafeInteger(retained.branchIndex) && retained.branchIndex >= 0 &&
-          retained.branchIndex < definition.branches.length
+          retained.branchIndex < definition.branches.length &&
+          retained.branchKey === (branch?.type === "branch" ? branch.key : undefined)
         ) {
           branchHits.add(branchOffsets[definitionIndex]! + retained.branchIndex)
         }

package/src/internal/testing/machine/verification.ts

@@ -1512,6 +1512,17 @@ export const verify = <M extends AnyMachine>(
       return undefined
     }
     const branch = definition.branches[transition.branchIndex]!
+    const expectedBranchKey = branch.type === "branch" ? branch.key : undefined
+    if (transition.branchKey !== expectedBranchKey) {
+      add(
+        "definitions.branchKey",
+        location,
+        `retained transition from "${transition.source}" selected branch key ` +
+          `"${String(transition.branchKey)}" instead of "${String(expectedBranchKey)}"`,
+        transition.source
+      )
+      return undefined
+    }
     if (!targetWithinSelection(transition.target, branch, byPath)) {
       const expected = branch.selection.kind === "none"
         ? "an explicitly targetless result"

package/src/testing/MachineTest.ts

@@ -138,6 +138,10 @@ type ReadyMachine<M extends AnyMachine> =
     Machine.Machine.OutputStates<M>
   >
 
+type RootReadyMachine<M extends AnyMachine> =
+  & ReadyMachine<M>
+  & Machine.Machine.RootCompatible<Machine.Machine.ParentEvents<M>>
+
 /**
  * A generated public-input scenario for a machine.
  *
@@ -238,10 +242,8 @@ export interface Scenarios<M extends AnyMachine> {
  * }).handle({
  *   Idle: {
  *     on: {
- *       Reset: Machine.transition({
- *         target: (to) => to.full.Idle(),
- *         resolve: ({ target }) => target.from()
- *       })
+ *       Reset: (to) =>
+ *         to.full.Idle().resolve(({ target }) => target.from())
  *     }
  *   }
  * })
@@ -881,7 +883,7 @@ export { PlannerRuntimeAgreementError } from "../internal/testing/machine/verifi
  * @since 0.4.0
  */
 export const assertPlannerRuntimeAgreement: <M extends AnyMachine, Error, Output>(
-  machine: ReadyMachine<M>,
+  machine: RootReadyMachine<M>,
   transcript: CausalRuntimeEvidence<M, Error, Output>
 ) => Effect.Effect<void, internal.PlannerRuntimeAgreementError<M>, RunServices<M>> =
   internal.assertPlannerRuntimeAgreement
@@ -1447,10 +1449,9 @@ export type ExploreOptions<M extends AnyMachine, Key extends ExplorationKey = Ex
  * }).handle({
  *   Count: {
  *     on: {
- *       Increment: Machine.transition({
- *         target: (to) => to.full.Count(),
- *         resolve: ({ state, target }) => target(new Count({ value: state.value + 1 }))
- *       })
+ *       Increment: (to) =>
+ *         to.full.Count().resolve(({ state, target }) =>
+ *           target(new Count({ value: state.value + 1 })))
  *     }
  *   }
  * })
@@ -1465,7 +1466,7 @@ export type ExploreOptions<M extends AnyMachine, Key extends ExplorationKey = Ex
  * @since 0.4.0
  */
 export const explore: <M extends AnyMachine, Key extends ExplorationKey>(
-  machine: ReadyMachine<M>,
+  machine: RootReadyMachine<M>,
   options: ExploreOptions<M, Key>
 ) => Effect.Effect<
   Exploration<M, Key>,
@@ -1646,7 +1647,7 @@ export type RunServices<M extends AnyMachine> = IsAny<
  * @since 0.4.0
  */
 export const run: <M extends AnyMachine>(
-  machine: ReadyMachine<M>,
+  machine: RootReadyMachine<M>,
   scenario: Scenario<M>
 ) => Effect.Effect<Trace<M>, RunFailure<RunError<M>, M>, RunServices<M>> = internal.run
 
@@ -1703,6 +1704,7 @@ export interface TransitionDefinitionCoverageItem<
   readonly source: SourcePath
   readonly trigger: Machine.Machine.TransitionTrigger<EventTag>
   readonly reenter: boolean
+  readonly acceptance: Machine.Machine.TransitionAcceptance
   readonly branches: ReadonlyArray<Machine.Machine.TransitionBranch<TargetPath>>
 }
 
@@ -1721,9 +1723,11 @@ export interface TransitionBranchCoverageItem<
   readonly id: string
   readonly definitionIndex: number
   readonly branchIndex: number
+  readonly branchKey: string | undefined
   readonly source: SourcePath
   readonly trigger: Machine.Machine.TransitionTrigger<EventTag>
   readonly reenter: boolean
+  readonly acceptance: Machine.Machine.TransitionAcceptance
   readonly branch: Machine.Machine.TransitionBranch<TargetPath>
 }
 
@@ -2063,6 +2067,7 @@ export type VerificationLaw =
   | "definitions.initial"
   | "definitions.transition"
   | "definitions.branchIndex"
+  | "definitions.branchKey"
   | "definitions.selection"
   | "definitions.resolution"
 

package/src/unstable/cluster/ClusterMachine.ts

@@ -342,7 +342,8 @@ export const make: <
   Output,
   Emits extends ReadonlyArray<Machine.Machine.TaggedSchema>,
   OutputStates extends Machine.Machine.StateIdentifier<States>,
-  InputEvents extends ReadonlyArray<Machine.Machine.TaggedSchema> = Events
+  InputEvents extends ReadonlyArray<Machine.Machine.TaggedSchema> = Events,
+  ParentEvents extends ReadonlyArray<Machine.Machine.TaggedSchema> = readonly []
 >(
   type: Type,
   machine:
@@ -359,9 +360,11 @@ export const make: <
       Output,
       Emits,
       OutputStates,
-      InputEvents
+      InputEvents,
+      ParentEvents
     >
-    & EnsureExecutable<States, UnhandledStates, OutputStates>,
+    & EnsureExecutable<States, UnhandledStates, OutputStates>
+    & Machine.Machine.RootCompatible<ParentEvents>,
   options: {
     readonly version: string
   },
@@ -381,7 +384,8 @@ export const make: <
     Output,
     Emits,
     OutputStates,
-    InputEvents
+    InputEvents,
+    ParentEvents
   >,
   | ExcludeCompatibleRuntime<
     Machine.ExecutionServices<R | InitialR>,

package/src/unstable/reactivity/AtomMachine.ts

@@ -159,11 +159,11 @@ export interface MachineAtom<State, Event, Error = never, Output = never, StartE
   ) => ChildMachineAtom<Child, StartError>
 }
 
-type RefState<Ref> = Ref extends Machine.MachineRef<infer State, any, any, any> ? State : never
+type RefState<Ref> = Ref extends Machine.MachineRef<infer State, any, any, any, any> ? State : never
 
-type RefError<Ref> = Ref extends Machine.MachineRef<any, any, infer Error, any> ? Error : never
+type RefError<Ref> = Ref extends Machine.MachineRef<any, any, infer Error, any, any> ? Error : never
 
-type RefOutput<Ref> = Ref extends Machine.MachineRef<any, any, any, infer Output> ? Output : never
+type RefOutput<Ref> = Ref extends Machine.MachineRef<any, any, any, infer Output, any> ? Output : never
 type RefEmitted<Ref> = Ref extends Machine.MachineRef<any, any, any, any, infer Emitted> ? Emitted : never
 
 /**
@@ -305,7 +305,7 @@ export interface ChildMachineAtom<Child extends Machine.ChildMachine.Any, StartE
   ) => ChildMachineAtom<Nested, StartError>
 }
 
-type BridgeStartError<Bridge> = Bridge extends MachineAtom<any, any, any, any, infer StartError> ? StartError
+type BridgeStartError<Bridge> = Bridge extends MachineAtom<any, never, any, any, infer StartError, any> ? StartError
   : Bridge extends ChildMachineAtom<any, infer StartError> ? StartError
   : never
 
@@ -317,7 +317,7 @@ type BridgeStartError<Bridge> = Bridge extends MachineAtom<any, any, any, any, i
  * @since 0.4.0
  */
 export type ChildOf<
-  Parent extends MachineAtom<any, any, any, any, any> | ChildMachineAtom<any, any>,
+  Parent extends MachineAtom<any, never, any, any, any, any> | ChildMachineAtom<any, any>,
   Child extends Machine.ChildMachine.Any
 > = ChildMachineAtom<Child, BridgeStartError<Parent>>
 
@@ -389,8 +389,9 @@ export const select: <
   Error,
   Output,
   StartError,
+  Emitted,
   const Path extends ValuedSnapshotIdentifier<State>
->(self: MachineAtom<State, Event, Error, Output, StartError>, path: Path) => Atom.Atom<
+>(self: MachineAtom<State, Event, Error, Output, StartError, Emitted>, path: Path) => Atom.Atom<
   AsyncResult.AsyncResult<Option.Option<SnapshotValueByIdentifier<State, Path>>, StartError | Error>
 > = internal.select
 
@@ -410,8 +411,9 @@ export const selectSnapshot: <
   Error,
   Output,
   StartError,
+  Emitted,
   const Path extends SnapshotIdentifier<State>
->(self: MachineAtom<State, Event, Error, Output, StartError>, path: Path) => Atom.Atom<
+>(self: MachineAtom<State, Event, Error, Output, StartError, Emitted>, path: Path) => Atom.Atom<
   AsyncResult.AsyncResult<Option.Option<SnapshotByIdentifier<State, Path>>, StartError | Error>
 > = internal.selectSnapshot
 
@@ -503,9 +505,10 @@ export const matches: <
   Error,
   Output,
   StartError,
+  Emitted,
   const Path extends SnapshotIdentifier<State>
 >(
-  self: MachineAtom<State, Event, Error, Output, StartError>,
+  self: MachineAtom<State, Event, Error, Output, StartError, Emitted>,
   path: Path
 ) => Atom.Atom<AsyncResult.AsyncResult<boolean, StartError | Error>> = internal.matches
 
@@ -625,7 +628,8 @@ export interface Bound<Services, RuntimeError = never> {
     machine:
       & M
       & EnsureBoundRequirements<Services, NoInfer<M>>
-      & EnsureMachineExecutable<NoInfer<M>>,
+      & EnsureMachineExecutable<NoInfer<M>>
+      & Machine.Machine.RootCompatible<Machine.Machine.ParentEvents<NoInfer<M>>>,
     ...args: MachineInputArgsOf<M>
   ) => MachineAtomOf<M, RuntimeError>
 
@@ -634,7 +638,8 @@ export interface Bound<Services, RuntimeError = never> {
     machine:
       & M
       & EnsureBoundResumeRequirements<Services, NoInfer<M>>
-      & EnsureMachineExecutable<NoInfer<M>>,
+      & EnsureMachineExecutable<NoInfer<M>>
+      & Machine.Machine.RootCompatible<Machine.Machine.ParentEvents<NoInfer<M>>>,
     snapshot: Machine.Machine.Snapshot<Machine.Machine.States<M>>
   ) => ResumedMachineAtomOf<M, RuntimeError>
 }
@@ -711,7 +716,8 @@ export const make: {
           Machine.Machine.EmitOf<Emits>
         >
       >
-      & EnsureExecutable<States, UnhandledStates, OutputStates>,
+      & EnsureExecutable<States, UnhandledStates, OutputStates>
+      & Machine.Machine.RootCompatible<ParentEvents>,
     ...args: [...Machine.Machine.InputArgs<Input>]
   ): MachineAtom<
     Machine.Machine.Snapshot<States>,
@@ -738,7 +744,8 @@ export const resume: {
     machine:
       & M
       & EnsureNoExternalRequirements<MachineResumeRequirementsOf<NoInfer<M>>>
-      & EnsureMachineExecutable<NoInfer<M>>,
+      & EnsureMachineExecutable<NoInfer<M>>
+      & Machine.Machine.RootCompatible<Machine.Machine.ParentEvents<NoInfer<M>>>,
     snapshot: Machine.Machine.Snapshot<Machine.Machine.States<M>>
   ): ResumedMachineAtomOf<M, never>
 } = internal.resume