nuxt-cf-jobs 0.0.2

package/README.md

@@ -0,0 +1,331 @@
+# nuxt-cf-jobs
+
+Typed Cloudflare Queue jobs for Nuxt.
+
+`nuxt-cf-jobs` scans your Nuxt server job files, generates a typed registry, and gives you small runtime helpers for:
+
+- building typed queue payloads
+- sending jobs to Cloudflare Queue bindings
+- consuming Cloudflare queue batches through Nitro hooks
+- persisting durable jobs in D1
+- testing queues without Cloudflare
+
+## Install
+
+```bash
+pnpm add nuxt-cf-jobs
+```
+
+Add the module:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-cf-jobs'],
+  cfJobs: {
+    queues: {
+      default: 'QUEUE_DEFAULT',
+      analytics: {
+        binding: 'QUEUE_ANALYTICS',
+        queueName: 'analytics-production',
+        jobType: 'analytics',
+      },
+    },
+    jobsDir: 'server/jobs',
+  },
+})
+```
+
+`queues` maps your logical queue names to Cloudflare environment binding names. The string form uses the logical name as the Cloudflare queue name. The object form lets the Cloudflare queue name differ from the logical name.
+
+## Define Jobs
+
+Create default-exported jobs under `server/jobs`:
+
+```ts
+// server/jobs/sync/table.ts
+import { defineJob } from '#cf-jobs/server'
+
+export default defineJob({
+  name: 'sync/table',
+  queue: 'default',
+  async handle(payload: {
+    siteId: string
+    userId: number
+    table: string
+    priority?: 'low' | 'normal'
+  }, ctx) {
+    ctx.log.info('syncing table', payload.table)
+  },
+})
+```
+
+Job names are derived from file paths for the generated registry, so this file is available as `sync/table`. Duplicate derived names fail during template generation.
+
+The module ignores private/test files by default:
+
+```ts
+jobsIgnore: ['**/_*.ts', '**/*.d.ts', '**/*.test.ts', '**/*.spec.ts']
+```
+
+## Use The Typed Registry
+
+The generated registry is available as `#cf-jobs/app` by default.
+
+```ts
+import {
+  buildJobPayload,
+  getJobDefinition,
+  getQueue,
+  prepareJob,
+  type JobName,
+  type JobPayload,
+} from '#cf-jobs/app'
+
+const name: JobName = 'sync/table'
+
+const payload = {
+  siteId: 'site_1',
+  userId: 123,
+  table: 'pages',
+  priority: 'low',
+} satisfies JobPayload<'sync/table'>
+
+const message = buildJobPayload(name, payload)
+const definition = getJobDefinition(name)
+```
+
+Unknown job names and invalid payload shapes are rejected by TypeScript when the job payload type can be inferred from the job definition.
+
+## Send Jobs
+
+Use `getQueue(event, jobDefinition)` inside server routes, event handlers, Nitro plugins, or other server code where you have an `H3Event` or Cloudflare env-like source.
+
+```ts
+// server/api/sync.post.ts
+import { getJobDefinition, getQueue } from '#cf-jobs/app'
+
+export default defineEventHandler(async (event) => {
+  const job = getJobDefinition('sync/table')
+  if (!job)
+    throw createError({ statusCode: 500, statusMessage: 'Job not registered' })
+
+  const queue = getQueue(event, job)
+  const queued = await queue.send({
+    siteId: 'site_1',
+    userId: 123,
+    table: 'pages',
+  })
+
+  return { queued }
+})
+```
+
+`queue.send()` returns `false` when the configured Cloudflare binding is unavailable. That lets development or unsupported runtimes fail explicitly without throwing.
+
+In Nuxt dev, the module installs a dev-only Nitro plugin that creates in-memory queue bindings from your `cfJobs.queues` config and forwards messages to the `cloudflare:queue` hook.
+
+## Consume Queue Batches
+
+Register a queue consumer from a Nitro plugin:
+
+```ts
+// server/plugins/cf-jobs.ts
+import { registerQueueConsumer } from '#cf-jobs/app'
+
+export default defineNitroPlugin((nitroApp) => {
+  registerQueueConsumer(nitroApp, {
+    createContext({ env, job, message, control }) {
+      return {
+        env,
+        db: null,
+        log: console,
+        jobId: job.id,
+        batchId: job.batchId,
+        attempt: message.attempts,
+        async release(delaySeconds: number) {
+          control.handled = true
+          control.action = 'released'
+          control.delaySeconds = delaySeconds
+          message.retry({ delaySeconds })
+        },
+        async fail(error: string) {
+          control.handled = true
+          control.action = 'failed'
+          control.error = error
+          message.ack()
+        },
+      }
+    },
+  })
+})
+```
+
+The generated `registerQueueConsumer()` wires the generated registry and `runtimeConfig.cfJobs.queues` for you. You provide only the application-specific context.
+
+Useful options:
+
+```ts
+registerQueueConsumer(nitroApp, {
+  createContext,
+  getJobId: ({ payload }) => String(payload.jobId),
+  getSiteId: payload => typeof payload.siteId === 'string' ? payload.siteId : null,
+  getUserId: payload => typeof payload.userId === 'number' ? payload.userId : null,
+  retryDelaySeconds: ({ error, job }) => 30,
+  onInvalidPayload: input => console.warn(input.error),
+  onDispatchError: input => console.error(input.error),
+})
+```
+
+If you do not provide `getJobId`, the consumer uses `payload.jobId` when present, otherwise a stable serialized payload ID.
+
+## Durable D1 Jobs
+
+For jobs that should survive process restarts or queue delivery issues, persist a durable job record first, then enqueue a lightweight queue message.
+
+```ts
+import {
+  createD1DurableJobRepository,
+  createQueuePublisher,
+  enqueueDurableJob,
+} from 'nuxt-cf-jobs/server'
+import { prepareJob } from '#cf-jobs/app'
+
+export default defineEventHandler(async (event) => {
+  const env = event.context.cloudflare?.env as {
+    DB: D1Database
+    QUEUE_DEFAULT: Queue
+  }
+
+  const repository = createD1DurableJobRepository(env.DB)
+  await repository.migrate()
+
+  const publisher = createQueuePublisher(env, queue =>
+    queue === 'default' ? 'QUEUE_DEFAULT' : undefined,
+  )
+
+  const record = await prepareJob({
+    name: 'sync/table',
+    payload: {
+      siteId: 'site_1',
+      userId: 123,
+      table: 'pages',
+    },
+  })
+
+  return await enqueueDurableJob(repository, publisher, record)
+})
+```
+
+Consume durable queue messages with `runDurableJobMessage()` and the D1 repository:
+
+```ts
+import { runDurableJobMessage } from 'nuxt-cf-jobs/durable'
+import { createD1DurableJobRepository } from 'nuxt-cf-jobs/d1'
+import { jobRegistry } from '#cf-jobs/app'
+
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('cloudflare:queue', async ({ batch, env }) => {
+    const repository = createD1DurableJobRepository(env.DB)
+
+    for (const message of batch.messages) {
+      await runDurableJobMessage({
+        message,
+        lifecycle: repository,
+        registry: jobRegistry,
+        toDispatchableJob: repository.toDispatchableJob,
+        createJobContext({ job, storedJob, control }) {
+          return {
+            env,
+            db: env.DB,
+            log: console,
+            jobId: job.id,
+            batchId: job.batchId,
+            attempt: job.attempts,
+            async release(delaySeconds: number) {
+              control.handled = true
+              control.action = 'released'
+              control.delaySeconds = delaySeconds
+              await repository.releaseJob(storedJob, { delaySeconds })
+              message.retry({ delaySeconds })
+            },
+            async fail(error: string) {
+              control.handled = true
+              control.action = 'failed'
+              control.error = error
+              await repository.failJob(storedJob, error)
+            },
+          }
+        },
+      })
+    }
+  })
+})
+```
+
+`createD1DurableJobRepository()` exposes:
+
+- `migrate()`
+- `insertJob()`
+- `claimJob()`
+- `completeJob()`
+- `failJob()`
+- `releaseJob()`
+- `findDispatchableJobs()`
+- `findStaleReservedJobs()`
+- `releaseStaleReservedJobs()`
+- `toDispatchableJob()`
+
+## Runtime Validation
+
+The generated registry validates jobs at startup. It fails loudly for:
+
+- invalid job definitions
+- duplicate job names
+- missing or invalid queue names
+
+Queue binding checks are available from `#cf-jobs/app`:
+
+```ts
+import { assertQueueBindings, validateQueueBindings } from '#cf-jobs/app'
+
+const issues = validateQueueBindings()
+assertQueueBindings()
+```
+
+## Public Imports
+
+Use the narrow subpaths when you can:
+
+```ts
+import { defineJob } from 'nuxt-cf-jobs/server'
+import { runDurableJobMessage } from 'nuxt-cf-jobs/durable'
+import { createD1DurableJobRepository } from 'nuxt-cf-jobs/d1'
+import { createFakeQueue } from 'nuxt-cf-jobs/testing'
+```
+
+Available package subpaths:
+
+- `nuxt-cf-jobs` - Nuxt module
+- `nuxt-cf-jobs/server` - full server runtime barrel
+- `nuxt-cf-jobs/d1` - D1 durable repository adapter
+- `nuxt-cf-jobs/durable` - durable outbox helpers
+- `nuxt-cf-jobs/queue` - queue binding and consumer helpers
+- `nuxt-cf-jobs/schema` - Drizzle schema
+- `nuxt-cf-jobs/testing` - fake queue helpers
+
+Inside a Nuxt app, prefer the generated aliases:
+
+- `#cf-jobs/server` for server runtime helpers
+- `#cf-jobs/app` for your generated typed job registry
+
+## Tests
+
+```bash
+pnpm test
+pnpm typecheck
+pnpm build
+pnpm test:e2e
+```
+
+`pnpm test:e2e` starts Wrangler fixtures and requires the local Cloudflare/Wrangler toolchain to be available.

