@tstdl/base 0.93.87 → 0.93.90

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

@@ -0,0 +1,174 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { CancellationToken } from '../../cancellation/index.js';
+import { DependencyJoinMode, TaskQueueProvider, TaskState } from '../../task-queue/index.js';
+import { setupIntegrationTest } from '../../unit-test/index.js';
+import { timeout } from '../../utils/timing.js';
+describe('Queue Dependencies & Tree Tests', () => {
+    let injector;
+    let queue;
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+    });
+    beforeEach(() => {
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        const queueName = `dep-queue-${Date.now()}-${Math.random()}`;
+        queue = queueProvider.get(queueName, {
+            visibilityTimeout: 1000,
+        });
+    });
+    afterEach(async () => {
+        await queue.clear();
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    describe('Dependencies (Fan-In)', () => {
+        it('should schedule a task only after dependency completes (completeAfterTags)', async () => {
+            // 1. Create a dependent task (Waiting)
+            const dependent = await queue.enqueue('dependent', { foo: 'bar' }, {
+                completeAfterTags: ['tag-a'],
+            });
+            expect(dependent.status).toBe(TaskState.Waiting);
+            // 2. Create the prerequisite task
+            const prereq = await queue.enqueue('prereq', { val: 1 }, { tags: ['tag-a'] });
+            // 3. Complete prereq
+            const dequeued = await queue.dequeue({ types: ['prereq'] });
+            expect(dequeued?.id).toBe(prereq.id);
+            await queue.complete(dequeued);
+            await queue.processPendingFanIn();
+            const updatedDependent = await queue.getTask(dependent.id);
+            expect(updatedDependent?.status).toBe(TaskState.Completed);
+        });
+        it('should schedule a task to run after dependency completes (scheduleAfterTags)', async () => {
+            // 1. Dependent task
+            const dependent = await queue.enqueue('dependent', { foo: 'bar' }, {
+                scheduleAfterTags: ['tag-b'],
+            });
+            expect(dependent.status).toBe(TaskState.Waiting);
+            // 2. Prereq
+            const prereq = await queue.enqueue('prereq', {}, { tags: ['tag-b'] });
+            // 3. Complete prereq
+            const dequeued = await queue.dequeue({ types: ['prereq'] });
+            await queue.complete(dequeued);
+            await queue.processPendingFanIn();
+            // 5. Dependent should be Pending (ready to run)
+            const updatedDependent = await queue.getTask(dependent.id);
+            expect(updatedDependent?.status).toBe(TaskState.Pending);
+            // 6. Should be dequeueable
+            const d2 = await queue.dequeue({ types: ['dependent'] });
+            expect(d2?.id).toBe(dependent.id);
+        });
+        it('should fail-fast if dependency fails', async () => {
+            const dependent = await queue.enqueue('dependent', {}, {
+                scheduleAfterTags: ['tag-fail'],
+                failFast: true
+            });
+            const prereq = await queue.enqueue('prereq', {}, { tags: ['tag-fail'] });
+            const dequeued = await queue.dequeue({ types: ['prereq'] });
+            // Fail fatally
+            await queue.fail(dequeued, new Error('boom'), true);
+            // Trigger resolution
+            await queue.processPendingFanIn();
+            let updatedDependent;
+            for (let i = 0; i < 20; i++) {
+                await timeout(100);
+                updatedDependent = await queue.getTask(dependent.id);
+                if (updatedDependent?.status === TaskState.Dead)
+                    break;
+                await queue.processPendingFanIn(); // Retry processing if it didn't catch it yet
+            }
+            expect(updatedDependent?.status).toBe(TaskState.Dead);
+            expect(updatedDependent?.error?.code).toBe('DependencyFailed');
+        });
+        it('should respect DependencyJoinMode.Or', async () => {
+            // Wait for tag-1 OR tag-2
+            const dependent = await queue.enqueue('dependent', {}, {
+                scheduleAfterTags: ['tag-1', 'tag-2'],
+                dependencyJoinMode: DependencyJoinMode.Or
+            });
+            // Complete tag-1 only
+            await queue.enqueue('t1', {}, { tags: ['tag-1'] });
+            const d1 = await queue.dequeue({ types: ['t1'] });
+            await queue.complete(d1);
+            await queue.processPendingFanIn();
+            const updated = await queue.getTask(dependent.id);
+            expect(updated?.status).toBe(TaskState.Pending);
+        });
+    });
+    describe('Tree Operations & Cancellation', () => {
+        it('should retrieve task tree and cancel hierarchy', async () => {
+            // Root
+            const root = await queue.enqueue('root', {});
+            // Child
+            const child = await queue.enqueue('child', {}, { parentId: root.id });
+            // Grandchild
+            const grandchild = await queue.enqueue('grandchild', {}, { parentId: child.id });
+            // Get Tree
+            const tree = await queue.getTree(root.id);
+            expect(tree.length).toBe(3);
+            expect(tree.map(t => t.id)).toContain(grandchild.id);
+            // Cancel Root
+            await queue.cancel(root.id);
+            // Verify all cancelled
+            const tRoot = await queue.getTask(root.id);
+            const tChild = await queue.getTask(child.id);
+            const tGrand = await queue.getTask(grandchild.id);
+            expect(tRoot?.status).toBe(TaskState.Cancelled);
+            expect(tChild?.status).toBe(TaskState.Cancelled);
+            expect(tGrand?.status).toBe(TaskState.Cancelled);
+        });
+        it('should cancel many by tags', async () => {
+            await queue.enqueue('t1', {}, { tags: ['group-a'] });
+            await queue.enqueue('t2', {}, { tags: ['group-a'] });
+            await queue.enqueue('t3', {}, { tags: ['group-b'] });
+            await queue.cancelManyByTags(['group-a']);
+            // Check status
+            const tasks = await queue.getManyByTags('group-a');
+            expect(tasks.length).toBe(2);
+            expect(tasks.every(t => t.status === TaskState.Cancelled)).toBe(true);
+            const tasksB = await queue.getManyByTags('group-b');
+            expect(tasksB[0]?.status).toBe(TaskState.Pending);
+        });
+    });
+    describe('Restart & Consumers', () => {
+        it('should restart a dead/cancelled task', async () => {
+            const task = await queue.enqueue('restart-test', {});
+            const d = await queue.dequeue({ types: ['restart-test'] });
+            await queue.fail(d, new Error('fatal'), true); // Dead
+            await queue.restart(task.id);
+            const updated = await queue.getTask(task.id);
+            expect(updated?.status).toBe(TaskState.Pending);
+            expect(updated?.tries).toBe(0);
+            expect(updated?.error).toBeNull();
+        });
+        it('should consume tasks via async iterator (getConsumer)', async () => {
+            await queue.enqueue('c1', { val: 1 });
+            await queue.enqueue('c2', { val: 2 });
+            const token = new CancellationToken();
+            const consumer = queue.getConsumer(token);
+            const t1 = (await consumer.next()).value;
+            expect(t1.data.val).toBe(1);
+            const t2 = (await consumer.next()).value;
+            expect(t2.data.val).toBe(2);
+            token.set(); // Stop consumer
+            const t3 = await consumer.next();
+            expect(t3.done).toBe(true);
+        });
+        it('should consume batches via async iterator (getBatchConsumer)', async () => {
+            await queue.enqueueMany([
+                { type: 'b', data: { val: 1 } },
+                { type: 'b', data: { val: 2 } },
+                { type: 'b', data: { val: 3 } }
+            ]);
+            const token = new CancellationToken();
+            const batchConsumer = queue.getBatchConsumer(2, token);
+            const b1 = (await batchConsumer.next()).value;
+            expect(b1.length).toBe(2);
+            const b2 = (await batchConsumer.next()).value;
+            expect(b2.length).toBe(1);
+            token.set();
+            const b3 = await batchConsumer.next();
+            expect(b3.done).toBe(true);
+        });
+    });
+});

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,334 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { TaskQueueProvider, TaskState } from '../../task-queue/index.js';
+import { setupIntegrationTest } from '../../unit-test/index.js';
+import { currentTimestamp } from '../../utils/date-time.js';
+import { timeout } from '../../utils/timing.js';
+describe('Queue Integration Tests', () => {
+    let injector;
+    let queue;
+    const queueName = `test-queue-${Date.now()}`;
+    // Helper to verify state in DB
+    async function assertTaskState(id, state, message) {
+        const task = await queue.getTask(id);
+        expect(task?.status, message).toBe(state);
+    }
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+        // Use the QueueProvider to Create/Retrieve the queue.
+        // This is the cleanest way to get a configured queue instance without
+        // messing with `injectArgument` manually in the test body.
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        queue = queueProvider.get(queueName, {
+            visibilityTimeout: 5000,
+            retryDelayMinimum: 100, // Fast retries for testing
+            retryDelayGrowth: 1, // Linear/No growth for predictable tests
+        });
+    });
+    afterEach(async () => {
+        // Drain the queue to prevent state leakage between tests
+        await queue.clear();
+    });
+    afterAll(async () => {
+        try {
+            await queue.clear();
+            await injector.dispose();
+        }
+        catch (error) {
+            // Ignore known double-dispose issue from MessageBus interaction
+            if (error instanceof Error && error.message === 'MessageBus is disposed.') {
+                return;
+            }
+            throw error;
+        }
+    });
+    it('Basic FIFO Flow', async () => {
+        const t1 = await queue.enqueue('test', { value: 'first' });
+        const t2 = await queue.enqueue('test', { value: 'second' });
+        const d1 = await queue.dequeue();
+        expect(d1?.id).toBe(t1.id);
+        expect(d1?.data.value).toBe('first');
+        await queue.complete(d1, { success: true });
+        await assertTaskState(t1.id, TaskState.Completed, 'Task 1 completed');
+        const d2 = await queue.dequeue();
+        expect(d2?.id).toBe(t2.id);
+        await queue.complete(d2, { success: true });
+    });
+    it('Priorities', async () => {
+        // Priority 1000 (default)
+        const low = await queue.enqueue('test', { value: 'low' });
+        // Priority 1
+        const high = await queue.enqueue('test', { value: 'high' }, { priority: 1 });
+        const first = await queue.dequeue();
+        expect(first?.id).toBe(high.id);
+        await queue.complete(first);
+        const second = await queue.dequeue();
+        expect(second?.id).toBe(low.id);
+        await queue.complete(second);
+    });
+    it('Deduplication (Idempotency Keys)', async () => {
+        const key = `unique-${Date.now()}`;
+        // 1. Initial Insert
+        const t1 = await queue.enqueue('test', { value: 'original' }, { idempotencyKey: key });
+        // 2. Default Strategy (replace: false): Should return existing task, ignore new data
+        const t2 = await queue.enqueue('test', { value: 'ignored' }, { idempotencyKey: key });
+        expect(t2.id, 'Same ID if not replaced').toBe(t1.id);
+        const check1 = await queue.getTask(t1.id);
+        expect(check1?.data.value).toBe('original');
+        // 3. Replace Strategy: Should replace existing task with new data AND new ID
+        const t3 = await queue.enqueueMany([{ type: 'test', data: { value: 'updated' }, idempotencyKey: key }], { replace: true, returnTasks: true });
+        expect(t3[0].id, 'New ID if replaced').not.toBe(t1.id);
+        // New task should have new data
+        const checkNew = await queue.getTask(t3[0].id);
+        expect(checkNew?.data.value).toBe('updated');
+        expect(checkNew?.tries).toBe(0);
+    });
+    it('Retries and Failures', async () => {
+        const task = await queue.enqueue('test', { value: 'fail-me' });
+        // Try 1
+        const attempt1 = await queue.dequeue();
+        expect(attempt1?.id).toBe(task.id);
+        await queue.fail(attempt1, { message: 'oops' });
+        // Force reschedule to now to bypass retryDelay
+        await queue.reschedule(task.id, Date.now());
+        // Try 2
+        const attempt2 = await queue.dequeue();
+        expect(attempt2?.id).toBe(task.id);
+        expect(attempt2?.tries).toBe(2);
+        // Fail fatally
+        await queue.fail(attempt2, { message: 'fatal error' }, true);
+        await assertTaskState(task.id, TaskState.Dead, 'Task is Dead after fatal error');
+    });
+    it('Hierarchy (Parent/Child)', async () => {
+        // A. Create Parent
+        const p = await queue.enqueue('test', { value: 'parent-manual' });
+        // B. Dequeue Parent
+        const pTask = await queue.dequeue();
+        expect(pTask?.id).toBe(p.id);
+        // C. Parent spawns child
+        const child = await queue.enqueue('test', { value: 'child-manual' }, { parentId: p.id });
+        // D. "Finish" Parent execution.
+        await queue.complete(pTask);
+        // await assertTaskState(p.id, TaskState.Waiting, 'Parent entered WAITING state'); // Depends on implementation details of auto-waiting
+    });
+    it('Batching', async () => {
+        const batch = queue.batch();
+        for (let i = 0; i < 5; i++) {
+            batch.add('test', { value: `batch-${i}` });
+        }
+        const tasks = await batch.enqueue(true);
+        expect(tasks.length).toBe(5);
+        const dequeuedBatch = await queue.dequeueMany(5);
+        expect(dequeuedBatch.length).toBe(5);
+        await queue.completeMany(dequeuedBatch);
+        const leftover = await queue.dequeue();
+        expect(leftover).toBeUndefined();
+    });
+});
+describe('PostgresQueue (Distributed Task Orchestration)', () => {
+    let injector;
+    let queue;
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+    });
+    beforeEach(() => {
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        const queueName = `pg-test-queue-${Date.now()}-${Math.random()}`;
+        queue = queueProvider.get(queueName, {
+            visibilityTimeout: 200, // Short timeout for testing
+            retryDelayMinimum: 50,
+            retryDelayGrowth: 1,
+            circuitBreakerThreshold: 2,
+            circuitBreakerResetTimeout: 200,
+        });
+    });
+    afterEach(async () => {
+        await queue.clear();
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    describe('Basic Lifecycle', () => {
+        it('should enqueue and dequeue a task', async () => {
+            await queue.enqueue('test', { foo: 'bar' });
+            const task = await queue.dequeue();
+            expect(task).toBeDefined();
+            expect(task?.data).toEqual({ foo: 'bar' });
+            expect(task?.status).toBe(TaskState.Running);
+            expect(task?.tries).toBe(1);
+        });
+        it('should complete a task successfully', async () => {
+            const task = await queue.enqueue('test', { foo: 'bar' });
+            const dequeued = await queue.dequeue();
+            await queue.complete(dequeued, { result: true });
+            const updated = await queue.getTask(task.id);
+            expect(updated?.status).toBe(TaskState.Completed);
+            expect(updated?.result).toEqual({ result: true });
+            expect(updated?.completeTimestamp).toBeGreaterThan(0);
+        });
+        it('should fail a task and increment tries', async () => {
+            const task = await queue.enqueue('test', { foo: 'bar' });
+            const dequeued = await queue.dequeue();
+            await queue.fail(dequeued, new Error('temp failure'));
+            const updated = await queue.getTask(task.id);
+            expect(updated?.status).toBe(TaskState.Pending);
+            expect(updated?.tries).toBe(1);
+            expect(updated?.error).toBeDefined();
+        });
+    });
+    describe('Priority and Scheduling', () => {
+        it('should dequeue tasks in priority order (lower number first)', async () => {
+            await queue.enqueue('test', { foo: 'low' }, { priority: 2000 });
+            await queue.enqueue('test', { foo: 'high' }, { priority: 10 });
+            await queue.enqueue('test', { foo: 'mid' }, { priority: 1000 });
+            const t1 = await queue.dequeue();
+            const t2 = await queue.dequeue();
+            const t3 = await queue.dequeue();
+            expect(t1?.data?.foo).toBe('high');
+            expect(t2?.data?.foo).toBe('mid');
+            expect(t3?.data?.foo).toBe('low');
+        });
+        it('should not dequeue a task scheduled in the future', async () => {
+            const future = currentTimestamp() + 500;
+            await queue.enqueue('test', { foo: 'future' }, { scheduleTimestamp: future });
+            const task = await queue.dequeue();
+            expect(task).toBeUndefined();
+            await timeout(600);
+            const taskLater = await queue.dequeue();
+            expect(taskLater).toBeDefined();
+        });
+    });
+    describe('Concurrency Control', () => {
+        it('should respect global concurrency limits', async () => {
+            const queueProvider = injector.resolve(TaskQueueProvider);
+            const limitedQueue = queueProvider.get(`limit-test-${Date.now()}`, { globalConcurrency: 2 });
+            await limitedQueue.enqueueMany([
+                { type: 'test', data: { foo: '1' } },
+                { type: 'test', data: { foo: '2' } },
+                { type: 'test', data: { foo: '3' } },
+            ]);
+            const t1 = await limitedQueue.dequeue();
+            const t2 = await limitedQueue.dequeue();
+            const t3 = await limitedQueue.dequeue();
+            expect(t1).toBeDefined();
+            expect(t2).toBeDefined();
+            expect(t3).toBeUndefined(); // Limit reached
+            await limitedQueue.complete(t1);
+            const t3Retry = await limitedQueue.dequeue();
+            expect(t3Retry).toBeDefined(); // Slot opened
+            await limitedQueue.clear();
+        });
+    });
+    describe('Circuit Breaker', () => {
+        it('should trip the breaker after threshold failures', async () => {
+            // Config: circuitBreakerThreshold: 2 (set in beforeEach)
+            await queue.enqueue('test', { foo: '1' });
+            await queue.enqueue('test', { foo: '2' });
+            await queue.enqueue('test', { foo: '3' });
+            await queue.fail((await queue.dequeue()), 'err');
+            await queue.fail((await queue.dequeue()), 'err');
+            // Breaker should be Open
+            const t3Attempt = await queue.dequeue();
+            expect(t3Attempt).toBeUndefined();
+        });
+        it('should allow a single probe in Half-Open state', async () => {
+            await queue.enqueueMany([
+                { type: 'test', data: { foo: '1' } },
+                { type: 'test', data: { foo: '2' } },
+            ]);
+            await queue.fail((await queue.dequeue()), 'err');
+            await queue.fail((await queue.dequeue()), 'err');
+            // Breaker is Open. Wait for reset timeout (200ms)
+            await timeout(250);
+            const probe = await queue.dequeue();
+            expect(probe).toBeDefined();
+            const secondAttempt = await queue.dequeue();
+            expect(secondAttempt).toBeUndefined(); // Only 1 probe allowed in Half-Open
+        });
+    });
+    describe('Timeouts and Maintenance (Pruning)', () => {
+        it('should recover "Zombie" tasks (crashed workers)', async () => {
+            const task = await queue.enqueue('test', { foo: 'zombie' });
+            await queue.dequeue(); // Task is now Running with a token
+            // processTimeout is 200ms. Wait for it to expire.
+            await timeout(300);
+            await queue.maintenance();
+            const recovered = await queue.getTask(task.id);
+            expect(recovered?.status).toBe(TaskState.Pending);
+            expect(recovered?.tries).toBe(1);
+            expect(recovered?.token).toBeNull();
+        });
+        it('should fail tasks that exceed Hard Execution Timeout via prune', async () => {
+            // Re-configure queue with very short execution timeout
+            const queueProvider = injector.resolve(TaskQueueProvider);
+            const shortQueue = queueProvider.get(`prune-test-${Date.now()}`, { maxExecutionTime: 100 });
+            const task = await shortQueue.enqueue('test', { foo: 'long-running' });
+            await shortQueue.dequeue();
+            await timeout(200);
+            await shortQueue.maintenance();
+            const updated = await shortQueue.getTask(task.id);
+            expect(updated?.status).toBe(TaskState.Dead);
+            expect(updated?.error?.message).toContain('Hard Execution Timeout');
+            await shortQueue.clear();
+        });
+        it('should touch a task to extend token', async () => {
+            const task = await queue.enqueue('test', { foo: 'work' });
+            const dequeued = await queue.dequeue();
+            const initialLock = dequeued.visibilityDeadline;
+            await timeout(50);
+            const touched = await queue.touch(dequeued);
+            expect(touched?.visibilityDeadline).toBeGreaterThan(initialLock);
+        });
+        it('should prevent touching if token is lost (stolen by another worker)', async () => {
+            await queue.enqueue('test', { foo: 'work' });
+            const dequeued = await queue.dequeue();
+            expect(dequeued).toBeDefined();
+            // processTimeout is 200ms. Wait for it to expire.
+            await timeout(300);
+            await queue.maintenance();
+            await queue.dequeue(); // Stolen by another worker (tries=2)
+            // Original worker tries to touch
+            const touchResult = await queue.touch(dequeued);
+            expect(touchResult).toBeUndefined();
+        });
+    });
+    describe('Batch Operations', () => {
+        it('should complete many tasks efficiently', async () => {
+            const tasks = await queue.enqueueMany([
+                { type: 'test', data: { foo: '1' } },
+                { type: 'test', data: { foo: '2' } },
+            ], { returnTasks: true });
+            const d1 = await queue.dequeue();
+            const d2 = await queue.dequeue();
+            await queue.completeMany([d1, d2]);
+            const t1 = await queue.getTask(tasks[0].id);
+            const t2 = await queue.getTask(tasks[1].id);
+            expect(t1?.status).toBe(TaskState.Completed);
+            expect(t2?.status).toBe(TaskState.Completed);
+        });
+    });
+    describe('Rescheduling', () => {
+        it('should reschedule and refund tries if running', async () => {
+            const task = await queue.enqueue('test', { foo: 'reschedule-me' });
+            const dequeued = await queue.dequeue();
+            expect(dequeued?.tries).toBe(1);
+            const inFuture = currentTimestamp() + 1000;
+            await queue.reschedule(dequeued.id, inFuture);
+            const updated = await queue.getTask(task.id);
+            expect(updated?.status).toBe(TaskState.Pending);
+            expect(updated?.tries).toBe(0); // Refunded
+            expect(updated?.scheduleTimestamp).toBe(inFuture);
+        });
+    });
+    describe('TaskContext (Worker DX)', () => {
+        it('checkpoint() should update progress and handle token loss', async () => {
+            const task = await queue.enqueue('test', { foo: 'progress' });
+            const dequeued = await queue.dequeue();
+            // In real scenarios TaskContext wraps the queue logic.
+            // Here we just verify touch/checkpoint effects on the DB.
+            await queue.touch(dequeued, { progress: 0.5, state: { step: 1 } });
+            const updated = await queue.getTask(task.id);
+            expect(updated?.progress).toBe(0.5);
+            expect(updated?.state).toEqual({ step: 1 });
+        });
+    });
+});

