@monque/core 1.4.0 → 1.5.1

package/src/scheduler/services/types.ts

@@ -19,11 +19,15 @@ export interface ResolvedMonqueOptions
 				| 'maxBackoffDelay'
 				| 'jobRetention'
 				| 'instanceConcurrency'
+				| 'maxPayloadSize'
 				| 'defaultConcurrency'
 				| 'maxConcurrency'
 			>
 		>,
-		Pick<MonqueOptions, 'maxBackoffDelay' | 'jobRetention' | 'instanceConcurrency'> {
+		Pick<
+			MonqueOptions,
+			'maxBackoffDelay' | 'jobRetention' | 'instanceConcurrency' | 'maxPayloadSize'
+		> {
 	// Ensure resolved options use the new naming convention
 	workerConcurrency: number;
 }

package/src/scheduler/types.ts

@@ -173,4 +173,27 @@ export interface MonqueOptions {
 	 * @default false
 	 */
 	skipIndexCreation?: boolean;
+
+	/**
+	 * Maximum allowed BSON byte size for job data payloads.
+	 *
+	 * When set, `enqueue()`, `now()`, and `schedule()` validate the payload size
+	 * using `BSON.calculateObjectSize()` before insertion. Jobs exceeding this limit
+	 * throw `PayloadTooLargeError`.
+	 *
+	 * When undefined, no size validation occurs.
+	 */
+	maxPayloadSize?: number | undefined;
+
+	/**
+	 * TTL in milliseconds for getQueueStats() result caching.
+	 *
+	 * When set to a positive value, repeated getQueueStats() calls with the same
+	 * filter return cached results instead of re-executing the aggregation pipeline.
+	 * Each unique filter (job name) maintains its own cache entry.
+	 *
+	 * Set to 0 to disable caching entirely.
+	 * @default 5000
+	 */
+	statsCacheTtlMs?: number;
 }

package/src/shared/errors.ts

@@ -223,3 +223,34 @@ export class AggregationTimeoutError extends MonqueError {
 		}
 	}
 }
+
+/**
+ * Error thrown when a job payload exceeds the configured maximum BSON byte size.
+ *
+ * @example
+ * ```typescript
+ * const monque = new Monque(db, { maxPayloadSize: 1_000_000 }); // 1 MB
+ *
+ * try {
+ *   await monque.enqueue('job', hugePayload);
+ * } catch (error) {
+ *   if (error instanceof PayloadTooLargeError) {
+ *     console.error(`Payload ${error.actualSize} bytes exceeds limit ${error.maxSize} bytes`);
+ *   }
+ * }
+ * ```
+ */
+export class PayloadTooLargeError extends MonqueError {
+	constructor(
+		message: string,
+		public readonly actualSize: number,
+		public readonly maxSize: number,
+	) {
+		super(message);
+		this.name = 'PayloadTooLargeError';
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, PayloadTooLargeError);
+		}
+	}
+}

package/src/shared/index.ts

@@ -5,6 +5,7 @@ export {
 	InvalidCursorError,
 	JobStateError,
 	MonqueError,
+	PayloadTooLargeError,
 	ShutdownTimeoutError,
 	WorkerRegistrationError,
 } from './errors.js';