nuxt-cf-jobs 0.3.0 → 0.4.0

package/README.md

@@ -275,6 +275,43 @@ export default defineNitroPlugin((nitroApp) => {
 - `releaseStaleReservedJobs()`
 - `toDispatchableJob()`
 
+## Scheduled Tasks (cron)
+
+Queue jobs handle per-request deferred work; **scheduled tasks** handle cron work. `defineScheduledTask` co-locates the cron schedule with its handler, and the module derives `nitro.tasks`, `nitro.scheduledTasks`, and the Cloudflare `triggers.crons` from it — so there is no central list to keep in sync (and no way for the three to silently drift apart).
+
+```ts
+// server/tasks/cleanup.ts
+export default defineScheduledTask({
+  name: 'db:cleanup', // nitro task name (also the runTask id)
+  cron: '0 3 * * *', // or cron: ['0 3 * * *', '0 */6 * * *']
+  description: 'Nightly cleanup',
+  run() {
+    // ...same shape as nitro defineTask's run
+    return { result: 'ok' }
+  },
+})
+```
+
+Enable scanning via `cfJobs.tasksDir`:
+
+```ts
+export default defineNuxtConfig({
+  cfJobs: {
+    // `true` → auto-discover `server/tasks` in the app AND every extended layer
+    // (nuxt.options._layers), so a new layer with cron work needs no host config.
+    tasksDir: true,
+    // …or be explicit: tasksDir: ['server/tasks', '../some-layer/server/tasks']
+  },
+})
+```
+
+Notes:
+
+- `name` and `cron` must be **string literals** — the module reads them statically at build time (without executing the file, which typically imports a DB/server utils that won't load outside nitro). Computed values are skipped with a warning.
+- Plain nitro `defineTask` files in the same dirs are still registered (so they're runnable via `runTask`), just not scheduled.
+- `nitro.scheduledTasks` is populated only outside dev by default (so crons don't fire locally); override with `cfJobs.scheduledTasks: true | false`. The deploy-only `triggers.crons` is always written.
+- Opt-in: nothing is scanned or registered unless `tasksDir` is set.
+
 ## CLI
 
 The package ships a `cf-jobs` binary, an `artisan queue:*`-style tool for inspecting and managing the durable D1 job tables. It queries D1 through `wrangler d1 execute`, so it works against both the local miniflare database (default) and production (`--remote`), auto-detecting the D1 binding from your wrangler config.

package/dist/module.d.mts

@@ -106,6 +106,14 @@ declare module '@nuxt/schema' {
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 declare function generateRegistryTemplate(options: ModuleOptions, rootDir: string, templateDir: string): Promise<string>;
+/**
+ * Emits a `declare module '#cf-jobs/app'` augmentation. The data-only runtime
+ * `registry.ts` carries no hand-written types; this augmentation MERGES the
+ * type-only aliases into that module so consumers can `import type { JobName,
+ * JobPayload } from '#cf-jobs/app'`. Types are derived from each job's *full*
+ * default-export type via `typeof import(...)` — purely type-level, so no
+ * handler module is loaded to compute them.
+ */
 declare function generateRegistryTypesTemplate(options: ModuleOptions, rootDir: string, templateDir: string): Promise<string>;
 
 export { _default as default, generateRegistryTemplate, generateRegistryTypesTemplate };

package/dist/module.json

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

package/dist/module.mjs

@@ -1,9 +1,108 @@
 import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { resolve, relative, sep } from 'node:path';
-import { defineNuxtModule, createResolver, addServerImports, addTemplate, updateTemplates, useLogger, addServerPlugin, resolveFiles } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addServerImports, addTemplate, addTypeTemplate, updateTemplates, useLogger, addServerPlugin, resolveFiles } from '@nuxt/kit';
+import { parseModule } from 'magicast';
 import { cfJobsAppExportNames } from '../dist/runtime/server/app.js';
 import { c as collectTasks, f as findDuplicateTaskNames, b as buildCronUnion, a as buildScheduledTasks, g as renderSuggestedCronsToml, e as findWranglerConfig, p as parseWranglerConfig, d as crossCheckCrons, r as reconcileQueues } from './shared/nuxt-cf-jobs.C2yTYlMg.mjs';
-import 'node:fs/promises';
+
+function isNode(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+function emptyMeta() {
+  return { hasInput: false, hasUniqueId: false };
+}
+function findDefineJobCall(node) {
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      const found = findDefineJobCall(child);
+      if (found)
+        return found;
+    }
+    return void 0;
+  }
+  if (!isNode(node))
+    return void 0;
+  if (node.type === "CallExpression") {
+    const callee = node.callee;
+    if (isNode(callee) && callee.type === "Identifier" && callee.name === "defineJob")
+      return node;
+  }
+  for (const key in node) {
+    if (key === "type")
+      continue;
+    const found = findDefineJobCall(node[key]);
+    if (found)
+      return found;
+  }
+  return void 0;
+}
+function propKeyName(prop) {
+  const key = prop.key;
+  if (!isNode(key))
+    return void 0;
+  if (key.type === "Identifier" && typeof key.name === "string")
+    return key.name;
+  if (key.type === "StringLiteral" && typeof key.value === "string")
+    return key.value;
+  return void 0;
+}
+function extractJobMeta(code) {
+  const meta = emptyMeta();
+  let ast;
+  try {
+    ast = parseModule(code).$ast;
+  } catch {
+    return meta;
+  }
+  const call = findDefineJobCall(ast);
+  if (!call)
+    return meta;
+  const args = call.arguments;
+  const arg = Array.isArray(args) ? args[0] : void 0;
+  if (!isNode(arg) || arg.type !== "ObjectExpression")
+    return meta;
+  const properties = Array.isArray(arg.properties) ? arg.properties : [];
+  for (const prop of properties) {
+    if (!isNode(prop) || prop.type !== "ObjectProperty")
+      continue;
+    if (prop.computed === true)
+      continue;
+    const name = propKeyName(prop);
+    if (!name)
+      continue;
+    const value = prop.value;
+    switch (name) {
+      case "queue":
+        if (isNode(value) && value.type === "StringLiteral" && typeof value.value === "string")
+          meta.queue = value.value;
+        break;
+      case "jobType":
+        if (isNode(value) && value.type === "StringLiteral" && typeof value.value === "string")
+          meta.jobType = value.value;
+        break;
+      case "maxAttempts":
+        if (isNode(value) && value.type === "NumericLiteral" && typeof value.value === "number")
+          meta.maxAttempts = value.value;
+        break;
+      case "tries":
+        if (isNode(value) && value.type === "NumericLiteral" && typeof value.value === "number")
+          meta.tries = value.value;
+        break;
+      case "unique":
+        if (isNode(value) && value.type === "BooleanLiteral" && typeof value.value === "boolean")
+          meta.unique = value.value;
+        break;
+      case "input":
+        meta.hasInput = true;
+        break;
+      case "uniqueId":
+        meta.hasUniqueId = true;
+        break;
+    }
+  }
+  return meta;
+}
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -33,16 +132,15 @@ const module$1 = defineNuxtModule({
       write: true,
       getContents: async () => generateRegistryTemplate(options, nuxt.options.rootDir, resolve(nuxt.options.buildDir, "cf-jobs"))
     });
-    addTemplate({
-      filename: "cf-jobs/registry.d.ts",
-      write: true,
-      getContents: async () => generateRegistryTypesTemplate(options, nuxt.options.rootDir, resolve(nuxt.options.buildDir, "cf-jobs"))
-    });
     nuxt.options.alias[options.registryAlias ?? "#cf-jobs/app"] = registryTemplate.dst;
+    const typesTemplate = addTypeTemplate({
+      filename: "cf-jobs/registry-augmentation.d.ts",
+      getContents: async () => generateRegistryTypesTemplate(options, nuxt.options.rootDir, resolve(nuxt.options.buildDir, "cf-jobs"))
+    }, { nuxt: true, nitro: true });
     nuxt.hooks.hook("builder:watch", (async (_event, path) => {
       if (!isWatchedJobPath(path, options, nuxt.options.rootDir))
         return;
-      await updateTemplates({ filter: (template) => template.dst === registryTemplate.dst });
+      await updateTemplates({ filter: (template) => template.dst === registryTemplate.dst || template.dst === typesTemplate.dst });
     }));
     if (options.defaultQueue && !options.queues[options.defaultQueue])
       useLogger("nuxt-cf-jobs").warn(`cfJobs.defaultQueue="${options.defaultQueue}" is not a key of cfJobs.queues`);
@@ -151,17 +249,36 @@ See ${resolve(templateDir, "wrangler.suggested.toml")} for the expected blocks.`
 async function generateRegistryTemplate(options, rootDir, templateDir) {
   const files = await resolveJobFiles(options, rootDir);
   assertUniqueGeneratedJobNames(files, options, rootDir);
-  const imports = files.map((file, index) => {
-    return `import job${index} from ${JSON.stringify(toImportPath(templateDir, file).replace(/\.ts$/, ""))}`;
-  });
-  const jobItems = files.map((_, index) => `job${index}`).join(", ");
+  const entryLines = await Promise.all(files.map(async (file) => {
+    const name = toJobName(file, options, rootDir);
+    const importPath = toImportPath(templateDir, file).replace(/\.ts$/, "");
+    const meta = extractJobMeta(await readFile(file, "utf8").catch(() => ""));
+    const fields = [`name: ${JSON.stringify(name)}`];
+    if (meta.queue !== void 0)
+      fields.push(`queue: ${JSON.stringify(meta.queue)}`);
+    if (meta.jobType !== void 0)
+      fields.push(`jobType: ${JSON.stringify(meta.jobType)}`);
+    if (meta.maxAttempts !== void 0)
+      fields.push(`maxAttempts: ${meta.maxAttempts}`);
+    if (meta.tries !== void 0)
+      fields.push(`tries: ${meta.tries}`);
+    if (meta.unique !== void 0)
+      fields.push(`unique: ${meta.unique}`);
+    if (meta.hasInput)
+      fields.push(`hasInput: true`);
+    if (meta.hasUniqueId)
+      fields.push(`hasUniqueId: true`);
+    fields.push(`load: () => import(${JSON.stringify(importPath)}).then(m => m.default)`);
+    return `  { ${fields.join(", ")} },`;
+  }));
   return [
     "/* This file is generated by nuxt-cf-jobs. Do not edit directly. */",
     `import { useRuntimeConfig } from 'nitropack/runtime'`,
     `import { createGeneratedCfJobsApp } from 'nuxt-cf-jobs/server'`,
-    ...imports,
     "",
-    `export const jobs = [${jobItems}] as const`,
+    "export const jobs = [",
+    ...entryLines,
+    "]",
     `export const app = createGeneratedCfJobsApp(jobs, useRuntimeConfig, ${options.defaultQueue ? JSON.stringify(options.defaultQueue) : "undefined"})`,
     "",
     "export const {",
@@ -174,29 +291,26 @@ async function generateRegistryTypesTemplate(options, rootDir, templateDir) {
   const files = await resolveJobFiles(options, rootDir);
   assertUniqueGeneratedJobNames(files, options, rootDir);
   const jobTypeLines = files.map((file) => {
-    return `  typeof import(${JSON.stringify(toImportPath(templateDir, file).replace(/\.ts$/, ""))})['default'],`;
+    return `    typeof import(${JSON.stringify(toImportPath(templateDir, file).replace(/\.ts$/, ""))})['default'],`;
   });
   return [
     "/* This file is generated by nuxt-cf-jobs. Do not edit directly. */",
-    `import type { JobMessageByName, JobMessageByQueue, JobNameOf, JobPayloadByName, JobPayloadOf, JobQueueByName, QueueNameOf, QueueConsumerOptions } from 'nuxt-cf-jobs/server'`,
-    `export type { QueueConsumerOptions }`,
+    `import type { JobMessageByName, JobMessageByQueue, JobNameOf, JobPayloadOf, JobQueueByName, QueueNameOf } from 'nuxt-cf-jobs/server'`,
     "",
-    "export declare const jobs: readonly [",
+    `declare module '#cf-jobs/app' {`,
+    `  export type { QueueConsumerOptions } from 'nuxt-cf-jobs/server'`,
+    "  type Jobs = readonly [",
     ...jobTypeLines,
-    "]",
-    "export declare const app: ReturnType<typeof import('nuxt-cf-jobs/server').createCfJobsApp<typeof jobs>>",
-    "",
-    "export type Jobs = typeof jobs",
-    "export type JobsByName = { readonly [Job in Jobs[number] as Job['name']]: Job }",
-    "export type JobName = keyof JobsByName & JobNameOf<Jobs>",
-    "export type JobDefinitionOf<Name extends JobName> = JobsByName[Name]",
-    "export type QueueName = QueueNameOf<Jobs>",
-    "export type JobPayload<Name extends JobName> = JobPayloadOf<JobDefinitionOf<Name>>",
-    "export type JobQueue<Name extends JobName> = JobQueueByName<Jobs, Name>",
-    "export type JobMessage<Name extends JobName> = JobMessageByName<Jobs, Name>",
-    "export type QueueMessage<Queue extends QueueName> = JobMessageByQueue<Jobs, Queue>",
-    "",
-    ...cfJobsAppExportNames.map((name) => `export declare const ${name}: typeof app.${name}`),
+    "  ]",
+    "  type JobsByName = { readonly [Job in Jobs[number] as Job['name']]: Job }",
+    "  export type JobName = keyof JobsByName & JobNameOf<Jobs>",
+    "  export type JobDefinitionOf<Name extends JobName> = JobsByName[Name]",
+    "  export type QueueName = QueueNameOf<Jobs>",
+    "  export type JobPayload<Name extends JobName> = JobPayloadOf<JobDefinitionOf<Name>>",
+    "  export type JobQueue<Name extends JobName> = JobQueueByName<Jobs, Name>",
+    "  export type JobMessage<Name extends JobName> = JobMessageByName<Jobs, Name>",
+    "  export type QueueMessage<Queue extends QueueName> = JobMessageByQueue<Jobs, Queue>",
+    "}",
     ""
   ].join("\n");
 }

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

@@ -1,6 +1,6 @@
 import type { PrepareRegisteredDurableJobOptions } from './outbox.js';
 import type { QueueSource, RegisterRegisteredQueueConsumerOptions } from './queue.js';
-import type { AnyJobDefinition, JobNameOf, JobPayloadByName } from './registry.js';
+import type { AnyJobDefinition, JobNameOf, JobPayloadByName, LazyJobEntry } from './registry.js';
 import type { QueueBindingsConfig } from './types.js';
 import { createJobQueue } from './queue.js';
 export interface CfJobsRuntimeConfig {
@@ -30,8 +30,8 @@ export declare function createCfJobsApp<const Jobs extends readonly AnyJobDefini
     jobs: Jobs;
     jobRegistry: {
         jobs: Jobs;
-        handlers: Map<string, import("./types.js").JobHandler<unknown, unknown, unknown, unknown>>;
-        getHandler(name: string): import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | undefined;
+        getHandler: (name: string) => import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | Promise<import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | undefined> | undefined;
+        loadJobDefinition: (name: string) => Promise<AnyJobDefinition | undefined>;
         getJobDefinition: {
             <Name extends JobNameOf<Jobs>>(name: Name): Extract<Jobs[number], {
                 name: Name;
@@ -54,7 +54,8 @@ export declare function createCfJobsApp<const Jobs extends readonly AnyJobDefini
             extra: string[];
         };
     };
-    getHandler: (name: string) => import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | undefined;
+    getHandler: (name: string) => import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | Promise<import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | undefined> | undefined;
+    loadJobDefinition: (name: string) => Promise<AnyJobDefinition | undefined>;
     getJobDefinition: {
         <Name extends JobNameOf<Jobs>>(name: Name): Extract<Jobs[number], {
             name: Name;
@@ -95,25 +96,25 @@ export declare function createCfJobsApp<const Jobs extends readonly AnyJobDefini
  * `any` param + cast) to the strictly-typed injectable. Keeping this here means
  * the template emits only dynamic data, and the cast is type-checked in source.
  */
-export declare function createGeneratedCfJobsApp<const Jobs extends readonly AnyJobDefinition[]>(jobs: Jobs, useRuntimeConfig: (...args: any[]) => any, defaultQueue?: string): {
-    jobs: Jobs;
+export declare function createGeneratedCfJobsApp<const Jobs extends readonly LazyJobEntry[]>(jobs: Jobs, useRuntimeConfig: (...args: any[]) => any, defaultQueue?: string): {
+    jobs: readonly AnyJobDefinition[];
     jobRegistry: {
-        jobs: Jobs;
-        handlers: Map<string, import("./types.js").JobHandler<unknown, unknown, unknown, unknown>>;
-        getHandler(name: string): import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | undefined;
+        jobs: readonly AnyJobDefinition[];
+        getHandler: (name: string) => import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | Promise<import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | undefined> | undefined;
+        loadJobDefinition: (name: string) => Promise<AnyJobDefinition | undefined>;
         getJobDefinition: {
-            <Name extends JobNameOf<Jobs>>(name: Name): Extract<Jobs[number], {
+            <Name extends string>(name: Name): Extract<AnyJobDefinition, {
                 name: Name;
             }> | undefined;
             (name: string): AnyJobDefinition | undefined;
         };
         getJobQueue: {
-            <Name extends JobNameOf<Jobs>>(name: Name): import("./registry.js").JobQueueByName<Jobs, Name> | undefined;
+            <Name extends string>(name: Name): import("./registry.js").JobQueueByName<readonly AnyJobDefinition[], Name> | undefined;
             (name: string): string | undefined;
         };
-        buildPayload<Name extends JobNameOf<Jobs>>(name: Name, payload: JobPayloadByName<Jobs, Name>): {
+        buildPayload<Name extends string>(name: Name, payload: JobPayloadByName<readonly AnyJobDefinition[], Name>): {
             _task: Name;
-        } & JobPayloadByName<Jobs, Name>;
+        } & JobPayloadByName<readonly AnyJobDefinition[], Name>;
         getJobRoute(name: string): {
             queue: string;
             jobType: string;
@@ -123,15 +124,16 @@ export declare function createGeneratedCfJobsApp<const Jobs extends readonly Any
             extra: string[];
         };
     };
-    getHandler: (name: string) => import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | undefined;
+    getHandler: (name: string) => import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | Promise<import("./types.js").JobHandler<unknown, unknown, unknown, unknown> | undefined> | undefined;
+    loadJobDefinition: (name: string) => Promise<AnyJobDefinition | undefined>;
     getJobDefinition: {
-        <Name extends JobNameOf<Jobs>>(name: Name): Extract<Jobs[number], {
+        <Name extends string>(name: Name): Extract<AnyJobDefinition, {
             name: Name;
         }> | undefined;
         (name: string): AnyJobDefinition | undefined;
     };
     getJobQueue: {
-        <Name extends JobNameOf<Jobs>>(name: Name): import("./registry.js").JobQueueByName<Jobs, Name> | undefined;
+        <Name extends string>(name: Name): import("./registry.js").JobQueueByName<readonly AnyJobDefinition[], Name> | undefined;
         (name: string): string | undefined;
     };
     getJobRoute: (name: string) => {
@@ -145,13 +147,13 @@ export declare function createGeneratedCfJobsApp<const Jobs extends readonly Any
     validateQueueBindings: (queues?: QueueBindingsConfig) => import("./queue.js").QueueBindingValidationIssue[];
     assertQueueBindings: (queues?: QueueBindingsConfig) => void;
     getQueue: {
-        <const Job extends Jobs[number]>(job: Job): import("./queue.js").JobQueuePublisher<Job>;
-        <const Job extends Jobs[number]>(source: QueueSource | undefined, job: Job): import("./queue.js").JobQueuePublisher<Job>;
+        <const Job extends AnyJobDefinition>(job: Job): import("./queue.js").JobQueuePublisher<Job>;
+        <const Job extends AnyJobDefinition>(source: QueueSource | undefined, job: Job): import("./queue.js").JobQueuePublisher<Job>;
     };
-    buildJobPayload: <Name extends JobNameOf<Jobs>>(name: Name, payload: JobPayloadByName<Jobs, Name>) => {
+    buildJobPayload: <Name extends string>(name: Name, payload: JobPayloadByName<readonly AnyJobDefinition[], Name>) => {
         _task: Name;
-    } & JobPayloadByName<Jobs, Name>;
-    prepareJob: <Name extends JobNameOf<Jobs>>(opts: PrepareRegisteredDurableJobOptions<Jobs, Name>) => Promise<import("./outbox.js").DurableJobRecord<import("./registry.js").JobQueueByName<Jobs, Name>>>;
+    } & JobPayloadByName<readonly AnyJobDefinition[], Name>;
+    prepareJob: <Name extends string>(opts: PrepareRegisteredDurableJobOptions<readonly AnyJobDefinition[], Name>) => Promise<import("./outbox.js").DurableJobRecord<import("./registry.js").JobQueueByName<readonly AnyJobDefinition[], Name>>>;
     registerQueueConsumer: <Env extends Record<string, unknown>, Db, Logger>(nitroApp: {
         hooks: {
             hook: (name: any, handler: any) => void;
@@ -161,12 +163,11 @@ export declare function createGeneratedCfJobsApp<const Jobs extends readonly Any
 export type CfJobsApp<Jobs extends readonly AnyJobDefinition[]> = ReturnType<typeof createCfJobsApp<Jobs>>;
 /**
  * Authoritative list of `createCfJobsApp` members re-exported by the generated
- * `#cf-jobs/app` module. The build-time templates (`generateRegistryTemplate` /
- * `generateRegistryTypesTemplate`) map over this so the runtime destructure, the
- * `.d.ts` declarations, and the app's return shape can't drift apart.
+ * `#cf-jobs/app` module. `generateRegistryTemplate` maps over this so the runtime
+ * destructure and the app's return shape can't drift apart.
  *
  * `jobs` is exported separately by the template (as a `const` tuple), so it is
  * intentionally absent here.
  */
-export declare const cfJobsAppExportNames: readonly ["jobRegistry", "getHandler", "getJobDefinition", "getJobQueue", "getJobRoute", "validateRegistry", "validateQueueBindings", "assertQueueBindings", "getQueue", "buildJobPayload", "prepareJob", "registerQueueConsumer"];
+export declare const cfJobsAppExportNames: readonly ["jobRegistry", "getHandler", "loadJobDefinition", "getJobDefinition", "getJobQueue", "getJobRoute", "validateRegistry", "validateQueueBindings", "assertQueueBindings", "getQueue", "buildJobPayload", "prepareJob", "registerQueueConsumer"];
 export type QueueConsumerOptions<Env extends Record<string, unknown>, Db, Logger> = CfJobsQueueConsumerOptions<Env, Db, Logger>;

package/dist/runtime/server/app.js

@@ -69,6 +69,7 @@ ${issues.map((i) => `  - ${i}`).join("\n")}`);
     jobs: materialized,
     jobRegistry,
     getHandler: jobRegistry.getHandler,
+    loadJobDefinition: jobRegistry.loadJobDefinition,
     getJobDefinition: jobRegistry.getJobDefinition,
     getJobQueue: jobRegistry.getJobQueue,
     getJobRoute: jobRegistry.getJobRoute,
@@ -87,6 +88,7 @@ export function createGeneratedCfJobsApp(jobs, useRuntimeConfig, defaultQueue) {
 export const cfJobsAppExportNames = [
   "jobRegistry",
   "getHandler",
+  "loadJobDefinition",
   "getJobDefinition",
   "getJobQueue",
   "getJobRoute",
@@ -99,5 +101,7 @@ export const cfJobsAppExportNames = [
   "registerQueueConsumer"
 ];
 function isJobDefinition(value) {
-  return !!value && typeof value === "object" && typeof value.name === "string" && typeof value.handle === "function";
+  if (!value || typeof value !== "object" || typeof value.name !== "string")
+    return false;
+  return typeof value.handle === "function" || typeof value.load === "function";
 }

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

@@ -1,7 +1,19 @@
 import type { DispatchableJob, DispatchResult, JobContext, JobControlResult, JobDefinition, JobHandler, JobMiddleware } from './types.js';
 export interface JobRegistryLike<Env, Db, Logger> {
-    getHandler: (name: string) => JobHandler<unknown, Env, Db, Logger> | undefined;
+    /** May resolve asynchronously for lazily-loaded jobs; callers must await. */
+    getHandler: (name: string) => JobHandler<unknown, Env, Db, Logger> | undefined | Promise<JobHandler<unknown, Env, Db, Logger> | undefined>;
+    /**
+     * Returns the definition for routing/validation. For lazy entries this is
+     * static routing metadata typed as a full definition (its `handle`/`input` are
+     * absent at runtime); dispatch prefers `loadJobDefinition` for the real module.
+     */
     getJobDefinition?: (name: string) => JobDefinition<string, unknown, string, Env, Db, Logger> | undefined;
+    /**
+     * Loads the full definition (handler, `input`, `middleware`, `failed`) for a
+     * lazy entry. Preferred at dispatch so payload validation + failure hooks see
+     * the real module. Falls back to `getJobDefinition`/`getHandler` when absent.
+     */
+    loadJobDefinition?: (name: string) => Promise<JobDefinition<string, unknown, string, Env, Db, Logger> | undefined>;
 }
 export interface DispatchContextInput<Job extends DispatchableJob> {
     job: Job;

package/dist/runtime/server/dispatch.js

@@ -5,8 +5,8 @@ export async function dispatchRegisteredJob(opts) {
   if (typeof taskName !== "string" || taskName.length === 0) {
     return { success: false, error: "No _task in payload", handlerNotFound: true };
   }
-  const definition = opts.registry.getJobDefinition?.(taskName);
-  const handler = definition?.handle ?? opts.registry.getHandler(taskName);
+  const definition = opts.registry.loadJobDefinition ? await opts.registry.loadJobDefinition(taskName) : opts.registry.getJobDefinition?.(taskName);
+  const handler = definition?.handle ?? await opts.registry.getHandler(taskName);
   if (!handler) {
     return { success: false, error: `No handler for task: ${taskName}`, handlerNotFound: true };
   }

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

@@ -75,7 +75,8 @@ export interface DurableJobFailureRepository {
     recordFailure: (input: RecordDurableJobFailureInput) => Promise<void>;
 }
 export interface DurableJobRegistryLike<Env = unknown, Db = unknown, Logger = unknown> {
-    getHandler?: (name: string) => JobHandler<unknown, Env, Db, Logger> | undefined;
+    /** May resolve asynchronously for lazily-loaded jobs. Unused on the producer path. */
+    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;
     getJobRoute?: (name: string) => DurableJobRoute<string> | undefined;
 }

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

@@ -1,6 +1,33 @@
 import type { JobBackoff, JobDefinition, JobFailedHandler, JobHandler, JobMiddleware, JobPayloadSchema } from './types.js';
 export type JobPayloadMap = Record<string, unknown>;
 export type AnyJobDefinition = JobDefinition<string, any, string, any, any, any>;
+/**
+ * A build-time registry entry that defers loading the handler module. The
+ * static routing fields are AST-extracted from the job's `defineJob({...})`
+ * call so the producer/consumer can route, validate queues and resolve attempts
+ * WITHOUT importing (and evaluating) the handler — `load()` pulls the full
+ * definition only when a handler/`input`/`failed` is actually needed (dispatch,
+ * or a producer of a job that declares `input`/`unique`). This is what keeps a
+ * worker from evaluating all job modules to run one job.
+ */
+export interface LazyJobEntry<Name extends string = string, Queue extends string = string> {
+    name: Name;
+    queue?: Queue;
+    jobType?: string;
+    maxAttempts?: number;
+    tries?: number;
+    unique?: boolean;
+    /** Whether the source `defineJob` declares an `input` schema (AST flag). */
+    hasInput?: boolean;
+    /** Whether the source `defineJob` declares a `uniqueId` fn (AST flag). */
+    hasUniqueId?: boolean;
+    load: () => Promise<AnyJobDefinition>;
+}
+/** Either an eagerly-constructed definition or a lazily-loaded entry. */
+export type RegistryEntry = AnyJobDefinition | LazyJobEntry;
+export declare function isLazyJobEntry(entry: RegistryEntry): entry is LazyJobEntry;
+/** Static routing metadata shared by eager defs and lazy entries. */
+export type JobStaticDefinition = Pick<AnyJobDefinition, 'name' | 'queue' | 'jobType' | 'maxAttempts' | 'tries' | 'unique'>;
 export type JobPayloadOf<Job extends AnyJobDefinition> = Job extends JobDefinition<string, infer Payload, string, any, any, any> ? Payload extends object ? Payload : never : never;
 export type JobMessageOf<Job extends AnyJobDefinition> = Job extends JobDefinition<infer Name, any, string, any, any, any> ? {
     _task: Name;
@@ -49,8 +76,8 @@ export declare function validateJobDefinitions(jobs: readonly unknown[]): JobDef
 export declare function assertJobDefinitions(jobs: readonly unknown[]): void;
 export declare function defineJobRegistry<const Jobs extends readonly AnyJobDefinition[]>(jobs: Jobs): {
     jobs: Jobs;
-    handlers: Map<string, JobHandler<unknown, unknown, unknown, unknown>>;
-    getHandler(name: string): JobHandler<unknown, unknown, unknown, unknown> | undefined;
+    getHandler: (name: string) => JobHandler<unknown, unknown, unknown, unknown> | Promise<JobHandler<unknown, unknown, unknown, unknown> | undefined> | undefined;
+    loadJobDefinition: (name: string) => Promise<AnyJobDefinition | undefined>;
     getJobDefinition: {
         <Name extends JobNameOf<Jobs>>(name: Name): JobDefinitionByName<Jobs, Name> | undefined;
         (name: string): AnyJobDefinition | undefined;

package/dist/runtime/server/registry.js

@@ -1,4 +1,17 @@
 import { buildJobPayload } from "./payload.js";
+export function isLazyJobEntry(entry) {
+  return typeof entry.load === "function" && typeof entry.handle !== "function";
+}
+function toStaticDefinition(entry) {
+  return {
+    name: entry.name,
+    queue: entry.queue,
+    jobType: entry.jobType,
+    maxAttempts: entry.maxAttempts,
+    tries: entry.tries,
+    unique: entry.unique
+  };
+}
 export function defineJob(opts) {
   return opts;
 }
@@ -23,7 +36,7 @@ export function validateJobDefinitions(jobs) {
     }
     const definition = job;
     const name = typeof definition.name === "string" && definition.name.length > 0 ? definition.name : "<unknown>";
-    if (typeof definition.name !== "string" || definition.name.length === 0 || typeof definition.handle !== "function") {
+    if (typeof definition.name !== "string" || definition.name.length === 0 || typeof definition.handle !== "function" && typeof definition.load !== "function") {
       issues.push({ name, reason: "invalid-definition" });
     }
     if (typeof definition.queue !== "string" || definition.queue.length === 0)
@@ -43,35 +56,58 @@ export function assertJobDefinitions(jobs) {
 }
 export function defineJobRegistry(jobs) {
   assertJobDefinitions(jobs);
-  const handlers = new Map(
-    jobs.map((job) => [job.name, job.handle])
-  );
+  const entries = jobs;
+  const byName = new Map(entries.map((job) => [job.name, job]));
+  const loaded = /* @__PURE__ */ new Map();
+  function loadJobDefinition(name) {
+    const entry = byName.get(name);
+    if (!entry)
+      return Promise.resolve(void 0);
+    if (!isLazyJobEntry(entry))
+      return Promise.resolve(entry);
+    let pending = loaded.get(name);
+    if (!pending) {
+      pending = entry.load();
+      loaded.set(name, pending);
+    }
+    return pending;
+  }
   function getJobDefinition(name) {
-    return jobs.find((job) => job.name === name);
+    const entry = byName.get(name);
+    if (!entry)
+      return void 0;
+    return isLazyJobEntry(entry) ? toStaticDefinition(entry) : entry;
   }
   function getJobQueue(name) {
-    return jobs.find((job) => job.name === name)?.queue;
+    return byName.get(name)?.queue;
+  }
+  function getHandler(name) {
+    const entry = byName.get(name);
+    if (!entry)
+      return void 0;
+    if (!isLazyJobEntry(entry))
+      return entry.handle;
+    return loadJobDefinition(name).then((def) => def?.handle);
   }
   return {
     jobs,
-    handlers,
-    getHandler(name) {
-      return handlers.get(name);
-    },
+    getHandler,
+    loadJobDefinition,
     getJobDefinition,
     getJobQueue,
     buildPayload(name, payload) {
-      const definition = jobs.find((job) => job.name === name);
-      if (!definition)
+      const entry = byName.get(name);
+      if (!entry)
         throw new Error(`Unknown task: ${name}`);
+      const definition = isLazyJobEntry(entry) ? toStaticDefinition(entry) : entry;
       return buildJobMessage(definition, payload);
     },
     getJobRoute(name) {
-      const job = jobs.find((job2) => job2.name === name);
-      return job ? { queue: job.queue, jobType: job.jobType ?? job.name } : void 0;
+      const entry = byName.get(name);
+      return entry ? { queue: entry.queue, jobType: entry.jobType ?? entry.name } : void 0;
     },
     validate(expectedTasks) {
-      const registered = new Set(handlers.keys());
+      const registered = new Set(byName.keys());
       const expected = new Set(expectedTasks);
       return {
         missing: expectedTasks.filter((task) => !registered.has(task)),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-cf-jobs",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Nuxt module for typed Cloudflare queue jobs.",
   "author": {
     "name": "Harlan Wilton",
@@ -61,8 +61,9 @@
   "dependencies": {
     "@nuxt/kit": "^4.4.6",
     "@nuxt/schema": "^4.4.6",
-    "citty": "^0.1.6",
-    "drizzle-orm": "1.0.0-rc.3"
+    "citty": "^0.2.2",
+    "drizzle-orm": "1.0.0-rc.3",
+    "magicast": "^0.5.3"
   },
   "devDependencies": {
     "@antfu/eslint-config": "latest",