Skip to content

index.md

Latest commit

 

History

History
61 lines (50 loc) · 3.55 KB

index.md

File metadata and controls

61 lines (50 loc) · 3.55 KB
Raw
title Commands
description Change application state with Arc commands, and find the pages for validation, outcomes, context, operations, and calling commands from code.

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.

flowchart LR
    Client -->|POST| Endpoint[Arc route]
    Endpoint --> Checks[Authentication, authorization, validation]
    Checks --> Handle[provide, then handle]
    Handle --> Values[Response values and operations]
    Values --> Result[CommandResult]
    Result --> Client
Loading

A command

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.