@typeonce/effect-machine 0.20.0 → 0.22.0

package/src/internal/machine/planner.ts

@@ -47,11 +47,13 @@ import {
   getNode,
   type InitialTarget as InitialTargetInstruction,
   isChoiceTarget,
+  isCombinedTarget,
   isDeclined,
   isHistoryTarget,
   isInitialTarget,
   isNoTarget,
   isSnapshot,
+  isStateUpdate,
   isTarget,
   makeChoiceTarget,
   makeTarget,
@@ -69,6 +71,7 @@ export type MicrostepPlan<State, Event, E, R> = {
     readonly branchKey: string | undefined
     readonly target: string | undefined
     readonly resolvedTarget: string | undefined
+    readonly updates: ReadonlyArray<string>
   }>
   readonly commands: ReadonlyArray<RuntimeCommand>
   readonly raisedEvents: ReadonlyArray<Event>
@@ -78,6 +81,11 @@ export type MicrostepPlan<State, Event, E, R> = {
   readonly changed: boolean
 }
 
+type SettlingMicrostep<State, Event, E, R> = MicrostepPlan<State, Event, E, R> & {
+  /** Internal signal that eventless stabilization must run again. */
+  readonly stabilize: boolean
+}
+
 export type MacrostepPlan<State, Event, E, R, Output> =
   & {
     readonly next: State
@@ -580,10 +588,15 @@ export type EvaluatedTransition<States extends Machine.StateSchemas, Event, E, R
     | Machine.Snapshot<States>
     | Machine.Target<States, Machine.StateIdentifier<States>>
     | undefined
+  readonly update: {
+    readonly path: string
+    readonly value: unknown
+  } | undefined
   readonly commands: ReadonlyArray<RuntimeCommand>
   readonly raisedEvents: ReadonlyArray<Event>
   readonly emittedEvents: ReadonlyArray<unknown>
   readonly changed: boolean
+  readonly stabilize: boolean
   readonly exitPaths: ReadonlyArray<string>
   readonly entryPaths: ReadonlyArray<string>
   readonly choiceTransitions: ReadonlyArray<{
@@ -594,6 +607,7 @@ export type EvaluatedTransition<States extends Machine.StateSchemas, Event, E, R
     readonly branchKey: string | undefined
     readonly target: string
     readonly resolvedTarget: string
+    readonly updates: ReadonlyArray<string>
   }>
 }
 
@@ -1143,7 +1157,9 @@ export const removeConflictingTransitions = <
     let preempted = false
     const transitionsToRemove = new Set<EvaluatedTransition<States, Event, E, R, Context>>()
     for (const selected of filtered) {
-      if (hasPathIntersection(transition.exitPaths, selected.exitPaths)) {
+      const writesSameState = transition.update !== undefined && selected.update !== undefined &&
+        transition.update.path === selected.update.path
+      if (hasPathIntersection(transition.exitPaths, selected.exitPaths) || writesSameState) {
         if (isDescendantOf(transition.selection.sourcePath, selected.selection.sourcePath)) {
           transitionsToRemove.add(selected)
         } else {
@@ -1221,6 +1237,7 @@ interface ResolvedChoiceTransition {
   readonly branchKey: string | undefined
   readonly target: string
   readonly resolvedTarget: string
+  readonly updates: ReadonlyArray<string>
 }
 
 function resolveChoiceTarget(
@@ -1299,7 +1316,8 @@ function resolveChoiceTarget(
         branchIndex: collected.branchIndex,
         branchKey: collected.branchKey,
         target: returnedPath,
-        resolvedTarget: nested?.target.path ?? returnedPath
+        resolvedTarget: nested?.target.path ?? returnedPath,
+        updates: []
       })
       commands.push(...collected.commands)
       raisedEvents.push(...collected.raisedEvents)
@@ -1343,9 +1361,12 @@ const collectEvaluatedTransition = <
   if (transitionResult.declined) {
     throw new Error("Machine transition returned decline without declaring declinable: true")
   }
-  const unresolvedTarget = transitionResult.state === undefined
+  const combined = isCombinedTarget(transitionResult.state) ? transitionResult.state : undefined
+  const transitionState = combined?.target ?? transitionResult.state
+  const unresolvedTarget = transitionState === undefined
+      || isStateUpdate(transitionState)
     ? undefined
-    : transitionResult.state as
+    : transitionState as
       | Machine.Snapshot<States>
       | Machine.Target<States, Machine.StateIdentifier<States>>
       | Machine.HistoryTarget<States, Machine.HistoryIdentifier<States>>
@@ -1356,6 +1377,22 @@ const collectEvaluatedTransition = <
     selection.transition.targets,
     unresolvedTarget
   )
+  const stateUpdate = combined?.update ?? (isStateUpdate(transitionState) ? transitionState : undefined)
+  const update = stateUpdate !== undefined
+    ? (() => {
+      const node = getNode(machine, stateUpdate.path)
+      if (
+        !state.active.has(node.path) || node.schema === undefined ||
+        (node.type !== "compound" && node.type !== "parallel")
+      ) {
+        throw new Error(`Machine state update owner "${node.path}" must be an active valued compound or parallel state`)
+      }
+      return {
+        path: node.path,
+        value: decodeStateValueSync(machine, node, stateUpdate.value)
+      }
+    })()
+    : undefined
   const choiceResolution = unresolvedTarget === undefined
     ? undefined
     : resolveChoiceTarget(
@@ -1456,7 +1493,10 @@ const collectEvaluatedTransition = <
     ? getTargetNodePath(target)
     : getTargetNodePath(unresolvedTarget)
   let stateAfterTransition = target === undefined
-    ? state
+    ? update === undefined ? state : {
+      ...state,
+      values: new Map(state.values).set(update.path, update.value)
+    }
     : normalizeTargetConfigurationSync<States>(machine, state, target)
   for (const additionalTarget of additionalChoiceTargets) {
     stateAfterTransition = normalizeTargetConfigurationSync<States>(
@@ -1465,7 +1505,17 @@ const collectEvaluatedTransition = <
       additionalTarget
     )
   }
+  if (combined !== undefined && update !== undefined && !stateAfterTransition.active.has(update.path)) {
+    throw new Error(`Machine combined target exited its updating owner "${update.path}"`)
+  }
+  if (update !== undefined) {
+    stateAfterTransition = {
+      ...stateAfterTransition,
+      values: new Map(stateAfterTransition.values).set(update.path, update.value)
+    }
+  }
   const changed = selection.transition.reenter || !hasSameActivePaths(state, stateAfterTransition)
+  const stabilize = changed || update !== undefined
 
   if (!changed) {
     return {
@@ -1474,6 +1524,7 @@ const collectEvaluatedTransition = <
       branchKey: transitionResult.branchKey,
       unresolvedTarget,
       target,
+      update,
       commands: [
         ...transitionResult.commands,
         ...(choiceResolution?.commands ?? []),
@@ -1496,6 +1547,7 @@ const collectEvaluatedTransition = <
         ...additionalTargetEmittedEvents
       ],
       changed,
+      stabilize,
       exitPaths: [],
       entryPaths: [],
       choiceTransitions: [
@@ -1521,6 +1573,7 @@ const collectEvaluatedTransition = <
     branchKey: transitionResult.branchKey,
     unresolvedTarget,
     target,
+    update,
     commands: [
       ...transitionResult.commands,
       ...(choiceResolution?.commands ?? []),
@@ -1543,6 +1596,7 @@ const collectEvaluatedTransition = <
       ...additionalTargetEmittedEvents
     ],
     changed,
+    stabilize,
     exitPaths: reenteredHistoryTarget !== undefined
       ? sortExitPaths(
         machine,
@@ -1744,7 +1798,8 @@ export const planInitialSync = <
       emittedEvents: [...choiceResolution.emittedEvents, ...initialHistoryEmittedEvents],
       exitPaths: [],
       entryPaths: [],
-      changed: false
+      changed: false,
+      stabilize: false
     }]
   )
 
@@ -1850,7 +1905,8 @@ const microstep = <
       emittedEvents: [],
       exitPaths: [],
       entryPaths: [],
-      changed: false
+      changed: false,
+      stabilize: false
     }
   }
 
@@ -1876,11 +1932,23 @@ const microstep = <
       branchIndex: transition.branchIndex,
       branchKey: transition.branchKey,
       target: transition.unresolvedTarget === undefined ? undefined : getTargetNodePath(transition.unresolvedTarget),
-      resolvedTarget: transition.target === undefined ? undefined : getTargetNodePath(transition.target)
+      resolvedTarget: transition.target === undefined ? undefined : getTargetNodePath(transition.target),
+      updates: transition.update === undefined ? [] : [transition.update.path]
     },
     ...transition.choiceTransitions
   ])
   let stateAfterTransition = state
+  // Updates never reactivate topology. Apply every retained value write to the
+  // original active configuration before any control target becomes
+  // authoritative.
+  for (const transition of sortedTransitions) {
+    if (transition.update !== undefined) {
+      stateAfterTransition = {
+        ...stateAfterTransition,
+        values: new Map(stateAfterTransition.values).set(transition.update.path, transition.update.value)
+      }
+    }
+  }
   // Value-only targets are evaluated against the original configuration. If
   // one is applied after a control-changing transition, it can resurrect a
   // branch that the changing transition exited. Apply value-only updates
@@ -1901,6 +1969,7 @@ const microstep = <
   }
 
   const changed = transitions.some((transition) => transition.changed)
