queasy 0.1.0 → 0.2.0

package/test/client.test.js

@@ -5,45 +5,43 @@ import { Client } from '../src/index.js';
 
 const QUEUE_NAME = 'client-test';
 
-describe('Client heartbeat', () => {
-	/** @type {import('redis').RedisClientType} */
-	let redis;
-	/** @type {import('../src/client.js').Client} */
-	let client;
-
-	beforeEach(async () => {
-		redis = createClient();
-		await redis.connect();
-		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();
-	});
-
-	afterEach(async () => {
-		client.close();
-		const keys = await redis.keys(`{${QUEUE_NAME}}*`);
-		if (keys.length > 0) await redis.del(keys);
-		await redis.quit();
-	});
-
-	it('should update expiry key when bump is called', async () => {
-		const q = client.queue(QUEUE_NAME);
-		await q.dispatch({ task: 'test' });
-
-		const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
-		await q.listen(handlerPath);
-
-		// Dequeue to start heartbeats
-		await (await q.dequeue(1)).promise;
-
-		// Manually call bump to exercise the bump method
-		await client.bump(`{${QUEUE_NAME}}`);
-
-		// Expiry key should have our client's entry
-		const expiryScore = await redis.zScore(`{${QUEUE_NAME}}:expiry`, client.clientId);
-		assert.ok(expiryScore !== null, 'Expiry entry should exist after bump');
-		assert.ok(expiryScore > Date.now(), 'Expiry should be in the future');
-	});
+describe.skip('Client heartbeat', () => {
+    /** @type {import('redis').RedisClientType} */
+    let redis;
+    /** @type {import('../src/client.js').Client} */
+    let client;
+
+    beforeEach(async () => {
+        redis = createClient();
+        await redis.connect();
+        client = new Client(redis, 1);
+        client.scheduleBump = mock.fn();
+        if (client.manager) client.manager.addQueue = mock.fn();
+    });
+
+    afterEach(async () => {
+        await client.close();
+        const keys = await redis.keys(`{${QUEUE_NAME}}*`);
+        if (keys.length > 0) await redis.del(keys);
+        await redis.quit();
+    });
+
+    it('should update expiry key when bump is called', async () => {
+        const q = client.queue(QUEUE_NAME);
+        await q.dispatch({ task: 'test' });
+
+        const handlerPath = new URL('./fixtures/success-handler.js', import.meta.url).pathname;
+        await q.listen(handlerPath);
+
+        // Dequeue to start heartbeats
+        await (await q.dequeue(1)).promise;
+
+        // Manually call bump to exercise the bump method
+        await client.bump(`{${QUEUE_NAME}}`);
+
+        // Expiry key should have our client's entry
+        const expiryScore = await redis.zScore(`{${QUEUE_NAME}}:expiry`, client.clientId);
+        assert.ok(expiryScore !== null, 'Expiry entry should exist after dequeue');
+        assert.ok(expiryScore > Date.now(), 'Expiry should be in the future');
+    });
 });

package/test/errors.test.js

@@ -3,17 +3,17 @@ import { describe, it } from 'node:test';
 import { PermanentError, StallError } from '../src/errors.js';
 
 describe('Error classes', () => {
-	it('PermanentError has correct name and message', () => {
-		const err = new PermanentError('test message');
-		assert.equal(err.name, 'PermanentError');
-		assert.equal(err.message, 'test message');
-		assert.ok(err instanceof Error);
-	});
+    it('PermanentError has correct name and message', () => {
+        const err = new PermanentError('test message');
+        assert.equal(err.name, 'PermanentError');
+        assert.equal(err.message, 'test message');
+        assert.ok(err instanceof Error);
+    });
 
-	it('StallError has correct name and message', () => {
-		const err = new StallError('stall message');
-		assert.equal(err.name, 'StallError');
-		assert.equal(err.message, 'stall message');
-		assert.ok(err instanceof Error);
-	});
+    it('StallError has correct name and message', () => {
+        const err = new StallError('stall message');
+        assert.equal(err.name, 'StallError');
+        assert.equal(err.message, 'stall message');
+        assert.ok(err instanceof Error);
+    });
 });

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

@@ -1,8 +1,8 @@
 /**
  * Handler that always fails with a retriable error
- * @param {any} data - Job data
- * @param {import('../../src/types.js').Job} job - Job metadata
+ * @param {any} _data - Job data
+ * @param {import('../../src/types.js').Job} _job - Job metadata
  */
-export async function handle(data, job) {
+export async function handle(_data, _job) {
     throw new Error('Always fails');
 }

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

@@ -3,8 +3,13 @@
  * @param {any} data - Job data
  * @param {import('../../src/types.js').Job} job - Job metadata
  */
+/** @type {{ data: any, job: import('../../src/types.js').Job }[]} */
 export const receivedJobs = [];
 
+/**
+ * @param {any} data - Job data
+ * @param {import('../../src/types.js').Job} job - Job metadata
+ */
 export async function handle(data, job) {
     receivedJobs.push({ data, job });
 }

package/test/fixtures/failure-handler.js

@@ -1,9 +1,9 @@
 /**
  * Failure handler
  * @param {any} data - Failure data [originalJobId, originalData, error]
- * @param {import('../../src/types.js').Job} job - Job metadata
+ * @param {import('../../src/types.js').Job} _job - Job metadata
  */
-export async function handle(data, job) {
+export async function handle(data, _job) {
     // Just succeed to process the failure
     console.log('Failure handler called with:', data);
 }

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

@@ -2,9 +2,9 @@ import { PermanentError } from '../../src/errors.js';
 
 /**
  * Handler that throws a PermanentError
- * @param {any} data - Job data
- * @param {import('../../src/types.js').Job} job - Job metadata
+ * @param {any} _data - Job data
+ * @param {import('../../src/types.js').Job} _job - Job metadata
  */
-export async function handle(data, job) {
+export async function handle(_data, _job) {
     throw new PermanentError('Permanent failure');
 }

package/test/fixtures/slow-handler.js

@@ -1,9 +1,9 @@
 /**
  * Handler that takes some time to complete (for testing heartbeat)
  * @param {any} data - Job data
- * @param {import('../../src/types.js').Job} job - Job metadata
+ * @param {import('../../src/types.js').Job} _job - Job metadata
  */
-export async function handle(data, job) {
+export async function handle(data, _job) {
     const delay = data?.delay || 1000;
     await new Promise((resolve) => setTimeout(resolve, delay));
 }

package/test/fixtures/success-handler.js

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

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

@@ -1,8 +1,8 @@
 /**
  * Handler that always fails
- * @param {any} data - Job data
- * @param {import('../../src/types.js').Job} job - Job metadata
+ * @param {any} _data - Job data
+ * @param {import('../../src/types.js').Job} _job - Job metadata
  */
-export async function handle(data, job) {
+export async function handle(_data, _job) {
     throw new Error('Always fails');
 }

package/test/guards.test.js

@@ -0,0 +1,141 @@
+import assert from 'node:assert';
+import { afterEach, beforeEach, describe, it, mock } from 'node:test';
+import { createClient } from 'redis';
+import { Client } from '../src/index.js';
+
+describe('Client disconnect guard', () => {
+    /** @type {import('redis').RedisClientType} */
+    let redis;
+    /** @type {import('../src/client.js').Client} */
+    let client;
+
+    beforeEach(async () => {
+        redis = createClient();
+        await redis.connect();
+        return new Promise((res) => {
+            client = new Client(redis, 0, res);
+        });
+    });
+
+    afterEach(async () => {
+        await client.close();
+        await redis.quit();
+    });
+
+    it('should throw from queue() when disconnected', () => {
+        client.disconnected = true;
+        assert.throws(() => client.queue('test'), /disconnected/);
+    });
+});
+
+describe('Queue disconnect guards', () => {
+    /** @type {import('redis').RedisClientType} */
+    let redis;
+    /** @type {import('../src/client.js').Client} */
+    let 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));
+    });
+
+    afterEach(async () => {
+        await client.close();
+        await redis.quit();
+    });
+
+    it('should throw from dispatch() when disconnected', async () => {
+        const q = client.queue('guard-test');
+        client.disconnected = true;
+        await assert.rejects(() => q.dispatch({ data: 1 }), /disconnected/);
+    });
+
+    it('should throw from cancel() when disconnected', async () => {
+        const q = client.queue('guard-test');
+        client.disconnected = true;
+        await assert.rejects(() => q.cancel('some-id'), /disconnected/);
+    });
+
+    it('should throw from listen() when disconnected', async () => {
+        const q = client.queue('guard-test');
+        client.disconnected = true;
+        await assert.rejects(() => q.listen('/some/handler.js'), /disconnected/);
+    });
+
+    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 q = nonProcessingClient.queue('guard-test');
+        await assert.rejects(() => q.listen('/some/handler.js'), /non-processing/);
+        await client.close();
+    });
+});
+
+describe('Client bump lost lock', () => {
+    /** @type {import('redis').RedisClientType} */
+    let redis;
+    /** @type {import('../src/client.js').Client} */
+    let client;
+
+    const QUEUE_NAME = 'bump-lock-test';
+
+    beforeEach(async () => {
+        redis = createClient();
+        await redis.connect();
+        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();
+    });
+
+    afterEach(async () => {
+        await client.close();
+        const keys = await redis.keys(`{${QUEUE_NAME}}*`);
+        if (keys.length > 0) await redis.del(keys);
+        await redis.quit();
+    });
+
+    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;
+        await q.listen(handlerPath);
+
+        // Dequeue to register the client in the expiry set and start heartbeats
+        await (await q.dequeue(1)).promise;
+
+        // Remove the client from the expiry set to simulate a lost lock
+        await redis.zRem(`{${QUEUE_NAME}}:expiry`, client.clientId);
+
+        const disconnected = new Promise((resolve) => client.on('disconnected', resolve));
+
+        // Bump should detect it's been evicted
+        await client.bump(`{${QUEUE_NAME}}`);
+
+        const reason = await disconnected;
+        assert.ok(String(reason).includes('Lost locks'));
+        assert.equal(client.disconnected, true);
+    });
+
+    it('should skip bump when already disconnected', async () => {
+        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;
+        await q.listen(handlerPath);
+        await (await q.dequeue(1)).promise;
+
+        client.disconnected = true;
+
+        // Should return early without calling fCall
+        await client.bump(`{${QUEUE_NAME}}`);
+        // If we get here without error, the early return worked
+        assert.equal(client.disconnected, true);
+    });
+});

