nuxt-cf-jobs 0.12.2 → 0.12.4

package/dist/module.json

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

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

@@ -16,8 +16,16 @@ export interface JobMetricsEvent {
     batchId: string | null;
     siteId: string | null;
     userId: number | null;
-    /** Present for `failed` / `released` (the release reason). */
+    /** Present for `failed` / `released` (the release reason). Single-line headline. */
     error?: string;
+    /**
+     * Present for `failed`: 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)`. Dimension-oriented sinks (Analytics Engine) must
+     * ignore it — it is an arbitrary object, not a blob.
+     */
+    cause?: unknown;
     /** Optional completion result supplied by the consumer. */
     result?: unknown;
     rowsFetched?: number;

package/dist/runtime/server/metrics.js

@@ -21,7 +21,8 @@ function toEvent(job, status, extra) {
     batchId: job.batch_id,
     siteId: job.site_id,
     userId: job.user_id,
-    error: extra.error
+    error: extra.error,
+    ...extra.cause !== void 0 ? { cause: extra.cause } : {}
   };
 }
 export function metricsSinkToRepoHooks(sink) {
@@ -32,8 +33,8 @@ export function metricsSinkToRepoHooks(sink) {
         event.result = result;
       return sink.record(event);
     },
-    onJobFailed({ job, error }) {
-      return sink.record(toEvent(job, "failed", { durationMs: job.duration_ms ?? null, error }));
+    onJobFailed({ job, error, cause }) {
+      return sink.record(toEvent(job, "failed", { durationMs: job.duration_ms ?? null, error, cause }));
     },
     onJobReleased({ job, opts }) {
       return sink.record(toEvent(job, "released", { error: opts?.error }));

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

@@ -97,11 +97,20 @@ export interface ReleaseDurableJobOptions {
     availableAt?: number;
     error?: string;
 }
+/**
+ * Well-known `failJob` options, always available regardless of a repository's own
+ * `FailOptions` (`unknown & T` is `T`). `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?: 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 +237,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?: 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>;

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

@@ -44,15 +44,16 @@ export interface RunLightweightMessageOptions<Env = unknown, Db = unknown, Logge
     /** 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)`.
+     * Diagnostic sink for dropped/invalid messages (no throw). When the entry came from
+     * a thrown defect, `cause` is the original value (report it directly) and `stack` its
+     * rendering — so a consumer never has to reconstruct `new Error(error)`.
      */
     onLog?: (event: {
         stage: string;
         taskName?: string;
         error?: string;
         stack?: string;
+        cause?: unknown;
     }) => void;
 }
 export type RunLightweightMessageResult = {
@@ -84,6 +85,7 @@ export interface ConsumeQueueBatchOptions<Queue extends string, Env, Db, Logger>
         jobId?: string;
         error?: string;
         stack?: string;
+        cause?: unknown;
     }) => void;
     createJobScope?: (storedJob: D1DurableJobRecord<Queue>) => DurableJobScope<D1DurableJobRecord<Queue>>;
     isPermanentFailure?: (input: {
@@ -177,6 +179,7 @@ export interface CreateDurableJobsRuntimeOptions<Queue extends string = string,
         jobId?: string;
         error?: string;
         stack?: string;
+        cause?: unknown;
     }) => void;
     /** Per-job scope: wrap dispatch (e.g. telemetry) + observe each settlement. */
     createJobScope?: (storedJob: D1DurableJobRecord<Queue>) => DurableJobScope<D1DurableJobRecord<Queue>>;

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.12.4",
   "description": "Nuxt module for typed Cloudflare queue jobs.",
   "author": {
     "name": "Harlan Wilton",