Spawn typed

A Behavior<T> is a value. To put it into the runtime — to get an actual ActorRef<T> you can tell messages to — use the method on whichever host you’re spawning from:

Where	Method
Outside an actor	system.spawnTyped(behavior, name) / system.spawnTypedAnonymous(behavior)
Inside an untyped Actor.onReceive	this.context.spawnTyped(behavior, name) / this.context.spawnTypedAnonymous(behavior)
Inside a typed Behaviors.setup / handler	ctx.spawn(behavior, name)
Anywhere Props<T> is accepted	typedProps(behavior)

The method form mirrors the standard OO API — spawn vs. spawnAnonymous for whether you supply a name.

system.spawnTyped — top-level

import { ActorSystem, Behaviors, type Behavior, type ActorRef } from 'actor-ts';

type Cmd = { kind: 'inc' } | { kind: 'get'; replyTo: ActorRef<number> };

const counter = (n: number): Behavior<Cmd> => Behaviors.receive((ctx, cmd) => {
  if (cmd.kind === 'inc') return counter(n + 1);
  if (cmd.kind === 'get') { cmd.replyTo.tell(n); return Behaviors.same; }
  return Behaviors.same;
});

const system = ActorSystem.create('demo');
const ref = system.spawnTyped(counter(0), 'counter');
//    ^- ActorRef<Cmd>

The signatures:

class ActorSystem {
  spawnTyped<T>(behavior: Behavior<T>, name: string): ActorRef<T>;
  spawnTypedAnonymous<T>(behavior: Behavior<T>): ActorRef<T>;
}

Returns a typed ActorRef<T> — tell accepts only Cmd-shaped messages, the compiler enforces it.

ctx.spawnTyped — typed child from an untyped parent

import { Actor, Behaviors } from 'actor-ts';

class UntypedParent extends Actor<...> {
  override preStart(): void {
    const typedChild = this.context.spawnTyped(counter(0), 'child');
    // typedChild: ActorRef<Cmd>
    typedChild.tell({ kind: 'inc' });
  }
}

The signatures live on ActorContext:

interface ActorContext {
  spawnTyped<T>(behavior: Behavior<T>, name: string): ActorRef<T>;
  spawnTypedAnonymous<T>(behavior: Behavior<T>): ActorRef<T>;
}

Useful when you have an existing untyped supervisor that needs to spawn typed workers. The child is a normal entry in the parent’s children list — supervisor strategies apply per the parent’s strategy, death watch works both ways.

typedProps — interop with Props

import { typedProps } from 'actor-ts';

const props = typedProps(counter(0))
  .withMailboxCapacity(500)
  .withDispatcher(myDispatcher);

const ref = system.spawn(props, 'counter');

When you want a typed Behavior but the API takes Props<T> (because it’s an older entry point, or because you want to chain with… builders), typedProps(behavior) returns the right Props<T>.

The shape:

function typedProps<T>(behavior: Behavior<T>): Props<T>;

The returned Props can be passed anywhere Props<T> is expected — system.spawn, context.spawn, Cluster.singletonProxy, the sharding region’s entity-props slot.

Typed-actor-to-typed-child: ctx.spawn

Inside a typed handler, the context exposes its own spawn:

const parent: Behavior<ParentMsg> = Behaviors.setup((ctx) => {
  const child = ctx.spawn(workerBehavior, 'worker');
  //    ^- ActorRef<WorkerMsg>

  return Behaviors.receive((ctx, msg) => {
    child.tell({ kind: 'do-it' });
    return Behaviors.same;
  });
});

This is the standard way for typed parents to spawn typed children — typed all the way through. ctx.spawn(behavior) knows the child’s message type from the Behavior’s type parameter.

Naming + paths

For the deterministic variants (spawnTyped), the name parameter is required and must be unique among siblings. For spawnTypedAnonymous, the framework generates one ('$1', '$2', …).

The resulting actor’s path follows the standard format:

• system.spawnTyped(b, 'counter') → actor-ts://my-app/user/counter
• parentCtx.spawnTyped(b, 'worker') → actor-ts://my-app/user/<parent>/worker
• ctx.spawn(b, 'worker') → actor-ts://my-app/user/<parent>/worker

See Actor paths for the path semantics.

When to use which

Caller is outside an actor:
    → system.spawnTyped(b, name)         // with a name
    → system.spawnTypedAnonymous(b)      // throwaway

Caller is inside an untyped Actor.onReceive:
    → this.context.spawnTyped(b, name)
    → this.context.spawnTypedAnonymous(b)

Caller is inside a typed Behaviors.setup or handler:
    → ctx.spawn(b, name)

You have a function that takes Props<T> and you want to use a Behavior:
    → typedProps(b)

The methods are deliberately small — each handles one common case. typedProps is the escape hatch when you need to plug a behavior into Props-shaped APIs.

Don't share a Behavior across actor instances

const sharedBehavior = counter(0);
system.spawnTyped(sharedBehavior, 'a');
system.spawnTyped(sharedBehavior, 'b');   // ← both start at count=0, fine

Behaviors are values — reading them is fine. The trap is if the behavior closure captures mutable state and you mutate it: both actors see the same mutated reference. Stick to immutable parameters in your behavior closures; the typed form is designed for that.

Naming collisions

system.spawnTyped(b, 'counter');
system.spawnTyped(b, 'counter');   // ← throws — name already in use

Names must be unique among siblings. Either use spawnTypedAnonymous (auto-generated) or use a unique scheme (counter-${id}, worker-${slot}). Same rule as untyped spawn.

Where to next

• Behaviors — the DSL that produces the values you pass to these methods.
• Typed actor — the runtime the spawn methods wrap.
• Props — the untyped configuration typedProps returns.
• Actor system — the spawn API the methods ultimately call.