@quave/agenda 1.0.0

package/dist/decorators/Define.d.ts

@@ -0,0 +1,33 @@
+import { type DefineOptions } from './metadata.js';
+export type { DefineOptions };
+/**
+ * Method decorator that defines a job handler.
+ *
+ * Jobs decorated with @Define must be scheduled programmatically using
+ * `agenda.now()`, `agenda.schedule()`, or `agenda.every()`.
+ *
+ * @param options - Configuration options for the job definition
+ * @returns Method decorator
+ *
+ * @example
+ * ```typescript
+ * import { JobsController, Define, Job } from 'agenda';
+ *
+ * @JobsController()
+ * class EmailJobs {
+ *   @Define({
+ *     name: 'sendWelcome',
+ *     concurrency: 5,
+ *     priority: 'high'
+ *   })
+ *   async sendWelcomeEmail(job: Job<{ userId: string; template: string }>) {
+ *     const { userId, template } = job.attrs.data;
+ *     await this.emailService.send(userId, template);
+ *   }
+ * }
+ *
+ * // Later, schedule the job:
+ * await agenda.now('sendWelcome', { userId: '123', template: 'welcome' });
+ * ```
+ */
+export declare function Define(options?: DefineOptions): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/decorators/Define.js

@@ -0,0 +1,44 @@
+import { getOrCreateControllerMetadata } from './metadata.js';
+/**
+ * Method decorator that defines a job handler.
+ *
+ * Jobs decorated with @Define must be scheduled programmatically using
+ * `agenda.now()`, `agenda.schedule()`, or `agenda.every()`.
+ *
+ * @param options - Configuration options for the job definition
+ * @returns Method decorator
+ *
+ * @example
+ * ```typescript
+ * import { JobsController, Define, Job } from 'agenda';
+ *
+ * @JobsController()
+ * class EmailJobs {
+ *   @Define({
+ *     name: 'sendWelcome',
+ *     concurrency: 5,
+ *     priority: 'high'
+ *   })
+ *   async sendWelcomeEmail(job: Job<{ userId: string; template: string }>) {
+ *     const { userId, template } = job.attrs.data;
+ *     await this.emailService.send(userId, template);
+ *   }
+ * }
+ *
+ * // Later, schedule the job:
+ * await agenda.now('sendWelcome', { userId: '123', template: 'welcome' });
+ * ```
+ */
+export function Define(options = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Standard decorator signature requires any for target
+    return function (target, propertyKey, descriptor) {
+        const metadata = getOrCreateControllerMetadata(target.constructor);
+        metadata.jobs.set(propertyKey, {
+            type: 'define',
+            methodName: propertyKey,
+            options
+        });
+        return descriptor;
+    };
+}
+//# sourceMappingURL=Define.js.map

package/dist/decorators/Define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Define.js","sourceRoot":"","sources":["../../src/decorators/Define.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAsB,MAAM,eAAe,CAAC;AAIlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,MAAM,CAAC,UAAyB,EAAE;IACjD,sHAAsH;IACtH,OAAO,UAAU,MAAW,EAAE,WAAmB,EAAE,UAA8B;QAChF,MAAM,QAAQ,GAAG,6BAA6B,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAEnE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE;YAC9B,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,WAAW;YACvB,OAAO;SACP,CAAC,CAAC;QAEH,OAAO,UAAU,CAAC;IACnB,CAAC,CAAC;AACH,CAAC"}

package/dist/decorators/Every.d.ts

