@typeonce/effect-machine 0.31.2 → 0.32.0

package/src/internal/machine/runtime.ts

@@ -18,37 +18,26 @@ import * as Scope from "effect/Scope"
 import * as Stream from "effect/Stream"
 import * as SynchronizedRef from "effect/SynchronizedRef"
 import type * as Take from "effect/Take"
+import type { RuntimeOutcome as PublicRuntimeOutcome, RuntimeSnapshot as PublicRuntimeSnapshot } from "../../Machine.js"
 import type { ChildMachine, Inspection, Machine as MachineDefinition, MachineTarget } from "../../Machine.js"
+import {
+  type ChildDescriptor,
+  type ChildEntry,
+  type ChildKey,
+  type ChildObserver,
+  type ChildRegistry,
+  type ChildSelector,
+  matchesChild,
+  offerChildObservation,
+  registerChild,
+  selectRegistryChild,
+  takeChildObservations,
+  unregisterChild
+} from "./childRegistry.js"
 import { ChildAlreadyExistsError, StoppedError } from "./errors.js"
 import * as InspectionRuntime from "./inspectionRuntime.js"
 import { ChildMachineLogicTypeId } from "./symbols.js"
 
-type ChildDescriptor = {
-  readonly id: string
-  readonly machine: object
-}
-
-type ChildEntry =
-  | {
-    readonly _tag: "Starting"
-    readonly token: symbol
-    readonly ownerKey?: string
-    readonly ownerPath?: string
-    ownerActive?: boolean
-  }
-  | {
-    readonly _tag: "Started"
-    readonly token: symbol
-    readonly descriptor: ChildDescriptor | undefined
-    readonly ref: MachineRef<any, any, any, any>
-    readonly ownerKey?: string
-    readonly ownerPath?: string
-    ownerActive?: boolean
-  }
-
-type ChildSelector = string | ChildDescriptor
-type ChildKey = string | symbol
-
 /** @internal */
 export const activeSnapshotObserver: unique symbol = Symbol.for("effect/Machine/activeSnapshotObserver")
 
@@ -131,134 +120,7 @@ type InspectedOffer<Event> = (
   deferred?: Deferred.Deferred<AcknowledgedDelivery<unknown>, unknown>
 ) => Effect.Effect<void, StoppedError>
 
