@typeonce/effect-machine 0.7.0 → 0.9.0

package/src/internal/machine/activities.ts

@@ -4,8 +4,7 @@
  * @since 0.4.0
  */
 
-/** @internal */
-export const ActivityMetadataTypeId: unique symbol = Symbol.for("effect/Machine/ActivityMetadata")
+import * as Duration from "effect/Duration"
 
 /** @internal */
 export type StaticActivityMetadata =
@@ -21,8 +20,7 @@ export type StaticActivityMetadata =
   }
   | {
     readonly type: "timer"
-    readonly duration: string
-    readonly event: string
+    readonly duration: string | "dynamic"
   }
   | {
     readonly type: "machine"
@@ -33,20 +31,10 @@ export type StaticActivityMetadata =
   }
 
 /** @internal */
-export type ActivityDefinition<Source extends string = string> =
-  | ({
-    readonly source: Source
-    readonly id: string
-  } & StaticActivityMetadata)
-  | {
-    readonly source: Source
-    readonly type: "dynamic"
-  }
-
-interface ActivityDescriptor {
+export type ActivityDefinition<Source extends string = string> = {
+  readonly source: Source
   readonly id: string
-  readonly [ActivityMetadataTypeId]: StaticActivityMetadata
-}
+} & StaticActivityMetadata
 
 interface InspectableMachine {
   readonly handlers: unknown
@@ -62,31 +50,60 @@ const isObject = (value: unknown): value is object =>
 
 const getProperty = (value: unknown, key: PropertyKey): unknown => isObject(value) ? Reflect.get(value, key) : undefined
 
-const hasActivityMetadata = (value: unknown): value is ActivityDescriptor =>
-  isObject(value) && typeof getProperty(value, "id") === "string" &&
-  isObject(getProperty(value, ActivityMetadataTypeId))
-
 const appendStaticDefinition = (
   definitions: Array<ActivityDefinition>,
   source: string,
   descriptor: unknown
 ): void => {
-  if (!hasActivityMetadata(descriptor)) {
+  if (!isObject(descriptor)) return
+  const child = getProperty(descriptor, "child")
+  if (isObject(child)) {
+    const id = getProperty(child, "id")
+    if (typeof id !== "string") return
+    const machine = getProperty(child, "machine")
+    const machineId = getProperty(machine, "id")
+    definitions.push({
+      source,
+      id,
+      type: "machine",
+      child: { id, machineId: typeof machineId === "string" ? machineId : null }
+    })
     return
   }
-  definitions.push({
-    source,
-    id: descriptor.id,
-    ...descriptor[ActivityMetadataTypeId]
-  })
+  const id = getProperty(descriptor, "id")
+  if (typeof id !== "string") return
+  if (Reflect.has(descriptor, "effect")) {
+    definitions.push({
+      source,
+      id,
+      type: "effect",
+      outcomes: {
+        success: "dynamic",
+        failure: Reflect.has(descriptor, "onFailure") ? "dynamic" : "none"
+      }
+    })
+    return
+  }
+  if (Reflect.has(descriptor, "after")) {
+    const after = getProperty(descriptor, "after")
+    definitions.push({
+      source,
+      id,
+      type: "timer",
+      duration: typeof after === "function" ? "dynamic" : Duration.format(Duration.fromInputUnsafe(after as any))
+    })
+    return
+  }
+  if (Reflect.has(descriptor, "logic")) {
+    definitions.push({ source, id, type: "process" })
+  }
 }
 
 /**
  * Collects state-owned activity descriptions without executing user code.
  *
- * Function-valued invoke definitions depend on an entry context and are
- * therefore represented as dynamic. Static descriptors are returned in state
- * definition order and descriptor array order.
+ * Source factories are inspected without execution. Static descriptors are
+ * returned in state definition order and descriptor array order.
  *
  * @internal
  */
@@ -94,9 +111,7 @@ export const activityDefinitions = (machine: InspectableMachine): ReadonlyArray<
   const definitions: Array<ActivityDefinition> = []
   for (const node of machine.stateNodes.byPath.values()) {
     const invoke = getProperty(getProperty(machine.handlers, node.path), "invoke")
-    if (typeof invoke === "function") {
-      definitions.push({ source: node.path, type: "dynamic" })
-    } else if (Array.isArray(invoke)) {
+    if (Array.isArray(invoke)) {
       for (const descriptor of invoke) {
         appendStaticDefinition(definitions, node.path, descriptor)
       }

package/src/internal/machine/atom.ts

@@ -120,7 +120,7 @@ const startMachineAtomEffect = <
 ): Effect.Effect<
   Machine.MachineRef<
     Machine.Machine.Snapshot<States>,
-    Machine.Machine.EventOf<InputEvents>,
+    Machine.Machine.EventInputOf<InputEvents>,
     MachineRuntimeError<E, R>,
     Output
   >,
@@ -431,6 +431,13 @@ type SnapshotIdentifier<State> = SnapshotNode<State> extends infer Node ?
   Node extends { readonly path: infer Path extends string } ? Path : never
   : never
 
+type ValuedSnapshotIdentifier<State> = SnapshotNode<State> extends infer Node ?
+  Node extends { readonly path: infer Path extends string; readonly value: infer Value } ?
+    [Value] extends [undefined] ? never
+    : Path
+  : never
+  : never
+
 type SnapshotValueByIdentifier<State, Path extends SnapshotIdentifier<State>> = SnapshotNode<State> extends infer Node ?
   Node extends { readonly path: Path; readonly value: infer Value } ? Value : never
   : never
@@ -443,7 +450,7 @@ type ChildState<Child extends Machine.ChildMachine.Any> = RefState<Machine.Child
 
 const selectValueByPath = <
   State extends Machine.Machine.AtomicSnapshot<string, unknown>,
-  Path extends SnapshotIdentifier<State>
+  Path extends ValuedSnapshotIdentifier<State>
 >(
   snapshot: State,
   path: Path
@@ -467,7 +474,7 @@ export const select = <
   Error,
   Output,
   StartError,
-  const Path extends SnapshotIdentifier<State>
+  const Path extends ValuedSnapshotIdentifier<State>
 >(
   self: MachineAtom<State, Event, Error, Output, StartError>,
   path: Path
@@ -498,7 +505,7 @@ export const selectSnapshot = <
 export const selectChild = <
   Child extends Machine.ChildMachine.Any,
   StartError,
-  const Path extends SnapshotIdentifier<ChildState<Child>>
+  const Path extends ValuedSnapshotIdentifier<ChildState<Child>>
 >(
   self: ChildMachineAtom<Child, StartError>,
   path: Path
@@ -578,7 +585,7 @@ type EnsureMachineExecutable<M extends Machine.Machine.Any> = IsAny<Machine.Mach
 
 type ResumedMachineAtomOf<M extends Machine.Machine.Any, RuntimeError> = MachineAtom<
   Machine.Machine.Snapshot<Machine.Machine.States<M>>,
-  Machine.Machine.InputEvent<M>,
+  Machine.Machine.EventInput<Machine.Machine.InputEvent<M>>,
   MachineRuntimeError<Machine.Machine.Error<M>, Machine.Machine.Services<M>>,
   Machine.Machine.Output<M>,
   Machine.MachineSchemaDecodeError | RuntimeError
@@ -628,7 +635,7 @@ export const make: {
     ...args: [...Machine.Machine.InputArgs<Input>]
   ): MachineAtom<
     Machine.Machine.Snapshot<States>,
-    Machine.Machine.EventOf<InputEvents>,
+    Machine.Machine.EventInputOf<InputEvents>,
     MachineRuntimeError<E, R>,
     Output,
     MachineStartError<InitialE, E, InitialR, R>

package/src/internal/machine/configuration.ts

@@ -84,7 +84,7 @@ const historyFromSnapshot = (
     const active = new Set<string>()
     const values = new Map<string, unknown>()
     for (const activePath of entry.active) {
-      if (active.has(activePath) || !Object.prototype.hasOwnProperty.call(entry.values, activePath)) {
+      if (active.has(activePath)) {
         throw new Error(`Machine snapshot contains invalid remembered state "${activePath}"`)
       }
       const node = getNode(machine, activePath)
@@ -96,9 +96,15 @@ const historyFromSnapshot = (
         throw new Error(`Machine snapshot contains invalid remembered value for "${activePath}"`)
       }
       active.add(activePath)
-      values.set(activePath, decodeStateValueSync(machine, node, entry.values[activePath]))
+      const hasValue = Object.prototype.hasOwnProperty.call(entry.values, activePath)
+      if (node.schema === undefined) {
+        if (hasValue) throw new Error(`Machine snapshot contains a value for structural state "${activePath}"`)
+      } else {
+        if (!hasValue) throw new Error(`Machine snapshot omits remembered value for "${activePath}"`)
+        values.set(activePath, decodeStateValueSync(machine, node, entry.values[activePath]))
+      }
     }
-    if (!active.has(historyNode.parent) || Object.keys(entry.values).length !== active.size) {
+    if (!active.has(historyNode.parent) || Object.keys(entry.values).length !== values.size) {
       throw new Error(`Machine snapshot contains incomplete history record "${path}"`)
     }
     history.set(path, {
@@ -138,7 +144,6 @@ const historyFromSnapshotEffect = Effect.fnUntraced(function*(
       const node = machine.stateNodes.byPath.get(activePath)
       if (
         active.has(activePath) || node === undefined || node.type === "history" || node.type === "choice" ||
-        !Object.prototype.hasOwnProperty.call(entry.values, activePath) ||
         !(isPathInSubtree(activePath, historyNode.parent) ||
           getPathToRoot(machine, historyNode.parent).includes(activePath))
       ) {
@@ -152,15 +157,39 @@ const historyFromSnapshotEffect = Effect.fnUntraced(function*(
         )
       }
       active.add(activePath)
-      values.set(
-        activePath,
-        yield* decodeBoundary(machine, getStateNodeSchema(node), entry.values[activePath], {
-          boundary: "history",
-          state: activePath
-        })
-      )
+      const hasValue = Object.prototype.hasOwnProperty.call(entry.values, activePath)
+      if (node.schema === undefined) {
+        if (hasValue) {
+          return yield* Effect.fail(
+            new MachineSchemaDecodeError({
+              machineId: machine.id,
+              boundary: "history",
+              state: activePath,
+              cause: Cause.die(new Error(`Machine snapshot contains a value for structural state "${activePath}"`))
+            })
+          )
+        }
+      } else {
+        if (!hasValue) {
+          return yield* Effect.fail(
+            new MachineSchemaDecodeError({
+              machineId: machine.id,
+              boundary: "history",
+              state: activePath,
+              cause: Cause.die(new Error(`Machine snapshot omits remembered value for "${activePath}"`))
+            })
+          )
+        }
+        values.set(
+          activePath,
+          yield* decodeBoundary(machine, getStateNodeSchema(node), entry.values[activePath], {
+            boundary: "history",
+            state: activePath
+          })
+        )
+      }
     }
-    if (!active.has(historyNode.parent) || Object.keys(entry.values).length !== active.size) {
+    if (!active.has(historyNode.parent) || Object.keys(entry.values).length !== values.size) {
       return yield* Effect.fail(
         new MachineSchemaDecodeError({
           machineId: machine.id,
@@ -212,7 +241,7 @@ const historyToSnapshot = (
     entries[path] = {
       mode: record.mode,
       active,
-      values: Object.fromEntries(active.map((path) => [path, record.values.get(path)]))
+      values: Object.fromEntries(record.values)
     }
   }
   return entries
@@ -329,7 +358,9 @@ export const getParentValues = (
   const paths = getPathToRoot(machine, path)
   for (let index = 0; index < paths.length - 1; index++) {
     const parent = paths[index]!
-    parents[parent] = getActiveValue(configuration, parent)
+    if (configuration.values.has(parent)) {
+      parents[parent] = configuration.values.get(parent)
+    }
   }
   return parents
 }
@@ -340,7 +371,7 @@ export const getParentValue = (
   path: string
 ): unknown => {
   const parent = getNode(machine, path).parent
-  return parent === undefined ? undefined : getActiveValue(configuration, parent)
+  return parent === undefined ? undefined : configuration.values.get(parent)
 }
 
 export const getInitialEntryPaths = (
@@ -368,7 +399,7 @@ export const snapshotFromPath = <const States extends Machine.StateSchemas>(
   const node = getNode(machine, path)
   const snapshot: Record<string, unknown> = {
     path,
-    value: getActiveValue(configuration, path)
+    value: configuration.values.get(path)
   }
   if (node.type === "compound") {
     const child = node.children.find((child) => configuration.active.has(child))
@@ -438,9 +469,14 @@ export const configurationFromSnapshot = (
 
   const visit = (current: Machine.AtomicSnapshot<string, unknown>): void => {
     const node = getNode(machine, String(current.path))
-    const value = decodeStateValueSync(machine, node, current.value)
     active.add(node.path)
-    values.set(node.path, value)
+    if (node.schema === undefined) {
+      if (current.value !== undefined) {
+        throw new Error(`Machine structural snapshot "${node.path}" cannot contain a value`)
+      }
+    } else {
+      values.set(node.path, decodeStateValueSync(machine, node, current.value))
+    }
     if (node.type === "compound") {
       if (!hasProperty(current, "state") || !isSnapshot(current.state)) {
         throw new Error(`Machine expected compound snapshot "${node.path}" to include an active child state`)
@@ -520,9 +556,14 @@ export const configurationFromSnapshotEffect = Effect.fnUntraced(function*(
     current: Machine.AtomicSnapshot<string, unknown>
   ) {
     const node = getNode(machine, String(current.path))
-    const value = yield* decodeStateValue(machine, node, current.value)
     active.add(node.path)
-    values.set(node.path, value)
+    if (node.schema === undefined) {
+      if (current.value !== undefined) {
+        throw new Error(`Machine structural snapshot "${node.path}" cannot contain a value`)
+      }
+    } else {
+      values.set(node.path, yield* decodeStateValue(machine, node, current.value))
+    }
     if (node.type === "compound") {
       if (!hasProperty(current, "state") || !isSnapshot(current.state)) {
         throw new Error(`Machine expected compound snapshot "${node.path}" to include an active child state`)
@@ -645,7 +686,9 @@ export const captureHistory = (
     }
     const values = new Map<string, unknown>()
     for (const path of active) {
-      values.set(path, getActiveValue(current, path))
+      if (current.values.has(path)) {
+        values.set(path, current.values.get(path))
+      }
     }
     history.set(node.path, {
       mode,
@@ -722,6 +765,15 @@ export const configurationFromTargetPathEffect = Effect.fnUntraced(function*(
   for (const currentPath of paths) {
     const currentNode = getNode(machine, currentPath)
     active.add(currentPath)
+    if (currentNode.schema === undefined) {
+      const supplied = currentPath === node.path ?
+        value
+        : providedValues !== undefined && hasOwn(providedValues, currentPath) ?
+        providedValues[currentPath]
+        : undefined
+      if (supplied !== undefined) throw new Error(`Machine structural target "${currentPath}" cannot contain a value`)
+      continue
+    }
     if (currentPath === node.path) {
       values.set(currentPath, yield* decodeStateValue(machine, currentNode, value))
     } else if (providedValues !== undefined && hasOwn(providedValues, currentPath)) {
@@ -783,6 +835,12 @@ export const configurationFromTargetSnapshotEffect = Effect.fnUntraced(function*
   for (const ancestor of paths.slice(0, -1)) {
     const node = getNode(machine, ancestor)
     active.add(ancestor)
+    if (node.schema === undefined) {
+      if (providedValues !== undefined && hasOwn(providedValues, ancestor)) {
+        throw new Error(`Machine structural target "${ancestor}" cannot contain a value`)
+      }
+      continue
+    }
     if (providedValues !== undefined && hasOwn(providedValues, ancestor)) {
       values.set(ancestor, yield* decodeStateValue(machine, node, providedValues[ancestor]))
     } else if (current.values.has(ancestor)) {
@@ -816,6 +874,9 @@ export const configurationFromTargetSnapshotEffect = Effect.fnUntraced(function*
             if (!isPathInSubtree(providedPath, child)) continue
             const providedNode = getNode(machine, providedPath)
             active.add(providedPath)
+            if (providedNode.schema === undefined) {
+              throw new Error(`Machine structural target "${providedPath}" cannot contain a value`)
+            }
             values.set(providedPath, yield* decodeStateValue(machine, providedNode, providedValue))
           }
         }
@@ -885,6 +946,15 @@ const configurationFromTargetPathSync = (
   for (const currentPath of paths) {
     const currentNode = getNode(machine, currentPath)
     active.add(currentPath)
+    if (currentNode.schema === undefined) {
+      const supplied = currentPath === node.path ?
+        value
+        : providedValues !== undefined && hasOwn(providedValues, currentPath) ?
+        providedValues[currentPath]
+        : undefined
+      if (supplied !== undefined) throw new Error(`Machine structural target "${currentPath}" cannot contain a value`)
+      continue
+    }
     if (currentPath === node.path) {
       values.set(currentPath, decodeStateValueSync(machine, currentNode, value))
     } else if (providedValues !== undefined && hasOwn(providedValues, currentPath)) {
@@ -932,6 +1002,12 @@ const configurationFromTargetSnapshotSync = (
   for (const ancestor of paths.slice(0, -1)) {
     const node = getNode(machine, ancestor)
     active.add(ancestor)
+    if (node.schema === undefined) {
+      if (providedValues !== undefined && hasOwn(providedValues, ancestor)) {
+        throw new Error(`Machine structural target "${ancestor}" cannot contain a value`)
+      }
+      continue
+    }
     if (providedValues !== undefined && hasOwn(providedValues, ancestor)) {
       values.set(ancestor, decodeStateValueSync(machine, node, providedValues[ancestor]))
     } else if (current.values.has(ancestor)) {
@@ -960,6 +1036,9 @@ const configurationFromTargetSnapshotSync = (
           if (!isPathInSubtree(providedPath, child)) continue
           const providedNode = getNode(machine, providedPath)
           active.add(providedPath)
+          if (providedNode.schema === undefined) {
+            throw new Error(`Machine structural target "${providedPath}" cannot contain a value`)
+          }
           values.set(providedPath, decodeStateValueSync(machine, providedNode, providedValue))
         }
       }
@@ -1098,7 +1177,7 @@ export const resolveFinalOutputEffect: <
 ) {
   const node = getNode(machine, path)
   const output = getStateConfigByPath(machine, path)?.output?.({
-    state: getActiveValue(configuration, path),
+    state: configuration.values.get(path),
     parent: getParentValue(machine, configuration, path),
     parents: getParentValues(machine, configuration, path),
     event,
@@ -1251,7 +1330,7 @@ const resolveFinalOutputSync = <const Events extends ReadonlyArray<Machine.Tagge
 ): unknown => {
   const node = getNode(machine, path)
   const output = getStateConfigByPath(machine, path)?.output?.({
-    state: getActiveValue(configuration, path),
+    state: configuration.values.get(path),
     parent: getParentValue(machine, configuration, path),
     parents: getParentValues(machine, configuration, path),
     event,

package/src/internal/machine/executionPlan.ts

@@ -21,6 +21,7 @@ import {
   validateInitialConfiguration
 } from "./configuration.js"
 import { InfiniteTransitionError } from "./errors.js"
+import * as InvocationEvent from "./invocationEvent.js"
 import {
   broadenTransitionBoundary,
   type EvaluatedTransition,
@@ -100,6 +101,12 @@ const compileIndexedExecutionDescriptor = (
     if (node.type === "choice" || node.type === "history") {
       return undefined
     }
+    // Structural active states deliberately use the generic semantic
+    // reference until the indexed value table represents absent values as an
+    // explicit capability rather than an `undefined` slot.
+    if (node.schema === undefined) {
+      return undefined
+    }
     if (node.type === "atomic" || node.type === "final") {
       leafPaths.push(node.path)
     }
@@ -769,6 +776,34 @@ const planIndexedState = (
   input: unknown,
   retainMicrosteps: boolean
 ): ExecutionMacrostep<OwnedIndexedState> => {
+  if (InvocationEvent.isInvocationEvent(input)) {
+    // Invocation lifecycle transitions retain the generic planner as their
+    // semantic reference. Ordinary machine events and initialization stay on
+    // the indexed representation; only the private lifecycle macrostep crosses
+    // the representation boundary.
+    const planned = planConfiguration(
+      machine as any,
+      activeConfigurationFromIndexedState(descriptor, configuration),
+      input
+    )
+    return {
+      next: ownedIndexedStateFromActive(descriptor, planned.next),
+      commands: planned.commands,
+      emittedEvents: planned.emittedEvents,
+      microsteps: planned.microsteps.map((step) => ({
+        next: ownedIndexedStateFromActive(descriptor, step.next),
+        event: step.event,
+        commands: step.commands,
+        raisedEvents: step.raisedEvents,
+        emittedEvents: step.emittedEvents,
+        exitPaths: step.exitPaths,
+        entryPaths: step.entryPaths,
+        changed: step.changed
+      })),
+      done: planned.done,
+      output: planned.output
+    }
+  }
   const decoded = decodeEventSync(machine, input)
   if (descriptor.flat) {
     return planIndexedFlatState(machine, descriptor, configuration, decoded, retainMicrosteps)