@tstdl/base 0.93.138 → 0.93.140

package/task-queue/task-queue.d.ts

@@ -175,6 +175,14 @@ export type QueueConfig = {
 export type TaskQueueArgument = string | (QueueConfig & {
     namespace: string;
 });
+export type TaskQueueWaitOptions = {
+    interval?: number;
+    timeout?: number;
+    cancellationSignal?: CancellationSignal;
+};
+export type TaskQueueWaitResult = {
+    cancelled: boolean;
+};
 export declare const defaultQueueConfig: Required<QueueConfig>;
 export declare abstract class TaskQueue<Definitions extends TaskDefinitionMap = TaskDefinitionMap> extends Transactional<QueueConfig & {
     namespace: string;
@@ -211,6 +219,15 @@ export declare abstract class TaskQueue<Definitions extends TaskDefinitionMap =
     abstract getTree(rootId: string | string[], options?: {
         transaction?: Transaction;
     }): Promise<Task[]>;
+    /**
+     * Waits for the specified tasks to reach a finalized state (Completed, Cancelled, or Dead) or be removed/archived from queue (non-existent).
+     * @param ids The IDs of the tasks to wait for.
+     * @param options Timeout and cancellation options.
+     */
+    abstract waitForTasks(ids: string[], options?: {
+        timeout?: number;
+        cancellationSignal?: CancellationSignal;
+    }): Promise<TaskQueueWaitResult>;
     abstract cancel(id: string, options?: {
         transaction?: Transaction;
     }): Promise<void>;

package/task-queue/task-queue.js

@@ -1,3 +1,55 @@
+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.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { defineEnum } from '../enumeration/enumeration.js';
 import { inject, injectArgument, Injector } from '../injector/index.js';
 import { Logger } from '../logger/logger.js';
@@ -103,59 +155,66 @@ export class TaskQueue extends Transactional {
      */
     async processWorker(cancellationSignal, handler, options) {
         for await (const task of this.getConsumer(cancellationSignal, options)) {
-            const taskToken = cancellationSignal.createChild();
-            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);
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            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);
+                        }
+                    }
+                })();
+                try {
                     if (taskToken.isSet) {
-                        break;
+                        throw new Error('Task cancelled before start');
                     }
-                    try {
-                        const touchedTask = await this.touch(task);
-                        if (isUndefined(touchedTask) && taskToken.isUnset) {
-                            context.logger.warn(`Task lost lease. Aborting.`);
-                            isTaskActive = false;
-                            taskToken.set();
+                    const result = await handler(context);
+                    if (isDefined(result) && isTaskActive) {
+                        switch (result.payload.action) {
+                            case 'complete':
+                                context.logger.verbose(`Completing task`);
+                                await this.complete(task, { result: result.payload.result });
+                                break;
+                            case 'fail':
+                                context.logger.verbose(`Failing task`);
+                                await this.fail(task, result.payload.error, { fatal: result.payload.fatal });
+                                break;
+                            case 'reschedule':
+                                context.logger.verbose(`Rescheduling task`);
+                                await this.reschedule(task.id, result.payload.timestamp);
+                                break;
+                            default:
+                                throw new Error(`Unsupported task result action.`);
                         }
                     }
-                    catch (error) {
-                        context.logger.error('Error touching task', error);
-                    }
                 }
-            })();
-            try {
-                if (taskToken.isSet) {
-                    throw new Error('Task cancelled before start');
-                }
-                const result = await handler(context);
-                if (isDefined(result) && isTaskActive) {
-                    switch (result.payload.action) {
-                        case 'complete':
-                            context.logger.verbose(`Completing task`);
-                            await this.complete(task, { result: result.payload.result });
-                            break;
-                        case 'fail':
-                            context.logger.verbose(`Failing task`);
-                            await this.fail(task, result.payload.error, { fatal: result.payload.fatal });
-                            break;
-                        case 'reschedule':
-                            context.logger.verbose(`Rescheduling task`);
-                            await this.reschedule(task.id, result.payload.timestamp);
-                            break;
-                        default:
-                            throw new Error(`Unsupported task result action.`);
-                    }
+                catch (error) {
+                    context.logger.error('Error processing task', error);
+                    await this.fail(task, error);
                 }
             }
-            catch (error) {
-                context.logger.error('Error processing task', error);
-                await this.fail(task, error);
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
             }
             finally {
-                taskToken.set();
+                __disposeResources(env_1);
             }
         }
     }