@@ -0,0 +1,43 @@
+import { type EveryOptions } from './metadata.js';
+export type { EveryOptions };
+/**
+ * Method decorator that defines a recurring job.
+ *
+ * Jobs decorated with @Every are automatically scheduled when registered
+ * with the Agenda instance. They will run at the specified interval.
+ *
+ * @param interval - The interval at which the job should run.
+ *                   Can be a cron expression, human-readable string, or milliseconds.
+ * @param options - Configuration options for the job
+ * @returns Method decorator
+ *
+ * @example
+ * ```typescript
+ * import { JobsController, Every, Job } from 'agenda';
+ *
+ * @JobsController({ namespace: 'maintenance' })
+ * class MaintenanceJobs {
+ *   // Run every 5 minutes
+ *   @Every('5 minutes')
+ *   async healthCheck(job: Job) {
+ *     await this.checkSystemHealth();
+ *   }
+ *
+ *   // Run daily at midnight using cron
+ *   @Every('0 0 * * *', {
+ *     name: 'dailyCleanup',
+ *     timezone: 'America/New_York'
+ *   })
+ *   async cleanupOldData(job: Job) {
+ *     await this.deleteOldRecords();
+ *   }
+ *
+ *   // Run every hour with high priority
+ *   @Every('1 hour', { priority: 'high', concurrency: 1 })
+ *   async generateReport(job: Job) {
+ *     await this.createHourlyReport();
+ *   }
+ * }
+ * ```
+ */
+export declare function Every(interval: string | number, options?: EveryOptions): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/decorators/Every.js

@@ -0,0 +1,55 @@
+import { getOrCreateControllerMetadata } from './metadata.js';
+/**
+ * Method decorator that defines a recurring job.
+ *
+ * Jobs decorated with @Every are automatically scheduled when registered
+ * with the Agenda instance. They will run at the specified interval.
+ *
+ * @param interval - The interval at which the job should run.
+ *                   Can be a cron expression, human-readable string, or milliseconds.
+ * @param options - Configuration options for the job
+ * @returns Method decorator
+ *
+ * @example
+ * ```typescript
+ * import { JobsController, Every, Job } from 'agenda';
+ *
+ * @JobsController({ namespace: 'maintenance' })
+ * class MaintenanceJobs {
+ *   // Run every 5 minutes
+ *   @Every('5 minutes')
+ *   async healthCheck(job: Job) {
+ *     await this.checkSystemHealth();
+ *   }
+ *
+ *   // Run daily at midnight using cron
+ *   @Every('0 0 * * *', {
+ *     name: 'dailyCleanup',
+ *     timezone: 'America/New_York'
+ *   })
+ *   async cleanupOldData(job: Job) {
+ *     await this.deleteOldRecords();
+ *   }
+ *
+ *   // Run every hour with high priority
+ *   @Every('1 hour', { priority: 'high', concurrency: 1 })
+ *   async generateReport(job: Job) {
+ *     await this.createHourlyReport();
+ *   }
+ * }
+ * ```
+ */
+export function Every(interval, options = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Standard decorator signature requires any for target
+    return function (target, propertyKey, descriptor) {
+        const metadata = getOrCreateControllerMetadata(target.constructor);
+        metadata.jobs.set(propertyKey, {
+            type: 'every',
+            methodName: propertyKey,
+            interval,
+            options
+        });
+        return descriptor;
+    };
+}
+//# sourceMappingURL=Every.js.map

package/dist/decorators/Every.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Every.js","sourceRoot":"","sources":["../../src/decorators/Every.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAqB,MAAM,eAAe,CAAC;AAIjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,KAAK,CAAC,QAAyB,EAAE,UAAwB,EAAE;IAC1E,sHAAsH;IACtH,OAAO,UAAU,MAAW,EAAE,WAAmB,EAAE,UAA8B;QAChF,MAAM,QAAQ,GAAG,6BAA6B,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAEnE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE;YAC9B,IAAI,EAAE,OAAO;YACb,UAAU,EAAE,WAAW;YACvB,QAAQ;YACR,OAAO;SACP,CAAC,CAAC;QAEH,OAAO,UAAU,CAAC;IACnB,CAAC,CAAC;AACH,CAAC"}

