@typeonce/effect-machine 0.12.0 → 0.14.0

package/src/internal/machine/symbols.ts

@@ -1,5 +1,8 @@
 /** @internal */
 export const InitialEventTypeId: unique symbol = Symbol("effect/Machine/InitialEvent")
 
+/** @internal */
+export const SnapshotBuilderStateTypeId: unique symbol = Symbol("effect/Machine/SnapshotBuilderState")
+
 /** @internal Returns process logic for a child descriptor and optional input. */
 export const ChildMachineLogicTypeId: unique symbol = Symbol("effect/Machine/ChildMachineLogic")

package/src/internal/machine/topology.ts

@@ -19,10 +19,14 @@ export const StateConstructionTypeId: unique symbol = Symbol("effect/Machine/Sta
 
 export const HistoryTargetTypeId: unique symbol = Symbol("effect/Machine/HistoryTarget")
 
+export const InitialTargetTypeId: unique symbol = Symbol("effect/Machine/InitialTarget")
+
 export const ChoiceTargetTypeId: unique symbol = Symbol("effect/Machine/ChoiceTarget")
 
 export const NoTargetTypeId: unique symbol = Symbol("effect/Machine/NoTarget")
 
+export const TargetSelectionTypeId: unique symbol = Symbol("effect/Machine/TargetSelection")
+
 interface StateInput {
   readonly [StateInputTypeId]: typeof StateInputTypeId
   readonly input: unknown
@@ -36,6 +40,17 @@ export interface HistoryTarget {
   readonly parent: string
 }
 
+/** Internal instruction that enters the selected state's declared initial
+ * configuration. The planner supplies implicit child values through the
+ * owning states' `initialize` handlers. */
+export interface InitialTarget {
+  readonly [InitialTargetTypeId]: typeof InitialTargetTypeId
+  readonly _tag: "InitialTarget"
+  readonly path: string
+  readonly value: unknown
+  readonly values?: Readonly<Record<string, unknown>>
+}
+
 /** Internal target produced by a choice target builder. */
 export interface ChoiceTarget {
   readonly [ChoiceTargetTypeId]: typeof ChoiceTargetTypeId
@@ -49,6 +64,32 @@ export interface NoTarget {
   readonly [NoTargetTypeId]: typeof NoTargetTypeId
 }
 
+export type TargetSelectionKind = "state" | "initial" | "history" | "choice" | "none"
+
+export type TargetSelectionScope = "local" | "branch" | "full" | "initial"
+
+/** Immutable destination selected while a machine definition is captured. */
+export interface TargetSelection {
+  readonly [TargetSelectionTypeId]: typeof TargetSelectionTypeId
+  readonly kind: TargetSelectionKind
+  readonly scope: TargetSelectionScope | undefined
+  readonly path: string | undefined
+}
+
+export const makeTargetSelection = (
+  kind: TargetSelectionKind,
+  path?: string,
+  scope?: TargetSelectionScope
+): TargetSelection =>
+  Object.freeze({
+    [TargetSelectionTypeId]: TargetSelectionTypeId as typeof TargetSelectionTypeId,
+    kind,
+    scope,
+    path
+  })
+
+export const isTargetSelection = (u: unknown): u is TargetSelection => hasProperty(u, TargetSelectionTypeId)
+
 const noTarget = Object.freeze({
   [NoTargetTypeId]: NoTargetTypeId
 }) as NoTarget
@@ -65,6 +106,20 @@ export const makeHistoryTarget = (path: string, parent: string): HistoryTarget =
 
 export const isHistoryTarget = (u: unknown): u is HistoryTarget => hasProperty(u, HistoryTargetTypeId)
 
+export const makeInitialTarget = (
+  path: string,
+  value: unknown,
+  values?: Readonly<Record<string, unknown>>
+): InitialTarget => ({
+  [InitialTargetTypeId]: InitialTargetTypeId,
+  _tag: "InitialTarget",
+  path,
+  value,
+  ...(values === undefined ? {} : { values })
+})
+
+export const isInitialTarget = (u: unknown): u is InitialTarget => hasProperty(u, InitialTargetTypeId)
+
 export const makeChoiceTarget = (
   path: string,
   parent: string,
@@ -354,12 +409,10 @@ export const compileStateNodes = (states: Machine.StateSchemas): Machine.StateNo
   } as Machine.StateNodes
 }
 
-const dynamicTransitionTargets = { type: "dynamic" } as const
-
-const transitionTargets = (handler: unknown): Machine.TransitionTargets =>
-  typeof handler === "object" && handler !== null && "targets" in handler && handler.targets !== undefined
-    ? { type: "declared", paths: Array.from(handler.targets as ReadonlyArray<string>) }
-    : dynamicTransitionTargets
+const transitionBranches = (handler: unknown): ReadonlyArray<Machine.TransitionBranch> =>
+  typeof handler === "object" && handler !== null && "branches" in handler && Array.isArray(handler.branches)
+    ? Array.from(handler.branches as ReadonlyArray<Machine.TransitionBranch>)
+    : []
 
 export const transitionDefinitions = (
   machine: Machine.Any
@@ -377,7 +430,7 @@ export const transitionDefinitions = (
           source: node.path,
           trigger: { type: "choice" },
           reenter: false,
-          targets: transitionTargets(choice)
+          branches: transitionBranches(choice)
         })
       }
       continue
@@ -387,8 +440,8 @@ export const transitionDefinitions = (
       definitions.push({
         source: node.path,
         trigger: { type: "event", event },
-        reenter: typeof handler === "object" && handler !== null && handler.reenter === true,
-        targets: transitionTargets(handler)
+        reenter: hasProperty(handler, "reenter") && handler.reenter === true,
+        branches: transitionBranches(handler)
       })
     }
     if (config.always !== undefined) {
@@ -396,7 +449,7 @@ export const transitionDefinitions = (
         source: node.path,
         trigger: { type: "always" },
         reenter: false,
-        targets: transitionTargets(config.always)
+        branches: transitionBranches(config.always)
       })
     }
     if (config.onDone !== undefined) {
@@ -404,7 +457,7 @@ export const transitionDefinitions = (
         source: node.path,
         trigger: { type: "done" },
         reenter: false,
-        targets: transitionTargets(config.onDone)
+        branches: transitionBranches(config.onDone)
       })
     }
     const invokes = config.invoke === undefined
