cfw-autumn/.claude/skills/workflows/references/HATCHET.md

Hatchet Workflows

For complex workflows needing retries, multi-step, typed outputs, or long delays.

Workflow Definition

// server/src/internal/.../workflows/myWorkflow/myWorkflow.ts

import { hatchet } from "@/external/hatchet/initHatchet.js";
import { createWorkflowTask } from "@/queue/hatchetWorkflows/createWorkflowTask.js";
import { JobName } from "@/queue/JobName.js";

// 1. Define input/output types
export type MyWorkflowInput = {
  orgId: string;
  env: AppEnv;
  customerId: string;
};

type MyWorkflowOutput = {
  myTask: {
    success: boolean;
    message: string;
  };
};

// 2. Create workflow (only if Hatchet enabled)
export const myWorkflow = hatchet?.workflow<MyWorkflowInput, MyWorkflowOutput>({
  name: JobName.MyWorkflow,
});

// 3. Define task
myWorkflow?.task({
  name: JobName.MyWorkflow,
  executionTimeout: "60s",
  fn: createWorkflowTask<MyWorkflowInput, MyWorkflowOutput["myTask"]>({
    handler: async ({ input, autumnContext }) => {
      const { customerId } = input;
      
      // Your logic here
      autumnContext.logger.info(`Processing ${customerId}`);
      
      return {
        success: true,
        message: "Completed",
      };
    },
  }),
});

Register Worker

// server/src/queue/initWorkers.ts

import { myWorkflow } from "@/internal/.../workflows/myWorkflow/myWorkflow.js";

export const initHatchetWorker = async () => {
  if (!hatchet) return;

  const worker = await hatchet.worker("hatchet-worker", {
    workflows: [
      verifyCacheConsistency!,
      myWorkflow!,  // Add here
    ],
  });

  worker.start().catch(console.error);
};

Register in queueUtils.ts

// server/src/queue/queueUtils.ts

import { myWorkflow } from "@/internal/.../workflows/myWorkflow/myWorkflow.js";

const hatchetWorkflows: Record<JobName, any> = {
  [JobName.VerifyCacheConsistency]: verifyCacheConsistency,
  [JobName.MyWorkflow]: myWorkflow,  // Add here
};

Triggering with Options

await workflows.triggerMyWorkflow(payload, {
  delayMs: 5000,
  metadata: {
    workflowId: generateId("workflow"),
    customerId,
  },
});

createWorkflowTask Helper

Provides:

• Automatic AutumnContext creation from input
• Error handling with Sentry integration
• Workflow logging context

createWorkflowTask<TInput, TOutput>({
  handler: async ({ input, autumnContext }) => {
    // input: Your typed input
    // autumnContext: Full AutumnContext with logger, db, org, env, etc.
    return output;
  },
})

Checklist

1. ☐ Add to JobName.ts
2. ☐ Define payload type in workflows.ts
3. ☐ Add to workflowRegistry with runner: "hatchet"
4. ☐ Add trigger function to workflows export
5. ☐ Create workflow file with hatchet?.workflow() + .task()
6. ☐ Add to hatchetWorkflows map in queueUtils.ts
7. ☐ Add to initHatchetWorker workflows array

SQS vs Hatchet

Feature	SQS	Hatchet
Setup complexity	Lower	Higher
Typed output	No	Yes
Multi-step tasks	No	Yes
Configurable timeout	30s visibility	Per-task
Max delay	15 minutes	Unlimited
Observability	CloudWatch	Hatchet UI