@marianmeres/actor

A lightweight, type-safe Actor Model implementation for TypeScript/JavaScript.

What is an Actor?

An actor is a message-driven stateful computation unit. It processes messages sequentially through a mailbox, ensuring safe state mutations without complex async coordination.

Key benefits:

• Sequential processing: Messages are queued and processed one at a time (FIFO)
• No async race conditions: Concurrent sends are serialized automatically
• Reactive subscriptions: Subscribe to state changes
• Error isolation: Handler errors don't break the mailbox
• Framework-agnostic: Works with any UI framework or Node.js

Installation

# Deno
deno add jsr:@marianmeres/actor

# npm
npm install @marianmeres/actor

Quick Start

import { createStateActor } from "@marianmeres/actor";

// Define message types
type Message =
  | { type: "INCREMENT" }
  | { type: "DECREMENT" }
  | { type: "ADD"; payload: number };

// Create a counter actor
const counter = createStateActor<number, Message>(0, (state, msg) => {
  switch (msg.type) {
    case "INCREMENT": return state + 1;
    case "DECREMENT": return state - 1;
    case "ADD": return state + msg.payload;
  }
});

// Send messages
await counter.send({ type: "INCREMENT" });
await counter.send({ type: "ADD", payload: 10 });

console.log(counter.getState()); // 11

// Subscribe to changes (with optional previous state, Svelte-compatible)
const unsubscribe = counter.subscribe(({ current, previous }) => {
  console.log("Counter:", current, "(was:", previous, ")");
});

// Cleanup
counter.destroy();

API Reference

For complete API documentation, see API.md.

Function	Description
createStateActor(initial, handler, options?)	Simple actor where handler returns the new state
createActor(options)	Full control with optional reducer, onError, debug, logger
defineMessage(type)	Creates typed message factories (like Redux action creators)
createTypedStateActor(initial, handlers, options?)	Exhaustive message handling with compile-time checking
createTypedActor(options)	Full control + exhaustive handlers + reducer + debug logging
createMessageFactory()	DTOKit factory for validating external messages

All actor factories support optional debug: true and custom logger for verbose debug logging.

Actor Method	Description
send(msg)	Queue message, returns Promise<TResponse>
subscribe(fn)	Subscribe to state changes. Callback receives { current, previous? } - called immediately with undefined previous, then on each change with actual previous state. Svelte-compatible single parameter.
getState()	Get current state synchronously
destroy()	Clear mailbox and subscribers
debug	Read-only debug flag value (boolean | undefined)
logger	Read-only logger instance (custom or console)

How send() Works: The Deferred Promise Pattern

The send() method uses a "deferred promise" pattern internally to bridge the gap between when you call send() and when your message is actually processed:

send(message) {
  return new Promise((resolve, reject) => {
    mailbox.push({ message, resolve, reject });  // Store callbacks with message
    processMailbox();
  });
}

Why this design?

1. Callbacks stored with message: Each message is queued alongside its own resolve/reject functions. When processMailbox eventually processes this specific message, it can resolve/reject the correct caller's promise.

2. Non-blocking queue trigger: processMailbox() is called after every push, but has a guard (if (processing) return) so it's a no-op when already running. The while loop inside ensures all queued messages are processed sequentially before releasing the lock.

3. Async by design: Even if your handler is synchronous, send() returns a Promise because:

   • Your message may wait behind others in the queue (FIFO order)
   • The handler might be async (I/O, network calls)
   • Callers need to know when their message was processed and get the result

This pattern enables the core actor guarantee: sequential message processing with async-friendly callers.

Understanding the Reducer

The reducer option separates what the handler returns from how state is updated.

Without reducer (createStateActor): handler's return value IS the new state.

With reducer: handler can return rich data, reducer extracts what goes into state:

const actor = createActor<
  number,                              // State type
  string,                              // Message type
  { delta: number; log: string }       // Response type (different from state!)
>({
  initialState: 0,
  handler: (state, msg) => {
    return { delta: msg.length, log: `Processed: ${msg}` };
  },
  reducer: (state, response) => state + response.delta,
});

const result = await actor.send("hello");
// result = { delta: 5, log: "Processed: hello" }  ← caller gets full response
// state = 5                                        ← but state only stores delta

Use cases: async operations returning { data, metadata }, validation returning { valid, errors }, side effects returning status while reducer decides what to persist.

Previous State in Subscribers

Subscribers receive { current, previous } as a single parameter (Svelte-compatible), enabling powerful change detection patterns:

