@typeonce/effect-machine 0.16.0 → 0.18.0

package/dist/internal/machine/machine.js

@@ -16,8 +16,10 @@ import * as Topology from "./topology.js";
 export { ChildAlreadyExistsError, InfiniteTransitionError, MachineSchemaDecodeError, MachineSchemaEncodeError, ProcessLocalError, StartupError, StoppedError } from "./errors.js";
 export { ChildMachineLogicTypeId, InitialEventTypeId, SnapshotBuilderStateTypeId } from "./symbols.js";
 const TypeId = "~effect/Machine";
+const ParentTypeId = "~effect/Machine/Parent";
 export const InvokeTypeId = Symbol.for("effect/Machine/Invoke");
 export const TransitionTypeId = Symbol.for("effect/Machine/Transition");
+const InvokeBuilderDescriptorTypeId = Symbol("effect/Machine/InvokeBuilderDescriptor");
 const ChildMachineTypeId = "~effect/Machine/ChildMachine";
 const Proto = {
     ...Inspectable.BaseProto,
@@ -29,14 +31,13 @@ const Proto = {
         };
     }
 };
-const makeBoundInvoke = (config) => config;
 const makeWithHandlers = (self, handlers) => {
     const machine = Object.create(Proto);
     machine.states = self.states;
     machine.events = self.events;
     machine.internalEvents = self.internalEvents;
     machine.emittedEvents = self.emittedEvents;
-    machine.parentEvents = self.parentEvents;
+    machine.parent = self.parent;
     machine.input = self.input;
     machine.id = self.id;
     machine.initial = self.initial;
@@ -44,16 +45,134 @@ const makeWithHandlers = (self, handlers) => {
     machine.stateNodes = self.stateNodes;
     machine.makeTargetBuilder = self.makeTargetBuilder;
     machine.handlers = handlers;
-    machine.invoke = makeBoundInvoke;
     Protocol.copyProtocol(self, machine);
     return machine;
 };
+const TransitionBuilderDescriptorTypeId = Symbol("effect/Machine/TransitionBuilderDescriptor");
+const InitialBuilderDescriptorTypeId = Symbol("effect/Machine/InitialBuilderDescriptor");
+const plainTargetSelection = (selection) => selection.kind === "none"
+    ? Topology.noneTargetSelection
+    : Topology.makeTargetSelection(selection.kind, selection.path, selection.scope);
+const transitionOptions = (options) => {
+    const configuration = typeof options === "object" && options !== null
+        ? options
+        : {};
+    return {
+        reenter: configuration.reenter === true,
+        declinable: configuration.declinable === true
+    };
+};
+const makeDirectTransitionDescriptor = (selection, resolve, options) => {
+    const shared = {
+        [TransitionBuilderDescriptorTypeId]: TransitionBuilderDescriptorTypeId,
+        type: "direct",
+        selection: plainTargetSelection(selection),
+        ...transitionOptions(options)
+    };
+    return resolve === undefined
+        ? Object.freeze(shared)
+        : Object.freeze({ ...shared, resolve });
+};
+const decorateTransitionSelection = (selection) => Object.freeze({
+    ...selection,
+    resolve: (resolve, options) => makeDirectTransitionDescriptor(selection, resolve, options),
+    reenter: () => makeDirectTransitionDescriptor(selection, undefined, { reenter: true })
+});
+const noneTransitionSelection = decorateTransitionSelection(Topology.noneTargetSelection);
+const makeInitialBuilderDescriptor = (selection, resolve) => Object.freeze({
+    [InitialBuilderDescriptorTypeId]: InitialBuilderDescriptorTypeId,
+    selection: plainTargetSelection(selection),
+    resolve
+});
+const decorateInitialSelection = (selection) => Object.freeze({
+    ...selection,
+    resolve: (resolve) => makeInitialBuilderDescriptor(selection, resolve)
+});
+const decorateInitialSelectorNode = (node) => {
+    if (Topology.isTargetSelection(node))
+        return decorateInitialSelection(node);
+    if (typeof node === "function") {
+        const wrapped = ((...args) => decorateInitialSelection(node(...args)));
+        for (const key of Object.keys(node)) {
+            wrapped[key] = decorateInitialSelectorNode(node[key]);
+        }
+        return Object.freeze(wrapped);
+    }
+    if (typeof node === "object" && node !== null) {
+        const wrapped = {};
+        for (const key of Object.keys(node)) {
+            wrapped[key] = decorateInitialSelectorNode(node[key]);
+        }
+        return Object.freeze(wrapped);
+    }
+    return node;
+};
+const decorateTransitionSelectorNode = (node) => {
+    if (Topology.isTargetSelection(node)) {
+        return node === Topology.noneTargetSelection ? noneTransitionSelection : decorateTransitionSelection(node);
+    }
+    if (typeof node === "function") {
+        const wrapped = ((...args) => decorateTransitionSelection(node(...args)));
+        for (const key of Object.keys(node)) {
+            wrapped[key] = decorateTransitionSelectorNode(node[key]);
+        }
+        return Object.freeze(wrapped);
+    }
+    if (typeof node === "object" && node !== null) {
+        const wrapped = {};
+        for (const key of Object.keys(node)) {
+            wrapped[key] = decorateTransitionSelectorNode(node[key]);
+        }
+        return Object.freeze(wrapped);
+    }
+    return node;
+};
+const makeTransitionSelector = (stateNodes, source) => {
+    const selector = {
+        ...decorateTransitionSelectorNode(makeTargetSelector(stateNodes, source))
+    };
+    selector.branches = (declarations) => Object.freeze({
+        resolve: (resolve, options) => Object.freeze({
+            [TransitionBuilderDescriptorTypeId]: TransitionBuilderDescriptorTypeId,
+            type: "branches",
+            declarations,
+            resolve,
+            ...transitionOptions(options)
+        })
+    });
+    return Object.freeze(selector);
+};
+const normalizeTransitionBuilder = (transition, stateNodes, path) => {
+    const result = transition(makeTransitionSelector(stateNodes, path));
+    if (Topology.isTargetSelection(result)) {
+        const selection = plainTargetSelection(result);
+        return { target: () => selection };
+    }
+    if (!hasProperty(result, TransitionBuilderDescriptorTypeId))
+        return result;
+    const descriptor = result;
+    if (descriptor.type === "branches") {
+        return {
+            branches: () => descriptor.declarations,
+            resolve: descriptor.resolve,
+            reenter: descriptor.reenter,
+            declinable: descriptor.declinable
+        };
+    }
+    return {
+        target: () => descriptor.selection,
+        resolve: descriptor.resolve,
+        reenter: descriptor.reenter,
+        declinable: descriptor.declinable
+    };
+};
 const transitionTargetSelection = (selection) => Object.freeze({
     path: selection.path,
     kind: selection.kind,
     scope: selection.scope
 });
 const makeSelectionMethod = (kind, path, scope) => () => Topology.makeTargetSelection(kind, path, scope);
+const makeSelectionValue = (kind, path, scope) => Topology.makeTargetSelection(kind, path, scope);
 const addSelectionChildren = (builder, stateNodes, parent, scope) => {
     for (const node of stateNodes.byPath.values()) {
         if (node.parent !== parent || node.type === "history")
@@ -67,7 +186,7 @@ const makeSelectionNode = (stateNodes, path, scope) => {
     const method = makeSelectionMethod(kind, path, scope);
     if (node.type !== "atomic" && node.type !== "final" && node.type !== "choice" && node.type !== "history") {
         Object.defineProperty(method, "initial", {
-            value: makeSelectionMethod("initial", path, scope),
+            value: makeSelectionValue("initial", path, scope),
             enumerable: true
         });
         if (scope === "local" || scope === "branch") {
@@ -82,7 +201,7 @@ const makeHistorySelectionTree = (stateNodes, parent) => {
         if (node.parent !== parent)
             continue;
         if (node.type === "history") {
-            builder[node.key] = makeSelectionMethod("history", node.path, "full");
+            builder[node.key] = makeSelectionValue("history", node.path, "full");
         }
         else if (node.type !== "choice") {
             const children = makeHistorySelectionTree(stateNodes, node.path);
@@ -107,12 +226,12 @@ const makeTargetSelector = (stateNodes, source) => {
     if (localScope !== undefined) {
         const localScopeNode = getTargetBuilderNode(stateNodes, localScope);
         if (localScopeNode.schema !== undefined) {
-            local.with = makeSelectionMethod("state", localScope, "local");
+            local.with = makeSelectionValue("state", localScope, "local");
         }
         addSelectionChildren(local, stateNodes, localScope, "local");
     }
     return {
-        none: makeSelectionMethod("none", undefined, "local"),
+        none: Topology.noneTargetSelection,
         local,
         branch,
         full,
@@ -167,7 +286,7 @@ const getSelectionBuilder = (target, selection, stateNodes, source) => {
     }
     return builder;
 };
-const constructSelectedTarget = (builder) => typeof builder === "function" ? builder() : builder.from();
+const constructSelectedTarget = (builder) => typeof builder?.from === "function" ? builder.from() : builder();
 const validateResolvedSelection = (result, selection, stateNodes) => {
     if (selection.kind === "none") {
         if (result !== undefined) {
@@ -198,7 +317,15 @@ const runCapturedBranch = (branch, context, enqueue, stateNodes, source) => {
         delete resolverContext.target;
     else
         resolverContext.target = selectedTarget;
+    if (branch.declinable === true)
+        resolverContext.decline = Topology.makeDeclined;
     const resolved = branch.resolve(resolverContext, enqueue);
+    if (Topology.isDeclined(resolved)) {
+        if (branch.declinable !== true) {
+            throw new Error(`Machine transition for state "${source}" returned decline without declaring declinable: true`);
+        }
+        return resolved;
+    }
     validateResolvedSelection(resolved, branch.selection, stateNodes);
     return resolved === undefined ? constructSelectedTarget(selectedTarget) : resolved;
 };
@@ -232,7 +359,7 @@ const captureNamedBranches = (declarations, path, trigger) => {
         if (title !== undefined && (typeof title !== "string" || title.length === 0)) {
             throw new Error(`Machine transition branch "${key}" title must be a non-empty string`);
         }
-        return Object.freeze({ key, title: title ?? key, selection: target });
+        return Object.freeze({ key, title: title ?? key, selection: plainTargetSelection(target) });
     }));
 };
 const wrapSelectedBranchBuilder = (builder, owner, branchIndex, branchKey) => {
@@ -287,13 +414,18 @@ const validateSelectedBranchResult = (result, selection, stateNodes) => {
     }
     validateResolvedSelection(result, selection, stateNodes);
 };
-const captureTransition = (transition, stateNodes, path, trigger) => {
+const captureTransition = (rawTransition, stateNodes, path, trigger) => {
+    if (typeof rawTransition !== "function") {
+        throw new Error(`Machine transition for state "${path}" on "${String(trigger)}" must be a target-first callback`);
+    }
+    const transition = normalizeTransitionBuilder(rawTransition, stateNodes, path);
     if (typeof transition !== "object" || transition === null) {
         throw new Error(`Machine transition for state "${path}" on "${String(trigger)}" must be an object`);
     }
     const definition = transition;
     const selector = makeTargetSelector(stateNodes, path);
     const reenter = definition.reenter === true;
+    const declinable = definition.declinable === true;
     if (hasProperty(definition, "branches")) {
         const branching = definition;
         if (typeof branching.branches !== "function" || typeof branching.resolve !== "function") {
@@ -306,7 +438,15 @@ const captureTransition = (transition, stateNodes, path, trigger) => {
             const resolverContext = { ...context };
             delete resolverContext.target;
             resolverContext.select = makeBranchSelectors(context, branches, owner, stateNodes, path);
+            if (declinable)
+                resolverContext.decline = Topology.makeDeclined;
             const selected = resolve(resolverContext, enqueue);
+            if (Topology.isDeclined(selected)) {
+                if (!declinable) {
+                    throw new Error(`Machine branching transition for state "${path}" on "${String(trigger)}" returned decline without declaring declinable: true`);
+                }
+                return { result: selected, branchIndex: -1, branchKey: undefined };
+            }
             if (!Topology.isSelectedBranch(selected) || selected.owner !== owner) {
                 throw new Error(`Machine branching transition for state "${path}" on "${String(trigger)}" must select one declared branch`);
             }
@@ -323,6 +463,7 @@ const captureTransition = (transition, stateNodes, path, trigger) => {
         };
         return {
             reenter,
+            declinable,
             targets: [
                 ...new Set(branches.flatMap((branch) => branch.selection.path === undefined ? [] : [branch.selection.path]))
             ],
@@ -345,6 +486,7 @@ const captureTransition = (transition, stateNodes, path, trigger) => {
     });
     return {
         reenter,
+        declinable,
         targets: branch.selection.path === undefined ? [] : [branch.selection.path],
         branches: [{
                 type: "direct",
@@ -365,18 +507,55 @@ const captureEventHandlers = (on, stateNodes, path) => {
     }
     return captured;
 };
-const captureInvokeDefinition = (invoke, stateNodes, path) => {
-    if (Array.isArray(invoke))
-        return invoke.map((item) => captureInvokeDefinition(item, stateNodes, path));
-    if (typeof invoke !== "object" || invoke === null)
-        return invoke;
-    const captured = { ...invoke };
-    for (const key of ["onElement", "onDone", "onFailure", "onSnapshot"]) {
-        if (captured[key] !== undefined) {
-            captured[key] = captureTransition(captured[key], stateNodes, path, key);
+const makeInvokeBuilder = (config, channels) => {
+    const builder = {
+        [InvokeBuilderDescriptorTypeId]: InvokeBuilderDescriptorTypeId,
+        config
+    };
+    for (const channel of channels) {
+        if (!hasProperty(config, channel)) {
+            builder[channel] = (handler) => makeInvokeBuilder({ ...config, [channel]: handler }, channels);
         }
     }
-    return captured;
+    return Object.freeze(builder);
+};
+const invokeSelector = Object.freeze({
+    effect: (id, effect) => makeInvokeBuilder({ id, effect }, ["onDone", "onFailure"]),
+    stream: (id, stream) => makeInvokeBuilder({ id, stream }, ["onElement", "onDone", "onFailure"]),
+    timer: (id, after) => makeInvokeBuilder({ id, after }, ["onDone"]),
+    logic: (id, options) => makeInvokeBuilder({ id, ...options }, ["onSnapshot", "onDone", "onFailure"]),
+    child: (child, options) => makeInvokeBuilder(options === undefined ? { child } : { child, ...options }, [
+        "onSnapshot",
+        "onDone",
+        "onFailure"
+    ])
+});
+const invokeBuilderConfig = (value, path) => {
+    if (typeof value !== "object" || value === null ||
+        !hasProperty(value, InvokeBuilderDescriptorTypeId) ||
+        value[InvokeBuilderDescriptorTypeId] !== InvokeBuilderDescriptorTypeId) {
+        throw new Error(`Machine invocation for state "${path}" must be constructed from its source selector`);
+    }
+    return value.config;
+};
+const captureInvokeDefinition = (invoke, stateNodes, path) => {
+    if (typeof invoke !== "function") {
+        throw new Error(`Machine invocation for state "${path}" must be a source-first callback`);
+    }
+    const authored = invoke(invokeSelector);
+    const definitions = Array.isArray(authored) ? authored : [authored];
+    const capturedDefinitions = definitions.map((definition) => {
+        const captured = { ...invokeBuilderConfig(definition, path) };
+        for (const key of ["onElement", "onDone", "onFailure", "onSnapshot"]) {
+            if (captured[key] !== undefined) {
+                captured[key] = captureTransition(captured[key], stateNodes, path, key);
+            }
+        }
+        return captured;
+    });
+    if (Array.isArray(authored))
+        return capturedDefinitions;
+    return capturedDefinitions[0];
 };
 const flattenHandlers = (handlers, stateNodes, states, prefix, config) => {
     for (const key of Object.keys(config)) {
@@ -750,10 +929,12 @@ const makeInitialSelector = (stateNodes) => {
     const selector = {};
     for (const node of stateNodes.byPath.values()) {
         if (node.parent === undefined && node.type !== "history" && node.type !== "choice") {
-            selector[node.key] = makeSelectionNode(stateNodes, node.path, "initial");
+            selector[node.key] = node.type === "atomic" || node.type === "final"
+                ? makeSelectionMethod("state", node.path, "initial")
+                : Object.freeze({ initial: makeSelectionValue("initial", node.path, "initial") });
         }
     }
-    return selector;
+    return Object.freeze(selector);
 };
 const getInitialSelectionBuilder = (initialBuilder, selection) => {
     const path = selection.path;
@@ -766,12 +947,32 @@ const getInitialSelectionBuilder = (initialBuilder, selection) => {
     }
     return builder;
 };
-const captureInitialBranch = (branch, selector, initialBuilder) => {
-    const captured = captureDefinitionBranch(branch, selector, "<machine>", "initial");
-    if (captured.selection.kind !== "state" && captured.selection.kind !== "initial") {
+const captureInitialBranch = (definition, stateNodes, initialBuilder) => {
+    if (typeof definition !== "function") {
+        throw new Error("Machine initial definition must be a target-first callback");
+    }
+    const result = definition(decorateInitialSelectorNode(makeInitialSelector(stateNodes)));
+    let selection;
+    let resolve;
+    if (Topology.isTargetSelection(result)) {
+        selection = plainTargetSelection(result);
+    }
+    else if (hasProperty(result, InitialBuilderDescriptorTypeId)) {
+        const descriptor = result;
+        selection = descriptor.selection;
+        resolve = descriptor.resolve;
+    }
+    else {
+        throw new Error("Machine initial definition must select exactly one target");
+    }
+    if (selection.kind !== "state" && selection.kind !== "initial") {
         throw new Error("Machine initial target must select a top-level state or its declared initial entry");
     }
-    return { ...captured, builder: getInitialSelectionBuilder(initialBuilder, captured.selection) };
+    const captured = {
+        selection,
+        builder: getInitialSelectionBuilder(initialBuilder, selection)
+    };
+    return resolve === undefined ? Object.freeze(captured) : Object.freeze({ ...captured, resolve });
 };
 const validateInitialSelection = (result, selection) => {
     if (typeof result !== "object" || result === null || !hasProperty(result, "path") || result.path !== selection.path) {
@@ -782,17 +983,13 @@ const validateInitialSelection = (result, selection) => {
     }
 };
 const compileInitial = (definition, states, stateNodes) => {
-    if (typeof definition !== "object" || definition === null) {
-        throw new Error("Machine initial definition must be an object");
-    }
-    const selector = makeInitialSelector(stateNodes);
     const initialBuilder = makeSnapshotBuilder(states, { mode: "initial", prefix: "" });
-    const branch = captureInitialBranch(definition, selector, initialBuilder);
+    const branch = captureInitialBranch(definition, stateNodes, initialBuilder);
     return {
         initial: (input) => {
             const result = branch.resolve === undefined
-                ? branch.builder()
-                : branch.resolve({ input, target: branch.builder }, undefined);
+                ? constructSelectedTarget(branch.builder)
+                : branch.resolve({ input, target: branch.builder });
             validateInitialSelection(result, branch.selection);
             return result;
         },
@@ -828,7 +1025,7 @@ export const make = ((config) => {
     self.events = config.events;
     self.internalEvents = config.internalEvents ?? Protocol.makeEventProtocol("internal", []);
     self.emittedEvents = config.emittedEvents ?? Protocol.makeEventProtocol("emitted", []);
-    self.parentEvents = config.parentEvents ?? Protocol.makeEventProtocol("public", []);
+    self.parent = config.parent;
     self.input = config.input;
     self.id = config.id;
     self.stateNodes = Topology.compileStateNodes(config.states);
@@ -838,7 +1035,6 @@ export const make = ((config) => {
     self.makeTargetBuilder = makeTargetBuilder(config.states, self.stateNodes);
     self.handlers = Object.create(null);
     self.handle = makeHandle(self);
-    self.invoke = makeBoundInvoke;
     Protocol.setProtocol(self);
     return self;
 });
@@ -846,6 +1042,14 @@ const flattenEventProtocolInputs = (kind, inputs) => inputs.flatMap((input) => P
     ? Protocol.eventProtocolSchemas(input)
     : [input]);
 export const events = (...inputs) => Protocol.makeEventProtocol("public", flattenEventProtocolInputs("public", inputs));
+const makeParent = (mode, events) => {
+    if (!Protocol.isEventProtocol(events, "public")) {
+        throw new Error("Machine parent declarations require a protocol created with Machine.events");
+    }
+    return Object.freeze({ [ParentTypeId]: ParentTypeId, mode, events });
+};
+export const parent = (events) => makeParent("required", events);
+export const optionalParent = (events) => makeParent("optional", events);
 export const internalEvents = (...inputs) => Protocol.makeEventProtocol("internal", flattenEventProtocolInputs("internal", inputs));
 export const emittedEvents = (...inputs) => Protocol.makeEventProtocol("emitted", flattenEventProtocolInputs("emitted", inputs));
 export const encodeSnapshot = Serialization.encodeSnapshot;