nuxt-cf-jobs 0.12.0 → 0.12.2

package/dist/module.json

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

package/dist/runtime/server/d1.js

@@ -1,4 +1,4 @@
-import { DurableJobOwnershipError } from "./errors.js";
+import { DurableJobOwnershipError, headlineOf } from "./errors.js";
 export const d1DurableJobMigrationSql = [
   "CREATE TABLE IF NOT EXISTS job_batches (id text PRIMARY KEY, name text, parent_batch_id text, total_jobs integer NOT NULL DEFAULT 0, pending_jobs integer NOT NULL DEFAULT 0, failed_jobs integer NOT NULL DEFAULT 0, on_finish text, handler text, allow_failures integer DEFAULT 0, site_id text, user_id integer, created_at integer NOT NULL DEFAULT (unixepoch()), updated_at integer NOT NULL DEFAULT (unixepoch()), finished_at integer)",
   "CREATE TABLE IF NOT EXISTS jobs (id text PRIMARY KEY, queue text NOT NULL, job_type text NOT NULL, batch_id text REFERENCES job_batches(id), user_id integer, site_id text, partner_id text, trace_id text, unique_key text, payload text NOT NULL, attempts integer DEFAULT 0, max_attempts integer DEFAULT 3, reserved_at integer, available_at integer NOT NULL, created_at integer NOT NULL DEFAULT (unixepoch()), completed_at integer, failed_at integer, last_error text, retry_reasons text, rows_fetched integer, rows_inserted integer, d1_rows_read integer, d1_rows_written integer, duration_ms integer)",
@@ -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 }));
+      fireHook(() => opts.onJobFailed?.({ job, error: headlineOf(error) }));
     },
     async releaseJob(job, releaseOpts) {
       const result = await db.prepare(`

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

@@ -72,6 +72,30 @@ export type JobErrorTag = JobError['_tag'];
 export declare function isJobError(value: unknown): value is JobError;
 /** Renders any defect into a string for `message` fields and string-only sinks. */
 export declare function describeCause(cause: unknown): string;
+/** Upper bound on a rendered stack, so one defect can't blow up a `failed_jobs` row. */
+export declare const MAX_DESCRIBED_STACK_CHARS = 4000;
+/**
+ * The first line of a rendered defect — `"TypeError: <message>"` for anything that
+ * came through {@link describeCauseWithStack}, and the string itself for a plain
+ * single-line message. Telemetry sinks (Sentry issue titles, realtime payloads)
+ * want this, not the whole stack.
+ */
+export declare function headlineOf(rendered: string): string;
+/**
+ * Renders a defect for DIAGNOSTICS — the stack, plus the `cause` chain beneath it.
+ *
+ * `describeCause` deliberately collapses an `Error` to its `.message`, which is the
+ * right rendering for the short `message` fields of a `JobError`. But it is also what
+ * used to land in `failed_jobs.exception`, so a terminal failure was persisted as a
+ * bare sentence with no stack and no cause — undiagnosable without reproducing it
+ * (this is how a `TypeError: Cannot assign to read only property 'name'` sat in the
+ * crawl queue for 103 occurrences with nothing to point at). Use this at the
+ * persistence / observability boundary; keep `describeCause` for `message`.
+ *
+ * `error.stack` already begins with `"<name>: <message>"`, so it is used whole when
+ * present and synthesised otherwise. Cycles and runaway chains are bounded.
+ */
+export declare function describeCauseWithStack(cause: unknown, maxChars?: number): string;
 export declare const jobErrors: {
     readonly noTask: () => NoTaskError;
     readonly handlerNotFound: (task: string) => HandlerNotFoundError;

package/dist/runtime/server/errors.js

@@ -16,6 +16,33 @@ export function describeCause(cause) {
     return cause.message;
   return typeof cause === "string" ? cause : String(cause);
 }
+export const MAX_DESCRIBED_STACK_CHARS = 4e3;
+export function headlineOf(rendered) {
+  const newline = rendered.indexOf("\n");
+  return newline === -1 ? rendered : rendered.slice(0, newline);
+}
+export function describeCauseWithStack(cause, maxChars = MAX_DESCRIBED_STACK_CHARS) {
+  const parts = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = cause;
+  while (current !== void 0 && current !== null && parts.length < 5) {
+    if (typeof current === "object") {
+      if (seen.has(current))
+        break;
+      seen.add(current);
+    }
+    if (current instanceof Error) {
+      parts.push(current.stack || `${current.name}: ${current.message}`);
+      current = current.cause;
+      continue;
+    }
+    parts.push(describeCause(current));
+    break;
+  }
+  const rendered = parts.join("\nCaused by: ") || describeCause(cause);
+  return rendered.length > maxChars ? `${rendered.slice(0, maxChars)}
+\u2026 (truncated)` : rendered;
+}
 export const jobErrors = {
   noTask() {
     return { _tag: "no-task", message: "No _task in payload" };

package/dist/runtime/server/outbox.js

@@ -1,5 +1,5 @@
 import { dispatchRegisteredJob } from "./dispatch.js";
-import { describeCause, formatJobError, isDurableJobOwnershipError, jobErrors, jobErrorToException } from "./errors.js";
+import { describeCause, describeCauseWithStack, formatJobError, isDurableJobOwnershipError, jobErrors, jobErrorToException } from "./errors.js";
 import { buildJobPayload } from "./payload.js";
 import { createJobTraceId, createJobUniqueKey, resolveJobMaxAttempts } from "./policy.js";
 import { CF_QUEUE_MAX_MESSAGE_BYTES, sendBatchChunked, withSendBackpressure } from "./queue.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, describeCause(error));
+        await failDurableJob(opts.lifecycle, storedJob, describeCauseWithStack(error));
       } catch (failError) {
         const obsolete = obsoleteDelivery(failError);
         if (obsolete)

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

@@ -43,11 +43,16 @@ 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). */
+    /**
+     * 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;
 }
 export type RunLightweightMessageResult = {
@@ -78,6 +83,7 @@ export interface ConsumeQueueBatchOptions<Queue extends string, Env, Db, Logger>
         taskName?: string;
         jobId?: string;
         error?: string;
+        stack?: string;
     }) => void;
     createJobScope?: (storedJob: D1DurableJobRecord<Queue>) => DurableJobScope<D1DurableJobRecord<Queue>>;
     isPermanentFailure?: (input: {
@@ -170,6 +176,7 @@ export interface CreateDurableJobsRuntimeOptions<Queue extends string = string,
         taskName?: string;
         jobId?: string;
         error?: string;
+        stack?: string;
     }) => 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

@@ -2,7 +2,7 @@ import { createD1DurableBatchStore, createJobBatch, settleBatchMember } from "./
 import { createCfJobsBroadcastBatchProgressHandler, createCfJobsBroadcastRepositoryHooks } from "./broadcast.js";
 import { createD1DurableJobRepository } from "./d1.js";
 import { dispatchRegisteredJob } from "./dispatch.js";
-import { formatJobError } from "./errors.js";
+import { describeCause, describeCauseWithStack, formatJobError } from "./errors.js";
 import { createMessageDedup } from "./message-dedup.js";
 import { metricsSinkToRepoHooks } from "./metrics.js";
 import { createQueuePublisher, enqueueDurableJob, prepareDurableJob, pruneDurableJobs, runDurableJobMessage } from "./outbox.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: error instanceof Error ? error.message : String(error) });
+    opts.onLog?.({ stage: "unexpected", taskName, error: describeCause(error), stack: describeCauseWithStack(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: error instanceof Error ? error.message : String(error) });
+      opts.onLog?.({ stage: "onfinish-failed", taskName: c.name, jobId: batch.id, error: describeCause(error), stack: describeCauseWithStack(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.0",
+  "version": "0.12.2",
   "description": "Nuxt module for typed Cloudflare queue jobs.",
   "author": {
     "name": "Harlan Wilton",
@@ -86,20 +86,20 @@
     "@nuxt/module-builder": "^1.0.2",
     "@nuxt/test-utils": "^4.0.3",
     "@types/node": "^26.1.0",
-    "@vitest/coverage-v8": "4.1.9",
+    "@vitest/coverage-v8": "4.1.10",
     "eslint": "^10.6.0",
     "eslint-plugin-harlanzw": "latest",
     "eslint-plugin-vue": "latest",
-    "h3": "2.0.1-rc.22",
+    "h3": "2.0.1-rc.23",
     "happy-dom": "^20.10.6",
     "nitropack": "^2.13.4",
     "nuxt": "^4.4.8",
     "typescript": "^6.0.3",
     "unbuild": "^3.6.1",
-    "vitest": "^4.1.9",
+    "vitest": "^4.1.10",
     "vue": "^3.5.39",
     "vue-tsc": "^3.3.6",
-    "wrangler": "^4.106.0"
+    "wrangler": "^4.107.0"
   },
   "scripts": {
     "build": "nuxt-module-build build && nuxt-module-build prepare",