@tstdl/base 0.93.141 → 0.93.142

package/task-queue/task-queue.js

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
 var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
     if (value !== null && value !== void 0) {
         if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
@@ -55,30 +56,53 @@ import { inject, injectArgument, Injector } from '../injector/index.js';
 import { Logger } from '../logger/logger.js';
 import { Transactional } from '../orm/server/transactional.js';
 import { currentTimestamp } from '../utils/date-time.js';
-import { cancelableTimeout } from '../utils/timing.js';
-import { isDefined, isString, isUndefined } from '../utils/type-guards.js';
+import { isDefined, isError, isString } from '../utils/type-guards.js';
 import { millisecondsPerDay, millisecondsPerMinute, millisecondsPerSecond } from '../utils/units.js';
 import { TaskQueueEnqueueBatch } from './enqueue-batch.js';
 import { TaskContext } from './task-context.js';
+/**
+ * Represents the result of processing a task.
+ * @template Result The type of the result data.
+ */
 export class TaskProcessResult {
     payload;
     constructor(payload) {
         this.payload = payload;
     }
+    /**
+     * Creates a successful process result.
+     * @param result The optional result data.
+     */
     static Complete(result) {
         return new TaskProcessResult({ action: 'complete', result });
     }
+    /**
+     * Creates a failed process result.
+     * @param error The error that occurred.
+     * @param fatal Whether the error is fatal and the task should not be retried.
+     */
     static Fail(error, fatal = false) {
         return new TaskProcessResult({ action: 'fail', error, fatal });
     }
+    /**
+     * Creates a result that reschedules the task to a specific timestamp.
+     * @param timestamp The timestamp to reschedule to.
+     */
     static RescheduleTo(timestamp) {
         return new TaskProcessResult({ action: 'reschedule', timestamp });
     }
+    /**
+     * Creates a result that reschedules the task by a specific number of milliseconds.
+     * @param milliseconds The number of milliseconds to reschedule by.
+     */
     static RescheduleBy(milliseconds) {
         const timestamp = currentTimestamp() + milliseconds;
         return this.RescheduleTo(timestamp);
     }
 }
+/**
+ * Represents the status of a task in the queue.
+ */
 export const TaskStatus = defineEnum('TaskStatus', {
     /**
      * The task is ready to be processed and is waiting for a worker.
@@ -112,18 +136,51 @@ export const TaskStatus = defineEnum('TaskStatus', {
      * The task has been manually paused and will not be dequeued until resumed.
      */
     Paused: 'paused',
+    /**
+     * The task has failed but has remaining attempts and is waiting for its next scheduled attempt.
+     */
+    Retrying: 'retrying',
+    /**
+     * The task was forcefully terminated because its execution time exceeded maxExecutionTime.
+     */
+    TimedOut: 'timed-out',
+    /**
+     * The task expired in the queue before it could be picked up by a worker.
+     */
+    Expired: 'expired',
+    /**
+     * The task was never attempted because one of its prerequisites failed or was cancelled.
+     */
+    Skipped: 'skipped',
+    /**
+     * The task was abandoned by a worker and has exhausted all retry attempts.
+     */
+    Orphaned: 'orphaned',
 });
+/**
+ * Represents the type of dependency between tasks.
+ */
 export const TaskDependencyType = defineEnum('TaskDependencyType', {
+    /**
+     * The task should only be scheduled after the dependency has reached a specific status.
+     */
     Schedule: 'schedule',
+    /**
+     * The task is only considered complete after the dependency has reached a specific status.
+     */
     Complete: 'complete',
+    /**
+     * The task is only considered complete after the child task has reached a specific status.
+     */
+    Child: 'child',
 });
+/** Default priority for tasks. */
 export const defaultTaskPriority = 1000;
 export const defaultQueueConfig = {
     visibilityTimeout: millisecondsPerMinute * 5,
     maxExecutionTime: millisecondsPerMinute * 60,
     maxTries: 3,
     retention: 30 * millisecondsPerDay,
-    globalConcurrency: null,
     circuitBreakerThreshold: 5,
     circuitBreakerResetTimeout: 30 * millisecondsPerSecond,
     retryDelayMinimum: 5 * millisecondsPerSecond,
@@ -137,15 +194,30 @@ export const defaultQueueConfig = {
     rateInterval: 1000,
     idempotencyWindow: millisecondsPerMinute * 60,
 };
+/**
+ * Abstract base class for task queues.
+ * @template Definitions The type map of task definitions.
+ */
 export class TaskQueue extends Transactional {
+    #activeTasks = new Map();
+    #heartbeatLoopRunning = false;
     injector = inject(Injector);
     config = this.transactionalContextData ?? (() => { const arg = injectArgument(this); return isString(arg) ? { namespace: arg } : arg; })();
     logger = inject(Logger, TaskQueue.name).with({ namespace: this.config.namespace });
+    get namespace() {
+        return this.config.namespace;
+    }
+    /**
+     * Starts a new batch operation for enqueuing multiple tasks.
+     * @returns A TaskQueueEnqueueBatch instance.
+     */
     batch() {
         return new TaskQueueEnqueueBatch(this);
     }
     /**
-     * Starts processing tasks with the provided worker function in the background until the cancellation signal is triggered.
+     * Starts processing tasks with the provided worker function.
+     * @param options Concurrency, cancellation signal, task types, and forceDequeue flag.
+     * @param handler The worker function to process tasks.
      */
     process({ concurrency = 1, cancellationSignal, types, forceDequeue }, handler) {
         const promises = [];
@@ -159,7 +231,10 @@ export class TaskQueue extends Transactional {
         return this.config;
     }
     /**
-     * Starts processing tasks with the provided worker function in the foreground until the cancellation signal is triggered.
+     * Internal method to process tasks using a worker function.
+     * @param cancellationSignal A signal to stop processing tasks.
+     * @param handler The worker function.
+     * @param options Dequeue options.
      */
     async processWorker(cancellationSignal, handler, options) {
         for await (const task of this.getConsumer(cancellationSignal, options)) {
@@ -167,54 +242,50 @@ export class TaskQueue extends Transactional {
             try {
                 const taskToken = __addDisposableResource(env_1, cancellationSignal.fork(), false);
                 const context = new TaskContext(this, task, taskToken, this.logger.with({ type: task.type }));
-                let isTaskActive = true;
-                context.logger.verbose(`Processing task`);
-                void (async () => {
-                    while (taskToken.isUnset) {
-                        await cancelableTimeout(Math.min(this.visibilityTimeout / 2, 5000), taskToken);
-                        if (taskToken.isSet) {
-                            break;
-                        }
-                        try {
-                            const touchedTask = await this.touch(task);
-                            if (isUndefined(touchedTask) && taskToken.isUnset) {
-                                context.logger.warn(`Task lost lease. Aborting.`);
-                                isTaskActive = false;
-                                taskToken.set();
-                            }
-                        }
-                        catch (error) {
-                            context.logger.error('Error touching task', error);
-                        }
-                    }
-                })();
+                const isTaskActiveObj = { value: true };
+                this.#activeTasks.set(task.id, {
+                    task: task,
+                    taskToken,
+                    logger: context.logger,
+                    isTaskActive: isTaskActiveObj,
+                });
+                if (!this.#heartbeatLoopRunning) {
+                    void this.#runHeartbeatLoop();
+                }
+                context.logger.verbose('Processing task');
                 try {
                     if (taskToken.isSet) {
                         throw new Error('Task cancelled before start');
                     }
                     const result = await handler(context);
-                    if (isDefined(result) && isTaskActive) {
+                    if (isDefined(result) && isTaskActiveObj.value) {
                         switch (result.payload.action) {
                             case 'complete':
-                                context.logger.verbose(`Completing task`);
+                                context.logger.verbose('Completing task');
                                 await this.complete(task, { result: result.payload.result });
                                 break;
                             case 'fail':
-                                context.logger.verbose(`Failing task`);
+                                context.logger.verbose('Failing task');
                                 await this.fail(task, result.payload.error, { fatal: result.payload.fatal });
                                 break;
                             case 'reschedule':
-                                context.logger.verbose(`Rescheduling task`);
+                                context.logger.verbose('Rescheduling task');
                                 await this.reschedule(task.id, result.payload.timestamp);
                                 break;
                             default:
-                                throw new Error(`Unsupported task result action.`);
+                                throw new Error('Unsupported task result action.');
                         }
                     }
                 }
                 catch (error) {
                     context.logger.error('Error processing task', error);
                     await this.fail(task, error);
+                    if (isError(error) && ((error.message === 'Task cancelled before start') || (error.message == 'Unsupported task result action.'))) {
+                        throw error;
+                    }
+                }
+                finally {
+                    this.#activeTasks.delete(task.id);
                 }
             }
             catch (e_1) {
@@ -226,4 +297,37 @@ export class TaskQueue extends Transactional {
             }
         }
     }
+    async #runHeartbeatLoop() {
+        if (this.#heartbeatLoopRunning) {
+            return;
+        }
+        this.#heartbeatLoopRunning = true;
+        try {
+            while (this.#activeTasks.size > 0) {
+                await new Promise((resolve) => setTimeout(resolve, Math.min(this.visibilityTimeout / 2, 5000)));
+                if (this.#activeTasks.size === 0) {
+                    break;
+                }
+                const entries = Array.from(this.#activeTasks.values());
+                const tasks = entries.map((e) => e.task);
+                try {
+                    const touchedIds = await this.touchMany(tasks);
+                    const touchedSet = new Set(touchedIds);
+                    for (const entry of entries) {
+                        if (entry.taskToken.isUnset && !touchedSet.has(entry.task.id)) {
+                            entry.logger.warn(`Task lost lease. Aborting.`);
+                            entry.isTaskActive.value = false;
+                            entry.taskToken.set();
+                        }
+                    }
+                }
+                catch (error) {
+                    this.logger.error('Error touching tasks', error);
+                }
+            }
+        }
+        finally {
+            this.#heartbeatLoopRunning = false;
+        }
+    }
 }

package/task-queue/tests/coverage-branch.test.js

@@ -17,7 +17,7 @@ describe('Task Queue Branch Coverage Enhancement', () => {
     });
     beforeEach(() => {
         const queueProvider = injector.resolve(TaskQueueProvider);
-        const queueName = `branch-coverage-queue-${Date.now()}-${Math.random()}`;
+        const queueName = `branch-coverage-queue-${crypto.randomUUID()}`;
         queue = queueProvider.get(queueName, {
             visibilityTimeout: 200,
         });
@@ -33,9 +33,7 @@ describe('Task Queue Branch Coverage Enhancement', () => {
     it('should handle TaskProcessResult.RescheduleTo in worker', async () => {
         const task = await queue.enqueue('reschedule-test', {});
         const future = currentTimestamp() + 5000;
-        queue.process({ cancellationSignal: token }, async () => {
-            return TaskProcessResult.RescheduleTo(future);
-        });
+        queue.process({ cancellationSignal: token }, () => TaskProcessResult.RescheduleTo(future));
         await timeout(500);
         token.set();
         const updated = await queue.getTask(task.id);
@@ -44,9 +42,7 @@ describe('Task Queue Branch Coverage Enhancement', () => {
     });
     it('should handle TaskProcessResult.Fail(fatal: true) in worker', async () => {
         const task = await queue.enqueue('fail-fatal-test', {});
-        queue.process({ cancellationSignal: token }, async () => {
-            return TaskProcessResult.Fail(new Error('fatal error'), true);
-        });
+        queue.process({ cancellationSignal: token }, () => TaskProcessResult.Fail(new Error('fatal error'), true));
         await timeout(500);
         token.set();
         const updated = await queue.getTask(task.id);
@@ -54,15 +50,15 @@ describe('Task Queue Branch Coverage Enhancement', () => {
     });
     it('should handle errors in touch during background lease extension', async () => {
         const task = await queue.enqueue('touch-error-test', {});
-        // Mock touch to throw once
-        const originalTouch = queue.touch.bind(queue);
+        // Mock touchMany to throw once
+        const originalTouchMany = queue.touchMany.bind(queue);
         let thrown = false;
-        vi.spyOn(queue, 'touch').mockImplementation(async (t, o) => {
+        vi.spyOn(queue, 'touchMany').mockImplementation(async (t, o) => {
             if (!thrown) {
                 thrown = true;
                 throw new Error('touch error');
             }
-            return originalTouch(t, o);
+            return originalTouchMany(t, o);
         });
         queue.process({ cancellationSignal: token }, async () => {
             await timeout(300); // Wait for background touch to trigger
@@ -78,8 +74,8 @@ describe('Task Queue Branch Coverage Enhancement', () => {
         // visibilityTimeout is 200ms. Background touch is every 100ms.
         const task = await queue.enqueue('lease-loss-test', {});
         let workerFinished = false;
-        // Mock touch to return undefined (stolen/lost)
-        vi.spyOn(queue, 'touch').mockResolvedValue(undefined);
+        // Mock touchMany to return empty array (stolen/lost)
+        vi.spyOn(queue, 'touchMany').mockResolvedValue([]);
         queue.process({ cancellationSignal: token }, async (context) => {
             // Wait for background touch to discover lease loss
             for (let i = 0; i < 20; i++) {
@@ -113,7 +109,10 @@ describe('Task Queue Branch Coverage Enhancement', () => {
         expect(d2?.type).toBe('type1');
     });
     it('should handle maintenance when no tasks need maintenance', async () => {
-        await expect(queue.maintenance()).resolves.toBeUndefined();
+        await queue.enqueue('t1', {});
+        await queue.maintenance();
+        const count = await queue.count({ status: TaskStatus.Pending });
+        expect(count).toBe(1);
     });
     it('should handle multiple workers competing for tasks', async () => {
         await queue.enqueue('compete', {});
@@ -143,36 +142,30 @@ describe('Task Queue Branch Coverage Enhancement', () => {
         expect(result).toBeUndefined();
     });
     it('should handle complete with non-existent task', async () => {
-        const fakeTask = { id: '00000000-0000-0000-0000-000000000000', token: '00000000-0000-0000-0000-000000000000' };
-        // Should not throw
+        const fakeTask = { id: crypto.randomUUID(), token: crypto.randomUUID() };
+        // Should not throw and should not affect existing tasks
+        await queue.enqueue('t1', {});
         await queue.complete(fakeTask);
+        const count = await queue.count();
+        expect(count).toBe(1);
     });
     it('should handle dequeueMany with forceDequeue', async () => {
         await queue.enqueue('force', {});
         const tasks = await queue.dequeueMany(1, { forceDequeue: true });
         expect(tasks).toHaveLength(1);
-    });
-    it('should handle dequeueMany with globalConcurrency limit', async () => {
-        const limitedQueue = injector.resolve(TaskQueueProvider).get(`limited-${Date.now()}`, { globalConcurrency: 1 });
-        await limitedQueue.enqueue('t1', {});
-        await limitedQueue.enqueue('t2', {});
-        const d1 = await limitedQueue.dequeue();
-        expect(d1).toBeDefined();
-        const d2 = await limitedQueue.dequeue();
-        expect(d2).toBeUndefined(); // Limited by globalConcurrency
-    });
-    it('should handle waitForTasks timeout', async () => {
-        const task = await queue.enqueue('wait-timeout', {});
-        await expect(queue.waitForTasks([task.id], { timeout: 100, interval: 50 })).rejects.toThrow('Timeout');
+        expect(tasks[0]?.status).toBe(TaskStatus.Running);
     });
     it('should handle cancelMany with empty ids', async () => {
-        // Should not throw
+        await queue.enqueue('t1', {});
         await queue.cancelMany([]);
+        const count = await queue.count({ status: TaskStatus.Pending });
+        expect(count).toBe(1);
     });
     it('should handle touch with progress and state', async () => {
         const task = await queue.enqueue('touch-data', {});
         const dequeued = await queue.dequeue();
-        await queue.touch(dequeued, { progress: 0.7, state: { ok: true } });
+        const result = await queue.touch(dequeued, { progress: 0.7, state: { ok: true } });
+        expect(result).toBeDefined();
         const updated = await queue.getTask(task.id);
         expect(updated?.progress).toBe(0.7);
         expect(updated?.state).toEqual({ ok: true });
@@ -193,20 +186,8 @@ describe('Task Queue Branch Coverage Enhancement', () => {
         expect(dependent.status).toBe(TaskStatus.Pending); // Because scheduleAfterCount is 0
         expect(dependent.unresolvedCompleteDependencies).toBe(1);
     });
-    it('should handle maintenance recovering zombie tasks', async () => {
-        const isolatedQueue = injector.resolve(TaskQueueProvider).get(`zombie-${Date.now()}`, { visibilityTimeout: 100 });
-        await isolatedQueue.enqueue('z', {});
-        const d1 = await isolatedQueue.dequeue();
-        expect(d1).toBeDefined();
-        // Wait for visibility timeout to expire
-        await timeout(200);
-        await isolatedQueue.maintenance();
-        const updated = await isolatedQueue.getTask(d1.id);
-        expect(updated?.status).toBe(TaskStatus.Pending);
-        expect(updated?.token).toBeNull();
-    });
     it('should handle getTask including archived tasks', async () => {
-        const archQueue = injector.resolve(TaskQueueProvider).get(`arch-${Date.now()}`, { retention: 0, archiveRetention: 3600000 });
+        const archQueue = injector.resolve(TaskQueueProvider).get(`arch-${crypto.randomUUID()}`, { retention: 0, archiveRetention: 3600000 });
         const t = await archQueue.enqueue('t', {});
         const d = await archQueue.dequeue();
         await archQueue.complete(d);
@@ -217,17 +198,20 @@ describe('Task Queue Branch Coverage Enhancement', () => {
         expect(archived?.id).toBe(t.id);
     });
     it('should handle maintenance with no work to do', async () => {
-        await queue.maintenance(); // Should not throw
+        await queue.enqueue('t1', {});
+        await queue.maintenance();
+        const count = await queue.count({ status: TaskStatus.Pending });
+        expect(count).toBe(1);
     });
     it('should handle task TTL failure in maintenance', async () => {
         // retention=0 to allow maintenance to process immediately
-        const ttlQueue = injector.resolve(TaskQueueProvider).get(`ttl-${Date.now()}`, { retention: 0 });
+        const ttlQueue = injector.resolve(TaskQueueProvider).get(`ttl-${crypto.randomUUID()}`, { retention: 0 });
         // Enqueue with TTL in the past
         const task = await ttlQueue.enqueue('ttl-fail', {}, { timeToLive: currentTimestamp() - 1000 });
         await timeout(100);
         await ttlQueue.maintenance();
         const updated = await ttlQueue.getTask(task.id);
-        expect(updated?.status).toBe(TaskStatus.Dead);
+        expect(updated?.status).toBe(TaskStatus.Expired);
         expect(updated?.error?.message).toContain('Task expired');
     });
     it('should handle cancelMany with multiple valid IDs', async () => {
@@ -241,7 +225,7 @@ describe('Task Queue Branch Coverage Enhancement', () => {
     });
     it('should handle pruning long expired tasks', async () => {
         // archiveRetention = 0
-        const pruneQueue = injector.resolve(TaskQueueProvider).get(`prune-long-${Date.now()}`, { retention: 0, archiveRetention: 0 });
+        const pruneQueue = injector.resolve(TaskQueueProvider).get(`prune-long-${crypto.randomUUID()}`, { retention: 0, archiveRetention: 0 });
         const task = await pruneQueue.enqueue('p1', {});
         const d1 = await pruneQueue.dequeue();
         await pruneQueue.complete(d1);
@@ -279,7 +263,7 @@ describe('Task Queue Branch Coverage Enhancement', () => {
         expect(tasks).toHaveLength(1);
     });
     it('should handle CircuitBreaker Half-Open state in dequeue', async () => {
-        const namespace = `cb-half-${Date.now()}`;
+        const namespace = `cb-half-${crypto.randomUUID()}`;
         const cbQueue = injector.resolve(TaskQueueProvider).get(namespace, { circuitBreakerThreshold: 1 });
         const cb = injector.resolve(CircuitBreaker, namespace);
         // Mock CB to be Half-Open
@@ -289,7 +273,7 @@ describe('Task Queue Branch Coverage Enhancement', () => {
         expect(tasks).toBeDefined();
     });
     it('should handle CircuitBreaker Half-Open state blocking when already probing', async () => {
-        const namespace = `cb-block-${Date.now()}`;
+        const namespace = `cb-block-${crypto.randomUUID()}`;
         const cbQueue = injector.resolve(TaskQueueProvider).get(namespace, { circuitBreakerThreshold: 1 });
         const cb = injector.resolve(CircuitBreaker, namespace);
         // Mock CB to be Half-Open but NOT a probe (already probing)
@@ -313,28 +297,32 @@ describe('Task Queue Branch Coverage Enhancement', () => {
         expect(updated?.status).toBe(TaskStatus.WaitingChildren);
     });
     it('should handle maintenance recovering zombie tasks via touchMany logic in prune', async () => {
-        const pruneQueue = injector.resolve(TaskQueueProvider).get(`prune-fail-${Date.now()}`, { maxExecutionTime: 50, retention: 0 });
+        const pruneQueue = injector.resolve(TaskQueueProvider).get(`prune-fail-${crypto.randomUUID()}`, { maxExecutionTime: 50, retention: 0 });
         const task = await pruneQueue.enqueue('p1', {});
         await pruneQueue.dequeue();
         await timeout(100);
         await pruneQueue.maintenance();
         const updated = await pruneQueue.getTask(task.id);
-        expect(updated?.status).toBe(TaskStatus.Dead);
+        expect(updated?.status).toBe(TaskStatus.TimedOut);
     });
     it('should handle enqueueMany with parentId and waitForCompletion false', async () => {
         const parent = await queue.enqueue('p', {});
-        await queue.enqueueMany([{ type: 'child', data: {}, parentId: parent.id, waitForCompletion: false }]);
+        const tasks = await queue.enqueueMany([{ type: 'child', data: {}, parentId: parent.id, waitForCompletion: false }], { returnTasks: true });
+        expect(tasks).toHaveLength(1);
+        expect(tasks[0]?.parentId).toBe(parent.id);
+        const updatedParent = await queue.getTask(parent.id);
+        expect(updatedParent?.unresolvedCompleteDependencies).toBe(0);
     });
     it('should handle failMany for running tasks', async () => {
         const t1 = await queue.enqueue('t1', {});
         const d1 = await queue.dequeue();
         await queue.failMany([d1], [new Error('fail')]);
         const updated = await queue.getTask(t1.id);
-        expect(updated?.status).toBe(TaskStatus.Pending);
+        expect(updated?.status).toBe(TaskStatus.Retrying);
         expect(updated?.tries).toBe(1);
     });
     it('should handle failMany reaching max tries (Dead state)', async () => {
-        const isolatedQueue = injector.resolve(TaskQueueProvider).get(`exhaust-${Date.now()}`, { maxTries: 1 });
+        const isolatedQueue = injector.resolve(TaskQueueProvider).get(`exhaust-${crypto.randomUUID()}`, { maxTries: 1 });
         const t1 = await isolatedQueue.enqueue('t1', {});
         const d1 = await isolatedQueue.dequeue();
         await isolatedQueue.failMany([d1], [new Error('fatal')]);
@@ -390,7 +378,7 @@ describe('Task Queue Branch Coverage Enhancement', () => {
         expect(result).toHaveLength(0);
     });
     it('should handle large batch maintenance (> 1000 tasks)', async () => {
-        const namespace = `aging-batch-${Date.now()}`;
+        const namespace = `aging-batch-${crypto.randomUUID()}`;
         const agingQueue = injector.resolve(TaskQueueProvider).get(namespace, { priorityAgingInterval: 60000, priorityAgingStep: 1 });
         const items = Array.from({ length: 1001 }, (_, i) => ({ type: 'batch', data: { i } }));
         await agingQueue.enqueueMany(items);
@@ -401,7 +389,7 @@ describe('Task Queue Branch Coverage Enhancement', () => {
         await agingQueue.maintenance();
     });
     it('should handle maintenance with empty archive and active tables', async () => {
-        const emptyQueue = injector.resolve(TaskQueueProvider).get(`empty-${Date.now()}`, { retention: 0, archiveRetention: 0 });
+        const emptyQueue = injector.resolve(TaskQueueProvider).get(`empty-${crypto.randomUUID()}`, { retention: 0, archiveRetention: 0 });
         await emptyQueue.maintenance();
     });
 });