actions-events

Actions + events

Business logic lives in actions; cross-cutting effects run through events. Controllers stay thin (policy → validate → action → response). Actions take a plain input, never HttpContext. When an action needs a side effect (mail, notification, transmit, external HTTP), it emits a domain event; a listener in the module's start/events.ts receives it and runs the effect. This keeps actions synchronous domain code, keeps side effects composable (a new listener is a new file, not an edit to the action), and makes testing effortless — fake the emitter, fake the mail.

Rules

• Location: app/<mod>/actions/<verb_noun>.ts — one file per action.

• Shape: default-export a class with a single public method async handle(input): Promise<Result | void>. input is a plain interface. No HttpContext.

• Return or throw: return the primary value (a model, an id, void). Throw domain exceptions from app/<mod>/exceptions/ for expected failure paths (rate limits, permission denials, invariant violations).

• Side effects go through events. Anything that reaches out is emitted, not called inline:

  emitter.emit('user:registered', { user, token })
  

  This applies to every kind of effect without exception:

  Kind	Example call the action must not make
  Mail	mail.send(new WelcomeEmail(...))
  In-app notification	facteur.notification(...).send()
  SSE / realtime broadcast	transmit.broadcast(channel, payload)
  External HTTP	fetch('https://api.stripe.com/...')
  Audit log write	any write to an audits / activity_logs table that's cross-cutting

• Listeners live in app/<mod>/start/events.ts. Register with emitter.on('event:name', async (data) => { ... }). Preload the file from adonisrc.ts so it wires at boot (see [[module-scaffolding]]).

• Guards as helper functions at the top of the action file — e.g. requireManageRoles(executor) throws if not permitted. Keeps the action body short and the guard reusable across actions.

• Controllers call actions: await new Action().handle(input). Never instantiate an action inside another action; if two actions need shared work, extract a service (behavior with side effects) or a query (read-only).