Commands

Registering a task or renaming it should not require a hand-written route, body parser, validation response, and status-code mapping per endpoint. In Arc, a command is a class that carries the input and handles itself. Arc supplies the endpoint, the pipeline, the result envelope, and, through the proxy generator, a typed frontend client.

Arc is a CQRS framework, not an event store. A command’s handle() can call a service, write through a storage integration, or return a value. It does not have to produce an event or use Chronicle.

A command

Features/Tasks/Registration/Registration.ts

import { field } from '@cratis/fundamentals';
import { command } from '@cratis/arc.core';
import { TaskId } from '../TaskId.js';
import { TaskTitle } from '../TaskTitle.js';
import { Tasks } from '../Tasks.js';

@command()
export class RegisterTask {
    @field(TaskId) id!: TaskId;
    @field(TaskTitle) title!: TaskTitle;

    handle(tasks: Tasks): TaskId {
        tasks.register(this.id, this.title);
        return this.id;
    }
}

This is the Tasks sample command. The sample’s generated metadata binds the tasks parameter to the Tasks service; without it, mark handle() with @inject(Tasks). Your first command walks through it with its imports.

Find your way

Page	Use it when you want to
Model-bound commands	Declare fields, handle(), and provide(), and control a command’s route
Command authorization	Restrict a command with roles, policies, or anonymous access
Command validation	Add rules with CommandValidator before handle() runs
Validation severity filtering	Let warnings pass or block, per request
Command pipeline	Understand the order in which every check runs
Command outcomes	Return a response, reject, or deny from provide() and handle()
Response value handlers	Process extra return values on the server
Command context	Read the key, values, and request identity; bind the signal and context
Command execution scopes	Run code around provide() and handle(), such as a unit of work
Command operations	Declare side effects that Arc executes and compensates
Command filters	Validate low-level definitions with validate and filters
Low-level definitions	Keep Zod-backed defineCommand and defineQuery
Calling commands from code	Run a command or query from a job, a spec, or a Fetch API host

To append events from a command, see the experimental Chronicle integration.