@typeonce/effect-machine 0.15.0 → 0.16.0

package/src/internal/machine/activities.ts

@@ -22,6 +22,9 @@ export type StaticActivityMetadata =
     readonly type: "timer"
     readonly duration: string | "dynamic"
   }
+  | {
+    readonly type: "stream"
+  }
   | {
     readonly type: "machine"
     readonly child: {
@@ -94,6 +97,10 @@ const appendStaticDefinition = (
     })
     return
   }
+  if (Reflect.has(descriptor, "stream")) {
+    definitions.push({ source, id, type: "stream" })
+    return
+  }
   if (Reflect.has(descriptor, "logic")) {
     definitions.push({ source, id, type: "process" })
   }

package/src/internal/machine/executionPlan.ts

@@ -445,11 +445,12 @@ const collectIndexedTransition = (
     }
   }
   const evaluated = evaluate === undefined
-    ? { result: transition(context, enqueue), branchIndex: 0 }
+    ? { result: transition(context, enqueue), branchIndex: 0, branchKey: undefined }
     : evaluate(context, enqueue)
   return {
     state: isNoTarget(evaluated.result) ? undefined : evaluated.result,
     branchIndex: evaluated.branchIndex,
+    branchKey: evaluated.branchKey,
     commands: commands ?? emptyExecutionValues,
     raisedEvents: raisedEvents ?? emptyExecutionValues,
     emittedEvents: emittedEvents ?? emptyExecutionValues
@@ -569,6 +570,7 @@ const collectIndexedEvaluatedTransition = (
     return {
       selection,
       branchIndex: transitionResult.branchIndex,
+      branchKey: transitionResult.branchKey,
       unresolvedTarget: unresolvedTarget as any,
       target: target as any,
       next,
@@ -593,6 +595,7 @@ const collectIndexedEvaluatedTransition = (
   return {
     selection,
     branchIndex: transitionResult.branchIndex,
+    branchKey: transitionResult.branchKey,
     unresolvedTarget: unresolvedTarget as any,
     target: target as any,
     next,
@@ -619,6 +622,7 @@ const indexedMicrostep = (
     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)
   })
@@ -804,6 +808,7 @@ const planIndexedFlatState = (
               trigger: { type: "event", event: event._tag },
               reenter: transition.reenter,
               branchIndex: transitionResult.branchIndex,
+              branchKey: transitionResult.branchKey,
               target: target === undefined ? undefined : getTargetNodePath(target as any),
               resolvedTarget: target === undefined ? undefined : getTargetNodePath(target as any)
             }]

package/src/internal/machine/invocation.ts

@@ -6,12 +6,13 @@
 
 import * as Cause from "effect/Cause"
 import * as Effect from "effect/Effect"
+import * as Stream from "effect/Stream"
 import type { ChildMachine, Inspection, 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 * as Runtime from "./runtime.js"
 import { ChildMachineLogicTypeId } from "./symbols.js"
 
 /** @internal */
@@ -37,12 +38,35 @@ const oneShot = (effect: Effect.Effect<any, any, any>): Logic<void, never, any,
   run: () => effect
 })
 
+const streamLogic = (
+  stream: Stream.Stream<any, any, any>,
+  path: string,
+  id: string
+): Runtime.ProcessLogic<void, never, any, any, void> => ({
+  initial: () => Effect.void,
+  run: ({ parent }) => {
+    const send = parent?.[Runtime.acknowledgedSend]
+    if (send === undefined) {
+      return Effect.die(new Error("Stream invocation requires an acknowledged parent machine"))
+    }
+    return Stream.runForEach(
+      stream,
+      (element) =>
+        send(InvocationEvent.element(path, id, element)).pipe(
+          Effect.asVoid,
+          Effect.catchCause(() => Effect.interrupt)
+        )
+    )
+  }
+})
+
 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>
+  context: Machine.InvokeContext<any, any, any, any>,
+  path: string
 ): AnyConfig => {
   if ("effect" in raw) {
     return {
@@ -78,6 +102,17 @@ const resolveOne = (
       activityKind: "Timer"
     }
   }
+  if ("stream" in raw) {
+    const id = String(raw.id)
+    return {
+      id,
+      src: () =>
+        streamLogic(raw.stream(context), path, id) as unknown as Runtime.ProcessLogic<any, any, any, any, any, any>,
+      onDone: raw.onDone,
+      onFailure: raw.onFailure,
+      activityKind: "Stream"
+    }
+  }
   if ("logic" in raw) {
     return {
       id: String(raw.id),
@@ -103,7 +138,7 @@ const resolveOne = (
       onSnapshot: raw.onSnapshot
     }
   }
-  throw new Error("Machine invoke must define exactly one of effect, after, logic, or child")
+  throw new Error("Machine invoke must define exactly one of effect, stream, after, logic, or child")
 }
 
 /** @internal */
@@ -269,7 +304,7 @@ export const startAll = (
       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))
+          : start(scope, ownedChildren, path, resolveOne(definition, context, path))
       )
     })
   return effects.length === 0 ? undefined : runSequentialDiscard(effects)

