@monque/core 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@monque/core",
-	"version": "1.1.0",
+	"version": "1.1.2",
 	"description": "MongoDB-backed job scheduler with atomic locking, exponential backoff, and cron scheduling",
 	"author": "Maurice de Bruyn <debruyn.maurice@gmail.com>",
 	"repository": {
@@ -8,6 +8,7 @@
 		"url": "git+https://github.com/ueberBrot/monque.git",
 		"directory": "packages/core"
 	},
+	"license": "ISC",
 	"bugs": {
 		"url": "https://github.com/ueberBrot/monque/issues"
 	},
@@ -36,7 +37,8 @@
 		}
 	},
 	"files": [
-		"dist"
+		"dist",
+		"src"
 	],
 	"scripts": {
 		"build": "tsdown",
@@ -66,7 +68,6 @@
 		"atomic",
 		"persistence"
 	],
-	"license": "ISC",
 	"dependencies": {
 		"cron-parser": "^5.5.0"
 	},
@@ -79,12 +80,13 @@
 		"@testcontainers/mongodb": "^11.11.0",
 		"@total-typescript/ts-reset": "^0.6.1",
 		"@types/bun": "^1.3.6",
-		"@vitest/coverage-v8": "^4.0.17",
+		"@vitest/coverage-v8": "^4.0.18",
 		"fishery": "^2.4.0",
 		"mongodb": "^7.0.0",
-		"publint": "^0.3.16",
-		"tsdown": "^0.19.0",
+		"publint": "^0.3.17",
+		"tsdown": "^0.20.1",
 		"typescript": "^5.9.3",
-		"vitest": "^4.0.17"
+		"unplugin-unused": "^0.5.7",
+		"vitest": "^4.0.18"
 	}
 }

package/src/events/index.ts

@@ -0,0 +1 @@
+export type { MonqueEventMap } from './types.js';

package/src/events/types.ts