package/dist/decorators/JobsController.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Options for the @JobsController decorator
+ */
+export interface JobsControllerOptions {
+    /**
+     * Namespace prefix for all jobs in this class.
+     * Job names will be formatted as "namespace.jobName"
+     * @example
+     * ```typescript
+     * @JobsController({ namespace: 'email' })
+     * class EmailJobs {
+     *   @Define()
+     *   async sendWelcome(job: Job) {} // registered as "email.sendWelcome"
+     * }
+     * ```
+     */
+    namespace?: string;
+}
+/**
+ * Class decorator that marks a class as containing job handlers.
+ *
+ * @param options - Configuration options for the jobs controller
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * import { JobsController, Define, Every } from 'agenda';
+ *
+ * @JobsController({ namespace: 'notifications' })
+ * class NotificationJobs {
+ *   @Define()
+ *   async sendPush(job: Job<{ userId: string }>) {
+ *     // Handle push notification
+ *   }
+ *
+ *   @Every('5 minutes')
+ *   async checkPending(job: Job) {
+ *     // Check for pending notifications
+ *   }
+ * }
+ * ```
+ */
+export declare function JobsController(options?: JobsControllerOptions): <T extends new (...args: any[]) => any>(target: T) => T;

package/dist/decorators/JobsController.js

@@ -0,0 +1,37 @@
+import { getOrCreateControllerMetadata, setControllerMetadata } from './metadata.js';
+/**
+ * Class decorator that marks a class as containing job handlers.
+ *
+ * @param options - Configuration options for the jobs controller
+ * @returns Class decorator
+ *
+ * @example
+ * ```typescript
+ * import { JobsController, Define, Every } from 'agenda';
+ *
+ * @JobsController({ namespace: 'notifications' })
+ * class NotificationJobs {
+ *   @Define()
+ *   async sendPush(job: Job<{ userId: string }>) {
+ *     // Handle push notification
+ *   }
+ *
+ *   @Every('5 minutes')
+ *   async checkPending(job: Job) {
+ *     // Check for pending notifications
+ *   }
+ * }
+ * ```
+ */
+export function JobsController(options = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Standard class decorator signature requires any
+    return function (target) {
+        const metadata = getOrCreateControllerMetadata(target);
+        setControllerMetadata(target, {
+            ...metadata,
+            namespace: options.namespace
+        });
+        return target;
+    };
+}
+//# sourceMappingURL=JobsController.js.map

package/dist/decorators/JobsController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JobsController.js","sourceRoot":"","sources":["../../src/decorators/JobsController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAqBrF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,cAAc,CAAC,UAAiC,EAAE;IACjE,iHAAiH;IACjH,OAAO,UAAiD,MAAS;QAChE,MAAM,QAAQ,GAAG,6BAA6B,CAAC,MAAM,CAAC,CAAC;QACvD,qBAAqB,CAAC,MAAM,EAAE;YAC7B,GAAG,QAAQ;YACX,SAAS,EAAE,OAAO,CAAC,SAAS;SAC5B,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IACf,CAAC,CAAC;AACH,CAAC"}

package/dist/decorators/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Agenda Decorators
+ *
+ * TypeScript decorators for defining job handlers in a declarative way.
+ *
+ * @example
+ * ```typescript
+ * import { Agenda, JobsController, Define, Every, registerJobs, Job } from 'agenda';
+ * import { MongoBackend } from '@quave/agenda-mongodb';
+ *
+ * @JobsController({ namespace: 'email' })
+ * class EmailJobs {
+ *   @Define({ concurrency: 5 })
+ *   async sendWelcome(job: Job<{ userId: string }>) {
+ *     // Send welcome email
+ *   }
+ *
+ *   @Every('1 hour')
+ *   async cleanupBounced(job: Job) {
+ *     // Cleanup bounced emails
+ *   }
+ * }
+ *
+ * const agenda = new Agenda({
+ *   backend: new MongoBackend({ address: 'mongodb://localhost/agenda' })
+ * });
+ *
+ * registerJobs(agenda, [new EmailJobs()]);
+ * await agenda.start();
+ *
+ * // Schedule a job
+ * await agenda.now('email.sendWelcome', { userId: '123' });
+ * ```
+ *
+ * @module decorators
+ */
+export { JobsController, type JobsControllerOptions } from './JobsController.js';
+export { Define, type DefineOptions } from './Define.js';
+export { Every, type EveryOptions } from './Every.js';
+export { registerJobs, getRegisteredJobsInfo, JobsRegistrationError } from './register.js';
+export { getControllerMetadata, isJobsController, type ControllerMetadata, type JobMetadata, type ScheduleOptions } from './metadata.js';

package/dist/decorators/index.js

