@typeonce/effect-machine 0.19.0 → 0.20.0

package/README.md

@@ -34,7 +34,7 @@ Cluster and are exposed only through explicit integration boundaries.
 ## Install
 
 ```sh
-pnpm add @typeonce/effect-machine effect@4.0.0-rc.110
+pnpm add @typeonce/effect-machine effect@4.0.0-rc.111
 ```
 
 `effect` is an exact peer dependency. Install the version above and upgrade it
@@ -582,6 +582,46 @@ entered. Use an Effect containing `Effect.sleep(...)` for generic work, while
 `from.timer(...)` keeps timer intent explicit and makes static durations visible
 through activity inspection.
 
+### Spawn dynamic child machines
+
+Use `from.child(...)` when a state owns a fixed child lifecycle. Use the
+`children` context inside an invoked Effect when the machine process owns an
+open set of children that must survive state changes:
+
+```ts
+const Plant = Machine.childFamily(plantMachine)
+
+const central = Machine.make({
+  events: Machine.events(ResourcesOffered, PlantBroken)
+  // ...
+}).handle({
+  Commissioning: {
+    invoke: (from) =>
+      from.effect("commission-wave", ({ children, state }) =>
+        Effect.forEach(
+          state.plants,
+          (input) => children.spawn(Plant(input.id), { input }),
+          { discard: true }
+        ))
+        .onDone((to) => to.full.Operating())
+        .onFailure((to) => to.full.CommissioningFailed())
+  }
+})
+```
+
+`children.spawn` completes after initialization. The new child remains owned
+by the machine process after the commissioning Effect completes or its state
+exits. `children.sendTo` and `children.stop` address one active child from an
+Effect; transition resolvers use `enqueue.sendTo` and `enqueue.stop` with the
+same descriptor. Duplicate active ids fail with `ChildAlreadyExistsError` and
+do not replace the existing child. Earlier successful spawns remain active if
+a later spawn in the same wave fails.
+
+The child machine's declared `Machine.parent(...)` events must be accepted by
+the owner. This is checked at each spawn call even though ids and cardinality
+remain dynamic. `scope.spawn(child, { input })` provides the same descriptor
+form for lower-level process logic, where the process event protocol is known.
+
 ## Reactivity
 
 `AtomMachine` runs one lazy machine instance per `AtomRegistry`:
@@ -603,6 +643,15 @@ The bridge exposes `ref`, `snapshot`, `state`, fail-aware `result`, writable
 equality-aware derivations. React applications using `@effect/atom-react` need
 a `RegistryProvider`.
 
+Descriptors reconstructed from a `Machine.childFamily` resolve the same child
+bridge by machine identity and id:
+
+```ts
+const Plant = Machine.childFamily(plantMachine)
+const plantAtom = centralAtom.child(Plant(selectedPlantId))
+const brokenAtom = AtomMachine.matchesChild(plantAtom, "Broken")
+```
+
 Emissions stay streams rather than becoming retained atom state:
 
 ```ts
@@ -679,20 +728,6 @@ import { MachineTest } from "@typeonce/effect-machine/testing"
 
 Each ESM entrypoint is independent and tree-shakeable.
 
-## Examples
-
-Every package directly under [`examples/`](./examples) has its own lockfile and
-`check` script.
-
-| Example                             | What it demonstrates                                                                                                                                                                                          |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Playground](./examples/playground) | Five focused React examples: atomic turnstile commands, state-scoped traffic-light timers, hierarchical microwave safety, a resource-owned media player, and a worker-hosted machine synchronized across tabs |
-| [Pokémon](./examples/pokemon)       | Compound workflow states, invoked child machines, typed emissions, Atom reactivity, and a live Effect service                                                                                                 |
-| [Platformer](./examples/platformer) | Nested parallel statecharts, typed deep history, raised events, state-scoped timers, deterministic model tests, and a playable SVG adapter                                                                    |
-
-The playground is the shortest path from one concept to working code. The
-standalone examples show larger composition and ownership boundaries.
-
 ## Reference and development
 
 - [API reference](https://effect-machine.typeonce.dev)

package/dist/Machine.d.ts

@@ -1258,7 +1258,8 @@ export declare namespace Logic {
      * @category models
      * @since 0.4.0
      */
-    interface Spawn {
+    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<MachineRef<ChildState, ChildEvent, ChildError, ChildOutput>, ChildInitialError, Exclude<ChildRequirements, Scope.Scope>>;
         <ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, Options extends SpawnOptions, ChildInitialError = never>(logic: Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>, options: Options & ChildAddress.OptionsCompatibility<Options, ChildEvent>): Effect.Effect<MachineRef<ChildState, ChildEvent, ChildError, ChildOutput>, SpawnIdError<Options> | ChildInitialError, Exclude<ChildRequirements, Scope.Scope>>;
     }
@@ -1274,7 +1275,7 @@ export declare namespace Logic {
         /** Address of the owning process, when one exists. */
         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: {
             <TargetEvent>(target: MachineTarget<TargetEvent>, event: TargetEvent): Effect.Effect<void, StoppedError>;
@@ -1302,6 +1303,7 @@ export declare namespace Logic {
 }
 declare const ChildAddressTypeId = "~effect/Machine/ChildAddress";
 declare const ChildAddressCompatibilityErrorTypeId = "~effect/Machine/ChildAddressCompatibilityError";
+declare const ChildParentCompatibilityErrorTypeId = "~effect/Machine/ChildParentCompatibilityError";
 declare const ChildMachineTypeId = "~effect/Machine/ChildMachine";
 type InvokeLifecycleId = string & {
     readonly [ChildAddressTypeId]?: never;
@@ -1342,6 +1344,68 @@ export declare namespace ChildMachine {
      * @since 0.4.0
      */
     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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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.
      *
@@ -1357,6 +1421,21 @@ export declare namespace ChildMachine {
      */
     type Event<Child> = Child extends ChildMachine<string, infer M> ? Machine.EventInput<Machine.InputEvent<M>> : 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.
  *
@@ -3060,6 +3139,8 @@ export declare namespace Machine {
      * @since 0.4.0
      */
     type InvokeContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, 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. */
@@ -4989,6 +5070,16 @@ export declare const logic: <State, Event = never, Output = void, Error = never,
  * @since 0.4.0
  */
 export declare const child: <const Id extends string, M extends Machine.Any>(id: Id, machine: M) => ChildMachine<Id, M>;
+/**
+ * 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 declare const childFamily: <M extends Machine.Any>(machine: M) => ChildMachine.Family<M>;
 /**
  * Creates a typed parent-local address for lower-level child process logic.
  *