@typeonce/effect-machine 0.20.0 → 0.21.0

package/src/Machine.ts

@@ -3577,9 +3577,10 @@ export declare namespace Machine {
    *
    * **Details**
    *
-   * Every branch exposes its selected target without executing its resolver.
-   * A compound local or branch target covers its descendants;
-   * `undefined` identifies an explicitly targetless branch.
+   * Every branch exposes its static selection without executing its resolver.
+   * A compound local or branch target covers its descendants. An `update`
+   * selection keeps `target` undefined and records its value owner in
+   * `selection.path`; `none` identifies an explicitly targetless branch.
    *
    * @category models
    * @since 0.4.0
@@ -4461,6 +4462,33 @@ export declare namespace Machine {
     >
   }
 
+  /**
+   * Opaque instruction that replaces one active compound or parallel state's
+   * value without changing its active descendants.
+   *
+   * @category models
+   * @since 0.21.0
+   */
+  export interface StateUpdate<
+    States extends StateSchemas,
+    StateId extends ValuedStateIdentifier<States>
+  > {
+    readonly [Topology.StateUpdateTypeId]: typeof Topology.StateUpdateTypeId
+    readonly path: StateId
+    readonly value: StateByIdentifier<States, StateId>
+  }
+
+  /** @internal */
+  type StateUpdateBuilder<
+    States extends StateSchemas,
+    StateId extends ValuedStateIdentifier<States>
+  > =
+    & ((value: StateByIdentifier<States, StateId>) => StateUpdate<States, StateId>)
+    & FromMethod<
+      readonly [input: SchemaByIdentifier<States, StateId>["~type.make.in"]],
+      StateUpdate<States, StateId>
+    >
+
   /**
    * Opaque result returned by an explicitly targetless transition.
    *
@@ -4745,6 +4773,45 @@ export declare namespace Machine {
         & SelectionTreeWithPrefix<AllStates, Children, Path, Scope, Builder>
     : SelectionMethod<Builder, Path>
 
+  /** @internal */
+  type StateUpdateSelectionForNode<
+    AllStates extends StateSchemas,
+    Node,
+    Path extends string
+  > = Node extends { readonly states: StateSchemas } ? NodeSchema<Node> extends never ? {}
+    : {
+      readonly update: SelectionValue<
+        StateUpdateBuilder<AllStates, Extract<Path, ValuedStateIdentifier<AllStates>>>,
+        Path,
+        "update"
+      >
+    }
+    : {}
+
+  /** @internal */
+  type BranchUpdateSelectionPath<
+    AllStates extends StateSchemas,
+    Node,
+    Path extends string,
+    Rest extends string
+  > =
+    & StateUpdateSelectionForNode<AllStates, Node, Path>
+    & (Node extends { readonly states: infer Children extends StateSchemas } ?
+      Rest extends `${infer Head}.${infer Tail}` ? Head extends keyof Children ? {
+            readonly [Key in Head]: BranchUpdateSelectionPath<
+              AllStates,
+              Children[Head],
+              JoinPath<Path, Head>,
+              Tail
+            >
+          }
+        : {}
+      : Rest extends keyof Children ? {
+          readonly [Key in Rest]: StateUpdateSelectionForNode<AllStates, Children[Rest], JoinPath<Path, Rest>>
+        }
+      : {}
+      : {})
+
   type FullSelectionNode<
     AllStates extends StateSchemas,
     Node,
@@ -4769,13 +4836,17 @@ export declare namespace Machine {
     Source extends StateNodeIdentifier<States>,
     Root extends string = Source extends `${infer Head}.${string}` ? Head : Source
   > = Root extends ActiveStateKey<States> ? Root extends keyof BranchTargetBuilder<States, Source> ? {
-        readonly [Key in Root]: SelectionNode<
-          States,
-          States[Key],
-          Key,
-          "branch",
-          BranchTargetBuilder<States, Source>[Key]
-        >
+        readonly [Key in Root]:
+          & SelectionNode<
+            States,
+            States[Key],
+            Key,
+            "branch",
+            BranchTargetBuilder<States, Source>[Key]
+          >
+          & (Source extends ChoiceIdentifier<States> ? {}
+            : Source extends `${Key}.${infer Rest}` ? BranchUpdateSelectionPath<States, States[Key], Key, Rest>
+            : StateUpdateSelectionForNode<States, States[Key], Key>)
       }
     : {}
     : {}
@@ -4783,14 +4854,21 @@ export declare namespace Machine {
   type LocalTargetSelector<
     States extends StateSchemas,
     Source extends StateNodeIdentifier<States>
-  > = NearestCompoundScope<States, Source> extends infer Scope extends StateIdentifier<States> ?
-    ChildrenOf<States, Scope> extends infer Children extends StateSchemas ?
-      LocalTargetBuilder<States, Source> extends infer Builder ?
-          & SelectionTreeWithPrefix<States, Children, Scope, "local", Builder>
-          & ("with" extends keyof Builder ? {
-              readonly with: SelectionValue<Builder["with"], Scope>
-            }
-            : {})
+  > = NearestCompoundScope<States, Source> extends infer Scope ? [Scope] extends [never] ? {}
+    : Scope extends StateIdentifier<States> ?
+      ChildrenOf<States, Scope> extends infer Children extends StateSchemas ?
+        LocalTargetBuilder<States, Source> extends infer Builder ?
+            & SelectionTreeWithPrefix<States, Children, Scope, "local", Builder>
+            & ("with" extends keyof Builder ? {
+                readonly with: SelectionValue<Builder["with"], Scope>
+              }
+              : {})
+            & (Source extends ChoiceIdentifier<States> ? {}
+              : Scope extends ValuedStateIdentifier<States> ? {
+                  readonly update: SelectionValue<StateUpdateBuilder<States, Scope>, Scope, "update">
+                }
+              : {})
+        : {}
       : {}
     : {}
     : {}
@@ -4831,9 +4909,9 @@ export declare namespace Machine {
   > {
     /** Handles the trigger without selecting a destination. */
     readonly none: SelectionValue<TargetBuilder<States, Source>["none"], never, "none">
-    /** Selects a destination inside the nearest active compound scope. */
+    /** Selects a destination or updates the nearest active compound scope. */
     readonly local: LocalTargetSelector<States, Source>
-    /** Selects a destination elsewhere under the currently active root. */
+    /** Selects a destination or updates a valued active ancestor under the current root. */
     readonly branch: BranchTargetSelector<States, Source>
     /** Selects a complete destination under any top-level state. */
     readonly full: FullTargetSelector<States>
@@ -5243,9 +5321,9 @@ export declare namespace Machine {
    * **Details**
    *
    * Handlers return snapshots for complete state replacement, target builder
-   * results for path-safe partial transitions, or `target.none()` for an
-   * explicitly targetless transition. Raw decoded state values and `void` are
-   * not accepted at transition boundaries.
+   * results for path-safe partial transitions, state-value updates, or
+   * `target.none()` for an explicitly targetless transition. Raw decoded state
+   * values and `void` are not accepted at transition boundaries.
    *
    * @category utility types
    * @since 0.4.0
@@ -5255,11 +5333,13 @@ export declare namespace Machine {
     | Target<States, StateIdentifier<States>>
     | HistoryTarget<States, HistoryIdentifier<States>>
     | ChoiceTarget<States, ChoiceIdentifier<States>>
+    | StateUpdate<States, ValuedStateIdentifier<States>>
     | StateConstruction<
       | Snapshot<States>
       | Target<States, StateIdentifier<States>>
       | HistoryTarget<States, HistoryIdentifier<States>>
       | ChoiceTarget<States, ChoiceIdentifier<States>>
+      | StateUpdate<States, ValuedStateIdentifier<States>>
     >
     | NoTarget
 
@@ -5639,6 +5719,28 @@ export declare namespace Machine {
     | (SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined)
     | Declined
 
+  /** @internal */
+  type StateUpdateResolver<
+    Events extends ReadonlyArray<TaggedSchema>,
+    Emits extends ReadonlyArray<TaggedSchema>,
+    Context,
+    Selection
+  > = (
+    context: TransitionResolveContext<Context, Selection>,
+    enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>
+  ) => SelectedTargetResult<Selection>
+
+  /** @internal */
+  type DeclinableStateUpdateResolver<
+    Events extends ReadonlyArray<TaggedSchema>,
+    Emits extends ReadonlyArray<TaggedSchema>,
+    Context,
+    Selection
+  > = (
+    context: TransitionResolveContext<Context, Selection> & DeclineCapability,
+    enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>
+  ) => SelectedTargetResult<Selection> | Declined
+
   /** One named destination declared by a branching transition. */
   export interface TransitionBranchInput<
     Selection extends TargetSelection<any, any, any> = TargetSelection<any, any, any>
@@ -5880,6 +5982,80 @@ export declare namespace Machine {
       : {}
       : {})
 
+  /** @internal */
+  interface StateUpdateTransitionRequired<
+    States extends StateSchemas,
+    Events extends ReadonlyArray<TaggedSchema>,
+    Emits extends ReadonlyArray<TaggedSchema>,
+    StateId extends StateNodeIdentifier<States>,
+    Context,
+    Reenter extends boolean,
+    Selection extends TargetSelection<any, any, "update">
+  > {
+    (
+      resolve: StateUpdateResolver<Events, Emits, Context, Selection>,
+      options?: TransitionRequiredOptions<Reenter>
+    ): BuiltTransition<
+      States,
+      Events,
+      Emits,
+      StateId,
+      Context,
+      Reenter,
+      SelectedTargetResult<Selection>,
+      "required"
+    >
+  }
+
+  /** @internal */
+  interface StateUpdateTransitionDeclinable<
+    States extends StateSchemas,
+    Events extends ReadonlyArray<TaggedSchema>,
+    Emits extends ReadonlyArray<TaggedSchema>,
+    StateId extends StateNodeIdentifier<States>,
+    Context,
+    Reenter extends boolean,
+    Selection extends TargetSelection<any, any, "update">
+  > {
+    (
+      resolve: DeclinableStateUpdateResolver<Events, Emits, Context, Selection>,
+      options: TransitionDeclinableOptions<Reenter>
+    ): BuiltTransition<
+      States,
+      Events,
+      Emits,
+      StateId,
+      Context,
+      Reenter,
+      SelectedTargetResult<Selection> | Declined,
+      "declinable"
+    >
+  }
+
+  /** @internal */
+  type StateUpdateTransition<
+    States extends StateSchemas,
+    Events extends ReadonlyArray<TaggedSchema>,
+    Emits extends ReadonlyArray<TaggedSchema>,
+    StateId extends StateNodeIdentifier<States>,
+    Context,
+    Reenter extends boolean,
+    Acceptance extends TransitionAcceptance,
+    Selection extends TargetSelection<any, any, "update">
+  > =
+    & Selection
+    & StateUpdateTransitionRequired<States, Events, Emits, StateId, Context, Reenter, Selection>
+    & ("declinable" extends Acceptance ? StateUpdateTransitionDeclinable<
+        States,
+        Events,
+        Emits,
+        StateId,
+        Context,
+        Reenter,
+        Selection
+      >
+      : {})
+
   /** @internal Type evidence retained by a machine initial-entry declaration. */
   export interface InitialBuilderEvidence<out Selection> {
     readonly [InitialBuilderTypeId]: Types.Covariant<Selection>
@@ -5933,19 +6109,18 @@ export declare namespace Machine {
     Reenter extends boolean,
     Acceptance extends TransitionAcceptance,
     Node
-  > = Node extends (...args: infer Args) => infer Selection ? Selection extends TargetSelection<any, any, any> ?
-        & ((...args: Args) => TransitionTarget<
-          States,
-          Events,
-          Emits,
-          StateId,
-          Context,
-          Reenter,
-          Acceptance,
-          Selection
-        >)
-        & {
-          readonly [Key in keyof Node]: TransitionSelectorNode<
+  > = Node extends TargetSelection<any, any, "update"> ? StateUpdateTransition<
+      States,
+      Events,
+      Emits,
+      StateId,
+      Context,
+      Reenter,
+      Acceptance,
+      Node
+    >
+    : Node extends (...args: infer Args) => infer Selection ? Selection extends TargetSelection<any, any, any> ?
+          & ((...args: Args) => TransitionTarget<
             States,
             Events,
             Emits,
@@ -5953,10 +6128,21 @@ export declare namespace Machine {
             Context,
             Reenter,
             Acceptance,
-            Node[Key]
-          >
-        }
-    : never
+            Selection
+          >)
+          & {
+            readonly [Key in keyof Node]: TransitionSelectorNode<
+              States,
+              Events,
+              Emits,
+              StateId,
+              Context,
+              Reenter,
+              Acceptance,
+              Node[Key]
+            >
+          }
+      : never
     : Node extends TargetSelection<any, any, any> ? TransitionTarget<
         States,
         Events,
@@ -8760,9 +8946,10 @@ export const initialDefinition: <M extends Machine.Any>(machine: M) => Machine.I
  *
  * Event handlers retain their handler-key order within each source state and
  * are followed by eventless and completion handlers. This function does not
- * execute resolvers. Every direct, named, and targetless branch exposes the
- * destination selected by its required static `target` declaration, while
- * `acceptance` reports whether the resolver may decline the transition.
+ * execute resolvers. Every branch exposes its static selection. State updates
+ * retain the updated owner in `selection.path` while leaving `target`
+ * undefined because they do not change topology. `acceptance` reports whether
+ * the resolver may decline the transition.
  *
  * @category getters
  * @since 0.4.0

package/src/internal/machine/executionPlan.ts

@@ -47,7 +47,7 @@ import {
   validateDeclaredTransitionTarget
 } from "./planner.js"
 import { decodeEmitSync, decodeEventSync, decodeInputSync, decodeStateValueSync } from "./protocol.js"
-import { isInitialTarget, isNoTarget, isSnapshot, isTarget, TargetSnapshotTypeId } from "./topology.js"
+import { isInitialTarget, isNoTarget, isSnapshot, isStateUpdate, isTarget, TargetSnapshotTypeId } from "./topology.js"
 
 interface IndexedExecutionDescriptor {
   readonly flat: boolean
@@ -548,7 +548,25 @@ const collectIndexedEvaluatedTransition = (
     selection.context,
     selection.transition.evaluate
   )
-  const unresolvedTarget = transitionResult.state
+  const update = isStateUpdate(transitionResult.state)
+    ? (() => {
+      const index = descriptor.indexByPath.get(transitionResult.state.path)
+      const node = index === undefined ? undefined : descriptor.nodes[index]
+      if (
+        index === undefined || node === undefined || state.active[index] !== 1 || node.schema === undefined ||
+        (node.type !== "compound" && node.type !== "parallel")
+      ) {
+        throw new Error(
+          `Machine state update owner "${transitionResult.state.path}" must be an active valued compound or parallel state`
+        )
+      }
+      return {
+        path: node.path,
+        value: decodeStateValueSync(machine, node, transitionResult.state.value)
+      }
+    })()
+    : undefined
+  const unresolvedTarget = update === undefined ? transitionResult.state : undefined
   validateDeclaredTransitionTarget(
     selection.sourcePath,
     selection.trigger,
@@ -568,9 +586,14 @@ const collectIndexedEvaluatedTransition = (
     throw new Error("Machine expected indexed transition target to be a snapshot or target builder result")
   }
   const next = target === undefined
-    ? state
+    ? update === undefined ? state : (() => {
+      const next = copyOwnedIndexedState(state)
+      next.values[descriptor.indexByPath.get(update.path)!] = update.value
+      return next
+    })()
     : normalizeIndexedTargetStateSync(machine, descriptor, state, target as any, selection.leafIndex)
   const changed = selection.transition.reenter || !hasSameIndexedActive(state, next)
+  const stabilize = changed || update !== undefined
   if (!changed) {
     return {
       selection,
@@ -578,11 +601,13 @@ const collectIndexedEvaluatedTransition = (
       branchKey: transitionResult.branchKey,
       unresolvedTarget: unresolvedTarget as any,
       target: target as any,
+      update,
       next,
       commands: [...transitionResult.commands, ...(initialResolution?.commands ?? [])],
       raisedEvents: [...transitionResult.raisedEvents, ...(initialResolution?.raisedEvents ?? [])],
       emittedEvents: [...transitionResult.emittedEvents, ...(initialResolution?.emittedEvents ?? [])],
       changed: false,
+      stabilize,
       exitPaths: [],
       entryPaths: [],
       choiceTransitions: initialResolution?.transitions ?? []
@@ -603,11 +628,13 @@ const collectIndexedEvaluatedTransition = (
     branchKey: transitionResult.branchKey,
     unresolvedTarget: unresolvedTarget as any,
     target: target as any,
+    update,
     next,
     commands: [...transitionResult.commands, ...(initialResolution?.commands ?? [])],
     raisedEvents: [...transitionResult.raisedEvents, ...(initialResolution?.raisedEvents ?? [])],
     emittedEvents: [...transitionResult.emittedEvents, ...(initialResolution?.emittedEvents ?? [])],
     changed: true,
+    stabilize,
     exitPaths: getExitPaths(machine, activeConfigurationFromIndexedState(descriptor, state), boundary),
     entryPaths: getEntryPaths(machine, activeConfigurationFromIndexedState(descriptor, next), boundary),
     choiceTransitions: initialResolution?.transitions ?? []
@@ -663,6 +690,13 @@ const indexedMicrostep = (
   if (transitions.length === 1) {
     next = transitions[0]!.next
   } else {
+    for (const transition of transitions) {
+      if (transition.update !== undefined) {
+        const values = next.values.slice()
+        values[descriptor.indexByPath.get(transition.update.path)!] = transition.update.value
+        next = { ...next, values }
+      }
+    }
     const applicationOrder = [
       ...transitions.filter((transition) => !transition.changed),
       ...transitions.filter((transition) => transition.changed)

package/src/internal/machine/machine.ts

@@ -227,6 +227,15 @@ const decorateTransitionSelection = (selection: Topology.TargetSelection): Topol
     reenter: () => makeDirectTransitionDescriptor(selection, undefined, { reenter: true })
   })
 
+const decorateStateUpdateSelection = (selection: Topology.TargetSelection): Topology.TargetSelection => {
+  const update = (
+    resolve: (context: any, enqueue: unknown) => unknown,
+    options?: unknown
+  ) => makeDirectTransitionDescriptor(selection, resolve, options)
+  Object.assign(update, selection)
+  return Object.freeze(update) as unknown as Topology.TargetSelection
+}
+
 const noneTransitionSelection = decorateTransitionSelection(Topology.noneTargetSelection)
 
 const makeInitialBuilderDescriptor = (
@@ -268,6 +277,7 @@ const decorateInitialSelectorNode = (node: unknown): unknown => {
 
 const decorateTransitionSelectorNode = (node: unknown): unknown => {
   if (Topology.isTargetSelection(node)) {
+    if (node.kind === "update") return decorateStateUpdateSelection(node)
     return node === Topology.noneTargetSelection ? noneTransitionSelection : decorateTransitionSelection(node)
   }
   if (typeof node === "function") {
@@ -363,22 +373,29 @@ const makeSelectionValue = (
   scope: Topology.TargetSelectionScope
 ): Topology.TargetSelection => Topology.makeTargetSelection(kind, path, scope)
 
+const makeStateUpdateSelection = (
+  path: string,
+  scope: "local" | "branch"
+): Topology.TargetSelection => Topology.makeTargetSelection("update", path, scope)
+
 const addSelectionChildren = (
   builder: Record<string, unknown>,
   stateNodes: Machine.StateNodes,
   parent: string,
-  scope: "local" | "branch"
+  scope: "local" | "branch",
+  source?: string
 ): void => {
   for (const node of stateNodes.byPath.values()) {
     if (node.parent !== parent || node.type === "history") continue
-    builder[node.key] = makeSelectionNode(stateNodes, node.path, scope)
+    builder[node.key] = makeSelectionNode(stateNodes, node.path, scope, source)
   }
 }
 
 const makeSelectionNode = (
   stateNodes: Machine.StateNodes,
   path: string,
-  scope: Topology.TargetSelectionScope
+  scope: Topology.TargetSelectionScope,
+  source?: string
 ): unknown => {
   const node = getTargetBuilderNode(stateNodes, path)
   const kind: Topology.TargetSelectionKind = node.type === "choice" ? "choice" : "state"
@@ -389,7 +406,17 @@ const makeSelectionNode = (
       enumerable: true
     })
     if (scope === "local" || scope === "branch") {
-      addSelectionChildren(method, stateNodes, path, scope)
+      addSelectionChildren(method, stateNodes, path, scope, source)
+    }
+    if (
+      scope === "branch" && source !== undefined && node.schema !== undefined &&
+      (source === path || source.startsWith(`${path}.`)) &&
+      getTargetBuilderNode(stateNodes, source).type !== "choice"
+    ) {
+      Object.defineProperty(method, "update", {
+        value: makeStateUpdateSelection(path, "branch"),
+        enumerable: true
+      })
     }
   }
   return method
@@ -424,13 +451,16 @@ const makeTargetSelector = (
   }
   const branch: Record<string, unknown> = {}
   const root = getTargetBuilderNode(stateNodes, source.split(".")[0]!)
-  branch[root.key] = makeSelectionNode(stateNodes, root.path, "branch")
+  branch[root.key] = makeSelectionNode(stateNodes, root.path, "branch", source)
   const local: Record<string, unknown> = {}
   const localScope = getLocalTargetScope(stateNodes, source)
   if (localScope !== undefined) {
     const localScopeNode = getTargetBuilderNode(stateNodes, localScope)
     if (localScopeNode.schema !== undefined) {
       local.with = makeSelectionValue("state", localScope, "local")
+      if (getTargetBuilderNode(stateNodes, source).type !== "choice") {
+        local.update = makeStateUpdateSelection(localScope, "local")
+      }
     }
     addSelectionChildren(local, stateNodes, localScope, "local")
   }
@@ -469,6 +499,13 @@ const getSelectionBuilder = (
   source: string
 ): unknown => {
   if (selection.kind === "none") return target.none
+  if (selection.kind === "update") {
+    return withFrom(
+      (value: unknown) => Topology.makeStateUpdate(selection.path!, value),
+      "leaf",
+      true
+    )
+  }
   let builder: any
   let parts = selection.path!.split(".")
   if (selection.kind === "history") {
@@ -514,6 +551,12 @@ const validateResolvedSelection = (
     }
     return
   }
+  if (selection.kind === "update") {
+    if (!Topology.isStateUpdate(result) || result.path !== selection.path) {
+      throw new Error(`Machine state update for "${selection.path}" must return its selected update builder`)
+    }
+    return
+  }
   if (result === undefined) return
   const resultPath = typeof result === "object" && result !== null && hasProperty(result, "path") &&
       typeof result.path === "string"
@@ -556,6 +599,9 @@ const runCapturedBranch = (
   return resolved === undefined ? constructSelectedTarget(selectedTarget) : resolved
 }
 
+const topologyTargetPath = (selection: Topology.TargetSelection): string | undefined =>
+  selection.kind === "update" ? undefined : selection.path
+
 const isArrayIndexKey = (key: string): boolean => {
   const index = Number(key)
   return Number.isInteger(index) && index >= 0 && index < 0xffff_ffff && String(index) === key
@@ -738,7 +784,9 @@ const captureTransition = (
       declinable,
       targets: [
         ...new Set(
-          branches.flatMap((branch) => branch.selection.path === undefined ? [] : [branch.selection.path])
+          branches.flatMap((branch) =>
+            topologyTargetPath(branch.selection) === undefined ? [] : [branch.selection.path!]
+          )
         )
       ],
       branches: branches.map((branch) =>
@@ -746,7 +794,7 @@ const captureTransition = (
           type: "branch" as const,
           key: branch.key,
           title: branch.title,
-          target: branch.selection.path,
+          target: topologyTargetPath(branch.selection),
           selection: transitionTargetSelection(branch.selection)
         })
       ),
@@ -763,10 +811,10 @@ const captureTransition = (
   return {
     reenter,
     declinable,
-    targets: branch.selection.path === undefined ? [] : [branch.selection.path],
+    targets: topologyTargetPath(branch.selection) === undefined ? [] : [branch.selection.path!],
     branches: [{
       type: "direct" as const,
-      target: branch.selection.path,
+      target: topologyTargetPath(branch.selection),
       selection: transitionTargetSelection(branch.selection)
     }],
     evaluate,