@typeonce/effect-machine 0.7.0 → 0.8.0

package/src/internal/machine/atom.ts

@@ -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

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

@@ -100,6 +100,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)
     }

package/src/internal/machine/invocation.ts

@@ -109,7 +109,7 @@ export const startAll = (
     .filter((path) => configuration.active.has(path))
     .flatMap((path) =>
       resolve(Configuration.getStateConfigByPath(machine, path), {
-        state: Configuration.getActiveValue(configuration, path),
+        state: configuration.values.get(path),
         parent: Configuration.getParentValue(machine, configuration, path),
         parents: Configuration.getParentValues(machine, configuration, path),
         event

package/src/internal/machine/machine.ts

@@ -278,10 +278,14 @@ type FromMethodKind = "leaf" | "nested"
 
 const withFrom = <Method extends (value: unknown, ...args: ReadonlyArray<any>) => unknown>(
   method: Method,
-  kind: FromMethodKind
+  kind: FromMethodKind,
+  valued: boolean
 ): Method & { readonly from: (...args: ReadonlyArray<any>) => unknown } => {
   Object.defineProperty(method, "from", {
     value: (...args: ReadonlyArray<any>) => {
+      if (!valued) {
+        return method(undefined, ...args)
+      }
       const omitted = args.length === 0 || (kind === "nested" && args.length === 1 && typeof args[0] === "function")
       const input = omitted ? {} : args[0]
       const rest = omitted ? args : args.slice(1)
@@ -312,7 +316,8 @@ const makeSnapshotBuilder = (
     builder[key] = withFrom(
       (value: unknown, selector?: (builder: unknown) => unknown) =>
         makeSnapshotForNode(definition, key, value, selector, options),
-      node.states === undefined ? "leaf" : "nested"
+      node.states === undefined ? "leaf" : "nested",
+      node.schema !== undefined
     )
   }
   return builder
@@ -339,14 +344,18 @@ const makeParallelSnapshotBuilder = (
     }
     const path = options.prefix === "" ? key : `${options.prefix}.${key}`
     const node = Topology.getStateNodeDefinition(path, definition)
-    builder[key] = withFrom((value: unknown, selector?: (builder: unknown) => unknown) => {
-      const nextRegions: Record<string, unknown> = {}
-      for (const regionKey of Object.keys(regions)) {
-        nextRegions[regionKey] = regions[regionKey]
-      }
-      nextRegions[key] = makeSnapshotForNode(definition, key, value, selector, options)
-      return makeParallelSnapshotBuilder(states, options, nextRegions)
-    }, node.states === undefined ? "leaf" : "nested")
+    builder[key] = withFrom(
+      (value: unknown, selector?: (builder: unknown) => unknown) => {
+        const nextRegions: Record<string, unknown> = {}
+        for (const regionKey of Object.keys(regions)) {
+          nextRegions[regionKey] = regions[regionKey]
+        }
+        nextRegions[key] = makeSnapshotForNode(definition, key, value, selector, options)
+        return makeParallelSnapshotBuilder(states, options, nextRegions)
+      },
+      node.states === undefined ? "leaf" : "nested",
+      node.schema !== undefined
+    )
   }
   return builder
 }
@@ -525,13 +534,25 @@ const makeLocalTargetChildBuilder = (
       builder[child.key] = () => Topology.makeChoiceTarget(child.path, parent.path, values)
       continue
     }
-    builder[child.key] = withFrom((value: unknown, selector?: (builder: unknown) => unknown) => {
-      if (child.type === "atomic" || child.type === "final") {
-        return makeTargetWithValues(child.path, value, values)
-      }
-      if (child.type === "parallel") {
-        if (source !== child.path && !source.startsWith(`${child.path}.`)) {
-          return makeParallelTarget(states, child, value, selector, values)
+    builder[child.key] = withFrom(
+      (value: unknown, selector?: (builder: unknown) => unknown) => {
+        if (child.type === "atomic" || child.type === "final") {
+          return makeTargetWithValues(child.path, value, values)
+        }
+        if (child.type === "parallel") {
+          if (source !== child.path && !source.startsWith(`${child.path}.`)) {
+            return makeParallelTarget(states, child, value, selector, values)
+          }
+          if (selector === undefined) {
+            throw new Error(`Machine expected target "${child.path}" builder to provide an active child state`)
+          }
+          return selector(makeLocalTargetChildBuilder(
+            states,
+            stateNodes,
+            child.path,
+            child.schema === undefined ? values : extendTargetValues(values, child.path, value),
+            source
+          ))
         }
         if (selector === undefined) {
           throw new Error(`Machine expected target "${child.path}" builder to provide an active child state`)
@@ -540,21 +561,13 @@ const makeLocalTargetChildBuilder = (
           states,
           stateNodes,
           child.path,
-          extendTargetValues(values, child.path, value),
+          child.schema === undefined ? values : extendTargetValues(values, child.path, value),
           source
         ))
-      }
-      if (selector === undefined) {
-        throw new Error(`Machine expected target "${child.path}" builder to provide an active child state`)
-      }
-      return selector(makeLocalTargetChildBuilder(
-        states,
-        stateNodes,
-        child.path,
-        extendTargetValues(values, child.path, value),
-        source
-      ))
-    }, child.type === "atomic" || child.type === "final" ? "leaf" : "nested")
+      },
+      child.type === "atomic" || child.type === "final" ? "leaf" : "nested",
+      child.schema !== undefined
+    )
   }
   return builder
 }
@@ -569,12 +582,19 @@ const makeLocalTargetBuilder = (
     return {}
   }
   const builder = makeLocalTargetChildBuilder(states, stateNodes, scope, undefined, source) as Record<string, unknown>
-  builder.with = withFrom((value: unknown, selector?: (builder: unknown) => unknown) => {
-    if (selector === undefined) {
-      throw new Error(`Machine expected target "${scope}" builder to provide an active child state`)
-    }
-    return selector(makeLocalTargetChildBuilder(states, stateNodes, scope, { [scope]: value }, source))
-  }, "nested")
+  const scopeNode = getTargetBuilderNode(stateNodes, scope)
+  if (scopeNode.schema !== undefined) {
+    builder.with = withFrom(
+      (value: unknown, selector?: (builder: unknown) => unknown) => {
+        if (selector === undefined) {
+          throw new Error(`Machine expected target "${scope}" builder to provide an active child state`)
+        }
+        return selector(makeLocalTargetChildBuilder(states, stateNodes, scope, { [scope]: value }, source))
+      },
+      "nested",
+      true
+    )
+  }
   return builder
 }
 
@@ -610,12 +630,31 @@ const makeBranchTargetNodeBuilder = (
 ): unknown => {
   const node = getTargetBuilderNode(stateNodes, path)
   if (node.type === "atomic" || node.type === "final") {
-    return withFrom((value: unknown) => makeTargetWithValues(node.path, value, values), "leaf")
+    return withFrom(
+      (value: unknown) => makeTargetWithValues(node.path, value, values),
+      "leaf",
+      node.schema !== undefined
+    )
   }
-  const builder = withFrom((value: unknown, selector?: (builder: unknown) => unknown) => {
-    if (node.type === "parallel") {
-      if (source !== node.path && !source.startsWith(`${node.path}.`)) {
-        return makeParallelTarget(states, node, value, selector, values)
+  const builder = withFrom(
+    (value: unknown, selector?: (builder: unknown) => unknown) => {
+      if (node.type === "parallel") {
+        if (source !== node.path && !source.startsWith(`${node.path}.`)) {
+          return makeParallelTarget(states, node, value, selector, values)
+        }
+        if (selector === undefined) {
+          throw new Error(`Machine expected target "${node.path}" builder to provide an active child state`)
+        }
+        const nextBuilder: Record<string, unknown> = {}
+        addBranchTargetChildren(
+          nextBuilder,
+          states,
+          stateNodes,
+          node.path,
+          node.schema === undefined ? values : extendTargetValues(values, node.path, value),
+          source
+        )
+        return selector(nextBuilder)
       }
       if (selector === undefined) {
         throw new Error(`Machine expected target "${node.path}" builder to provide an active child state`)
@@ -626,25 +665,14 @@ const makeBranchTargetNodeBuilder = (
         states,
         stateNodes,
         node.path,
-        extendTargetValues(values, node.path, value),
+        node.schema === undefined ? values : extendTargetValues(values, node.path, value),
         source
       )
       return selector(nextBuilder)
-    }
-    if (selector === undefined) {
-      throw new Error(`Machine expected target "${node.path}" builder to provide an active child state`)
-    }
-    const nextBuilder: Record<string, unknown> = {}
-    addBranchTargetChildren(
-      nextBuilder,
-      states,
-      stateNodes,
-      node.path,
-      extendTargetValues(values, node.path, value),
-      source
-    )
-    return selector(nextBuilder)
-  }, "nested") as unknown as Record<string, unknown>
+    },
+    "nested",
+    node.schema !== undefined
+  ) as unknown as Record<string, unknown>
   if (node.type !== "parallel" || source === node.path || source.startsWith(`${node.path}.`)) {
     addBranchTargetChildren(builder, states, stateNodes, node.path, values, source)
   }