const user = createStateActor<
  { name: string; email: string; preferences: object },
  UpdateMessage
>(initialState, handler);

user.subscribe(({ current, previous }) => {
  // On initial subscription, previous is undefined
  if (previous === undefined) {
    console.log("Initial state loaded");
    return;
  }

  // React only to specific property changes
  if (current.email !== previous.email) {
    sendEmailVerification(current.email);
  }

  if (current.preferences !== previous.preferences) {
    syncPreferencesToServer(current.preferences);
  }
});

Common use cases for previous state:

• Conditional side effects (only run when specific fields change)
• Computing diffs for analytics or debugging
• Animations/transitions between states
• Undo/redo without external history tracking

When to Use Actors

Good fit:

• Complex async workflows needing serialization
• Shared state with multiple async writers
• WebSocket/SSE message handling
• Form submission with validation
• Background task queues
• Undo/redo stacks
• Game state machines

Probably overkill:

• Simple component state (use signals/stores instead)
• Synchronous state updates only
• Single-writer scenarios

Design Philosophy: Single-Actor Simplicity

This library intentionally implements a single-actor pattern without actor addresses, hierarchies, or spawning capabilities. This is a deliberate design choice.

What's NOT included (and why)

In the traditional Actor Model (Erlang/Elixir OTP, Akka), actors have:

• Addresses - unique identifiers allowing actors to send messages to each other
• Spawning - actors can create child actors and receive their addresses
• Supervision - parent actors monitor and restart failed children

These features are essential for building distributed, fault-tolerant systems with many coordinating actors. However, they add significant complexity.

What this library provides instead

A focused, lightweight primitive for the most common use case: serialized message processing with encapsulated state. Each actor is self-contained and handles:

• Sequential (FIFO) message processing via mailbox
• Safe state mutations without complex async coordination
• Reactive subscriptions for state changes
• Error isolation within the handler

When you might need the full Actor Model

If your use case requires actors communicating with each other, building actor hierarchies, or distributed fault-tolerance, consider:

• xstate - State machines with actor spawning
• Comlink - Web Workers as actors
• A backend runtime like Elixir/Erlang for true distributed actors

For most frontend and simple backend scenarios, this single-actor approach provides the core benefits (serialization, isolation, reactivity) without the cognitive overhead of a full actor system.

DTOKit Integration: Exhaustive Message Handling

For actors with multiple message types, the optional @marianmeres/dtokit integration provides compile-time exhaustive checking - TypeScript will error if you forget to handle any message type.

The Problem

With standard createStateActor, forgetting a message type in your switch statement produces no TypeScript error:

type Message =
  | { type: "INC" }
  | { type: "DEC" }
  | { type: "ADD"; amount: number };

const counter = createStateActor<number, Message>(0, (state, msg) => {
  switch (msg.type) {
    case "INC": return state + 1;
    case "DEC": return state - 1;
    // Oops! Forgot "ADD" - TypeScript doesn't complain!
  }
});

The Solution

With createTypedStateActor, missing handlers cause compile-time errors:

import { createTypedStateActor } from "@marianmeres/actor";

// Define schemas: keys MUST match the "type" discriminator values
type Schemas = {
  INC: { type: "INC" };
  DEC: { type: "DEC" };
  ADD: { type: "ADD"; amount: number };
};

const counter = createTypedStateActor<Schemas, number>(0, {
  INC: (msg, state) => state + 1,
  DEC: (msg, state) => state - 1,
  // TypeScript ERROR: Property 'ADD' is missing in type...
});

How It Works

1. Single source of truth: Define message types once in a schemas object
2. Exhaustive handlers: Provide a handler for each schema key (not a switch statement)
3. Type inference: Each handler receives the correctly-typed message
4. Compile-time safety: Add a new message type → compiler shows where to add handlers

Detailed Comparison

Aspect	createStateActor	createTypedStateActor
Message definition	Union type: { type: "A" } | { type: "B" }	Schema object: { A: {...}, B: {...} }
Handler style	switch (msg.type)	Handler object: { A: fn, B: fn }
Missing case	No error (silent bug)	Compile error
Adding message	Edit union + add case	Edit schema + add handler (compiler guides you)
Refactoring	Manual find/replace	Compiler catches all locations

Complete Example

import { createTypedStateActor, createMessageFactory } from "@marianmeres/actor";

