@typeonce/effect-machine 0.20.0 → 0.22.0

package/src/internal/machine/executionPlan.ts

@@ -47,7 +47,15 @@ import {
   validateDeclaredTransitionTarget
 } from "./planner.js"
 import { decodeEmitSync, decodeEventSync, decodeInputSync, decodeStateValueSync } from "./protocol.js"
-import { isInitialTarget, isNoTarget, isSnapshot, isTarget, TargetSnapshotTypeId } from "./topology.js"
+import {
+  isCombinedTarget,
+  isInitialTarget,
+  isNoTarget,
+  isSnapshot,
+  isStateUpdate,
+  isTarget,
+  TargetSnapshotTypeId
+} from "./topology.js"
 
 interface IndexedExecutionDescriptor {
   readonly flat: boolean
@@ -548,7 +556,28 @@ const collectIndexedEvaluatedTransition = (
     selection.context,
     selection.transition.evaluate
   )
-  const unresolvedTarget = transitionResult.state
+  const combined = isCombinedTarget(transitionResult.state) ? transitionResult.state : undefined
+  const transitionState = combined?.target ?? transitionResult.state
+  const stateUpdate = combined?.update ?? (isStateUpdate(transitionState) ? transitionState : undefined)
+  const update = stateUpdate !== undefined
+    ? (() => {
+      const index = descriptor.indexByPath.get(stateUpdate.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 "${stateUpdate.path}" must be an active valued compound or parallel state`
+        )
+      }
+      return {
+        path: node.path,
+        value: decodeStateValueSync(machine, node, stateUpdate.value)
+      }
+    })()
+    : undefined
+  const unresolvedTarget = transitionState === undefined || isStateUpdate(transitionState) ? undefined : transitionState
   validateDeclaredTransitionTarget(
     selection.sourcePath,
     selection.trigger,
@@ -567,10 +596,24 @@ const collectIndexedEvaluatedTransition = (
   if (target !== undefined && !isTarget(target) && !isSnapshot(target)) {
     throw new Error("Machine expected indexed transition target to be a snapshot or target builder result")
   }
-  const next = target === undefined
-    ? state
+  let next = target === undefined
+    ? 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)
+  if (combined !== undefined && update !== undefined) {
+    const ownerIndex = descriptor.indexByPath.get(update.path)!
+    if (next.active[ownerIndex] !== 1) {
+      throw new Error(`Machine combined target exited its updating owner "${update.path}"`)
+    }
+    const values = next.values.slice()
+    values[ownerIndex] = update.value
+    next = { ...next, values }
+  }
   const changed = selection.transition.reenter || !hasSameIndexedActive(state, next)
+  const stabilize = changed || update !== undefined
   if (!changed) {
     return {
       selection,
@@ -578,11 +621,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 +648,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 ?? []
@@ -629,7 +676,8 @@ const indexedMicrostep = (
     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]
   })
   if (selections.length === 1) {
     const transition = collectIndexedEvaluatedTransition(machine, descriptor, state, selections[0]!)
@@ -663,6 +711,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)
@@ -815,7 +870,8 @@ const planIndexedFlatState = (
               branchIndex: transitionResult.branchIndex,
               branchKey: transitionResult.branchKey,
               target: target === undefined ? undefined : getTargetNodePath(target as any),
-              resolvedTarget: target === undefined ? undefined : getTargetNodePath(target as any)
+              resolvedTarget: target === undefined ? undefined : getTargetNodePath(target as any),
+              updates: []
             }]
           }
           : undefined),

package/src/internal/machine/initialization.ts

@@ -14,11 +14,19 @@ const getNode = (machine: Machine.Any, path: string): Machine.StateNode => {
 }
 
 const withFrom = <Method extends (value: unknown) => unknown>(method: Method) => {
-  Object.defineProperty(method, "from", {
+  const builder = {}
+  Object.defineProperty(builder, "decoded", {
+    value: method,
+    enumerable: false
+  })
+  Object.defineProperty(builder, "from", {
     value: (...args: ReadonlyArray<unknown>) => method(Topology.makeStateInput(args.length === 0 ? {} : args[0])),
     enumerable: false
   })
-  return method as Method & { readonly from: (...args: ReadonlyArray<unknown>) => unknown }
+  return builder as {
+    readonly decoded: Method
+    readonly from: (...args: ReadonlyArray<unknown>) => unknown
+  }
 }
 
 const makeCompletion = (values: Readonly<Record<string, unknown>>): object => {

package/src/internal/machine/machine.ts

@@ -191,7 +191,7 @@ type InitialBuilderDescriptor = {
 const plainTargetSelection = (selection: Topology.TargetSelection): Topology.TargetSelection =>
   selection.kind === "none"
     ? Topology.noneTargetSelection
-    : Topology.makeTargetSelection(selection.kind, selection.path, selection.scope)
+    : Topology.makeTargetSelection(selection.kind, selection.path, selection.scope, selection.updatePath)
 
 const transitionOptions = (options: unknown): { readonly reenter: boolean; readonly declinable: boolean } => {
   const configuration = typeof options === "object" && options !== null
@@ -224,9 +224,33 @@ const decorateTransitionSelection = (selection: Topology.TargetSelection): Topol
     ...selection,
     resolve: (resolve: (context: any, enqueue: unknown) => unknown, options?: unknown) =>
       makeDirectTransitionDescriptor(selection, resolve, options),
-    reenter: () => makeDirectTransitionDescriptor(selection, undefined, { reenter: true })
+    reenter: () => makeDirectTransitionDescriptor(selection, undefined, { reenter: true }),
+    updating: (owner: unknown) => {
+      if (typeof owner !== "function") {
+        throw new Error("Machine updating owner must be a state selector")
+      }
+      const ownerSelection = owner()
+      if (
+        !Topology.isTargetSelection(ownerSelection) || ownerSelection.kind !== "state" ||
+        ownerSelection.scope !== "branch"
+      ) {
+        throw new Error("Machine updating owner must be addressed by one branch state selector")
+      }
+      return decorateTransitionSelection(
+        Topology.makeTargetSelection(selection.kind, selection.path, selection.scope, ownerSelection.path)
+      )
+    }
   })
 
+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 +292,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") {
@@ -350,6 +375,11 @@ const transitionTargetSelection = (
     scope: selection.scope
   })
 
+const selectionUpdates = (selection: Topology.TargetSelection): ReadonlyArray<string> =>
+  selection.updatePath === undefined ?
+    selection.kind === "update" && selection.path !== undefined ? [selection.path] : []
+    : [selection.updatePath]
+
 const makeSelectionMethod = (
   kind: Topology.TargetSelectionKind,
   path: string | undefined,
@@ -363,22 +393,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 +426,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 +471,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")
   }
@@ -446,6 +496,7 @@ const makeTargetSelector = (
 const captureDefinitionBranch = (
   branch: unknown,
   selector: unknown,
+  stateNodes: Machine.StateNodes,
   path: string,
   trigger: PropertyKey
 ): CapturedBranch => {
@@ -459,9 +510,58 @@ const captureDefinitionBranch = (
   if (!Topology.isTargetSelection(selection)) {
     throw new Error(`Machine transition for state "${path}" on "${String(trigger)}" must select exactly one target`)
   }
+  if (selection.updatePath !== undefined) {
+    const owner = stateNodes.byPath.get(selection.updatePath)
+    if (
+      selection.kind !== "state" || (selection.scope !== "local" && selection.scope !== "branch") ||
+      selection.path === undefined || owner === undefined || owner.schema === undefined ||
+      (owner.type !== "compound" && owner.type !== "parallel") ||
+      !Configuration.isDescendantOf(path, owner.path) ||
+      !Configuration.isDescendantOf(selection.path, owner.path)
+    ) {
+      throw new Error(
+        `Machine updating owner "${selection.updatePath}" must be a valued ancestor retained by source "${path}" and target "${selection.path}"`
+      )
+    }
+  }
   return { ...(branch as DefinitionBranch), selection }
 }
 
+const makeUpdatingConstruction = (
+  target: unknown,
+  ownerPath: string
+): { readonly update: (update: unknown) => Topology.CombinedTarget } =>
+  Object.freeze({
+    update: (update: unknown) => {
+      if (!Topology.isStateUpdate(update) || update.path !== ownerPath) {
+        throw new Error(`Machine combined target must update its declared owner "${ownerPath}"`)
+      }
+      return Topology.makeCombinedTarget(target, update)
+    }
+  })
+
+const makeUpdatingTargetBuilder = (
+  builder: unknown,
+  ownerPath: string
+): unknown => {
+  if (typeof builder !== "object" || builder === null) {
+    throw new Error("Machine combined target requires a state construction builder")
+  }
+  const updating: Record<PropertyKey, unknown> = {}
+  for (const property of Reflect.ownKeys(builder)) {
+    const descriptor = Object.getOwnPropertyDescriptor(builder, property)
+    if (descriptor === undefined) continue
+    if (
+      (property === "from" || property === "decoded") && "value" in descriptor && typeof descriptor.value === "function"
+    ) {
+      const construct = descriptor.value
+      descriptor.value = (...args: ReadonlyArray<unknown>) => makeUpdatingConstruction(construct(...args), ownerPath)
+    }
+    Object.defineProperty(updating, property, descriptor)
+  }
+  return Object.freeze(updating)
+}
+
 const getSelectionBuilder = (
   target: Record<string, any>,
   selection: Topology.TargetSelection,
@@ -469,6 +569,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") {
@@ -497,7 +604,7 @@ const getSelectionBuilder = (
   ) {
     throw new Error(`Machine could not construct selected transition target "${selection.path}"`)
   }
-  return builder
+  return selection.updatePath === undefined ? builder : makeUpdatingTargetBuilder(builder, selection.updatePath)
 }
 
 const constructSelectedTarget = (builder: any): unknown =>
@@ -514,10 +621,24 @@ 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 (selection.updatePath !== undefined) {
+    if (!Topology.isCombinedTarget(result) || result.update.path !== selection.updatePath) {
+      throw new Error(`Machine target updating "${selection.updatePath}" must return target construction .update(...)`)
+    }
+  } else if (Topology.isCombinedTarget(result)) {
+    throw new Error("Machine combined target requires an updating owner declaration")
+  }
   if (result === undefined) return
-  const resultPath = typeof result === "object" && result !== null && hasProperty(result, "path") &&
-      typeof result.path === "string"
-    ? result.path
+  const target = Topology.isCombinedTarget(result) ? result.target : result
+  const resultPath = typeof target === "object" && target !== null && hasProperty(target, "path") &&
+      typeof target.path === "string"
+    ? target.path
     : undefined
   const selectedNode = selection.path === undefined ? undefined : stateNodes.byPath.get(selection.path)
   const acceptsDescendant = (selection.scope === "local" || selection.scope === "branch") &&
@@ -544,6 +665,26 @@ const runCapturedBranch = (
   const resolverContext = { ...context }
   if (branch.selection.kind === "none") delete resolverContext.target
   else resolverContext.target = selectedTarget
+  if (branch.selection.kind === "update") {
+    const ownerPath = branch.selection.path!
+    delete resolverContext.target
+    resolverContext.current = context.ancestors[ownerPath] ?? context.state
+    resolverContext.owner = getSelectionBuilder(
+      context.target,
+      makeStateUpdateSelection(ownerPath, branch.selection.scope === "local" ? "local" : "branch"),
+      stateNodes,
+      source
+    )
+  } else if (branch.selection.updatePath !== undefined) {
+    const ownerPath = branch.selection.updatePath
+    resolverContext.current = context.ancestors[ownerPath]
+    resolverContext.owner = getSelectionBuilder(
+      context.target,
+      makeStateUpdateSelection(ownerPath, "branch"),
+      stateNodes,
+      source
+    )
+  }
   if (branch.declinable === true) resolverContext.decline = Topology.makeDeclined
   const resolved = branch.resolve(resolverContext, enqueue)
   if (Topology.isDeclined(resolved)) {
@@ -556,6 +697,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
@@ -590,6 +734,9 @@ const captureNamedBranches = (
     if (!Topology.isTargetSelection(target)) {
       throw new Error(`Machine transition branch "${key}" must select exactly one target`)
     }
+    if (target.updatePath !== undefined) {
+      throw new Error(`Machine transition branch "${key}" cannot declare an updating target`)
+    }
     if (title !== undefined && (typeof title !== "string" || title.length === 0)) {
       throw new Error(`Machine transition branch "${key}" title must be a non-empty string`)
     }
@@ -738,7 +885,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,15 +895,16 @@ const captureTransition = (
           type: "branch" as const,
           key: branch.key,
           title: branch.title,
-          target: branch.selection.path,
-          selection: transitionTargetSelection(branch.selection)
+          target: topologyTargetPath(branch.selection),
+          selection: transitionTargetSelection(branch.selection),
+          updates: selectionUpdates(branch.selection)
         })
       ),
       evaluate,
       transition: (context: Record<string, any>, enqueue: unknown) => evaluate(context, enqueue).result
     }
   }
-  const branch = captureDefinitionBranch(transition, selector, path, trigger)
+  const branch = captureDefinitionBranch(transition, selector, stateNodes, path, trigger)
   const evaluate = (context: Record<string, any>, enqueue: unknown) => ({
     result: runCapturedBranch(branch, context, enqueue, stateNodes, path),
     branchIndex: 0,
@@ -763,11 +913,12 @@ 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,
-      selection: transitionTargetSelection(branch.selection)
+      target: topologyTargetPath(branch.selection),
+      selection: transitionTargetSelection(branch.selection),
+      updates: selectionUpdates(branch.selection)
     }],
     evaluate,
     transition: (context: Record<string, any>, enqueue: unknown) => evaluate(context, enqueue).result
@@ -974,8 +1125,18 @@ const withFrom = <Method extends (value: unknown, ...args: ReadonlyArray<any>) =
   method: Method,
   kind: FromMethodKind,
   valued: boolean
-): Method & { readonly from: (...args: ReadonlyArray<any>) => unknown } => {
-  Object.defineProperty(method, "from", {
+): {
+  readonly decoded?: Method
+  readonly from: (...args: ReadonlyArray<any>) => unknown
+} => {
+  const builder: Record<string, unknown> = {}
+  if (valued) {
+    Object.defineProperty(builder, "decoded", {
+      value: method,
+      enumerable: false
+    })
+  }
+  Object.defineProperty(builder, "from", {
     value: (...args: ReadonlyArray<any>) => {
       if (!valued) {
         return method(undefined, ...args)
@@ -987,7 +1148,10 @@ const withFrom = <Method extends (value: unknown, ...args: ReadonlyArray<any>) =
     },
     enumerable: false
   })
-  return method as Method & { readonly from: (...args: ReadonlyArray<any>) => unknown }
+  return builder as {
+    readonly decoded?: Method
+    readonly from: (...args: ReadonlyArray<any>) => unknown
+  }
 }
 
 const withInitial = <Builder extends object>(
@@ -1470,13 +1634,13 @@ const makeInitialSelector = (stateNodes: Machine.StateNodes): unknown => {
 const getInitialSelectionBuilder = (
   initialBuilder: Record<string, any>,
   selection: Topology.TargetSelection
-): (...args: ReadonlyArray<any>) => unknown => {
+): Record<string, any> => {
   const path = selection.path
   if (path === undefined || path.includes(".")) {
     throw new Error("Machine initial target must select one top-level state")
   }
   const builder = initialBuilder[path]
-  if (typeof builder !== "function") {
+  if (typeof builder !== "object" || builder === null || typeof builder.from !== "function") {
     throw new Error(`Machine could not construct selected initial state "${path}"`)
   }
   return builder
@@ -1489,7 +1653,7 @@ const captureInitialBranch = (
 ): {
   readonly selection: Topology.TargetSelection
   readonly resolve?: (context: any) => unknown
-  readonly builder: (...args: ReadonlyArray<any>) => unknown
+  readonly builder: Record<string, any>
 } => {
   if (typeof definition !== "function") {
     throw new Error("Machine initial definition must be a target-first callback")