queasy 0.2.0 → 0.3.1

package/src/{worker.js → worker.ts}

@@ -1,15 +1,12 @@
 import { pathToFileURL } from 'node:url';
 import { parentPort, setEnvironmentData } from 'node:worker_threads';
-import { PermanentError } from './errors.js';
-
-/** @typedef {import('./types.js').ExecMessage} ExecMessage */
-/** @typedef {import('./types.js').DoneMessage} DoneMessage */
+import { PermanentError } from './errors.ts';
+import type { DoneMessage, ExecMessage } from './types.ts';
 
 if (!parentPort) throw new Error('Worker cannot be executed directly.');
 setEnvironmentData('queasy_worker_context', true);
 
-/** @param {ExecMessage} msg */
-parentPort.on('message', async (msg) => {
+parentPort.on('message', async (msg: ExecMessage) => {
     const { handlerPath, job } = msg;
     try {
         const mod = await import(pathToFileURL(handlerPath).href);
@@ -20,7 +17,7 @@ parentPort.on('message', async (msg) => {
         await mod.handle(job.data, job);
         send({ op: 'done', jobId: job.id });
     } catch (err) {
-        const { message, name, retryAt } = /** @type {Error & { retryAt?: number }} */ (err);
+        const { message, name, retryAt } = err as Error & { retryAt?: number };
 
         send({
             op: 'done',
@@ -35,10 +32,6 @@ parentPort.on('message', async (msg) => {
     }
 });
 
-/**
- * Send a message to the parentPort
- * @param {DoneMessage} message
- */
-function send(message) {
+function send(message: DoneMessage): void {
     parentPort?.postMessage(message);
 }

package/test/{client.test.js → client.test.ts}

@@ -1,20 +1,19 @@
 import assert from 'node:assert';
 import { afterEach, beforeEach, describe, it, mock } from 'node:test';
 import { createClient } from 'redis';
-import { Client } from '../src/index.js';
+import type { RedisClientType } from 'redis';
+import { Client } from '../src/index.ts';
 
 const QUEUE_NAME = 'client-test';
 
-describe.skip('Client heartbeat', () => {
-    /** @type {import('redis').RedisClientType} */
-    let redis;
-    /** @type {import('../src/client.js').Client} */
-    let client;
+describe('Client heartbeat', () => {
+    let redis: RedisClientType;
+    let client: Client;
 
     beforeEach(async () => {
         redis = createClient();
         await redis.connect();
-        client = new Client(redis, 1);
+        client = await new Promise<Client>((res) => new Client({}, 1, res));
         client.scheduleBump = mock.fn();
         if (client.manager) client.manager.addQueue = mock.fn();
     });

package/test/{errors.test.js → errors.test.ts}

@@ -1,6 +1,6 @@
 import assert from 'node:assert';
 import { describe, it } from 'node:test';
-import { PermanentError, StallError } from '../src/errors.js';
+import { PermanentError, StallError } from '../src/errors.ts';
 
 describe('Error classes', () => {
     it('PermanentError has correct name and message', () => {

package/test/fixtures/always-fail-handler.ts

@@ -0,0 +1,5 @@
+import type { Job } from '../../src/types.ts';
+
+export async function handle(_data: unknown, _job: Job): Promise<void> {
+    throw new Error('Always fails');
+}

package/test/fixtures/data-logger-handler.ts

@@ -0,0 +1,11 @@
+import type { Job } from '../../src/types.ts';
+
+export const receivedJobs: { data: unknown; job: Job }[] = [];
+
+export async function handle(data: unknown, job: Job): Promise<void> {
+    receivedJobs.push({ data, job });
+}
+
+export function clearLogs(): void {
+    receivedJobs.length = 0;
+}

package/test/fixtures/failure-handler.ts

@@ -0,0 +1,6 @@
+import type { Job } from '../../src/types.ts';
+
+export async function handle(data: unknown, _job: Job): Promise<void> {
+    // Just succeed to process the failure
+    console.log('Failure handler called with:', data);
+}

package/test/fixtures/permanent-error-handler.ts

@@ -0,0 +1,6 @@
+import { PermanentError } from '../../src/errors.ts';
+import type { Job } from '../../src/types.ts';
+
+export async function handle(_data: unknown, _job: Job): Promise<void> {
+    throw new PermanentError('Permanent failure');
+}

package/test/fixtures/slow-handler.ts

@@ -0,0 +1,6 @@
+import type { Job } from '../../src/types.ts';
+
+export async function handle(data: { delay?: number }, _job: Job): Promise<void> {
+    const delay = data?.delay || 1000;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+}

package/test/fixtures/success-handler.js

@@ -1,8 +1,3 @@
-/**
- * Handler that always succeeds
- * @param {any} _data - Job data
- * @param {import('../../src/types.js').Job} _job - Job metadata
- */
 export async function handle(_data, _job) {
     // Job succeeds immediately
     return;

package/test/fixtures/success-handler.ts

@@ -0,0 +1,6 @@
+import type { Job } from '../../src/types.ts';
+
+export async function handle(_data: unknown, _job: Job): Promise<void> {
+    // Job succeeds immediately
+    return;
+}

package/test/fixtures/with-failure-handler.ts

@@ -0,0 +1,5 @@
+import type { Job } from '../../src/types.ts';
+
+export async function handle(_data: unknown, _job: Job): Promise<void> {
+    throw new Error('Always fails');
+}

package/test/{guards.test.js → guards.test.ts}

@@ -1,25 +1,20 @@
 import assert from 'node:assert';
 import { afterEach, beforeEach, describe, it, mock } from 'node:test';
 import { createClient } from 'redis';
-import { Client } from '../src/index.js';
+import type { RedisClientType } from 'redis';
+import { Client } from '../src/index.ts';
 
 describe('Client disconnect guard', () => {
-    /** @type {import('redis').RedisClientType} */
-    let redis;
-    /** @type {import('../src/client.js').Client} */
-    let client;
+    let client: Client;
 
-    beforeEach(async () => {
-        redis = createClient();
-        await redis.connect();
+    beforeEach(() => {
         return new Promise((res) => {
-            client = new Client(redis, 0, res);
+            client = new Client({}, 0, res);
         });
     });
 
     afterEach(async () => {
         await client.close();
-        await redis.quit();
     });
 
     it('should throw from queue() when disconnected', () => {
@@ -29,23 +24,17 @@ describe('Client disconnect guard', () => {
 });
 
 describe('Queue disconnect guards', () => {
-    /** @type {import('redis').RedisClientType} */
-    let redis;
-    /** @type {import('../src/client.js').Client} */
-    let client;
+    let client: Client;
 
-    beforeEach(async () => {
-        redis = createClient();
-        await redis.connect();
-        client = new Client(redis, 1);
-        if (client.manager) client.manager.addQueue = mock.fn();
-        // Wait for installLuaFunctions to settle
-        await new Promise((r) => setTimeout(r, 50));
+    beforeEach(() => {
+        return new Promise((res) => {
+            client = new Client({}, 1, res);
+            if (client.manager) client.manager.addQueue = mock.fn();
+        });
     });
 
     afterEach(async () => {
         await client.close();
-        await redis.quit();
     });
 
     it('should throw from dispatch() when disconnected', async () => {
@@ -67,20 +56,16 @@ describe('Queue disconnect guards', () => {
     });
 
     it('should throw from listen() on non-processing client', async () => {
-        const nonProcessingClient = new Client(redis, 0);
-        // Wait for installLuaFunctions to settle
-        await new Promise((r) => setTimeout(r, 50));
+        const nonProcessingClient = await new Promise<Client>((res) => new Client({}, 0, res));
         const q = nonProcessingClient.queue('guard-test');
         await assert.rejects(() => q.listen('/some/handler.js'), /non-processing/);
-        await client.close();
+        await nonProcessingClient.close();
     });
 });
 
 describe('Client bump lost lock', () => {
-    /** @type {import('redis').RedisClientType} */
-    let redis;
-    /** @type {import('../src/client.js').Client} */
-    let client;
+    let redis: RedisClientType;
+    let client: Client;
 
     const QUEUE_NAME = 'bump-lock-test';
 
@@ -90,8 +75,10 @@ describe('Client bump lost lock', () => {
         const keys = await redis.keys(`{${QUEUE_NAME}}*`);
         if (keys.length > 0) await redis.del(keys);
 
-        client = new Client(redis, 1);
-        if (client.manager) client.manager.addQueue = mock.fn();
+        await new Promise((res) => {
+            client = new Client({}, 1, res);
+            if (client.manager) client.manager.addQueue = mock.fn();
+        });
     });
 
     afterEach(async () => {
@@ -104,7 +91,7 @@ describe('Client bump lost lock', () => {
     it('should close and emit disconnected when bump returns 0', async () => {
         const q = client.queue(QUEUE_NAME);
         await q.dispatch({ task: 'test' });
-        const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+        const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
         await q.listen(handlerPath);
 
         // Dequeue to register the client in the expiry set and start heartbeats
@@ -127,7 +114,7 @@ describe('Client bump lost lock', () => {
         const q = client.queue(QUEUE_NAME);
         // Set up the queue entry so scheduleBump doesn't error
         await q.dispatch({ task: 'test' });
-        const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+        const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
         await q.listen(handlerPath);
         await (await q.dequeue(1)).promise;
 

package/test/{manager.test.js → manager.test.ts}

@@ -1,30 +1,28 @@
 import assert from 'node:assert';
 import { afterEach, beforeEach, describe, it, mock } from 'node:test';
+import type { Mock } from 'node:test';
 import { createClient } from 'redis';
-import { Client } from '../src/index.js';
-import { Manager } from '../src/manager.js';
+import type { RedisClientType } from 'redis';
+import { Client } from '../src/index.ts';
+import { Manager } from '../src/manager.ts';
+import type { Pool } from '../src/pool.ts';
+import type { Queue } from '../src/queue.ts';
+import type { HandlerOptions } from '../src/types.ts';
 
 describe('Manager unit tests', () => {
-    /**
-     * @param {object} [overrides]
-     * @returns {import('../src/manager.js').Manager}
-     */
-    function createManager(overrides = {}) {
-        const pool = /** @type {import('../src/pool.js').Pool} */ ({
-            capacity: 100,
-            ...overrides,
-        });
+    function createManager(overrides: Partial<Pool> = {}): Manager {
+        const pool = { capacity: 100, ...overrides } as Pool;
         return new Manager(pool);
     }
 
-    /**
-     * @param {{ handlerOptions?: Partial<import('../src/types.js').HandlerOptions>, dequeue?: import('node:test').Mock<any> }} [overrides]
-     */
-    function mockQueue(overrides = {}) {
-        return /** @type {import('../src/queue.js').ProcessingQueue} */ ({
+    function mockQueue(overrides: {
+        handlerOptions?: Partial<HandlerOptions>;
+        dequeue?: Mock<() => Promise<{ count: number }>>;
+    } = {}): Queue {
+        return {
             handlerOptions: { size: 10, priority: 100, ...overrides.handlerOptions },
             dequeue: overrides.dequeue ?? mock.fn(async () => ({ count: 0 })),
-        });
+        } as unknown as Queue;
     }
 
     it('should return early from next() when queues are empty', async () => {
@@ -41,7 +39,7 @@ describe('Manager unit tests', () => {
         // Wait for next() to run (addQueue calls next via setTimeout)
         await new Promise((r) => setTimeout(r, 50));
         // dequeue should NOT have been called since capacity (5) < size (10)
-        assert.equal(/** @type {import('node:test').Mock<any>} */ (q.dequeue).mock.callCount(), 0);
+        assert.equal((q.dequeue as Mock<() => Promise<{ count: number }>>).mock.callCount(), 0);
         mgr.close();
     });
 
@@ -101,7 +99,7 @@ describe('Manager unit tests', () => {
         mgr.busyCount = 3;
         await mgr.next();
         // Lower priority value sorts before higher
-        const priorities = mgr.queues.map((e) => e.queue.handlerOptions.priority);
+        const priorities = mgr.queues.map((e) => e.queue.handlerOptions!.priority);
         assert.ok(priorities.indexOf(50) < priorities.indexOf(200));
         mgr.close();
     });
@@ -142,7 +140,7 @@ describe('Manager unit tests', () => {
         mgr.busyCount = 3;
         await mgr.next();
         // Among entries with same priority and lastDequeuedAt: smaller size sorts first
-        const sizes = mgr.queues.map((e) => e.queue.handlerOptions.size);
+        const sizes = mgr.queues.map((e) => e.queue.handlerOptions!.size);
         assert.ok(sizes.indexOf(5) < sizes.indexOf(20));
         mgr.close();
     });
@@ -151,10 +149,8 @@ describe('Manager unit tests', () => {
 const QUEUE_NAME = 'mgr-test';
 
 describe('Manager scheduling', () => {
-    /** @type {import('redis').RedisClientType} */
-    let redis;
-    /** @type {import('../src/client.js').Client} */
-    let client;
+    let redis: RedisClientType;
+    let client: Client;
 
     beforeEach(async () => {
         redis = createClient();
@@ -163,7 +159,9 @@ describe('Manager scheduling', () => {
         if (keys.length > 0) await redis.del(keys);
 
         // Do NOT mock manager.addQueue — let the manager drive dequeuing
-        client = new Client(redis, 1);
+        await new Promise((res) => {
+            client = new Client({}, 1, res);
+        });
     });
 
     afterEach(async () => {
@@ -177,7 +175,7 @@ describe('Manager scheduling', () => {
         const q = client.queue(QUEUE_NAME);
         const jobId = await q.dispatch({ task: 'managed' });
 
-        const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+        const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
         await q.listen(handlerPath);
 
         // Wait for manager to dequeue and process the job fully
@@ -197,7 +195,7 @@ describe('Manager scheduling', () => {
         const jobId1 = await q1.dispatch({ q: 1 });
         const jobId2 = await q2.dispatch({ q: 2 });
 
-        const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+        const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
         await q1.listen(handlerPath);
         await q2.listen(handlerPath);
 
@@ -216,13 +214,7 @@ describe('Manager scheduling', () => {
     });
 });
 
-/**
- * Poll a condition until it returns true, with a timeout.
- * @param {() => Promise<boolean>} fn
- * @param {number} [timeout=5000]
- * @param {number} [interval=20]
- */
-async function poll(fn, timeout = 5000, interval = 20) {
+async function poll(fn: () => Promise<boolean>, timeout = 5000, interval = 20): Promise<void> {
     const deadline = Date.now() + timeout;
     while (Date.now() < deadline) {
         if (await fn()) return;

package/test/{pool.test.js → pool.test.ts}

@@ -1,8 +1,10 @@
 import assert from 'node:assert';
 import { afterEach, beforeEach, describe, it, mock } from 'node:test';
 import { createClient } from 'redis';
-import { Client } from '../src/index.js';
-import { Pool } from '../src/pool.js';
+import type { RedisClientType } from 'redis';
+import { Client } from '../src/index.ts';
+import { Pool } from '../src/pool.ts';
+import type { DoneMessage } from '../src/types.ts';
 
 describe('Pool unit tests', () => {
     /** Helper to create a fake job entry with a no-op timer */
@@ -11,12 +13,8 @@ describe('Pool unit tests', () => {
         return { resolve: () => {}, reject: () => {}, size, timer };
     }
 
-    /** @param {Pool} pool */
-    function getWorker(pool) {
-        const entry = /** @type {import('../src/pool.js').WorkerEntry} */ (
-            pool.workers.values().next().value
-        );
-        return entry;
+    function getWorker(pool: Pool) {
+        return pool.workers.values().next().value;
     }
 
     it('should warn and return on message with unknown job ID', () => {
@@ -100,10 +98,8 @@ describe('Pool unit tests', () => {
 const QUEUE_NAME = 'pool-test';
 
 describe('Pool stall and timeout', () => {
-    /** @type {import('redis').RedisClientType} */
-    let redis;
-    /** @type {import('../src/client.js').Client} */
-    let client;
+    let redis: RedisClientType;
+    let client: Client;
 
     beforeEach(async () => {
         redis = createClient();
@@ -111,8 +107,10 @@ describe('Pool stall and timeout', () => {
         const keys = await redis.keys(`{${QUEUE_NAME}}*`);
         if (keys.length > 0) await redis.del(keys);
 
-        client = new Client(redis, 1);
-        if (client.manager) client.manager.addQueue = mock.fn();
+        await new Promise((res) => {
+            client = new Client({}, 1, res);
+            if (client.manager) client.manager.addQueue = mock.fn();
+        });
     });
 
     afterEach(async () => {
@@ -126,7 +124,7 @@ describe('Pool stall and timeout', () => {
         const q = client.queue(QUEUE_NAME);
         const jobId = await q.dispatch({ delay: 500 });
 
-        const handlerPath = new URL('./fixtures/slow-handler.js', import.meta.url).pathname;
+        const handlerPath = new URL('./fixtures/slow-handler.ts', import.meta.url).pathname;
         // Very short timeout (50ms) so pool.handleTimeout fires before the 500ms handler completes
         await q.listen(handlerPath, { timeout: 50, maxRetries: 5 });
 
@@ -141,7 +139,7 @@ describe('Pool stall and timeout', () => {
         const q = client.queue(QUEUE_NAME);
         const jobId = await q.dispatch({ delay: 2000 });
 
-        const handlerPath = new URL('./fixtures/slow-handler.js', import.meta.url).pathname;
+        const handlerPath = new URL('./fixtures/slow-handler.ts', import.meta.url).pathname;
         await q.listen(handlerPath, { maxRetries: 5 });
 
         // Dequeue but don't await the promise — job is still processing

package/test/{queue.test.js → queue.test.ts}

@@ -1,15 +1,14 @@
 import assert from 'node:assert';
 import { afterEach, beforeEach, describe, it, mock } from 'node:test';
 import { createClient } from 'redis';
-import { Client } from '../src/index.js';
+import type { RedisClientType } from 'redis';
+import { Client } from '../src/index.ts';
 
 const QUEUE_NAME = 'test';
 
 describe('Queue E2E', () => {
-    /** @type {import('redis').RedisClientType} */
-    let redis;
-    /** @type {import('../src/client.js').Client}*/
-    let client;
+    let redis: RedisClientType;
+    let client: Client;
 
     beforeEach(async () => {
         redis = createClient();
@@ -19,10 +18,11 @@ describe('Queue E2E', () => {
             await redis.del(keys);
         }
 
-        client = new Client(redis, 1);
-
-        // Mock this so that no actual work is dequeued by the manager.
-        if (client.manager) client.manager.addQueue = mock.fn();
+        await new Promise((res) => {
+            client = new Client({}, 1, res);
+            // Mock this so that no actual work is dequeued by the manager.
+            if (client.manager) client.manager.addQueue = mock.fn();
+        });
     });
 
     afterEach(async () => {
@@ -128,7 +128,7 @@ describe('Queue E2E', () => {
             const q = client.queue(QUEUE_NAME);
             const jobId = await q.dispatch({ greeting: 'hello' });
 
-            const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+            const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
             await q.listen(handlerPath);
             await (await q.dequeue(1)).promise;
 
@@ -148,7 +148,7 @@ describe('Queue E2E', () => {
                 q.dispatch({ id: 3 }),
             ]);
 
-            const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+            const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
             await q.listen(handlerPath);
             await (await q.dequeue(5)).promise;
 
@@ -165,7 +165,7 @@ describe('Queue E2E', () => {
             const futureTime = Date.now() + 10000;
             const jobId = await q.dispatch({ task: 'future' }, { runAt: futureTime });
 
-            const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+            const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
             await q.listen(handlerPath);
             await (await q.dequeue(1)).promise;
 
@@ -184,7 +184,7 @@ describe('Queue E2E', () => {
             const cancelled = await q.cancel(jobId1);
             assert.ok(cancelled);
 
-            const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+            const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
             await q.listen(handlerPath);
             await (await q.dequeue(1)).promise;
 
@@ -212,7 +212,7 @@ describe('Queue E2E', () => {
             const jobId1 = await queue1.dispatch({ queue: 1 });
             const jobId2 = await queue2.dispatch({ queue: 2 });
 
-            const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+            const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
             await queue1.listen(handlerPath);
             await queue2.listen(handlerPath);
             // First wait for these jobs to be dequeued and sent to workers
@@ -245,9 +245,9 @@ describe('Queue E2E', () => {
             const q = client.queue('fail-opt');
             await q.dispatch({ task: 'will-fail' });
 
-            const mainHandler = new URL('./fixtures/with-failure-handler.js', import.meta.url)
+            const mainHandler = new URL('./fixtures/with-failure-handler.ts', import.meta.url)
                 .pathname;
-            const failHandler = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+            const failHandler = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
 
             // listen with failHandler option — this covers queue.js lines 60-63
             await q.listen(mainHandler, { maxRetries: 0, failHandler });
@@ -270,7 +270,7 @@ describe('Queue E2E', () => {
             const q = client.queue(QUEUE_NAME);
             const jobId = await q.dispatch({ task: 'will-fail' });
 
-            const handlerPath = new URL('./fixtures/always-fail-handler.js', import.meta.url)
+            const handlerPath = new URL('./fixtures/always-fail-handler.ts', import.meta.url)
                 .pathname;
             await q.listen(handlerPath, { maxRetries: 2, minBackoff: 1000, maxBackoff: 10000 });
 
@@ -295,7 +295,7 @@ describe('Queue E2E', () => {
             // Manually set stall_count to exceed maxStalls (default 3)
             await redis.hSet(`{stall-test}:waiting_job:${jobId}`, 'stall_count', '5');
 
-            const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+            const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
             await q.listen(handlerPath, { maxStalls: 3 });
             q.failKey = '{stall-test}-fail';
 
@@ -332,7 +332,7 @@ describe('Queue E2E', () => {
 
             await redis.hSet(`{stall-nofail}:waiting_job:${jobId}`, 'stall_count', '5');
 
-            const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+            const handlerPath = new URL('./fixtures/success-handler.ts', import.meta.url).pathname;
             await q.listen(handlerPath, { maxStalls: 3 });
             // No failKey set — job should just be finished
 
@@ -359,7 +359,7 @@ describe('Queue E2E', () => {
             const q = client.queue('bad-handler');
             await q.dispatch({ task: 'test' });
 
-            const handlerPath = new URL('./fixtures/no-handle-handler.js', import.meta.url)
+            const handlerPath = new URL('./fixtures/no-handle-handler.ts', import.meta.url)
                 .pathname;
             await q.listen(handlerPath, { maxRetries: 0 });
             q.failKey = '{bad-handler}-fail';
@@ -397,7 +397,7 @@ describe('Queue E2E', () => {
             const q = client.queue('fail-test');
             const jobId = await q.dispatch({ task: 'will-fail' });
 
-            const handlerPath = new URL('./fixtures/with-failure-handler.js', import.meta.url)
+            const handlerPath = new URL('./fixtures/with-failure-handler.ts', import.meta.url)
                 .pathname;
 
             // Listen without failHandler so no fail queue listener races us