@@ -425,7 +478,7 @@ export const transitionDefinitions = (
             source: node.path,
             trigger: { type: "invoke", id, outcome },
             reenter: typeof handler === "object" && handler !== null && handler.reenter === true,
-            targets: transitionTargets(handler)
+            branches: transitionBranches(handler)
           })
         }
       }

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

@@ -30,6 +30,7 @@ import type {
 import type { EnsureExecutable } from "../../machine/readiness.js"
 import { assertInvariants, type InvariantError } from "./invariant.js"
 import { appendTrace, run } from "./trace.js"
+import { makeTransitionCoverageCollector } from "./transitionCoverage.js"
 
 type AnyMachine = Machine.Machine.Any
 
@@ -119,6 +120,10 @@ export const explore = <M extends AnyMachine, Key extends ExplorationKey>(
 
     const initialContext = stateContext(machine, initialTrace)
     const initialKey = validateKey(options.stateKey(initialContext))
+    const transitionCoverage = makeTransitionCoverageCollector<M>(machine)
+    for (const microstep of initialTrace.initial.plan.microsteps) {
+      transitionCoverage.observeMicrostep(microstep)
+    }
     const nodes: Array<ExplorationNode<M, Key>> = [{ ...initialContext, key: initialKey }]
     const nodeDraftsByKey = new Map<Key, number>([[initialKey, 0]])
     const edges: Array<ExplorationEdgeDraft<M>> = []
@@ -165,6 +170,8 @@ export const explore = <M extends AnyMachine, Key extends ExplorationKey>(
         const scenario = scenarioWithEvent(source.trace, event)
         const targetTrace = yield* appendTrace(machine, source.trace, event, scenario)
         plannedTransitions += 1
+        const step = targetTrace.steps[targetTrace.steps.length - 1]!
+        for (const microstep of step.plan.microsteps) transitionCoverage.observeMicrostep(microstep)
         if (invariants.length > 0) {
           yield* assertInvariants(machine, targetTrace, invariants)
         }
@@ -178,7 +185,7 @@ export const explore = <M extends AnyMachine, Key extends ExplorationKey>(
             target: existing,
             edge: {
               event,
-              step: targetTrace.steps[targetTrace.steps.length - 1]!,
+              step,
               discovered: false
             }
           })
@@ -207,7 +214,7 @@ export const explore = <M extends AnyMachine, Key extends ExplorationKey>(
           target: targetIndex,
           edge: {
             event,
-            step: targetTrace.steps[targetTrace.steps.length - 1]!,
+            step,
             discovered: true
           }
         })
@@ -243,6 +250,7 @@ export const explore = <M extends AnyMachine, Key extends ExplorationKey>(
         retainedEdges: edges.length,
         maxDepth: nodes.reduce((maximum, node) => Math.max(maximum, node.depth), 0)
       },
+      transitionCoverage: transitionCoverage.summary(),
       completeness
     }
   })

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