@@ -0,0 +1,46 @@
+/**
+ * Agenda Decorators
+ *
+ * TypeScript decorators for defining job handlers in a declarative way.
+ *
+ * @example
+ * ```typescript
+ * import { Agenda, JobsController, Define, Every, registerJobs, Job } from 'agenda';
+ * import { MongoBackend } from '@quave/agenda-mongodb';
+ *
+ * @JobsController({ namespace: 'email' })
+ * class EmailJobs {
+ *   @Define({ concurrency: 5 })
+ *   async sendWelcome(job: Job<{ userId: string }>) {
+ *     // Send welcome email
+ *   }
+ *
+ *   @Every('1 hour')
+ *   async cleanupBounced(job: Job) {
+ *     // Cleanup bounced emails
+ *   }
+ * }
+ *
+ * const agenda = new Agenda({
+ *   backend: new MongoBackend({ address: 'mongodb://localhost/agenda' })
+ * });
+ *
+ * registerJobs(agenda, [new EmailJobs()]);
+ * await agenda.start();
+ *
+ * // Schedule a job
+ * await agenda.now('email.sendWelcome', { userId: '123' });
+ * ```
+ *
+ * @module decorators
+ */
+// Class decorator
+export { JobsController } from './JobsController.js';
+// Method decorators
+export { Define } from './Define.js';
+export { Every } from './Every.js';
+// Registration utilities
+export { registerJobs, getRegisteredJobsInfo, JobsRegistrationError } from './register.js';
+// Metadata utilities (for advanced use cases)
+export { getControllerMetadata, isJobsController } from './metadata.js';
+//# sourceMappingURL=index.js.map

package/dist/decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAA8B,MAAM,qBAAqB,CAAC;AAEjF,oBAAoB;AACpB,OAAO,EAAE,MAAM,EAAsB,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAC;AAEtD,yBAAyB;AACzB,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3F,8CAA8C;AAC9C,OAAO,EACN,qBAAqB,EACrB,gBAAgB,EAIhB,MAAM,eAAe,CAAC"}

package/dist/decorators/metadata.d.ts

@@ -0,0 +1,50 @@
+import type { JobPriority } from '../utils/priority.js';
+/**
+ * Metadata storage for job decorators
+ * Uses a WeakMap to avoid memory leaks and doesn't require reflect-metadata
+ */
+export interface DefineOptions {
+    name?: string;
+    concurrency?: number;
+    lockLifetime?: number;
+    lockLimit?: number;
+    priority?: JobPriority;
+}
+export interface EveryOptions extends DefineOptions {
+    timezone?: string;
+    skipImmediate?: boolean;
+}
+export interface ScheduleOptions extends DefineOptions {
+    when?: string | Date;
+}
+export interface JobMetadata {
+    type: 'define' | 'every' | 'schedule';
+    methodName: string;
+    options: DefineOptions | EveryOptions | ScheduleOptions;
+    interval?: string | number;
+}
+export interface ControllerMetadata {
+    namespace?: string;
+    jobs: Map<string, JobMetadata>;
+}
+/**
+ * Type for class constructors used in decorator metadata
+ */
+type Constructor = abstract new (...args: any[]) => any;
+/**
+ * Get or create controller metadata for a class
+ */
+export declare function getOrCreateControllerMetadata(target: Constructor): ControllerMetadata;
+/**
+ * Get controller metadata for a class
+ */
+export declare function getControllerMetadata(target: Constructor): ControllerMetadata | undefined;
+/**
+ * Set controller metadata for a class
+ */
+export declare function setControllerMetadata(target: Constructor, metadata: ControllerMetadata): void;
+/**
+ * Check if a class is decorated with @JobsController
+ */
+export declare function isJobsController(target: Constructor): boolean;
+export {};

package/dist/decorators/metadata.js

