@monque/core 0.1.0 → 0.2.0

package/README.md

@@ -4,6 +4,15 @@
 
 <h1 align="center">@monque/core</h1>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@monque/core">
+    <img src="https://img.shields.io/npm/v/%40monque%2Fcore?style=for-the-badge&label=%40monque%2Fcore" alt="@monque/core version" />
+  </a>
+  <a href="https://codecov.io/gh/ueberBrot/monque">
+    <img src="https://img.shields.io/codecov/c/github/ueberBrot/monque?style=for-the-badge&logo=codecov&logoColor=white" alt="Codecov" />
+  </a>
+</p>
+
 <p align="center">MongoDB-backed job scheduler with atomic locking, exponential backoff, and cron scheduling.</p>
 
 > [!WARNING]
@@ -42,7 +51,7 @@ const monque = new Monque(client.db('myapp'), {
 await monque.initialize();
 
 // Register workers
-monque.worker('send-email', async (job) => {
+monque.register('send-email', async (job) => {
   await sendEmail(job.data.to, job.data.subject);
 });
 
@@ -81,7 +90,7 @@ Creates a new Monque instance.
 - `enqueue(name, data, options?)` - Enqueue a job
 - `now(name, data)` - Enqueue for immediate processing
 - `schedule(cron, name, data)` - Schedule recurring job
-- `worker(name, handler, options?)` - Register a worker
+- `register(name, handler, options?)` - Register a worker
 - `start()` - Start processing jobs
 - `stop()` - Graceful shutdown
 - `isHealthy()` - Check scheduler health

package/dist/{errors-BX3oWYfZ.cjs → errors-D5ZGG2uI.cjs}

@@ -99,8 +99,8 @@ var ShutdownTimeoutError = class ShutdownTimeoutError extends MonqueError {
 * @example
 * ```typescript
 * try {
-*   monque.worker('send-email', handler1);
-*   monque.worker('send-email', handler2); // throws
+*   monque.register('send-email', handler1);
+*   monque.register('send-email', handler2); // throws
 * } catch (error) {
 *   if (error instanceof WorkerRegistrationError) {
 *     console.error('Worker already registered for:', error.jobName);
@@ -108,7 +108,7 @@ var ShutdownTimeoutError = class ShutdownTimeoutError extends MonqueError {
 * }
 *
 * // To intentionally replace a worker:
-* monque.worker('send-email', handler2, { replace: true });
+* monque.register('send-email', handler2, { replace: true });
 * ```
 */
 var WorkerRegistrationError = class WorkerRegistrationError extends MonqueError {
@@ -152,4 +152,4 @@ Object.defineProperty(exports, 'WorkerRegistrationError', {
     return WorkerRegistrationError;
   }
 });
-//# sourceMappingURL=errors-BX3oWYfZ.cjs.map
+//# sourceMappingURL=errors-D5ZGG2uI.cjs.map

package/dist/errors-D5ZGG2uI.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-D5ZGG2uI.cjs","names":[],"sources":["../src/shared/errors.ts"],"sourcesContent":["import type { Job } from '@/jobs';\n\n/**\n * Base error class for all Monque-related errors.\n *\n * @example\n * ```typescript\n * try {\n *   await monque.enqueue('job', data);\n * } catch (error) {\n *   if (error instanceof MonqueError) {\n *     console.error('Monque error:', error.message);\n *   }\n * }\n * ```\n */\nexport class MonqueError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = 'MonqueError';\n\t\t// Maintains proper stack trace for where our error was thrown (only available on V8)\n\t\t/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */\n\t\tif (Error.captureStackTrace) {\n\t\t\tError.captureStackTrace(this, MonqueError);\n\t\t}\n\t}\n}\n\n/**\n * Error thrown when an invalid cron expression is provided.\n *\n * @example\n * ```typescript\n * try {\n *   await monque.schedule('invalid cron', 'job', data);\n * } catch (error) {\n *   if (error instanceof InvalidCronError) {\n *     console.error('Invalid expression:', error.expression);\n *   }\n * }\n * ```\n */\nexport class InvalidCronError extends MonqueError {\n\tconstructor(\n\t\tpublic readonly expression: string,\n\t\tmessage: string,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = 'InvalidCronError';\n\t\t/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */\n\t\tif (Error.captureStackTrace) {\n\t\t\tError.captureStackTrace(this, InvalidCronError);\n\t\t}\n\t}\n}\n\n/**\n * Error thrown when there's a database connection issue.\n *\n * @example\n * ```typescript\n * try {\n *   await monque.enqueue('job', data);\n * } catch (error) {\n *   if (error instanceof ConnectionError) {\n *     console.error('Database connection lost');\n *   }\n * }\n * ```\n */\nexport class ConnectionError extends MonqueError {\n\tconstructor(message: string, options?: { cause?: Error }) {\n\t\tsuper(message);\n\t\tthis.name = 'ConnectionError';\n\t\tif (options?.cause) {\n\t\t\tthis.cause = options.cause;\n\t\t}\n\t\t/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */\n\t\tif (Error.captureStackTrace) {\n\t\t\tError.captureStackTrace(this, ConnectionError);\n\t\t}\n\t}\n}\n\n/**\n * Error thrown when graceful shutdown times out.\n * Includes information about jobs that were still in progress.\n *\n * @example\n * ```typescript\n * try {\n *   await monque.stop();\n * } catch (error) {\n *   if (error instanceof ShutdownTimeoutError) {\n *     console.error('Incomplete jobs:', error.incompleteJobs.length);\n *   }\n * }\n * ```\n */\nexport class ShutdownTimeoutError extends MonqueError {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly incompleteJobs: Job[],\n\t) {\n\t\tsuper(message);\n\t\tthis.name = 'ShutdownTimeoutError';\n\t\t/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */\n\t\tif (Error.captureStackTrace) {\n\t\t\tError.captureStackTrace(this, ShutdownTimeoutError);\n\t\t}\n\t}\n}\n\n/**\n * Error thrown when attempting to register a worker for a job name\n * that already has a registered worker, without explicitly allowing replacement.\n *\n * @example\n * ```typescript\n * try {\n *   monque.register('send-email', handler1);\n *   monque.register('send-email', handler2); // throws\n * } catch (error) {\n *   if (error instanceof WorkerRegistrationError) {\n *     console.error('Worker already registered for:', error.jobName);\n *   }\n * }\n *\n * // To intentionally replace a worker:\n * monque.register('send-email', handler2, { replace: true });\n * ```\n */\nexport class WorkerRegistrationError extends MonqueError {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly jobName: string,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = 'WorkerRegistrationError';\n\t\t/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */\n\t\tif (Error.captureStackTrace) {\n\t\t\tError.captureStackTrace(this, WorkerRegistrationError);\n\t\t}\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,IAAa,cAAb,MAAa,oBAAoB,MAAM;CACtC,YAAY,SAAiB;AAC5B,QAAM,QAAQ;AACd,OAAK,OAAO;;AAGZ,MAAI,MAAM,kBACT,OAAM,kBAAkB,MAAM,YAAY;;;;;;;;;;;;;;;;;AAmB7C,IAAa,mBAAb,MAAa,yBAAyB,YAAY;CACjD,YACC,AAAgB,YAChB,SACC;AACD,QAAM,QAAQ;EAHE;AAIhB,OAAK,OAAO;;AAEZ,MAAI,MAAM,kBACT,OAAM,kBAAkB,MAAM,iBAAiB;;;;;;;;;;;;;;;;;AAmBlD,IAAa,kBAAb,MAAa,wBAAwB,YAAY;CAChD,YAAY,SAAiB,SAA6B;AACzD,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,MAAI,SAAS,MACZ,MAAK,QAAQ,QAAQ;;AAGtB,MAAI,MAAM,kBACT,OAAM,kBAAkB,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;AAoBjD,IAAa,uBAAb,MAAa,6BAA6B,YAAY;CACrD,YACC,SACA,AAAgB,gBACf;AACD,QAAM,QAAQ;EAFE;AAGhB,OAAK,OAAO;;AAEZ,MAAI,MAAM,kBACT,OAAM,kBAAkB,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;AAwBtD,IAAa,0BAAb,MAAa,gCAAgC,YAAY;CACxD,YACC,SACA,AAAgB,SACf;AACD,QAAM,QAAQ;EAFE;AAGhB,OAAK,OAAO;;AAEZ,MAAI,MAAM,kBACT,OAAM,kBAAkB,MAAM,wBAAwB"}

package/dist/{errors-DWkXsP3R.mjs → errors-DEvnqoOC.mjs}

@@ -1,3 +1,3 @@
-import { a as WorkerRegistrationError, i as ShutdownTimeoutError, n as InvalidCronError, r as MonqueError, t as ConnectionError } from "./errors-DW20rHWR.mjs";
+import { a as WorkerRegistrationError, i as ShutdownTimeoutError, n as InvalidCronError, r as MonqueError, t as ConnectionError } from "./errors-DQ2_gprw.mjs";
 
 export { ShutdownTimeoutError };

package/dist/{errors-DW20rHWR.mjs → errors-DQ2_gprw.mjs}

@@ -98,8 +98,8 @@ var ShutdownTimeoutError = class ShutdownTimeoutError extends MonqueError {
 * @example
 * ```typescript
 * try {
-*   monque.worker('send-email', handler1);
-*   monque.worker('send-email', handler2); // throws
+*   monque.register('send-email', handler1);
+*   monque.register('send-email', handler2); // throws
 * } catch (error) {
 *   if (error instanceof WorkerRegistrationError) {
 *     console.error('Worker already registered for:', error.jobName);
@@ -107,7 +107,7 @@ var ShutdownTimeoutError = class ShutdownTimeoutError extends MonqueError {
 * }
 *
 * // To intentionally replace a worker:
-* monque.worker('send-email', handler2, { replace: true });
+* monque.register('send-email', handler2, { replace: true });
 * ```
 */
 var WorkerRegistrationError = class WorkerRegistrationError extends MonqueError {
@@ -122,4 +122,4 @@ var WorkerRegistrationError = class WorkerRegistrationError extends MonqueError
 
 //#endregion
 export { WorkerRegistrationError as a, ShutdownTimeoutError as i, InvalidCronError as n, MonqueError as r, ConnectionError as t };
-//# sourceMappingURL=errors-DW20rHWR.mjs.map
+//# sourceMappingURL=errors-DQ2_gprw.mjs.map

package/dist/errors-DQ2_gprw.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-DQ2_gprw.mjs","names":[],"sources":["../src/shared/errors.ts"],"sourcesContent":["import type { Job } from '@/jobs';\n\n/**\n * Base error class for all Monque-related errors.\n *\n * @example\n * ```typescript\n * try {\n *   await monque.enqueue('job', data);\n * } catch (error) {\n *   if (error instanceof MonqueError) {\n *     console.error('Monque error:', error.message);\n *   }\n * }\n * ```\n */\nexport class MonqueError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = 'MonqueError';\n\t\t// Maintains proper stack trace for where our error was thrown (only available on V8)\n\t\t/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */\n\t\tif (Error.captureStackTrace) {\n\t\t\tError.captureStackTrace(this, MonqueError);\n\t\t}\n\t}\n}\n\n/**\n * Error thrown when an invalid cron expression is provided.\n *\n * @example\n * ```typescript\n * try {\n *   await monque.schedule('invalid cron', 'job', data);\n * } catch (error) {\n *   if (error instanceof InvalidCronError) {\n *     console.error('Invalid expression:', error.expression);\n *   }\n * }\n * ```\n */\nexport class InvalidCronError extends MonqueError {\n\tconstructor(\n\t\tpublic readonly expression: string,\n\t\tmessage: string,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = 'InvalidCronError';\n\t\t/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */\n\t\tif (Error.captureStackTrace) {\n\t\t\tError.captureStackTrace(this, InvalidCronError);\n\t\t}\n\t}\n}\n\n/**\n * Error thrown when there's a database connection issue.\n *\n * @example\n * ```typescript\n * try {\n *   await monque.enqueue('job', data);\n * } catch (error) {\n *   if (error instanceof ConnectionError) {\n *     console.error('Database connection lost');\n *   }\n * }\n * ```\n */\nexport class ConnectionError extends MonqueError {\n\tconstructor(message: string, options?: { cause?: Error }) {\n\t\tsuper(message);\n\t\tthis.name = 'ConnectionError';\n\t\tif (options?.cause) {\n\t\t\tthis.cause = options.cause;\n\t\t}\n\t\t/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */\n\t\tif (Error.captureStackTrace) {\n\t\t\tError.captureStackTrace(this, ConnectionError);\n\t\t}\n\t}\n}\n\n/**\n * Error thrown when graceful shutdown times out.\n * Includes information about jobs that were still in progress.\n *\n * @example\n * ```typescript\n * try {\n *   await monque.stop();\n * } catch (error) {\n *   if (error instanceof ShutdownTimeoutError) {\n *     console.error('Incomplete jobs:', error.incompleteJobs.length);\n *   }\n * }\n * ```\n */\nexport class ShutdownTimeoutError extends MonqueError {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly incompleteJobs: Job[],\n\t) {\n\t\tsuper(message);\n\t\tthis.name = 'ShutdownTimeoutError';\n\t\t/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */\n\t\tif (Error.captureStackTrace) {\n\t\t\tError.captureStackTrace(this, ShutdownTimeoutError);\n\t\t}\n\t}\n}\n\n/**\n * Error thrown when attempting to register a worker for a job name\n * that already has a registered worker, without explicitly allowing replacement.\n *\n * @example\n * ```typescript\n * try {\n *   monque.register('send-email', handler1);\n *   monque.register('send-email', handler2); // throws\n * } catch (error) {\n *   if (error instanceof WorkerRegistrationError) {\n *     console.error('Worker already registered for:', error.jobName);\n *   }\n * }\n *\n * // To intentionally replace a worker:\n * monque.register('send-email', handler2, { replace: true });\n * ```\n */\nexport class WorkerRegistrationError extends MonqueError {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly jobName: string,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = 'WorkerRegistrationError';\n\t\t/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */\n\t\tif (Error.captureStackTrace) {\n\t\t\tError.captureStackTrace(this, WorkerRegistrationError);\n\t\t}\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgBA,IAAa,cAAb,MAAa,oBAAoB,MAAM;CACtC,YAAY,SAAiB;AAC5B,QAAM,QAAQ;AACd,OAAK,OAAO;;AAGZ,MAAI,MAAM,kBACT,OAAM,kBAAkB,MAAM,YAAY;;;;;;;;;;;;;;;;;AAmB7C,IAAa,mBAAb,MAAa,yBAAyB,YAAY;CACjD,YACC,AAAgB,YAChB,SACC;AACD,QAAM,QAAQ;EAHE;AAIhB,OAAK,OAAO;;AAEZ,MAAI,MAAM,kBACT,OAAM,kBAAkB,MAAM,iBAAiB;;;;;;;;;;;;;;;;;AAmBlD,IAAa,kBAAb,MAAa,wBAAwB,YAAY;CAChD,YAAY,SAAiB,SAA6B;AACzD,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,MAAI,SAAS,MACZ,MAAK,QAAQ,QAAQ;;AAGtB,MAAI,MAAM,kBACT,OAAM,kBAAkB,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;AAoBjD,IAAa,uBAAb,MAAa,6BAA6B,YAAY;CACrD,YACC,SACA,AAAgB,gBACf;AACD,QAAM,QAAQ;EAFE;AAGhB,OAAK,OAAO;;AAEZ,MAAI,MAAM,kBACT,OAAM,kBAAkB,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;AAwBtD,IAAa,0BAAb,MAAa,gCAAgC,YAAY;CACxD,YACC,SACA,AAAgB,SACf;AACD,QAAM,QAAQ;EAFE;AAGhB,OAAK,OAAO;;AAEZ,MAAI,MAAM,kBACT,OAAM,kBAAkB,MAAM,wBAAwB"}

package/dist/{errors-Ca92IlaL.cjs → errors-Dfli-u59.cjs}

@@ -1,3 +1,3 @@
-const require_errors = require('./errors-BX3oWYfZ.cjs');
+const require_errors = require('./errors-D5ZGG2uI.cjs');
 
 exports.ShutdownTimeoutError = require_errors.ShutdownTimeoutError;

package/dist/index.cjs

@@ -1,4 +1,4 @@
-const require_errors = require('./errors-BX3oWYfZ.cjs');
+const require_errors = require('./errors-D5ZGG2uI.cjs');
 let node_crypto = require("node:crypto");
 let node_events = require("node:events");
 let cron_parser = require("cron-parser");
@@ -396,7 +396,7 @@ type EmailJob = {};
 *   body: string
 * }
 *
-* monque.worker<EmailJob>('send-email', async (job) =>
+* monque.register<EmailJob>('send-email', async (job) =>
 {
 *   await emailService.send(job.data.to, job.data.subject, job.data.body)
 *
@@ -845,7 +845,7 @@ var Monque = class extends node_events.EventEmitter {
 	*   body: string;
 	* }
 	*
-	* monque.worker<EmailJob>('send-email', async (job) => {
+	* monque.register<EmailJob>('send-email', async (job) => {
 	*   await emailService.send(job.data.to, job.data.subject, job.data.body);
 	* });
 	* ```
@@ -853,7 +853,7 @@ var Monque = class extends node_events.EventEmitter {
 	* @example Worker with custom concurrency
 	* ```typescript
 	* // Limit to 2 concurrent video processing jobs (resource-intensive)
-	* monque.worker('process-video', async (job) => {
+	* monque.register('process-video', async (job) => {
 	*   await videoProcessor.transcode(job.data.videoId);
 	* }, { concurrency: 2 });
 	* ```
@@ -861,12 +861,12 @@ var Monque = class extends node_events.EventEmitter {
 	* @example Replacing an existing worker
 	* ```typescript
 	* // Replace the existing handler for 'send-email'
-	* monque.worker('send-email', newEmailHandler, { replace: true });
+	* monque.register('send-email', newEmailHandler, { replace: true });
 	* ```
 	*
 	* @example Worker with error handling
 	* ```typescript
-	* monque.worker('sync-user', async (job) => {
+	* monque.register('sync-user', async (job) => {
 	*   try {
 	*     await externalApi.syncUser(job.data.userId);
 	*   } catch (error) {
@@ -877,7 +877,7 @@ var Monque = class extends node_events.EventEmitter {
 	* });
 	* ```
 	*/
-	worker(name, handler, options = {}) {
+	register(name, handler, options = {}) {
 		const concurrency = options.concurrency ?? this.options.defaultConcurrency;
 		if (this.workers.has(name) && options.replace !== true) throw new require_errors.WorkerRegistrationError(`Worker already registered for job name "${name}". Use { replace: true } to replace.`, name);
 		this.workers.set(name, {
@@ -901,8 +901,8 @@ var Monque = class extends node_events.EventEmitter {
 	* const monque = new Monque(db);
 	* await monque.initialize();
 	*
-	* monque.worker('send-email', emailHandler);
-	* monque.worker('process-order', orderHandler);
+	* monque.register('send-email', emailHandler);
+	* monque.register('process-order', orderHandler);
 	*
 	* monque.start(); // Begin processing jobs
 	* ```
@@ -1037,7 +1037,7 @@ var Monque = class extends node_events.EventEmitter {
 		}
 		if (result === "timeout") {
 			const incompleteJobs = this.getActiveJobsList();
-			const { ShutdownTimeoutError: ShutdownTimeoutError$1 } = await Promise.resolve().then(() => require("./errors-Ca92IlaL.cjs"));
+			const { ShutdownTimeoutError: ShutdownTimeoutError$1 } = await Promise.resolve().then(() => require("./errors-Dfli-u59.cjs"));
 			const error = new ShutdownTimeoutError$1(`Shutdown timed out after ${this.options.shutdownTimeout}ms with ${incompleteJobs.length} incomplete jobs`, incompleteJobs);
 			this.emit("job:error", { error });
 		}
@@ -1195,6 +1195,7 @@ var Monque = class extends node_events.EventEmitter {
 	*
 	* Called at regular intervals (configured by `pollInterval`). For each registered worker,
 	* attempts to acquire jobs up to the worker's available concurrency slots.
+	* Aborts early if the scheduler is stopping (`isRunning` is false).
 	*
 	* @private
 	*/
@@ -1204,6 +1205,7 @@ var Monque = class extends node_events.EventEmitter {
 			const availableSlots = worker.concurrency - worker.activeJobs.size;
 			if (availableSlots <= 0) continue;
 			for (let i = 0; i < availableSlots; i++) {
+				if (!this.isRunning) return;
 				const job = await this.acquireJob(name);
 				if (job) this.processJob(job, worker).catch((error) => {
 					this.emit("job:error", {
@@ -1224,12 +1226,14 @@ var Monque = class extends node_events.EventEmitter {
 	* - Has nextRunAt <= now
 	* - Is not claimed by another instance (claimedBy is null/undefined)
 	*
+	* Returns `null` immediately if scheduler is stopping (`isRunning` is false).
+	*
 	* @private
 	* @param name - The job type to acquire
 	* @returns The acquired job with updated status, claimedBy, and heartbeat info, or `null` if no jobs available
 	*/
 	async acquireJob(name) {
-		if (!this.collection) return null;
+		if (!this.collection || !this.isRunning) return null;
 		const now = /* @__PURE__ */ new Date();
 		const result = await this.collection.findOneAndUpdate({
 			name,