statelyai/xactor

_{The Actor Model for JavaScript}

🚧 Work in progress! 🚧

XActor is an actor model implementation for JavaScript and TypeScript, heavily inspired by Akka. It represents the "actor model" parts of XState and can be used with or without XState.

Resources

Learn more about the Actor Model:

• The Actor Model in 10 Minutes
• 🎥 The Actor Model Explained
• What is the Actor Model and When Should You Use It?
• 📄 ACTORS: A Model of Concurrent Computation in Distributed Systems (Gul Agha)
• 📄 A Universal Modular ACTOR Formalism for Artificial Intelligence (Carl Hewitt et. al.

Installation

• With npm: npm install xactor --save
• With Yarn: yarn add xactor

Quick Start

Simple Example:

import { createSystem, createBehavior } from 'xactor';

// Yes, I know, another trivial counter example
const counter = createBehavior(
  (state, message, context) => {
    if (message.type === 'add') {
      context.log(`adding ${message.value}`);

      return {
        ...state,
        count: state.count + message.value,
      };
    }

    return state;
  },
  { count: 0 }
);

const counterSystem = createSystem(counter, 'counter');

counterSystem.subscribe(state => {
  console.log(state);
});

counterSystem.send({ type: 'add', value: 3 });
// => [counter] adding 3
// => { count: 3 }
counterSystem.send({ type: 'add', value: 1 });
// => [counter] adding 1
// => { count: 4 }

API

createBehavior(reducer, initialState)

Creates a behavior that is represented by the reducer and starts at the initialState.

Arguments

• reducer - a reducer that takes 3 arguments (state, message, actorContext) and should return the next state (tagged or not).
• initialState - the initial state of the behavior.

Reducer Arguments

• state - the current untagged state.
• message - the current message to be processed by the reducer.
• actorContext - the actor context of the actor instance using this behavior.

Actor Context

The actor context is an object that includes contextual information about the current actor instance:

• self - the ActorRef reference to the own actor
• system - the reference to the actor system that owns this actor
• log - function for logging messages that reference the actor
• spawn - function to spawn an actor
• stop - function to stop a spawned actor
• watch - function to watch an actor

Spawning Actors

Actors can be spawned via actorContext.spawn(behavior, name) within a behavior reducer:

const createTodo = (content = "") => createBehavior((state, msg, ctx) => {
  // ...
  
  return state;
}, { content });

const todos = createBehavior((state, msg, ctx) => {
  if (msg.type === 'todo.create') {
    return {
      ...state,
      todos: [
        ...state.todos,
        ctx.spawn(createTodo(), 'some-unique-todo-id')
      ]
    }
  }
  
  // ...
  
  return state;
}, { todos: [] });

const todoSystem = createSystem(todos, 'todos');

todoSystem.send({ type: 'todo.create' });

Documentation still a work-in-progress! Please see the tests for now as examples.