@pocketactors/ax

An embeddable actor system for Node, shipped as a native addon. You write state machines in JavaScript; a small C runtime spawns them, routes their events, supervises their failures, and — when you ask for it — replays them from a journal after a restart. No build step, no compiler: npm install fetches the prebuilt binary for your platform.

npm install @pocketactors/ax

A first actor

Actors push. You send an actor an event, it runs its handler, and what it produces leaves through a port — a function you plug in. There is no getState to poll, because state never sits still waiting to be read; the actor emits when it has something to say.

import { System } from '@pocketactors/ax';

const sys = new System();

// A port is yours: the actor emits to it, you decide what that means.
sys.plug('out', (target, message) => {
  console.log(`-> ${target}:`, message);
});

// A machine is a tree of states. This one stays in `live` and, on a `go`
// event, emits the payload it received through the `out` port.
sys.define({
  name: 'echo',
  initial: 'live',
  states: {
    live: {
      on: { go: (actor, ev) => actor.emit('out', 'client', 'frame', ev.payload) },
    },
  },
});

const ref = sys.spawn('echo');
sys.post(ref, 'go', { payload: { hello: 'actors' } });
// -> client: { hello: 'actors' }

sys.close();

define registers a machine, spawn returns a handle to one running instance, and post delivers an event and pumps the runtime to quiescence. Inside a handler, actor.emit(port, target, kind, payload) sends a value out through a plugged port, and actor.send(to, event, data) reaches another actor.

Durability

Spawn an actor with { durable: true } and the runtime journals every event it receives. After a crash or a restart, replaying that journal rebuilds the actor's state — no snapshot, no second copy of the truth, just the inputs played back through the same handlers.

const counter = sys.spawn('counter', { durable: true, name: 'orders' });

Durability is compiled into every platform binary; nothing extra to install.

Supported platforms

| OS | Architecture | Durability | |---------|----------------|------------| | Linux | x64, arm64 | included | | macOS | x64, arm64 | included | | Windows | x64 | included |

The entrypoint resolves the matching @pocketactors/ax-<os>-<arch> package at install time and loads its binary at runtime. Install on an unlisted platform and the import throws, naming the target it could not find.

License

MIT. See LICENSE.