nuxt-cf-jobs 0.0.2

package/dist/runtime/server/schema.js

@@ -0,0 +1,80 @@
+import { sql } from "drizzle-orm";
+import { index, integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
+export const cfJobBatches = sqliteTable("job_batches", {
+  id: text("id").primaryKey(),
+  name: text("name"),
+  parentBatchId: text("parent_batch_id"),
+  totalJobs: integer("total_jobs").notNull().default(0),
+  pendingJobs: integer("pending_jobs").notNull().default(0),
+  failedJobs: integer("failed_jobs").notNull().default(0),
+  onFinish: text("on_finish"),
+  handler: text("handler"),
+  allowFailures: integer("allow_failures").default(0),
+  siteId: text("site_id"),
+  userId: integer("user_id"),
+  createdAt: integer("created_at").notNull().default(sql`(unixepoch())`),
+  updatedAt: integer("updated_at").notNull().default(sql`(unixepoch())`),
+  finishedAt: integer("finished_at")
+}, (t) => [
+  index("idx_job_batches_site").on(t.siteId),
+  index("idx_job_batches_pending").on(t.pendingJobs),
+  index("idx_job_batches_parent").on(t.parentBatchId),
+  index("idx_job_batches_finished_at").on(t.finishedAt)
+]);
+export const cfJobs = sqliteTable("jobs", {
+  id: text("id").primaryKey(),
+  queue: text("queue").notNull(),
+  jobType: text("job_type").notNull(),
+  batchId: text("batch_id").references(() => cfJobBatches.id),
+  userId: integer("user_id"),
+  siteId: text("site_id"),
+  partnerId: text("partner_id"),
+  traceId: text("trace_id"),
+  uniqueKey: text("unique_key"),
+  payload: text("payload").notNull(),
+  attempts: integer("attempts").default(0),
+  maxAttempts: integer("max_attempts").default(3),
+  reservedAt: integer("reserved_at"),
+  availableAt: integer("available_at").notNull(),
+  createdAt: integer("created_at").notNull().default(sql`(unixepoch())`),
+  completedAt: integer("completed_at"),
+  failedAt: integer("failed_at"),
+  lastError: text("last_error"),
+  retryReasons: text("retry_reasons"),
+  rowsFetched: integer("rows_fetched"),
+  rowsInserted: integer("rows_inserted"),
+  d1RowsRead: integer("d1_rows_read"),
+  d1RowsWritten: integer("d1_rows_written"),
+  durationMs: integer("duration_ms")
+}, (t) => [
+  index("idx_jobs_claimable").on(t.queue, t.reservedAt, t.availableAt),
+  index("idx_jobs_user").on(t.userId),
+  index("idx_jobs_site").on(t.siteId),
+  index("idx_jobs_partner").on(t.partnerId),
+  index("idx_jobs_type").on(t.jobType),
+  index("idx_jobs_batch").on(t.batchId),
+  index("idx_jobs_trace").on(t.traceId),
+  index("idx_jobs_sync_dedup").on(t.siteId, t.jobType),
+  uniqueIndex("idx_jobs_unique_active").on(t.uniqueKey).where(sql`unique_key IS NOT NULL AND completed_at IS NULL AND failed_at IS NULL`)
+]);
+export const cfFailedJobs = sqliteTable("failed_jobs", {
+  id: text("id").primaryKey(),
+  queue: text("queue").notNull(),
+  jobType: text("job_type").notNull(),
+  batchId: text("batch_id"),
+  userId: integer("user_id"),
+  siteId: text("site_id"),
+  partnerId: text("partner_id"),
+  traceId: text("trace_id"),
+  uniqueKey: text("unique_key"),
+  payload: text("payload").notNull(),
+  exception: text("exception").notNull(),
+  attempts: integer("attempts").notNull(),
+  maxAttempts: integer("max_attempts").notNull(),
+  failedAt: integer("failed_at").notNull()
+}, (t) => [
+  index("idx_failed_jobs_queue").on(t.queue),
+  index("idx_failed_jobs_site").on(t.siteId),
+  index("idx_failed_jobs_trace").on(t.traceId),
+  index("idx_failed_jobs_failed_at").on(t.failedAt)
+]);

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

@@ -0,0 +1,34 @@
+import type { CloudflareQueue, QueueBatch, QueueMessage } from './types.js';
+export interface FakeQueuedMessage<T> {
+    body: T;
+    opts?: {
+        delaySeconds?: number;
+    };
+}
+export declare function createFakeQueue<T = unknown>(): {
+    queue: CloudflareQueue<T>;
+    messages: FakeQueuedMessage<T>[];
+    clear(): void;
+};
+export declare function createFakeQueueEnv<T = unknown>(binding?: string): {
+    queue: CloudflareQueue<T>;
+    messages: FakeQueuedMessage<T>[];
+    clear(): void;
+    env: {
+        [binding]: CloudflareQueue<T>;
+    };
+};
+export declare function createQueueMessage<T>(body: T, attempts?: number, id?: string): QueueMessage<T> & {
+    acked: boolean;
+    retries: Array<{
+        delaySeconds?: number;
+    } | undefined>;
+};
+export declare function createQueueBatch<T>(queue: string, bodies: T[], opts?: {
+    ids?: string[];
+}): QueueBatch<T> & {
+    ackedAll: boolean;
+    retriedAll: Array<{
+        delaySeconds?: number;
+    } | undefined>;
+};

package/dist/runtime/server/testing.js

@@ -0,0 +1,61 @@
+export function createFakeQueue() {
+  const messages = [];
+  const queue = {
+    async send(message, opts) {
+      messages.push({ body: message, opts });
+    },
+    async sendBatch(batch, opts) {
+      for (const message of batch) {
+        const perMessage = message.delaySeconds !== void 0 || message.contentType !== void 0 ? { delaySeconds: message.delaySeconds, contentType: message.contentType } : void 0;
+        messages.push({ body: message.body, opts: perMessage ?? opts });
+      }
+    }
+  };
+  return {
+    queue,
+    messages,
+    clear() {
+      messages.length = 0;
+    }
+  };
+}
+export function createFakeQueueEnv(binding = "QUEUE") {
+  const fake = createFakeQueue();
+  return {
+    env: { [binding]: fake.queue },
+    ...fake
+  };
+}
+export function createQueueMessage(body, attempts = 0, id) {
+  return {
+    id,
+    body,
+    attempts,
+    acked: false,
+    retries: [],
+    ack() {
+      this.acked = true;
+    },
+    retry(opts) {
+      this.retries.push(opts);
+    }
+  };
+}
+export function createQueueBatch(queue, bodies, opts) {
+  const messages = bodies.map((body, i) => createQueueMessage(body, 0, opts?.ids?.[i]));
+  const batch = {
+    queue,
+    messages,
+    ackedAll: false,
+    retriedAll: [],
+    ackAll() {
+      batch.ackedAll = true;
+      for (const message of messages) message.ack();
+    },
+    retryAll(retryOpts) {
+      batch.retriedAll.push(retryOpts);
+      for (const message of messages) message.retry(retryOpts);
+    }
+  };
+  return batch;
+}

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

@@ -0,0 +1,123 @@
+export type QueueMessageContentType = 'text' | 'json' | 'bytes' | 'v8';
+export interface QueueSendOptions {
+    delaySeconds?: number;
+    contentType?: QueueMessageContentType;
+}
+export interface QueueRetryOptions {
+    delaySeconds?: number;
+}
+export interface QueueMessage<T = unknown> {
+    id?: string;
+    body: T;
+    attempts: number;
+    timestamp?: Date | number;
+    ack: () => void;
+    retry: (opts?: QueueRetryOptions) => void;
+}
+export interface QueueBatch<T = unknown> {
+    queue: string;
+    messages: Array<QueueMessage<T>>;
+    ackAll?: () => void;
+    retryAll?: (opts?: QueueRetryOptions) => void;
+}
+export interface QueuePayload<T = unknown, Env extends Record<string, unknown> = Record<string, unknown>> {
+    batch: QueueBatch<T>;
+    env: Env;
+}
+export interface CloudflareQueueSendBatchMessage<T = unknown> {
+    body: T;
+    contentType?: QueueMessageContentType;
+    delaySeconds?: number;
+}
+export interface CloudflareQueue<T = unknown> {
+    send: (message: T, opts?: QueueSendOptions) => Promise<void>;
+    sendBatch?: (messages: Array<CloudflareQueueSendBatchMessage<T>>, opts?: QueueSendOptions) => Promise<void>;
+}
+export interface QueueBindingConfig {
+    binding: string;
+    queueName?: string;
+    jobType?: string;
+    /** Wrangler `[[queues.consumers]].max_batch_size` (informational; validated against handler expectations). */
+    maxBatchSize?: number;
+    /** Wrangler `[[queues.consumers]].max_batch_timeout` in seconds. */
+    maxBatchTimeout?: number;
+    /** Wrangler `[[queues.consumers]].max_concurrency`. */
+    maxConcurrency?: number;
+    /** Wrangler `[[queues.consumers]].max_retries`. Compared against `definition.tries`. */
+    maxRetries?: number;
+    /** Wrangler `[[queues.consumers]].retry_delay` in seconds (default retry delay if none supplied per-message). */
+    retryDelay?: number;
+    /** Wrangler `[[queues.consumers]].dead_letter_queue` — the *Cloudflare* queue name. */
+    deadLetterQueue?: string;
+    /** Binding name of the DLQ producer, used when this module manually forwards exhausted messages. */
+    deadLetterQueueBinding?: string;
+}
+export type QueueBindingsConfig = Record<string, string | QueueBindingConfig>;
+export interface JobControlResult {
+    handled: boolean;
+    action?: 'released' | 'failed';
+    delaySeconds?: number;
+    error?: string;
+}
+export interface JobContext<Env, Db, Logger> {
+    env: Env;
+    jobId: string;
+    batchId: string | null;
+    attempt: number;
+    db: Db;
+    log: Logger;
+    release: (delaySeconds: number) => Promise<void>;
+    fail: (error: string) => Promise<void>;
+}
+export type JobHandler<Payload, Env, Db, Logger> = (payload: Payload, ctx: JobContext<Env, Db, Logger>) => Promise<void>;
+export type JobFailedHandler<Payload, Env, Db, Logger> = (payload: Payload, ctx: JobContext<Env, Db, Logger>, error: unknown) => Promise<void>;
+export type JobNext = () => Promise<void>;
+export type JobMiddleware<Payload, Env, Db, Logger> = (payload: Payload, ctx: JobContext<Env, Db, Logger>, next: JobNext) => Promise<void>;
+export type JobBackoff = number | number[] | ((attempt: number) => number);
+export type JobPayloadParseResult<Payload> = {
+    success: true;
+    data: Payload;
+} | {
+    success: false;
+    error: unknown;
+};
+export interface JobPayloadSchema<Payload> {
+    safeParse: (payload: unknown) => JobPayloadParseResult<Payload>;
+}
+export interface JobDefinition<Name extends string, Payload, Queue extends string, Env, Db, Logger> {
+    name: Name;
+    queue: Queue;
+    jobType?: string;
+    input?: JobPayloadSchema<Payload>;
+    handle: JobHandler<Payload, Env, Db, Logger>;
+    failed?: JobFailedHandler<Payload, Env, Db, Logger>;
+    middleware?: Array<JobMiddleware<Payload, Env, Db, Logger>>;
+    tries?: number;
+    maxAttempts?: number;
+    backoff?: JobBackoff;
+    unique?: boolean;
+    uniqueId?: (payload: Payload) => string;
+}
+export interface DispatchableJob<Payload = Record<string, unknown>> {
+    id: string;
+    queue: string;
+    payload: Payload;
+    attempts: number;
+    batchId: string | null;
+    siteId?: string | null;
+    userId?: number | null;
+}
+export interface DispatchResult {
+    success: boolean;
+    error?: string;
+    handlerNotFound?: boolean;
+    invalidPayload?: boolean;
+    validationError?: unknown;
+    control?: JobControlResult;
+}
+export type QueueHandlerResult = {
+    action: 'ack';
+} | {
+    action: 'retry';
+    delaySeconds?: number;
+};

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "nuxt-cf-jobs",
+  "type": "module",
+  "version": "0.0.2",
+  "description": "Nuxt module for typed Cloudflare queue jobs.",
+  "author": {
+    "name": "Harlan Wilton",
+    "email": "harlan@harlanzw.com",
+    "url": "https://harlanzw.com/"
+  },
+  "contributors": [
+    "Harlan Wilton <harlan@harlanzw.com>"
+  ],
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs",
+      "default": "./dist/module.mjs"
+    },
+    "./server": {
+      "types": "./dist/runtime/server/index.d.ts",
+      "import": "./dist/runtime/server/index.js",
+      "default": "./dist/runtime/server/index.js"
+    },
+    "./d1": {
+      "types": "./dist/runtime/server/d1.d.ts",
+      "import": "./dist/runtime/server/d1.js",
+      "default": "./dist/runtime/server/d1.js"
+    },
+    "./durable": {
+      "types": "./dist/runtime/server/outbox.d.ts",
+      "import": "./dist/runtime/server/outbox.js",
+      "default": "./dist/runtime/server/outbox.js"
+    },
+    "./queue": {
+      "types": "./dist/runtime/server/queue.d.ts",
+      "import": "./dist/runtime/server/queue.js",
+      "default": "./dist/runtime/server/queue.js"
+    },
+    "./schema": {
+      "types": "./dist/runtime/server/schema.d.ts",
+      "import": "./dist/runtime/server/schema.js",
+      "default": "./dist/runtime/server/schema.js"
+    },
+    "./testing": {
+      "types": "./dist/runtime/server/testing.d.ts",
+      "import": "./dist/runtime/server/testing.js",
+      "default": "./dist/runtime/server/testing.js"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "types": "./dist/types.d.mts",
+  "typesVersions": {
+    "*": {
+      "server": [
+        "dist/runtime/server/index.d.ts"
+      ],
+      "d1": [
+        "dist/runtime/server/d1.d.ts"
+      ],
+      "durable": [
+        "dist/runtime/server/outbox.d.ts"
+      ],
+      "queue": [
+        "dist/runtime/server/queue.d.ts"
+      ],
+      "schema": [
+        "dist/runtime/server/schema.d.ts"
+      ],
+      "testing": [
+        "dist/runtime/server/testing.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "nuxt": ">=3.0.0 <5.0.0"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.4.6",
+    "@nuxt/schema": "^4.4.6",
+    "drizzle-orm": "0.45.2"
+  },
+  "devDependencies": {
+    "@nuxt/module-builder": "^1.0.2",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "4.1.7",
+    "happy-dom": "^20.9.0",
+    "nuxt": "^4.4.6",
+    "typescript": "^6.0.3",
+    "unbuild": "^3.6.1",
+    "vitest": "^4.1.7",
+    "vue": "^3.5.34",
+    "vue-tsc": "^3.3.1",
+    "wrangler": "^4.94.0"
+  },
+  "scripts": {
+    "build": "nuxt-module-build build && nuxt-module-build prepare",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare",
+    "test": "vitest run tests/dispatch.test.ts --typecheck=false",
+    "test:unit": "vitest run tests/dispatch.test.ts --typecheck=false",
+    "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"
+  }
+}