@typeonce/effect-machine 0.15.0 → 0.17.0

package/src/internal/machine/planner.ts

@@ -7,13 +7,7 @@
 import * as Cause from "effect/Cause"
 import * as Effect from "effect/Effect"
 import type * as Schema from "effect/Schema"
-import type {
-  Enqueue,
-  InitialEvent as MachineInitialEvent,
-  Machine,
-  MachineReferences,
-  MachineTarget
-} from "../../Machine.js"
+import type { Enqueue, InitialEvent as MachineInitialEvent, Machine, MachineTarget } from "../../Machine.js"
 import { getTargetBuilder, makeCollector, type RuntimeCommand } from "./command.js"
 import {
   type ActiveConfiguration,
@@ -53,6 +47,7 @@ import {
   getNode,
   type InitialTarget as InitialTargetInstruction,
   isChoiceTarget,
+  isDeclined,
   isHistoryTarget,
   isInitialTarget,
   isNoTarget,
@@ -71,6 +66,7 @@ export type MicrostepPlan<State, Event, E, R> = {
     readonly trigger: Machine.TransitionTrigger
     readonly reenter: boolean
     readonly branchIndex: number
+    readonly branchKey: string | undefined
     readonly target: string | undefined
     readonly resolvedTarget: string | undefined
   }>
@@ -103,11 +99,12 @@ export type MacrostepPlan<State, Event, E, R, Output> =
 export type TransitionHandler<States extends Machine.StateSchemas, E, R, Context> = (
   context: Context,
   enqueue: Enqueue<any, any>
-) => Machine.HandlerResult<States, E, R>
+) => Machine.HandlerResult<States, E, R> | Machine.Declined
 
 type TransitionEvaluation<States extends Machine.StateSchemas, E, R> = {
-  readonly result: Machine.HandlerResult<States, E, R>
+  readonly result: Machine.HandlerResult<States, E, R> | Machine.Declined
   readonly branchIndex: number
+  readonly branchKey: string | undefined
 }
 
 type TransitionEvaluator<States extends Machine.StateSchemas, E, R, Context> = (
@@ -115,24 +112,42 @@ type TransitionEvaluator<States extends Machine.StateSchemas, E, R, Context> = (
   enqueue: Enqueue<any, any>
 ) => TransitionEvaluation<States, E, R>
 
-const rootMachineReferences = new WeakMap<Machine.Any, MachineReferences<any, any>>()
-const scopedMachineReferences = new WeakMap<Machine.Any, MachineReferences<any, any>>()
+type PlanningMachineReferences = {
+  readonly self: MachineTarget<any>
+  readonly parent: MachineTarget<any> | undefined
+}
+
+type BehaviorMachineReferences = {
+  readonly self: MachineTarget<any>
+  readonly parent?: MachineTarget<any> | undefined
+}
+
+const rootMachineReferences = new WeakMap<Machine.Any, BehaviorMachineReferences>()
+const scopedMachineReferences = new WeakMap<Machine.Any, BehaviorMachineReferences>()
+
+const exposeMachineReferences = (
+  machine: Machine.Any,
+  machineReferences: PlanningMachineReferences
+): BehaviorMachineReferences =>
+  machine.parent === undefined
+    ? { self: machineReferences.self }
+    : { self: machineReferences.self, parent: machineReferences.parent }
 
 export const withMachineReferences = (
   machine: Machine.Any,
-  machineReferences: MachineReferences<any, any>
+  machineReferences: PlanningMachineReferences
 ): Machine.Any => {
   const scoped = Object.create(machine) as Machine.Any
-  scopedMachineReferences.set(scoped, { self: machineReferences.self, parent: machineReferences.parent })
+  scopedMachineReferences.set(scoped, exposeMachineReferences(machine, machineReferences))
   return scoped
 }
 
 const resolveMachineReferences = (
   machine: Machine.Any,
   configuration: ActiveConfiguration
-): MachineReferences<any, any> => {
+): BehaviorMachineReferences => {
   const scope = configuration.machineReferences
-  if (scope !== undefined) return scope
+  if (scope !== undefined) return exposeMachineReferences(machine, scope)
   const machineScope = scopedMachineReferences.get(machine)
   if (machineScope !== undefined) return machineScope
   const cached = rootMachineReferences.get(machine)
@@ -142,7 +157,7 @@ const resolveMachineReferences = (
     sessionId: "Machine.plan",
     send: () => Effect.fail(new StoppedError())
   }
-  const root = { self, parent: undefined }
+  const root = exposeMachineReferences(machine, { self, parent: undefined })
   rootMachineReferences.set(machine, root)
   return root
 }
@@ -151,6 +166,7 @@ type EventTransition<States extends Machine.StateSchemas, E, R, Context> =
   | TransitionHandler<States, E, R, Context>
   | {
     readonly reenter?: boolean
+    readonly declinable?: boolean
     readonly targets?: ReadonlyArray<string>
     readonly transition: TransitionHandler<States, E, R, Context>
     readonly evaluate?: TransitionEvaluator<States, E, R, Context>
@@ -158,6 +174,7 @@ type EventTransition<States extends Machine.StateSchemas, E, R, Context> =
 
 export type MicrostepTransition<States extends Machine.StateSchemas, E, R, Context> = {
   readonly reenter: boolean
+  readonly declinable: boolean
   readonly targets: ReadonlyArray<string> | undefined
   readonly transition: TransitionHandler<States, E, R, Context>
   readonly evaluate: TransitionEvaluator<States, E, R, Context> | undefined
@@ -170,9 +187,10 @@ export const normalizeTransition = <States extends Machine.StateSchemas, E, R, C
     return undefined
   }
   return typeof transition === "function"
-    ? { reenter: false, targets: undefined, transition, evaluate: undefined }
+    ? { reenter: false, declinable: false, targets: undefined, transition, evaluate: undefined }
     : {
       reenter: transition.reenter === true,
+      declinable: transition.declinable === true,
       targets: transition.targets,
       transition: transition.transition,
       evaluate: transition.evaluate
@@ -214,11 +232,16 @@ const collectTransition = <
 ) => {
   const collected = makeCollector<Event>(machine)
   const evaluated = evaluate === undefined
-    ? { result: transition(context, collected.enqueue), branchIndex: 0 }
+    ? { result: transition(context, collected.enqueue), branchIndex: 0, branchKey: undefined }
     : evaluate(context, collected.enqueue)
+  if (isDeclined(evaluated.result)) {
+    return { declined: true as const }
+  }
   return {
+    declined: false as const,
     state: isNoTarget(evaluated.result) ? undefined : evaluated.result,
     branchIndex: evaluated.branchIndex,
+    branchKey: evaluated.branchKey,
     commands: collected.commands,
     raisedEvents: collected.raisedEvents,
     emittedEvents: collected.emittedEvents
@@ -518,11 +541,35 @@ export type SelectedTransition<States extends Machine.StateSchemas, E, R, Contex
   readonly trigger: Machine.TransitionTrigger
   readonly transition: MicrostepTransition<States, E, R, Context>
   readonly context: Context
+  readonly collected?: {
+    readonly declined: false
+    readonly state: unknown
+    readonly branchIndex: number
+    readonly branchKey: string | undefined
+    readonly commands: ReadonlyArray<RuntimeCommand>
+    readonly raisedEvents: ReadonlyArray<unknown>
+    readonly emittedEvents: ReadonlyArray<unknown>
+  }
+}
+
+const resolveDeclinableCandidate = <States extends Machine.StateSchemas, E, R, Context>(
+  machine: Machine.Any,
+  selection: SelectedTransition<States, E, R, Context>
+): SelectedTransition<States, E, R, Context> | undefined => {
+  if (!selection.transition.declinable) return selection
+  const collected = collectTransition(
+    machine,
+    selection.transition.transition,
+    selection.context,
+    selection.transition.evaluate
+  )
+  return collected.declined ? undefined : { ...selection, collected }
 }
 
 export type EvaluatedTransition<States extends Machine.StateSchemas, Event, E, R, Context> = {
   readonly selection: SelectedTransition<States, E, R, Context>
   readonly branchIndex: number
+  readonly branchKey: string | undefined
   readonly unresolvedTarget:
     | Machine.Snapshot<States>
     | Machine.Target<States, Machine.StateIdentifier<States>>
@@ -544,6 +591,7 @@ export type EvaluatedTransition<States extends Machine.StateSchemas, Event, E, R
     readonly trigger: Machine.TransitionTrigger
     readonly reenter: false
     readonly branchIndex: number
+    readonly branchKey: string | undefined
     readonly target: string
     readonly resolvedTarget: string
   }>
@@ -754,15 +802,16 @@ const selectAlwaysTransitions = <
     >
   > = []
   const selectedSources = new Set<string>()
+  const evaluatedSources = new Map<string, SelectedTransition<States, E, R, any> | undefined>()
   let snapshot: Machine.Snapshot<States> | undefined
   const capturedSnapshot = () => snapshot ??= snapshotFromConfiguration<States>(machine, configuration)
   for (const leaf of getActiveLeafPaths(machine, configuration)) {
     for (const path of getLeafCandidatePaths(machine, leaf)) {
       const always = normalizeTransition(machine.handlers[path]?.always)
       if (always !== undefined) {
-        if (!selectedSources.has(path)) {
-          selectedSources.add(path)
-          selected.push({
+        let candidate = evaluatedSources.get(path)
+        if (!evaluatedSources.has(path)) {
+          candidate = resolveDeclinableCandidate(machine, {
             sourcePath: path,
             leafPath: leaf,
             trigger: { type: "always" },
@@ -791,6 +840,12 @@ const selectAlwaysTransitions = <
               target: getTargetBuilder(machine, path)
             }
           })
+          evaluatedSources.set(path, candidate)
+        }
+        if (candidate === undefined) continue
+        if (!selectedSources.has(path)) {
+          selectedSources.add(path)
+          selected.push(candidate as (typeof selected)[number])
         }
         break
       }
@@ -833,7 +888,7 @@ const selectDoneTransitions = <
     const onDone = normalizeTransition(machine.handlers[completion.path]?.onDone)
     if (onDone !== undefined && !selectedSources.has(completion.path)) {
       selectedSources.add(completion.path)
-      selected.push({
+      const candidate = resolveDeclinableCandidate(machine, {
         sourcePath: completion.path,
         leafPath: getActiveLeafPathFrom(machine, configuration, completion.path),
         trigger: { type: "done" },
@@ -852,6 +907,7 @@ const selectDoneTransitions = <
           capturedSnapshot()
         )
       })
+      if (candidate !== undefined) selected.push(candidate)
     }
   }
   return selected
@@ -892,15 +948,16 @@ const selectEventTransitions = <
     >
   > = []
   const selectedSources = new Set<string>()
+  const evaluatedSources = new Map<string, SelectedTransition<States, E, R, any> | undefined>()
   let snapshot: Machine.Snapshot<States> | undefined
   const capturedSnapshot = () => snapshot ??= snapshotFromConfiguration<States>(machine, configuration)
   for (const leaf of getActiveLeafPaths(machine, configuration)) {
     for (const path of getLeafCandidatePaths(machine, leaf)) {
       const transition = normalizeTransition(machine.handlers[path]?.on?.[event._tag])
       if (transition !== undefined) {
-        if (!selectedSources.has(path)) {
-          selectedSources.add(path)
-          selected.push({
+        let candidate = evaluatedSources.get(path)
+        if (!evaluatedSources.has(path)) {
+          candidate = resolveDeclinableCandidate(machine, {
             sourcePath: path,
             leafPath: leaf,
             trigger: { type: "event", event: event._tag },
@@ -926,6 +983,12 @@ const selectEventTransitions = <
               Machine.TagOf<Events[number]>
             >(machine as any, configuration, path, event, capturedSnapshot())
           })
+          evaluatedSources.set(path, candidate)
+        }
+        if (candidate === undefined) continue
+        if (!selectedSources.has(path)) {
+          selectedSources.add(path)
+          selected.push(candidate as (typeof selected)[number])
         }
         break
       }
@@ -952,7 +1015,9 @@ const selectInvocationTransition = <
     return String(id) === event.id
   })
   if (invoke === undefined) return []
-  const handler = event.type === "done"
+  const handler = event.type === "element"
+    ? invoke.onElement
+    : event.type === "done"
     ? invoke.onDone
     : event.type === "failure"
     ? invoke.onFailure
@@ -968,19 +1033,22 @@ const selectInvocationTransition = <
     snapshot,
     target: getTargetBuilder(machine, event.path),
     id: event.id,
-    ...(event.type === "done"
+    ...(event.type === "element"
+      ? { element: event.element }
+      : event.type === "done"
       ? { output: event.output }
       : event.type === "failure"
       ? { error: event.error }
       : { snapshot: event.snapshot })
   }
-  return [{
+  const candidate = resolveDeclinableCandidate(machine, {
     sourcePath: event.path,
     leafPath: getActiveLeafPathFrom(machine, configuration, event.path),
     trigger: { type: "invoke", id: event.id, outcome: event.type },
     transition: transition as unknown as MicrostepTransition<States, E, R, any>,
     context
-  }]
+  })
+  return candidate === undefined ? [] : [candidate]
 }
 
 export const getTargetNodePath = <const States extends Machine.StateSchemas>(
@@ -1150,6 +1218,7 @@ interface ResolvedChoiceTransition {
   readonly trigger: Machine.TransitionTrigger
   readonly reenter: false
   readonly branchIndex: number
+  readonly branchKey: string | undefined
   readonly target: string
   readonly resolvedTarget: string
 }
@@ -1228,6 +1297,7 @@ function resolveChoiceTarget(
         trigger: { type: "choice" },
         reenter: false,
         branchIndex: collected.branchIndex,
+        branchKey: collected.branchKey,
         target: returnedPath,
         resolvedTarget: nested?.target.path ?? returnedPath
       })
@@ -1264,12 +1334,15 @@ const collectEvaluatedTransition = <
   selection: SelectedTransition<States, E, R, Context>
 ) => {
   const stateIdentifier = selection.leafPath
-  const transitionResult = collectTransition<States, Event, E, R, Context>(
+  const transitionResult = selection.collected ?? collectTransition<States, Event, E, R, Context>(
     machine,
     selection.transition.transition,
     selection.context,
     selection.transition.evaluate
   )
+  if (transitionResult.declined) {
+    throw new Error("Machine transition returned decline without declaring declinable: true")
+  }
   const unresolvedTarget = transitionResult.state === undefined
     ? undefined
     : transitionResult.state as
@@ -1398,6 +1471,7 @@ const collectEvaluatedTransition = <
     return {
       selection,
       branchIndex: transitionResult.branchIndex,
+      branchKey: transitionResult.branchKey,
       unresolvedTarget,
       target,
       commands: [
@@ -1444,6 +1518,7 @@ const collectEvaluatedTransition = <
   return {
     selection,
     branchIndex: transitionResult.branchIndex,
+    branchKey: transitionResult.branchKey,
     unresolvedTarget,
     target,
     commands: [
@@ -1799,6 +1874,7 @@ const microstep = <
       trigger: transition.selection.trigger,
       reenter: transition.selection.transition.reenter,
       branchIndex: transition.branchIndex,
+      branchKey: transition.branchKey,
       target: transition.unresolvedTarget === undefined ? undefined : getTargetNodePath(transition.unresolvedTarget),
       resolvedTarget: transition.target === undefined ? undefined : getTargetNodePath(transition.target)
     },

package/src/internal/machine/runtime.ts

@@ -355,6 +355,9 @@ interface ProcessAddress<in Event> {
     source: Inspection.Subject | undefined,
     causedBy: Inspection.Causation | undefined
   ) => Effect.Effect<void, StoppedError>
+  readonly [acknowledgedSend]?: (
+    event: Event
+  ) => Effect.Effect<AcknowledgedDelivery<unknown>, unknown | StoppedError>
 }
 
 const isMachineTarget = (value: unknown): value is MachineTarget<unknown> =>
@@ -843,7 +846,10 @@ class OwnedChildRuntimeImpl implements OwnedChildRuntime {
     private readonly registry: ChildRegistry,
     private readonly self: ProcessAddress<any>,
     private readonly runtime: ProcessRuntime,
-    private readonly services?: Context.Context<any>
+    private readonly services?: Context.Context<any>,
+    private readonly sendAcknowledged?: (
+      event: unknown
+    ) => Effect.Effect<AcknowledgedDelivery<unknown>, unknown | StoppedError>
   ) {}
 
   private has(key: string): boolean {
@@ -886,7 +892,15 @@ class OwnedChildRuntimeImpl implements OwnedChildRuntime {
         ...this.self,
         send: (event) => options.sendParent(isCurrent, event),
         sendInspected: (event, source, causedBy) =>
-          isCurrent() ? sendMachineTarget(this.self, event, source, causedBy) : Effect.void
+          isCurrent() ? sendMachineTarget(this.self, event, source, causedBy) : Effect.void,
+        ...(this.sendAcknowledged === undefined
+          ? undefined
+          : {
+            [acknowledgedSend]: (event: unknown) =>
+              isCurrent()
+                ? this.sendAcknowledged!(event)
+                : Effect.interrupt
+          })
       }
       const startOptions: StartInternalOptions = {
         detached: true,
@@ -1048,7 +1062,10 @@ const childlessRuntime: ChildRuntime = {
 const makeChildRuntimeSync = (
   self: ProcessAddress<any>,
   runtime: ProcessRuntime,
-  services?: Context.Context<any>
+  services?: Context.Context<any>,
+  sendAcknowledged?: (
+    event: unknown
+  ) => Effect.Effect<AcknowledgedDelivery<unknown>, unknown | StoppedError>
 ): ChildRuntime => {
   // Child-registry decisions are synchronous and every access below runs in
   // one Effect.sync / Effect.suspend step. Keep the unobserved representation
@@ -1290,15 +1307,18 @@ const makeChildRuntimeSync = (
     changes,
     sendTo,
     stop,
-    owned: new OwnedChildRuntimeImpl(registry, self, runtime, services)
+    owned: new OwnedChildRuntimeImpl(registry, self, runtime, services, sendAcknowledged)
   }
 }
 
 const makeChildRuntime = (
   self: ProcessAddress<any>,
   runtime: ProcessRuntime,
-  services?: Context.Context<any>
-): Effect.Effect<ChildRuntime> => Effect.sync(() => makeChildRuntimeSync(self, runtime, services))
+  services?: Context.Context<any>,
+  sendAcknowledged?: (
+    event: unknown
+  ) => Effect.Effect<AcknowledgedDelivery<unknown>, unknown | StoppedError>
+): Effect.Effect<ChildRuntime> => Effect.sync(() => makeChildRuntimeSync(self, runtime, services, sendAcknowledged))
 
 // `Machine.logic` permits an arbitrary Effect program, including programs that
 // suspend or supervise their own fibers. Keep its two-fiber worker/supervisor
@@ -1376,6 +1396,23 @@ const startGenericInternal: <
         Effect.tap(() => Effect.sync(() => publishInspectedSent(inspector, subject!, message)))
       )
     })
+  const sendAcknowledged:
+    | ((event: Event) => Effect.Effect<AcknowledgedDelivery<State>, Error | StoppedError>)
+    | undefined = logic.execution?._tag !== "Compiled"
+      ? undefined
+      : (event) =>
+        Effect.uninterruptibleMask((restore) =>
+          Deferred.make<AcknowledgedDelivery<unknown>, unknown>().pipe(
+            Effect.flatMap((deferred) => {
+              const offered = inspector === undefined
+                ? offerDirect({ [AcknowledgedMessageTypeId]: true as const, event, deferred })
+                : offerInspected!(event, undefined, undefined, deferred)
+              return offered.pipe(Effect.andThen(restore(Deferred.await(deferred))))
+            }),
+            Effect.map((delivery) => delivery as AcknowledgedDelivery<State>)
+          )
+        ) as Effect.Effect<AcknowledgedDelivery<State>, Error | StoppedError>
+
   const self: ProcessAddress<Event> = {
     id,
     sessionId,
@@ -1396,22 +1433,6 @@ const startGenericInternal: <
       ? undefined
       : { inspectionSubject: subject!, sendInspected: offerInspected! })
   }
-  const sendAcknowledged:
-    | ((event: Event) => Effect.Effect<AcknowledgedDelivery<State>, Error | StoppedError>)
-    | undefined = logic.execution?._tag !== "Compiled"
-      ? undefined
-      : (event) =>
-        Effect.uninterruptibleMask((restore) =>
-          Deferred.make<AcknowledgedDelivery<unknown>, unknown>().pipe(
-            Effect.flatMap((deferred) => {
-              const offered = inspector === undefined
-                ? offerDirect({ [AcknowledgedMessageTypeId]: true as const, event, deferred })
-                : offerInspected!(event, undefined, undefined, deferred)
-              return offered.pipe(Effect.andThen(restore(Deferred.await(deferred))))
-            }),
-            Effect.map((delivery) => delivery as AcknowledgedDelivery<State>)
-          )
-        ) as Effect.Effect<AcknowledgedDelivery<State>, Error | StoppedError>
 
   let {
     changes: childChanges,
@@ -1431,7 +1452,12 @@ const startGenericInternal: <
       sendTo,
       spawn,
       stop: stopChild
-    } = yield* makeChildRuntime(self, runtime))
+    } = yield* makeChildRuntime(
+      self,
+      runtime,
+      undefined,
+      sendAcknowledged === undefined ? undefined : (event) => sendAcknowledged(event as Event)
+    ))
   }
   const cleanupStartupFailure = <A, E>(exit: Exit.Exit<A, E>): Effect.Effect<void> => {
     if (Exit.isSuccess(exit)) return Effect.void
@@ -2227,7 +2253,12 @@ class CompiledProcess implements MachineRef<any, any, any, any> {
   initializeCompiledSync(): Effect.Effect<MachineRef<any, any, any, any>, unknown> {
     this.publishCreated()
     if (!this.execution.childless) {
-      this.childRuntime = makeChildRuntimeSync(this.address, this.options.runtime, this.services)
+      this.childRuntime = makeChildRuntimeSync(
+        this.address,
+        this.options.runtime,
+        this.services,
+        (event) => this.sendAcknowledgedEffect(event)
+      )
     }
     const parent = this.options.parent
     const sendParent = this.options.sendParent ?? (parent === undefined
@@ -2304,7 +2335,12 @@ class CompiledProcess implements MachineRef<any, any, any, any> {
     return Effect.gen(function*() {
       self.publishCreated()
       if (!self.execution.childless) {
-        self.childRuntime = yield* makeChildRuntime(self.address, self.options.runtime, self.services)
+        self.childRuntime = yield* makeChildRuntime(
+          self.address,
+          self.options.runtime,
+          self.services,
+          (event) => self.sendAcknowledgedEffect(event)
+        )
       }
       const parent = self.options.parent
       const sendParent = self.options.sendParent ?? (parent === undefined

package/src/internal/machine/stateDefinition.ts

@@ -138,6 +138,22 @@ const assertPlainRecord: (
   }
 }
 
+const validateTargetSelectorChildKey = (
+  boundary: StateDefinitionBoundary,
+  path: string,
+  states: unknown,
+  key: "initial" | "with",
+  message: string
+): void => {
+  if (typeof states !== "object" || states === null || Array.isArray(states) || !hasOwn(states, key)) return
+  const child = (states as Readonly<Record<string, unknown>>)[key]
+  if (
+    typeof child === "object" && child !== null && !Schema.isSchema(child) &&
+    (child as Readonly<Record<string, unknown>>).type === "history"
+  ) return
+  fail(boundary, `${path}.${key}`, message)
+}
+
 const assertAllowedProperties = (
   boundary: StateDefinitionBoundary,
   path: string,
@@ -252,6 +268,22 @@ const validateStateTree = (
       if (typeof node.initial !== "string") {
         fail(boundary, `${path}.initial`, "compound states must declare an initial child key")
       }
+      validateTargetSelectorChildKey(
+        boundary,
+        path,
+        node.states,
+        "initial",
+        "active and choice child states cannot use the reserved target selector key \"initial\""
+      )
+      if (valued) {
+        validateTargetSelectorChildKey(
+          boundary,
+          path,
+          node.states,
+          "with",
+          "schema-backed compound child states cannot use the reserved local target selector key \"with\""
+        )
+      }
       const initialKey = node.initial as string
       validateStateTree(boundary, node.states, path, true)
       if (!hasOwn(node.states as object, initialKey)) {
@@ -270,6 +302,13 @@ const validateStateTree = (
       if (!hasOwn(node, "states")) {
         fail(boundary, `${path}.states`, "parallel states must declare child regions")
       }
+      validateTargetSelectorChildKey(
+        boundary,
+        path,
+        node.states,
+        "initial",
+        "active and choice child states cannot use the reserved target selector key \"initial\""
+      )
       validateStateTree(boundary, node.states, path, true)
     }
   }