@typeonce/effect-machine 0.19.1 → 0.21.0

package/src/Machine.ts

@@ -2265,7 +2265,15 @@ export declare namespace Logic {
    * @category models
    * @since 0.4.0
    */
-  export interface Spawn {
+  export interface Spawn<OwnerEvent = unknown> {
+    <const Child extends ChildMachine.Any>(
+      child: Child & ChildMachine.Executable<Child> & ChildMachine.ParentCompatibility<Child, OwnerEvent>,
+      ...options: ChildMachine.SpawnArgs<Child>
+    ): Effect.Effect<
+      ChildMachine.Ref<Child>,
+      ChildAlreadyExistsError | ChildMachine.StartError<Child>,
+      ChildMachine.StartRequirements<Child>
+    >
     <ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError = never>(
       logic: Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>
     ): Effect.Effect<
@@ -2305,7 +2313,7 @@ export declare namespace Logic {
     readonly parent: Address<unknown> | undefined
 
     /** Starts a child process owned by this scope. */
-    readonly spawn: Spawn
+    readonly spawn: Spawn<Event>
 
     /** Sends an event to a machine target or typed parent-local child address. */
     readonly sendTo: {
@@ -2345,6 +2353,7 @@ export declare namespace Logic {
 
 const ChildAddressTypeId = "~effect/Machine/ChildAddress"
 const ChildAddressCompatibilityErrorTypeId = "~effect/Machine/ChildAddressCompatibilityError"
+const ChildParentCompatibilityErrorTypeId = "~effect/Machine/ChildParentCompatibilityError"
 const ChildMachineTypeId = "~effect/Machine/ChildMachine"
 type InvokeLifecycleId = string & { readonly [ChildAddressTypeId]?: never }
 
@@ -2389,6 +2398,95 @@ export declare namespace ChildMachine {
    */
   export type Any = ChildMachine<string, Machine.Any>
 
+  /**
+   * Bound constructor for an open family of child descriptors that share one
+   * machine definition.
+   *
+   * @category models
+   * @since 0.20.0
+   */
+  export interface Family<M extends Machine.Any> {
+    <const Id extends string>(id: Id): ChildMachine<Id, M>
+  }
+
+  /**
+   * Ensures a child machine's declared owner protocol is accepted by the
+   * process that will own it.
+   *
+   * @category utility types
+   * @since 0.20.0
+   */
+  export type ParentCompatibility<Child extends Any, OwnerEvent> = Child extends ChildMachine<string, infer M> ?
+    Machine.Any extends M ? {
+        readonly [ChildParentCompatibilityErrorTypeId]: {
+          readonly child: unknown
+          readonly owner: OwnerEvent
+        }
+      }
+    : [Machine.EventOf<Machine.ParentEvents<M>>] extends [OwnerEvent] ? unknown :
+    {
+      readonly [ChildParentCompatibilityErrorTypeId]: {
+        readonly child: Machine.EventOf<Machine.ParentEvents<M>>
+        readonly owner: OwnerEvent
+      }
+    }
+    : never
+
+  /**
+   * Ensures the selected child machine has complete handlers and outputs.
+   *
+   * @category utility types
+   * @since 0.20.0
+   */
+  export type Executable<Child extends Any> = Child["machine"] extends EnsureExecutable<
+    Machine.States<Child["machine"]>,
+    Machine.UnhandledStates<Child["machine"]>,
+    Machine.OutputStates<Child["machine"]>
+  > ? unknown
+    : never
+
+  /**
+   * Startup arguments accepted while spawning a child machine.
+   *
+   * @category utility types
+   * @since 0.20.0
+   */
+  export type SpawnArgs<Child extends Any> = Machine.InputSchema<Child["machine"]> extends typeof Schema.Void ?
+    [options?: { readonly input?: never }]
+    : [options: { readonly input: Machine.Input<Child["machine"]> }]
+
+  /**
+   * Typed failures that may occur before a spawned child becomes active.
+   *
+   * @category utility types
+   * @since 0.20.0
+   */
+  export type StartError<Child extends Any> = Child extends ChildMachine<string, infer M> ?
+      | Machine.InitialError<M>
+      | Machine.Error<M>
+      | ActionError<Machine.InitialServices<M> | Machine.Services<M>>
+      | InfiniteTransitionError
+      | MachineSchemaDecodeError
+      | StartupError
+      | StoppedError
+    : never
+
+  /**
+   * Services needed to initialize a spawned child machine.
+   *
+   * @category utility types
+   * @since 0.20.0
+   */
+  export type StartRequirements<Child extends Any> = Child extends ChildMachine<string, infer M> ? Exclude<
+      ExcludeCompatibleRuntime<
+        Exclude<ExecutionServices<Machine.InitialServices<M> | Machine.Services<M>>, MachineRuntimeRequirement>,
+        Machine.Event<M>,
+        Machine.Emit<M>
+      >,
+      Scope.Scope
+    >
+    : never
+
   /**
    * Running machine reference selected by a child descriptor.
    *
@@ -2418,6 +2516,34 @@ export declare namespace ChildMachine {
     : never
 }
 
+/**
+ * Effectful operations for child machines owned directly by the current
+ * machine process.
+ *
+ * @category models
+ * @since 0.20.0
+ */
+export interface ChildOwner<OwnerEvent> {
+  /** Starts a process-owned child and returns once initialization succeeds. */
+  readonly spawn: <const Child extends ChildMachine.Any>(
+    child: Child & ChildMachine.Executable<Child> & ChildMachine.ParentCompatibility<Child, OwnerEvent>,
+    ...options: ChildMachine.SpawnArgs<Child>
+  ) => Effect.Effect<
+    ChildMachine.Ref<Child>,
+    ChildAlreadyExistsError | ChildMachine.StartError<Child>,
+    ChildMachine.StartRequirements<Child>
+  >
+
+  /** Sends an event to one active child. Missing children are ignored. */
+  readonly sendTo: <Child extends ChildMachine.Any>(
+    child: Child,
+    event: ChildMachine.Event<Child>
+  ) => Effect.Effect<void, StoppedError>
+
+  /** Stops one active child. Missing children are ignored. */
+  readonly stop: <Child extends ChildMachine.Any>(child: Child) => Effect.Effect<void>
+}
+
 /**
  * Parent-local address for a child process that can receive events.
  *
@@ -3451,9 +3577,10 @@ export declare namespace Machine {
    *
    * **Details**
    *
-   * Every branch exposes its selected target without executing its resolver.
-   * A compound local or branch target covers its descendants;
-   * `undefined` identifies an explicitly targetless branch.
+   * Every branch exposes its static selection without executing its resolver.
+   * A compound local or branch target covers its descendants. An `update`
+   * selection keeps `target` undefined and records its value owner in
+   * `selection.path`; `none` identifies an explicitly targetless branch.
    *
    * @category models
    * @since 0.4.0
@@ -4335,6 +4462,33 @@ export declare namespace Machine {
     >
   }
 
+  /**
+   * Opaque instruction that replaces one active compound or parallel state's
+   * value without changing its active descendants.
+   *
+   * @category models
+   * @since 0.21.0
+   */
+  export interface StateUpdate<
+    States extends StateSchemas,
+    StateId extends ValuedStateIdentifier<States>
+  > {
+    readonly [Topology.StateUpdateTypeId]: typeof Topology.StateUpdateTypeId
+    readonly path: StateId
+    readonly value: StateByIdentifier<States, StateId>
+  }
+
+  /** @internal */
+  type StateUpdateBuilder<
+    States extends StateSchemas,
+    StateId extends ValuedStateIdentifier<States>
+  > =
+    & ((value: StateByIdentifier<States, StateId>) => StateUpdate<States, StateId>)
+    & FromMethod<
+      readonly [input: SchemaByIdentifier<States, StateId>["~type.make.in"]],
+      StateUpdate<States, StateId>
+    >
+
   /**
    * Opaque result returned by an explicitly targetless transition.
    *
@@ -4619,6 +4773,45 @@ export declare namespace Machine {
         & SelectionTreeWithPrefix<AllStates, Children, Path, Scope, Builder>
     : SelectionMethod<Builder, Path>
 
+  /** @internal */
+  type StateUpdateSelectionForNode<
+    AllStates extends StateSchemas,
+    Node,
+    Path extends string
+  > = Node extends { readonly states: StateSchemas } ? NodeSchema<Node> extends never ? {}
+    : {
+      readonly update: SelectionValue<
+        StateUpdateBuilder<AllStates, Extract<Path, ValuedStateIdentifier<AllStates>>>,
+        Path,
+        "update"
+      >
+    }
+    : {}
+
+  /** @internal */
+  type BranchUpdateSelectionPath<
+    AllStates extends StateSchemas,
+    Node,
+    Path extends string,
+    Rest extends string
+  > =
+    & StateUpdateSelectionForNode<AllStates, Node, Path>
+    & (Node extends { readonly states: infer Children extends StateSchemas } ?
+      Rest extends `${infer Head}.${infer Tail}` ? Head extends keyof Children ? {
+            readonly [Key in Head]: BranchUpdateSelectionPath<
+              AllStates,
+              Children[Head],
+              JoinPath<Path, Head>,
+              Tail
+            >
+          }
+        : {}
+      : Rest extends keyof Children ? {
+          readonly [Key in Rest]: StateUpdateSelectionForNode<AllStates, Children[Rest], JoinPath<Path, Rest>>
+        }
+      : {}
+      : {})
+
   type FullSelectionNode<
     AllStates extends StateSchemas,
     Node,
@@ -4643,13 +4836,17 @@ export declare namespace Machine {
     Source extends StateNodeIdentifier<States>,
     Root extends string = Source extends `${infer Head}.${string}` ? Head : Source
   > = Root extends ActiveStateKey<States> ? Root extends keyof BranchTargetBuilder<States, Source> ? {
-        readonly [Key in Root]: SelectionNode<
-          States,
-          States[Key],
-          Key,
-          "branch",
-          BranchTargetBuilder<States, Source>[Key]
-        >
+        readonly [Key in Root]:
+          & SelectionNode<
+            States,
+            States[Key],
+            Key,
+            "branch",
+            BranchTargetBuilder<States, Source>[Key]
+          >
+          & (Source extends ChoiceIdentifier<States> ? {}
+            : Source extends `${Key}.${infer Rest}` ? BranchUpdateSelectionPath<States, States[Key], Key, Rest>
+            : StateUpdateSelectionForNode<States, States[Key], Key>)
       }
     : {}
     : {}
@@ -4657,14 +4854,21 @@ export declare namespace Machine {
   type LocalTargetSelector<
     States extends StateSchemas,
     Source extends StateNodeIdentifier<States>
-  > = NearestCompoundScope<States, Source> extends infer Scope extends StateIdentifier<States> ?
-    ChildrenOf<States, Scope> extends infer Children extends StateSchemas ?
-      LocalTargetBuilder<States, Source> extends infer Builder ?
-          & SelectionTreeWithPrefix<States, Children, Scope, "local", Builder>
-          & ("with" extends keyof Builder ? {
-              readonly with: SelectionValue<Builder["with"], Scope>
-            }
-            : {})
+  > = NearestCompoundScope<States, Source> extends infer Scope ? [Scope] extends [never] ? {}
+    : Scope extends StateIdentifier<States> ?
+      ChildrenOf<States, Scope> extends infer Children extends StateSchemas ?
+        LocalTargetBuilder<States, Source> extends infer Builder ?
+            & SelectionTreeWithPrefix<States, Children, Scope, "local", Builder>
+            & ("with" extends keyof Builder ? {
+                readonly with: SelectionValue<Builder["with"], Scope>
+              }
+              : {})
+            & (Source extends ChoiceIdentifier<States> ? {}
+              : Scope extends ValuedStateIdentifier<States> ? {
+                  readonly update: SelectionValue<StateUpdateBuilder<States, Scope>, Scope, "update">
+                }
+              : {})
+        : {}
       : {}
     : {}
     : {}
@@ -4705,9 +4909,9 @@ export declare namespace Machine {
   > {
     /** Handles the trigger without selecting a destination. */
     readonly none: SelectionValue<TargetBuilder<States, Source>["none"], never, "none">
-    /** Selects a destination inside the nearest active compound scope. */
+    /** Selects a destination or updates the nearest active compound scope. */
     readonly local: LocalTargetSelector<States, Source>
-    /** Selects a destination elsewhere under the currently active root. */
+    /** Selects a destination or updates a valued active ancestor under the current root. */
     readonly branch: BranchTargetSelector<States, Source>
     /** Selects a complete destination under any top-level state. */
     readonly full: FullTargetSelector<States>
@@ -4799,6 +5003,8 @@ export declare namespace Machine {
     InputEvents extends ReadonlyArray<TaggedSchema> = Events,
     ParentEvents extends ReadonlyArray<TaggedSchema> = readonly []
   > = MachineReferences<InputEvents, ParentEvents> & {
+    /** Process-owned child operations for dynamic child machine lifecycles. */
+    readonly children: ChildOwner<EventOf<InputEvents>>
     /** Value owned by the state that owns this invocation. */
     readonly state: StateByIdentifier<States, StateId>
     /** Value owned by the nearest schema-backed ancestor, when one exists. */
@@ -5115,9 +5321,9 @@ export declare namespace Machine {
    * **Details**
    *
    * Handlers return snapshots for complete state replacement, target builder
-   * results for path-safe partial transitions, or `target.none()` for an
-   * explicitly targetless transition. Raw decoded state values and `void` are
-   * not accepted at transition boundaries.
+   * results for path-safe partial transitions, state-value updates, or
+   * `target.none()` for an explicitly targetless transition. Raw decoded state
+   * values and `void` are not accepted at transition boundaries.
    *
    * @category utility types
    * @since 0.4.0
@@ -5127,11 +5333,13 @@ export declare namespace Machine {
     | Target<States, StateIdentifier<States>>
     | HistoryTarget<States, HistoryIdentifier<States>>
     | ChoiceTarget<States, ChoiceIdentifier<States>>
+    | StateUpdate<States, ValuedStateIdentifier<States>>
     | StateConstruction<
       | Snapshot<States>
       | Target<States, StateIdentifier<States>>
       | HistoryTarget<States, HistoryIdentifier<States>>
       | ChoiceTarget<States, ChoiceIdentifier<States>>
+      | StateUpdate<States, ValuedStateIdentifier<States>>
     >
     | NoTarget
 
@@ -5511,6 +5719,28 @@ export declare namespace Machine {
     | (SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined)
     | Declined
 
+  /** @internal */
+  type StateUpdateResolver<
+    Events extends ReadonlyArray<TaggedSchema>,
+    Emits extends ReadonlyArray<TaggedSchema>,
+    Context,
+    Selection
+  > = (
+    context: TransitionResolveContext<Context, Selection>,
+    enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>
+  ) => SelectedTargetResult<Selection>
+
+  /** @internal */
+  type DeclinableStateUpdateResolver<
+    Events extends ReadonlyArray<TaggedSchema>,
+    Emits extends ReadonlyArray<TaggedSchema>,
+    Context,
+    Selection
+  > = (
+    context: TransitionResolveContext<Context, Selection> & DeclineCapability,
+    enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>
+  ) => SelectedTargetResult<Selection> | Declined
+
   /** One named destination declared by a branching transition. */
   export interface TransitionBranchInput<
     Selection extends TargetSelection<any, any, any> = TargetSelection<any, any, any>
@@ -5752,6 +5982,80 @@ export declare namespace Machine {
       : {}
       : {})
 
+  /** @internal */
+  interface StateUpdateTransitionRequired<
+    States extends StateSchemas,
+    Events extends ReadonlyArray<TaggedSchema>,
+    Emits extends ReadonlyArray<TaggedSchema>,
+    StateId extends StateNodeIdentifier<States>,
+    Context,
+    Reenter extends boolean,
+    Selection extends TargetSelection<any, any, "update">
+  > {
+    (
+      resolve: StateUpdateResolver<Events, Emits, Context, Selection>,
+      options?: TransitionRequiredOptions<Reenter>
+    ): BuiltTransition<
+      States,
+      Events,
+      Emits,
+      StateId,
+      Context,
+      Reenter,
+      SelectedTargetResult<Selection>,
+      "required"
+    >
+  }
+
+  /** @internal */
+  interface StateUpdateTransitionDeclinable<
+    States extends StateSchemas,
+    Events extends ReadonlyArray<TaggedSchema>,
+    Emits extends ReadonlyArray<TaggedSchema>,
+    StateId extends StateNodeIdentifier<States>,
+    Context,
+    Reenter extends boolean,
+    Selection extends TargetSelection<any, any, "update">
+  > {
+    (
+      resolve: DeclinableStateUpdateResolver<Events, Emits, Context, Selection>,
+      options: TransitionDeclinableOptions<Reenter>
+    ): BuiltTransition<
+      States,
+      Events,
+      Emits,
+      StateId,
+      Context,
+      Reenter,
+      SelectedTargetResult<Selection> | Declined,
+      "declinable"
+    >
+  }
+
+  /** @internal */
+  type StateUpdateTransition<
+    States extends StateSchemas,
+    Events extends ReadonlyArray<TaggedSchema>,
+    Emits extends ReadonlyArray<TaggedSchema>,
+    StateId extends StateNodeIdentifier<States>,
+    Context,
+    Reenter extends boolean,
+    Acceptance extends TransitionAcceptance,
+    Selection extends TargetSelection<any, any, "update">
+  > =
+    & Selection
+    & StateUpdateTransitionRequired<States, Events, Emits, StateId, Context, Reenter, Selection>
+    & ("declinable" extends Acceptance ? StateUpdateTransitionDeclinable<
+        States,
+        Events,
+        Emits,
+        StateId,
+        Context,
+        Reenter,
+        Selection
+      >
+      : {})
+
   /** @internal Type evidence retained by a machine initial-entry declaration. */
   export interface InitialBuilderEvidence<out Selection> {
     readonly [InitialBuilderTypeId]: Types.Covariant<Selection>
@@ -5805,19 +6109,18 @@ export declare namespace Machine {
     Reenter extends boolean,
     Acceptance extends TransitionAcceptance,
     Node
-  > = Node extends (...args: infer Args) => infer Selection ? Selection extends TargetSelection<any, any, any> ?
-        & ((...args: Args) => TransitionTarget<
-          States,
-          Events,
-          Emits,
-          StateId,
-          Context,
-          Reenter,
-          Acceptance,
-          Selection
-        >)
-        & {
-          readonly [Key in keyof Node]: TransitionSelectorNode<
+  > = Node extends TargetSelection<any, any, "update"> ? StateUpdateTransition<
+      States,
+      Events,
+      Emits,
+      StateId,
+      Context,
+      Reenter,
+      Acceptance,
+      Node
+    >
+    : Node extends (...args: infer Args) => infer Selection ? Selection extends TargetSelection<any, any, any> ?
+          & ((...args: Args) => TransitionTarget<
             States,
             Events,
             Emits,
@@ -5825,10 +6128,21 @@ export declare namespace Machine {
             Context,
             Reenter,
             Acceptance,
-            Node[Key]
-          >
-        }
-    : never
+            Selection
+          >)
+          & {
+            readonly [Key in keyof Node]: TransitionSelectorNode<
+              States,
+              Events,
+              Emits,
+              StateId,
+              Context,
+              Reenter,
+              Acceptance,
+              Node[Key]
+            >
+          }
+      : never
     : Node extends TargetSelection<any, any, any> ? TransitionTarget<
         States,
         Events,
@@ -8632,9 +8946,10 @@ export const initialDefinition: <M extends Machine.Any>(machine: M) => Machine.I
  *
  * Event handlers retain their handler-key order within each source state and
  * are followed by eventless and completion handlers. This function does not
- * execute resolvers. Every direct, named, and targetless branch exposes the
- * destination selected by its required static `target` declaration, while
- * `acceptance` reports whether the resolver may decline the transition.
+ * execute resolvers. Every branch exposes its static selection. State updates
+ * retain the updated owner in `selection.path` while leaving `target`
+ * undefined because they do not change topology. `acceptance` reports whether
+ * the resolver may decline the transition.
  *
  * @category getters
  * @since 0.4.0
@@ -8917,6 +9232,17 @@ export const logic: <
 export const child: <const Id extends string, M extends Machine.Any>(id: Id, machine: M) => ChildMachine<Id, M> =
   internal.child
 
+/**
+ * Binds one machine definition to an open family of runtime child ids.
+ *
+ * Descriptors created by the returned function are interchangeable with
+ * {@link child} descriptors for the same id and machine definition.
+ *
+ * @category constructors
+ * @since 0.20.0
+ */
+export const childFamily: <M extends Machine.Any>(machine: M) => ChildMachine.Family<M> = internal.childFamily
+
 /**
  * Creates a typed parent-local address for lower-level child process logic.
  *

package/src/internal/machine/atom.ts

@@ -342,15 +342,7 @@ const makeChildFromRefAtom = <Child extends Machine.ChildMachine.Any, StartError
     }
   )
 
-  const childFamily = Atom.family((nested: Machine.ChildMachine.Any) =>
-    makeChildFromRefAtom(
-      makeChildRefAtom(ref as any, nested),
-      nested
-    )
-  )
-  const child = <Nested extends Machine.ChildMachine.Any>(
-    nested: Nested
-  ): ChildMachineAtom<Nested, StartError> => childFamily(nested) as ChildMachineAtom<Nested, StartError>
+  const child = makeChildSelector<StartError>(ref as any)
 
   return {
     ref,
@@ -363,6 +355,30 @@ const makeChildFromRefAtom = <Child extends Machine.ChildMachine.Any, StartError
   }
 }
 
+const makeChildSelector = <StartError>(
+  parentRef: Atom.Atom<
+    AsyncResult.AsyncResult<Option.Option<Machine.MachineRef<any, any, any, any, any>>, StartError>
+  >
+) => {
+  const byMachine = new WeakMap<object, (id: string) => ChildMachineAtom<Machine.ChildMachine.Any, StartError>>()
+  return <Child extends Machine.ChildMachine.Any>(descriptor: Child): ChildMachineAtom<Child, StartError> => {
+    let family = byMachine.get(descriptor.machine)
+    if (family === undefined) {
+      const machine = descriptor.machine
+      const atoms = Atom.family((id: string) => {
+        const child = internalMachine.child(id, machine)
+        return makeChildFromRefAtom(
+          makeChildRefAtom(parentRef as any, child),
+          child
+        )
+      })
+      family = (id) => atoms(id) as ChildMachineAtom<Machine.ChildMachine.Any, StartError>
+      byMachine.set(machine, family)
+    }
+    return family(descriptor.id) as ChildMachineAtom<Child, StartError>
+  }
+}
+
 const makeFromRefAtom = <State, Event, Error, Output, StartError, Emitted>(
   ref: Atom.Atom<AsyncResult.AsyncResult<Machine.MachineRef<State, Event, Error, Output, Emitted>, StartError>>
 ): MachineAtom<State, Event, Error, Output, StartError, Emitted> => {
@@ -438,15 +454,7 @@ const makeFromRefAtom = <State, Event, Error, Output, StartError, Emitted>(
   )
 
   const optionalRef = Atom.mapResult(ref, Option.some)
-  const childFamily = Atom.family((descriptor: Machine.ChildMachine.Any) =>
-    makeChildFromRefAtom(
-      makeChildRefAtom(optionalRef as any, descriptor),
-      descriptor
-    )
-  )
-  const child = <Child extends Machine.ChildMachine.Any>(
-    descriptor: Child
-  ): ChildMachineAtom<Child, StartError> => childFamily(descriptor) as ChildMachineAtom<Child, StartError>
+  const child = makeChildSelector<StartError>(optionalRef as any)
 
   return {
     ref,