@nicnocquee/dataqueue 1.26.0-beta.20260223202259 → 1.26.0-beta.20260223204425

package/ai/docs-content.json

@@ -45,7 +45,7 @@
     "slug": "api/job-record",
     "title": "JobRecord",
     "description": "",
-    "content": "The `JobRecord` interface represents a job stored in the queue, including its status, attempts, and metadata.\n\n## Fields\n\n- `id`: _number_ — Unique job ID.\n- `jobType`: _string_ — The type of the job.\n- `payload`: _any_ — The job payload.\n- `status`:\n  _'pending' | 'processing' | 'completed' | 'failed' | 'cancelled'_ —\n  Current job status.\n- `createdAt`: _Date_ — When the job was created.\n- `updated_at`: _Date_ — When the job was last updated.\n- `locked_at`: _Date | null_ — When the job was locked for\n  processing.\n- `locked_by`: _string | null_ — Worker that locked the job.\n- `attempts`: _number_ — Number of attempts so far.\n- `maxAttempts`: _number_ — Maximum allowed attempts.\n- `nextAttemptAt`: _Date | null_ — When the next attempt is\n  scheduled.\n- `priority`: _number_ — Job priority.\n- `runAt`: _Date_ — When the job is scheduled to run.\n- `pendingReason?`: _string | null_ — Reason for pending\n  status.\n- `errorHistory?`: _\\{ message: string; timestamp: string \\}[]_ — Error history for the job.\n- `timeoutMs?`: _number | null_ — Timeout for this job in\n  milliseconds.\n- `failureReason?`: _FailureReason | null_ — Reason for last\n  failure, if any.\n- `completedAt`: _Date | null_ — When the job was completed.\n- `startedAt`: _Date | null_ — When the job was first picked up\n  for processing.\n- `lastRetriedAt`: _Date | null_ — When the job was last\n  retried.\n- `lastFailedAt`: _Date | null_ — When the job last failed.\n- `lastCancelledAt`: _Date | null_ — When the job was last\n  cancelled.\n- `tags?`: _string[]_ — Tags for this job. Used for grouping, searching, or batch operations.\n- `idempotencyKey?`: _string | null_ — The idempotency key for this job, if one was provided when the job was created.\n- `progress?`: _number | null_ — Progress percentage (0–100) reported by the handler via `ctx.setProgress()`. `null` if no progress has been reported. See [Progress Tracking](/usage/progress-tracking).\n\n## Example\n\n```json\n{\n  \"id\": 1,\n  \"jobType\": \"email\",\n  \"payload\": { \"to\": \"user@example.com\", \"subject\": \"Hello\" },\n  \"status\": \"pending\",\n  \"createdAt\": \"2024-06-01T12:00:00Z\",\n  \"tags\": [\"welcome\", \"user\"],\n  \"idempotencyKey\": \"welcome-email-user-123\",\n  \"progress\": null\n}\n```"
+    "content": "The `JobRecord` interface represents a job stored in the queue, including its status, attempts, and metadata.\n\n## Fields\n\n- `id`: _number_ — Unique job ID.\n- `jobType`: _string_ — The type of the job.\n- `payload`: _any_ — The job payload.\n- `status`:\n  _'pending' | 'processing' | 'completed' | 'failed' | 'cancelled'_ —\n  Current job status.\n- `createdAt`: _Date_ — When the job was created.\n- `updated_at`: _Date_ — When the job was last updated.\n- `locked_at`: _Date | null_ — When the job was locked for\n  processing.\n- `locked_by`: _string | null_ — Worker that locked the job.\n- `attempts`: _number_ — Number of attempts so far.\n- `maxAttempts`: _number_ — Maximum allowed attempts.\n- `nextAttemptAt`: _Date | null_ — When the next attempt is\n  scheduled.\n- `priority`: _number_ — Job priority.\n- `runAt`: _Date_ — When the job is scheduled to run.\n- `pendingReason?`: _string | null_ — Reason for pending\n  status.\n- `errorHistory?`: _\\{ message: string; timestamp: string \\}[]_ — Error history for the job.\n- `timeoutMs?`: _number | null_ — Timeout for this job in\n  milliseconds.\n- `failureReason?`: _FailureReason | null_ — Reason for last\n  failure, if any.\n- `completedAt`: _Date | null_ — When the job was completed.\n- `startedAt`: _Date | null_ — When the job was first picked up\n  for processing.\n- `lastRetriedAt`: _Date | null_ — When the job was last\n  retried.\n- `lastFailedAt`: _Date | null_ — When the job last failed.\n- `lastCancelledAt`: _Date | null_ — When the job was last\n  cancelled.\n- `tags?`: _string[]_ — Tags for this job. Used for grouping, searching, or batch operations.\n- `idempotencyKey?`: _string | null_ — The idempotency key for this job, if one was provided when the job was created.\n- `progress?`: _number | null_ — Progress percentage (0–100) reported by the handler via `ctx.setProgress()`. `null` if no progress has been reported. See [Progress Tracking](/usage/progress-tracking).\n- `output?`: _unknown_ — Handler output stored via `ctx.setOutput(data)` or by returning a value from the handler. `null` if no output has been stored. See [Job Output](/usage/job-output).\n\n## Example\n\n```json\n{\n  \"id\": 1,\n  \"jobType\": \"email\",\n  \"payload\": { \"to\": \"user@example.com\", \"subject\": \"Hello\" },\n  \"status\": \"completed\",\n  \"createdAt\": \"2024-06-01T12:00:00Z\",\n  \"tags\": [\"welcome\", \"user\"],\n  \"idempotencyKey\": \"welcome-email-user-123\",\n  \"progress\": 100,\n  \"output\": { \"messageId\": \"abc-123\", \"sentAt\": \"2024-06-01T12:00:05Z\" }\n}\n```"
   },
   {
     "slug": "api/processor",
@@ -227,6 +227,12 @@
     "description": "",
     "content": "The first thing you need to do is define your job types and their corresponding payload types. A payload is the data passed to the job handler. A job handler is a function that runs when a job is processed.\n\n### Define Job Types and Payloads\n\nJob types and their payloads are specific to your app. You can define them in any file. The important thing is that they are an object type, where the keys are the job types and the values are the payload types. In this example, `send_email`, `generate_report`, and `generate_image` are the job types, and their values are the payload types.\n\n```typescript title=\"@lib/types/job-payload-map.ts\"\n// Define the job payload map for this app.\n// This ensures that the job payload is typed correctly when adding jobs.\n// The keys are the job types, and the values are the payload types.\nexport type JobPayloadMap = {\n  send_email: {\n    to: string;\n    subject: string;\n    body: string;\n  };\n  generate_report: {\n    reportId: string;\n    userId: string;\n  };\n  generate_image: {\n    prompt: string;\n  };\n};\n```\n\n### Define Job Handlers\n\nNext, define the job handlers by exporting a `JobHandlers` object that maps job types to handler functions. If you forget to add a handler for a job type, TypeScript will show an error.\n\n```typescript title=\"@lib/job-handlers.ts\"\nimport { sendEmail } from './services/email'; // Function to send the email\nimport { generateReport } from './services/generate-report'; // Function to generate the report\nimport { JobHandlers } from '@nicnocquee/dataqueue';\n\nexport const jobHandlers: JobHandlers<JobPayloadMap> = {\n  send_email: async (payload) => {\n    const { to, subject, body } = payload;\n    await sendEmail(to, subject, body);\n  },\n  generate_report: async (payload) => {\n    const { reportId, userId } = payload;\n    await generateReport(reportId, userId);\n  },\n  generate_image: async (payload, signal) => {\n    const { prompt } = payload;\n    await generateImageAi(prompt, signal);\n  },\n};\n```\n\nIn the example above, we define three job handlers: `send_email`, `generate_report`, and `generate_image`. Each handler is a function that takes a payload, an `AbortSignal`, and a `JobContext` as arguments. The `AbortSignal` is used to abort the job if it takes too long to complete. The `JobContext` provides methods to extend the job's timeout while it's running.\n\n### Job Handler Signature\n\nA job handler receives three arguments: the job payload, an `AbortSignal`, and a `JobContext`.\n\n```typescript\n(payload: Payload, signal: AbortSignal, ctx: JobContext) => Promise<void>;\n```\n\nYou can omit arguments you don't need. For example, if you only need the payload:\n\n```typescript\nconst handler = async (payload) => {\n  // ...\n};\n```\n\n### JobContext\n\nThe third argument provides methods for timeout management and progress reporting:\n\n- `ctx.prolong(ms?)` — Proactively reset the timeout. If `ms` is provided, sets the deadline to `ms` milliseconds from now. If omitted, resets to the original `timeoutMs`.\n- `ctx.onTimeout(callback)` — Register a callback that fires when the timeout is about to hit, before the `AbortSignal` is triggered. Return a number (ms) to extend, or return nothing to let the timeout proceed.\n- `ctx.setProgress(percent)` — Report progress as a percentage (0–100). The value is persisted to the database and can be read by clients via `getJob()` or the React SDK's `useJob()` hook.\n\nSee [Job Timeout](/usage/job-timeout) for timeout examples and [Progress Tracking](/usage/progress-tracking) for progress reporting."
   },
