Actions

Business operations callable from HTTP, CLI, workflows, or other actions.

Actions are the primary unit of business logic in Chimpbase. They are typed, validated operations that can be called from HTTP endpoints, CLI commands, workflows, or other actions.

Defining an Action

import { action, v } from "@chimpbase/runtime";

export const createProject = action({
  args: v.object({
    name: v.string(),
    description: v.string().optional(),
  }),
  async handler(ctx, input) {
    const [project] = await ctx.query<{ id: number }>(
      "insert into projects (name, description) values (?1, ?2) returning id",
      [input.name, input.description ?? null],
    );
    return project;
  },
});

Input Validation

Actions use the built-in v validator for input schemas:

v.string()              // string
v.number()              // number
v.boolean()             // boolean
v.object({ ... })       // object with typed fields
v.string().optional()   // optional field
v.string().nullable()   // nullable field
v.string().array()      // array of strings

Registering Actions

Actions are registered by name. When passed as a named export or object property, the key becomes the action name:

// Name inferred from the object key
chimpbase.register({ createProject, listProjects });

Calling Actions from Other Actions

Actions can invoke other registered actions through the context:

const setupWorkspace = action({
  args: v.object({ name: v.string() }),
  async handler(ctx, input) {
    const project = await ctx.action("createProject", [{ name: input.name }]);
    return project;
  },
});

Transaction Behavior

Actions run inside runtime-managed transactions. You do not need to wrap your queries in ctx.db().transaction() — in fact, it is intentionally unsupported.

Using Decorators

If you prefer a class-based style, use the @Action decorator:

import { Action } from "@chimpbase/runtime";

class ProjectModule {
  @Action({ args: v.object({ name: v.string() }) })
  async createProject(ctx, input) {
    // ...
  }
}

Collect decorator-based registrations with registrationsFrom(...).

Explicit Primitives
Why Chimpbase favours small, composable building blocks over framework magic.
Subscriptions
Internal pub/sub reactions with optional idempotency.