orbital-express: Skill for Claude Code

Add a background task

Tasks run in the worker process, not the request lifecycle. Naming: same as actions but append Task (V1ExportTask). Read README "Tasks Folder", "The Aggregate + Singular Task Pattern", "How a Job Gets Created".

Steps

1. Plan/sign-off: define job inputs, idempotency, trigger, side effects, worker wiring, and tests; get sign-off before scaffolding or edits. Preview/apply missing structure with yarn repair <Feature> --dry-run then yarn repair <Feature>.

2. Scaffold: yarn gen <Feature> -t V1<Action>Task. This validates names/targets first, exclusively creates the task + test, and deterministically rebuilds tasks/index.js. Existing source/test conflicts abort before any write. Never hand-create or pass .js.

3. Write the task (app/<Feature>/tasks/V1<Action>Task.js):

   • Receives a single job object; arguments come from job.data (not req.args).
   • JSDoc documents @job.data fields and Success.
   • Joi-validate job.data; on failure throw new Error(joiErrorsMessage(error)) (tasks throw — no errorResponse, no res).
   • Do work in a try; on success return true; on error throw (Bull marks the job failed → queueError).
   • // END V1<Action>Task.

4. Register the processor (manual — the generator can't): in app/<Feature>/worker.js add <Feature>Queue.process('V1<Action>Task', tasks.V1<Action>Task); and ensure the failed/stalled/error handlers exist. The root worker auto-discovers feature workers.

5. Enqueue it from wherever triggers it:

   • From an action: const q = queue.get('<Feature>Queue'); const job = await q.add('V1<Action>Task', data); return { status: 202, success: true, jobId: job.id };
   • From a cronjob (cronjobs.js) or another task (aggregate → singular fan-out).

6. Large datasets → Aggregate + Singular pattern: an aggregate task (V1CheckAllOrdersTask) queries targets and enqueues one singular task (V1CheckOrderTask) per record. Aggregate only fans out; all business logic lives in the singular task.