@@ -0,0 +1,35 @@
+/**
+ * Registry for storing job controller metadata
+ * Uses WeakMap to allow garbage collection of unused classes
+ */
+const controllerRegistry = new WeakMap();
+/**
+ * Get or create controller metadata for a class
+ */
+export function getOrCreateControllerMetadata(target) {
+    let metadata = controllerRegistry.get(target);
+    if (!metadata) {
+        metadata = { jobs: new Map() };
+        controllerRegistry.set(target, metadata);
+    }
+    return metadata;
+}
+/**
+ * Get controller metadata for a class
+ */
+export function getControllerMetadata(target) {
+    return controllerRegistry.get(target);
+}
+/**
+ * Set controller metadata for a class
+ */
+export function setControllerMetadata(target, metadata) {
+    controllerRegistry.set(target, metadata);
+}
+/**
+ * Check if a class is decorated with @JobsController
+ */
+export function isJobsController(target) {
+    return controllerRegistry.has(target);
+}
+//# sourceMappingURL=metadata.js.map

package/dist/decorators/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/decorators/metadata.ts"],"names":[],"mappings":"AA0CA;;;GAGG;AACH,MAAM,kBAAkB,GAAG,IAAI,OAAO,EAAmC,CAAC;AAE1E;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAAC,MAAmB;IAChE,IAAI,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,QAAQ,GAAG,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;QAC/B,kBAAkB,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAmB;IACxD,OAAO,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAmB,EAAE,QAA4B;IACtF,kBAAkB,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAmB;IACnD,OAAO,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACvC,CAAC"}

package/dist/decorators/register.d.ts

@@ -0,0 +1,52 @@
+import type { Agenda } from '../index.js';
+import { type JobMetadata } from './metadata.js';
+/**
+ * Error thrown when attempting to register an invalid jobs controller
+ */
+export declare class JobsRegistrationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Register job handlers from decorated class instances with an Agenda instance.
+ *
+ * This function reads the metadata from classes decorated with `@JobsController`
+ * and registers their methods as job handlers.
+ *
+ * @param agenda - The Agenda instance to register jobs with
+ * @param instances - Array of instantiated job controller classes
+ * @throws {JobsRegistrationError} If a class is not decorated with @JobsController
+ *
+ * @example
+ * ```typescript
+ * import { Agenda, registerJobs } from 'agenda';
+ * import { MongoBackend } from '@quave/agenda-mongodb';
+ * import { EmailJobs } from './jobs/email';
+ * import { ReportJobs } from './jobs/reports';
+ *
+ * const agenda = new Agenda({
+ *   backend: new MongoBackend({ address: 'mongodb://localhost/agenda' })
+ * });
+ *
+ * // Create instances (can inject dependencies via constructor)
+ * const emailJobs = new EmailJobs(emailService);
+ * const reportJobs = new ReportJobs(reportService);
+ *
+ * // Register all job handlers
+ * registerJobs(agenda, [emailJobs, reportJobs]);
+ *
+ * await agenda.start();
+ * ```
+ */
+export declare function registerJobs(agenda: Agenda, instances: object[]): void;
+/**
+ * Get information about registered jobs from decorated classes.
+ * Useful for debugging and introspection.
+ *
+ * @param instances - Array of job controller instances
+ * @returns Array of job registration info
+ */
+export declare function getRegisteredJobsInfo(instances: object[]): Array<{
+    className: string;
+    namespace?: string;
+    jobs: JobMetadata[];
+}>;

package/dist/decorators/register.js

