nuxt-cf-jobs 0.12.2 → 0.13.0

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-cf-jobs",
   "configKey": "cfJobs",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/server/broadcast.js

@@ -164,6 +164,7 @@ function releaseToExtra(opts) {
   return opts?.error ? { error: opts.error } : {};
 }
 function jobEventFromMetrics(event) {
+  const completed = event.status === "completed" ? event : void 0;
   return {
     jobName: null,
     jobId: event.jobId,
@@ -173,12 +174,12 @@ function jobEventFromMetrics(event) {
     attempts: event.attempts,
     durationMs: event.durationMs,
     batchId: event.batchId,
-    error: event.error,
-    rowsFetched: event.rowsFetched,
-    rowsInserted: event.rowsInserted,
-    d1RowsRead: event.d1RowsRead,
-    d1RowsWritten: event.d1RowsWritten,
-    result: event.result
+    error: event.status === "completed" ? void 0 : event.error,
+    rowsFetched: completed?.stats.rowsFetched,
+    rowsInserted: completed?.stats.rowsInserted,
+    d1RowsRead: completed?.stats.d1RowsRead,
+    d1RowsWritten: completed?.stats.d1RowsWritten,
+    result: completed?.result
   };
 }
 async function loadBroadcastJobDefinition(registry, name) {

package/dist/runtime/server/cloudflare.js

@@ -1,17 +1,19 @@
 import { noopMetricsSink } from "./metrics.js";
 export function defaultJobDataPoint(event) {
+  const stats = event.status === "completed" ? event.stats : void 0;
+  const error = event.status === "completed" ? null : event.error ?? null;
   return {
     indexes: [event.queue],
-    blobs: [event.queue, event.jobType, event.status, event.error ?? null],
+    blobs: [event.queue, event.jobType, event.status, error],
     // doubles are positional — keep this order stable (the AE SQL API references
     // double1..double6). duration, attempts, then the reported execution stats.
     doubles: [
       event.durationMs ?? 0,
       event.attempts,
-      event.rowsFetched ?? 0,
-      event.rowsInserted ?? 0,
-      event.d1RowsRead ?? 0,
-      event.d1RowsWritten ?? 0
+      stats?.rowsFetched ?? 0,
+      stats?.rowsInserted ?? 0,
+      stats?.d1RowsRead ?? 0,
+      stats?.d1RowsWritten ?? 0
     ]
   };
 }

package/dist/runtime/server/d1.d.ts

@@ -87,10 +87,17 @@ export interface D1DurableJobRepositoryOptions<Queue extends string = string> {
         durationMs: number | null;
         result?: unknown;
     }) => void;
-    /** Fire-and-forget hook invoked after `failJob` writes succeed. Errors are swallowed. */
+    /**
+     * Fire-and-forget hook invoked after `failJob` writes succeed. Errors are swallowed.
+     *
+     * `error` is the HEADLINE (`"TypeError: <message>"`) — safe for issue titles,
+     * realtime payloads and Analytics Engine blobs. `cause` is the ORIGINAL thrown
+     * value: report it as-is (`captureException(cause)`) to keep the native stack.
+     */
     onJobFailed?: (input: {
         job: D1DurableJobRecord<Queue>;
         error: string;
+        cause?: unknown;
     }) => void;
     /** Fire-and-forget hook invoked after `releaseJob` writes succeed. Errors are swallowed. */
     onJobReleased?: (input: {

package/dist/runtime/server/d1.js

@@ -149,7 +149,7 @@ export function createD1DurableJobRepository(db, opts = {}) {
       assertOwnedMutation(resultUpdate, job.id);
       fireHook(() => opts.onJobCompleted?.({ job, durationMs, result }));
     },
-    async failJob(job, error) {
+    async failJob(job, error, failOpts) {
       const insert = await db.prepare(`
         INSERT OR REPLACE INTO ${failedJobsTable} (
           id, queue, job_type, batch_id, user_id, site_id, partner_id, trace_id, unique_key, payload,
@@ -180,7 +180,7 @@ export function createD1DurableJobRepository(db, opts = {}) {
           AND failed_at IS NULL
       `).bind(job.id, job.reserved_at, job.attempts).run();
       assertOwnedMutation(deleted, job.id);
-      fireHook(() => opts.onJobFailed?.({ job, error: headlineOf(error) }));
+      fireHook(() => opts.onJobFailed?.({ job, error: headlineOf(error), cause: failOpts?.cause }));
     },
     async releaseJob(job, releaseOpts) {
       const result = await db.prepare(`

package/dist/runtime/server/metrics.d.ts

@@ -1,30 +1,57 @@
 import type { D1DurableJobRepositoryOptions } from './d1.js';
-export type JobMetricStatus = 'completed' | 'failed' | 'released';
-/**
- * One terminal-ish job lifecycle event, engine-neutral. `released` is a
- * deliberate retry (`ctx.release()` / a handler throw) rather than a terminal
- * state, but it is worth recording for retry-rate dashboards.
- */
-export interface JobMetricsEvent {
+import type { JobRunStats } from './types.js';
+/** Fields every lifecycle event carries, whatever its outcome. */
+export interface JobMetricsEventBase {
     jobId: string;
     queue: string;
     jobType: string;
-    status: JobMetricStatus;
     attempts: number;
-    /** Wall-clock duration when known (completed jobs); null otherwise. */
-    durationMs: number | null;
     batchId: string | null;
     siteId: string | null;
     userId: number | null;
-    /** Present for `failed` / `released` (the release reason). */
-    error?: string;
-    /** Optional completion result supplied by the consumer. */
-    result?: unknown;
-    rowsFetched?: number;
-    rowsInserted?: number;
-    d1RowsRead?: number;
-    d1RowsWritten?: number;
 }
+/**
+ * One terminal-ish job lifecycle event, engine-neutral, discriminated on `status`
+ * so a sink can only read the fields that outcome actually has. `released` is a
+ * deliberate retry (`ctx.release()`) rather than a terminal state, but it is worth
+ * recording for retry-rate dashboards.
+ *
+ * Previously this was one interface with `error?`/`cause?`/`result?`/`rows*?` all
+ * optional, which made `{ status: 'completed', cause }` and `{ status: 'failed',
+ * rowsInserted }` representable — and the Analytics Engine adapter duly wrote an
+ * `error` blob and zero-filled stat doubles for completed jobs. The union removes
+ * both the illegal states and the guesswork.
+ */
+export type JobMetricsEvent = (JobMetricsEventBase & {
+    status: 'completed';
+    /** Wall-clock duration when the repository timed the run. */
+    durationMs: number | null;
+    /** Whatever the consumer's `completeJob` returned. */
+    result?: unknown;
+    /** Execution stats from `ctx.reportStats`; `{}` when the handler reported none. */
+    stats: JobRunStats;
+}) | (JobMetricsEventBase & {
+    status: 'failed';
+    durationMs: number | null;
+    /** Single-line headline (`"TypeError: <message>"`) — safe for titles + blobs. */
+    error: string;
+    /**
+     * The ORIGINAL thrown value, not a rendering of it. An error-tracker sink should
+     * `captureException(cause)` so it groups on the real throw site and keeps the
+     * native stack + `cause` chain, rather than rebuilding a synthetic
+     * `new Error(error)`. Absent when the failure never had a throw (a dispatch
+     * fault, `ctx.fail()`). Dimension-oriented sinks must ignore it — it is an
+     * arbitrary object, not a blob.
+     */
+    cause?: unknown;
+}) | (JobMetricsEventBase & {
+    status: 'released';
+    /** A release is not a completed run, so it is never timed. */
+    durationMs: null;
+    /** The release reason, when `ctx.release()` supplied one. */
+    error?: string;
+});
+export type JobMetricStatus = JobMetricsEvent['status'];
 export interface JobMetricsSink {
     record: (event: JobMetricsEvent) => void | Promise<void>;
 }

package/dist/runtime/server/metrics.js

@@ -10,33 +10,44 @@ function readStats(result) {
   }
   return out;
 }
-function toEvent(job, status, extra) {
+function baseOf(job) {
   return {
     jobId: job.id,
     queue: job.queue,
     jobType: job.job_type,
-    status,
     attempts: job.attempts,
-    durationMs: extra.durationMs ?? null,
     batchId: job.batch_id,
     siteId: job.site_id,
-    userId: job.user_id,
-    error: extra.error
+    userId: job.user_id
   };
 }
 export function metricsSinkToRepoHooks(sink) {
   return {
     onJobCompleted({ job, durationMs, result }) {
-      const event = { ...toEvent(job, "completed", { durationMs }), ...readStats(result) };
-      if (result !== void 0)
-        event.result = result;
-      return sink.record(event);
+      return sink.record({
+        ...baseOf(job),
+        status: "completed",
+        durationMs: durationMs ?? null,
+        stats: readStats(result),
+        ...result !== void 0 ? { result } : {}
+      });
     },
-    onJobFailed({ job, error }) {
-      return sink.record(toEvent(job, "failed", { durationMs: job.duration_ms ?? null, error }));
+    onJobFailed({ job, error, cause }) {
+      return sink.record({
+        ...baseOf(job),
+        status: "failed",
+        durationMs: job.duration_ms ?? null,
+        error,
+        ...cause !== void 0 ? { cause } : {}
+      });
     },
     onJobReleased({ job, opts }) {
-      return sink.record(toEvent(job, "released", { error: opts?.error }));
+      return sink.record({
+        ...baseOf(job),
+        status: "released",
+        durationMs: null,
+        ...opts?.error !== void 0 ? { error: opts.error } : {}
+      });
     }
   };
 }

package/dist/runtime/server/outbox.d.ts

@@ -97,11 +97,22 @@ export interface ReleaseDurableJobOptions {
     availableAt?: number;
     error?: string;
 }
+/**
+ * Well-known `failJob` options, always passable regardless of a repository's own
+ * `FailOptions` — hence `Partial<FailOptions> & FailDurableJobOptions` on `failJob`
+ * (`Partial<unknown>` collapses to `{}`), so the runtime can supply just a `cause`
+ * without knowing a repository's bespoke options. `cause` is the ORIGINAL thrown
+ * value: the `error` string is a rendering for the `failed_jobs` row, but a telemetry
+ * hook wants the instance so it can report the real stack instead of rebuilding one.
+ */
+export interface FailDurableJobOptions {
+    cause?: unknown;
+}
 export interface DurableJobLifecycle<Job, CompleteResult = void, FailOptions = unknown, ReleaseResult = void> {
     claimJob: (id: string) => Promise<Job | null>;
     resolveClaimMiss?: (id: string) => Promise<DurableJobClaimMiss>;
     completeJob: (job: Job, result?: unknown) => Promise<CompleteResult>;
-    failJob: (job: Job, error: string, opts?: FailOptions) => Promise<void>;
+    failJob: (job: Job, error: string, opts?: Partial<FailOptions> & FailDurableJobOptions) => Promise<void>;
     releaseJob?: (job: Job, opts?: ReleaseDurableJobOptions) => Promise<ReleaseResult>;
 }
 export interface QueuePublisher<Queue extends string = string, Message extends QueueJobMessage<Queue> = QueueJobMessage<Queue>> {
@@ -228,7 +239,7 @@ export declare function createQueuePublisher<Env extends Record<string, unknown>
 }): QueuePublisher<Queue, Message>;
 export declare function claimDurableJob<Job>(lifecycle: Pick<DurableJobLifecycle<Job>, 'claimJob' | 'resolveClaimMiss'>, id: string): Promise<DurableJobClaimResult<Job>>;
 export declare function completeDurableJob<Job, CompleteResult>(lifecycle: Pick<DurableJobLifecycle<Job, CompleteResult>, 'completeJob'>, job: Job, result?: unknown): Promise<CompleteResult>;
-export declare function failDurableJob<Job, FailOptions>(lifecycle: Pick<DurableJobLifecycle<Job, unknown, FailOptions>, 'failJob'>, job: Job, error: string, opts?: FailOptions): Promise<void>;
+export declare function failDurableJob<Job, FailOptions>(lifecycle: Pick<DurableJobLifecycle<Job, unknown, FailOptions>, 'failJob'>, job: Job, error: string, opts?: Partial<FailOptions> & FailDurableJobOptions): Promise<void>;
 export declare function releaseDurableJob<Job, ReleaseResult>(lifecycle: Pick<DurableJobLifecycle<Job, unknown, unknown, ReleaseResult>, 'releaseJob'>, job: Job, opts?: ReleaseDurableJobOptions): Promise<ReleaseResult | undefined>;
 export declare function findDispatchableDurableJobs<Queue extends string, Record extends Pick<DurableJobRecord<Queue>, 'id' | 'queue'>>(repository: Pick<DurableJobRecoveryRepository<Queue, Record>, 'findDispatchableJobs'>, query?: DurableJobRecoveryQuery): Promise<Record[]>;
 export declare function releaseStaleReservedDurableJobs<Queue extends string, Record extends Pick<DurableJobRecord<Queue>, 'id' | 'queue'>>(repository: Pick<DurableJobRecoveryRepository<Queue, Record>, 'releaseStaleReservedJobs'>, query: DurableJobStaleRecoveryQuery): Promise<number>;
@@ -285,9 +296,9 @@ export declare function dispatchDurableJobBatch<Queue extends string>(publisher:
     delaySeconds?: number;
 }): Promise<Array<DispatchDurableJobBatchResult<Queue>>>;
 export type DurableJobMessageStatus = 'invalid-message' | DurableJobClaimMiss | 'dispatch-failed' | 'released' | 'failed' | 'completed' | 'errored';
-export interface RunDurableJobMessageOptions<StoredJob, Job extends DispatchableJob, Message extends QueueJobMessage = QueueJobMessage, Env = unknown, Db = unknown, Logger = unknown, CompleteResult = unknown, FailOptions = unknown> {
+export interface RunDurableJobMessageOptions<StoredJob, Job extends DispatchableJob, Message extends QueueJobMessage = QueueJobMessage, Env = unknown, Db = unknown, Logger = unknown, CompleteResult = unknown> {
     message: Pick<QueueMessage<Message>, 'body' | 'ack' | 'retry'>;
-    lifecycle: Pick<DurableJobLifecycle<StoredJob, CompleteResult, FailOptions>, 'claimJob' | 'resolveClaimMiss' | 'completeJob' | 'failJob' | 'releaseJob'>;
+    lifecycle: Pick<DurableJobLifecycle<StoredJob, CompleteResult, FailDurableJobOptions>, 'claimJob' | 'resolveClaimMiss' | 'completeJob' | 'failJob' | 'releaseJob'>;
     registry: {
         getHandler: (name: string) => JobHandler<unknown, Env, Db, Logger> | undefined | Promise<JobHandler<unknown, Env, Db, Logger> | undefined>;
         getJobDefinition?: (name: string) => JobDefinition<string, unknown, string, Env, Db, Logger> | undefined;
@@ -414,4 +425,4 @@ export type RunDurableJobMessageResult = {
     status: 'claim-error';
     error: JobError;
 };
-export declare function runDurableJobMessage<StoredJob, Job extends DispatchableJob, Message extends QueueJobMessage = QueueJobMessage, Env = unknown, Db = unknown, Logger = unknown, CompleteResult = unknown, FailOptions = unknown>(opts: RunDurableJobMessageOptions<StoredJob, Job, Message, Env, Db, Logger, CompleteResult, FailOptions>): Promise<RunDurableJobMessageResult>;
+export declare function runDurableJobMessage<StoredJob, Job extends DispatchableJob, Message extends QueueJobMessage = QueueJobMessage, Env = unknown, Db = unknown, Logger = unknown, CompleteResult = unknown>(opts: RunDurableJobMessageOptions<StoredJob, Job, Message, Env, Db, Logger, CompleteResult>): Promise<RunDurableJobMessageResult>;

package/dist/runtime/server/outbox.js

@@ -338,7 +338,7 @@ export async function runDurableJobMessage(opts) {
     const permanent = opts.isPermanentFailure ? opts.isPermanentFailure({ error, storedJob, attempts: job.attempts, maxAttempts }) : typeof maxAttempts === "number" && job.attempts >= maxAttempts;
     if (permanent) {
       try {
-        await failDurableJob(opts.lifecycle, storedJob, describeCauseWithStack(error));
+        await failDurableJob(opts.lifecycle, storedJob, describeCauseWithStack(error), { cause: error });
       } catch (failError) {
         const obsolete = obsoleteDelivery(failError);
         if (obsolete)

package/dist/runtime/server/runtime.d.ts

@@ -35,6 +35,33 @@ export declare function runDurableJobBatchMessage<StoredJob, Job extends Dispatc
     jobId: string;
     queue: string;
 }, Env = unknown, Db = unknown, Logger = unknown>(opts: RunDurableJobBatchMessageOptions<StoredJob, Job, Message, Env, Db, Logger>): Promise<RunDurableJobBatchMessageResult>;
+/**
+ * Every stage the runtime reports through {@link CfJobsLogEvent}. A union, not
+ * `string`: consumers switch on it to pick a log level / catalogued name, and a new
+ * stage should break their switch rather than fall silently into a default branch.
+ *
+ * - `invalid_payload` — no `_task`, or no handler registered for it.
+ * - `unexpected`      — a lightweight handler threw; the message is retried.
+ * - `failed`          — a handler called `ctx.fail()`.
+ * - `dlq`             — a durable job exhausted its retries and was dead-lettered.
+ * - `onfinish-failed` — a batch's `onFinish` continuation threw.
+ */
+export type CfJobsLogStage = 'invalid_payload' | 'unexpected' | 'failed' | 'dlq' | 'onfinish-failed';
+/**
+ * Diagnostic entry from the consumer loop (never a throw). When the stage came from a
+ * defect, `cause` is the original thrown value — report it directly rather than
+ * rebuilding `new Error(error)` — and `stack` is its rendering (stack + `cause`
+ * chain). `error` is always a single-line headline, safe for an issue title.
+ */
+export interface CfJobsLogEvent {
+    stage: CfJobsLogStage;
+    queue?: string;
+    taskName?: string;
+    jobId?: string;
+    error?: string;
+    stack?: string;
+    cause?: unknown;
+}
 export interface RunLightweightMessageOptions<Env = unknown, Db = unknown, Logger = unknown> {
     message: Pick<QueueMessage, 'id' | 'body' | 'attempts' | 'ack' | 'retry'>;
     registry: DurableJobsRuntimeRegistry<Env, Db, Logger>;
@@ -43,17 +70,8 @@ export interface RunLightweightMessageOptions<Env = unknown, Db = unknown, Logge
     isDuplicate?: (id: string | undefined) => boolean;
     /** Mark an id as terminally handled. Retried/released messages must not be marked. */
     markDuplicate?: (id: string | undefined) => void;
-    /**
-     * Diagnostic sink for dropped/invalid messages (no throw). `stack` is present
-     * when the entry came from a thrown defect, so a consumer can report the real
-     * stack rather than reconstructing `new Error(error)`.
-     */
-    onLog?: (event: {
-        stage: string;
-        taskName?: string;
-        error?: string;
-        stack?: string;
-    }) => void;
+    /** Diagnostic sink for dropped/invalid messages (no throw). */
+    onLog?: (event: CfJobsLogEvent) => void;
 }
 export type RunLightweightMessageResult = {
     status: 'invalid' | 'duplicate' | 'dispatch-failed' | 'released' | 'failed' | 'completed' | 'errored';
@@ -77,14 +95,7 @@ export interface ConsumeQueueBatchOptions<Queue extends string, Env, Db, Logger>
     isDlqQueue?: (queue: string) => boolean;
     isDuplicate?: (id: string | undefined) => boolean;
     markDuplicate?: (id: string | undefined) => void;
-    onLog?: (event: {
-        stage: string;
-        queue?: string;
-        taskName?: string;
-        jobId?: string;
-        error?: string;
-        stack?: string;
-    }) => void;
+    onLog?: (event: CfJobsLogEvent) => void;
     createJobScope?: (storedJob: D1DurableJobRecord<Queue>) => DurableJobScope<D1DurableJobRecord<Queue>>;
     isPermanentFailure?: (input: {
         error: unknown;
@@ -170,14 +181,7 @@ export interface CreateDurableJobsRuntimeOptions<Queue extends string = string,
      */
     dedup?: Set<string>;
     /** Diagnostic log sink for DLQ / dropped lightweight messages. */
-    onLog?: (event: {
-        stage: string;
-        queue?: string;
-        taskName?: string;
-        jobId?: string;
-        error?: string;
-        stack?: string;
-    }) => void;
+    onLog?: (event: CfJobsLogEvent) => void;
     /** Per-job scope: wrap dispatch (e.g. telemetry) + observe each settlement. */
     createJobScope?: (storedJob: D1DurableJobRecord<Queue>) => DurableJobScope<D1DurableJobRecord<Queue>>;
     /** Decide whether a thrown error is terminal (default: attempts >= max). */

package/dist/runtime/server/runtime.js

@@ -93,7 +93,7 @@ export async function runLightweightMessage(opts) {
     return { status: "completed" };
   } catch (error) {
     const delaySeconds = resolveJobRetryDelay(definition, message.attempts);
-    opts.onLog?.({ stage: "unexpected", taskName, error: describeCause(error), stack: describeCauseWithStack(error) });
+    opts.onLog?.({ stage: "unexpected", taskName, error: describeCause(error), stack: describeCauseWithStack(error), cause: error });
     message.retry({ delaySeconds });
     return { status: "errored" };
   }
@@ -246,7 +246,7 @@ export function createDurableJobsRuntime(opts) {
         });
       }
     } catch (error) {
-      opts.onLog?.({ stage: "onfinish-failed", taskName: c.name, jobId: batch.id, error: describeCause(error), stack: describeCauseWithStack(error) });
+      opts.onLog?.({ stage: "onfinish-failed", taskName: c.name, jobId: batch.id, error: describeCause(error), stack: describeCauseWithStack(error), cause: error });
     }
   });
   const dedup = opts.dedup ? createMessageDedup(opts.dedup) : void 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-cf-jobs",
   "type": "module",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Nuxt module for typed Cloudflare queue jobs.",
   "author": {
     "name": "Harlan Wilton",
@@ -109,7 +109,7 @@
     "test:nitro": "vitest run --project nitro",
     "test:types": "nuxt prepare tests/fixtures/nuxt-demo && vue-tsc --noEmit -p tests/fixtures/nuxt-demo/tsconfig.json",
     "test:e2e": "CF_JOBS_E2E=1 vitest run --no-file-parallelism tests/wrangler-dev.e2e.test.ts tests/wrangler-d1.e2e.test.ts",
-    "typecheck": "tsc --noEmit -p tsconfig.json && pnpm test:types",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tests/tsconfig.json && pnpm test:types",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
   }