@@ -1177,44 +1177,6 @@ const stateValue = (
   return { _tag: stateTag(state.path), value: value ?? state.node.value }
 }
 
-const runtimeTargetPath = (
-  byPath: ReadonlyMap<string, FlatFiniteState>,
-  sourcePath: string,
-  requestedPath: string
-): string => {
-  const source = byPath.get(sourcePath)!
-  const requested = byPath.get(requestedPath)!
-  if (requested.node._tag === "History") return requested.parent!
-  if (requested.node._tag === "Choice") return runtimeTargetPath(byPath, sourcePath, requested.node.selected)
-  if (source.root !== requested.root) return requested.path
-
-  const initial = (path: string): string => {
-    const current = byPath.get(path)!
-    if (current.node._tag === "Parallel") {
-      if (sourcePath !== current.path && !sourcePath.startsWith(`${current.path}.`)) {
-        return current.path
-      }
-      const child = sourcePath === current.path
-        ? current.node.states[0]!.key
-        : sourcePath.slice(current.path.length + 1).split(".")[0]!
-      return initial(`${current.path}.${child}`)
-    }
-    return current.node._tag === "Compound" ? initial(`${current.path}.${current.node.initial}`) : current.path
-  }
-  const inspect = (path: string): string => {
-    const current = byPath.get(path)!
-    if (
-      current.node._tag === "Parallel" && sourcePath !== current.path && !sourcePath.startsWith(`${current.path}.`)
-    ) {
-      return current.path
-    }
-    if (current.path === requestedPath) return initial(current.path)
-    const next = requestedPath.slice(current.path.length + 1).split(".")[0]!
-    return inspect(`${current.path}.${next}`)
-  }
-  return inspect(source.root)
-}
-
 const makeStateTree = (
   states: ReadonlyArray<FiniteState>,
   parent: string | undefined
@@ -1357,10 +1319,88 @@ const selectHistoryTarget = (builder: Record<string, any>, path: string): unknow
   return current[parts[parts.length - 1]!]()
 }
 
