queasy 0.1.0

package/test/client.test.js

@@ -0,0 +1,49 @@
+import assert from 'node:assert';
+import { afterEach, beforeEach, describe, it, mock } from 'node:test';
+import { createClient } from 'redis';
+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');
+	});
+});

package/test/errors.test.js

@@ -0,0 +1,19 @@
+import assert from 'node:assert';
+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('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

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

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

@@ -0,0 +1,14 @@
+/**
+ * Handler that logs received data to a global array (for testing)
+ * @param {any} data - Job data
+ * @param {import('../../src/types.js').Job} job - Job metadata
+ */
+export const receivedJobs = [];
+
+export async function handle(data, job) {
+    receivedJobs.push({ data, job });
+}
+
+export function clearLogs() {
+    receivedJobs.length = 0;
+}

package/test/fixtures/failure-handler.js

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

package/test/fixtures/no-handle-handler.js

@@ -0,0 +1 @@
+export const notAFunction = 'hello';

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

@@ -0,0 +1,10 @@
+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
+ */
+export async function handle(data, job) {
+    throw new PermanentError('Permanent failure');
+}

package/test/fixtures/slow-handler.js

@@ -0,0 +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
+ */
+export async function handle(data, job) {
+    const delay = data?.delay || 1000;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+}

package/test/fixtures/success-handler.js

@@ -0,0 +1,9 @@
+/**
+ * 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/with-failure-handler.js

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

package/test/index.test.js

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { after, before, describe, it } from 'node:test';
+import { createClient } from 'redis';
+
+describe('Redis connection', () => {
+    /** @type {import('redis').RedisClientType} */
+    let redis;
+
+    before(async () => {
+        // Connect to Redis running in Docker
+        redis = createClient({
+            socket: {
+                host: 'localhost',
+                port: 6379,
+                reconnectStrategy: (retries) => {
+                    if (retries > 10) {
+                        return new Error('Max retries reached');
+                    }
+                    return Math.min(retries * 50, 2000); // Exponential backoff
+                },
+            },
+        });
+
+        await redis.connect();
+        // Wait for connection to be ready
+        await redis.ping();
+    });
+
+    after(async () => {
+        redis.destroy();
+    });
+
+    it('should connect to Redis and execute basic commands', async () => {
+        // Test SET command
+        const setResult = await redis.set('test:key', 'test-value');
+        assert.equal(setResult, 'OK');
+
+        // Test GET command
+        const getValue = await redis.get('test:key');
+        assert.equal(getValue, 'test-value');
+
+        // Test DEL command
+        const delResult = await redis.del('test:key');
+        assert.equal(delResult, 1);
+
+        // Verify key is deleted
+        const deletedValue = await redis.get('test:key');
+        assert.equal(deletedValue, null);
+    });
+
+    it('should execute PING command', async () => {
+        const result = await redis.ping();
+        assert.equal(result, 'PONG');
+    });
+});

package/test/manager.test.js

@@ -0,0 +1,87 @@
+import assert from 'node:assert';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { createClient } from 'redis';
+import { Client } from '../src/index.js';
+
+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);
+	});
+});
+
+/**
+ * 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) {
+	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');
+}

package/test/pool.test.js

@@ -0,0 +1,66 @@
+import assert from 'node:assert';
+import { afterEach, beforeEach, describe, it, mock } from 'node:test';
+import { createClient } from 'redis';
+import { Client } from '../src/index.js';
+
+const QUEUE_NAME = 'pool-test';
+
+describe('Pool stall and timeout', () => {
+	/** @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 handle worker timeout as a stall', async () => {
+		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;
+		// Very short timeout (50ms) so pool.handleTimeout fires before the 500ms handler completes
+		await q.listen(handlerPath, { timeout: 50, maxRetries: 5 });
+
+		await (await q.dequeue(1)).promise;
+
+		// Job should be back in waiting set (retried after timeout stall)
+		const score = await redis.zScore(`{${QUEUE_NAME}}`, jobId);
+		assert.ok(score !== null, 'Job should be retried back to waiting set');
+	});
+
+	it('should reject active jobs when pool is closed', async () => {
+		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;
+		await q.listen(handlerPath, { maxRetries: 5 });
+
+		// Dequeue but don't await the promise — job is still processing
+		const { promise } = await q.dequeue(1);
+
+		// Close the client immediately while job is active
+		client.close();
+
+		// The promise should resolve (the rejection gets handled by the catch block in dequeue)
+		await promise;
+
+		// Job should be back in waiting set (retry after stall rejection)
+		const score = await redis.zScore(`{${QUEUE_NAME}}`, jobId);
+		assert.ok(score !== null, 'Job should be retried after pool close');
+	});
+});