Skip to content

Model-bound commands

Keep the intent and its decision together. A command is a named Go struct, and its receiver is the decoded command, not a DI-created handler object.

Declaration excerpt, with context imported:

type Greet struct {
Name string `json:"name"`
}
func (c Greet) Handle(context.Context) (string, error) {
return "Hello, " + c.Name, nil
}

The method remains ordinary Go. Calling it directly bypasses the pipeline; use pipeline execution when you need authorization, validation, resources, or returned effects.

Composition excerpt using this declaration and the commands package:

var registry commands.Registry
err := commands.Register(&registry, commands.Handle(Greet.Handle))

Check err before building. The adapter carries the exact receiver and raw return type; registration does not invoke the method. The executable ExampleHandle in commands/example_test.go builds a real pipeline and prints true true Hello, Ada.

Use type-only registration for void methods

Section titled “Use type-only registration for void methods”

commands.Register[ClearLocalCache](&registry) needs no adapter when ClearLocalCache implements exactly Handle(context.Context) error. A value registration never synthesizes a pointer receiver. Pointer and value registrations are exact, distinct types; give them distinct public identities if you register both.

Go cannot infer an arbitrary method return type from the command type alone. Result-bearing methods therefore use Handle(C.Handle). Methods with services use a closure, Invoke, or Scoped. The compiled examples cover each approach without a container.

WithProvide(C.Provide, C.Handle) passes one exact typed payload to Handle after authorization and input validation. Multiple prepared dependencies belong in an application struct. A supplied nil pointer remains an explicit payload; it never falls back to DI.

Use WithPreparation when Provide needs controls: Provided carries a usable payload, ProvidedWith adds a verdict, and StopProviding always skips Handle, including successful early termination. Zero Preparation fails with ErrInvalidPreparation. Provide errors never fabricate a payload. Validate invokes neither stage.

A matching Validate(context.Context) ([]validation.Result, error) runs automatically through the validation graph. This is a Go convention, not a claim that C# invokes a command Validate method. Tags such as validate:"required" describe supported input rules; validation defines their limits.

Public identity defaults to the named type and the registry’s explicitly configured namespace, or global. Never derive routes from a Go import path. Pin migrations with WithDescriptor; individual metadata options override it regardless of option order. Repeated singular options and multiple handlers fail.

An optional blank declaration field can carry runtime-readable metadata:

type PublishItem struct {
_ struct{} `json:"-" arc:"command,name=PublishItem,path=/items/publish" authorize:"roles=Editor|Admin"`
ID string `json:"id" arc:"key"`
}

This excerpt declares metadata only; supply a supported Handle method or adapter before registering it. Declaration authorization uses the same compiler as explicit options. See authorization before exposing the command.