+  {
+    "slug": "usage/job-output",
+    "title": "Job Output",
+    "description": "Store and retrieve results from job handlers",
+    "content": "Jobs can store an output value when they complete. This is useful when you need to retrieve the result of a background task — for example, a generated report URL, a processed image path, or computation results.\n\n## Storing Output\n\nThere are two ways to store output from a handler:\n\n### 1. Return a value from the handler\n\nThe simplest approach — return any JSON-serializable value from your handler function:\n\n```typescript title=\"@lib/job-handlers.ts\"\nimport { JobHandlers } from '@nicnocquee/dataqueue';\n\nexport const jobHandlers: JobHandlers<JobPayloadMap> = {\n  generate_report: async (payload, signal, ctx) => {\n    const url = await generateReport(payload.reportId);return { url, generatedAt: new Date().toISOString() };},\n};\n```\n\n### 2. Use `ctx.setOutput(data)`\n\nFor more control, call `ctx.setOutput()` explicitly. This is useful when you want to store intermediate results during execution:\n\n```typescript title=\"@lib/job-handlers.ts\"\nexport const jobHandlers: JobHandlers<JobPayloadMap> = {\n  process_images: async (payload, signal, ctx) => {\n    const results: string[] = [];\n\n    for (const image of payload.images) {\n      const url = await processImage(image);\n      results.push(url);\n\n      await ctx.setProgress(\n        Math.round((results.length / payload.images.length) * 100),\n      );\n      await ctx.setOutput({ processedUrls: results });}\n  },\n};\n```\n\n### Precedence\n\nIf both `ctx.setOutput()` is called **and** the handler returns a value, the `ctx.setOutput()` value takes precedence. The handler's return value is ignored in that case.\n\n### Rules\n\n- **JSON-serializable**: The output value must be JSON-serializable (objects, arrays, strings, numbers, booleans, null).\n- **Last write wins**: Calling `ctx.setOutput()` multiple times overwrites the previous value.\n- **Best-effort persistence**: Like `setProgress`, output writes to the database are best-effort — errors do not kill the handler.\n\n## Reading Output\n\nOutput is stored in the `output` field of the [JobRecord](/api/job-record):\n\n```typescript\nconst job = await jobQueue.getJob(jobId);\nconsole.log(job?.output); // null | any JSON value\n```\n\n- Before the handler stores output, the value is `null`.\n- After the job completes, the output is preserved and can be read at any time.\n- Handlers that return `undefined` (or `void`) do not store output — the field remains `null`.\n\n## Tracking Output in React\n\nIf you're using the [React SDK](/usage/react-sdk), the `useJob` hook exposes `output` directly:\n\n```tsx\nimport { useJob } from '@nicnocquee/dataqueue-react';\n\nfunction JobResult({ jobId }: { jobId: number }) {\n  const { status, output, progress } = useJob(jobId, {\n    fetcher: (id) =>\n      fetch(`/api/jobs/${id}`)\n        .then((r) => r.json())\n        .then((d) => d.job),\n  });\n\n  if (status === 'completed' && output) {\n    return <a href={(output as any).url}>Download Report</a>;\n  }\n\n  return (\n    <div>\n      <p>Status: {status}</p>\n      <progress value={progress ?? 0} max={100} />\n    </div>\n  );\n}\n```\n\n## Listening for Output Events\n\nYou can subscribe to the `job:output` event to be notified whenever a handler calls `ctx.setOutput()`:\n\n```typescript\njobQueue.on('job:output', ({ jobId, output }) => {\n  console.log(`Job ${jobId} stored output:`, output);\n});\n```\n\n## Database Migration\n\n> **Note:** If you're using the **PostgreSQL** backend, make sure to run the latest\n  migrations to add the `output` column. See [Database\n  Migration](/usage/database-migration).\n\nThe Redis backend requires no migration — the `output` field is stored automatically as part of the job hash."
+  },
   {
     "slug": "usage/job-timeout",
     "title": "Job Timeout",
@@ -249,7 +255,7 @@
     "slug": "usage/progress-tracking",
     "title": "Progress Tracking",
     "description": "Report and track job progress from handlers",
-    "content": "Jobs can report their progress as a percentage (0–100) while they run. This is useful for long-running tasks like file processing, data imports, or image generation where you want to show a progress bar or percentage to the user.\n\n## Reporting Progress from a Handler\n\nUse `ctx.setProgress(percent)` inside your job handler to report progress:\n\n```typescript title=\"@lib/job-handlers.ts\"\nimport { JobHandlers } from '@nicnocquee/dataqueue';\n\nexport const jobHandlers: JobHandlers<JobPayloadMap> = {\n  generate_report: async (payload, signal, ctx) => {\n    const chunks = await loadData(payload.reportId);\n\n    for (let i = 0; i < chunks.length; i++) {\n      if (signal.aborted) return;\n\n      await processChunk(chunks[i]);\n\n      // Report progress (0-100)\n      await ctx.setProgress(Math.round(((i + 1) / chunks.length) * 100));\n    }\n  },\n};\n```\n\n### setProgress Rules\n\n- **Range**: The value must be between 0 and 100 (inclusive). Values outside this range throw an error.\n- **Rounding**: Fractional values are rounded to the nearest integer (`33.7` becomes `34`).\n- **Best-effort persistence**: Progress is written to the database but errors during the write do not kill the handler — processing continues.\n\n## Reading Progress\n\nProgress is stored in the `progress` field of the [JobRecord](/api/job-record):\n\n```typescript\nconst job = await jobQueue.getJob(jobId);\nconsole.log(job?.progress); // null | 0–100\n```\n\n- Before the handler calls `setProgress`, the value is `null`.\n- After the job completes, the last progress value is preserved (typically `100`).\n\n## Tracking Progress in React\n\nIf you're using the [React SDK](/usage/react-sdk), the `useJob` hook exposes `progress` directly:\n\n```tsx\nimport { useJob } from '@nicnocquee/dataqueue-react';\n\nfunction JobProgress({ jobId }: { jobId: number }) {\n  const { status, progress } = useJob(jobId, {\n    fetcher: (id) =>\n      fetch(`/api/jobs/${id}`)\n        .then((r) => r.json())\n        .then((d) => d.job),\n  });\n\n  return (\n    <div>\n      <p>Status: {status}</p>\n      <progress value={progress ?? 0} max={100} />\n      <span>{progress ?? 0}%</span>\n    </div>\n  );\n}\n```\n\n## Database Migration\n\n> **Note:** If you're using the **PostgreSQL** backend, make sure to run the latest\n  migrations to add the `progress` column. See [Database\n  Migration](/usage/database-migration).\n\nThe Redis backend requires no migration — the `progress` field is stored automatically as part of the job hash."
+    "content": "Jobs can report their progress as a percentage (0–100) while they run. This is useful for long-running tasks like file processing, data imports, or image generation where you want to show a progress bar or percentage to the user.\n\n## Reporting Progress from a Handler\n\nUse `ctx.setProgress(percent)` inside your job handler to report progress:\n\n```typescript title=\"@lib/job-handlers.ts\"\nimport { JobHandlers } from '@nicnocquee/dataqueue';\n\nexport const jobHandlers: JobHandlers<JobPayloadMap> = {\n  generate_report: async (payload, signal, ctx) => {\n    const chunks = await loadData(payload.reportId);\n\n    for (let i = 0; i < chunks.length; i++) {\n      if (signal.aborted) return;\n\n      await processChunk(chunks[i]);\n\n      // Report progress (0-100)\n      await ctx.setProgress(Math.round(((i + 1) / chunks.length) * 100));\n    }\n  },\n};\n```\n\n### setProgress Rules\n\n- **Range**: The value must be between 0 and 100 (inclusive). Values outside this range throw an error.\n- **Rounding**: Fractional values are rounded to the nearest integer (`33.7` becomes `34`).\n- **Best-effort persistence**: Progress is written to the database but errors during the write do not kill the handler — processing continues.\n\n## Reading Progress\n\nProgress is stored in the `progress` field of the [JobRecord](/api/job-record):\n\n```typescript\nconst job = await jobQueue.getJob(jobId);\nconsole.log(job?.progress); // null | 0–100\n```\n\n- Before the handler calls `setProgress`, the value is `null`.\n- After the job completes, the last progress value is preserved (typically `100`).\n\n## Tracking Progress in React\n\nIf you're using the [React SDK](/usage/react-sdk), the `useJob` hook exposes `progress` directly:\n\n```tsx\nimport { useJob } from '@nicnocquee/dataqueue-react';\n\nfunction JobProgress({ jobId }: { jobId: number }) {\n  const { status, progress } = useJob(jobId, {\n    fetcher: (id) =>\n      fetch(`/api/jobs/${id}`)\n        .then((r) => r.json())\n        .then((d) => d.job),\n  });\n\n  return (\n    <div>\n      <p>Status: {status}</p>\n      <progress value={progress ?? 0} max={100} />\n      <span>{progress ?? 0}%</span>\n    </div>\n  );\n}\n```\n\n## Database Migration\n\n> **Note:** If you're using the **PostgreSQL** backend, make sure to run the latest\n  migrations to add the `progress` column. See [Database\n  Migration](/usage/database-migration).\n\nThe Redis backend requires no migration — the `progress` field is stored automatically as part of the job hash.\n\n## Related\n\n- [Job Output](/usage/job-output) — Store and retrieve results from job handlers using `ctx.setOutput()` or handler return values."
   },
   {
     "slug": "usage/quick-start",

package/ai/rules/advanced.md

@@ -130,7 +130,7 @@ queue.on('job:failed', ({ jobId, jobType, error, willRetry }) => {
 queue.on('error', (error) => Sentry.captureException(error));
 ```
 
-Events: `job:added`, `job:processing`, `job:completed`, `job:failed` (with `willRetry`), `job:cancelled`, `job:retried`, `job:waiting`, `job:progress`, `error`.
+Events: `job:added`, `job:processing`, `job:completed`, `job:failed` (with `willRetry`), `job:cancelled`, `job:retried`, `job:waiting`, `job:progress`, `job:output`, `error`.
 
 `error` events fire alongside `onError` callbacks in `ProcessorOptions` / `SupervisorOptions` — both mechanisms work independently.
 
@@ -148,3 +148,23 @@ await ctx.setProgress(50); // 0–100, persisted to DB
 ```
 
 Read via `queue.getJob(id)` (`progress` field) or React SDK's `useJob` hook.
+
+## Job Output
+
+Store results via `ctx.setOutput(data)` or by returning a value from the handler:
+
+```typescript
+// Option 1: return a value
+const handler = async (payload, signal, ctx) => {
+  const result = await doWork(payload);
+  return { url: result.downloadUrl };
+};
+
+// Option 2: ctx.setOutput (takes precedence over return value)
+const handler = async (payload, signal, ctx) => {
+  const result = await doWork(payload);
+  await ctx.setOutput({ url: result.downloadUrl });
+};
+```
+
+Read via `queue.getJob(id)` (`output` field) or React SDK's `useJob` hook (`output` property).

package/ai/rules/react-dashboard.md

@@ -10,7 +10,7 @@ Install: `npm install @nicnocquee/dataqueue-react` (requires React 18+).
 'use client';
 import { useJob } from '@nicnocquee/dataqueue-react';
 
-const { status, progress, data, isLoading, error } = useJob(jobId, {
+const { status, progress, output, data, isLoading, error } = useJob(jobId, {
   fetcher: (id) =>
     fetch(`/api/jobs/${id}`)
       .then((r) => r.json())
@@ -81,3 +81,7 @@ Wrap handlers with your auth middleware before exporting GET/POST.
 ## Progress Tracking
 
 Use `ctx.setProgress(percent)` in handlers (0–100). The value appears in `useJob`'s `progress` field and the dashboard detail view.
+
+## Job Output
+
+Store results via `ctx.setOutput(data)` or by returning a value from the handler. The value appears in `useJob`'s `output` field and the dashboard detail view. If both are used, `ctx.setOutput()` takes precedence.

package/ai/skills/dataqueue-core/SKILL.md

@@ -38,7 +38,8 @@ export const jobHandlers: JobHandlers<JobPayloadMap> = {
   },
   generate_report: async (payload, signal) => {
     if (signal.aborted) return;
-    await generateReport(payload.reportId, payload.userId);
+    const url = await generateReport(payload.reportId, payload.userId);
+    return { url }; // stored as job output, readable via getJob()
   },
 };
 ```

package/ai/skills/dataqueue-react/SKILL.md

@@ -102,13 +102,14 @@ export async function GET(
 
 ### useJob Return Value
 
-| Field       | Type                | Description                     |
-| ----------- | ------------------- | ------------------------------- |
-| `data`      | `JobData \| null`   | Latest job data from fetcher    |
-| `status`    | `JobStatus \| null` | Current job status              |
-| `progress`  | `number \| null`    | Progress percentage (0–100)     |
-| `isLoading` | `boolean`           | True until first fetch resolves |
-| `error`     | `Error \| null`     | Last fetch error                |
+| Field       | Type                | Description                                           |
+| ----------- | ------------------- | ----------------------------------------------------- |
+| `data`      | `JobData \| null`   | Latest job data from fetcher                          |
+| `status`    | `JobStatus \| null` | Current job status                                    |
+| `progress`  | `number \| null`    | Progress percentage (0–100)                           |
+| `output`    | `unknown \| null`   | Handler output from `ctx.setOutput()` or return value |
+| `isLoading` | `boolean`           | True until first fetch resolves                       |
+| `error`     | `Error \| null`     | Last fetch error                                      |
 
 ## Dashboard — @nicnocquee/dataqueue-dashboard
 
@@ -187,3 +188,14 @@ const handler = async (payload, signal, ctx) => {
   }
 };
 ```
+
+### Job Output from Handlers
+
+Store results via `ctx.setOutput(data)` or by returning a value from the handler. Exposed via `getJob()` (`output` field) and the `useJob` hook's `output` property. If both are used, `ctx.setOutput()` takes precedence.
+
+```typescript
+const handler = async (payload, signal, ctx) => {
+  const result = await doWork(payload);
+  return { url: result.downloadUrl }; // stored as output
+};
+```

package/dist/index.cjs

@@ -151,9 +151,9 @@ async function runHandlerInWorker(handler, payload, timeoutMs, jobType) {
           }
           
           handlerFn(payload, signal)
-            .then(() => {
+            .then((result) => {
               clearTimeout(timeoutId);
-              parentPort.postMessage({ type: 'success' });
+              parentPort.postMessage({ type: 'success', output: result });
             })
             .catch((error) => {
               clearTimeout(timeoutId);
@@ -188,24 +188,27 @@ async function runHandlerInWorker(handler, payload, timeoutMs, jobType) {
       }
     });
     let resolved = false;
-    worker.on("message", (message) => {
-      if (resolved) return;
-      resolved = true;
-      if (message.type === "success") {
-        resolve();
-      } else if (message.type === "timeout") {
-        const timeoutError = new Error(
-          `Job timed out after ${timeoutMs} ms and was forcefully terminated`
-        );
-        timeoutError.failureReason = "timeout" /* Timeout */;
-        reject(timeoutError);
-      } else if (message.type === "error") {
-        const error = new Error(message.error.message);
-        error.stack = message.error.stack;
-        error.name = message.error.name;
-        reject(error);
+    worker.on(
+      "message",
+      (message) => {
+        if (resolved) return;
+        resolved = true;
+        if (message.type === "success") {
+          resolve(message.output);
+        } else if (message.type === "timeout") {
+          const timeoutError = new Error(
+            `Job timed out after ${timeoutMs} ms and was forcefully terminated`
+          );
+          timeoutError.failureReason = "timeout" /* Timeout */;
+          reject(timeoutError);
+        } else if (message.type === "error") {
+          const error = new Error(message.error.message);
+          error.stack = message.error.stack;
+          error.name = message.error.name;
+          reject(error);
+        }
       }
-    });
+    );
     worker.on("error", (error) => {
       if (resolved) return;
       resolved = true;
@@ -362,6 +365,9 @@ function buildWaitContext(backend, jobId, stepData, baseCtx) {
       if (percent < 0 || percent > 100)
         throw new Error("Progress must be between 0 and 100");
       await backend.updateProgress(jobId, Math.round(percent));
+    },
+    setOutput: async (data) => {
+      await backend.updateOutput(jobId, data);
     }
   };
   return ctx;
@@ -397,9 +403,16 @@ async function processJobWithHandlers(backend, job, jobHandlers, emit) {
   const forceKillOnTimeout = job.forceKillOnTimeout ?? false;
   let timeoutId;
   const controller = new AbortController();
+  let setOutputCalled = false;
+  let handlerReturnValue;
   try {
     if (forceKillOnTimeout && timeoutMs && timeoutMs > 0) {
-      await runHandlerInWorker(handler, job.payload, timeoutMs, job.jobType);
+      handlerReturnValue = await runHandlerInWorker(
+        handler,
+        job.payload,
+        timeoutMs,
+        job.jobType
+      );
     } else {
       let onTimeoutCallback;
       let timeoutReject;
@@ -461,6 +474,12 @@ async function processJobWithHandlers(backend, job, jobHandlers, emit) {
           });
         };
       }
+      const originalSetOutput = ctx.setOutput;
+      ctx.setOutput = async (data) => {
+        setOutputCalled = true;
+        await originalSetOutput(data);
+        emit?.("job:output", { jobId: job.id, output: data });
+      };
       if (forceKillOnTimeout && !hasTimeout) {
         log(
           `forceKillOnTimeout is set but no timeoutMs for job ${job.id}, running without force kill`
@@ -468,7 +487,7 @@ async function processJobWithHandlers(backend, job, jobHandlers, emit) {
       }
       const jobPromise = handler(job.payload, controller.signal, ctx);
       if (hasTimeout) {
-        await Promise.race([
+        handlerReturnValue = await Promise.race([
           jobPromise,
           new Promise((_, reject) => {
             timeoutReject = reject;
@@ -476,11 +495,12 @@ async function processJobWithHandlers(backend, job, jobHandlers, emit) {
           })
         ]);
       } else {
-        await jobPromise;
+        handlerReturnValue = await jobPromise;
       }
     }
     if (timeoutId) clearTimeout(timeoutId);
-    await backend.completeJob(job.id);
+    const completionOutput = setOutputCalled || handlerReturnValue === void 0 ? void 0 : handlerReturnValue;
+    await backend.completeJob(job.id, completionOutput);
     emit?.("job:completed", { jobId: job.id, jobType: job.jobType });
   } catch (error) {
     if (timeoutId) clearTimeout(timeoutId);
@@ -1234,7 +1254,7 @@ var PostgresBackend = class {
     const client = await this.pool.connect();
     try {
       const result = await client.query(
-        `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags, idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax" FROM job_queue WHERE id = $1`,
+        `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags, idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax", output FROM job_queue WHERE id = $1`,
         [id]
       );
       if (result.rows.length === 0) {
@@ -1261,7 +1281,7 @@ var PostgresBackend = class {
     const client = await this.pool.connect();
     try {
       const result = await client.query(
-        `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax" FROM job_queue WHERE status = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`,
+        `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax", output FROM job_queue WHERE status = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`,
         [status, limit, offset]
       );
       log(`Found ${result.rows.length} jobs by status ${status}`);
@@ -1283,7 +1303,7 @@ var PostgresBackend = class {
     const client = await this.pool.connect();
     try {
       const result = await client.query(
-        `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax" FROM job_queue ORDER BY created_at DESC LIMIT $1 OFFSET $2`,
+        `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax", output FROM job_queue ORDER BY created_at DESC LIMIT $1 OFFSET $2`,
         [limit, offset]
       );
       log(`Found ${result.rows.length} jobs (all)`);
@@ -1303,7 +1323,7 @@ var PostgresBackend = class {
   async getJobs(filters, limit = 100, offset = 0) {
     const client = await this.pool.connect();
     try {
-      let query = `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags, idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax" FROM job_queue`;
+      let query = `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags, idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax", output FROM job_queue`;
       const params = [];
       const where = [];
       let paramIdx = 1;
@@ -1404,7 +1424,7 @@ var PostgresBackend = class {
   async getJobsByTags(tags, mode = "all", limit = 100, offset = 0) {
     const client = await this.pool.connect();
     try {
-      let query = `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags, idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax"
+      let query = `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags, idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax", output
          FROM job_queue`;
       let params = [];
       switch (mode) {
@@ -1498,7 +1518,7 @@ var PostgresBackend = class {
           LIMIT $2
           FOR UPDATE SKIP LOCKED
         )
-        RETURNING id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax"
+        RETURNING id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", force_kill_on_timeout AS "forceKillOnTimeout", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", idempotency_key AS "idempotencyKey", wait_until AS "waitUntil", wait_token_id AS "waitTokenId", step_data AS "stepData", progress, retry_delay AS "retryDelay", retry_backoff AS "retryBackoff", retry_delay_max AS "retryDelayMax", output
       `,
         params
       );
@@ -1526,17 +1546,19 @@ var PostgresBackend = class {
       client.release();
     }
   }
-  async completeJob(jobId) {
+  async completeJob(jobId, output) {
     const client = await this.pool.connect();
     try {
+      const outputJson = output !== void 0 ? JSON.stringify(output) : null;
       const result = await client.query(
         `
         UPDATE job_queue
         SET status = 'completed', updated_at = NOW(), completed_at = NOW(),
-            step_data = NULL, wait_until = NULL, wait_token_id = NULL
+            step_data = NULL, wait_until = NULL, wait_token_id = NULL,
+            output = COALESCE($2::jsonb, output)
         WHERE id = $1 AND status = 'processing'
       `,
-        [jobId]
+        [jobId, outputJson]
       );
       if (result.rowCount === 0) {
         log(
@@ -1639,6 +1661,21 @@ var PostgresBackend = class {
       client.release();
     }
   }
+  // ── Output ────────────────────────────────────────────────────────────
+  async updateOutput(jobId, output) {
+    const client = await this.pool.connect();
+    try {
+      await client.query(
+        `UPDATE job_queue SET output = $2::jsonb, updated_at = NOW() WHERE id = $1`,
+        [jobId, JSON.stringify(output)]
+      );
+      log(`Updated output for job ${jobId}`);
+    } catch (error) {
+      log(`Error updating output for job ${jobId}: ${error}`);
+    } finally {
+      client.release();
+    }
+  }
   // ── Job management ────────────────────────────────────────────────────
   async retryJob(jobId) {
     const client = await this.pool.connect();
@@ -3038,16 +3075,24 @@ var COMPLETE_JOB_SCRIPT = `
 local prefix = KEYS[1]
 local jobId = ARGV[1]
 local nowMs = ARGV[2]
+local outputJson = ARGV[3]
 local jk = prefix .. 'job:' .. jobId
 
-redis.call('HMSET', jk,
+local fields = {
   'status', 'completed',
   'updatedAt', nowMs,
   'completedAt', nowMs,
   'stepData', 'null',
   'waitUntil', 'null',
   'waitTokenId', 'null'
-)
+}
+
+if outputJson ~= '__NONE__' then
+  fields[#fields + 1] = 'output'
+  fields[#fields + 1] = outputJson
+end
+
+redis.call('HMSET', jk, unpack(fields))
 redis.call('SREM', prefix .. 'status:processing', jobId)
 redis.call('SADD', prefix .. 'status:completed', jobId)
 
@@ -3510,9 +3555,18 @@ function deserializeJob(h) {
     stepData: parseStepData(h.stepData),
     retryDelay: numOrNull(h.retryDelay),
     retryBackoff: h.retryBackoff === "true" ? true : h.retryBackoff === "false" ? false : null,
-    retryDelayMax: numOrNull(h.retryDelayMax)
+    retryDelayMax: numOrNull(h.retryDelayMax),
+    output: parseJsonField(h.output)
   };
 }
+function parseJsonField(raw) {
+  if (!raw || raw === "null") return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 function parseStepData(raw) {
   if (!raw || raw === "null") return void 0;
   try {
@@ -3810,9 +3864,17 @@ var RedisBackend = class {
     }
     return jobs;
   }
-  async completeJob(jobId) {
+  async completeJob(jobId, output) {
     const now = this.nowMs();
-    await this.client.eval(COMPLETE_JOB_SCRIPT, 1, this.prefix, jobId, now);
+    const outputArg = output !== void 0 ? JSON.stringify(output) : "__NONE__";
+    await this.client.eval(
+      COMPLETE_JOB_SCRIPT,
+      1,
+      this.prefix,
+      jobId,
+      now,
+      outputArg
+    );
     await this.recordJobEvent(jobId, "completed" /* Completed */);
     log(`Completed job ${jobId}`);
   }
@@ -3865,6 +3927,22 @@ var RedisBackend = class {
       log(`Error updating progress for job ${jobId}: ${error}`);
     }
   }
+  // ── Output ────────────────────────────────────────────────────────────
+  async updateOutput(jobId, output) {
+    try {
+      const now = this.nowMs();
+      await this.client.hset(
+        `${this.prefix}job:${jobId}`,
+        "output",
+        JSON.stringify(output),
+        "updatedAt",
+        now.toString()
+      );
+      log(`Updated output for job ${jobId}`);
+    } catch (error) {
+      log(`Error updating output for job ${jobId}: ${error}`);
+    }
+  }
   // ── Job management ────────────────────────────────────────────────────
   async retryJob(jobId) {
     const now = this.nowMs();