@monque/tsed 0.1.0

package/src/decorators/worker.ts

@@ -0,0 +1,66 @@
+/**
+ * @Worker method decorator
+ *
+ * Registers a method as a job handler. The method will be called when a job
+ * with the matching name is picked up for processing.
+ *
+ * @param name - Job name (combined with controller namespace if present).
+ * @param options - Worker configuration options.
+ *
+ * @example
+ * ```typescript
+ * @WorkerController("notifications")
+ * export class NotificationWorkers {
+ *   @Worker("push", { concurrency: 10 })
+ *   async sendPush(job: Job<PushPayload>) {
+ *     await pushService.send(job.data);
+ *   }
+ * }
+ * ```
+ */
+import { Store } from '@tsed/core';
+
+import { MONQUE } from '@/constants';
+
+import type { WorkerDecoratorOptions, WorkerMetadata, WorkerStore } from './types.js';
+
+/**
+ * Method decorator that registers a method as a job handler.
+ *
+ * @param name - The job name (will be prefixed with controller namespace if present)
+ * @param options - Optional worker configuration (concurrency, replace, etc.)
+ */
+export function Worker(name: string, options?: WorkerDecoratorOptions): MethodDecorator {
+	return <T>(
+		target: object,
+		propertyKey: string | symbol,
+		_descriptor: TypedPropertyDescriptor<T>,
+	): void => {
+		const methodName = String(propertyKey);
+
+		const workerMetadata: WorkerMetadata = {
+			name,
+			method: methodName,
+			opts: options || {},
+		};
+
+		// Get the class constructor (target is the prototype for instance methods)
+		const targetConstructor = target.constructor;
+		const store = Store.from(targetConstructor);
+
+		// Get or initialize the MONQUE store
+		const existing = store.get<Partial<WorkerStore>>(MONQUE) || {
+			type: 'controller',
+			workers: [],
+			cronJobs: [],
+		};
+
+		// Add this worker to the list
+		const workers = [...(existing.workers || []), workerMetadata];
+
+		store.set(MONQUE, {
+			...existing,
+			workers,
+		});
+	};
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { type MonqueTsedConfig, validateDatabaseConfig } from './config';
+export { MONQUE, type ProviderType, ProviderTypes } from './constants';
+export type {
+	CronDecoratorOptions,
+	CronMetadata,
+	WorkerDecoratorOptions,
+	WorkerMetadata,
+	WorkerStore,
+} from './decorators';
+export { Cron, Worker, WorkerController } from './decorators';
+export { MonqueModule } from './monque-module.js';
+export { MonqueService } from './services';
+export {
+	buildJobName,
+	type CollectedWorkerMetadata,
+	collectWorkerMetadata,
+	getWorkerToken,
+	type InjectorFn,
+	resolveDatabase,
+} from './utils';

package/src/monque-module.ts

@@ -0,0 +1,199 @@
+/**
+ * MonqueModule - Main Integration Module
+ *
+ * Orchestrates the integration between Monque and Ts.ED.
+ * Handles lifecycle hooks, configuration resolution, and worker registration.
+ */
+
+import {
+	type Job,
+	Monque,
+	type MonqueOptions,
+	type ScheduleOptions,
+	type WorkerOptions,
+} from '@monque/core';
+import {
+	Configuration,
+	DIContext,
+	Inject,
+	InjectorService,
+	LOGGER,
+	Module,
+	type OnDestroy,
+	type OnInit,
+	ProviderScope,
+	runInContext,
+	type TokenProvider,
+} from '@tsed/di';
+
+import { type MonqueTsedConfig, validateDatabaseConfig } from '@/config';
+import { ProviderTypes } from '@/constants';
+import { MonqueService } from '@/services';
+import { collectWorkerMetadata, resolveDatabase } from '@/utils';
+
+@Module({
+	imports: [MonqueService],
+})
+export class MonqueModule implements OnInit, OnDestroy {
+	protected injector: InjectorService;
+	protected monqueService: MonqueService;
+	protected logger: LOGGER;
+	protected monqueConfig: MonqueTsedConfig;
+
+	protected monque: Monque | null = null;
+
+	constructor(
+		@Inject(InjectorService) injector: InjectorService,
+		@Inject(MonqueService) monqueService: MonqueService,
+		@Inject(LOGGER) logger: LOGGER,
+		@Inject(Configuration) configuration: Configuration,
+	) {
+		this.injector = injector;
+		this.monqueService = monqueService;
+		this.logger = logger;
+		this.monqueConfig = configuration.get<MonqueTsedConfig>('monque') || {};
+	}
+
+	async $onInit(): Promise<void> {
+		const config = this.monqueConfig;
+
+		if (config?.enabled === false) {
+			this.logger.info('Monque integration is disabled');
+
+			return;
+		}
+
+		validateDatabaseConfig(config);
+
+		try {
+			const db = await resolveDatabase(config, (token) =>
+				this.injector.get(token as TokenProvider),
+			);
+
+			// We construct the options object carefully to match MonqueOptions
+			const { db: _db, ...restConfig } = config;
+			const options: MonqueOptions = restConfig;
+
+			this.monque = new Monque(db, options);
+			this.monqueService._setMonque(this.monque);
+
+			this.logger.info('Monque: Connecting to MongoDB...');
+			await this.monque.initialize();
+
+			await this.registerWorkers();
+
+			await this.monque.start();
+
+			this.logger.info('Monque: Started successfully');
+		} catch (error) {
+			this.logger.error({
+				event: 'MONQUE_INIT_ERROR',
+				message: 'Failed to initialize Monque',
+				error,
+			});
+
+			throw error;
+		}
+	}
+
+	async $onDestroy(): Promise<void> {
+		if (this.monque) {
+			this.logger.info('Monque: Stopping...');
+
+			await this.monque.stop();
+
+			this.logger.info('Monque: Stopped');
+		}
+	}
+
+	/**
+	 * Discover and register all workers from @WorkerController providers
+	 */
+	protected async registerWorkers(): Promise<void> {
+		if (!this.monque) {
+			throw new Error('Monque instance not initialized');
+		}
+
+		const monque = this.monque;
+		const workerControllers = this.injector.getProviders(ProviderTypes.WORKER_CONTROLLER);
+		const registeredJobs = new Set<string>();
+
+		this.logger.info(`Monque: Found ${workerControllers.length} worker controllers`);
+
+		for (const provider of workerControllers) {
+			const useClass = provider.useClass;
+			const workers = collectWorkerMetadata(useClass);
+			// Try to resolve singleton instance immediately
+			const instance = this.injector.get(provider.token);
+
+			if (!instance && provider.scope !== ProviderScope.REQUEST) {
+				this.logger.warn(
+					`Monque: Could not resolve instance for controller ${provider.name}. Skipping.`,
+				);
+
+				continue;
+			}
+
+			for (const worker of workers) {
+				const { fullName, method, opts, isCron, cronPattern } = worker;
+
+				if (registeredJobs.has(fullName)) {
+					throw new Error(
+						`Monque: Duplicate job registration detected. Job "${fullName}" is already registered.`,
+					);
+				}
+
+				registeredJobs.add(fullName);
+
+				const handler = async (job: Job) => {
+					const $ctx = new DIContext({
+						injector: this.injector,
+						id: job._id?.toString() || 'unknown',
+					});
+					$ctx.set('MONQUE_JOB', job);
+					$ctx.container.set(DIContext, $ctx);
+
+					await runInContext($ctx, async () => {
+						try {
+							let targetInstance = instance;
+							if (provider.scope === ProviderScope.REQUEST || !targetInstance) {
+								targetInstance = await this.injector.invoke(provider.token, {
+									locals: $ctx.container,
+								});
+							}
+
+							const typedInstance = targetInstance as Record<string, (job: Job) => unknown>;
+
+							if (typedInstance && typeof typedInstance[method] === 'function') {
+								await typedInstance[method](job);
+							}
+						} catch (error) {
+							this.logger.error({
+								event: 'MONQUE_JOB_ERROR',
+								jobName: fullName,
+								jobId: job._id,
+								message: `Error processing job ${fullName}`,
+								error,
+							});
+							throw error;
+						} finally {
+							await $ctx.destroy();
+						}
+					});
+				};
+
+				if (isCron && cronPattern) {
+					this.logger.debug(`Monque: Registering cron job "${fullName}" (${cronPattern})`);
+
+					monque.register(fullName, handler, opts as WorkerOptions);
+					await monque.schedule(cronPattern, fullName, {}, opts as ScheduleOptions);
+				} else {
+					this.logger.debug(`Monque: Registering worker "${fullName}"`);
+					monque.register(fullName, handler, opts as WorkerOptions);
+				}
+			}
+		}
+
+		this.logger.info(`Monque: Registered ${registeredJobs.size} jobs`);
+	}
+}

package/src/services/index.ts

@@ -0,0 +1 @@
+export { MonqueService } from './monque-service.js';

package/src/services/monque-service.ts

@@ -0,0 +1,267 @@
+/**
+ * MonqueService - Injectable wrapper for Monque
+ *
+ * Provides a DI-friendly interface to the Monque job queue.
+ * All methods delegate to the underlying Monque instance.
+ *
+ * @example
+ * ```typescript
+ * @Service()
+ * export class OrderService {
+ *   @Inject()
+ *   private monque: MonqueService;
+ *
+ *   async createOrder(data: CreateOrderDto) {
+ *     const order = await this.save(data);
+ *     await this.monque.enqueue("order.process", { orderId: order.id });
+ *     return order;
+ *   }
+ * }
+ * ```
+ */
+
+import type {
+	BulkOperationResult,
+	CursorOptions,
+	CursorPage,
+	EnqueueOptions,
+	GetJobsFilter,
+	JobSelector,
+	Monque,
+	PersistedJob,
+	QueueStats,
+	ScheduleOptions,
+} from '@monque/core';
+import { MonqueError } from '@monque/core';
+import { Injectable } from '@tsed/di';
+import { ObjectId } from 'mongodb';
+
+/**
+ * Injectable service that wraps the Monque instance.
+ *
+ * Exposes the full Monque public API through dependency injection.
+ */
+@Injectable()
+export class MonqueService {
+	/**
+	 * Internal Monque instance (set by MonqueModule)
+	 * @internal
+	 */
+	private _monque: Monque | null = null;
+
+	/**
+	 * Set the internal Monque instance.
+	 * Called by MonqueModule during initialization.
+	 * @internal
+	 */
+	_setMonque(monque: Monque): void {
+		this._monque = monque;
+	}
+
+	/**
+	 * Access the underlying Monque instance.
+	 * @throws Error if MonqueModule is not initialized
+	 */
+	get monque(): Monque {
+		if (!this._monque) {
+			throw new MonqueError(
+				'MonqueService is not initialized. Ensure MonqueModule is imported and enabled.',
+			);
+		}
+
+		return this._monque;
+	}
+
+	// ─────────────────────────────────────────────────────────────────────────────
+	// Job Scheduling
+	// ─────────────────────────────────────────────────────────────────────────────
+
+	/**
+	 * Enqueue a job for processing.
+	 *
+	 * @param name - Job type identifier (use full namespaced name, e.g., "email.send")
+	 * @param data - Job payload
+	 * @param options - Scheduling and deduplication options
+	 * @returns The created or existing job document
+	 */
+	async enqueue<T>(name: string, data: T, options?: EnqueueOptions): Promise<PersistedJob<T>> {
+		return this.monque.enqueue(name, data, options);
+	}
+
+	/**
+	 * Enqueue a job for immediate processing.
+	 *
+	 * @param name - Job type identifier
+	 * @param data - Job payload
+	 * @returns The created job document
+	 */
+	async now<T>(name: string, data: T): Promise<PersistedJob<T>> {
+		return this.monque.now(name, data);
+	}
+
+	/**
+	 * Schedule a recurring job with a cron expression.
+	 *
+	 * @param cron - Cron expression (5-field standard or predefined like @daily)
+	 * @param name - Job type identifier
+	 * @param data - Job payload
+	 * @param options - Scheduling options
+	 * @returns The created job document
+	 */
+	async schedule<T>(
+		cron: string,
+		name: string,
+		data: T,
+		options?: ScheduleOptions,
+	): Promise<PersistedJob<T>> {
+		return this.monque.schedule(cron, name, data, options);
+	}
+
+	// ─────────────────────────────────────────────────────────────────────────────
+	// Job Management (Single Job Operations)
+	// ─────────────────────────────────────────────────────────────────────────────
+
+	/**
+	 * Cancel a pending or scheduled job.
+	 *
+	 * @param jobId - The ID of the job to cancel
+	 * @returns The cancelled job, or null if not found
+	 */
+	async cancelJob(jobId: string): Promise<PersistedJob<unknown> | null> {
+		return this.monque.cancelJob(jobId);
+	}
+
+	/**
+	 * Retry a failed or cancelled job.
+	 *
+	 * @param jobId - The ID of the job to retry
+	 * @returns The updated job, or null if not found
+	 */
+	async retryJob(jobId: string): Promise<PersistedJob<unknown> | null> {
+		return this.monque.retryJob(jobId);
+	}
+
+	/**
+	 * Reschedule a pending job to run at a different time.
+	 *
+	 * @param jobId - The ID of the job to reschedule
+	 * @param runAt - The new Date when the job should run
+	 * @returns The updated job, or null if not found
+	 */
+	async rescheduleJob(jobId: string, runAt: Date): Promise<PersistedJob<unknown> | null> {
+		return this.monque.rescheduleJob(jobId, runAt);
+	}
+
+	/**
+	 * Permanently delete a job.
+	 *
+	 * @param jobId - The ID of the job to delete
+	 * @returns true if deleted, false if job not found
+	 */
+	async deleteJob(jobId: string): Promise<boolean> {
+		return this.monque.deleteJob(jobId);
+	}
+
+	// ─────────────────────────────────────────────────────────────────────────────
+	// Job Management (Bulk Operations)
+	// ─────────────────────────────────────────────────────────────────────────────
+
+	/**
+	 * Cancel multiple jobs matching the given filter.
+	 *
+	 * @param filter - Selector for which jobs to cancel
+	 * @returns Result with count of cancelled jobs
+	 */
+	async cancelJobs(filter: JobSelector): Promise<BulkOperationResult> {
+		return this.monque.cancelJobs(filter);
+	}
+
+	/**
+	 * Retry multiple jobs matching the given filter.
+	 *
+	 * @param filter - Selector for which jobs to retry
+	 * @returns Result with count of retried jobs
+	 */
+	async retryJobs(filter: JobSelector): Promise<BulkOperationResult> {
+		return this.monque.retryJobs(filter);
+	}
+
+	/**
+	 * Delete multiple jobs matching the given filter.
+	 *
+	 * @param filter - Selector for which jobs to delete
+	 * @returns Result with count of deleted jobs
+	 */
+	async deleteJobs(filter: JobSelector): Promise<BulkOperationResult> {
+		return this.monque.deleteJobs(filter);
+	}
+
+	// ─────────────────────────────────────────────────────────────────────────────
+	// Job Queries
+	// ─────────────────────────────────────────────────────────────────────────────
+
+	/**
+	 * Get a job by its ID.
+	 *
+	 * @param jobId - The job's ObjectId (as string or ObjectId)
+	 * @returns The job document, or null if not found
+	 * @throws MonqueError if jobId is an invalid hex string
+	 */
+	async getJob<T>(jobId: string | ObjectId): Promise<PersistedJob<T> | null> {
+		let id: ObjectId;
+
+		if (typeof jobId === 'string') {
+			if (!ObjectId.isValid(jobId)) {
+				throw new MonqueError(`Invalid job ID format: ${jobId}`);
+			}
+			id = ObjectId.createFromHexString(jobId);
+		} else {
+			id = jobId;
+		}
+
+		return this.monque.getJob(id);
+	}
+
+	/**
+	 * Query jobs from the queue with optional filters.
+	 *
+	 * @param filter - Optional filter criteria (name, status, limit, skip)
+	 * @returns Array of matching jobs
+	 */
+	async getJobs<T>(filter?: GetJobsFilter): Promise<PersistedJob<T>[]> {
+		return this.monque.getJobs(filter);
+	}
+
+	/**
+	 * Get a paginated list of jobs using opaque cursors.
+	 *
+	 * @param options - Pagination options (cursor, limit, direction, filter)
+	 * @returns Page of jobs with next/prev cursors
+	 */
+	async getJobsWithCursor<T>(options?: CursorOptions): Promise<CursorPage<T>> {
+		return this.monque.getJobsWithCursor(options);
+	}
+
+	/**
+	 * Get aggregate statistics for the job queue.
+	 *
+	 * @param filter - Optional filter to scope statistics by job name
+	 * @returns Queue statistics
+	 */
+	async getQueueStats(filter?: Pick<JobSelector, 'name'>): Promise<QueueStats> {
+		return this.monque.getQueueStats(filter);
+	}
+
+	// ─────────────────────────────────────────────────────────────────────────────
+	// Health Check
+	// ─────────────────────────────────────────────────────────────────────────────
+
+	/**
+	 * Check if the scheduler is healthy and running.
+	 *
+	 * @returns true if running and connected
+	 */
+	isHealthy(): boolean {
+		return this.monque.isHealthy();
+	}
+}

package/src/utils/build-job-name.ts

@@ -0,0 +1,17 @@
+/**
+ * Build the full job name by combining namespace and name.
+ *
+ * @param namespace - Optional namespace from @WorkerController
+ * @param name - Job name from @Worker or @Cron
+ * @returns Full job name (e.g., "email.send" or just "send")
+ *
+ * @example
+ * ```typescript
+ * buildJobName("email", "send"); // "email.send"
+ * buildJobName(undefined, "send"); // "send"
+ * buildJobName("", "send"); // "send"
+ * ```
+ */
+export function buildJobName(namespace: string | undefined, name: string): string {
+	return namespace ? `${namespace}.${name}` : name;
+}

package/src/utils/collect-worker-metadata.ts

@@ -0,0 +1,95 @@
+/**
+ * Collect worker metadata utility
+ *
+ * Collects all worker metadata from a class decorated with @WorkerController.
+ * Used by MonqueModule to discover and register all workers.
+ */
+import { Store } from '@tsed/core';
+
+import { MONQUE } from '@/constants';
+import type { CronDecoratorOptions, WorkerDecoratorOptions, WorkerStore } from '@/decorators';
+
+import { buildJobName } from './build-job-name.js';
+
+/**
+ * Collected worker registration info ready for Monque.register()
+ */
+export interface CollectedWorkerMetadata {
+	/**
+	 * Full job name (with namespace prefix if applicable)
+	 */
+	fullName: string;
+
+	/**
+	 * Method name on the controller class
+	 */
+	method: string;
+
+	/**
+	 * Worker options to pass to Monque.register()
+	 */
+	opts: WorkerDecoratorOptions | CronDecoratorOptions;
+
+	/**
+	 * Whether this is a cron job
+	 */
+	isCron: boolean;
+
+	/**
+	 * Cron pattern (only for cron jobs)
+	 */
+	cronPattern?: string;
+}
+
+/**
+ * Collect all worker metadata from a class.
+ *
+ * @param target - The class constructor (decorated with @WorkerController)
+ * @returns Array of collected worker metadata ready for registration
+ *
+ * @example
+ * ```typescript
+ * const metadata = collectWorkerMetadata(EmailWorkers);
+ * // Returns:
+ * // [
+ * //   { fullName: "email.send", method: "sendEmail", opts: {}, isCron: false },
+ * //   { fullName: "email.daily-digest", method: "sendDailyDigest", opts: {}, isCron: true, cronPattern: "0 9 * * *" }
+ * // ]
+ * ```
+ */
+export function collectWorkerMetadata(
+	target: new (...args: unknown[]) => unknown,
+): CollectedWorkerMetadata[] {
+	const store = Store.from(target);
+	const workerStore = store.get<WorkerStore>(MONQUE);
+
+	if (!workerStore) {
+		return [];
+	}
+
+	const results: CollectedWorkerMetadata[] = [];
+	const namespace = workerStore.namespace;
+
+	// Collect regular workers
+	for (const worker of workerStore.workers) {
+		results.push({
+			fullName: buildJobName(namespace, worker.name),
+			method: worker.method,
+			opts: worker.opts,
+			isCron: false,
+		});
+	}
+
+	// Collect cron jobs
+	for (const cron of workerStore.cronJobs) {
+		results.push({
+			fullName: buildJobName(namespace, cron.name),
+			method: cron.method,
+			opts: cron.opts,
+			isCron: true,
+			cronPattern: cron.pattern,
+		});
+	}
+
+	return results;
+}

package/src/utils/get-worker-token.ts

@@ -0,0 +1,27 @@
+/**
+ * Generate a unique token for a worker controller.
+ *
+ * Used internally by Ts.ED DI to identify worker controller providers.
+ * The token is based on the class name for debugging purposes.
+ *
+ * @param target - The class constructor
+ * @returns A Symbol token unique to this worker controller
+ *
+ * @example
+ * ```typescript
+ * @WorkerController("email")
+ * class EmailWorkers {}
+ *
+ * const token = getWorkerToken(EmailWorkers);
+ * // Symbol("monque:worker:EmailWorkers")
+ * ```
+ */
+export function getWorkerToken(target: new (...args: unknown[]) => unknown): symbol {
+	const name = target.name?.trim();
+
+	if (!name) {
+		throw new Error('Worker class must have a non-empty name');
+	}
+
+	return Symbol.for(`monque:worker:${name}`);
+}