support for spawning child actors connected to life cycle of parent actor

[bhvngt]

Thanks for publishing this library. I was looking out for xstate like library within effect-ts eco system and this appears to be the closest match.

As I was exploring the api, I was wondering if there is any support for spawning and managing child actor. I wrote a sample program to spawn child actors using spawnChild effect. However, for some reason, I am not able to get access to the child actor.

Here's my sample code

import { Effect, Schema, Option } from "effect";
import { ActorSystemDefault, ActorSystemService, Event, Machine, Slot, State } from "effect-machine";

const ChildState = State({ Idle: {}, Running: {} });
const ChildEvent = Event({ Start: {} });

const childMachine = Machine.make({
  state: ChildState,
  event: ChildEvent,
  initial: ChildState.Idle
}).on(ChildState.Idle, ChildEvent.Start, () => ChildState.Running).build();

const ParentState = State({ Idle: {}, Active: {} });
const ParentEvent = Event({ Activate: {} });

// Define the "Slot" for the effect
const ParentEffects = Slot.Effects({
  spawnChild: { id: Schema.String }
});

const config = {
  state: ParentState,
  event: ParentEvent,
  effects: ParentEffects,
  initial: ParentState.Idle
};

const parentMachine =
  Machine.make(config)
         .on(ParentState.Idle, ParentEvent.Activate, () => ParentState.Active)
         .spawn(ParentState.Active, ({ effects }) => effects.spawnChild({ id: "child-1" }))
         .build({
           spawnChild: ({ id }) =>
             Effect.gen(function* () {
               const system = yield* ActorSystemService;
               const childActor = yield* system.spawn(id, childMachine);
               yield* Effect.addFinalizer(() => Effect.log("closing child actor"));
               yield* childActor.send(ChildEvent.Start);
               yield* Effect.log(`Child actor ${id} spawned and started.`);
             }).pipe(Effect.catchTag("DuplicateActorError", e => Effect.log(e)), Effect.provide(ActorSystemDefault))
         });

Effect.gen(function* () {
  const system = yield* ActorSystemService;
  const actor = yield* system.spawn("parent", parentMachine);
  yield* actor.send(ParentEvent.Activate);
  yield* actor.waitFor(ParentState.Active);
  const childActor = yield* system.get("child-1");
  console.log(`Option.isSome(childActor)`, Option.isSome(childActor));
  if (Option.isSome(childActor)) {
    const childActorRef = childActor.value;
    childActorRef.subscribe((state) => console.log(state._tag))
    yield* childActorRef.waitFor(ChildState.Running);
  }
  yield* actor.stop;
}).pipe(Effect.scoped, Effect.provide(ActorSystemDefault), Effect.runPromise);

and here's my sample output

timestamp=2026-02-04T07:08:40.301Z level=INFO fiber=#2 message="Child actor child-1 spawned and started."

Option.isSome(childActor) false

timestamp=2026-02-04T07:08:40.306Z level=INFO fiber=#0 message="closing connection"

[cevr]

Hey @bhvngt, thanks for the issue! Child actor support has been added.

Your original code didn't work because Effect.provide(ActorSystemDefault) inside the slot created a separate isolated system — so the child wasn't visible from the parent's system.

Now handlers receive self.spawn which registers children in the parent's system automatically:

const parentMachine = Machine.make({
  state: ParentState,
  event: ParentEvent,
  initial: ParentState.Idle,
})
  .on(ParentState.Idle, ParentEvent.Activate, () => ParentState.Active)
  .spawn(ParentState.Active, ({ self }) =>
    Effect.gen(function* () {
      const child = yield* self.spawn("child-1", childMachine).pipe(Effect.orDie);
      yield* child.send(ChildEvent.Start);
      // child auto-stopped when parent exits Active state
    }),
  )
  .build();

Access children externally via actor.system:

const parent = yield* Machine.spawn(parentMachine);
yield* parent.send(ParentEvent.Activate);
const child = yield* parent.system.get("child-1"); // Option.isSome === true

No need for ActorSystemDefault either — Machine.spawn creates an implicit system now.

Give it a try and let me know what you think!

[bhvngt]

Thanks @cevr. This totally works with a very nice DX. Appreciate your effort and response. Thanks a ton.

[bhvngt]

Is there a way to get all the spawned child actors of a parent? This can be useful specifically in cases when multiple dynamic child actors have been spawned.

[cevr]

Good catch, just added support for this. actor.children gives you a ReadonlyMap<string, ActorRef> of all children spawned via self.spawn:

const parent = yield* Machine.spawn(parentMachine);
yield* parent.send(ParentEvent.Activate);

parent.children; // ReadonlyMap<string, ActorRef>
parent.children.size; // number of children
parent.children.get("worker-1"); // ActorRef | undefined

State-scoped children are auto-removed when the parent exits that state.

You can also observe children joining/leaving via the system:

// sync callback
parent.system.subscribe((event) => {
  // event._tag: "ActorSpawned" | "ActorStopped"
  console.log(event._tag, event.id);
});

// or async stream
parent.system.events; // Stream<SystemEvent>

[bhvngt]

Does your current design supports spawning child actors during background effects. For example, for cases where I would like the child machine responsible for managing observability be scoped with the machine lifetime.

[cevr]

Yep, .background() handlers receive self which has self.spawn. Children spawned there live for the machine's lifetime (not tied to any state scope):

const parentMachine = Machine.make({
  state: ParentState,
  event: ParentEvent,
  initial: ParentState.Idle,
})
  .background(({ self }) =>
    Effect.gen(function* () {
      const observability = yield* self.spawn("observability", observabilityMachine).pipe(Effect.orDie);
      yield* observability.send(ObsEvent.Start);
      // lives until parent machine stops
    }),
  )
  .build();

The child gets interrupted when the parent machine reaches a final state or is explicitly stopped.

[bhvngt]

Thats great to know @cevr. Thank you for your reply.