Actions

Actions are how clients & other actors communicate with actors. Actions are defined as functions in the actor configuration and can be called from clients.

​

Writing Actions

Actions are defined in the actions object when creating an actor:

import { actor } from "actor-core";

const mathUtils = actor({
  state: {},
  actions: {
    // This is an action
    multiplyByTwo: (c, x) => {
      return x * 2;
    }
  }
});

Each action receives a context object (commonly named c) as its first parameter, which provides access to state, connections, and other utilities. Additional parameters follow after that.

​

Private Helper Functions

You can define helper functions outside the actions object to keep your code organized. These functions cannot be called directly by clients:

import { actor } from "actor-core";

// Private helper function - not callable by clients
const calculateFee = (amount) => {
  return amount * 0.05;
};

const paymentProcessor = actor({
  state: { 
    transactions: [] 
  },
  actions: {
    // Public action - callable by clients
    processPayment: (c, amount) => {
      const fee = calculateFee(amount);
      // Process payment logic...
      c.state.transactions.push({ amount, fee });
      return { amount, fee };
    }
  }
});

​

Streaming Return Data

Actions have a single return value. To stream realtime data in response to an action, use events.

​

Calling Actions

Calling actions from the client is simple:

import { createClient } from "actor-core/client";
import type { App } from "./src/index";

const client = createClient<App>("http://localhost:6420");
const counter = await client.counter.get();
const result = await counter.increment(42);
console.log(result); // The value returned by the action

​

Type Safety

The actor client includes type safety out of the box. When you use createClient<App>(), TypeScript automatically infers action parameter and return types:

import { setup } from "actor-core";

// Create simple counter
const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, count: number) => {
      c.state.count += count;
      return c.state.count;
    }
  }
});

// Create and export the app
const app = setup({
  actors: { counter }
});

export type App = typeof app;

​

Error Handling

Actors provide robust error handling out of the box for actions.

​

User Errors

UserError can be used to return rich error data to the client. You can provide:

• A human-readable message
• A machine-readable code that’s useful for matching errors in a try-catch (optional)
• A metadata object for providing richer error context (optional)

For example:

import { actor, UserError } from "actor-core";

const user = actor({
  state: { users: [] },
  actions: {
    registerUser: (c, username) => {
      // Validate username
      if (username.length > 32) {
        // Throw a simple error with a message
        throw new UserError("Invalid username", {
          code: "invalid_username",
          meta: {
            maxLength: 32
          }
        });
      }
      
      // Rest of the user registration logic...
    }
  }
});

​

Internal Errors

All other errors will return an error with the code internal_error to the client. This helps keep your application secure, as errors can sometimes expose sensitive information.

​

Schema Validation

Data schemas are not validated by default. For production applications, use a library like zod to validate input types.

For example, to validate action parameters:

import { actor, UserError } from "actor-core";
import { z } from "zod";

// Define schema for action parameters
const IncrementSchema = z.object({
  count: z.number().int().positive()
});

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, params) => {
      // Validate parameters
      try {
        const { count } = IncrementSchema.parse(params);
        c.state.count += count;
        return c.state.count;
      } catch (err) {
        throw new UserError("Invalid parameters", { 
          code: "invalid_params",
          meta: { errors: err.errors }
        });
      }
    }
  }
});

​

Authentication

By default, clients can call all actions on an actor without restriction. Make sure to implement authentication if needed. Documentation on authentication is available here.

​

Using ActionContext Type Externally

When writing complex logic for actions, you may want to extract parts of your implementation into separate helper functions. When doing this, you’ll need a way to properly type the context parameter.

ActorCore provides the ActionContextOf utility type for exactly this purpose:

import { actor, ActionContextOf } from "actor-core";

const counter = actor({
  state: { count: 0 },
  
  actions: {
    increment: (c) => {
      return incrementCount(c);
    }
  }
});

// Simple helper function with typed context
function incrementCount(c: ActionContextOf<typeof counter>) {
  c.state.count += 1;
  return c.state.count;
}

See Helper Types for more details on using ActionContextOf and other type utilities.