@typeonce/effect-machine 0.11.0 → 0.13.0

package/dist/internal/machine/planner.js

@@ -6,27 +6,28 @@
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import { getTargetBuilder, makeCollector } from "./command.js";
-import { captureHistory, compareDocumentOrder, completeConfigurationEffect, completeConfigurationSync, configurationFromHistoryRecord, getActiveLeafPathFrom, getActiveLeafPaths, getHistoryRecord, getInitialEntryPaths, getLeafPath, getParentValue, getParentValues, getPathToRoot, getRootPath, isActiveFinalConfiguration, isDescendantOf, isPathInSubtree, normalizeConfiguration, normalizeConfigurationEffect, normalizeConfigurationSync, normalizeTargetConfigurationSync, pathDepth, snapshotFromConfiguration, snapshotFromConfigurationAtPath, validateInitialConfiguration } from "./configuration.js";
+import { captureHistory, compareDocumentOrder, completeConfigurationEffect, completeConfigurationSync, configurationFromHistoryRecord, configurationFromInitialTargetSync, getActiveLeafPathFrom, getActiveLeafPaths, getHistoryRecord, getInitialEntryPaths, getLeafPath, getParentValue, getParentValues, getPathToRoot, getRootPath, isActiveFinalConfiguration, isDescendantOf, isPathInSubtree, normalizeConfiguration, normalizeConfigurationEffect, normalizeConfigurationSync, normalizeTargetConfigurationSync, pathDepth, snapshotFromConfiguration, snapshotFromConfigurationAtPath, validateInitialConfiguration } from "./configuration.js";
 import { InfiniteTransitionError, MachineSchemaDecodeError, StartupError, StoppedError } from "./errors.js";
+import { getStateInitializeValues, makeStateInitializeBuilder } from "./initialization.js";
 import * as InvocationEvent from "./invocationEvent.js";
 import { decodeEventSync, decodeInputSync, decodeStateValueSync } from "./protocol.js";
 import { InitialEventTypeId } from "./symbols.js";