// 1. Define your message schemas (single source of truth)
type TodoSchemas = {
  ADD: { type: "ADD"; text: string };
  REMOVE: { type: "REMOVE"; id: number };
  TOGGLE: { type: "TOGGLE"; id: number };
  CLEAR_DONE: { type: "CLEAR_DONE" };
};

type Todo = { id: number; text: string; done: boolean };

// 2. Create actor with exhaustive handlers
const todos = createTypedStateActor<TodoSchemas, Todo[]>([], {
  ADD: (msg, state) => [...state, { id: Date.now(), text: msg.text, done: false }],
  REMOVE: (msg, state) => state.filter(t => t.id !== msg.id),
  TOGGLE: (msg, state) => state.map(t =>
    t.id === msg.id ? { ...t, done: !t.done } : t
  ),
  CLEAR_DONE: (_, state) => state.filter(t => !t.done),
});

// 3. Full type safety on send()
await todos.send({ type: "ADD", text: "Buy milk" });
await todos.send({ type: "TOGGLE", id: 123 });
// await todos.send({ type: "TYPO" }); // TypeScript error!

// 4. Optional: Validate external messages (WebSocket, API, etc.)
const factory = createMessageFactory<TodoSchemas>();

websocket.onmessage = (event) => {
  const msg = factory.parse(JSON.parse(event.data));
  if (msg) {
    todos.send(msg); // Type-safe after validation!
  }
};

With Rich Response Data

Use createTypedActor when handlers return data different from state:

import { createTypedActor } from "@marianmeres/actor";

type Schemas = {
  PROCESS: { type: "PROCESS"; data: string };
  RESET: { type: "RESET" };
};

type State = { result: string | null };
type Response = { result: string; metadata: { processedAt: number } };

const processor = createTypedActor<Schemas, State, Response>({
  initialState: { result: null },
  handlers: {
    PROCESS: (msg, state) => ({
      result: msg.data.toUpperCase(),
      metadata: { processedAt: Date.now() }
    }),
    RESET: () => ({ result: "", metadata: { processedAt: 0 } }),
  },
  reducer: (state, response) => ({ result: response.result }),
});

const response = await processor.send({ type: "PROCESS", data: "hello" });
// response.result = "HELLO"
// response.metadata.processedAt = 1701234567890
// processor.getState() = { result: "HELLO" }

When to Use DTOKit Integration

Use createTypedStateActor when:

• You have 3+ message types
• Team members add new message types
• You want refactoring safety
• Messages come from external sources needing validation

Stick with createStateActor when:

• Simple actor with 1-2 message types
• You're prototyping quickly
• You prefer switch statement style

Note on Dependencies

The createTypedStateActor, createTypedActor, and createMessageFactory functions use @marianmeres/dtokit internally for exhaustive type checking. This dependency is included with the package - no additional installation needed.

// All exports from single entry point
import {
  createStateActor,        // Basic actor
  createTypedStateActor,   // With exhaustive checking
  createMessageFactory,    // For external message validation
} from "@marianmeres/actor";

Examples

Some examples below use the amazing @marianmeres/fsm library. Pure coincidence.

Async Data Fetching

interface DataState {
  data: unknown | null;
  loading: boolean;
  error: string | null;
}

const fetcher = createActor<DataState, { type: "FETCH"; url: string }, DataState>({
  initialState: { data: null, loading: false, error: null },
  handler: async (state, msg) => {
    const res = await fetch(msg.url);
    const data = await res.json();
    return { data, loading: false, error: null };
  },
  reducer: (_, response) => response,
});

// Multiple rapid fetches are serialized - no race conditions!
fetcher.send({ type: "FETCH", url: "/api/data" });
fetcher.send({ type: "FETCH", url: "/api/data" });
// Responses arrive in order, one at a time

Orchestrating Multiple Actors with FSM

A common DDD pattern: use a finite state machine to coordinate multiple domain actors. Each actor manages its own domain state, while the FSM orchestrates the workflow.

import { createTypedStateActor } from "@marianmeres/actor";
import { createFsm } from "@marianmeres/fsm";

// Domain actors - each manages its own bounded context

type CartSchemas = {
  ADD_ITEM: { type: "ADD_ITEM"; item: { sku: string; qty: number } };
  CLEAR: { type: "CLEAR" };
};

const cart = createTypedStateActor<CartSchemas, { items: Array<{ sku: string; qty: number }>; total: number }>(
  { items: [], total: 0 },
  {
    ADD_ITEM: (msg, state) => ({ ...state, items: [...state.items, msg.item] }),
    CLEAR: () => ({ items: [], total: 0 }),
  }
);