package/task-queue/tests/worker.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,163 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { CancellationToken } from '../../cancellation/index.js';
+import { TaskQueueProvider, TaskResult, TaskState } from '../../task-queue/index.js';
+import { setupIntegrationTest } from '../../unit-test/index.js';
+import { timeout } from '../../utils/timing.js';
+describe('Worker & Base Class Tests', () => {
+    let injector;
+    let queue;
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+    });
+    beforeEach(() => {
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        const queueName = `worker-queue-${Date.now()}-${Math.random()}`;
+        queue = queueProvider.get(queueName, {
+            visibilityTimeout: 500, // Short visibility for testing lease loss
+        });
+    });
+    afterEach(async () => {
+        await queue.clear();
+        const queueProvider = injector.resolve(TaskQueueProvider);
+        await queueProvider.get('other-queue').clear();
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    it('should process tasks using process() helper', async () => {
+        const t1 = await queue.enqueue('work', { val: 1 });
+        const t2 = await queue.enqueue('work', { val: 2 });
+        const processed = [];
+        const token = new CancellationToken();
+        queue.process({ cancellationSignal: token }, async (context) => {
+            processed.push(context.data.val);
+            return TaskResult.Complete();
+        });
+        // Wait until 2 tasks are processed
+        for (let i = 0; i < 20; i++) {
+            if (processed.length === 2)
+                break;
+            await timeout(100);
+        }
+        token.set(); // Stop worker
+        expect(processed).toContain(1);
+        expect(processed).toContain(2);
+        expect(processed.length).toBe(2);
+        const check1 = await queue.getTask(t1.id);
+        const check2 = await queue.getTask(t2.id);
+        expect(check1?.status).toBe(TaskState.Completed);
+        expect(check2?.status).toBe(TaskState.Completed);
+    });
+    it('should handle errors in worker gracefully', async () => {
+        const task = await queue.enqueue('fail', {});
+        const token = new CancellationToken();
+        queue.process({ cancellationSignal: token }, async () => {
+            throw new Error('worker error');
+        });
+        await timeout(200);
+        token.set();
+        const updated = await queue.getTask(task.id);
+        expect(updated?.status).toBe(TaskState.Pending); // Should retry
+        expect(updated?.tries).toBe(1);
+        expect(updated?.error?.message).toBe('worker error');
+    });
+    it('should process batch of tasks', async () => {
+        await queue.enqueueMany([
+            { type: 'batch', data: { v: 1 } },
+            { type: 'batch', data: { v: 2 } },
+            { type: 'batch', data: { v: 3 } },
+        ]);
+        const processedBatch = [];
+        const token = new CancellationToken();
+        queue.processBatch({ batchSize: 2, cancellationSignal: token }, async (context) => {
+            expect(context.tasks.length).toBeLessThanOrEqual(2);
+            context.tasks.forEach(t => processedBatch.push(t.data.v));
+            return context.tasks.map(() => TaskResult.Complete());
+        });
+        for (let i = 0; i < 20; i++) {
+            if (processedBatch.length === 3)
+                break;
+            await timeout(100);
+        }
+        token.set();
+        expect(processedBatch.sort()).toEqual([1, 2, 3]);
+    });
+    it('should extend lease (heartbeat) during long processing', async () => {
+        const task = await queue.enqueue('long', {});
+        const token = new CancellationToken();
+        let executed = false;
+        queue.process({ cancellationSignal: token }, async (_context) => {
+            // Simulate long work > visibilityTimeout (500ms)
+            await timeout(700);
+            executed = true;
+            return TaskResult.Complete();
+        });
+        await timeout(1000);
+        token.set();
+        expect(executed).toBe(true);
+        const updated = await queue.getTask(task.id);
+        expect(updated?.status).toBe(TaskState.Completed);
+    });
+    it('should handle TaskResult actions (Fail, Reschedule)', async () => {
+        const tFail = await queue.enqueue('fail-action', {});
+        const tResched = await queue.enqueue('resched-action', {});
+        const token = new CancellationToken();
+        const processed = new Set();
+        queue.process({ cancellationSignal: token }, async (context) => {
+            processed.add(context.id);
+            if (context.id === tFail.id) {
+                return TaskResult.Fail(new Error('explicit fail'));
+            }
+            if (context.id === tResched.id) {
+                return TaskResult.RescheduleBy(1000);
+            }
+            return TaskResult.Complete();
+        });
+        for (let i = 0; i < 20; i++) {
+            if (processed.size === 2)
+                break;
+            await timeout(100);
+        }
+        token.set();
+        const uFail = await queue.getTask(tFail.id);
+        expect(uFail?.status).toBe(TaskState.Pending); // Retry
+        expect(uFail?.error?.message).toBe('explicit fail');
+        const uResched = await queue.getTask(tResched.id);
+        expect(uResched?.status).toBe(TaskState.Pending);
+        expect(uResched?.scheduleTimestamp).toBeGreaterThan(Date.now());
+    });
+    it('should exercise TaskContext methods', async () => {
+        const task = await queue.enqueue('context-test', { val: 1 });
+        const token = new CancellationToken();
+        let executed = false;
+        queue.process({ cancellationSignal: token, types: ['context-test'] }, async (context) => {
+            expect(context.id).toBe(task.id);
+            expect(context.data).toEqual({ val: 1 });
+            expect(context.attempt).toBe(1);
+            expect(context.triesLeft).toBeGreaterThan(0);
+            expect(context.logger).toBeDefined();
+            expect(context.signal).toBeDefined();
+            await context.checkpoint({ progress: 0.5 });
+            const child = await context.spawn('child', { c: 1 });
+            expect(child.parentId).toBe(task.id);
+            const children = await context.spawnMany([{ type: 'child', data: { c: 2 } }]);
+            expect(children[0]?.parentId).toBe(task.id);
+            // Other queue spawn
+            const otherQueue = injector.resolve(TaskQueueProvider).get('other-queue');
+            const otherChild = await context.spawn(otherQueue, 'other', { x: 1 });
+            expect(otherChild.parentId).toBe(task.id);
+            expect(otherChild.namespace).toBe('other-queue');
+            const otherChildren = await context.spawnMany(otherQueue, [{ type: 'other', data: { x: 2 } }]);
+            expect(otherChildren[0]?.parentId).toBe(task.id);
+            executed = true;
+            return TaskResult.Complete();
+        });
+        for (let i = 0; i < 20; i++) {
+            if (executed)
+                break;
+            await timeout(100);
+        }
+        token.set();
+        expect(executed).toBe(true);
+    });
+});