🎉 Mailbox v0.11 - First Release Announcement

We're excited to announce the first official release of Mailbox - an NPM module that turns XState machines into proper Actor Model implementations with message queue support!

What is Mailbox?

Mailbox solves a fundamental problem with state machines: handling concurrent requests. While a naive state machine processes events immediately (potentially losing messages when busy), Mailbox adds a message queue that lets your machine decide when to process the next message - just like in the Akka Actor Model.

"If you send 3 messages to the same actor, it will just execute one at a time."
— The actor model in 10 minutes

Key Features

• 🎯 Actor Model Mailbox Pattern - Process one message at a time with automatic message queuing
• ⚡ Built on XState - Leverages the powerful finite state machine library
• 📬 Address Abstraction - Clean Address class for actor communication
• 🦆 Duckula Specification - Modular actor definition pattern for organizing events, types, and states
• 🔄 Observable Interface - Mailbox implements Observable for reactive programming
• 📦 Bounded Mailboxes - Configurable capacity with Dead Letter Queue support
• 💪 TypeScript First - Full type safety with ES Modules support

Quick Example

import * as Mailbox from 'mailbox'
import { createMachine } from 'xstate'

const machine = createMachine({
  initial: 'idle',
  states: {
    idle: {
      entry: Mailbox.actions.idle('my-actor'),
      on: { TASK: 'busy' },
    },
    busy: {
      entry: Mailbox.actions.reply('TASK_DONE'),
      after: { 100: 'idle' },
    },
  },
})

const mailbox = Mailbox.from(machine)
// Now your machine handles concurrent requests properly!

The Problem It Solves

A naive state machine is like a mailbox actor with capacity=0 - it faces the "Dead Letter" problem when new messages arrive while it's still processing the last one.

With Mailbox, incoming messages are queued and processed one at a time, ensuring no messages are lost.

Voice of the Community

"The mailbox is separate (which itself can be an actor) and the timing of events forwarded to the statechart can be n-time whereas transitions within the s/c are zero-time."
— @davidkpiano, Creator of XState

"...statecharts process events immediately while actors (by means of message queues) give you granular control of when to process the next event."
— @chrisshank23, Core member of StateML

Duckula Specification

Mailbox introduces the Duckula specification - a modular pattern for defining Mailbox Actors, similar to Redux Ducks but for actors.

Install

npm install mailbox

Links

• 📖 Documentation & README
• 📦 NPM Package
• 🔗 API Reference

Special Thanks

Great thanks to @alxhotel who kindly transferred the mailbox NPM package name for this project!

---

"Mailbox is predictable states & transitions container for actors."
— Huan, Creator of Wechaty, Jan 2022

License

Apache-2.0 © 2021 Huan LI