-import { getNode, isChoiceTarget, isHistoryTarget, isNoTarget, isSnapshot, isTarget, makeChoiceTarget, makeTarget, TargetSnapshotTypeId } from "./topology.js";
-const rootActorScopes = new WeakMap();
-const machineActorScopes = new WeakMap();
-export const withActorScope = (machine, actorScope) => {
+import { getNode, isChoiceTarget, isHistoryTarget, isInitialTarget, isNoTarget, isSnapshot, isTarget, makeChoiceTarget, makeTarget, TargetSnapshotTypeId } from "./topology.js";
+const rootMachineReferences = new WeakMap();
+const scopedMachineReferences = new WeakMap();
+export const withMachineReferences = (machine, machineReferences) => {
     const scoped = Object.create(machine);
-    machineActorScopes.set(scoped, { self: actorScope.self, parent: actorScope.parent });
+    scopedMachineReferences.set(scoped, { self: machineReferences.self, parent: machineReferences.parent });
     return scoped;
 };
-const getActorContext = (machine, configuration) => {
-    const scope = configuration.actorScope;
+const resolveMachineReferences = (machine, configuration) => {
+    const scope = configuration.machineReferences;
     if (scope !== undefined)
         return scope;
-    const machineScope = machineActorScopes.get(machine);
+    const machineScope = scopedMachineReferences.get(machine);
     if (machineScope !== undefined)
         return machineScope;
-    const cached = rootActorScopes.get(machine);
+    const cached = rootMachineReferences.get(machine);
     if (cached !== undefined)
         return cached;
     const self = {
@@ -35,7 +36,7 @@ const getActorContext = (machine, configuration) => {
         send: () => Effect.fail(new StoppedError())
     };
     const root = { self, parent: undefined };
-    rootActorScopes.set(machine, root);
+    rootMachineReferences.set(machine, root);
     return root;
 };
 export const normalizeTransition = (transition) => {
@@ -94,6 +95,7 @@ const completeHistoryConfiguration = (machine, configuration, event) => {
     const commands = [];
     const raisedEvents = [];
     const emittedEvents = [];
+    const transitions = [];
     let changed = true;
     while (changed) {
         changed = false;
@@ -109,22 +111,55 @@ const completeHistoryConfiguration = (machine, configuration, event) => {
                     values,
                     outputs: configuration.outputs,
                     history: configuration.history,
-                    actorScope: configuration.actorScope
+                    machineReferences: configuration.machineReferences
                 };
+                if (child.type === "choice") {
+                    const choice = resolveChoiceTarget(machine, current, makeChoiceTarget(child.path, path, Object.fromEntries(values)), event);
+                    let next = current;
+                    for (const routed of [choice.target, ...choice.additionalTargets]) {
+                        if (routed === undefined || isHistoryTarget(routed)) {
+                            throw new Error(`Machine initial choice "${child.path}" must resolve to an active state target`);
+                        }
+                        const resolved = isInitialTarget(routed)
+                            ? resolveInitialTarget(machine, next, routed, event)
+                            : undefined;
+                        next = normalizeTargetConfigurationSync(machine, next, (resolved?.target ?? routed));
+                        if (resolved !== undefined) {
+                            commands.push(...resolved.commands);
+                            raisedEvents.push(...resolved.raisedEvents);
+                            emittedEvents.push(...resolved.emittedEvents);
+                            transitions.push(...resolved.transitions);
+                        }
+                    }
+                    active.clear();
+                    values.clear();
+                    for (const activePath of next.active)
+                        active.add(activePath);
+                    for (const [valuePath, stateValue] of next.values)
+                        values.set(valuePath, stateValue);
+                    commands.push(...choice.commands);
+                    raisedEvents.push(...choice.raisedEvents);
+                    emittedEvents.push(...choice.emittedEvents);
+                    transitions.push(...choice.transitions);
+                    changed = true;
+                    continue;
+                }
                 active.add(child.path);
                 if (child.schema !== undefined) {
-                    const initializer = machine.handlers[path]?.initial;
+                    const initializer = machine.handlers[path]?.initialize;
                     if (initializer === undefined) {
                         throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`);
                     }
                     const initialized = collectStateInitializer(machine, initializer, {
-                        ...getActorContext(machine, current),
+                        ...resolveMachineReferences(machine, current),
                         state: current.values.get(path),
                         containingState: getParentValue(machine, current, path),
                         ancestors: getParentValues(machine, current, path),
-                        event
+                        event,
+                        builder: makeStateInitializeBuilder(machine, path)
                     });
-                    values.set(child.path, decodeStateValueSync(machine, child, initialized.value));
+                    const initializedValues = getStateInitializeValues(path, initialized.value);
+                    values.set(child.path, decodeStateValueSync(machine, child, initializedValues[child.key]));
                     commands.push(...initialized.commands);
                     raisedEvents.push(...initialized.raisedEvents);
                     emittedEvents.push(...initialized.emittedEvents);
@@ -140,31 +175,32 @@ const completeHistoryConfiguration = (machine, configuration, event) => {
                         values,
                         outputs: configuration.outputs,
                         history: configuration.history,
-                        actorScope: configuration.actorScope
+                        machineReferences: configuration.machineReferences
                     };
-                    const initializer = valuedMissing.length === 0 ? undefined : machine.handlers[path]?.initial;
+                    const initializer = valuedMissing.length === 0 ? undefined : machine.handlers[path]?.initialize;
                     if (valuedMissing.length > 0 && initializer === undefined) {
                         throw new Error(`Machine shallow history requires an initial value implementation for state "${path}"`);
                     }
                     const initialized = initializer === undefined ? undefined : collectStateInitializer(machine, initializer, {
-                        ...getActorContext(machine, current),
+                        ...resolveMachineReferences(machine, current),
                         state: current.values.get(path),
                         containingState: getParentValue(machine, current, path),
                         ancestors: getParentValues(machine, current, path),
-                        event
+                        event,
+                        builder: makeStateInitializeBuilder(machine, path)
                     });
-                    if (initialized !== undefined && (typeof initialized.value !== "object" || initialized.value === null)) {
-                        throw new Error(`Machine parallel state initializer for "${path}" must return its region values`);
-                    }
+                    const initializedValues = initialized === undefined
+                        ? undefined
+                        : getStateInitializeValues(path, initialized.value);
                     for (const childPath of missing) {
                         const child = getNode(machine, childPath);
                         active.add(child.path);
                         if (child.schema !== undefined) {
                             if (initialized === undefined ||
-                                !Object.prototype.hasOwnProperty.call(initialized.value, child.key)) {
+                                initializedValues === undefined || !Object.prototype.hasOwnProperty.call(initializedValues, child.key)) {
                                 throw new Error(`Machine parallel state initializer for "${path}" must return region "${child.key}"`);
                             }
-                            values.set(child.path, decodeStateValueSync(machine, child, initialized.value[child.key]));
+                            values.set(child.path, decodeStateValueSync(machine, child, initializedValues[child.key]));
                         }
                     }
                     if (initialized !== undefined) {
@@ -186,10 +222,26 @@ const completeHistoryConfiguration = (machine, configuration, event) => {
         },
         commands,
         raisedEvents,
-        emittedEvents
+        emittedEvents,
+        transitions
     };
 };
-const resolveHistoryTarget = (machine, configuration, target, event) => {
+export function resolveInitialTarget(machine, configuration, target, event) {
+    const partial = configurationFromInitialTargetSync(machine, configuration, target);
+    const completed = completeHistoryConfiguration(machine, partial, event);
+    const snapshot = snapshotFromConfigurationAtPath(machine, completed.configuration, target.path);
+    return {
+        target: makeTarget(target.path, snapshot.value, {
+            snapshot: snapshot,
+            values: Object.fromEntries(completed.configuration.values)
+        }),
+        commands: completed.commands,
+        raisedEvents: completed.raisedEvents,
+        emittedEvents: completed.emittedEvents,
+        transitions: completed.transitions
+    };
+}
+function resolveHistoryTarget(machine, configuration, target, event) {
     const node = getNode(machine, target.path);
     if (node.type !== "history" || node.parent !== target.parent) {
         throw new Error(`Machine expected history target "${target.path}" to resolve to its declared parent`);
@@ -211,7 +263,7 @@ const resolveHistoryTarget = (machine, configuration, target, event) => {
             commands: completed.commands,
             raisedEvents: completed.raisedEvents,
             emittedEvents: completed.emittedEvents,
-            transitions: []
+            transitions: completed.transitions
         };
     }
     const key = node.key;
@@ -262,7 +314,7 @@ const resolveHistoryTarget = (machine, configuration, target, event) => {
         emittedEvents: [...collected.emittedEvents, ...(choiceResolution?.emittedEvents ?? [])],
         transitions: choiceResolution?.transitions ?? []
     };
-};
+}
 const getCandidatePaths = (machine, configuration) => Array.from(configuration.active)
     .sort((left, right) => {
     const depth = pathDepth(machine, right) - pathDepth(machine, left);
@@ -304,14 +356,14 @@ export const sortEntryPaths = (machine, paths) => Array.from(new Set(paths))
     return depth === 0 ? compareDocumentOrder(machine, left, right) : depth;
 });
 const makeStateActionContext = (machine, configuration, path, event) => ({
-    ...getActorContext(machine, configuration),
+    ...resolveMachineReferences(machine, configuration),
     state: configuration.values.get(path),
     containingState: getParentValue(machine, configuration, path),
     ancestors: getParentValues(machine, configuration, path),
     event
 });
 const makeTransitionContext = (machine, configuration, path, event, snapshot) => ({
-    ...getActorContext(machine, configuration),
+    ...resolveMachineReferences(machine, configuration),
     state: configuration.values.get(path),
     containingState: getParentValue(machine, configuration, path),
     ancestors: getParentValues(machine, configuration, path),
@@ -320,7 +372,7 @@ const makeTransitionContext = (machine, configuration, path, event, snapshot) =>
     target: getTargetBuilder(machine, path)
 });
 const makeDoneContext = (machine, configuration, path, event, output, snapshot) => ({
-    ...getActorContext(machine, configuration),
+    ...resolveMachineReferences(machine, configuration),
     state: configuration.values.get(path),
     containingState: getParentValue(machine, configuration, path),
     ancestors: getParentValues(machine, configuration, path),
@@ -358,7 +410,7 @@ const selectAlwaysTransitions = (machine, configuration, event) => {
                         trigger: { type: "always" },
                         transition: always,
                         context: {
-                            ...getActorContext(machine, configuration),
+                            ...resolveMachineReferences(machine, configuration),
                             state: configuration.values.get(path),
                             containingState: getParentValue(machine, configuration, path),
                             ancestors: getParentValues(machine, configuration, path),
@@ -439,7 +491,7 @@ const selectInvocationTransition = (machine, configuration, event) => {
         return [];
     const snapshot = snapshotFromConfiguration(machine, configuration);
     const context = {
-        ...getActorContext(machine, configuration),
+        ...resolveMachineReferences(machine, configuration),
         state: configuration.values.get(event.path),
         containingState: getParentValue(machine, configuration, event.path),
         ancestors: getParentValues(machine, configuration, event.path),
@@ -563,7 +615,7 @@ const withChoiceValues = (target, values) => {
         values: { ...values, ...(target.values ?? {}) }
     });
 };
-const resolveChoiceTarget = (machine, configuration, initialTarget, event) => {
+function resolveChoiceTarget(machine, configuration, initialTarget, event) {
     const pending = [initialTarget];
     const resolvedTargets = [];
     const commands = [];
@@ -606,10 +658,10 @@ const resolveChoiceTarget = (machine, configuration, initialTarget, event) => {
                 ]),
                 outputs: configuration.outputs,
                 history: configuration.history,
-                ...(configuration.actorScope === undefined ? {} : { actorScope: configuration.actorScope })
+                ...(configuration.machineReferences === undefined ? {} : { machineReferences: configuration.machineReferences })
             };
             const collected = collectTransition(machine, choice.transition, {
-                ...getActorContext(machine, provisional),
+                ...resolveMachineReferences(machine, provisional),
                 containingState: getParentValue(machine, provisional, node.path),
                 ancestors: getParentValues(machine, provisional, node.path),
                 event,
@@ -633,7 +685,7 @@ const resolveChoiceTarget = (machine, configuration, initialTarget, event) => {
             raisedEvents.push(...collected.raisedEvents);
             emittedEvents.push(...collected.emittedEvents);
         }
-        if (!isTarget(current) && !isSnapshot(current) && !isHistoryTarget(current)) {
+        if (!isTarget(current) && !isSnapshot(current) && !isHistoryTarget(current) && !isInitialTarget(current)) {
             throw new Error("Machine choice resolver must return a concrete typed target");
         }
         resolvedTargets.push(current);
@@ -646,7 +698,7 @@ const resolveChoiceTarget = (machine, configuration, initialTarget, event) => {
         emittedEvents,
         transitions
     };
-};
+}
 const collectEvaluatedTransition = (machine, state, selection) => {
     const stateIdentifier = selection.leafPath;
     const transitionResult = collectTransition(machine, selection.transition.transition, selection.context);
@@ -658,45 +710,58 @@ const collectEvaluatedTransition = (machine, state, selection) => {
         ? undefined
         : resolveChoiceTarget(machine, state, unresolvedTarget, selection.context.event);
     const choiceResolvedTarget = choiceResolution?.target ?? unresolvedTarget;
+    const initialResolution = choiceResolvedTarget !== undefined && isInitialTarget(choiceResolvedTarget)
+        ? resolveInitialTarget(machine, state, choiceResolvedTarget, selection.context.event)
+        : undefined;
+    const routedTarget = initialResolution?.target ?? choiceResolvedTarget;
     let historyResolution;
-    const reenteredHistoryTarget = isHistoryTarget(choiceResolvedTarget) && selection.transition.reenter &&
-        state.active.has(choiceResolvedTarget.parent)
-        ? choiceResolvedTarget
+    const reenteredHistoryTarget = isHistoryTarget(routedTarget) && selection.transition.reenter &&
+        state.active.has(routedTarget.parent)
+        ? routedTarget
         : undefined;
-    if (choiceResolvedTarget !== undefined && isHistoryTarget(choiceResolvedTarget)) {
+    if (routedTarget !== undefined && isHistoryTarget(routedTarget)) {
         // A reentering transition may exit the history node's own parent. SCXML
         // history observes that same exit, so resolve against a provisional
         // capture rather than an older record (or the default).
         const provisionalBoundary = selection.transition.reenter
             ? getNode(machine, selection.sourcePath).parent
-            : getLeastCommonAncestor(machine, stateIdentifier, choiceResolvedTarget.parent);
+            : getLeastCommonAncestor(machine, stateIdentifier, routedTarget.parent);
         const provisionalExitPaths = reenteredHistoryTarget !== undefined
-            ? sortExitPaths(machine, Array.from(state.active).filter((path) => isPathInSubtree(path, choiceResolvedTarget.parent)))
+            ? sortExitPaths(machine, Array.from(state.active).filter((path) => isPathInSubtree(path, routedTarget.parent)))
             : getExitPaths(machine, state, provisionalBoundary);
-        const stateAtHistoryResolution = provisionalExitPaths.includes(choiceResolvedTarget.parent)
+        const stateAtHistoryResolution = provisionalExitPaths.includes(routedTarget.parent)
             ? captureHistory(machine, state, state, provisionalExitPaths)
             : state;
-        historyResolution = resolveHistoryTarget(machine, stateAtHistoryResolution, choiceResolvedTarget, selection.context.event);
+        historyResolution = resolveHistoryTarget(machine, stateAtHistoryResolution, routedTarget, selection.context.event);
     }
     const target = historyResolution === undefined
-        ? choiceResolvedTarget
+        ? routedTarget
         : historyResolution.target;
-    const additionalHistoryActions = [];
-    const additionalHistoryRaisedEvents = [];
-    const additionalHistoryEmittedEvents = [];
-    const additionalHistoryChoiceTransitions = [];
+    const additionalTargetActions = [];
+    const additionalTargetRaisedEvents = [];
+    const additionalTargetEmittedEvents = [];
+    const additionalTargetChoiceTransitions = [];
     const additionalChoiceTargets = [];
     for (const additionalTarget of choiceResolution?.additionalTargets ?? []) {
+        if (isInitialTarget(additionalTarget)) {
+            const resolved = resolveInitialTarget(machine, state, additionalTarget, selection.context.event);
+            additionalChoiceTargets.push(resolved.target);
+            additionalTargetActions.push(...resolved.commands);
+            additionalTargetRaisedEvents.push(...resolved.raisedEvents);
+            additionalTargetEmittedEvents.push(...resolved.emittedEvents);
+            additionalTargetChoiceTransitions.push(...resolved.transitions);
+            continue;
+        }
         if (!isHistoryTarget(additionalTarget)) {
             additionalChoiceTargets.push(additionalTarget);
             continue;
         }
         const resolved = resolveHistoryTarget(machine, state, additionalTarget, selection.context.event);
         additionalChoiceTargets.push(resolved.target);
-        additionalHistoryActions.push(...resolved.commands);
-        additionalHistoryRaisedEvents.push(...resolved.raisedEvents);
-        additionalHistoryEmittedEvents.push(...resolved.emittedEvents);
-        additionalHistoryChoiceTransitions.push(...resolved.transitions);
+        additionalTargetActions.push(...resolved.commands);
+        additionalTargetRaisedEvents.push(...resolved.raisedEvents);
+        additionalTargetEmittedEvents.push(...resolved.emittedEvents);
+        additionalTargetChoiceTransitions.push(...resolved.transitions);
     }
     const targetPath = target === undefined
         ? undefined
@@ -718,28 +783,32 @@ const collectEvaluatedTransition = (machine, state, selection) => {
             commands: [
                 ...transitionResult.commands,
                 ...(choiceResolution?.commands ?? []),
+                ...(initialResolution?.commands ?? []),
                 ...(historyResolution?.commands ?? []),
-                ...additionalHistoryActions
+                ...additionalTargetActions
             ],
             raisedEvents: [
                 ...transitionResult.raisedEvents,
                 ...(choiceResolution?.raisedEvents ?? []),
+                ...(initialResolution?.raisedEvents ?? []),
                 ...(historyResolution?.raisedEvents ?? []),
-                ...additionalHistoryRaisedEvents
+                ...additionalTargetRaisedEvents
             ],
             emittedEvents: [
                 ...transitionResult.emittedEvents,
                 ...(choiceResolution?.emittedEvents ?? []),
+                ...(initialResolution?.emittedEvents ?? []),
                 ...(historyResolution?.emittedEvents ?? []),
-                ...additionalHistoryEmittedEvents
+                ...additionalTargetEmittedEvents
             ],
             changed,
             exitPaths: [],
             entryPaths: [],
             choiceTransitions: [
                 ...(choiceResolution?.transitions ?? []),
+                ...(initialResolution?.transitions ?? []),
                 ...(historyResolution?.transitions ?? []),
-                ...additionalHistoryChoiceTransitions
+                ...additionalTargetChoiceTransitions
             ]
         };
     }
@@ -757,20 +826,23 @@ const collectEvaluatedTransition = (machine, state, selection) => {
         commands: [
             ...transitionResult.commands,
             ...(choiceResolution?.commands ?? []),
+            ...(initialResolution?.commands ?? []),
             ...(historyResolution?.commands ?? []),
-            ...additionalHistoryActions
+            ...additionalTargetActions
         ],
         raisedEvents: [
             ...transitionResult.raisedEvents,
             ...(choiceResolution?.raisedEvents ?? []),
+            ...(initialResolution?.raisedEvents ?? []),
             ...(historyResolution?.raisedEvents ?? []),
-            ...additionalHistoryRaisedEvents
+            ...additionalTargetRaisedEvents
         ],
         emittedEvents: [
             ...transitionResult.emittedEvents,
             ...(choiceResolution?.emittedEvents ?? []),
+            ...(initialResolution?.emittedEvents ?? []),
             ...(historyResolution?.emittedEvents ?? []),
-            ...additionalHistoryEmittedEvents
+            ...additionalTargetEmittedEvents
         ],
         changed,
         exitPaths: reenteredHistoryTarget !== undefined
@@ -781,8 +853,9 @@ const collectEvaluatedTransition = (machine, state, selection) => {
             : getEntryPaths(machine, stateAfterTransition, boundary),
         choiceTransitions: [
             ...(choiceResolution?.transitions ?? []),
+            ...(initialResolution?.transitions ?? []),
             ...(historyResolution?.transitions ?? []),
-            ...additionalHistoryChoiceTransitions
+            ...additionalTargetChoiceTransitions
         ]
     };
 };