NodeAkt is an actor runtime for Node.js, Bun, and Deno. An actor owns private state and a mailbox. The runtime delivers one message at a time, so that state needs no lock. Actors talk only by sending messages. The whole runtime, the multi-core layer and the network protocol included, has zero dependencies: installing it brings exactly one package.
Requires Node.js 22+, Bun 1.3+, or Deno 2+. ESM only (import, not require). Every runtime is exercised in CI, multi-core placement included.
- Actor system. One logical runtime per process that owns every actor's lifecycle, from startup through graceful shutdown.
- Typed messages. Messages are plain classes, so a handler narrows them with ordinary type checks. Send and forget when no answer is needed, or ask and await a typed reply.
- Hierarchy. Actors spawn children and watch any other actor, receiving a message when the watched one stops. Stopping a parent drains its whole subtree cleanly.
- Behaviors and stash. An actor can swap its message handler at runtime, set aside messages it cannot serve yet, and replay them once it switches back.
- Supervision. When an actor fails, its parent decides: stop it, resume it, restart it, or escalate, for the one child or for all of them, with restart budgets and exponential backoff.
- Routers. Spread work over a pool of identical actors or broadcast to all of them: round robin, random, fan-out, and consistent-hash routing. The router supervises its routees, the pool resizes in place, and replies go straight back to the original sender.
- Mailboxes. Unbounded and bounded FIFO, segmented, fair per-sender, and priority variants, or bring your own implementation.
- Passivation. Actors live as long as you need them: keep them forever, or retire them automatically after an idle timeout or a processed-message count.
- Reentrancy. An actor can keep working through its mailbox while one of its own requests is still in flight, with control over which messages may overtake the pending reply.
- Pipe to. The result of any promise can be delivered to an actor's mailbox as an ordinary message once it settles; failures and timeouts become dead letters instead of crashing the actor.
- Scheduling. Send a message to an actor after a delay or on a repeating interval, and cancel, pause, or resume it by reference. A schedule created inside an actor is cancelled automatically when that actor stops.
- Event stream. Subscribe to what the runtime observes: dead letters and actor lifecycle events such as started, stopped, restarted, and passivated.
- Logging. Structured JSON logging out of the box, or silence the runtime entirely.
- Multi-core. Spawn actors across every machine core without touching workers or threads yourself. An actor's address works the same locally and across cores, on Node.js, Bun, and Deno alike.
- Remoting. Look up, spawn, watch, and message actors on another machine over TCP with the same PID API: tell, ask, request, forward, pipeTo, and death watch all cross nodes, with typed messages and identical failure semantics.
The full API is in Documentation.
npm install @tochemey/nodeaktpnpm add @tochemey/nodeaktyarn add @tochemey/nodeaktbun add @tochemey/nodeaktdeno add npm:@tochemey/nodeaktThen import from the package:
import { ActorSystem } from "@tochemey/nodeakt";Then head to Getting started for a first actor.
- Documentation: getting started, the tour, and the full reference (source pages in docs/)
- Examples: small programs that match those pages
- Benchmarks: tell and ask throughput, memory density, multi-core scaling
- Contributing: setup, conventions, and what a change needs to merge
- Stable. A stable release is cut by pushing a version tag. The release pipeline folds the accumulated changesets into
CHANGELOG.md, publishes to npm aslatestwith provenance, and creates the GitHub release from the changelog. - Nightly. Every green push to
mainpublishes a build to npm under thenightlydist-tag, versionedX.Y.Z-nightly.<date>.<sha>. Install it withpnpm add @tochemey/nodeakt@nightly. Nightlies never touchlatest.