@nicnocquee/dataqueue 1.22.0 → 1.24.0

package/dist/index.d.cts

@@ -11,18 +11,75 @@ interface JobOptions<PayloadMap, T extends JobType<PayloadMap>> {
      * Timeout for this job in milliseconds. If not set, uses the processor default or unlimited.
      */
     timeoutMs?: number;
+    /**
+     * If true, the job will be forcefully terminated (using Worker Threads) when timeout is reached.
+     * If false (default), the job will only receive an AbortSignal and must handle the abort gracefully.
+     *
+     * **⚠️ RUNTIME REQUIREMENTS**: This option requires **Node.js** and uses the `worker_threads` module.
+     * It will **not work** in Bun or other runtimes that don't support Node.js worker threads.
+     *
+     * **IMPORTANT**: When `forceKillOnTimeout` is true, the handler must be serializable. This means:
+     * - The handler should be a standalone function (not a closure over external variables)
+     * - It should not capture variables from outer scopes that reference external dependencies
+     * - It should not use 'this' context unless it's a bound method
+     * - All dependencies must be importable in the worker thread context
+     *
+     * **Examples of serializable handlers:**
+     * ```ts
+     * // ✅ Good - standalone function
+     * const handler = async (payload, signal) => {
+     *   await doSomething(payload);
+     * };
+     *
+     * // ✅ Good - function that imports dependencies
+     * const handler = async (payload, signal) => {
+     *   const { api } = await import('./api');
+     *   await api.call(payload);
+     * };
+     *
+     * // ❌ Bad - closure over external variable
+     * const db = getDatabase();
+     * const handler = async (payload, signal) => {
+     *   await db.query(payload); // 'db' is captured from closure
+     * };
+     *
+     * // ❌ Bad - uses 'this' context
+     * class MyHandler {
+     *   async handle(payload, signal) {
+     *     await this.doSomething(payload); // 'this' won't work
+     *   }
+     * }
+     * ```
+     *
+     * If your handler doesn't meet these requirements, use `forceKillOnTimeout: false` (default)
+     * and ensure your handler checks `signal.aborted` to exit gracefully.
+     *
+     * Note: forceKillOnTimeout requires timeoutMs to be set.
+     */
+    forceKillOnTimeout?: boolean;
     /**
      * Tags for this job. Used for grouping, searching, or batch operations.
      */
     tags?: string[];
 }