package/task-queue/tests/complex.test.js

@@ -18,7 +18,7 @@ describe('Complex Queue Scenarios', () => {
             priorityAgingInterval: 50, // Fast aging
             priorityAgingStep: 10,
             rateLimit: 5,
-            rateInterval: 50,
+            rateInterval: 200,
             retryDelayMinimum: 50,
             retryDelayGrowth: 2,
             retention: 50, // Fast retention for archive test
@@ -143,7 +143,7 @@ describe('Complex Queue Scenarios', () => {
             const batch2 = await queue.dequeueMany(1);
             expect(batch2.length).toBe(0); // Rate limited
             // Wait for refill
-            await timeout(60);
+            await timeout(300);
             const batch3 = await queue.dequeueMany(5);
             expect(batch3.length).toBe(5); // Refilled
         });
@@ -153,7 +153,7 @@ describe('Complex Queue Scenarios', () => {
             await limitQueue.enqueueMany([
                 { type: 'c', data: {} },
                 { type: 'c', data: {} },
-                { type: 'c', data: {} }
+                { type: 'c', data: {} },
             ]);
             const t1 = await limitQueue.dequeue();
             const t2 = await limitQueue.dequeue();
@@ -290,7 +290,7 @@ describe('Complex Queue Scenarios', () => {
         it('should handle mixed AND/OR dependencies', async () => {
             const dep = await queue.enqueue('dep', {}, {
                 scheduleAfterTags: ['A', 'B'],
-                dependencyJoinMode: DependencyJoinMode.Or
+                dependencyJoinMode: DependencyJoinMode.Or,
             });
             const A = await queue.enqueue('A', {}, { tags: ['A'] });
             await queue.complete((await queue.dequeue({ types: ['A'] })));

package/task-queue/tests/dependencies.test.js

@@ -45,7 +45,8 @@ describe('Queue Dependencies & Tree Tests', () => {
             const dequeued = await queue.dequeue({ types: ['prereq'] });
             expect(dequeued?.id).toBe(prereq.id);
             await queue.complete(dequeued);
-            await waitForStatus(dependent.id, TaskStatus.Completed);
+            await queue.processPendingFanIn();
+            await queue.waitForTasks([dependent.id]);
             const updatedDependent = await queue.getTask(dependent.id);
             expect(updatedDependent?.status).toBe(TaskStatus.Completed);
         });
@@ -77,7 +78,8 @@ describe('Queue Dependencies & Tree Tests', () => {
             const dequeued = await queue.dequeue({ types: ['prereq'] });
             // Fail fatally
             await queue.fail(dequeued, new Error('boom'), { fatal: true });
-            await waitForStatus(dependent.id, TaskStatus.Dead);
+            await queue.processPendingFanIn();
+            await queue.waitForTasks([dependent.id]);
             const updatedDependent = await queue.getTask(dependent.id);
             expect(updatedDependent?.status).toBe(TaskStatus.Dead);
             expect(updatedDependent?.error?.code).toBe('DependencyFailed');

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

@@ -1,7 +1,9 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { CancellationToken } from '../../cancellation/index.js';
 import { TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
 import { setupIntegrationTest } from '../../testing/index.js';
 import { currentTimestamp } from '../../utils/date-time.js';
+import { Timer } from '../../utils/timer.js';
 import { timeout } from '../../utils/timing.js';
 describe('Queue Integration Tests', () => {
     let injector;
@@ -331,4 +333,113 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             expect(updated?.state).toEqual({ step: 1 });
         });
     });
+    describe('waitForTasks', () => {
+        it('should wait for multiple tasks to reach finalized state', async () => {
+            const t1 = await queue.enqueue('foo', { foo: 'wait-1' });
+            const t2 = await queue.enqueue('foo', { foo: 'wait-2' });
+            void (async () => {
+                await timeout(100);
+                const d1 = await queue.dequeue();
+                await queue.complete(d1);
+                await timeout(100);
+                const d2 = await queue.dequeue();
+                await queue.complete(d2);
+            })();
+            const result = await queue.waitForTasks([t1.id, t2.id], { timeout: 2000 });
+            expect(result.cancelled).toBe(false);
+            const check1 = await queue.getTask(t1.id);
+            const check2 = await queue.getTask(t2.id);
+            expect(check1?.status).toBe(TaskStatus.Completed);
+            expect(check2?.status).toBe(TaskStatus.Completed);
+        });
+        it('should throw TimeoutError on timeout', async () => {
+            const t1 = await queue.enqueue('foo', { foo: 'timeout' });
+            await expect(queue.waitForTasks([t1.id], { timeout: 100 })).rejects.toThrow('Timeout while waiting for tasks to complete');
+        });
+        it('should wait for Cancelled and Dead states', async () => {
+            const t1 = await queue.enqueue('foo', { foo: 'cancel' });
+            const t2 = await queue.enqueue('foo', { foo: 'dead' });
+            void (async () => {
+                await timeout(50);
+                const d1 = await queue.dequeue();
+                if (d1)
+                    await queue.cancel(d1.id);
+                const d2 = await queue.dequeue();
+                if (d2)
+                    await queue.fail(d2, new Error('fatal'), { fatal: true });
+                queue.notify();
+            })();
+            const result = await queue.waitForTasks([t1.id, t2.id], { timeout: 2000 });
+            expect(result.cancelled).toBe(false);
+            const c1 = await queue.getTask(t1.id);
+            const c2 = await queue.getTask(t2.id);
+            expect(c1?.status).toBe(TaskStatus.Cancelled);
+            expect(c2?.status).toBe(TaskStatus.Dead);
+        });
+        it('should handle cancellationSignal', async () => {
+            const t1 = await queue.enqueue('foo', { foo: 'long' });
+            const signal = new CancellationToken();
+            void timeout(100).then(() => signal.set());
+            const result = await queue.waitForTasks([t1.id], { cancellationSignal: signal, timeout: 5000 });
+            expect(result.cancelled).toBe(true);
+        });
+        it('should return immediately for non-existent tasks', async () => {
+            const result = await queue.waitForTasks([crypto.randomUUID()], { timeout: 1000 });
+            expect(result.cancelled).toBe(false);
+        });
+        it('should return immediately if all tasks are already finalized', async () => {
+            const t1 = await queue.enqueue('foo', { foo: 'immediate' });
+            const d1 = await queue.dequeue();
+            await queue.complete(d1);
+            const timer = Timer.startNew();
+            const result = await queue.waitForTasks([t1.id], { timeout: 1000 });
+            expect(result.cancelled).toBe(false);
+            expect(timer.milliseconds).toBeLessThan(100);
+        });
+        it('should handle a mix of active and archived tasks', async () => {
+            const queueProvider = injector.resolve(TaskQueueProvider);
+            const archiveQueue = queueProvider.get(`archive-test-${crypto.randomUUID()}`, {
+                retention: 0, // Archive immediately
+            });
+            const t1 = await archiveQueue.enqueue('foo', { foo: 'archived' });
+            const d1 = await archiveQueue.dequeue();
+            await archiveQueue.complete(d1);
+            // Run maintenance to move to archive
+            await archiveQueue.maintenance();
+            const t2 = await archiveQueue.enqueue('foo', { foo: 'active' });
+            const d2 = await archiveQueue.dequeue();
+            await archiveQueue.complete(d2);
+            // t1 is archived, t2 is completed (active)
+            const result = await archiveQueue.waitForTasks([t1.id, t2.id], { timeout: 1000 });
+            expect(result.cancelled).toBe(false);
+            await archiveQueue.clear();
+        });
+        it('should return immediately for empty ids array', async () => {
+            const result = await queue.waitForTasks([], { timeout: 1000 });
+            expect(result.cancelled).toBe(false);
+        });
+        it('should wait for parent task to reach finalized state after child completion', async () => {
+            const childTag = `child-of-${crypto.randomUUID()}`;
+            const parent = await queue.enqueue('test', { value: 'parent' }, { completeAfterTags: [childTag] });
+            const dParent = await queue.dequeue();
+            // Spawn a child
+            await queue.enqueueMany([{ type: 'test', data: { value: 'child' }, parentId: parent.id, tags: [childTag] }], { transaction: undefined });
+            // Complete parent (it will move to Waiting because of completeAfterTags)
+            await queue.complete(dParent);
+            const checkParent = await queue.getTask(parent.id);
+            expect(checkParent?.status).toBe(TaskStatus.Waiting);
+            void (async () => {
+                await timeout(100);
+                const dChild = await queue.dequeue();
+                if (dChild) {
+                    await queue.complete(dChild);
+                }
+                // Manual fan-in processing since we are in a test environment and might want immediate result
+                await queue.processPendingFanIn();
+            })();
+            await queue.waitForTasks([parent.id], { timeout: 2000 });
+            const finalParent = await queue.getTask(parent.id);
+            expect(finalParent?.status).toBe(TaskStatus.Completed);
+        });
+    });
 });

package/task-queue/tests/worker.test.js

@@ -37,11 +37,12 @@ describe('Worker & Base Class Tests', () => {
         });
         // Wait until 2 tasks are processed
         for (let i = 0; i < 50; i++) {
-            if (processed.length === 2)
+            if (processed.length == 2)
                 break;
             await timeout(20);
         }
         token.set(); // Stop worker
+        await queue.waitForTasks([t1.id, t2.id], { interval: 50, timeout: 1000 });
         expect(processed).toContain(1);
         expect(processed).toContain(2);
         expect(processed.length).toBe(2);
@@ -55,7 +56,14 @@ describe('Worker & Base Class Tests', () => {
         queue.process({ cancellationSignal: token }, async () => {
             throw new Error('worker error');
         });
-        await timeout(50);
+        // Wait until task is processed (error recorded and status is Pending)
+        for (let i = 0; i < 50; i++) {
+            const updated = await queue.getTask(task.id);
+            if (updated?.tries == 1) {
+                break;
+            }
+            await timeout(20);
+        }
         token.set();
         const updated = await queue.getTask(task.id);
         expect(updated?.status).toBe(TaskStatus.Pending); // Should retry
@@ -71,7 +79,7 @@ describe('Worker & Base Class Tests', () => {
             executed = true;
             return TaskProcessResult.Complete();
         });
-        await timeout(500);
+        await queue.waitForTasks([task.id], { timeout: 5000 });
         token.set();
         expect(executed).toBe(true);
         const updated = await queue.getTask(task.id);
@@ -83,17 +91,21 @@ describe('Worker & Base Class Tests', () => {
         const processed = new Set();
         queue.process({ cancellationSignal: token }, async (context) => {
             processed.add(context.id);
-            if (context.id === tFail.id) {
+            if (context.id == tFail.id) {
                 return TaskProcessResult.Fail(new Error('explicit fail'));
             }
-            if (context.id === tResched.id) {
+            if (context.id == tResched.id) {
                 return TaskProcessResult.RescheduleBy(1000);
             }
             return TaskProcessResult.Complete();
         });
+        // Wait until tasks are processed (error/reschedule recorded and status is Pending)
         for (let i = 0; i < 50; i++) {
-            if (processed.size === 2)
+            const uFail = await queue.getTask(tFail.id);
+            const uResched = await queue.getTask(tResched.id);
+            if (uFail?.tries == 1 && uResched?.status == TaskStatus.Pending && (uResched?.scheduleTimestamp ?? 0) > Date.now()) {
                 break;
+            }
             await timeout(20);
         }
         token.set();
@@ -129,11 +141,7 @@ describe('Worker & Base Class Tests', () => {
             executed = true;
             return TaskProcessResult.Complete();
         });
-        for (let i = 0; i < 50; i++) {
-            if (executed)
-                break;
-            await timeout(20);
-        }
+        await queue.waitForTasks([task.id], { interval: 50, timeout: 1000 });
         token.set();
         expect(executed).toBe(true);
     });
@@ -150,13 +158,13 @@ describe('Worker & Base Class Tests', () => {
         const finalAttemptValues = [];
         testQueue.process({ cancellationSignal: token }, async (context) => {
             finalAttemptValues.push(context.isFinalAttempt);
-            if (context.attempt === 1) {
+            if (context.attempt == 1) {
                 throw new Error('fail first attempt');
             }
             return TaskProcessResult.Complete();
         });
         for (let i = 0; i < 100; i++) {
-            if (finalAttemptValues.length === 2)
+            if (finalAttemptValues.length == 2)
                 break;
             testQueue.notify();
             await timeout(20);