@typeonce/effect-machine 0.8.0 → 0.10.0

package/src/internal/machine/planner.ts

@@ -7,7 +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 } from "../../Machine.js"
+import type { ActorContext, ActorRef, Enqueue, InitialEvent as MachineInitialEvent, Machine } from "../../Machine.js"
 import { getTargetBuilder, makeCollector, type RuntimeCommand } from "./command.js"
 import {
   type ActiveConfiguration,
@@ -37,13 +37,15 @@ import {
   snapshotFromConfigurationAtPath,
   validateInitialConfiguration
 } from "./configuration.js"
-import { InfiniteTransitionError, MachineSchemaDecodeError, StartupError } from "./errors.js"
+import { InfiniteTransitionError, MachineSchemaDecodeError, StartupError, StoppedError } from "./errors.js"
+import * as InvocationEvent from "./invocationEvent.js"
 import { decodeEventSync, decodeInputSync, decodeStateValueSync } from "./protocol.js"
 import { InitialEventTypeId } from "./symbols.js"
 import {
   getNode,
   isChoiceTarget,
   isHistoryTarget,
+  isNoTarget,
   isSnapshot,
   isTarget,
   makeChoiceTarget,
@@ -92,6 +94,38 @@ export type TransitionHandler<States extends Machine.StateSchemas, E, R, Context
   enqueue: Enqueue<any, any>
 ) => Machine.HandlerResult<States, E, R>
 
+const rootActorScopes = new WeakMap<Machine.Any, ActorContext<any, any>>()
+const machineActorScopes = new WeakMap<Machine.Any, ActorContext<any, any>>()
+
+export const withActorScope = (
+  machine: Machine.Any,
+  actorScope: ActorContext<any, any>
+): Machine.Any => {
+  const scoped = Object.create(machine) as Machine.Any
+  machineActorScopes.set(scoped, { self: actorScope.self, parent: actorScope.parent })
+  return scoped
+}
+
+const getActorContext = (
+  machine: Machine.Any,
+  configuration: ActiveConfiguration
+): ActorContext<any, any> => {
+  const scope = configuration.actorScope
+  if (scope !== undefined) return scope
+  const machineScope = machineActorScopes.get(machine)
+  if (machineScope !== undefined) return machineScope
+  const cached = rootActorScopes.get(machine)
+  if (cached !== undefined) return cached
+  const self: ActorRef<unknown> = {
+    id: machine.id ?? "Machine",
+    sessionId: "Machine.plan",
+    send: () => Effect.fail(new StoppedError())
+  }
+  const root = { self, parent: undefined }
+  rootActorScopes.set(machine, root)
+  return root
+}
+
 type EventTransition<States extends Machine.StateSchemas, E, R, Context> =
   | TransitionHandler<States, E, R, Context>
   | {
@@ -154,9 +188,9 @@ const collectTransition = <
   context: Context
 ) => {
   const collected = makeCollector<Event>(machine)
-  const state = transition(context, collected.enqueue)
+  const result = transition(context, collected.enqueue)
   return {
-    state,
+    state: isNoTarget(result) ? undefined : result,
     commands: collected.commands,
     raisedEvents: collected.raisedEvents,
     emittedEvents: collected.emittedEvents
@@ -205,7 +239,8 @@ const completeHistoryConfiguration = (
           active,
           values,
           outputs: configuration.outputs,
-          history: configuration.history
+          history: configuration.history,
+          actorScope: configuration.actorScope
         } as ActiveConfiguration
         active.add(child.path)
         if (child.schema !== undefined) {
@@ -214,9 +249,10 @@ const completeHistoryConfiguration = (
             throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`)
           }
           const initialized = collectStateInitializer(machine, initializer, {
+            ...getActorContext(machine, current),
             state: current.values.get(path),
-            parent: getParentValue(machine, current, path),
-            parents: getParentValues(machine, current, path),
+            containingState: getParentValue(machine, current, path),
+            ancestors: getParentValues(machine, current, path),
             event
           })
           values.set(child.path, decodeStateValueSync(machine, child, initialized.value))
@@ -234,16 +270,18 @@ const completeHistoryConfiguration = (
             active,
             values,
             outputs: configuration.outputs,
-            history: configuration.history
+            history: configuration.history,
+            actorScope: configuration.actorScope
           } as ActiveConfiguration
           const initializer = valuedMissing.length === 0 ? undefined : machine.handlers[path]?.initial
           if (valuedMissing.length > 0 && initializer === undefined) {
             throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`)
           }
           const initialized = initializer === undefined ? undefined : collectStateInitializer(machine, initializer, {
+            ...getActorContext(machine, current),
             state: current.values.get(path),
-            parent: getParentValue(machine, current, path),
-            parents: getParentValues(machine, current, path),
+            containingState: getParentValue(machine, current, path),
+            ancestors: getParentValues(machine, current, path),
             event
           })
           if (initialized !== undefined && (typeof initialized.value !== "object" || initialized.value === null)) {
@@ -327,7 +365,7 @@ const resolveHistoryTarget = (
   const collected = collectTransition(machine, fallback, {
     event,
     target: getTargetBuilder(machine, target.parent).full,
-    parent: target.parent
+    owner: target.parent
   })
   if (collected.state === undefined || isHistoryTarget(collected.state) || !isSnapshot(collected.state)) {
     throw new Error(`Machine history default for "${target.path}" must return a complete snapshot containing its owner`)
@@ -504,9 +542,10 @@ const makeStateActionContext = <
   path: string,
   event: Machine.LifecycleEvent<Events>
 ): Machine.StateActionContext<States, Events, Emits, StateId> => ({
+  ...getActorContext(machine, configuration),
   state: configuration.values.get(path) as Machine.StateByIdentifier<States, StateId>,
-  parent: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
-  parents: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
+  containingState: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
+  ancestors: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
   event
 })
 
@@ -523,9 +562,10 @@ const makeTransitionContext = <
   event: Machine.EventByTag<Events, EventTag>,
   snapshot: Machine.Snapshot<States>
 ): Machine.HandlerContext<States, Events, Emits, StateId, EventTag, any, any> => ({
+  ...getActorContext(machine, configuration),
   state: configuration.values.get(path) as Machine.StateByIdentifier<States, StateId>,
-  parent: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
-  parents: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
+  containingState: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
+  ancestors: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
   event,
   snapshot,
   target: getTargetBuilder(machine, path)
@@ -544,9 +584,10 @@ const makeDoneContext = <
   output: unknown,
   snapshot: Machine.Snapshot<States>
 ): Machine.DoneContext<States, Events, Emits, StateId> => ({
+  ...getActorContext(machine, configuration),
   state: configuration.values.get(path) as Machine.StateByIdentifier<States, StateId>,
-  parent: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
-  parents: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
+  containingState: getParentValue(machine, configuration, path) as Machine.ParentStateValue<States, StateId>,
+  ancestors: getParentValues(machine, configuration, path) as Machine.ParentStateValues<States, StateId>,
   event,
   output: output as Machine.CompletionOutputByIdentifier<States, StateId>,
   snapshot,
@@ -638,15 +679,16 @@ const selectAlwaysTransitions = <
               Machine.AlwaysContext<States, Events, Emits, Machine.StateIdentifier<States>>
             >,
             context: {
+              ...getActorContext(machine, configuration),
               state: configuration.values.get(path) as Machine.StateByIdentifier<
                 States,
                 Machine.StateIdentifier<States>
               >,
-              parent: getParentValue(machine, configuration, path) as Machine.ParentStateValue<
+              containingState: getParentValue(machine, configuration, path) as Machine.ParentStateValue<
                 States,
                 Machine.StateIdentifier<States>
               >,
-              parents: getParentValues(machine, configuration, path) as Machine.ParentStateValues<
+              ancestors: getParentValues(machine, configuration, path) as Machine.ParentStateValues<
                 States,
                 Machine.StateIdentifier<States>
               >,
@@ -798,6 +840,55 @@ const selectEventTransitions = <
   return selected
 }
 
+const selectInvocationTransition = <
+  const States extends Machine.StateSchemas,
+  const Events extends ReadonlyArray<Machine.TaggedSchema>,
+  const Emits extends ReadonlyArray<Machine.TaggedSchema>,
+  E,
+  R
+>(
+  machine: Machine.Any,
+  configuration: ActiveConfiguration,
+  event: InvocationEvent.InvocationEvent
+): ReadonlyArray<SelectedTransition<States, E, R, any>> => {
+  if (!configuration.active.has(event.path)) return []
+  const config = machine.handlers[event.path] as Machine.AnyStateConfig | undefined
+  const invoke = InvocationEvent.definitions(config?.invoke).find((definition) => {
+    const id = "child" in definition ? definition.child?.id : definition.id
+    return String(id) === event.id
+  })
+  if (invoke === undefined) return []
+  const handler = event.type === "done"
+    ? invoke.onDone
+    : event.type === "failure"
+    ? invoke.onFailure
+    : invoke.onSnapshot
+  const transition = normalizeTransition(handler)
+  if (transition === undefined) return []
+  const snapshot = snapshotFromConfiguration<States>(machine, configuration)
+  const context = {
+    ...getActorContext(machine, configuration),
+    state: configuration.values.get(event.path),
+    containingState: getParentValue(machine, configuration, event.path),
+    ancestors: getParentValues(machine, configuration, event.path),
+    snapshot,
+    target: getTargetBuilder(machine, event.path),
+    id: event.id,
+    ...(event.type === "done"
+      ? { output: event.output }
+      : event.type === "failure"
+      ? { error: event.error }
+      : { snapshot: event.snapshot })
+  }
+  return [{
+    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
+  }]
+}
+
 export const getTargetNodePath = <const States extends Machine.StateSchemas>(
   target:
     | Machine.Snapshot<States>
@@ -1015,11 +1106,13 @@ const resolveChoiceTarget = (
           ...Object.entries(extracted.values)
         ]),
         outputs: configuration.outputs,
-        history: configuration.history
+        history: configuration.history,
+        ...(configuration.actorScope === undefined ? {} : { actorScope: configuration.actorScope })
       }
       const collected = collectTransition(machine, choice.transition, {
-        parent: getParentValue(machine, provisional, node.path),
-        parents: getParentValues(machine, provisional, node.path),
+        ...getActorContext(machine, provisional),
+        containingState: getParentValue(machine, provisional, node.path),
+        ancestors: getParentValues(machine, provisional, node.path),
         event,
         target: getTargetBuilder(machine, node.path)
       })
@@ -1812,11 +1905,11 @@ const macrostepConfiguration = <
 >(
   machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits>,
   configuration: ActiveConfiguration,
-  event: Machine.EventOf<Events>
+  event: Machine.EventOf<Events> | InvocationEvent.InvocationEvent
 ) => {
-  const decodedEvent = decodeEventSync<Events>(machine, event)
+  const decodedEvent = InvocationEvent.isInvocationEvent(event) ? event : decodeEventSync<Events>(machine, event)
   if (isActiveFinalConfiguration(machine, configuration)) {
-    const completed = completeConfigurationSync(machine, configuration, decodedEvent)
+    const completed = completeConfigurationSync(machine, configuration, decodedEvent as any)
     const root = getRootPath(machine, completed.configuration)
     if (!completed.configuration.outputs.has(root)) {
       throw new Error("Machine reached a terminal configuration without a completed root output")
@@ -1831,11 +1924,13 @@ const macrostepConfiguration = <
     }
   }
 
-  const selections = selectEventTransitions<States, Events, Emits, E, R>(
-    machine,
-    configuration,
-    decodedEvent as Machine.EventByTag<Events, Machine.TagOf<Events[number]>>
-  )
+  const selections = InvocationEvent.isInvocationEvent(decodedEvent)
+    ? selectInvocationTransition<States, Events, Emits, E, R>(machine, configuration, decodedEvent)
+    : selectEventTransitions<States, Events, Emits, E, R>(
+      machine,
+      configuration,
+      decodedEvent as Machine.EventByTag<Events, Machine.TagOf<Events[number]>>
+    )
   if (selections.length === 0) {
     return {
       next: configuration,
@@ -1849,14 +1944,14 @@ const macrostepConfiguration = <
   const step = microstep(
     machine,
     configuration,
-    decodedEvent,
+    decodedEvent as any,
     selections
   )
   const commands = [...step.commands]
   const raisedEvents = [...step.raisedEvents]
   const emittedEvents = [...step.emittedEvents]
   const microsteps = [step]
-  return settle(machine, step.next, decodedEvent, commands, raisedEvents, emittedEvents, microsteps)
+  return settle(machine, step.next, decodedEvent as any, commands, raisedEvents, emittedEvents, microsteps)
 }
 
 const snapshotMacrostep = <

package/src/internal/machine/process.ts

@@ -131,7 +131,8 @@ const makeChildlessCompiledDrain = (
         planned = executionPlan.plan(
           configuration ?? executionPlan.fromConfiguration(Configuration.normalizeConfigurationSync(machine, current)),
           event,
-          acknowledged
+          acknowledged,
+          context.scope
         )
       } catch (error) {
         return error instanceof InfiniteTransitionError || error instanceof MachineSchemaDecodeError
@@ -255,7 +256,8 @@ const makeInvokingCompiledDrain = (
           configuration ??
             executionPlan.fromConfiguration(Configuration.normalizeConfigurationSync(machine, current)),
           event,
-          acknowledged
+          acknowledged,
+          scope
         )
       } catch (error) {
         return error instanceof InfiniteTransitionError || error instanceof MachineSchemaDecodeError
@@ -426,9 +428,11 @@ const makeProcessLogic: <
   const executionPlan = ExecutionPlan.compileExecutionPlan(machine)
   const initialArgs = entry._tag === "Initial" ? entry.args : []
   const compiledInitial = entry._tag === "Initial" ? executionPlan.initial : undefined
-  const makeCompiledInitial = compiledInitial === undefined ? undefined : () => {
+  const makeCompiledInitial = compiledInitial === undefined ? undefined : (
+    scope: internalRuntime.ProcessScope<Machine.EventOf<Events>>
+  ) => {
     try {
-      const planned = compiledInitial(initialArgs)
+      const planned = compiledInitial(initialArgs, scope)
       const result = {
         state: planned.state as Machine.Snapshot<States>,
         done: planned.done,
@@ -455,7 +459,7 @@ const makeProcessLogic: <
   ) =>
     compiledInitial === undefined
       ? internalRuntime.provideMachineRuntime(
-        internalPlanner.planInitial(machine, ...initialArgs).pipe(
+        internalPlanner.planInitial(internalPlanner.withActorScope(machine, scope), ...initialArgs).pipe(
           Effect.flatMap((planned) => {
             const commands = planned.commands.length === 0
               ? undefined
@@ -480,7 +484,7 @@ const makeProcessLogic: <
         ),
         scope
       )
-      : Effect.try({ try: makeCompiledInitial!, catch: (error) => error as any })
+      : Effect.try({ try: () => makeCompiledInitial!(scope), catch: (error) => error as any })
   return ({
     execution: {
       _tag: "Compiled",
@@ -536,7 +540,10 @@ const makeProcessLogic: <
               try {
                 planned = internalPlanner.planConfiguration(
                   machine,
-                  configuration ?? Configuration.normalizeConfigurationSync(machine, current),
+                  Configuration.withActorScope(
+                    configuration ?? Configuration.normalizeConfigurationSync(machine, current),
+                    context
+                  ),
                   event
                 )
               } catch (error) {
@@ -644,7 +651,10 @@ const makeProcessLogic: <
               try {
                 planned = internalPlanner.planConfiguration(
                   machine,
-                  configuration ?? Configuration.normalizeConfigurationSync(machine, current),
+                  Configuration.withActorScope(
+                    configuration ?? Configuration.normalizeConfigurationSync(machine, current),
+                    context
+                  ),
                   event
                 )
               } catch (error) {