@typeonce/effect-machine 0.19.0 → 0.20.0

package/docs/effect-atom-react.md

@@ -0,0 +1,230 @@
+# Effect Atom and React patterns
+
+This guide records the folder organization and three integration patterns
+validated in the process app. Use the API reference for individual AtomMachine
+operations. Read the [Effect Machine agent guide](./agent-guide.md) for
+statechart modeling, transitions, services, and testing.
+
+## Recommended folder structure
+
+```text
+src/
+├── context/                 # Optional React Context adapters
+│   ├── dialog-context.tsx
+│   └── process-context.tsx
+├── lib/
+│   ├── atom-runtime.ts      # Shared bound AtomMachine runtime
+│   └── services/            # Generic Effect business services
+│       └── query-processor.ts
+└── machines/
+    ├── counter/
+    │   ├── machine.ts       # Machine implementation
+    │   └── atom.ts          # Focused atoms for React
+    ├── process/
+    │   ├── machine.ts
+    │   └── atom.ts
+    └── dialog/
+        ├── machine.ts
+        └── atom.ts
+```
+
+Keep these responsibilities separate:
+
+- `machine.ts` defines states, events, transitions, statechart behavior, and
+  Effect service requirements. It has no React dependency.
+- `atom.ts` adapts that machine to the shared bound AtomMachine runtime and
+  exports the focused atoms React needs.
+- `lib/services/` contains reusable business services used by machines.
+- `context/` is optional. It only distributes an already-created machine scope
+  through a React subtree.
+- `lib/atom-runtime.ts` binds AtomMachine once to the application's Effect
+  service layer:
+
+```ts
+import { AtomMachine } from "@typeonce/effect-machine/reactivity"
+import { Atom } from "effect/unstable/reactivity"
+import { QueryProcessor } from "./services/query-processor"
+
+const atomRuntime = Atom.runtime(QueryProcessor.layer)
+
+export const machineAtoms = AtomMachine.bind(atomRuntime)
+```
+
+Each `machineAtoms.make` call still creates an independent machine bridge.
+
+## 1. One global actor with no input
+
+Use a module-level bridge when a no-input machine intentionally has one
+application-wide instance:
+
+```ts
+import { machineAtoms } from "@/lib/atom-runtime"
+import { AtomMachine } from "@typeonce/effect-machine/reactivity"
+import { counterMachine } from "./machine"
+
+export const counterMachineAtom = machineAtoms.make(counterMachine)
+
+export const counterStateAtom = AtomMachine.select(
+  counterMachineAtom,
+  "counter"
+)
+```
+
+"Global" means every import reaches this bridge under the same atom registry.
+Consumers read `counterStateAtom` and use `counterMachineAtom.send` directly.
+Do not add a redundant `counterSendAtom` alias.
+
+## 2. A machine with startup input selected through a family
+
+Use the family key as machine identity. The same value can also be startup
+input:
+
+```ts
+import { machineAtoms } from "@/lib/atom-runtime"
+import { AtomMachine } from "@typeonce/effect-machine/reactivity"
+import { Atom } from "effect/unstable/reactivity"
+import { processMachine } from "./machine"
+
+export const processFamily = Atom.family((query: string) => {
+  const machine = machineAtoms.make(processMachine, { query })
+
+  return {
+    detailsAtom: AtomMachine.select(machine, "process"),
+    resultAtom: AtomMachine.select(machine, "process.Ready"),
+    sendAtom: machine.send
+  }
+})
+```
+
+A consumer calls `processFamily(query)` and uses the returned focused atoms. If
+several nested components need the same scope, an optional Context can expose
+`ReturnType<typeof processFamily>`. The provider resolves the query once instead
+of drilling it through every component.
+
+Changing `query` selects another family member and therefore another machine.
+If a changing value should update the current workflow, model it as an event.
+
+## 3. Reusing one machine definition for multiple instances
+
+Define the dialog adapter once:
+
+```ts
+import { machineAtoms } from "@/lib/atom-runtime"
+import { AtomMachine } from "@typeonce/effect-machine/reactivity"
+import { dialogMachine } from "./machine"
+
+export function makeDialogScope() {
+  const machine = machineAtoms.make(dialogMachine)
+
+  return {
+    isOpenAtom: AtomMachine.matches(machine, "Open"),
+    isClosedAtom: AtomMachine.matches(machine, "Closed"),
+    openStateAtom: AtomMachine.select(machine, "Open"),
+    sendAtom: machine.send
+  }
+}
+
+export type DialogScope = ReturnType<typeof makeDialogScope>
+```
+
+Choose one of the following ownership forms.
+
+### React-tree-owned instance
+
+```tsx
+const DialogContext = createContext<DialogScope | null>(null)
+
+export function DialogProvider({ children }: { children: ReactNode }) {
+  const [scope] = useState(makeDialogScope)
+
+  return (
+    <DialogContext.Provider value={scope}>
+      {children}
+    </DialogContext.Provider>
+  )
+}
+```
+
+Each provider owns one independent dialog. Descendants use a small
+`useDialog()` hook and subscribe to the focused atom they need. Pass
+`DialogScope` through props when Context is unnecessary. Do not add a wrapper
+component whose only job is forwarding the scope.
+
+### Stable keyed instances shared across scattered components
+
+Use one private family to create the scope for an ID. Public selector families
+reach that same scope:
+
+```ts
+import { Atom } from "effect/unstable/reactivity"
+
+const dialogScopeFamily = Atom.family((dialogId: string) => {
+  const scope = makeDialogScope()
+
+  return {
+    isOpenAtom: scope.isOpenAtom.pipe(
+      Atom.withLabel(`dialog:${dialogId}:isOpen-source`)
+    ),
+    openStateAtom: scope.openStateAtom.pipe(
+      Atom.withLabel(`dialog:${dialogId}:openState-source`)
+    ),
+    sendAtom: scope.sendAtom.pipe(
+      Atom.withLabel(`dialog:${dialogId}:send-source`)
+    )
+  }
+})
+
+export const dialogIsOpenFamily = Atom.family((dialogId: string) => {
+  const scope = dialogScopeFamily(dialogId)
+
+  return Atom.transform(
+    scope.sendAtom,
+    (get) => get(scope.isOpenAtom)
+  ).pipe(Atom.withLabel(`dialog:${dialogId}:isOpen`))
+})
+
+export const dialogOpenStateFamily = Atom.family((dialogId: string) => {
+  const scope = dialogScopeFamily(dialogId)
+
+  return Atom.transform(
+    scope.sendAtom,
+    (get) => get(scope.openStateAtom)
+  ).pipe(Atom.withLabel(`dialog:${dialogId}:openState`))
+})
+```
+
+Components using the same `dialogId` share one machine. Different IDs create
+independent machines. The two public projections let consumers subscribe
+independently. Both remain writable through `Atom.transform`, so either can send
+the inferred dialog events.
+
+Use `dialogId` in atom labels for diagnostics. Do not pass it into
+`dialogMachine` as unused fake input.
+
+## 4. Selecting process-owned child machines
+
+Bind a machine definition once when a parent owns a runtime-sized set of child
+machines:
+
+```ts
+const Plant = Machine.childFamily(plantMachine)
+
+export const centralMachineAtom = machineAtoms.make(centralMachine)
+
+export const plantScopeFamily = Atom.family((plantId: string) => {
+  const plant = centralMachineAtom.child(Plant(plantId))
+
+  return {
+    stateAtom: plant.state,
+    isBrokenAtom: AtomMachine.matchesChild(plant, "Broken"),
+    sendAtom: plant.send,
+    stopAtom: plant.stop
+  }
+})
+```
+
+`Plant(plantId)` may be reconstructed wherever the id is available. Child
+lookup and bridge reuse match by machine identity and id, not descriptor object
+identity. Before the parent spawns that child, selectors contain `Option.none`
+and `matchesChild` is `false`. They follow the child after startup and return to
+the inactive values after it stops.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeonce/effect-machine",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Schema-first state machines and statecharts for Effect",
   "author": "Sandro Maglione",
   "repository": {
@@ -46,14 +46,14 @@
     "provenance": true
   },
   "peerDependencies": {
-    "effect": "4.0.0-rc.110"
+    "effect": "4.0.0-rc.111"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.0",
-    "@effect/vitest": "4.0.0-rc.110",
+    "@effect/vitest": "4.0.0-rc.111",
     "@types/node": "25.7.0",
     "dprint": "0.55.2",
-    "effect": "4.0.0-rc.110",
+    "effect": "4.0.0-rc.111",
     "pagefind": "1.5.2",
     "tinybench": "2.9.0",
     "tstyche": "7.2.1",

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.
  *
@@ -4799,6 +4925,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. */
@@ -8917,6 +9045,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,

package/src/internal/machine/invocation.ts

@@ -7,7 +7,7 @@
 import * as Cause from "effect/Cause"
 import * as Effect from "effect/Effect"
 import * as Stream from "effect/Stream"
-import type { ChildMachine, Inspection, Logic, Machine } from "../../Machine.js"
+import type { ChildMachine, ChildOwner, Inspection, Logic, Machine } from "../../Machine.js"
 import * as Configuration from "./configuration.js"
 import { InfiniteTransitionError, MachineSchemaDecodeError, StoppedError } from "./errors.js"
 import * as InvocationEvent from "./invocationEvent.js"
@@ -63,6 +63,16 @@ const streamLogic = (
 const resolveValue = (value: unknown, context: Machine.InvokeContext<any, any, any, any>): unknown =>
   typeof value === "function" ? value(context) : value
 
+const makeChildOwner = (scope: Runtime.ProcessScope<any>): ChildOwner<any> => ({
+  spawn:
+    ((descriptor: ChildMachine.Any, options?: { readonly input?: unknown }) =>
+      (scope.spawn as any)(descriptor, options)) as ChildOwner<any>["spawn"],
+  sendTo: ((descriptor: ChildMachine.Any, event: unknown) => scope.sendTo(descriptor, event)) as ChildOwner<
+    any
+  >["sendTo"],
+  stop: ((descriptor: ChildMachine.Any) => scope.stopChild(descriptor)) as ChildOwner<any>["stop"]
+})
+
 const resolveOne = (
   raw: Record<PropertyKey, any>,
   context: Machine.InvokeContext<any, any, any, any>,
@@ -291,11 +301,13 @@ export const startAll = (
   paths: ReadonlyArray<string>,
   event: Machine.LifecycleEvent<any>
 ): Effect.Effect<void, any, any> | undefined => {
+  const children = makeChildOwner(scope)
   const effects = Planner.sortEntryPaths(machine, paths)
     .filter((path) => configuration.active.has(path))
     .flatMap((path) => {
       const context = {
         ...(Configuration.getMachineReferences(configuration) ?? { self: scope.self, parent: scope.parent }),
+        children,
         state: configuration.values.get(path),
         containingState: Configuration.getParentValue(machine, configuration, path),
         ancestors: Configuration.getParentValues(machine, configuration, path),

package/src/internal/machine/machine.ts

@@ -2124,15 +2124,30 @@ export const transition = <State, Event, Error = never, Requirements = never>(
 export const child = <const Id extends string, M extends Machine.Any>(
   id: Id,
   machine: M
+): ChildMachine<Id, M> =>
+  makeChild(id, machine, (input) =>
+    machine.input === undefined
+      ? (internalProcess.toProcessLogic as any)(machine)
+      : (internalProcess.toProcessLogic as any)(machine, input))
+
+const makeChild = <const Id extends string, M extends Machine.Any>(
+  id: Id,
+  machine: M,
+  makeLogic: (input?: unknown) => Logic<any, any, any, any, any, any>
 ): ChildMachine<Id, M> => ({
   [ChildMachineTypeId]: ChildMachineTypeId,
   id,
   machine,
-  [ChildMachineLogicTypeId]: (input) =>
+  [ChildMachineLogicTypeId]: makeLogic
+})
+
+export const childFamily = <M extends Machine.Any>(machine: M): ChildMachine.Family<M> => {
+  const makeLogic = (input?: unknown): Logic<any, any, any, any, any, any> =>
     machine.input === undefined
       ? (internalProcess.toProcessLogic as any)(machine)
       : (internalProcess.toProcessLogic as any)(machine, input)
-})
+  return (id) => makeChild(id, machine, makeLogic)
+}
 
 export const childAddress = <Event = never>(id: string): ChildAddress<Event> => id as ChildAddress<Event>
 
@@ -2174,10 +2189,7 @@ export const spawn: {
     SpawnError<Options>,
     ChildInitialError
   >
-} = ((
-  logic: Logic<any, any, any, any, any, any>,
-  options?: SpawnOptions
-) =>
+} = ((logic: Logic<any, any, any, any, any, any>, options?: SpawnOptions) =>
   Effect.flatMap(
     internalRuntime.MachineRuntime,
     (runtime) => options === undefined ? runtime.spawn(logic) : (runtime.spawn as any)(logic, options)