type PaymentSchemas = {
  PROCESS: { type: "PROCESS" };
  SUCCESS: { type: "SUCCESS"; txId: string };
  FAIL: { type: "FAIL" };
};

const payment = createTypedStateActor<PaymentSchemas, { status: string; txId: string | null }>(
  { status: "idle", txId: null },
  {
    PROCESS: () => ({ status: "processing", txId: null }),
    SUCCESS: (msg) => ({ status: "success", txId: msg.txId }),
    FAIL: () => ({ status: "failed", txId: null }),
  }
);

type InventorySchemas = {
  RESERVE: { type: "RESERVE"; items: Array<{ sku: string; qty: number }> };
  RELEASE: { type: "RELEASE" };
};

const inventory = createTypedStateActor<InventorySchemas, { reserved: Array<{ sku: string; qty: number }> }>(
  { reserved: [] },
  {
    RESERVE: (msg, state) => ({ reserved: [...state.reserved, ...msg.items] }),
    RELEASE: () => ({ reserved: [] }),
  }
);

// FSM orchestrates the checkout workflow
const checkoutFsm = createFsm({
  initial: "IDLE",
  context: { error: null },
  states: {
    IDLE: {
      on: { start: "RESERVING" }
    },
    RESERVING: {
      onEnter: async (ctx) => {
        await inventory.send({ type: "RESERVE", items: cart.getState().items });
        checkoutFsm.transition("reserved");
      },
      on: { reserved: "CHARGING", fail: "FAILED" }
    },
    CHARGING: {
      onEnter: async (ctx) => {
        await payment.send({ type: "PROCESS" });
        // Simulate payment processing
        const success = Math.random() > 0.1;
        if (success) {
          await payment.send({ type: "SUCCESS", txId: "tx_123" });
          checkoutFsm.transition("charged");
        } else {
          await payment.send({ type: "FAIL" });
          checkoutFsm.transition("fail");
        }
      },
      on: { charged: "COMPLETED", fail: "ROLLING_BACK" }
    },
    ROLLING_BACK: {
      onEnter: async () => {
        await inventory.send({ type: "RELEASE" });
        checkoutFsm.transition("rolled_back");
      },
      on: { rolled_back: "FAILED" }
    },
    COMPLETED: {
      onEnter: async () => {
        await cart.send({ type: "CLEAR" });
      }
    },
    FAILED: {}
  }
});

// Usage: subscribe to FSM for workflow state, actors for domain state
checkoutFsm.subscribe(({ state }) => console.log("Checkout:", state));
payment.subscribe((s) => console.log("Payment:", s.status));

Multi-Actor Notification System

// User preferences actor
const preferences = createStateActor(
  { email: true, push: true, sms: false },
  (state, msg) => ({ ...state, [msg.channel]: msg.enabled })
);

// Notification queue actor - serializes delivery
const notificationQueue = createActor({
  initialState: { pending: 0, sent: 0 },
  handler: async (state, msg) => {
    const prefs = preferences.getState();
    const results = [];

    if (prefs.email && msg.channels.includes("email")) {
      await sendEmail(msg.to, msg.content);
      results.push("email");
    }
    if (prefs.push && msg.channels.includes("push")) {
      await sendPush(msg.to, msg.content);
      results.push("push");
    }

    return { delivered: results, messageId: msg.id };
  },
  reducer: (state, response) => ({
    pending: state.pending - 1,
    sent: state.sent + response.delivered.length
  })
});

// FSM controls notification campaign lifecycle
const campaignFsm = createFsm({
  initial: "DRAFT",
  context: { recipientCount: 0, sentCount: 0 },
  states: {
    DRAFT: { on: { schedule: "SCHEDULED", send: "SENDING" } },
    SCHEDULED: { on: { trigger: "SENDING", cancel: "DRAFT" } },
    SENDING: {
      onEnter: async (ctx) => {
        for (const recipient of ctx.recipients) {
          await notificationQueue.send({
            id: crypto.randomUUID(),
            to: recipient,
            content: ctx.message,
            channels: ["email", "push"]
          });
          ctx.sentCount++;
        }
        campaignFsm.transition("complete");
      },
      on: { complete: "COMPLETED", pause: "PAUSED" }
    },
    PAUSED: { on: { resume: "SENDING" } },
    COMPLETED: {}
  }
});

Actor as Aggregate Root