package/dist/module.d.mts

@@ -0,0 +1,73 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface QueueBindingOptions {
+    binding: string;
+    queueName?: string;
+    jobType?: string;
+    maxBatchSize?: number;
+    maxBatchTimeout?: number;
+    maxConcurrency?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+    /** Cloudflare queue name of the DLQ (mirrors wrangler `dead_letter_queue`). */
+    deadLetterQueue?: string;
+    /** Binding name of the DLQ producer so the module can forward exhausted messages. */
+    deadLetterQueueBinding?: string;
+}
+interface ModuleOptions {
+    /**
+     * Logical queue name -> Cloudflare env binding name.
+     *
+     * Example:
+     * {
+     *   "lh-scans": "QUEUE_LH_SCANS",
+     *   "sync-critical": { binding: "SYNC_CRITICAL", jobType: "sync" }
+     * }
+     */
+    queues: Record<string, string | QueueBindingOptions>;
+    /**
+     * Logical queue name used when a job omits `queue` on its `defineJob` call.
+     * Must be a key of `queues`.
+     */
+    defaultQueue?: string;
+    /**
+     * Directories scanned at build/dev time for default-exported job definitions.
+     * Relative paths are resolved from the Nuxt root directory.
+     */
+    jobsDir?: string | string[];
+    /**
+     * Glob pattern used inside each jobsDir.
+     */
+    jobsPattern?: string | string[];
+    /**
+     * Extra glob ignore patterns for jobsDir scanning.
+     */
+    jobsIgnore?: string[];
+    /**
+     * Alias for the generated typed registry module.
+     */
+    registryAlias?: string;
+    /**
+     * Cross-check the user's wrangler config against `queues` at build time
+     * and emit `.nuxt/cf-jobs/wrangler.suggested.toml`. Defaults to `true`.
+     */
+    validateWrangler?: boolean;
+    /**
+     * Override the wrangler config path (relative to rootDir).
+     * Defaults to scanning for `wrangler.jsonc`, `wrangler.json`, `wrangler.toml`.
+     */
+    wranglerPath?: string;
+}
+
+declare module '@nuxt/schema' {
+    interface RuntimeConfig {
+        cfJobs: {
+            queues: ModuleOptions['queues'];
+            defaultQueue?: string;
+        };
+    }
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-cf-jobs",
+  "configKey": "cfJobs",
+  "version": "0.0.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}