+  const stabilize = transitions.some((transition) => transition.stabilize)
   const transitionActions = sortedTransitions
     .flatMap((transition) => transition.commands)
   const transitionRaisedEvents = sortedTransitions
@@ -1918,7 +1987,8 @@ const microstep = <
       emittedEvents: transitionEmittedEvents,
       exitPaths: [],
       entryPaths: [],
-      changed: false
+      changed: false,
+      stabilize
     }
   }
 
@@ -1951,7 +2021,8 @@ const microstep = <
     emittedEvents: [...exit.emittedEvents, ...transitionEmittedEvents, ...entry.emittedEvents],
     exitPaths,
     entryPaths,
-    changed: true
+    changed: true,
+    stabilize
   }
 }
 
@@ -1974,7 +2045,7 @@ const settle = <
   commands: Array<RuntimeCommand>,
   raisedEvents: Array<Machine.EventOf<Events>>,
   emittedEvents: Array<unknown>,
-  microsteps: Array<MicrostepPlan<ActiveConfiguration, Machine.EventOf<Events>, E, R>>
+  microsteps: Array<SettlingMicrostep<ActiveConfiguration, Machine.EventOf<Events>, E, R>>
 ) => {
   let currentState = state
   let currentEvent = event
@@ -2010,7 +2081,7 @@ const settle = <
       pendingCompletions.length === 0 ? [] : [pendingCompletions.shift()!]
     )
     if (done.length > 0) {
-      const doneStep: MicrostepPlan<ActiveConfiguration, Machine.EventOf<Events>, E, R> = microstep(
+      const doneStep: SettlingMicrostep<ActiveConfiguration, Machine.EventOf<Events>, E, R> = microstep(
         machine,
         currentState,
         currentEvent,
@@ -2021,7 +2092,7 @@ const settle = <
       emittedEvents.push(...doneStep.emittedEvents)
       microsteps.push(doneStep)
       currentState = doneStep.next
-      shouldRunAlways = doneStep.changed
+      shouldRunAlways = doneStep.stabilize
       continue
     }
     if (isActiveFinalConfiguration(machine, currentState)) {
@@ -2038,7 +2109,7 @@ const settle = <
       ? selectAlwaysTransitions<States, Events, Emits, E, R>(machine, currentState, currentEvent)
       : []
     if (always.length > 0) {
-      const alwaysStep: MicrostepPlan<ActiveConfiguration, Machine.EventOf<Events>, E, R> = microstep(
+      const alwaysStep: SettlingMicrostep<ActiveConfiguration, Machine.EventOf<Events>, E, R> = microstep(
         machine,
         currentState,
         currentEvent,
@@ -2049,7 +2120,7 @@ const settle = <
       emittedEvents.push(...alwaysStep.emittedEvents)
       microsteps.push(alwaysStep)
       currentState = alwaysStep.next
-      shouldRunAlways = alwaysStep.changed
+      shouldRunAlways = alwaysStep.stabilize
       continue
     }
 

package/src/internal/machine/topology.ts

@@ -29,6 +29,10 @@ export const DeclinedTypeId: unique symbol = Symbol("effect/Machine/Declined")
 
 export const TargetSelectionTypeId: unique symbol = Symbol("effect/Machine/TargetSelection")
 
+export const StateUpdateTypeId: unique symbol = Symbol("effect/Machine/StateUpdate")
+
+export const CombinedTargetTypeId: unique symbol = Symbol("effect/Machine/CombinedTarget")
+
 export const SelectedBranchTypeId: unique symbol = Symbol("effect/Machine/SelectedBranch")
 
 interface StateInput {
@@ -73,7 +77,7 @@ export interface Declined {
   readonly [DeclinedTypeId]: typeof DeclinedTypeId
 }
 
-export type TargetSelectionKind = "state" | "initial" | "history" | "choice" | "none"
+export type TargetSelectionKind = "state" | "initial" | "history" | "choice" | "update" | "none"
 
 export type TargetSelectionScope = "local" | "branch" | "full" | "initial"
 
@@ -83,6 +87,7 @@ export interface TargetSelection {
   readonly kind: TargetSelectionKind
   readonly scope: TargetSelectionScope | undefined
   readonly path: string | undefined
+  readonly updatePath?: string
 }
 
 /** One branch selection returned by a compiled branching transition. */
@@ -97,13 +102,15 @@ export interface SelectedBranch {
 export const makeTargetSelection = (
   kind: TargetSelectionKind,
   path?: string,
-  scope?: TargetSelectionScope
+  scope?: TargetSelectionScope,
+  updatePath?: string
 ): TargetSelection =>
   Object.freeze({
     [TargetSelectionTypeId]: TargetSelectionTypeId as typeof TargetSelectionTypeId,
     kind,
     scope,
-    path
+    path,
+    ...(updatePath === undefined ? {} : { updatePath })
   })
 
 /** Source-independent definition-time selection for an explicitly targetless transition. */
@@ -111,6 +118,36 @@ export const noneTargetSelection: TargetSelection = makeTargetSelection("none",
 
 export const isTargetSelection = (u: unknown): u is TargetSelection => hasProperty(u, TargetSelectionTypeId)
 
+export interface StateUpdate {
+  readonly [StateUpdateTypeId]: typeof StateUpdateTypeId
+  readonly path: string
+  readonly value: unknown
+}
+
+export const makeStateUpdate = (path: string, value: unknown): StateUpdate =>
+  Object.freeze({
+    [StateUpdateTypeId]: StateUpdateTypeId,
+    path,
+    value
+  })
+
+export const isStateUpdate = (u: unknown): u is StateUpdate => hasProperty(u, StateUpdateTypeId)
+
+export interface CombinedTarget {
+  readonly [CombinedTargetTypeId]: typeof CombinedTargetTypeId
+  readonly target: unknown
+  readonly update: StateUpdate
+}
+
+export const makeCombinedTarget = (target: unknown, update: StateUpdate): CombinedTarget =>
+  Object.freeze({
+    [CombinedTargetTypeId]: CombinedTargetTypeId,
+    target,
+    update
+  })
+
+export const isCombinedTarget = (u: unknown): u is CombinedTarget => hasProperty(u, CombinedTargetTypeId)
+
 export const makeSelectedBranch = (
   owner: object,
   branchIndex: number,

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

@@ -1234,7 +1234,10 @@ const selectSnapshot = (
   if (state.node._tag === "Choice") {
     return (builder[state.node.key] as () => unknown)()
   }
-  const method = builder[state.node.key] as (value: unknown, selector?: (builder: any) => unknown) => unknown
+  const method = builder[state.node.key].decoded as (
+    value: unknown,
+    selector?: (builder: any) => unknown
+  ) => unknown
   const value = stateValue(state, path === requestedParts?.join(".") ? requestedValue : undefined)
   if (state.node._tag === "Atomic" || state.node._tag === "Final") return method(value)
 
@@ -1473,14 +1476,15 @@ const makeHandlers = (
           ...(Object.keys(history).length === 0 ? {} : { history }),
           ...(node._tag === "Compound"
             ? {
-              initialize: ({ builder }: any) => builder(stateValue(byPath.get(`${path}.${node.initial}`)!))
+              initialize: ({ builder }: any) => builder.decoded(stateValue(byPath.get(`${path}.${node.initial}`)!))
             }
             : {
               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}`)!)),
+                    (current: any, child) =>
+                      current[child.key].decoded(stateValue(byPath.get(`${path}.${child.key}`)!)),
                     builder
                   )
             }),

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

@@ -475,7 +475,7 @@ const targetWithinSelection = (
   nodeByPath: ReadonlyMap<string, Machine.Machine.StateNode>
 ): boolean => {
   const selection = branch.selection
-  if (selection.kind === "none") return target === undefined
+  if (selection.kind === "none" || selection.kind === "update") return target === undefined
   if (target === undefined || selection.path === undefined) return false
   if (target === selection.path) return true
   const selectedNode = nodeByPath.get(selection.path)
@@ -577,6 +577,7 @@ export const coverage = <M extends AnyMachine>(
   let microsteps = 0
   let changedMicrosteps = 0
   let targetlessTransitions = 0
+  let stateUpdates = 0
   let raisedEvents = 0
   let emittedEvents = 0
   let eventTriggered = 0
@@ -630,7 +631,8 @@ export const coverage = <M extends AnyMachine>(
     hitPaths(microstep.exitPaths, exitHits)
     observeSnapshot(microstep.next)
     for (const retained of microstep.transitions) {
-      if (retained.target === undefined) targetlessTransitions += 1
+      stateUpdates += retained.updates.length
+      if (retained.target === undefined && retained.updates.length === 0) targetlessTransitions += 1
       if (retained.trigger.type === "event") eventTriggered += 1
       else if (retained.trigger.type === "always") alwaysTriggered += 1
       else if (retained.trigger.type === "done") doneTriggered += 1
@@ -718,6 +720,7 @@ export const coverage = <M extends AnyMachine>(
       total: microsteps,
       changed: changedMicrosteps,
       targetless: targetlessTransitions,
+      updates: stateUpdates,
       raised: raisedEvents,
       emitted: emittedEvents,
       eventTriggered,
@@ -1540,6 +1543,18 @@ export const verify = <M extends AnyMachine>(
         transition.target === undefined ? transition.source : String(transition.target)
       )
     }
+    if (
+      transition.updates.length !== branch.updates.length ||
+      transition.updates.some((path, index) => path !== branch.updates[index])
+    ) {
+      add(
+        "definitions.selection",
+        location,
+        `transition branch ${transition.branchIndex} from "${transition.source}" reported retained owner updates ` +
+          `${JSON.stringify(transition.updates)} instead of ${JSON.stringify(branch.updates)}`,
+        transition.source
+      )
+    }
     return branch
   }
 
@@ -1598,7 +1613,13 @@ export const verify = <M extends AnyMachine>(
       const resolvedTarget = transition.resolvedTarget === undefined ? undefined : String(transition.resolvedTarget)
       const targetNode = target === undefined ? undefined : byPath.get(target)
       let expected = target
-      let explanation = target === undefined ? "an unresolved targetless transition" : `target "${target}"`
+      let explanation = transition.updates.length > 0
+        ? target === undefined
+          ? `update owner "${transition.updates.join("\", \"")}"`
+          : `target "${target}" and update owner "${transition.updates.join("\", \"")}"`
+        : target === undefined
+        ? "an unresolved targetless transition"
+        : `target "${target}"`
 
       if (transition.trigger.type === "choice") {
         explanation = target === undefined ? "a targetless choice edge" : `choice edge target "${target}"`

package/src/testing/MachineTest.ts

@@ -1109,7 +1109,7 @@ export const Invariant: {
  *   events: Machine.events(),
  *   initial: {
  *     target: (to) => to.Count(),
- *     resolve: ({ target }) => target(new Count({ value: 0 }))
+ *     resolve: ({ target }) => target.decoded(new Count({ value: 0 }))
  *   }
  * }).handle({ Count: {} })
  *
@@ -1444,14 +1444,14 @@ export type ExploreOptions<M extends AnyMachine, Key extends ExplorationKey = Ex
  *   events: Machine.events(Increment),
  *   initial: {
  *     target: (to) => to.Count(),
- *     resolve: ({ target }) => target(new Count({ value: 0 }))
+ *     resolve: ({ target }) => target.decoded(new Count({ value: 0 }))
  *   }
  * }).handle({
  *   Count: {
  *     on: {
  *       Increment: (to) =>
  *         to.full.Count().resolve(({ state, target }) =>
- *           target(new Count({ value: state.value + 1 })))
+ *           target.decoded(new Count({ value: state.value + 1 })))
  *     }
  *   }
  * })
@@ -1822,6 +1822,8 @@ export interface MicrostepCoverageEvidence {
   readonly total: number
   readonly changed: number
   readonly targetless: number
+  /** Retained state-value update operations. */
+  readonly updates: number
   readonly raised: number
   readonly emitted: number
   readonly eventTriggered: number

package/src/unstable/reactivity/AtomMachine.ts

@@ -374,7 +374,7 @@ type ChildState<Child extends Machine.ChildMachine.Any> = RefState<Machine.Child
  *   events: Machine.events(),
  *   initial: {
  *     target: (to) => to.Count(),
- *     resolve: ({ target }) => target(new Count({ value: 0 }))
+ *     resolve: ({ target }) => target.decoded(new Count({ value: 0 }))
  *   }
  * }).handle({ Count: {} })
  * const machineAtom = AtomMachine.make(machine)