In DDD, the aggregate root coordinates changes within a bounded context:

import { createTypedStateActor } from "@marianmeres/actor";

// Define the domain types
type Item = { sku: string; qty: number; price: number };
type Payment = { amount: number; method: string };
type Shipment = { trackingId: string; carrier: string };

type OrderState = {
  id: string;
  status: "pending" | "submitted" | "paid" | "shipped";
  items: Item[];
  payments: Payment[];
  shipments: Shipment[];
};

// Define all order commands (message schemas)
type OrderSchemas = {
  ADD_ITEM: { type: "ADD_ITEM"; item: Item };
  SUBMIT: { type: "SUBMIT" };
  RECORD_PAYMENT: { type: "RECORD_PAYMENT"; payment: Payment };
  SHIP: { type: "SHIP"; shipment: Shipment };
};

// Order aggregate - the actor IS the aggregate root
const createOrderActor = (orderId: string) => createTypedStateActor<OrderSchemas, OrderState>(
  {
    id: orderId,
    status: "pending",
    items: [],
    payments: [],
    shipments: []
  },
  {
    ADD_ITEM: (msg, state) => {
      if (state.status !== "pending") return state; // Invariant
      return { ...state, items: [...state.items, msg.item] };
    },
    SUBMIT: (_, state) => {
      if (state.items.length === 0) return state; // Invariant
      return { ...state, status: "submitted" };
    },
    RECORD_PAYMENT: (msg, state) => ({
      ...state,
      payments: [...state.payments, msg.payment],
      status: calculateStatus(state.payments, msg.payment)
    }),
    SHIP: (msg, state) => {
      if (state.status !== "paid") return state; // Invariant
      return { ...state, shipments: [...state.shipments, msg.shipment] };
    },
  }
);

// Each order is an independent actor maintaining its own invariants
const order1 = createOrderActor("order-1");
const order2 = createOrderActor("order-2");

// Messages to different orders process independently
await order1.send({ type: "ADD_ITEM", item: { sku: "A", qty: 2, price: 10 } });
await order2.send({ type: "ADD_ITEM", item: { sku: "B", qty: 1, price: 25 } });

Error Handling with FSM Orchestration

Use onError to propagate actor failures to the FSM layer:

// FSM with error handling - payload stored via onEnter
const workflowFsm = createFsm({
  initial: "IDLE",
  context: { error: null },
  states: {
    IDLE: { on: { start: "PROCESSING" } },
    PROCESSING: { on: { done: "COMPLETED", error: "ERROR" } },
    COMPLETED: {},
    ERROR: {
      onEnter: (ctx, payload) => { ctx.error = payload; }  // Store error from payload
    }
  }
});

// Actor with onError wired to FSM
const processor = createActor({
  initialState: { result: null },
  handler: async (state, msg) => {
    const res = await fetch(msg.url);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return { result: await res.json() };
  },
  reducer: (_, response) => response,
  onError: (error, message) => {
    // Pass error as transition payload
    workflowFsm.transition("error", { error: String(error), message });
  }
});

// Usage
workflowFsm.transition("start");
await processor.send({ url: "/api/data" });  // If this throws, FSM → ERROR
workflowFsm.transition("done");              // Only reached on success

Nested FSM: Actor-Level + App-Level Orchestration

Each actor can have its own internal FSM for complex lifecycle management, while a global FSM orchestrates multiple actors at the application level.

import { createActor } from "@marianmeres/actor";
import { createFsm } from "@marianmeres/fsm";

// Factory: creates a "job" actor with its own internal FSM lifecycle
const createJobActor = (id: string, work: () => Promise<unknown>) => {
  // Inner FSM - manages this job's lifecycle
  const jobFsm = createFsm({
    initial: "IDLE",
    context: { result: null, error: null },
    states: {
      IDLE: { on: { start: "RUNNING" } },
      RUNNING: { on: { complete: "DONE", fail: "FAILED" } },
      DONE: {},
      FAILED: { on: { retry: "RUNNING" } }  // Can retry from failed
    }
  });

  // Actor wraps the FSM and handles async work
  const actor = createActor<
    { id: string; status: string; result: unknown; error: unknown },
    { type: "START" } | { type: "RETRY" },
    { status: string }
  >({
    initialState: { id, status: "IDLE", result: null, error: null },
    handler: async (state, msg) => {
      if (msg.type === "START" || msg.type === "RETRY") {
        jobFsm.transition(msg.type === "START" ? "start" : "retry");
        try {
          const result = await work();
          jobFsm.transition("complete");
          jobFsm.context.result = result;
          return { status: "DONE" };
        } catch (e) {
          jobFsm.transition("fail");
          jobFsm.context.error = e;
          return { status: "FAILED" };
        }
      }
      return { status: jobFsm.state };
    },
    reducer: (state, response) => ({
      ...state,
      status: response.status,
      result: jobFsm.context.result,
      error: jobFsm.context.error
    })
  });

  return { actor, fsm: jobFsm };
};

