@monque/tsed 0.1.0

package/dist/index.mjs

@@ -0,0 +1,691 @@
+import { Store, useDecorators } from "@tsed/core";
+import { Configuration, DIContext, Inject, Injectable, InjectorService, LOGGER, Module, ProviderScope, runInContext } from "@tsed/di";
+import { Monque, MonqueError } from "@monque/core";
+import { ObjectId } from "mongodb";
+
+//#region src/config/config.ts
+/**
+* Validate that exactly one database resolution strategy is provided.
+*
+* @param config - The configuration to validate.
+* @throws Error if zero or multiple strategies are provided.
+*
+* @example
+* ```typescript
+* validateDatabaseConfig({ db: mongoDb }); // OK
+* validateDatabaseConfig({}); // throws
+* validateDatabaseConfig({ db: mongoDb, dbFactory: fn }); // throws
+* ```
+*/
+function validateDatabaseConfig(config) {
+	const strategies = [
+		config.db,
+		config.dbFactory,
+		config.dbToken
+	].filter(Boolean);
+	if (strategies.length === 0) throw new Error("MonqueTsedConfig requires exactly one of 'db', 'dbFactory', or 'dbToken' to be set");
+	if (strategies.length > 1) throw new Error("MonqueTsedConfig accepts only one of 'db', 'dbFactory', or 'dbToken' - multiple were provided");
+}
+
+//#endregion
+//#region src/constants/constants.ts
+/**
+* Symbol used to store decorator metadata on class constructors.
+*
+* Used by @WorkerController, @Worker, and @Cron decorators to attach
+* metadata that is later collected by MonqueModule during initialization.
+*
+* @example
+* ```typescript
+* Store.from(Class).set(MONQUE, metadata);
+* ```
+*/
+const MONQUE = Symbol.for("monque");
+
+//#endregion
+//#region src/constants/types.ts
+/**
+* Provider type constants for DI scanning.
+*
+* These constants are used to categorize providers registered with Ts.ED's
+* dependency injection container, enabling MonqueModule to discover and
+* register workers automatically.
+*
+* Note: Using string constants with `as const` instead of enums per
+* Constitution guidelines.
+*/
+const ProviderTypes = {
+	WORKER_CONTROLLER: "monque:worker-controller",
+	CRON: "monque:cron"
+};
+
+//#endregion
+//#region src/decorators/cron.ts
+/**
+* Method decorator that registers a method as a scheduled cron job.
+*
+* @param pattern - Cron expression (e.g., "* * * * *", "@daily")
+* @param options - Optional cron configuration (name, timezone, etc.)
+*
+* @example
+* ```typescript
+* @WorkerController()
+* class ReportWorkers {
+*   @Cron("@daily", { timezone: "UTC" })
+*   async generateDailyReport() {
+*     // ...
+*   }
+* }
+* ```
+*/
+function Cron(pattern, options) {
+	return (target, propertyKey, _descriptor) => {
+		const methodName = String(propertyKey);
+		const cronMetadata = {
+			pattern,
+			name: options?.name || methodName,
+			method: methodName,
+			opts: options || {}
+		};
+		const targetConstructor = target.constructor;
+		const store = Store.from(targetConstructor);
+		const existing = store.get(MONQUE) || {
+			type: "controller",
+			workers: [],
+			cronJobs: []
+		};
+		const cronJobs = [...existing.cronJobs || [], cronMetadata];
+		store.set(MONQUE, {
+			...existing,
+			cronJobs
+		});
+	};
+}
+
+//#endregion
+//#region src/decorators/worker.ts
+/**
+* @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);
+*   }
+* }
+* ```
+*/
+/**
+* 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.)
+*/
+function Worker(name, options) {
+	return (target, propertyKey, _descriptor) => {
+		const workerMetadata = {
+			name,
+			method: String(propertyKey),
+			opts: options || {}
+		};
+		const targetConstructor = target.constructor;
+		const store = Store.from(targetConstructor);
+		const existing = store.get(MONQUE) || {
+			type: "controller",
+			workers: [],
+			cronJobs: []
+		};
+		const workers = [...existing.workers || [], workerMetadata];
+		store.set(MONQUE, {
+			...existing,
+			workers
+		});
+	};
+}
+
+//#endregion
+//#region src/decorators/worker-controller.ts
+/**
+* @WorkerController class decorator
+*
+* Marks a class as containing worker methods and registers it with the Ts.ED DI container.
+* Workers in the class will have their job names prefixed with the namespace.
+*
+* @param namespace - Optional prefix for all job names in this controller.
+*                    When set, job names become "{namespace}.{name}".
+*
+* @example
+* ```typescript
+* @WorkerController("email")
+* export class EmailWorkers {
+*   @Worker("send")  // Registered as "email.send"
+*   async send(job: Job<EmailPayload>) { }
+* }
+* ```
+*/
+/**
+* Class decorator that registers a class as a worker controller.
+*
+* @param namespace - Optional namespace prefix for job names
+*/
+function WorkerController(namespace) {
+	return useDecorators(Injectable({ type: ProviderTypes.WORKER_CONTROLLER }), (target) => {
+		const store = Store.from(target);
+		const existing = store.get(MONQUE) || {};
+		const workerStore = {
+			type: "controller",
+			...namespace !== void 0 && { namespace },
+			workers: existing.workers || [],
+			cronJobs: existing.cronJobs || []
+		};
+		store.set(MONQUE, workerStore);
+	});
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.110.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+//#endregion
+//#region src/services/monque-service.ts
+let MonqueService = class MonqueService {
+	/**
+	* Internal Monque instance (set by MonqueModule)
+	* @internal
+	*/
+	_monque = null;
+	/**
+	* Set the internal Monque instance.
+	* Called by MonqueModule during initialization.
+	* @internal
+	*/
+	_setMonque(monque) {
+		this._monque = monque;
+	}
+	/**
+	* Access the underlying Monque instance.
+	* @throws Error if MonqueModule is not initialized
+	*/
+	get monque() {
+		if (!this._monque) throw new MonqueError("MonqueService is not initialized. Ensure MonqueModule is imported and enabled.");
+		return this._monque;
+	}
+	/**
+	* 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(name, data, options) {
+		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(name, data) {
+		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(cron, name, data, options) {
+		return this.monque.schedule(cron, name, data, options);
+	}
+	/**
+	* 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) {
+		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) {
+		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, runAt) {
+		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) {
+		return this.monque.deleteJob(jobId);
+	}
+	/**
+	* 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) {
+		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) {
+		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) {
+		return this.monque.deleteJobs(filter);
+	}
+	/**
+	* 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(jobId) {
+		let id;
+		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(filter) {
+		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(options) {
+		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) {
+		return this.monque.getQueueStats(filter);
+	}
+	/**
+	* Check if the scheduler is healthy and running.
+	*
+	* @returns true if running and connected
+	*/
+	isHealthy() {
+		return this.monque.isHealthy();
+	}
+};
+MonqueService = __decorate([Injectable()], MonqueService);
+
+//#endregion
+//#region src/utils/build-job-name.ts
+/**
+* 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"
+* ```
+*/
+function buildJobName(namespace, name) {
+	return namespace ? `${namespace}.${name}` : name;
+}
+
+//#endregion
+//#region src/utils/collect-worker-metadata.ts
+/**
+* Collect worker metadata utility
+*
+* Collects all worker metadata from a class decorated with @WorkerController.
+* Used by MonqueModule to discover and register all workers.
+*/
+/**
+* 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 * * *" }
+* // ]
+* ```
+*/
+function collectWorkerMetadata(target) {
+	const workerStore = Store.from(target).get(MONQUE);
+	if (!workerStore) return [];
+	const results = [];
+	const namespace = workerStore.namespace;
+	for (const worker of workerStore.workers) results.push({
+		fullName: buildJobName(namespace, worker.name),
+		method: worker.method,
+		opts: worker.opts,
+		isCron: false
+	});
+	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;
+}
+
+//#endregion
+//#region src/utils/get-worker-token.ts
+/**
+* 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")
+* ```
+*/
+function getWorkerToken(target) {
+	const name = target.name?.trim();
+	if (!name) throw new Error("Worker class must have a non-empty name");
+	return Symbol.for(`monque:worker:${name}`);
+}
+
+//#endregion
+//#region src/utils/guards.ts
+/**
+* Type guard to check if an object acts like a Mongoose Service.
+*
+* Checks if the object has a `get` method.
+*
+* @param value The value to check
+*/
+function isMongooseService(value) {
+	return typeof value === "object" && value !== null && "get" in value && typeof value.get === "function";
+}
+/**
+* Type guard to check if an object acts like a Mongoose Connection.
+*
+* Checks if the object has a `db` property.
+*
+* @param value The value to check
+*/
+function isMongooseConnection(value) {
+	return typeof value === "object" && value !== null && "db" in value && typeof value.db === "object" && value.db !== null && typeof value.db.collection === "function";
+}
+
+//#endregion
+//#region src/utils/resolve-database.ts
+/**
+* Resolve the MongoDB database instance from the configuration.
+*
+* Supports three resolution strategies:
+* 1. **Direct `db`**: Returns the provided Db instance directly
+* 2. **Factory `dbFactory`**: Calls the factory function (supports async)
+* 3. **DI Token `dbToken`**: Resolves the Db from the DI container
+*
+* @param config - The Monque configuration containing database settings
+* @param injectorFn - Optional function to resolve DI tokens (required for dbToken strategy)
+* @returns The resolved MongoDB Db instance
+* @throws Error if no database strategy is provided or if DI resolution fails
+*
+* @example
+* ```typescript
+* // Direct Db instance
+* const db = await resolveDatabase({ db: mongoDb });
+*
+* // Factory function
+* const db = await resolveDatabase({
+*   dbFactory: async () => {
+*     const client = await MongoClient.connect(uri);
+*     return client.db("myapp");
+*   }
+* });
+*
+* // DI token
+* const db = await resolveDatabase(
+*   { dbToken: "MONGODB_DATABASE" },
+*   (token) => injector.get(token)
+* );
+* ```
+*/
+async function resolveDatabase(config, injectorFn) {
+	if (config.db) return config.db;
+	if (config.dbFactory) return config.dbFactory();
+	if (config.dbToken) {
+		if (!injectorFn) throw new Error("MonqueTsedConfig.dbToken requires an injector function to resolve the database");
+		const resolved = injectorFn(config.dbToken);
+		if (!resolved) throw new Error(`Could not resolve database from token: ${String(config.dbToken)}. Make sure the provider is registered in the DI container.`);
+		if (isMongooseService(resolved)) {
+			const connectionId = config.mongooseConnectionId || "default";
+			const connection = resolved.get(connectionId);
+			if (!connection) throw new Error(`MongooseService resolved from token "${String(config.dbToken)}" returned no connection for ID "${connectionId}". Ensure the connection ID is correct and the connection is established.`);
+			if ("db" in connection && connection.db) return connection.db;
+		}
+		if (isMongooseConnection(resolved)) return resolved.db;
+		if (typeof resolved !== "object" || resolved === null || !("collection" in resolved)) throw new Error(`Resolved value from token "${String(config.dbToken)}" does not appear to be a valid MongoDB Db instance.`);
+		return resolved;
+	}
+	throw new Error("MonqueTsedConfig requires 'db', 'dbFactory', or 'dbToken' to be set");
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.110.0/helpers/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.110.0/helpers/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+
+//#endregion
+//#region src/monque-module.ts
+/**
+* MonqueModule - Main Integration Module
+*
+* Orchestrates the integration between Monque and Ts.ED.
+* Handles lifecycle hooks, configuration resolution, and worker registration.
+*/
+var _ref, _ref2, _ref3, _ref4;
+let MonqueModule = class MonqueModule {
+	injector;
+	monqueService;
+	logger;
+	monqueConfig;
+	monque = null;
+	constructor(injector, monqueService, logger, configuration) {
+		this.injector = injector;
+		this.monqueService = monqueService;
+		this.logger = logger;
+		this.monqueConfig = configuration.get("monque") || {};
+	}
+	async $onInit() {
+		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));
+			const { db: _db, ...restConfig } = config;
+			this.monque = new Monque(db, restConfig);
+			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() {
+		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
+	*/
+	async registerWorkers() {
+		if (!this.monque) throw new Error("Monque instance not initialized");
+		const monque = this.monque;
+		const workerControllers = this.injector.getProviders(ProviderTypes.WORKER_CONTROLLER);
+		const registeredJobs = /* @__PURE__ */ new Set();
+		this.logger.info(`Monque: Found ${workerControllers.length} worker controllers`);
+		for (const provider of workerControllers) {
+			const useClass = provider.useClass;
+			const workers = collectWorkerMetadata(useClass);
+			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) => {
+					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;
+							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);
+					await monque.schedule(cronPattern, fullName, {}, opts);
+				} else {
+					this.logger.debug(`Monque: Registering worker "${fullName}"`);
+					monque.register(fullName, handler, opts);
+				}
+			}
+		}
+		this.logger.info(`Monque: Registered ${registeredJobs.size} jobs`);
+	}
+};
+MonqueModule = __decorate([
+	Module({ imports: [MonqueService] }),
+	__decorateParam(0, Inject(InjectorService)),
+	__decorateParam(1, Inject(MonqueService)),
+	__decorateParam(2, Inject(LOGGER)),
+	__decorateParam(3, Inject(Configuration)),
+	__decorateMetadata("design:paramtypes", [
+		typeof (_ref = typeof InjectorService !== "undefined" && InjectorService) === "function" ? _ref : Object,
+		typeof (_ref2 = typeof MonqueService !== "undefined" && MonqueService) === "function" ? _ref2 : Object,
+		typeof (_ref3 = typeof LOGGER !== "undefined" && LOGGER) === "function" ? _ref3 : Object,
+		typeof (_ref4 = typeof Configuration !== "undefined" && Configuration) === "function" ? _ref4 : Object
+	])
+], MonqueModule);
+
+//#endregion
+export { Cron, MONQUE, MonqueModule, MonqueService, ProviderTypes, Worker, WorkerController, buildJobName, collectWorkerMetadata, getWorkerToken, resolveDatabase, validateDatabaseConfig };
+//# sourceMappingURL=index.mjs.map