-type ChildObservation = Option.Option<MachineRef<any, any, any, any>>
-type ChildObservationBatch = [ChildObservation, ...Array<ChildObservation>]
-
-interface ChildObserver {
-  readonly child: ChildSelector
-  readonly id: string
-  values: ChildObservationBatch | undefined
-  waiter: Deferred.Deferred<void> | undefined
-}
-
-const offerChildObservation = (
-  observer: ChildObserver,
-  value: ChildObservation
-): void => {
-  if (observer.values === undefined) {
-    observer.values = [value]
-  } else {
-    observer.values.push(value)
-  }
-  if (observer.waiter !== undefined) {
-    const waiter = observer.waiter
-    observer.waiter = undefined
-    Deferred.doneUnsafe(waiter, Effect.void)
-  }
-}
-
-const takeChildObservations = (
-  observer: ChildObserver
-): Effect.Effect<ChildObservationBatch> =>
-  Effect.suspend(() => {
-    if (observer.values !== undefined) {
-      const values = observer.values
-      observer.values = undefined
-      return Effect.succeed(values)
-    }
-    const waiter = Deferred.makeUnsafe<void>()
-    observer.waiter = waiter
-    return Deferred.await(waiter).pipe(Effect.andThen(takeChildObservations(observer)))
-  })
-
-interface ChildRegistry {
-  closed: boolean
-  readonly children: Map<ChildKey, ChildEntry>
-  observers: Set<ChildObserver> | undefined
-  scope: Scope.Closeable | undefined
-}
-
-const matchesChild = (
-  entry: ChildEntry,
-  child: ChildSelector
-): entry is Extract<ChildEntry, { readonly _tag: "Started" }> =>
-  entry._tag === "Started" && (typeof child === "string" || (
-    entry.descriptor !== undefined &&
-    entry.descriptor.id === child.id &&
-    entry.descriptor.machine === child.machine
-  ))
-
-const selectRegistryChild = (
-  registry: ChildRegistry,
-  id: string,
-  child: ChildSelector
-): ChildObservation => {
-  if (registry.closed) return Option.none()
-  const entry = registry.children.get(id)
-  return entry !== undefined && matchesChild(entry, child) ? Option.some(entry.ref) : Option.none()
-}
-
-const publishRegistryChange = (registry: ChildRegistry): void => {
-  if (registry.observers === undefined) return
-  for (const observer of registry.observers) {
-    offerChildObservation(observer, selectRegistryChild(registry, observer.id, observer.child))
-  }
-}
-
-const unregisterChild = (registry: ChildRegistry, key: ChildKey, token: symbol): void => {
-  const entry = registry.children.get(key)
-  if (entry === undefined || entry.token !== token) return
-  registry.children.delete(key)
-  if (typeof key === "string") publishRegistryChange(registry)
-}
-
-const registerChild = (
-  registry: ChildRegistry,
-  key: ChildKey,
-  token: symbol,
-  ref: MachineRef<any, any, any, any>,
-  descriptor: ChildDescriptor | undefined
-): boolean => {
-  const entry = registry.children.get(key)
-  if (registry.closed || entry === undefined || entry._tag !== "Starting" || entry.token !== token) {
-    return false
-  }
-  registry.children.delete(key)
-  const started: ChildEntry = entry.ownerKey === undefined
-    ? { _tag: "Started", token, descriptor, ref }
-    : {
-      _tag: "Started",
-      token,
-      descriptor,
-      ref,
-      ownerKey: entry.ownerKey,
-      ownerPath: entry.ownerPath!,
-      ownerActive: entry.ownerActive === true
-    }
-  registry.children.set(key, started)
-  if (typeof key === "string") publishRegistryChange(registry)
-  return true
-}
-
-export type RuntimeSnapshot<State, Error = never, Output = never> =
-  | {
-    readonly status: "active"
-    readonly state: State
-  }
-  | {
-    readonly status: "done"
-    readonly state: State
-    readonly output: Output
-  }
-  | {
-    readonly status: "error"
-    readonly state: State
-    readonly cause: Cause.Cause<Error>
-  }
-  | {
-    readonly status: "stopped"
-    readonly state: State
-  }
+export type RuntimeSnapshot<State, Error = never, Output = never> = PublicRuntimeSnapshot<State, Error, Output>
 
 interface VersionedSnapshot<State, Error, Output> {
   readonly revision: number
@@ -274,38 +136,7 @@ type VersionedSnapshotBatch<State, Error, Output> = [
   ...Array<VersionedSnapshot<State, Error, Output>>
 ]
 
-export type RuntimeOutcome<State, Error = never, Output = never> =
-  | {
-    readonly _tag: "Done"
-    readonly output: Output
-    readonly snapshot: Extract<RuntimeSnapshot<State, Error, Output>, { readonly status: "done" }>
-  }
-  | {
-    readonly _tag: "Failure"
-    readonly error: Error
-    readonly cause: Cause.Cause<Error>
-    readonly snapshot: Extract<RuntimeSnapshot<State, Error, Output>, { readonly status: "error" }>
-  }
-  | {
-    readonly _tag: "Defect"
-    readonly defect: unknown
-    readonly cause: Cause.Cause<Error>
-    readonly snapshot: Extract<RuntimeSnapshot<State, Error, Output>, { readonly status: "error" }>
-  }
-  | {
-    readonly _tag: "Interrupted"
-    readonly cause: Cause.Cause<Error>
-    readonly snapshot: Extract<RuntimeSnapshot<State, Error, Output>, { readonly status: "error" }>
-  }
-  | {
-    readonly _tag: "Cause"
-    readonly cause: Cause.Cause<Error>
-    readonly snapshot: Extract<RuntimeSnapshot<State, Error, Output>, { readonly status: "error" }>
-  }
-  | {
-    readonly _tag: "Stopped"
-    readonly snapshot: Extract<RuntimeSnapshot<State, Error, Output>, { readonly status: "stopped" }>
-  }
+export type RuntimeOutcome<State, Error = never, Output = never> = PublicRuntimeOutcome<State, Error, Output>
 
 export interface MachineRef<out State, in Event, out Error = never, out Output = never, out Emitted = never> {
   readonly id: string

package/src/internal/machine/serialization.ts

@@ -29,6 +29,7 @@ import { getNode, getStateNodeSchema } from "./topology.js"
 
 const EncodedSnapshotSchema = Schema.Struct({
   _tag: Schema.Literal("MachineSnapshot"),
+  version: Schema.Literal(2),
   active: Schema.Array(Schema.Struct({
     path: Schema.String,
     value: Schema.optionalKey(Schema.Json)
@@ -206,6 +207,16 @@ const failEncodeCause = (
   machine: Machine.Any,
   cause: Cause.Cause<unknown>
 ): Effect.Effect<never, MachineSchemaEncodeError> => {
+  if (Cause.hasInterrupts(cause)) {
+    return Effect.failCause(
+      Cause.map(cause, (error) =>
+        error instanceof MachineSchemaEncodeError ? error : new MachineSchemaEncodeError({
+          machineId: machine.id,
+          boundary: "configuration",
+          cause: Cause.fail(error)
+        }))
+    )
+  }
   const error = Cause.findErrorOption(cause)
   return Option.isSome(error) && error.value instanceof MachineSchemaEncodeError
     ? Effect.fail(error.value)
@@ -222,6 +233,16 @@ const failDecodeCause = (
   machine: Machine.Any,
   cause: Cause.Cause<unknown>
 ): Effect.Effect<never, MachineSchemaDecodeError> => {
+  if (Cause.hasInterrupts(cause)) {
+    return Effect.failCause(
+      Cause.map(cause, (error) =>
+        error instanceof MachineSchemaDecodeError ? error : new MachineSchemaDecodeError({
+          machineId: machine.id,
+          boundary: "configuration",
+          cause: Cause.fail(error)
+        }))
+    )
+  }
   const error = Cause.findErrorOption(cause)
   return Option.isSome(error) && error.value instanceof MachineSchemaDecodeError
     ? Effect.fail(error.value)
@@ -392,6 +413,7 @@ export const encodeSnapshot = (
 
     const encoded: Machine.EncodedSnapshot = {
       _tag: "MachineSnapshot" as const,
+      version: 2,
       active,
       ...(completed.length === 0 ? {} : { completed }),
       ...(Object.keys(history).length === 0 ? {} : { history })

package/src/internal/machine/stateDefinition.ts

@@ -18,7 +18,7 @@ export type AllowedStateNodeProperty<Kind extends StateNodeKind> = (typeof State
 
 export type AllowedPseudoStateAnnotationProperty = (typeof PseudoStateAnnotationProperties)[number]
 
-export type StateDefinitionBoundary = "Machine.state" | "Machine.states" | "Machine.make"
+export type StateDefinitionBoundary = "Machine.state" | "Machine.make"
 
 const hasOwn = (value: object, key: PropertyKey): boolean => Object.prototype.hasOwnProperty.call(value, key)
 
@@ -192,13 +192,14 @@ const validateStateTree = (
   boundary: StateDefinitionBoundary,
   states: unknown,
   parent: string,
-  allowPseudoStates: boolean
+  allowPseudoStates: boolean,
+  root = false
 ): void => {
   const treePath = parent === "" ? "<root>" : parent
   assertPlainRecord(boundary, treePath, states, "state trees")
 
   for (const key of Reflect.ownKeys(states)) {
-    const path = validateStateKey(boundary, parent, key)
+    const path = root && key === "" ? "" : validateStateKey(boundary, parent, key)
     const node = states[key]
 
     // Effect schemas have their own runtime properties. They are complete
@@ -358,3 +359,35 @@ const captureStateTree = (states: Readonly<Record<string, unknown>>): Readonly<R
 /** Captures caller-owned structural containers while preserving schema identity. */
 export const captureStateDefinitions = <States>(states: States): States =>
   captureStateTree(states as Readonly<Record<string, unknown>>) as States
+
+/** Root capture keeps descriptor helpers out of the compiled topology. */
+export const captureRoot = (input: unknown, tag = ""): unknown => {
+  if (Schema.isSchema(input)) return input
+  if (typeof input !== "object" || input === null) return input
+  if (
+    "~effect/Machine/State" in input && input["~effect/Machine/State"] === "~effect/Machine/State" && "node" in input
+  ) {
+    return input.node
+  }
+  const config = input as Readonly<Record<string, unknown>>
+  const copy: Record<string, unknown> = { ...config }
+  if (hasOwn(config, "fields")) {
+    if (hasOwn(config, "schema")) fail("Machine.state", tag, "declare fields or schema, not both")
+    assertPlainRecord("Machine.state", tag, config.fields, "state fields")
+    if (hasOwn(config.fields, "_tag")) fail("Machine.state", tag, "state fields cannot declare _tag")
+    copy.schema = Schema.TaggedStruct(tag, config.fields as Schema.Struct.Fields)
+    delete copy.fields
+  }
+  if (hasOwn(config, "states")) {
+    assertPlainRecord("Machine.state", tag, config.states, "child states")
+    const children: Record<string, unknown> = Object.create(null)
+    for (const key of Reflect.ownKeys(config.states)) {
+      validateStateKey("Machine.state", tag, key)
+      children[key as string] = captureRoot(config.states[key], key as string)
+    }
+    copy.states = children
+  }
+  if (tag !== "") return copy
+  validateStateTree("Machine.state", { "": copy }, "", false, true)
+  return captureStateDefinitions({ "": copy })[""]
+}