// Create job actors with different work
const job1 = createJobActor("job-1", async () => {
  await delay(100);
  return { data: "result-1" };
});
const job2 = createJobActor("job-2", async () => {
  await delay(200);
  if (Math.random() < 0.3) throw new Error("Random failure");
  return { data: "result-2" };
});

// App-level FSM - orchestrates the batch of jobs
const batchFsm = createFsm({
  initial: "IDLE",
  context: { completed: 0, failed: 0, total: 2 },
  states: {
    IDLE: { on: { run: "RUNNING" } },
    RUNNING: {
      onEnter: async (ctx) => {
        // Start all jobs in parallel
        const results = await Promise.all([
          job1.actor.send({ type: "START" }),
          job2.actor.send({ type: "START" })
        ]);

        // Tally results
        results.forEach(r => {
          if (r.status === "DONE") ctx.completed++;
          else ctx.failed++;
        });

        batchFsm.transition(ctx.failed > 0 ? "partial" : "success");
      },
      on: { success: "COMPLETED", partial: "PARTIAL_FAILURE" }
    },
    PARTIAL_FAILURE: {
      on: {
        retry: "RETRYING",
        accept: "COMPLETED"
      }
    },
    RETRYING: {
      onEnter: async (ctx) => {
        // Retry only failed jobs
        const failedJobs = [job1, job2].filter(j => j.fsm.state === "FAILED");
        for (const job of failedJobs) {
          const result = await job.actor.send({ type: "RETRY" });
          if (result.status === "DONE") {
            ctx.failed--;
            ctx.completed++;
          }
        }
        batchFsm.transition(ctx.failed > 0 ? "partial" : "success");
      },
      on: { success: "COMPLETED", partial: "PARTIAL_FAILURE" }
    },
    COMPLETED: {}
  }
});

// Subscribe to see the layered state
batchFsm.subscribe(({ state }) => console.log("Batch:", state));
job1.actor.subscribe(s => console.log("Job1:", s.status));
job2.actor.subscribe(s => console.log("Job2:", s.status));

// Run the batch
batchFsm.transition("run");

System State History (Audit Trail)

Track state changes across multiple actors and FSM for debugging, audit, or undo/redo:

// Historian actor - records all state changes across the system
const historian = createStateActor<
  { entries: Array<{ ts: number; source: string; state: unknown }> },
  { type: "RECORD"; source: string; state: unknown } | { type: "CLEAR" }
>(
  { entries: [] },
  (state, msg) => {
    switch (msg.type) {
      case "RECORD":
        return {
          entries: [...state.entries, { ts: Date.now(), source: msg.source, state: msg.state }]
        };
      case "CLEAR":
        return { entries: [] };
      default:
        return state;
    }
  }
);

// Helper to wire up any actor to the historian
const track = <T>(name: string, actor: { subscribe: (fn: (s: T) => void) => void }) => {
  actor.subscribe((state) => historian.send({ type: "RECORD", source: name, state }));
};

// Domain actors
const cart = createStateActor({ items: [] }, (state, msg) => { /* ... */ });
const payment = createStateActor({ status: "idle" }, (state, msg) => { /* ... */ });

// Wire them up
track("cart", cart);
track("payment", payment);

// Also track FSM transitions
const checkoutFsm = createFsm({ /* ... */ });
checkoutFsm.subscribe(({ state }) => {
  historian.send({ type: "RECORD", source: "checkout-fsm", state });
});

// Now historian.getState().entries contains full system history:
// [
//   { ts: 1701234567890, source: "cart", state: { items: [] } },
//   { ts: 1701234567891, source: "payment", state: { status: "idle" } },
//   { ts: 1701234567892, source: "checkout-fsm", state: "IDLE" },
//   { ts: 1701234567900, source: "cart", state: { items: [{ sku: "A" }] } },
//   { ts: 1701234567901, source: "checkout-fsm", state: "RESERVING" },
//   ...
// ]

License

MIT