+/**
+ * Options for editing a pending job.
+ * All fields are optional and only provided fields will be updated.
+ * Note: jobType cannot be changed.
+ * timeoutMs and tags can be set to null to clear them.
+ */
+type EditJobOptions<PayloadMap, T extends JobType<PayloadMap>> = Partial<Omit<JobOptions<PayloadMap, T>, 'jobType'>> & {
+    timeoutMs?: number | null;
+    tags?: string[] | null;
+};
 declare enum JobEventType {
     Added = "added",
     Processing = "processing",
     Completed = "completed",
     Failed = "failed",
     Cancelled = "cancelled",
-    Retried = "retried"
+    Retried = "retried",
+    Edited = "edited"
 }
 interface JobEvent {
     id: number;
@@ -60,6 +117,11 @@ interface JobRecord<PayloadMap, T extends JobType<PayloadMap>> {
      * Timeout for this job in milliseconds (null means no timeout).
      */
     timeoutMs?: number | null;
+    /**
+     * If true, the job will be forcefully terminated (using Worker Threads) when timeout is reached.
+     * If false (default), the job will only receive an AbortSignal and must handle the abort gracefully.
+     */
+    forceKillOnTimeout?: boolean | null;
     /**
      * The reason for the last failure, if any.
      */
@@ -242,6 +304,42 @@ interface JobQueue<PayloadMap> {
      * - This will set the job status to 'cancelled' and clear the locked_at and locked_by.
      */
     cancelJob: (jobId: number) => Promise<void>;
+    /**
+     * Edit a pending job given its ID.
+     * - Only works for jobs with status 'pending'. Silently fails for other statuses.
+     * - All fields in EditJobOptions are optional - only provided fields will be updated.
+     * - jobType cannot be changed.
+     * - Records an 'edited' event with the updated fields in metadata.
+     */
+    editJob: <T extends JobType<PayloadMap>>(jobId: number, updates: EditJobOptions<PayloadMap, T>) => Promise<void>;
+    /**
+     * Edit all pending jobs that match the filters.
+     * - Only works for jobs with status 'pending'. Non-pending jobs are not affected.
+     * - All fields in EditJobOptions are optional - only provided fields will be updated.
+     * - jobType cannot be changed.
+     * - Records an 'edited' event with the updated fields in metadata for each affected job.
+     * - Returns the number of jobs that were edited.
+     * - The filters are:
+     *   - jobType: The job type to edit.
+     *   - priority: The priority of the job to edit.
+     *   - runAt: The time the job is scheduled to run at (now supports gt/gte/lt/lte/eq).
+     *   - tags: An object with 'values' (string[]) and 'mode' (TagQueryMode) for tag-based editing.
+     */
+    editAllPendingJobs: <T extends JobType<PayloadMap>>(filters: {
+        jobType?: string;
+        priority?: number;
+        runAt?: Date | {
+            gt?: Date;
+            gte?: Date;
+            lt?: Date;
+            lte?: Date;
+            eq?: Date;
+        };
+        tags?: {
+            values: string[];
+            mode?: TagQueryMode;
+        };
+    } | undefined, updates: EditJobOptions<PayloadMap, T>) => Promise<number>;
     /**
      * Reclaim stuck jobs.
      * - If a process (e.g., API route or worker) crashes after marking a job as 'processing' but before completing it, the job can remain stuck in the 'processing' state indefinitely. This can happen if the process is killed or encounters an unhandled error after updating the job status but before marking it as 'completed' or 'failed'.
@@ -288,9 +386,60 @@ interface JobQueue<PayloadMap> {
     getPool: () => Pool;
 }
 
+/**
+ * Validates that a job handler can be serialized for use with forceKillOnTimeout.
+ *
+ * This function checks if a handler can be safely serialized and executed in a worker thread.
+ * Use this function during development to catch serialization issues early.
+ *
+ * @param handler - The job handler function to validate
+ * @param jobType - Optional job type name for better error messages
+ * @returns An object with `isSerializable` boolean and optional `error` message
+ *
+ * @example
+ * ```ts
+ * const handler = async (payload, signal) => {
+ *   await doSomething(payload);
+ * };
+ *
+ * const result = validateHandlerSerializable(handler, 'myJob');
+ * if (!result.isSerializable) {
+ *   console.error('Handler is not serializable:', result.error);
+ * }
+ * ```
+ */
+declare function validateHandlerSerializable<PayloadMap, T extends keyof PayloadMap & string>(handler: JobHandler<PayloadMap, T>, jobType?: string): {
+    isSerializable: boolean;
+    error?: string;
+};
+/**
+ * Test if a handler can be serialized and executed in a worker thread.
+ * This is a more thorough check that actually attempts to serialize and deserialize the handler.
+ *
+ * @param handler - The job handler function to test
+ * @param jobType - Optional job type name for better error messages
+ * @returns Promise that resolves to validation result
+ *
+ * @example
+ * ```ts
+ * const handler = async (payload, signal) => {
+ *   await doSomething(payload);
+ * };
+ *
+ * const result = await testHandlerSerialization(handler, 'myJob');
+ * if (!result.isSerializable) {
+ *   console.error('Handler failed serialization test:', result.error);
+ * }
+ * ```
+ */
+declare function testHandlerSerialization<PayloadMap, T extends keyof PayloadMap & string>(handler: JobHandler<PayloadMap, T>, jobType?: string): Promise<{
+    isSerializable: boolean;
+    error?: string;
+}>;
+
 /**
  * Initialize the job queue system
  */
 declare const initJobQueue: <PayloadMap = any>(config: JobQueueConfig) => JobQueue<PayloadMap>;
 
-export { type DatabaseSSLConfig, FailureReason, type JobEvent, JobEventType, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobRecord, type JobStatus, type JobType, type Processor, type ProcessorOptions, type TagQueryMode, initJobQueue };
+export { type DatabaseSSLConfig, type EditJobOptions, FailureReason, type JobEvent, JobEventType, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobRecord, type JobStatus, type JobType, type Processor, type ProcessorOptions, type TagQueryMode, initJobQueue, testHandlerSerialization, validateHandlerSerializable };

package/dist/index.d.ts

@@ -11,18 +11,75 @@ interface JobOptions<PayloadMap, T extends JobType<PayloadMap>> {
      * Timeout for this job in milliseconds. If not set, uses the processor default or unlimited.
      */
     timeoutMs?: number;
+    /**
+     * If true, the job will be forcefully terminated (using Worker Threads) when timeout is reached.
+     * If false (default), the job will only receive an AbortSignal and must handle the abort gracefully.
+     *
+     * **⚠️ RUNTIME REQUIREMENTS**: This option requires **Node.js** and uses the `worker_threads` module.
+     * It will **not work** in Bun or other runtimes that don't support Node.js worker threads.
+     *
+     * **IMPORTANT**: When `forceKillOnTimeout` is true, the handler must be serializable. This means:
+     * - The handler should be a standalone function (not a closure over external variables)
+     * - It should not capture variables from outer scopes that reference external dependencies
+     * - It should not use 'this' context unless it's a bound method
+     * - All dependencies must be importable in the worker thread context
+     *
+     * **Examples of serializable handlers:**
+     * ```ts
+     * // ✅ Good - standalone function
+     * const handler = async (payload, signal) => {
+     *   await doSomething(payload);
+     * };
+     *
+     * // ✅ Good - function that imports dependencies
+     * const handler = async (payload, signal) => {
+     *   const { api } = await import('./api');
+     *   await api.call(payload);
+     * };
+     *
+     * // ❌ Bad - closure over external variable
+     * const db = getDatabase();
+     * const handler = async (payload, signal) => {
+     *   await db.query(payload); // 'db' is captured from closure
+     * };
+     *
+     * // ❌ Bad - uses 'this' context
+     * class MyHandler {
+     *   async handle(payload, signal) {
+     *     await this.doSomething(payload); // 'this' won't work
+     *   }
+     * }
+     * ```
+     *
+     * If your handler doesn't meet these requirements, use `forceKillOnTimeout: false` (default)
+     * and ensure your handler checks `signal.aborted` to exit gracefully.
+     *
+     * Note: forceKillOnTimeout requires timeoutMs to be set.
+     */
+    forceKillOnTimeout?: boolean;
     /**
      * Tags for this job. Used for grouping, searching, or batch operations.
      */
     tags?: string[];
 }
+/**
+ * Options for editing a pending job.
+ * All fields are optional and only provided fields will be updated.
+ * Note: jobType cannot be changed.
+ * timeoutMs and tags can be set to null to clear them.
+ */
+type EditJobOptions<PayloadMap, T extends JobType<PayloadMap>> = Partial<Omit<JobOptions<PayloadMap, T>, 'jobType'>> & {
+    timeoutMs?: number | null;
+    tags?: string[] | null;
+};
 declare enum JobEventType {
     Added = "added",
     Processing = "processing",
     Completed = "completed",
     Failed = "failed",
     Cancelled = "cancelled",
-    Retried = "retried"
+    Retried = "retried",
+    Edited = "edited"
 }
 interface JobEvent {
     id: number;
@@ -60,6 +117,11 @@ interface JobRecord<PayloadMap, T extends JobType<PayloadMap>> {
      * Timeout for this job in milliseconds (null means no timeout).
      */
     timeoutMs?: number | null;
+    /**
+     * If true, the job will be forcefully terminated (using Worker Threads) when timeout is reached.
+     * If false (default), the job will only receive an AbortSignal and must handle the abort gracefully.
+     */
+    forceKillOnTimeout?: boolean | null;
     /**
      * The reason for the last failure, if any.
      */
@@ -242,6 +304,42 @@ interface JobQueue<PayloadMap> {
      * - This will set the job status to 'cancelled' and clear the locked_at and locked_by.
      */
     cancelJob: (jobId: number) => Promise<void>;
+    /**
+     * Edit a pending job given its ID.
+     * - Only works for jobs with status 'pending'. Silently fails for other statuses.
+     * - All fields in EditJobOptions are optional - only provided fields will be updated.
+     * - jobType cannot be changed.
+     * - Records an 'edited' event with the updated fields in metadata.
+     */
+    editJob: <T extends JobType<PayloadMap>>(jobId: number, updates: EditJobOptions<PayloadMap, T>) => Promise<void>;
+    /**
+     * Edit all pending jobs that match the filters.
+     * - Only works for jobs with status 'pending'. Non-pending jobs are not affected.
+     * - All fields in EditJobOptions are optional - only provided fields will be updated.
+     * - jobType cannot be changed.
+     * - Records an 'edited' event with the updated fields in metadata for each affected job.
+     * - Returns the number of jobs that were edited.
+     * - The filters are:
+     *   - jobType: The job type to edit.
+     *   - priority: The priority of the job to edit.
+     *   - runAt: The time the job is scheduled to run at (now supports gt/gte/lt/lte/eq).
+     *   - tags: An object with 'values' (string[]) and 'mode' (TagQueryMode) for tag-based editing.
+     */
+    editAllPendingJobs: <T extends JobType<PayloadMap>>(filters: {
+        jobType?: string;
+        priority?: number;
+        runAt?: Date | {
+            gt?: Date;
+            gte?: Date;
+            lt?: Date;
+            lte?: Date;
+            eq?: Date;
+        };
+        tags?: {
+            values: string[];
+            mode?: TagQueryMode;
+        };
+    } | undefined, updates: EditJobOptions<PayloadMap, T>) => Promise<number>;
     /**
      * Reclaim stuck jobs.
      * - If a process (e.g., API route or worker) crashes after marking a job as 'processing' but before completing it, the job can remain stuck in the 'processing' state indefinitely. This can happen if the process is killed or encounters an unhandled error after updating the job status but before marking it as 'completed' or 'failed'.
@@ -288,9 +386,60 @@ interface JobQueue<PayloadMap> {
     getPool: () => Pool;
 }
 
+/**
+ * Validates that a job handler can be serialized for use with forceKillOnTimeout.
+ *
+ * This function checks if a handler can be safely serialized and executed in a worker thread.
+ * Use this function during development to catch serialization issues early.
+ *
+ * @param handler - The job handler function to validate
+ * @param jobType - Optional job type name for better error messages
+ * @returns An object with `isSerializable` boolean and optional `error` message
+ *
+ * @example
+ * ```ts
+ * const handler = async (payload, signal) => {
+ *   await doSomething(payload);
+ * };
+ *
+ * const result = validateHandlerSerializable(handler, 'myJob');
+ * if (!result.isSerializable) {
+ *   console.error('Handler is not serializable:', result.error);
+ * }
+ * ```
+ */
+declare function validateHandlerSerializable<PayloadMap, T extends keyof PayloadMap & string>(handler: JobHandler<PayloadMap, T>, jobType?: string): {
+    isSerializable: boolean;
+    error?: string;
+};
+/**
+ * Test if a handler can be serialized and executed in a worker thread.
+ * This is a more thorough check that actually attempts to serialize and deserialize the handler.
+ *
+ * @param handler - The job handler function to test
+ * @param jobType - Optional job type name for better error messages
+ * @returns Promise that resolves to validation result
+ *
+ * @example
+ * ```ts
+ * const handler = async (payload, signal) => {
+ *   await doSomething(payload);
+ * };
+ *
+ * const result = await testHandlerSerialization(handler, 'myJob');
+ * if (!result.isSerializable) {
+ *   console.error('Handler failed serialization test:', result.error);
+ * }
+ * ```
+ */
+declare function testHandlerSerialization<PayloadMap, T extends keyof PayloadMap & string>(handler: JobHandler<PayloadMap, T>, jobType?: string): Promise<{
+    isSerializable: boolean;
+    error?: string;
+}>;
+
 /**
  * Initialize the job queue system
  */
 declare const initJobQueue: <PayloadMap = any>(config: JobQueueConfig) => JobQueue<PayloadMap>;
 
-export { type DatabaseSSLConfig, FailureReason, type JobEvent, JobEventType, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobRecord, type JobStatus, type JobType, type Processor, type ProcessorOptions, type TagQueryMode, initJobQueue };
+export { type DatabaseSSLConfig, type EditJobOptions, FailureReason, type JobEvent, JobEventType, type JobHandler, type JobHandlers, type JobOptions, type JobQueue, type JobQueueConfig, type JobRecord, type JobStatus, type JobType, type Processor, type ProcessorOptions, type TagQueryMode, initJobQueue, testHandlerSerialization, validateHandlerSerializable };