@monque/core 1.1.0 → 1.1.2

package/src/shared/utils/backoff.ts

@@ -0,0 +1,77 @@
+/**
+ * Default base interval for exponential backoff in milliseconds.
+ * @default 1000
+ */
+export const DEFAULT_BASE_INTERVAL = 1000;
+
+/**
+ * Default maximum delay cap for exponential backoff in milliseconds.
+ *
+ * This prevents unbounded delays (e.g. failCount=20 is >11 days at 1s base)
+ * and avoids precision/overflow issues for very large fail counts.
+ * @default 86400000 (24 hours)
+ */
+export const DEFAULT_MAX_BACKOFF_DELAY = 24 * 60 * 60 * 1_000;
+
+/**
+ * Calculate the next run time using exponential backoff.
+ *
+ * Formula: nextRunAt = now + (2^failCount × baseInterval)
+ *
+ * @param failCount - Number of previous failed attempts
+ * @param baseInterval - Base interval in milliseconds (default: 1000ms)
+ * @param maxDelay - Maximum delay in milliseconds (optional)
+ * @returns The next run date
+ *
+ * @example
+ * ```typescript
+ * // First retry (failCount=1): 2^1 * 1000 = 2000ms delay
+ * const nextRun = calculateBackoff(1);
+ *
+ * // Second retry (failCount=2): 2^2 * 1000 = 4000ms delay
+ * const nextRun = calculateBackoff(2);
+ *
+ * // With custom base interval
+ * const nextRun = calculateBackoff(3, 500); // 2^3 * 500 = 4000ms delay
+ *
+ * // With max delay
+ * const nextRun = calculateBackoff(10, 1000, 60000); // capped at 60000ms
+ * ```
+ */
+export function calculateBackoff(
+	failCount: number,
+	baseInterval: number = DEFAULT_BASE_INTERVAL,
+	maxDelay?: number,
+): Date {
+	const effectiveMaxDelay = maxDelay ?? DEFAULT_MAX_BACKOFF_DELAY;
+	let delay = 2 ** failCount * baseInterval;
+
+	if (delay > effectiveMaxDelay) {
+		delay = effectiveMaxDelay;
+	}
+
+	return new Date(Date.now() + delay);
+}
+
+/**
+ * Calculate just the delay in milliseconds for a given fail count.
+ *
+ * @param failCount - Number of previous failed attempts
+ * @param baseInterval - Base interval in milliseconds (default: 1000ms)
+ * @param maxDelay - Maximum delay in milliseconds (optional)
+ * @returns The delay in milliseconds
+ */
+export function calculateBackoffDelay(
+	failCount: number,
+	baseInterval: number = DEFAULT_BASE_INTERVAL,
+	maxDelay?: number,
+): number {
+	const effectiveMaxDelay = maxDelay ?? DEFAULT_MAX_BACKOFF_DELAY;
+	let delay = 2 ** failCount * baseInterval;
+
+	if (delay > effectiveMaxDelay) {
+		delay = effectiveMaxDelay;
+	}
+
+	return delay;
+}

package/src/shared/utils/cron.ts

@@ -0,0 +1,67 @@
+import { CronExpressionParser } from 'cron-parser';
+
+import { InvalidCronError } from '../errors.js';
+
+/**
+ * Parse a cron expression and return the next scheduled run date.
+ *
+ * @param expression - A 5-field cron expression (minute hour day-of-month month day-of-week) or a predefined expression
+ * @param currentDate - The reference date for calculating next run (default: now)
+ * @returns The next scheduled run date
+ * @throws {InvalidCronError} If the cron expression is invalid
+ *
+ * @example
+ * ```typescript
+ * // Every minute
+ * const nextRun = getNextCronDate('* * * * *');
+ *
+ * // Every day at midnight
+ * const nextRun = getNextCronDate('0 0 * * *');
+ *
+ * // Using predefined expression
+ * const nextRun = getNextCronDate('@daily');
+ *
+ * // Every Monday at 9am
+ * const nextRun = getNextCronDate('0 9 * * 1');
+ * ```
+ */
+export function getNextCronDate(expression: string, currentDate?: Date): Date {
+	try {
+		const interval = CronExpressionParser.parse(expression, {
+			currentDate: currentDate ?? new Date(),
+		});
+		return interval.next().toDate();
+	} catch (error) {
+		handleCronParseError(expression, error);
+	}
+}
+
+/**
+ * Validate a cron expression without calculating the next run date.
+ *
+ * @param expression - A 5-field cron expression
+ * @throws {InvalidCronError} If the cron expression is invalid
+ *
+ * @example
+ * ```typescript
+ * validateCronExpression('0 9 * * 1'); // Throws if invalid
+ * ```
+ */
+export function validateCronExpression(expression: string): void {
+	try {
+		CronExpressionParser.parse(expression);
+	} catch (error) {
+		handleCronParseError(expression, error);
+	}
+}
+
+function handleCronParseError(expression: string, error: unknown): never {
+	/* istanbul ignore next -- @preserve cron-parser always throws Error objects */
+	const errorMessage = error instanceof Error ? error.message : 'Unknown parsing error';
+	throw new InvalidCronError(
+		expression,
+		`Invalid cron expression "${expression}": ${errorMessage}. ` +
+			'Expected 5-field format: "minute hour day-of-month month day-of-week" or predefined expression (e.g. @daily). ' +
+			'Example: "0 9 * * 1" (every Monday at 9am)',
+	);
+}

package/src/shared/utils/index.ts

@@ -0,0 +1,7 @@
+export {
+	calculateBackoff,
+	calculateBackoffDelay,
+	DEFAULT_BASE_INTERVAL,
+	DEFAULT_MAX_BACKOFF_DELAY,
+} from './backoff.js';
+export { getNextCronDate, validateCronExpression } from './cron.js';

package/src/workers/index.ts

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

package/src/workers/types.ts

@@ -0,0 +1,39 @@
+import type { JobHandler, PersistedJob } from '@/jobs';
+
+/**
+ * Options for registering a worker.
+ *
+ * @example
+ * ```typescript
+ * monque.register('send-email', emailHandler, {
+ *   concurrency: 3,
+ * });
+ * ```
+ */
+export interface WorkerOptions {
+	/**
+	 * Number of concurrent jobs this worker can process.
+	 * @default 5 (uses defaultConcurrency from MonqueOptions)
+	 */
+	concurrency?: number;
+
+	/**
+	 * Allow replacing an existing worker for the same job name.
+	 * If false (default) and a worker already exists, throws WorkerRegistrationError.
+	 * @default false
+	 */
+	replace?: boolean;
+}
+
+/**
+ * Internal worker registration with handler and options.
+ * Tracks the handler, concurrency limit, and currently active jobs.
+ */
+export interface WorkerRegistration<T = unknown> {
+	/** The job handler function */
+	handler: JobHandler<T>;
+	/** Maximum concurrent jobs for this worker */
+	concurrency: number;
+	/** Map of active job IDs to their job data */
+	activeJobs: Map<string, PersistedJob<T>>;
+}