package/src/internal/machine/invocationEvent.ts

@@ -10,6 +10,13 @@ export const InvocationEventTypeId: unique symbol = Symbol("effect/Machine/Invoc
 
 /** @internal */
 export type InvocationEvent =
+  | {
+    readonly [InvocationEventTypeId]: true
+    readonly path: string
+    readonly id: string
+    readonly type: "element"
+    readonly element: unknown
+  }
   | {
     readonly [InvocationEventTypeId]: true
     readonly path: string
@@ -41,6 +48,15 @@ export const done = (path: string, id: string, output: unknown): InvocationEvent
   output
 })
 
+/** @internal */
+export const element = (path: string, id: string, value: unknown): InvocationEvent => ({
+  [InvocationEventTypeId]: true,
+  path,
+  id,
+  type: "element",
+  element: value
+})
+
 /** @internal */
 export const failure = (path: string, id: string, error: unknown): InvocationEvent => ({
   [InvocationEventTypeId]: true,

package/src/internal/machine/machine.ts

@@ -137,8 +137,6 @@ const makeWithHandlers = (
 }
 
 type DefinitionBranch = {
-  readonly title?: string
-  readonly when?: (context: any) => Option.Option<unknown>
   readonly target: (selector: unknown) => unknown
   readonly resolve?: (context: any, enqueue: unknown) => unknown
 }
@@ -147,6 +145,17 @@ type CapturedBranch = DefinitionBranch & {
   readonly selection: Topology.TargetSelection
 }
 
+type BranchDeclaration = {
+  readonly title?: string
+  readonly target: unknown
+}
+
+type CapturedNamedBranch = {
+  readonly key: string
+  readonly title: string
+  readonly selection: Topology.TargetSelection
+}
+
 const transitionTargetSelection = (
   selection: Topology.TargetSelection
 ): Machine.TransitionTargetSelection =>
@@ -336,20 +345,134 @@ const runCapturedBranch = (
   context: Record<string, any>,
   enqueue: unknown,
   stateNodes: Machine.StateNodes,
-  source: string,
-  match?: { readonly value: unknown }
+  source: string
 ): unknown => {
   const selectedTarget = getSelectionBuilder(context.target, branch.selection, stateNodes, source)
   if (branch.resolve === undefined) return constructSelectedTarget(selectedTarget)
   const resolverContext = { ...context }
   if (branch.selection.kind === "none") delete resolverContext.target
   else resolverContext.target = selectedTarget
-  if (match !== undefined) resolverContext.match = match.value
   const resolved = branch.resolve(resolverContext, enqueue)
   validateResolvedSelection(resolved, branch.selection, stateNodes)
   return resolved === undefined ? constructSelectedTarget(selectedTarget) : resolved
 }
 
+const isArrayIndexKey = (key: string): boolean => {
+  const index = Number(key)
+  return Number.isInteger(index) && index >= 0 && index < 0xffff_ffff && String(index) === key
+}
+
+const captureNamedBranches = (
+  declarations: unknown,
+  path: string,
+  trigger: PropertyKey
+): ReadonlyArray<CapturedNamedBranch> => {
+  if (typeof declarations !== "object" || declarations === null || Array.isArray(declarations)) {
+    throw new Error(`Machine branching transition for state "${path}" on "${String(trigger)}" requires a branch record`)
+  }
+  if (Object.getOwnPropertySymbols(declarations).length > 0) {
+    throw new Error(`Machine branching transition for state "${path}" on "${String(trigger)}" cannot use symbol keys`)
+  }
+  const keys = Object.keys(declarations)
+  if (keys.length === 0) {
+    throw new Error(`Machine branching transition for state "${path}" on "${String(trigger)}" requires a branch`)
+  }
+  return Object.freeze(keys.map((key) => {
+    if (key.length === 0 || isArrayIndexKey(key)) {
+      throw new Error(
+        `Machine branching transition for state "${path}" on "${String(trigger)}" requires non-index string branch keys`
+      )
+    }
+    const declaration = (declarations as Record<string, unknown>)[key]
+    if (typeof declaration !== "object" || declaration === null || !hasProperty(declaration, "target")) {
+      throw new Error(`Machine transition branch "${key}" requires a target selection`)
+    }
+    const { target, title } = declaration as BranchDeclaration
+    if (!Topology.isTargetSelection(target)) {
+      throw new Error(`Machine transition branch "${key}" must select exactly one target`)
+    }
+    if (title !== undefined && (typeof title !== "string" || title.length === 0)) {
+      throw new Error(`Machine transition branch "${key}" title must be a non-empty string`)
+    }
+    return Object.freeze({ key, title: title ?? key, selection: target })
+  }))
+}
+
+const wrapSelectedBranchBuilder = (
+  builder: unknown,
+  owner: object,
+  branchIndex: number,
+  branchKey: string
+): unknown => {
+  if (typeof builder === "function") {
+    const wrapped = (...args: ReadonlyArray<unknown>) =>
+      Topology.makeSelectedBranch(owner, branchIndex, branchKey, builder(...args))
+    for (const property of Reflect.ownKeys(builder)) {
+      if (
+        property === "length" || property === "name" || property === "prototype" || property === "caller" ||
+        property === "arguments"
+      ) continue
+      const descriptor = Object.getOwnPropertyDescriptor(builder, property)
+      if (descriptor === undefined) continue
+      if ("value" in descriptor && typeof descriptor.value === "function") {
+        descriptor.value = wrapSelectedBranchBuilder(descriptor.value, owner, branchIndex, branchKey)
+      }
+      Object.defineProperty(wrapped, property, descriptor)
+    }
+    return wrapped
+  }
+  if (typeof builder === "object" && builder !== null) {
+    const wrapped: Record<PropertyKey, unknown> = {}
+    for (const property of Reflect.ownKeys(builder)) {
+      const descriptor = Object.getOwnPropertyDescriptor(builder, property)
+      if (descriptor === undefined) continue
+      if ("value" in descriptor && typeof descriptor.value === "function") {
+        descriptor.value = wrapSelectedBranchBuilder(descriptor.value, owner, branchIndex, branchKey)
+      }
+      Object.defineProperty(wrapped, property, descriptor)
+    }
+    return wrapped
+  }
+  throw new Error(`Machine could not construct transition branch "${branchKey}"`)
+}
+
+const makeBranchSelectors = (
+  context: Record<string, any>,
+  branches: ReadonlyArray<CapturedNamedBranch>,
+  owner: object,
+  stateNodes: Machine.StateNodes,
+  source: string
+): Readonly<Record<string, unknown>> => {
+  const select: Record<string, unknown> = Object.create(null)
+  for (let branchIndex = 0; branchIndex < branches.length; branchIndex++) {
+    const branch = branches[branchIndex]!
+    select[branch.key] = wrapSelectedBranchBuilder(
+      getSelectionBuilder(context.target, branch.selection, stateNodes, source),
+      owner,
+      branchIndex,
+      branch.key
+    )
+  }
+  return Object.freeze(select)
+}
+
+const validateSelectedBranchResult = (
+  result: unknown,
+  selection: Topology.TargetSelection,
+  stateNodes: Machine.StateNodes
+): void => {
+  if (selection.kind === "none") {
+    if (!Topology.isNoTarget(result)) {
+      throw new Error("Machine targetless branch must return its selected targetless builder")
+    }
+    return
+  }
+  if (result === undefined) {
+    throw new Error(`Machine transition branch selected "${selection.path}" without constructing its target`)
+  }
+  validateResolvedSelection(result, selection, stateNodes)
+}
+
 const captureTransition = (
   transition: unknown,
   stateNodes: Machine.StateNodes,
@@ -362,64 +485,53 @@ const captureTransition = (
   const definition = transition as Record<PropertyKey, unknown>
   const selector = makeTargetSelector(stateNodes, path)
   const reenter = definition.reenter === true
-  if (Array.isArray(definition.cases)) {
-    const rawCases = definition.cases as ReadonlyArray<unknown>
-    if (definition.cases.length === 0 || !hasProperty(definition, "otherwise")) {
+  if (hasProperty(definition, "branches")) {
+    const branching = definition as { readonly branches: unknown; readonly resolve?: unknown }
+    if (typeof branching.branches !== "function" || typeof branching.resolve !== "function") {
       throw new Error(
-        `Machine conditional transition for state "${path}" on "${String(trigger)}" requires cases and otherwise`
+        `Machine branching transition for state "${path}" on "${String(trigger)}" requires branches and resolve`
       )
     }
-    const cases = rawCases.map((branch) => {
-      const captured = captureDefinitionBranch(branch, selector, path, trigger)
-      if (typeof captured.title !== "string" || captured.title.length === 0 || typeof captured.when !== "function") {
+    const resolve = branching.resolve
+    const branches = captureNamedBranches(branching.branches(selector), path, trigger)
+    const owner = Object.freeze({})
+    const evaluate = (context: Record<string, any>, enqueue: unknown) => {
+      const resolverContext = { ...context }
+      delete resolverContext.target
+      resolverContext.select = makeBranchSelectors(context, branches, owner, stateNodes, path)
+      const selected = resolve(resolverContext, enqueue)
+      if (!Topology.isSelectedBranch(selected) || selected.owner !== owner) {
         throw new Error(
-          `Machine conditional transition case for state "${path}" on "${String(trigger)}" requires title and when`
+          `Machine branching transition for state "${path}" on "${String(trigger)}" must select one declared branch`
         )
       }
-      return captured
-    })
-    const otherwise = captureDefinitionBranch(definition.otherwise, selector, path, trigger)
-    const evaluate = (context: Record<string, any>, enqueue: unknown) => {
-      const predicateContext = { ...context }
-      delete predicateContext.target
-      for (let branchIndex = 0; branchIndex < cases.length; branchIndex++) {
-        const branch = cases[branchIndex]!
-        const result = branch.when!(predicateContext)
-        if (!Option.isOption(result)) {
-          throw new Error(`Machine conditional transition case "${branch.title}" must return Option`)
-        }
-        if (Option.isSome(result)) {
-          return {
-            result: runCapturedBranch(branch, context, enqueue, stateNodes, path, { value: result.value }),
-            branchIndex
-          }
-        }
+      const branch = branches[selected.branchIndex]
+      if (branch === undefined || selected.branchKey !== branch.key) {
+        throw new Error(`Machine branching transition returned invalid branch evidence`)
       }
+      validateSelectedBranchResult(selected.result, branch.selection, stateNodes)
       return {
-        result: runCapturedBranch(otherwise, context, enqueue, stateNodes, path),
-        branchIndex: cases.length
+        result: selected.result,
+        branchIndex: selected.branchIndex,
+        branchKey: selected.branchKey
       }
     }
     return {
       reenter,
       targets: [
         ...new Set(
-          [...cases, otherwise].flatMap((branch) => branch.selection.path === undefined ? [] : [branch.selection.path])
+          branches.flatMap((branch) => branch.selection.path === undefined ? [] : [branch.selection.path])
         )
       ],
-      branches: [
-        ...cases.map((branch) => ({
-          type: "case" as const,
-          title: branch.title!,
+      branches: branches.map((branch) =>
+        Object.freeze({
+          type: "branch" as const,
+          key: branch.key,
+          title: branch.title,
           target: branch.selection.path,
           selection: transitionTargetSelection(branch.selection)
-        })),
-        {
-          type: "otherwise" as const,
-          target: otherwise.selection.path,
-          selection: transitionTargetSelection(otherwise.selection)
-        }
-      ],
+        })
+      ),
       evaluate,
       transition: (context: Record<string, any>, enqueue: unknown) => evaluate(context, enqueue).result
     }
@@ -427,7 +539,8 @@ const captureTransition = (
   const branch = captureDefinitionBranch(transition, selector, path, trigger)
   const evaluate = (context: Record<string, any>, enqueue: unknown) => ({
     result: runCapturedBranch(branch, context, enqueue, stateNodes, path),
-    branchIndex: 0
+    branchIndex: 0,
+    branchKey: undefined
   })
   return {
     reenter,
@@ -465,7 +578,7 @@ const captureInvokeDefinition = (
   if (Array.isArray(invoke)) return invoke.map((item) => captureInvokeDefinition(item, stateNodes, path))
   if (typeof invoke !== "object" || invoke === null) return invoke
   const captured = { ...(invoke as Record<PropertyKey, unknown>) }
-  for (const key of ["onDone", "onFailure", "onSnapshot"] as const) {
+  for (const key of ["onElement", "onDone", "onFailure", "onSnapshot"] as const) {
     if (captured[key] !== undefined) {
       captured[key] = captureTransition(captured[key], stateNodes, path, key)
     }

package/src/internal/machine/planner.ts

@@ -71,6 +71,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
   }>
@@ -108,6 +109,7 @@ export type TransitionHandler<States extends Machine.StateSchemas, E, R, Context
 type TransitionEvaluation<States extends Machine.StateSchemas, E, R> = {
   readonly result: Machine.HandlerResult<States, E, R>
   readonly branchIndex: number
+  readonly branchKey: string | undefined
 }
 
 type TransitionEvaluator<States extends Machine.StateSchemas, E, R, Context> = (
@@ -214,11 +216,12 @@ 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)
   return {
     state: isNoTarget(evaluated.result) ? undefined : evaluated.result,
     branchIndex: evaluated.branchIndex,
+    branchKey: evaluated.branchKey,
     commands: collected.commands,
     raisedEvents: collected.raisedEvents,
     emittedEvents: collected.emittedEvents
@@ -523,6 +526,7 @@ export type SelectedTransition<States extends Machine.StateSchemas, E, R, Contex
 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 +548,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
   }>
@@ -952,7 +957,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,7 +975,9 @@ 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 }
@@ -1150,6 +1159,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 +1238,7 @@ function resolveChoiceTarget(
         trigger: { type: "choice" },
         reenter: false,
         branchIndex: collected.branchIndex,
+        branchKey: collected.branchKey,
         target: returnedPath,
         resolvedTarget: nested?.target.path ?? returnedPath
       })
@@ -1398,6 +1409,7 @@ const collectEvaluatedTransition = <
     return {
       selection,
       branchIndex: transitionResult.branchIndex,
+      branchKey: transitionResult.branchKey,
       unresolvedTarget,
       target,
       commands: [
@@ -1444,6 +1456,7 @@ const collectEvaluatedTransition = <
   return {
     selection,
     branchIndex: transitionResult.branchIndex,
+    branchKey: transitionResult.branchKey,
     unresolvedTarget,
     target,
     commands: [
@@ -1799,6 +1812,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)
     },