@typeonce/effect-machine 0.8.0 → 0.9.0

package/src/internal/machine/activities.ts

@@ -4,8 +4,7 @@
  * @since 0.4.0
  */
 
-/** @internal */
-export const ActivityMetadataTypeId: unique symbol = Symbol.for("effect/Machine/ActivityMetadata")
+import * as Duration from "effect/Duration"
 
 /** @internal */
 export type StaticActivityMetadata =
@@ -21,8 +20,7 @@ export type StaticActivityMetadata =
   }
   | {
     readonly type: "timer"
-    readonly duration: string
-    readonly event: string
+    readonly duration: string | "dynamic"
   }
   | {
     readonly type: "machine"
@@ -33,20 +31,10 @@ export type StaticActivityMetadata =
   }
 
 /** @internal */
-export type ActivityDefinition<Source extends string = string> =
-  | ({
-    readonly source: Source
-    readonly id: string
-  } & StaticActivityMetadata)
-  | {
-    readonly source: Source
-    readonly type: "dynamic"
-  }
-
-interface ActivityDescriptor {
+export type ActivityDefinition<Source extends string = string> = {
+  readonly source: Source
   readonly id: string
-  readonly [ActivityMetadataTypeId]: StaticActivityMetadata
-}
+} & StaticActivityMetadata
 
 interface InspectableMachine {
   readonly handlers: unknown
@@ -62,31 +50,60 @@ const isObject = (value: unknown): value is object =>
 
 const getProperty = (value: unknown, key: PropertyKey): unknown => isObject(value) ? Reflect.get(value, key) : undefined
 
-const hasActivityMetadata = (value: unknown): value is ActivityDescriptor =>
-  isObject(value) && typeof getProperty(value, "id") === "string" &&
-  isObject(getProperty(value, ActivityMetadataTypeId))
-
 const appendStaticDefinition = (
   definitions: Array<ActivityDefinition>,
   source: string,
   descriptor: unknown
 ): void => {
-  if (!hasActivityMetadata(descriptor)) {
+  if (!isObject(descriptor)) return
+  const child = getProperty(descriptor, "child")
+  if (isObject(child)) {
+    const id = getProperty(child, "id")
+    if (typeof id !== "string") return
+    const machine = getProperty(child, "machine")
+    const machineId = getProperty(machine, "id")
+    definitions.push({
+      source,
+      id,
+      type: "machine",
+      child: { id, machineId: typeof machineId === "string" ? machineId : null }
+    })
     return
   }
-  definitions.push({
-    source,
-    id: descriptor.id,
-    ...descriptor[ActivityMetadataTypeId]
-  })
+  const id = getProperty(descriptor, "id")
+  if (typeof id !== "string") return
+  if (Reflect.has(descriptor, "effect")) {
+    definitions.push({
+      source,
+      id,
+      type: "effect",
+      outcomes: {
+        success: "dynamic",
+        failure: Reflect.has(descriptor, "onFailure") ? "dynamic" : "none"
+      }
+    })
+    return
+  }
+  if (Reflect.has(descriptor, "after")) {
+    const after = getProperty(descriptor, "after")
+    definitions.push({
+      source,
+      id,
+      type: "timer",
+      duration: typeof after === "function" ? "dynamic" : Duration.format(Duration.fromInputUnsafe(after as any))
+    })
+    return
+  }
+  if (Reflect.has(descriptor, "logic")) {
+    definitions.push({ source, id, type: "process" })
+  }
 }
 
 /**
  * Collects state-owned activity descriptions without executing user code.
  *
- * Function-valued invoke definitions depend on an entry context and are
- * therefore represented as dynamic. Static descriptors are returned in state
- * definition order and descriptor array order.
+ * Source factories are inspected without execution. Static descriptors are
+ * returned in state definition order and descriptor array order.
  *
  * @internal
  */
@@ -94,9 +111,7 @@ export const activityDefinitions = (machine: InspectableMachine): ReadonlyArray<
   const definitions: Array<ActivityDefinition> = []
   for (const node of machine.stateNodes.byPath.values()) {
     const invoke = getProperty(getProperty(machine.handlers, node.path), "invoke")
-    if (typeof invoke === "function") {
-      definitions.push({ source: node.path, type: "dynamic" })
-    } else if (Array.isArray(invoke)) {
+    if (Array.isArray(invoke)) {
       for (const descriptor of invoke) {
         appendStaticDefinition(definitions, node.path, descriptor)
       }

package/src/internal/machine/atom.ts

@@ -120,7 +120,7 @@ const startMachineAtomEffect = <
 ): Effect.Effect<
   Machine.MachineRef<
     Machine.Machine.Snapshot<States>,
-    Machine.Machine.EventOf<InputEvents>,
+    Machine.Machine.EventInputOf<InputEvents>,
     MachineRuntimeError<E, R>,
     Output
   >,
@@ -585,7 +585,7 @@ type EnsureMachineExecutable<M extends Machine.Machine.Any> = IsAny<Machine.Mach
 
 type ResumedMachineAtomOf<M extends Machine.Machine.Any, RuntimeError> = MachineAtom<
   Machine.Machine.Snapshot<Machine.Machine.States<M>>,
-  Machine.Machine.InputEvent<M>,
+  Machine.Machine.EventInput<Machine.Machine.InputEvent<M>>,
   MachineRuntimeError<Machine.Machine.Error<M>, Machine.Machine.Services<M>>,
   Machine.Machine.Output<M>,
   Machine.MachineSchemaDecodeError | RuntimeError
@@ -635,7 +635,7 @@ export const make: {
     ...args: [...Machine.Machine.InputArgs<Input>]
   ): MachineAtom<
     Machine.Machine.Snapshot<States>,
-    Machine.Machine.EventOf<InputEvents>,
+    Machine.Machine.EventInputOf<InputEvents>,
     MachineRuntimeError<E, R>,
     Output,
     MachineStartError<InitialE, E, InitialR, R>

package/src/internal/machine/executionPlan.ts

@@ -21,6 +21,7 @@ import {
   validateInitialConfiguration
 } from "./configuration.js"
 import { InfiniteTransitionError } from "./errors.js"
+import * as InvocationEvent from "./invocationEvent.js"
 import {
   broadenTransitionBoundary,
   type EvaluatedTransition,
@@ -775,6 +776,34 @@ const planIndexedState = (
   input: unknown,
   retainMicrosteps: boolean
 ): ExecutionMacrostep<OwnedIndexedState> => {
+  if (InvocationEvent.isInvocationEvent(input)) {
+    // Invocation lifecycle transitions retain the generic planner as their
+    // semantic reference. Ordinary machine events and initialization stay on
+    // the indexed representation; only the private lifecycle macrostep crosses
+    // the representation boundary.
+    const planned = planConfiguration(
+      machine as any,
+      activeConfigurationFromIndexedState(descriptor, configuration),
+      input
+    )
+    return {
+      next: ownedIndexedStateFromActive(descriptor, planned.next),
+      commands: planned.commands,
+      emittedEvents: planned.emittedEvents,
+      microsteps: planned.microsteps.map((step) => ({
+        next: ownedIndexedStateFromActive(descriptor, step.next),
+        event: step.event,
+        commands: step.commands,
+        raisedEvents: step.raisedEvents,
+        emittedEvents: step.emittedEvents,
+        exitPaths: step.exitPaths,
+        entryPaths: step.entryPaths,
+        changed: step.changed
+      })),
+      done: planned.done,
+      output: planned.output
+    }
+  }
   const decoded = decodeEventSync(machine, input)
   if (descriptor.flat) {
     return planIndexedFlatState(machine, descriptor, configuration, decoded, retainMicrosteps)

package/src/internal/machine/invocation.ts

@@ -4,28 +4,26 @@
  * @since 0.4.0
  */
 
+import * as Cause from "effect/Cause"
 import * as Effect from "effect/Effect"
-import type { Machine } from "../../Machine.js"
+import type { ChildMachine, Logic, Machine } from "../../Machine.js"
 import * as Configuration from "./configuration.js"
+import { InfiniteTransitionError, MachineSchemaDecodeError, StoppedError } from "./errors.js"
+import * as InvocationEvent from "./invocationEvent.js"
 import * as Planner from "./planner.js"
 import type * as Runtime from "./runtime.js"
+import { ChildMachineLogicTypeId } from "./symbols.js"
 
 /** @internal */
-export type AnyConfig = Machine.InvokeConfig<
-  any,
-  any,
-  any,
-  any,
-  any,
-  any,
-  any,
-  any,
-  any,
-  any,
-  any,
-  any,
-  any
->
+export interface AnyConfig {
+  readonly id: string
+  readonly address?: string
+  readonly descriptor?: ChildMachine.Any
+  readonly src: () => Runtime.ProcessLogic<any, any, any, any, any, any>
+  readonly onDone?: unknown
+  readonly onFailure?: unknown
+  readonly onSnapshot?: unknown
+}
 
 /** @internal */
 export const makeKey = (path: string, id: string): string => `${path.length}:${path}${id}`
@@ -33,16 +31,79 @@ export const makeKey = (path: string, id: string): string => `${path.length}:${p
 /** @internal */
 export const makeChildId = (path: string, id: string): string => `Machine.invoke:${makeKey(path, id)}`
 
-const resolve = (
-  config: Machine.AnyStateConfig | undefined,
+const oneShot = (effect: Effect.Effect<any, any, any>): Logic<void, never, any, any, any> => ({
+  initial: () => Effect.void,
+  run: () => effect
+})
+
+const resolveValue = (value: unknown, context: Machine.InvokeContext<any, any, any, any>): unknown =>
+  typeof value === "function" ? value(context) : value
+
+const resolveOne = (
+  raw: Record<PropertyKey, any>,
   context: Machine.InvokeContext<any, any, any, any>
-): ReadonlyArray<AnyConfig> => {
-  const definition = config?.invoke
-  const invokes = typeof definition === "function" ? definition(context) : definition
-  if (invokes === undefined) return []
-  return Array.isArray(invokes) ? invokes as ReadonlyArray<AnyConfig> : [invokes as AnyConfig]
+): AnyConfig => {
+  if ("effect" in raw) {
+    return {
+      id: String(raw.id),
+      src: () =>
+        oneShot(resolveValue(raw.effect, context) as Effect.Effect<any, any, any>) as unknown as Runtime.ProcessLogic<
+          any,
+          any,
+          any,
+          any,
+          any,
+          any
+        >,
+      onDone: raw.onDone,
+      onFailure: raw.onFailure,
+      onSnapshot: raw.onSnapshot
+    }
+  }
+  if ("after" in raw) {
+    return {
+      id: String(raw.id),
+      src: () =>
+        oneShot(Effect.sleep(resolveValue(raw.after, context) as any)) as unknown as Runtime.ProcessLogic<
+          any,
+          any,
+          any,
+          any,
+          any,
+          any
+        >,
+      onDone: raw.onDone
+    }
+  }
+  if ("logic" in raw) {
+    return {
+      id: String(raw.id),
+      address: String(raw.address),
+      src: () => resolveValue(raw.logic, context) as Runtime.ProcessLogic<any, any, any, any, any, any>,
+      onDone: raw.onDone,
+      onFailure: raw.onFailure,
+      onSnapshot: raw.onSnapshot
+    }
+  }
+  if ("child" in raw) {
+    const descriptor = raw.child as ChildMachine.Any
+    return {
+      id: descriptor.id,
+      address: descriptor.id,
+      descriptor,
+      src: () =>
+        descriptor[ChildMachineLogicTypeId](
+          "input" in raw ? resolveValue(raw.input, context) : undefined
+        ) as Runtime.ProcessLogic<any, any, any, any, any, any>,
+      onDone: raw.onDone,
+      onFailure: raw.onFailure,
+      onSnapshot: raw.onSnapshot
+    }
+  }
+  throw new Error("Machine invoke must define exactly one of effect, after, logic, or child")
 }
 
+/** @internal */
 const runSequentialDiscard = <E, R>(
   effects: ReadonlyArray<Effect.Effect<void, E, R>>
 ): Effect.Effect<void, E, R> =>
@@ -52,45 +113,110 @@ const runSequentialDiscard = <E, R>(
     ? effects[0]!
     : Effect.all(effects, { discard: true })
 
-const start = (
+const sendLifecycle = (
+  scope: Runtime.ProcessScope<any>,
+  event: InvocationEvent.InvocationEvent
+): Effect.Effect<void> => scope.self.send(event).pipe(Effect.catchTag("StoppedError", () => Effect.void))
+
+const isFrameworkFailure = (error: unknown): boolean =>
+  error instanceof InfiniteTransitionError || error instanceof MachineSchemaDecodeError || error instanceof StoppedError
+
+const startResolved = (
   scope: Runtime.ProcessScope<any>,
   ownedChildren: Runtime.OwnedChildRuntime,
   path: string,
-  config: AnyConfig
+  invokeId: string,
+  childId: string,
+  descriptor: ChildMachine.Any | undefined,
+  src: () => Runtime.ProcessLogic<any, any, any, any, any, any>,
+  onDone: unknown,
+  onFailure: unknown,
+  onSnapshot: unknown
 ): Effect.Effect<void, any, any> =>
   Effect.suspend(() => {
-    const invokeId = String(config.id)
     const key = makeKey(path, invokeId)
-    const childId = config.address === undefined ? makeChildId(path, invokeId) : String(config.address)
-    return ownedChildren.spawn(config.src as () => Runtime.ProcessLogic<any, any, any, any, any, any>, {
+    return ownedChildren.spawn(src, {
       key,
       path,
       id: childId,
       duplicateId: invokeId,
-      ...(config.descriptor === undefined ? undefined : { descriptor: config.descriptor }),
+      ...(descriptor === undefined ? undefined : { descriptor }),
       sendParent: (isCurrent, event) => isCurrent() ? scope.self.send(event) : Effect.void,
       onOutcome: (isCurrent, outcome) => {
         if (outcome._tag === "Stopped" || !isCurrent()) return Effect.void
-        if (outcome._tag !== "Done") return scope.failCause(outcome.cause)
-        const mappedEvent = config.onDone === undefined
-          ? outcome.output
-          : config.onDone({ id: config.id, output: outcome.output })
-        return mappedEvent === undefined
-          ? Effect.void
-          : scope.self.send(mappedEvent).pipe(Effect.catchTag("StoppedError", () => Effect.void))
-      },
-      ...(config.snapshot === undefined ? undefined : {
-        onSnapshot: (isCurrent: () => boolean, snapshot: any) => {
-          if (!isCurrent()) return Effect.void
-          const mappedEvent = config.snapshot!({ id: config.id, snapshot })
-          return mappedEvent === undefined
-            ? Effect.void
-            : scope.self.send(mappedEvent).pipe(Effect.catchTag("StoppedError", () => Effect.void))
+        if (outcome._tag === "Done") {
+          if (onDone === undefined) {
+            return scope.failCause(Cause.die(
+              new Error(
+                `Invocation "${invokeId}" completed without the required onDone handler`
+              )
+            ))
+          }
+          return sendLifecycle(scope, InvocationEvent.done(path, invokeId, outcome.output))
         }
+        if (
+          outcome._tag === "Failure" &&
+          onFailure !== undefined &&
+          (descriptor === undefined || !isFrameworkFailure(outcome.error))
+        ) {
+          return sendLifecycle(scope, InvocationEvent.failure(path, invokeId, outcome.error))
+        }
+        return scope.failCause(outcome.cause)
+      },
+      ...(onSnapshot === undefined ? undefined : {
+        onSnapshot: (isCurrent: () => boolean, snapshot: any) =>
+          isCurrent()
+            ? sendLifecycle(scope, InvocationEvent.snapshot(path, invokeId, snapshot))
+            : Effect.void
       })
     })
   })
 
+const start = (
+  scope: Runtime.ProcessScope<any>,
+  ownedChildren: Runtime.OwnedChildRuntime,
+  path: string,
+  config: AnyConfig
+): Effect.Effect<void, any, any> => {
+  const invokeId = String(config.id)
+  return startResolved(
+    scope,
+    ownedChildren,
+    path,
+    invokeId,
+    config.address === undefined ? makeChildId(path, invokeId) : String(config.address),
+    config.descriptor,
+    config.src,
+    config.onDone,
+    config.onFailure,
+    config.onSnapshot
+  )
+}
+
+const startStaticChild = (
+  scope: Runtime.ProcessScope<any>,
+  ownedChildren: Runtime.OwnedChildRuntime,
+  path: string,
+  raw: Record<PropertyKey, any>
+): Effect.Effect<void, any, any> => {
+  // A zero-input child has no entry-context dependency. Reuse the descriptor's
+  // source function so each running parent does not retain a resolved config
+  // object and an otherwise redundant source closure.
+  const descriptor = raw.child as ChildMachine.Any
+  return startResolved(
+    scope,
+    ownedChildren,
+    path,
+    descriptor.id,
+    descriptor.id,
+    descriptor,
+    descriptor[ChildMachineLogicTypeId],
+    raw.onDone,
+    raw.onFailure,
+    raw.onSnapshot
+  )
+}
+
 /**
  * Starts every invocation owned by active entry paths in deterministic entry
  * order. `undefined` keeps the compiled drain free of empty Effect nodes.
@@ -107,13 +233,18 @@ export const startAll = (
 ): Effect.Effect<void, any, any> | undefined => {
   const effects = Planner.sortEntryPaths(machine, paths)
     .filter((path) => configuration.active.has(path))
-    .flatMap((path) =>
-      resolve(Configuration.getStateConfigByPath(machine, path), {
+    .flatMap((path) => {
+      const context = {
         state: configuration.values.get(path),
         parent: Configuration.getParentValue(machine, configuration, path),
         parents: Configuration.getParentValues(machine, configuration, path),
         event
-      }).map((config) => start(scope, ownedChildren, path, config))
-    )
+      }
+      return InvocationEvent.definitions(Configuration.getStateConfigByPath(machine, path)?.invoke).map((definition) =>
+        "child" in definition && !("input" in definition)
+          ? startStaticChild(scope, ownedChildren, path, definition)
+          : start(scope, ownedChildren, path, resolveOne(definition, context))
+      )
+    })
   return effects.length === 0 ? undefined : runSequentialDiscard(effects)
 }

package/src/internal/machine/invocationEvent.ts

@@ -0,0 +1,72 @@
+/**
+ * Private mailbox messages used to route invocation lifecycle changes through
+ * the owning machine planner.
+ *
+ * @since 0.9.0
+ */
+
+/** @internal */
+export const InvocationEventTypeId: unique symbol = Symbol("effect/Machine/InvocationEvent")
+
+/** @internal */
+export type InvocationEvent =
+  | {
+    readonly [InvocationEventTypeId]: true
+    readonly path: string
+    readonly id: string
+    readonly type: "done"
+    readonly output: unknown
+  }
+  | {
+    readonly [InvocationEventTypeId]: true
+    readonly path: string
+    readonly id: string
+    readonly type: "failure"
+    readonly error: unknown
+  }
+  | {
+    readonly [InvocationEventTypeId]: true
+    readonly path: string
+    readonly id: string
+    readonly type: "snapshot"
+    readonly snapshot: unknown
+  }
+
+/** @internal */
+export const done = (path: string, id: string, output: unknown): InvocationEvent => ({
+  [InvocationEventTypeId]: true,
+  path,
+  id,
+  type: "done",
+  output
+})
+
+/** @internal */
+export const failure = (path: string, id: string, error: unknown): InvocationEvent => ({
+  [InvocationEventTypeId]: true,
+  path,
+  id,
+  type: "failure",
+  error
+})
+
+/** @internal */
+export const snapshot = (path: string, id: string, value: unknown): InvocationEvent => ({
+  [InvocationEventTypeId]: true,
+  path,
+  id,
+  type: "snapshot",
+  snapshot: value
+})
+
+/** @internal */
+export const isInvocationEvent = (value: unknown): value is InvocationEvent =>
+  typeof value === "object" && value !== null && InvocationEventTypeId in value
+
+/** @internal */
+export const definitions = (invoke: unknown): ReadonlyArray<Record<PropertyKey, any>> => {
+  if (invoke === undefined) return []
+  return Array.isArray(invoke)
+    ? invoke as ReadonlyArray<Record<PropertyKey, any>>
+    : [invoke as Record<PropertyKey, any>]
+}