@@ -0,0 +1,113 @@
+import type { Job } from '@/jobs';
+
+/**
+ * Event payloads for Monque lifecycle events.
+ */
+export interface MonqueEventMap {
+	/**
+	 * Emitted when a job begins processing.
+	 */
+	'job:start': Job;
+
+	/**
+	 * Emitted when a job finishes successfully.
+	 */
+	'job:complete': {
+		job: Job;
+		/** Processing duration in milliseconds */
+		duration: number;
+	};
+
+	/**
+	 * Emitted when a job fails (may retry).
+	 */
+	'job:fail': {
+		job: Job;
+		error: Error;
+		/** Whether the job will be retried */
+		willRetry: boolean;
+	};
+
+	/**
+	 * Emitted for unexpected errors during processing.
+	 */
+	'job:error': {
+		error: Error;
+		job?: Job;
+	};
+
+	/**
+	 * Emitted when stale jobs are recovered on startup.
+	 */
+	'stale:recovered': {
+		count: number;
+	};
+
+	/**
+	 * Emitted when the change stream is successfully connected.
+	 */
+	'changestream:connected': undefined;
+
+	/**
+	 * Emitted when a change stream error occurs.
+	 */
+	'changestream:error': {
+		error: Error;
+	};
+
+	/**
+	 * Emitted when the change stream is closed.
+	 */
+	'changestream:closed': undefined;
+
+	/**
+	 * Emitted when falling back from change streams to polling-only mode.
+	 */
+	'changestream:fallback': {
+		reason: string;
+	};
+	/**
+	 * Emitted when a job is manually cancelled.
+	 */
+	'job:cancelled': {
+		job: Job;
+	};
+
+	/**
+	 * Emitted when a job is manually retried.
+	 */
+	'job:retried': {
+		job: Job;
+		previousStatus: 'failed' | 'cancelled';
+	};
+
+	/**
+	 * Emitted when a job is manually deleted.
+	 */
+	'job:deleted': {
+		jobId: string;
+	};
+
+	/**
+	 * Emitted when multiple jobs are cancelled in bulk.
+	 */
+	'jobs:cancelled': {
+		jobIds: string[];
+		count: number;
+	};
+
+	/**
+	 * Emitted when multiple jobs are retried in bulk.
+	 */
+	'jobs:retried': {
+		jobIds: string[];
+		count: number;
+	};
+
+	/**
+	 * Emitted when multiple jobs are deleted in bulk.
+	 */
+	'jobs:deleted': {
+		count: number;
+	};
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+// Types - Events
+export type { MonqueEventMap } from '@/events';
+// Types - Jobs
+export {
+	type BulkOperationResult,
+	CursorDirection,
+	type CursorOptions,
+	type CursorPage,
+	type EnqueueOptions,
+	type GetJobsFilter,
+	isCancelledJob,
+	isCompletedJob,
+	isFailedJob,
+	isPendingJob,
+	isPersistedJob,
+	isProcessingJob,
+	isRecurringJob,
+	isValidJobStatus,
+	type Job,
+	type JobHandler,
+	type JobSelector,
+	JobStatus,
+	type JobStatusType,
+	type PersistedJob,
+	type QueueStats,
+	type ScheduleOptions,
+} from '@/jobs';
+// Types - Scheduler
+export type { MonqueOptions } from '@/scheduler';
+// Main class
+export { Monque } from '@/scheduler';
+// Errors
+// Utilities (for advanced use cases)
+export {
+	AggregationTimeoutError,
+	ConnectionError,
+	calculateBackoff,
+	calculateBackoffDelay,
+	DEFAULT_BASE_INTERVAL,
+	DEFAULT_MAX_BACKOFF_DELAY,
+	getNextCronDate,
+	InvalidCronError,
+	InvalidCursorError,
+	JobStateError,
+	MonqueError,
+	ShutdownTimeoutError,
+	validateCronExpression,
+	WorkerRegistrationError,
+} from '@/shared';
+// Types - Workers
+export type { WorkerOptions } from '@/workers';

package/src/jobs/guards.ts

@@ -0,0 +1,220 @@
+import type { Job, JobStatusType, PersistedJob } from './types.js';
+import { JobStatus } from './types.js';
+
+/**
+ * Type guard to check if a job has been persisted to MongoDB.
+ *
+ * A persisted job is guaranteed to have an `_id` field, which means it has been
+ * successfully inserted into the database. This is useful when you need to ensure
+ * a job can be updated or referenced by its ID.
+ *
+ * @template T - The type of the job's data payload
+ * @param job - The job to check
+ * @returns `true` if the job has a valid `_id`, narrowing the type to `PersistedJob<T>`
+ *
+ * @example Basic usage
+ * ```typescript
+ * const job: Job<EmailData> = await monque.enqueue('send-email', emailData);
+ *
+ * if (isPersistedJob(job)) {
+ *   // TypeScript knows job._id exists
+ *   console.log(`Job ID: ${job._id.toString()}`);
+ * }
+ * ```
+ *
+ * @example In a conditional
+ * ```typescript
+ * function logJobId(job: Job) {
+ *   if (!isPersistedJob(job)) {
+ *     console.log('Job not yet persisted');
+ *     return;
+ *   }
+ *   // TypeScript knows job is PersistedJob here
+ *   console.log(`Processing job ${job._id.toString()}`);
+ * }
+ * ```
+ */
+export function isPersistedJob<T>(job: Job<T>): job is PersistedJob<T> {
+	return '_id' in job && job._id !== undefined && job._id !== null;
+}
+
+/**
+ * Type guard to check if a value is a valid job status.
+ *
+ * Validates that a value is one of the five valid job statuses: `'pending'`,
+ * `'processing'`, `'completed'`, `'failed'`, or `'cancelled'`. Useful for runtime validation
+ * of user input or external data.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid `JobStatusType`, narrowing the type
+ *
+ * @example Validating user input
+ * ```typescript
+ * function filterByStatus(status: string) {
+ *   if (!isValidJobStatus(status)) {
+ *     throw new Error(`Invalid status: ${status}`);
+ *   }
+ *   // TypeScript knows status is JobStatusType here
+ *   return db.jobs.find({ status });
+ * }
+ * ```
+ *
+ * @example Runtime validation
+ * ```typescript
+ * const statusFromApi = externalData.status;
+ *
+ * if (isValidJobStatus(statusFromApi)) {
+ *   job.status = statusFromApi;
+ * } else {
+ *   job.status = JobStatus.PENDING;
+ * }
+ * ```
+ */
+export function isValidJobStatus(value: unknown): value is JobStatusType {
+	return typeof value === 'string' && Object.values(JobStatus).includes(value as JobStatusType);
+}
+
+/**
+ * Type guard to check if a job is in pending status.
+ *
+ * A convenience helper for checking if a job is waiting to be processed.
+ * Equivalent to `job.status === JobStatus.PENDING` but with better semantics.
+ *
+ * @template T - The type of the job's data payload
+ * @param job - The job to check
+ * @returns `true` if the job status is `'pending'`
+ *
+ * @example Filter pending jobs
+ * ```typescript
+ * const jobs = await monque.getJobs();
+ * const pendingJobs = jobs.filter(isPendingJob);
+ * console.log(`${pendingJobs.length} jobs waiting to be processed`);
+ * ```
+ *
+ * @example Conditional logic
+ * ```typescript
+ * if (isPendingJob(job)) {
+ *   await monque.now(job.name, job.data);
+ * }
+ * ```
+ */
+export function isPendingJob<T>(job: Job<T>): boolean {
+	return job.status === JobStatus.PENDING;
+}
+
+/**
+ * Type guard to check if a job is currently being processed.
+ *
+ * A convenience helper for checking if a job is actively running.
+ * Equivalent to `job.status === JobStatus.PROCESSING` but with better semantics.
+ *
+ * @template T - The type of the job's data payload
+ * @param job - The job to check
+ * @returns `true` if the job status is `'processing'`
+ *
+ * @example Monitor active jobs
+ * ```typescript
+ * const jobs = await monque.getJobs();
+ * const activeJobs = jobs.filter(isProcessingJob);
+ * console.log(`${activeJobs.length} jobs currently running`);
+ * ```
+ */
+export function isProcessingJob<T>(job: Job<T>): boolean {
+	return job.status === JobStatus.PROCESSING;
+}
+
+/**
+ * Type guard to check if a job has completed successfully.
+ *
+ * A convenience helper for checking if a job finished without errors.
+ * Equivalent to `job.status === JobStatus.COMPLETED` but with better semantics.
+ *
+ * @template T - The type of the job's data payload
+ * @param job - The job to check
+ * @returns `true` if the job status is `'completed'`
+ *
+ * @example Find completed jobs
+ * ```typescript
+ * const jobs = await monque.getJobs();
+ * const completedJobs = jobs.filter(isCompletedJob);
+ * console.log(`${completedJobs.length} jobs completed successfully`);
+ * ```
+ */
+export function isCompletedJob<T>(job: Job<T>): boolean {
+	return job.status === JobStatus.COMPLETED;
+}
+
+/**
+ * Type guard to check if a job has permanently failed.
+ *
+ * A convenience helper for checking if a job exhausted all retries.
+ * Equivalent to `job.status === JobStatus.FAILED` but with better semantics.
+ *
+ * @template T - The type of the job's data payload
+ * @param job - The job to check
+ * @returns `true` if the job status is `'failed'`
+ *
+ * @example Handle failed jobs
+ * ```typescript
+ * const jobs = await monque.getJobs();
+ * const failedJobs = jobs.filter(isFailedJob);
+ *
+ * for (const job of failedJobs) {
+ *   console.error(`Job ${job.name} failed: ${job.failReason}`);
+ *   await sendAlert(job);
+ * }
+ * ```
+ */
+export function isFailedJob<T>(job: Job<T>): boolean {
+	return job.status === JobStatus.FAILED;
+}
+
+/**
+ * Type guard to check if a job has been manually cancelled.
+ *
+ * A convenience helper for checking if a job was cancelled by an operator.
+ * Equivalent to `job.status === JobStatus.CANCELLED` but with better semantics.
+ *
+ * @template T - The type of the job's data payload
+ * @param job - The job to check
+ * @returns `true` if the job status is `'cancelled'`
+ *
+ * @example Filter cancelled jobs
+ * ```typescript
+ * const jobs = await monque.getJobs();
+ * const cancelledJobs = jobs.filter(isCancelledJob);
+ * console.log(`${cancelledJobs.length} jobs were cancelled`);
+ * ```
+ */
+export function isCancelledJob<T>(job: Job<T>): boolean {
+	return job.status === JobStatus.CANCELLED;
+}
+
+/**
+ * Type guard to check if a job is a recurring scheduled job.
+ *
+ * A recurring job has a `repeatInterval` cron expression and will be automatically
+ * rescheduled after each successful completion.
+ *
+ * @template T - The type of the job's data payload
+ * @param job - The job to check
+ * @returns `true` if the job has a `repeatInterval` defined
+ *
+ * @example Filter recurring jobs
+ * ```typescript
+ * const jobs = await monque.getJobs();
+ * const recurringJobs = jobs.filter(isRecurringJob);
+ * console.log(`${recurringJobs.length} jobs will repeat automatically`);
+ * ```
+ *
+ * @example Conditional cleanup
+ * ```typescript
+ * if (!isRecurringJob(job) && isCompletedJob(job)) {
+ *   // Safe to delete one-time completed jobs
+ *   await deleteJob(job._id);
+ * }
+ * ```
+ */
+export function isRecurringJob<T>(job: Job<T>): boolean {
+	return job.repeatInterval !== undefined && job.repeatInterval !== null;
+}

package/src/jobs/index.ts

@@ -0,0 +1,29 @@
+// Guards
+export {
+	isCancelledJob,
+	isCompletedJob,
+	isFailedJob,
+	isPendingJob,
+	isPersistedJob,
+	isProcessingJob,
+	isRecurringJob,
+	isValidJobStatus,
+} from './guards.js';
+// Types
+export {
+	type BulkOperationResult,
+	CursorDirection,
+	type CursorDirectionType,
+	type CursorOptions,
+	type CursorPage,
+	type EnqueueOptions,
+	type GetJobsFilter,
+	type Job,
+	type JobHandler,
+	type JobSelector,
+	JobStatus,
+	type JobStatusType,
+	type PersistedJob,
+	type QueueStats,
+	type ScheduleOptions,
+} from './types.js';