package/test/manager.test.js

@@ -1,74 +1,219 @@
 import assert from 'node:assert';
-import { afterEach, beforeEach, describe, it } from 'node:test';
+import { afterEach, beforeEach, describe, it, mock } from 'node:test';
 import { createClient } from 'redis';
 import { Client } from '../src/index.js';
+import { Manager } from '../src/manager.js';
+
+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,
+        });
+        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} */ ({
+            handlerOptions: { size: 10, priority: 100, ...overrides.handlerOptions },
+            dequeue: overrides.dequeue ?? mock.fn(async () => ({ count: 0 })),
+        });
+    }
+
+    it('should return early from next() when queues are empty', async () => {
+        const mgr = createManager();
+        // next() with no queues should not throw
+        await mgr.next();
+        mgr.close();
+    });
+
+    it('should return early from next() when pool capacity is insufficient', async () => {
+        const mgr = createManager({ capacity: 5 });
+        const q = mockQueue({ handlerOptions: { size: 10, priority: 100 } });
+        mgr.addQueue(q);
+        // 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);
+        mgr.close();
+    });
+
+    it('should clear existing timer when next() runs', async () => {
+        const mgr = createManager();
+        // Set a fake timer
+        mgr.timer = setTimeout(() => {}, 10000);
+        const q = mockQueue();
+        mgr.queues.push({ queue: q, lastDequeuedAt: 0, isBusy: false });
+        mgr.busyCount = 1;
+        await mgr.next();
+        // Timer should have been cleared and reset
+        assert.notEqual(mgr.timer, null);
+        mgr.close();
+    });
+
+    it('should set delay to 0 when queue is busy', async () => {
+        const mgr = createManager({ capacity: 100 });
+        // dequeue returns count equal to batchSize, making queue busy
+        const q = mockQueue({
+            dequeue: mock.fn(async () => ({ count: 10 })),
+        });
+        mgr.queues.push({ queue: q, lastDequeuedAt: 0, isBusy: false });
+        mgr.busyCount = 1;
+        await mgr.next();
+        assert.notEqual(mgr.timer, null);
+        mgr.close();
+    });
+
+    it('should sort queues: busy before non-busy', async () => {
+        const mgr = createManager({ capacity: 100 });
+        const q1 = mockQueue();
+        const q2 = mockQueue();
+        const entries = [
+            { queue: q1, lastDequeuedAt: 0, isBusy: false },
+            { queue: q2, lastDequeuedAt: 0, isBusy: true },
+        ];
+        mgr.queues = [...entries];
+        mgr.busyCount = 1;
+        // Manually call next to trigger the sort
+        await mgr.next();
+        // The busy queue should be first after sort
+        assert.equal(mgr.queues[0].isBusy, true);
+        mgr.close();
+    });
+
+    it('should exercise priority sort branches', async () => {
+        const mgr = createManager({ capacity: 200 });
+        const qProcessed = mockQueue({ handlerOptions: { size: 10, priority: 100 } });
+        const qLow = mockQueue({ handlerOptions: { size: 10, priority: 50 } });
+        const qHigh = mockQueue({ handlerOptions: { size: 10, priority: 200 } });
+        mgr.queues = [
+            { queue: qProcessed, lastDequeuedAt: 0, isBusy: false },
+            { queue: qHigh, lastDequeuedAt: 0, isBusy: false },
+            { queue: qLow, lastDequeuedAt: 0, isBusy: false },
+        ];
+        mgr.busyCount = 3;
+        await mgr.next();
+        // Lower priority value sorts before higher
+        const priorities = mgr.queues.map((e) => e.queue.handlerOptions.priority);
+        assert.ok(priorities.indexOf(50) < priorities.indexOf(200));
+        mgr.close();
+    });
+
+    it('should exercise lastDequeuedAt sort branches', async () => {
+        const mgr = createManager({ capacity: 200 });
+        const qProcessed = mockQueue();
+        const qOld = mockQueue();
+        const qNew = mockQueue();
+        mgr.queues = [
+            { queue: qProcessed, lastDequeuedAt: 0, isBusy: false },
+            { queue: qOld, lastDequeuedAt: 100, isBusy: false },
+            { queue: qNew, lastDequeuedAt: 200, isBusy: false },
+        ];
+        mgr.busyCount = 3;
+        await mgr.next();
+        // Among the two unprocessed: newer lastDequeuedAt sorts before older
+        const [, ...rest] = mgr.queues; // skip the processed entry (now has Date.now())
+        const oldIdx = rest.findIndex((e) => e.queue === qOld);
+        const newIdx = rest.findIndex((e) => e.queue === qNew);
+        if (oldIdx !== -1 && newIdx !== -1) {
+            assert.ok(newIdx < oldIdx);
+        }
+        mgr.close();
+    });
+
+    it('should exercise size sort branches', async () => {
+        const mgr = createManager({ capacity: 200 });
+        const now = Date.now();
+        const qProcessed = mockQueue({ handlerOptions: { size: 10, priority: 50 } });
+        const qSmall = mockQueue({ handlerOptions: { size: 5, priority: 100 } });
+        const qLarge = mockQueue({ handlerOptions: { size: 20, priority: 100 } });
+        mgr.queues = [
+            { queue: qProcessed, lastDequeuedAt: now, isBusy: false },
+            { queue: qSmall, lastDequeuedAt: now, isBusy: false },
+            { queue: qLarge, lastDequeuedAt: now, isBusy: false },
+        ];
+        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);
+        assert.ok(sizes.indexOf(5) < sizes.indexOf(20));
+        mgr.close();
+    });
+});
 
 const QUEUE_NAME = 'mgr-test';
 
 describe('Manager scheduling', () => {
-	/** @type {import('redis').RedisClientType} */
-	let redis;
-	/** @type {import('../src/client.js').Client} */
-	let client;
-
-	beforeEach(async () => {
-		redis = createClient();
-		await redis.connect();
-		const keys = await redis.keys(`{${QUEUE_NAME}}*`);
-		if (keys.length > 0) await redis.del(keys);
-
-		// Do NOT mock manager.addQueue — let the manager drive dequeuing
-		client = new Client(redis, 1);
-	});
-
-	afterEach(async () => {
-		client.close();
-		const keys = await redis.keys(`{${QUEUE_NAME}}*`);
-		if (keys.length > 0) await redis.del(keys);
-		await redis.quit();
-	});
-
-	it('should dequeue and process jobs via manager without explicit dequeue', async () => {
-		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;
-		await q.listen(handlerPath);
-
-		// Wait for manager to dequeue and process the job fully
-		await poll(async () => {
-			const score = await redis.zScore(`{${QUEUE_NAME}}`, jobId);
-			const activeExists = await redis.exists(`{${QUEUE_NAME}}:active_job:${jobId}`);
-			return score === null && activeExists === 0;
-		});
-	});
-
-	it('should process jobs from multiple queues', async () => {
-		const staleKeys = await redis.keys('{mgr-q2}*');
-		if (staleKeys.length > 0) await redis.del(staleKeys);
-
-		const q1 = client.queue(QUEUE_NAME);
-		const q2 = client.queue('mgr-q2');
-		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;
-		await q1.listen(handlerPath);
-		await q2.listen(handlerPath);
-
-		// Wait for both jobs to be fully processed
-		await poll(async () => {
-			const s1 = await redis.zScore(`{${QUEUE_NAME}}`, jobId1);
-			const a1 = await redis.exists(`{${QUEUE_NAME}}:active_job:${jobId1}`);
-			const s2 = await redis.zScore('{mgr-q2}', jobId2);
-			const a2 = await redis.exists(`{mgr-q2}:active_job:${jobId2}`);
-			return s1 === null && a1 === 0 && s2 === null && a2 === 0;
-		});
-
-		// Cleanup
-		const keys = await redis.keys('{mgr-q2}*');
-		if (keys.length > 0) await redis.del(keys);
-	});
+    /** @type {import('redis').RedisClientType} */
+    let redis;
+    /** @type {import('../src/client.js').Client} */
+    let client;
+
+    beforeEach(async () => {
+        redis = createClient();
+        await redis.connect();
+        const keys = await redis.keys(`{${QUEUE_NAME}}*`);
+        if (keys.length > 0) await redis.del(keys);
+
+        // Do NOT mock manager.addQueue — let the manager drive dequeuing
+        client = new Client(redis, 1);
+    });
+
+    afterEach(async () => {
+        await client.close();
+        const keys = await redis.keys(`{${QUEUE_NAME}}*`);
+        if (keys.length > 0) await redis.del(keys);
+        await redis.quit();
+    });
+
+    it('should dequeue and process jobs via manager without explicit dequeue', async () => {
+        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;
+        await q.listen(handlerPath);
+
+        // Wait for manager to dequeue and process the job fully
+        await poll(async () => {
+            const score = await redis.zScore(`{${QUEUE_NAME}}`, jobId);
+            const activeExists = await redis.exists(`{${QUEUE_NAME}}:active_job:${jobId}`);
+            return score === null && activeExists === 0;
+        });
+    });
+
+    it('should process jobs from multiple queues', async () => {
+        const staleKeys = await redis.keys('{mgr-q2}*');
+        if (staleKeys.length > 0) await redis.del(staleKeys);
+
+        const q1 = client.queue(QUEUE_NAME);
+        const q2 = client.queue('mgr-q2');
+        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;
+        await q1.listen(handlerPath);
+        await q2.listen(handlerPath);
+
+        // Wait for both jobs to be fully processed
+        await poll(async () => {
+            const s1 = await redis.zScore(`{${QUEUE_NAME}}`, jobId1);
+            const a1 = await redis.exists(`{${QUEUE_NAME}}:active_job:${jobId1}`);
+            const s2 = await redis.zScore('{mgr-q2}', jobId2);
+            const a2 = await redis.exists(`{mgr-q2}:active_job:${jobId2}`);
+            return s1 === null && a1 === 0 && s2 === null && a2 === 0;
+        });
+
+        // Cleanup
+        const keys = await redis.keys('{mgr-q2}*');
+        if (keys.length > 0) await redis.del(keys);
+    });
 });
 
 /**
@@ -78,10 +223,10 @@ describe('Manager scheduling', () => {
  * @param {number} [interval=20]
  */
 async function poll(fn, timeout = 5000, interval = 20) {
-	const deadline = Date.now() + timeout;
-	while (Date.now() < deadline) {
-		if (await fn()) return;
-		await new Promise((r) => setTimeout(r, interval));
-	}
-	assert.fail('Poll timed out');
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        if (await fn()) return;
+        await new Promise((r) => setTimeout(r, interval));
+    }
+    assert.fail('Poll timed out');
 }