-type TargetBuilder = {
-  readonly branch: Record<string, any>
-  readonly full: Record<string, any>
-  readonly history: Record<string, any>
+const selectableDefinitionTarget = (
+  source: string,
+  target: string,
+  byPath: ReadonlyMap<string, FlatFiniteState>
+): string => {
+  const parts = target.split(".")
+  for (let index = 0; index < parts.length; index++) {
+    const path = parts.slice(0, index + 1).join(".")
+    const node = byPath.get(path)?.node
+    if (
+      (node?._tag === "Compound" || node?._tag === "Parallel") &&
+      source !== path && !source.startsWith(`${path}.`)
+    ) return path
+  }
+  return target
+}
+
+const selectDefinitionTarget = (
+  selector: Record<string, any>,
+  source: string,
+  target: string,
+  byPath: ReadonlyMap<string, FlatFiniteState>
+): unknown => {
+  const selected = byPath.get(target)!
+  if (selected.node._tag === "History") {
+    return selectHistoryTarget(selector.history, target)
+  }
+  const sourceRoot = byPath.get(source)!.root
+  if (selected.root !== sourceRoot) {
+    const root = target.split(".")[0]!
+    return selector.full[root]()
+  }
+  const selectable = selectableDefinitionTarget(source, target, byPath)
+  let current = selector.branch
+  const parts = selectable.split(".")
+  for (const part of parts) current = current[part]
+  if (typeof current === "function") return current()
+  return current.initial()
+}
+
+const resolveDefinitionTarget = (
+  builder: any,
+  source: string,
+  target: string,
+  byPath: ReadonlyMap<string, FlatFiniteState>,
+  value?: number
+): unknown => {
+  const selected = byPath.get(target)!
+  if (selected.node._tag === "History") return builder()
+  if (selected.root !== byPath.get(source)!.root) {
+    const parts = target.split(".")
+    return selectSnapshot({ [parts[0]!]: builder }, parts[0]!, byPath, parts, 0, source, value)
+  }
+  const selectable = selectableDefinitionTarget(source, target, byPath)
+  if (selectable !== target) {
+    const bound = byPath.get(selectable)!
+    const parts = target.split(".")
+    return selectSnapshot(
+      { [bound.node.key]: builder },
+      selectable,
+      byPath,
+      parts,
+      selectable.split(".").length - 1,
+      source,
+      value
+    )
+  }
+  if (selected.node._tag === "Choice") return builder()
+  const input = { value: value ?? selected.node.value }
+  if (selected.node._tag === "Compound" || selected.node._tag === "Parallel") {
+    const parts = target.split(".")
+    return selectSnapshot(
+      { [selected.node.key]: builder },
+      target,
+      byPath,
+      parts,
+      parts.length - 1,
+      source,
+      value
+    )
+  }
+  return builder.from(input)
 }
 
 const makeHandlers = (
@@ -1375,15 +1415,11 @@ const makeHandlers = (
     if (node._tag === "History") continue
     if (node._tag === "Choice") {
       handlers[node.key] = {
-        choice: {
-          targets: node.targets,
-          transition: ({ target }: { readonly target: TargetBuilder }) => {
-            const selected = byPath.get(node.selected)!
-            const parts = selected.path.split(".")
-            const builder = selected.root === byPath.get(path)!.root ? target.branch : target.full
-            return selectSnapshot(builder, parts[0]!, byPath, parts, 0, path)
-          }
-        }
+        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)
       }
       continue
     }
@@ -1396,27 +1432,17 @@ const makeHandlers = (
     let onDone: unknown
     for (const transition of transitions.values()) {
       if (transition.source !== path) continue
-      const config = {
+      const config = (Machine.transition as any)({
         ...("reenter" in transition ? { reenter: transition.reenter } : {}),
-        ...(transition.target === undefined
-          ? {}
-          : {
-            targets: [
-              byPath.get(transition.target)!.node._tag === "History" ||
-                byPath.get(transition.target)!.node._tag === "Choice"
-                ? transition.target
-                : runtimeTargetPath(byPath, path, transition.target)
-            ]
-          }),
-        transition: ({ target }: { readonly target: TargetBuilder }) => {
-          if (transition.target === undefined) return undefined
-          const targetState = byPath.get(transition.target)!
-          if (targetState.node._tag === "History") return selectHistoryTarget(target.history, targetState.path)
-          const parts = transition.target.split(".")
-          const builder = targetState.root === byPath.get(path)!.root ? target.branch : target.full
-          return selectSnapshot(builder, parts[0]!, byPath, parts, 0, path, transition.targetValue)
-        }
-      }
+        target: (to: Record<string, any>) =>
+          transition.target === undefined
+            ? to.none()
+            : selectDefinitionTarget(to, path, transition.target, byPath),
+        resolve: transition.target === undefined
+          ? () => undefined
+          : ({ target }: { readonly target: any }) =>
+            resolveDefinitionTarget(target, path, transition.target!, byPath, transition.targetValue)
+      } as any)
       if (transition.trigger.type === "event") on[transition.trigger.event] = config
       else if (transition.trigger.type === "always") always = config
       else onDone = config
@@ -1449,15 +1475,16 @@ const makeHandlers = (
           ...(Object.keys(history).length === 0 ? {} : { history }),
           ...(node._tag === "Compound"
             ? {
-              initial: () => stateValue(byPath.get(`${path}.${node.initial}`)!)
+              initialize: ({ builder }: any) => builder(stateValue(byPath.get(`${path}.${node.initial}`)!))
             }
             : {
-              initial: () =>
-                Object.fromEntries(
-                  node.states
-                    .filter((child) => child._tag !== "History" && child._tag !== "Choice")
-                    .map((child) => [child.key, stateValue(byPath.get(`${path}.${child.key}`)!)])
-                )
+              initialize: ({ builder }: any) =>
+                node.states
+                  .filter((child) => child._tag !== "History" && child._tag !== "Choice")
+                  .reduce(
+                    (current: any, child) => current[child.key](stateValue(byPath.get(`${path}.${child.key}`)!)),
+                    builder
+                  )
             }),
           states: makeHandlers(node.states, path, byPath, transitions)
         }
@@ -1488,8 +1515,15 @@ export const compileModel = (model: FiniteModel): Machine.Machine.Any => {
   const machine = Machine.make({
     states: defined.states as any,
     events: Machine.events(...eventSchemas) as any,
-    initial: () => selectSnapshot(defined.initial as any, initial.path, byPath, [initial.path], 0) 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 }) =>
+        selectSnapshot({ [initial.path]: target }, initial.path, byPath, [initial.path], 0) as any
+    }
+  } as any)
   const transitions = new Map(model.transitions.map((transition) => [
     `${transition.source}\u0000${triggerKey(transition.trigger)}`,
     transition

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

@@ -0,0 +1,116 @@
+/**
+ * Exact transition-definition and branch coverage collected from retained
+ * planner microsteps.
+ *
+ * @since 0.14.0
+ */
+
+import * as Machine from "../../../Machine.js"
+import type {
+  CoverageSummary,
+  Microstep,
+  TransitionBranchCoverageItem,
+  TransitionCoverage,
+  TransitionDefinitionCoverageItem
+} from "../../../testing/MachineTest.js"
+
+type AnyMachine = Machine.Machine.Any
+
+type StateNodePath<M extends AnyMachine> = Machine.Machine.StateNodeIdentifier<Machine.Machine.States<M>>
+
+type EventTag<M extends AnyMachine> = Machine.Machine.TagOf<Machine.Machine.Events<M>[number]>
+
+type MachineTransitionCoverage<M extends AnyMachine> = TransitionCoverage<
+  StateNodePath<M>,
+  EventTag<M>,
+  StateNodePath<M>
+>
+
+const coverageSummary = <Item>(declared: ReadonlyArray<Item>, hit: ReadonlySet<number>): CoverageSummary<Item> => {
+  const hits: Array<Item> = []
+  const misses: Array<Item> = []
+  declared.forEach((item, index) => (hit.has(index) ? hits : misses).push(item))
+  return {
+    total: declared.length,
+    hit: hits.length,
+    missing: misses.length,
+    hits,
+    misses
+  }
+}
+
+export const sameTransitionTrigger = (
+  left: Machine.Machine.TransitionTrigger,
+  right: Machine.Machine.TransitionTrigger
+): boolean => {
+  if (left.type !== right.type) return false
+  if (left.type === "event") return right.type === "event" && left.event === right.event
+  if (left.type === "invoke") {
+    return right.type === "invoke" && left.id === right.id && left.outcome === right.outcome
+  }
+  return true
+}
+
+export interface TransitionCoverageCollector<M extends AnyMachine> {
+  readonly observeMicrostep: (microstep: Microstep<M, unknown>) => void
+  readonly summary: () => MachineTransitionCoverage<M>
+}
+
+export const makeTransitionCoverageCollector = <M extends AnyMachine>(
+  machine: M
+): TransitionCoverageCollector<M> => {
+  const definitions = Machine.transitionDefinitions(machine).map(
+    (definition, index): TransitionDefinitionCoverageItem<StateNodePath<M>, EventTag<M>, StateNodePath<M>> => ({
+      id: `transition:${index}`,
+      index,
+      source: definition.source,
+      trigger: definition.trigger,
+      reenter: definition.reenter,
+      branches: definition.branches
+    })
+  )
+  const definitionHits = new Set<number>()
+  const branchOffsets: Array<number> = []
+  const branches: Array<TransitionBranchCoverageItem<StateNodePath<M>, EventTag<M>, StateNodePath<M>>> = []
+  for (let definitionIndex = 0; definitionIndex < definitions.length; definitionIndex++) {
+    branchOffsets.push(branches.length)
+    const definition = definitions[definitionIndex]!
+    definition.branches.forEach((branch, branchIndex) => {
+      branches.push({
+        id: `transition:${definitionIndex}:branch:${branchIndex}`,
+        definitionIndex,
+        branchIndex,
+        source: definition.source,
+        trigger: definition.trigger,
+        reenter: definition.reenter,
+        branch
+      })
+    })
+  }
+  const branchHits = new Set<number>()
+
+  return {
+    observeMicrostep(microstep) {
+      for (const retained of microstep.transitions) {
+        const definitionIndex = definitions.findIndex((definition) =>
+          definition.source === retained.source &&
+          definition.reenter === retained.reenter &&
+          sameTransitionTrigger(definition.trigger, retained.trigger)
+        )
+        if (definitionIndex === -1) continue
+        definitionHits.add(definitionIndex)
+        const definition = definitions[definitionIndex]!
+        if (
+          Number.isSafeInteger(retained.branchIndex) && retained.branchIndex >= 0 &&
+          retained.branchIndex < definition.branches.length
+        ) {
+          branchHits.add(branchOffsets[definitionIndex]! + retained.branchIndex)
+        }
+      }
+    },
+    summary: () => ({
+      definitions: coverageSummary(definitions, definitionHits),
+      branches: coverageSummary(branches, branchHits)
+    })
+  }
+}