@@ -0,0 +1,139 @@
+import { getControllerMetadata, isJobsController } from './metadata.js';
+/**
+ * Error thrown when attempting to register an invalid jobs controller
+ */
+export class JobsRegistrationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'JobsRegistrationError';
+    }
+}
+/**
+ * Register job handlers from decorated class instances with an Agenda instance.
+ *
+ * This function reads the metadata from classes decorated with `@JobsController`
+ * and registers their methods as job handlers.
+ *
+ * @param agenda - The Agenda instance to register jobs with
+ * @param instances - Array of instantiated job controller classes
+ * @throws {JobsRegistrationError} If a class is not decorated with @JobsController
+ *
+ * @example
+ * ```typescript
+ * import { Agenda, registerJobs } from 'agenda';
+ * import { MongoBackend } from '@quave/agenda-mongodb';
+ * import { EmailJobs } from './jobs/email';
+ * import { ReportJobs } from './jobs/reports';
+ *
+ * const agenda = new Agenda({
+ *   backend: new MongoBackend({ address: 'mongodb://localhost/agenda' })
+ * });
+ *
+ * // Create instances (can inject dependencies via constructor)
+ * const emailJobs = new EmailJobs(emailService);
+ * const reportJobs = new ReportJobs(reportService);
+ *
+ * // Register all job handlers
+ * registerJobs(agenda, [emailJobs, reportJobs]);
+ *
+ * await agenda.start();
+ * ```
+ */
+export function registerJobs(agenda, instances) {
+    const pendingEveryJobs = [];
+    for (const instance of instances) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- instance.constructor is typed as Function
+        const constructor = instance.constructor;
+        // Validate that the class is decorated
+        if (!isJobsController(constructor)) {
+            throw new JobsRegistrationError(`Class "${constructor.name}" is not decorated with @JobsController. ` +
+                'Make sure to add @JobsController() decorator to your class.');
+        }
+        const metadata = getControllerMetadata(constructor);
+        if (!metadata) {
+            continue;
+        }
+        registerJobsFromMetadata(agenda, instance, metadata, pendingEveryJobs);
+    }
+    // Schedule @Every jobs after agenda starts
+    if (pendingEveryJobs.length > 0) {
+        scheduleEveryJobsOnReady(agenda, pendingEveryJobs);
+    }
+}
+/**
+ * Register jobs from a single controller's metadata
+ */
+function registerJobsFromMetadata(agenda, instance, metadata, pendingEveryJobs) {
+    const namespace = metadata.namespace;
+    for (const [methodName, jobMeta] of metadata.jobs) {
+        const jobName = buildJobName(namespace, jobMeta.options.name || methodName);
+        // Bind the method to the instance
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Dynamic method access requires any
+        const handler = instance[methodName].bind(instance);
+        // Create an async wrapper that matches Agenda's expected signature
+        const wrappedHandler = async (job) => {
+            await handler(job);
+        };
+        // Register the job definition with Agenda
+        agenda.define(jobName, wrappedHandler, {
+            concurrency: jobMeta.options.concurrency,
+            lockLifetime: jobMeta.options.lockLifetime,
+            lockLimit: jobMeta.options.lockLimit,
+            priority: jobMeta.options.priority
+        });
+        // Queue @Every jobs for scheduling after start
+        if (jobMeta.type === 'every' && jobMeta.interval !== undefined) {
+            pendingEveryJobs.push({
+                jobName,
+                interval: jobMeta.interval,
+                options: jobMeta.options
+            });
+        }
+    }
+}
+/**
+ * Build the full job name with optional namespace prefix
+ */
+function buildJobName(namespace, name) {
+    return namespace ? `${namespace}.${name}` : name;
+}
+/**
+ * Schedule @Every jobs when Agenda emits the 'ready' event
+ */
+function scheduleEveryJobsOnReady(agenda, pendingJobs) {
+    const scheduleJobs = async () => {
+        for (const pending of pendingJobs) {
+            await agenda.every(pending.interval, pending.jobName, undefined, {
+                timezone: pending.options.timezone,
+                skipImmediate: pending.options.skipImmediate
+            });
+        }
+    };
+    // The ready promise settles once whether the backend already connected
+    // or connects later, unlike a 'ready' listener which misses past events.
+    agenda.ready
+        .then(() => scheduleJobs())
+        .catch(err => {
+        agenda.emit('error', err);
+    });
+}
+/**
+ * Get information about registered jobs from decorated classes.
+ * Useful for debugging and introspection.
+ *
+ * @param instances - Array of job controller instances
+ * @returns Array of job registration info
+ */
+export function getRegisteredJobsInfo(instances) {
+    return instances.map(instance => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- instance.constructor is typed as Function
+        const constructor = instance.constructor;
+        const metadata = getControllerMetadata(constructor);
+        return {
+            className: constructor.name,
+            namespace: metadata?.namespace,
+            jobs: metadata ? Array.from(metadata.jobs.values()) : []
+        };
+    });
+}
+//# sourceMappingURL=register.js.map

package/dist/decorators/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/decorators/register.ts"],"names":[],"mappings":"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"}