queasy 0.3.0 → 0.3.1

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();
@@ -129,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;
 
@@ -149,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;
 
@@ -166,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;
 
@@ -185,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;
 
@@ -213,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
@@ -246,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 });
@@ -271,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 });
 
@@ -296,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';
 
@@ -333,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
 
@@ -360,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';
@@ -398,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

package/test/{redis-functions.test.js → redis-functions.test.ts}

@@ -4,13 +4,13 @@ import { dirname, join } from 'node:path';
 import { after, afterEach, before, describe, it } from 'node:test';
 import { fileURLToPath } from 'node:url';
 import { createClient } from 'redis';
+import type { RedisClientType } from 'redis';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 describe('Redis Lua functions', () => {
-    /** @type {import('redis').RedisClientType} */
-    let redis;
+    let redis: RedisClientType;
     const QUEUE_NAME = '{test-queue}';
 
     before(async () => {
@@ -281,12 +281,10 @@ describe('Redis Lua functions', () => {
 
             // Dequeue
             const expiryTime = now + 10000;
-            const result = /** @type {string[][]} */ (
-                await redis.fCall('queasy_dequeue', {
-                    keys: [QUEUE_NAME],
-                    arguments: [clientId, now.toString(), expiryTime.toString(), '10'],
-                })
-            );
+            const result = await redis.fCall('queasy_dequeue', {
+                keys: [QUEUE_NAME],
+                arguments: [clientId, now.toString(), expiryTime.toString(), '10'],
+            }) as string[][];
 
             assert.equal(result.length, 2);
             assert.deepEqual(result[0], ['id', jobId1]);
@@ -318,12 +316,10 @@ describe('Redis Lua functions', () => {
             await redis.hSet(`${QUEUE_NAME}:waiting_job:${jobId}`, 'id', jobId);
 
             // Try to dequeue
-            const result = /** @type {string[][]} */ (
-                await redis.fCall('queasy_dequeue', {
-                    keys: [QUEUE_NAME],
-                    arguments: [clientId, now.toString(), String(now + 10000), '10'],
-                })
-            );
+            const result = await redis.fCall('queasy_dequeue', {
+                keys: [QUEUE_NAME],
+                arguments: [clientId, now.toString(), String(now + 10000), '10'],
+            }) as string[][];
 
             assert.equal(result.length, 0);
         });
@@ -338,12 +334,10 @@ describe('Redis Lua functions', () => {
             await redis.hSet(`${QUEUE_NAME}:waiting_job:${jobId}`, 'id', jobId);
 
             // Try to dequeue
-            const result = /** @type {string[][]} */ (
-                await redis.fCall('queasy_dequeue', {
-                    keys: [QUEUE_NAME],
-                    arguments: [clientId, now.toString(), String(now + 10000), '10'],
-                })
-            );
+            const result = await redis.fCall('queasy_dequeue', {
+                keys: [QUEUE_NAME],
+                arguments: [clientId, now.toString(), String(now + 10000), '10'],
+            }) as string[][];
 
             assert.equal(result.length, 0);
         });

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

@@ -1,6 +1,6 @@
 import assert from 'node:assert';
 import { describe, it } from 'node:test';
-import { compareSemver, parseVersion } from '../src/utils.js';
+import { compareSemver, parseVersion } from '../src/utils.ts';
 
 describe('parseVersion', () => {
     it('should parse a simple major.minor version', () => {

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+    "compilerOptions": {
+        "strict": true,
+        "target": "esnext",
+        "module": "nodenext",
+        "moduleResolution": "nodenext",
+        "rewriteRelativeImportExtensions": true,
+        "outDir": "dist",
+        "rootDir": "src",
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "erasableSyntaxOnly": true,
+        "resolveJsonModule": true,
+        "lib": ["ES2022"]
+    },
+    "include": ["src/**/*.ts"]
+}

package/jsconfig.json

@@ -1,17 +0,0 @@
-{
-    "compilerOptions": {
-        "checkJs": true,
-        "strict": true,
-        "target": "ES2022",
-        "module": "ESNext",
-        "moduleResolution": "node",
-        "allowSyntheticDefaultImports": true,
-        "esModuleInterop": true,
-        "skipLibCheck": true,
-        "forceConsistentCasingInFileNames": true,
-        "resolveJsonModule": true,
-        "noEmit": true,
-        "lib": ["ES2022"]
-    },
-    "include": ["src/**/*.js", "test/**/*.js"]
-}

package/src/index.js

@@ -1,2 +0,0 @@
-export { Client } from './client.js';
-export { PermanentError, StallError } from './errors.js';

package/src/manager.js

@@ -1,94 +0,0 @@
-/**
- * This class manages resource allocation between
- * different queues based on the size of the queue
- */
-
-import { DEQUEUE_INTERVAL } from './constants.js';
-
-/** @typedef {import('./pool').Pool} Pool */
-/** @typedef {import('./queue').ProcessingQueue} Queue */
-/** @typedef {{ queue: Queue, lastDequeuedAt: number, isBusy: boolean }} QueueEntry */
-
-export class Manager {
-    /** @param {Pool} pool */
-    constructor(pool) {
-        this.pool = pool;
-
-        /** @type {Array<QueueEntry>} */
-        this.queues = [];
-
-        /** @type {NodeJS.Timeout?} */
-        this.timer = null;
-
-        this.busyCount = 0;
-    }
-
-    /** @param {Queue} queue */
-    addQueue(queue) {
-        // Add this at the beginning so we dequeue it at the next available opportunity.
-        this.queues.unshift({ queue, lastDequeuedAt: 0, isBusy: false });
-        this.busyCount += 1;
-
-        // This delay is required for queue listen tests
-        // as they need to be able to control dequeueing
-        this.next();
-    }
-
-    async next() {
-        // If this function is called while the previous execution is in progress,
-        // we do not want both executions to use the same queue.
-        const entry = this.queues.shift();
-        if (!entry) return;
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = null;
-        }
-
-        const size = entry.queue.handlerOptions.size;
-        if (this.pool.capacity < size) return;
-
-        const batchSize = Math.max(1, Math.floor(this.pool.capacity / this.busyCount / size));
-        entry.lastDequeuedAt = Date.now(); // We store the time just before the call to dequeue.
-        const { count } = await entry.queue.dequeue(batchSize);
-
-        // Update
-        const nowBusy = count >= batchSize;
-        this.busyCount += Number(nowBusy) - Number(entry.isBusy);
-        entry.isBusy = nowBusy;
-
-        this.queues.push(entry);
-        this.queues.sort(compareQueueEntries);
-
-        if (!this.timer && this.queues.length) {
-            const { isBusy, lastDequeuedAt } = this.queues[0];
-            // If the current top queue is busy, retry now.
-            const delay = isBusy ? 0 : Math.max(0, lastDequeuedAt - Date.now() + DEQUEUE_INTERVAL);
-            this.timer = setTimeout(() => this.next(), delay);
-        }
-    }
-
-    close() {
-        if (this.timer) clearTimeout(this.timer);
-    }
-}
-
-/**
- * @param {QueueEntry} a
- * @param {QueueEntry} b
- * @returns -1 | 0 | 1
- */
-function compareQueueEntries(a, b) {
-    if (a.isBusy > b.isBusy) return -1; // a busy, b not -> a first
-    if (a.isBusy < b.isBusy) return 1; // a free, b busy -> b first
-
-    if (a.queue.handlerOptions.priority > b.queue.handlerOptions.priority) return 1; // a higher -> a first
-    if (a.queue.handlerOptions.priority < b.queue.handlerOptions.priority) return -1; // b higher -> b first
-
-    if (a.lastDequeuedAt > b.lastDequeuedAt) return -1; // a newer -> b first
-    if (a.lastDequeuedAt < b.lastDequeuedAt) return 1; // a older -> a first
-
-    if (a.queue.handlerOptions.size > b.queue.handlerOptions.size) return 1; // a larger -> a first
-    if (a.queue.handlerOptions.size < b.queue.handlerOptions.size) return -1; // b larger -> b first
-
-    return 0;
-}

package/src/queue.js

@@ -1,154 +0,0 @@
-import { DEFAULT_RETRY_OPTIONS, FAILJOB_RETRY_OPTIONS } from './constants.js';
-import { generateId } from './utils.js';
-
-// Import types:
-/** @typedef {import('redis').RedisClientType} RedisClient */
-/** @typedef {import('./types').HandlerOptions} HandlerOptions */
-/** @typedef {import('./types').ListenOptions} ListenOptions */
-/** @typedef {import('./types').JobOptions} JobOptions */
-/** @typedef {import('./types').Job} Job */
-/** @typedef {import('./types').DoneMessage} DoneMessage */
-/** @typedef {import('./client').Client} Client */
-/** @typedef {import('./pool').Pool} Pool */
-/** @typedef {import('./manager').Manager} Manager */
-
-/** @typedef {Required<Partial<Pick<Queue, keyof Queue>>>} ProcessingQueue */
-
-/**
- * Queue instance for managing a named job queue
- */
-export class Queue {
-    /**
-     * @param {string} key - Queue key
-     * @param {Client} client - Redis client wrapper
-     * @param {Pool | undefined} pool - Worker pool
-     * @param {Manager | undefined} manager - Capacity allocation manager
-     */
-    constructor(key, client, pool, manager) {
-        this.key = key;
-        this.client = client;
-        this.pool = pool;
-        this.manager = manager;
-
-        /** @type {NodeJS.Timeout | undefined} */
-        // this.dequeueInterval = undefined;
-
-        /** @type {Required<HandlerOptions> | undefined} */
-        this.handlerOptions = undefined;
-
-        /** @type {string | undefined} */
-        this.handlerPath = undefined;
-
-        /** @type {string | undefined} */
-        this.failKey = undefined;
-    }
-
-    /**
-     * Attach handlers to process jobs from this queue
-     * @param {string} handlerPath - Path to handler module
-     * @param {ListenOptions} [options] - Retry strategy options and failure handler
-     * @returns {Promise<void>}
-     */
-    async listen(handlerPath, { failHandler, failRetryOptions, ...retryOptions } = {}) {
-        if (this.client.disconnected) throw new Error('Can’t listen: client disconnected');
-        if (!this.pool || !this.manager) throw new Error('Can’t listen: non-processing client');
-
-        this.handlerPath = handlerPath;
-        this.handlerOptions = { ...DEFAULT_RETRY_OPTIONS, ...retryOptions };
-
-        // Initialize failure handler on all workers if provided
-        if (failHandler) {
-            this.failKey = `${this.key}-fail`;
-            const failQueue = this.client.queue(this.failKey, true);
-            failQueue.listen(failHandler, { ...FAILJOB_RETRY_OPTIONS, ...failRetryOptions });
-        }
-
-        this.manager.addQueue(/** @type {ProcessingQueue} */ (this));
-
-        // if (!this.dequeueInterval) {
-        //     this.dequeueInterval = setInterval(() => this.dequeue(), DEQUEUE_INTERVAL);
-        // }
-    }
-
-    /**
-     * Add a job to the queue
-     * @param {any} data - Job data (any JSON-serializable value)
-     * @param {JobOptions} [options] - Job options
-     * @returns {Promise<string>} Job ID
-     */
-    async dispatch(data, options = {}) {
-        if (this.client.disconnected) throw new Error('Can’t dispatch: client disconnected');
-        const {
-            id = generateId(),
-            runAt = 0,
-            updateData = false,
-            updateRunAt = false,
-            resetCounts = false,
-        } = options;
-
-        await this.client.dispatch(this.key, id, runAt, data, updateData, updateRunAt, resetCounts);
-        return id;
-    }
-
-    /**
-     * Cancel a waiting job
-     * @param {string} id - Job ID
-     * @returns {Promise<boolean>} True if job was cancelled
-     */
-    async cancel(id) {
-        if (this.client.disconnected) throw new Error('Can’t cancel: client disconnected');
-        return await this.client.cancel(this.key, id);
-    }
-
-    /**
-     * Picks jobs from the queue and processes them
-     * @param {number} count
-     * @returns {Promise<{count: number, promise: Promise<Array<unknown>>}>}
-     */
-
-    async dequeue(count) {
-        const { pool, handlerPath, handlerOptions } = /** @type {ProcessingQueue} */ (this);
-        const { maxRetries, maxStalls, maxBackoff, minBackoff, size, timeout } = handlerOptions;
-
-        // const capacity = pool.getCapacity(size);
-        // if (capacity <= 0) return;
-
-        const jobs = await this.client.dequeue(this.key, count);
-
-        const promise = Promise.all(
-            jobs.map(async (job) => {
-                // Check if job has exceeded stall limit
-                if (job.stallCount >= maxStalls) {
-                    // Job has stalled too many times - fail it permanently
-                    if (!this.failKey) return this.client.finish(this.key, job.id);
-
-                    const failJobData = [job.id, job.data, { message: 'Max stalls exceeded' }];
-                    return this.client.fail(this.key, this.failKey, job.id, failJobData);
-                }
-
-                try {
-                    await pool.process(handlerPath, job, size, timeout);
-                    await this.client.finish(this.key, job.id);
-                } catch (message) {
-                    const { error } = /** @type {Required<DoneMessage>} */ (message);
-                    const { retryAt = 0, kind } = error;
-
-                    if (kind === 'permanent' || job.retryCount >= maxRetries) {
-                        if (!this.failKey) return this.client.finish(this.key, job.id);
-
-                        const failJobData = [job.id, job.data, error];
-                        return this.client.fail(this.key, this.failKey, job.id, failJobData);
-                    }
-
-                    const backoffUntil =
-                        Date.now() + Math.min(maxBackoff, minBackoff * 2 ** job.retryCount);
-
-                    // Retriable error: call retry
-                    await this.client.retry(this.key, job.id, Math.max(retryAt, backoffUntil));
-                }
-            })
-        );
-
-        return { count: jobs.length, promise };
-    }
-}

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

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-/**
- * 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
- */
-/** @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 });
-}
-
-export function clearLogs() {
-    receivedJobs.length = 0;
-}

package/test/fixtures/failure-handler.js

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

@@ -1,10 +0,0 @@
-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

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

@@ -1,8 +0,0 @@
-/**
- * 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');
-}