queasy 0.1.0 → 0.2.0

package/.github/workflows/check.yml

@@ -0,0 +1,50 @@
+name: Check
+
+on:
+  pull_request:
+    branches: [master]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    services:
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test with coverage
+        run: npm run test:coverage
+
+      - name: Check version is not already tagged
+        run: |
+          git fetch --tags
+          VERSION=$(node -e "console.log(require('./package.json').version)")
+          if [ -n "$(git tag -l "v$VERSION")" ]; then
+            echo "::error::Tag v$VERSION already exists. Bump the version in package.json."
+            exit 1
+          fi
+          echo "Version v$VERSION is not yet tagged"

package/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - run: npm install -g npm@latest
+
+      - run: npm ci
+
+      - name: Extract version
+        id: version
+        run: echo "version=$(node -e "console.log(require('./package.json').version)")" >> "$GITHUB_OUTPUT"
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create and push tag
+        run: |
+          git tag "v${{ steps.version.outputs.version }}"
+          git push origin "v${{ steps.version.outputs.version }}"
+
+      - name: Create GitHub release
+        run: gh release create "v${{ steps.version.outputs.version }}" --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/AGENTS.md

@@ -24,7 +24,8 @@ Queasy is a Redis-backed job queue for Node.js with **at-least-once** delivery s
 The JS side is split across several modules:
 
 - **`src/client.js`** (`Client` class): Top-level entry point. Wraps a `node-redis` connection, loads the Lua script into Redis via `FUNCTION LOAD REPLACE` on construction, and manages named `Queue` instances. Generates a unique `clientId` for heartbeats. All Redis `fCall` invocations live here (`dispatch`, `cancel`, `dequeue`, `finish`, `fail`, `retry`, `bump`). Exported from `src/index.js`.
-- **`src/queue.js`** (`Queue` class): Represents a single named queue. Holds dequeue options and handler path. `listen()` attaches a handler and starts a `setInterval` polling loop that calls `dequeue()`. `dequeue()` checks pool capacity, fetches jobs from Redis, and processes each via the pool. Handles retry/fail logic (backoff calculation, stall-count checks) on the JS side.
+- **`src/queue.js`** (`Queue` class): Represents a single named queue. `listen()` attaches a handler path and options, optionally sets up a fail queue (`{key}-fail`), then registers itself with the `Manager` via `addQueue()`. `dequeue(count)` fetches jobs from Redis, processes each via the pool, and handles outcomes: finishes on success, retries with exponential backoff on retriable errors, and dispatches to the fail queue on permanent errors or when `maxRetries`/`maxStalls` limits are exceeded. Returns `{ count, promise }` so the manager can track whether the queue is saturated.
+- **`src/manager.js`** (`Manager` class): Centralized dequeue scheduler shared across all queues on a client. When a queue calls `listen()`, it registers itself via `addQueue()`. The manager runs a single `next()` loop that round-robins through queues, calling `queue.dequeue(batchSize)` on each. Batch size is computed from pool capacity, the number of busy queues, and the handler's `size` option. After each dequeue, queues are re-sorted by a priority function (`compareQueueEntries`): busy queues first, then by `priority` (higher first), then by `lastDequeuedAt` (oldest first), then by `size` (larger first). The loop schedules the next tick immediately if the top queue is busy, otherwise waits `DEQUEUE_INTERVAL` ms from the last dequeue time.
 - **`src/pool.js`** (`Pool` class): Manages a set of `Worker` threads. Each worker has a `capacity` (default 100 units). `process()` picks the worker with the most spare capacity, posts the job, and returns a promise. Handles job timeouts: a timed-out job marks the worker as unhealthy, replaces it with a fresh one, and terminates the old worker once only stalled jobs remain.
 - **`src/worker.js`**: Runs inside a `Worker` thread. Receives `exec` messages, dynamically imports the handler module, calls `handle(data, job)`, and posts back `done` messages (with optional error info).
 - **`src/constants.js`**: Default retry options, heartbeat/timeout intervals, worker capacity, dequeue polling interval.

package/Readme.md

@@ -2,18 +2,18 @@
 
 A Redis-backed job queue for Node.js, featuring (in comparison with design inspiration BullMQ):
 
-- **Singleton jobs**: Guarantees that no more than one job with a given ID is be processed at a time, without trampolines or dropping jobs (“unsafe deduplication”).
-- **Fail handlers**: Guaranteed at-least-once handlers for failed or stalled jobs, which permits reliable periodic jobs without a external scheduling or “reviver” systems.
+- **Singleton jobs**: Guarantees that no more than one job with a given ID is being processed at any time, without trampolines or dropping jobs (“unsafe deduplication”).
+- **Fail handlers**: Guaranteed at-least-once handlers for failed or stalled jobs, enabling reliable periodic jobs without a external scheduling or “reviver” systems.
 - **Instant config changes**: Most configuration changes take effect immediately no matter the queue length, as they apply at dequeue time.
 - **Worker threads**: Jobs are processed in worker threads, preventing main process stalling and failing health checks due to CPU-bound jobs 
 - **Capacity model**: Worker capacity flexibly shared between heterogenous queues based on priority and demand, rather than queue-specific “concurrency”.
-- **Job timeout**: Enforced by draining and terminating worker threads with timed out jobs
-- **Zombie protection**: Clients that have lost locks detect this and exit at next heartbeat
+- **Job timeout**: Timed out jobs are killed by draining and terminating the worker threads it runs on
+- **Zombie protection**: Clients that have lost locks while stalled before recovering detect this and terminate themselves immediately
 - **Fine-grained updates**: Control over individual attributes when one job updates another with the same ID
 
 ### Terminology
 
-A _client_ is an instance of Quesy that connects to a Redis database. A _job_ is the basic unit of work that is _dispatched_ into a _queue_.
+A _client_ is an instance of Queasy that connects to a Redis database. A _job_ is the basic unit of work that is _dispatched_ into a _queue_.
 
 A _handler_ is JavaScript code that performs work. There are two kinds of handlers: _task handlers_, which process jobs, and _fail handlers_, which are invoked when a job fails permanently. Handlers run on _workers_, which are Node.js worker threads. By default, a Queasy client automatically creates one worker per CPU.
 
@@ -22,8 +22,9 @@ A _handler_ is JavaScript code that performs work. There are two kinds of handle
 - `id`: string; generated if unspecified. See _update semantics_ below for more information.
 - `data`: a JSON-serializable value passed to handlers
 - `runAt`: number; a unix timestamp, to delay job execution until at least that time
-- `stallCount`: number; how many times has this job caused the client or worker to stall?
-- `retryCount`: number; how many times has this job caused the handler to throw an error?
+- `retryCount`: number; how many times has this job been retried for any reason?
+- `stallCount`: number; how many times did the client processing this job stop sending heartbeats?
+- `timeoutCount`: number; how many times did this job fail to complete in the allocated time?
 
 ### Job lifecycle
 
@@ -42,13 +43,13 @@ Queues are dequeued based on their priority and the ratio of available capacity
 
 When a worker start processing a job, a timer is started; if the job completes or throws, the timer is cleared. If the timeout occurs, the job is marked stalled and the worker is removed from the pool so it no longer receives new jobs. A new worker is also created and added to the pool to replace it. 
 
-The unhealthy worker (with stalled jobs) continues to run until it has *only* stalled jobs remaining. When this happens, the worker is terminated, and all its stalled jobs are retried.
+The unhealthy worker (with at least one stalled job) continues to run until it has *only* stalled jobs remaining. When this happens, the worker is terminated, and all its stalled jobs are retried.
 
 ### Stall handling
 
 The client (in the main thread) sends periodic heartbeats to Redis for each queue it’s processing. If heartbeats from a client stop, a Lua script in Redis removes this client and returns all its active jobs into the waiting state with their stall count property incremented.
 
-When a job is dequeued, if its stall count exceeds the configured maximum, it is immediately considered permanently failed and its handler is not invoked.
+When a job is dequeued, if its stall count exceeds the configured maximum, it is immediately considered permanently failed; its task handler is not invoked.
 
 The response of the heartbeat Lua function indicates whether the client had been removed due to an earlier stall; if it receives this response, the client terminates all its worker threads immediately and re-initializes the pool and queues.
 
@@ -59,6 +60,7 @@ Returns a Queasy client.
 - `redisConnection`: a node-redis connection object.
 - `workerCount`: number; Size of the worker pool. If 0, or if called in a queasy worker thread, no pool is created. Defaults to the number of CPUs.
 
+The client object returned is an EventEmitter, which emits a 'disconnect' event when it fails permanently for any reason, such as library version mismatch between different workers connected to the same Redis insance, or a lost locks situation. When this happens, in general the application should exit the worker process and allow the supervisor to restart it.
 
 ### `client.queue(name)`
 
@@ -74,8 +76,7 @@ Adds a job to the queue. `data` may be any JSON value, which will be passed unch
 The following options take effect if an `id` is provided, and it matches that of a job already in the queue.
 - `updateData`: boolean; whether to replace the data of any waiting job with the same ID; default: true
 - `updateRunAt`: boolean | 'ifLater' | 'ifEarlier'; default: true
-- `updateRetryStrategy`: boolean; whether to replace `maxRetries`, `maxStalls`, `minBackoff` and `maxBackoff`
-- `resetCounts`: boolean; Whether to reset the internal failure and stall counts to 0; default: same as updateData
+- `resetCounts`: boolean; Whether to reset the retry, timeout and stall counts to 0; default: same as updateData
 
 Returns a promise that resolves to the job ID when the job has been added to Redis.
 
@@ -92,10 +93,12 @@ Attaches handlers to a queue to process jobs that are added to it.
 The following options control retry behavior:
 - `maxRetries`: number; default: 10
 - `maxStalls`: number; default: 3
+- `maxTimeouts`: number, default: 3
 - `minBackoff`: number; in milliseconds; default: 2,000
 - `maxBackoff`: number; default: 300,000
 - `size`: number; default: 10
 - `timeout`: number; in milliseconds; default: 60,000
+- `priority`: number; higher values are given preference; default: 100
 
 Additional options affect failure handling:
 - `failHandler`: The path to a JavaScript module that exports the handler for failure jobs
@@ -107,13 +110,13 @@ Every handler module must have a named export `handle`, a function that is calle
 
 ### Task handlers
 
-It receives two arguments:
+They receive two arguments:
 - `data`, the JSON value passed to dispatch
-- `job`, a Job object contains the job attributes except data
+- `job`, a Job object containing other job attributes (excluding data)
 
-This function may throw (or return a Promise that rejects) to indicate job failure. If the thrown error is an
-instance of `PermanentError`, or if `maxRetries` has been reached, the job is not retried. Otherwise, the job
-is queued to be retried with `maxRetries` incremented.
+This function may throw (or return a Promise that rejects) to indicate job failure. If the thrown error contains
+a property `kind` with the value `permanent`, or if `maxRetries` has been reached, the job is not retried. 
+Otherwise, the job is queued to be retried with `retryCount` incremented.
 
 If the thrown error has a property `retryAt`, the job’s `runAt` is set to this value; otherwise, it’s set using
 the exponential backoff algorithm.
@@ -123,8 +126,10 @@ If it returns any value apart from a Promise that rejects, the job is considered
 ### Failure handlers
 
 This function receives three arguments:
-- `data`, the JSON value passed to dispatch
-- `job`
-- `error`, a JSON object with a copy of the enumerable properties of the error thrown by the final call to handle, or an instance of `StallError` if the final call to handle didn’t return or throw.
+- `data`, a tuple (array) containing three items:
+  - `originalData`
+  - `originalJob`
+  - `error`, a JSON object with the name, message and kind properties of the error thrown by the final call to handle. Kind might be `permanent`, `retriable` or `stall`. In case of stall, the name property is either `StallError` or `TimeoutError`.
+- `job`, details of the failure handling job
 
 If this function throws an error (or returns a Promise that rejects), it is retried using exponential backoff.

package/package.json

@@ -1,12 +1,12 @@
 {
     "name": "queasy",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "A simple Redis-backed queue library for Node.js",
     "main": "src/index.js",
     "type": "module",
     "scripts": {
         "test": "node --test",
-        "test:coverage": "node --test --experimental-test-coverage",
+        "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=96 --test-coverage-include 'src/**/*.js' 'test/**/*.test.js'",
         "test:watch": "node --test --watch",
         "lint": "biome check .",
         "lint:fix": "biome check --write .",
@@ -16,6 +16,10 @@
         "docker:down": "docker compose down",
         "docker:logs": "docker compose logs -f"
     },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/aravindet/queasy.git"
+    },
     "keywords": [
         "queue",
         "redis",

package/src/client.js

@@ -1,16 +1,42 @@
+import EventEmitter from 'node:events';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getEnvironmentData } from 'node:worker_threads';
-import { HEARTBEAT_INTERVAL, HEARTBEAT_TIMEOUT } from './constants.js';
+import { HEARTBEAT_INTERVAL, HEARTBEAT_TIMEOUT, LUA_FUNCTIONS_VERSION } from './constants.js';
 import { Manager } from './manager.js';
 import { Pool } from './pool.js';
 import { Queue } from './queue.js';
-import { generateId } from './utils.js';
+import { compareSemver, generateId, parseVersion } from './utils.js';
 
-// Load Lua script
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const luaScript = readFileSync(join(__dirname, 'queasy.lua'), 'utf8');
+const luaScript = readFileSync(join(__dirname, 'queasy.lua'), 'utf8').replace(
+    '__QUEASY_VERSION__',
+    LUA_FUNCTIONS_VERSION
+);
+
+/**
+ * Check the installed version and load our Lua functions if needed.
+ * Returns true if this client should be disconnected (newer major on server).
+ * @param {RedisClient} redis
+ * @returns {Promise<boolean>} Whether to disconnect.
+ */
+async function installLuaFunctions(redis) {
+    const installedVersionString = /** @type {string?} */ (
+        await redis.fCall('queasy_version', { keys: [], arguments: [] }).catch(() => null)
+    );
+    const installedVersion = parseVersion(installedVersionString);
+    const availableVersion = parseVersion(LUA_FUNCTIONS_VERSION);
+
+    // No script installed or our version is later
+    if (compareSemver(availableVersion, installedVersion) > 0) {
+        await redis.sendCommand(['FUNCTION', 'LOAD', 'REPLACE', luaScript]);
+        return false;
+    }
+
+    // Keep the installed (newer) version. Return disconnect=true if the major versions disagree
+    return installedVersion[0] > availableVersion[0];
+}
 
 /** @typedef {import('redis').RedisClientType} RedisClient */
 /** @typedef {import('./types').Job} Job */
@@ -42,26 +68,33 @@ export function parseJob(jobArray) {
     };
 }
 
-export class Client {
+export class Client extends EventEmitter {
     /**
      * @param {RedisClient} redis - Redis client
      * @param {number?} workerCount - Allow this client to dequeue jobs.
+     * @param {((client: Client) => any)} [callback] - Callback when client is ready
      */
-    constructor(redis, workerCount) {
+    constructor(redis, workerCount, callback) {
+        super();
         this.redis = redis;
         this.clientId = generateId();
 
         /** @type {Record<string, QueueEntry>} */
         this.queues = {};
+        this.disconnected = false;
 
         const inWorker = getEnvironmentData('queasy_worker_context');
         this.pool = !inWorker && workerCount !== 0 ? new Pool(workerCount) : undefined;
         if (this.pool) this.manager = new Manager(this.pool);
 
-        // We are not awaiting this; we rely on Redis’ single-threaded blocking
-        // nature to ensure that this load completes before other Redis commands
-        // are processed.
-        this.redis.sendCommand(['FUNCTION', 'LOAD', 'REPLACE', luaScript]);
+        // Not awaited — the Lua script is read synchronously at module load,
+        // so Redis' single-threaded ordering ensures the FUNCTION LOAD completes
+        // before any subsequent fCalls from user code.
+        installLuaFunctions(this.redis).then((disconnect) => {
+            this.disconnected = disconnect;
+            if (disconnect) this.emit('disconnected', 'Redis has incompatible queasy version.');
+            else if (callback) callback(this);
+        });
     }
 
     /**
@@ -70,6 +103,8 @@ export class Client {
      * @returns {Queue} Queue object with dispatch, cancel, and listen methods
      */
     queue(name, isKey = false) {
+        if (this.disconnected) throw new Error('Can’t add queue: client disconnected');
+
         const key = isKey ? name : `{${name}}`;
         if (!this.queues[key]) {
             this.queues[key] = /** @type {QueueEntry} */ ({
@@ -79,20 +114,6 @@ export class Client {
         return this.queues[key].queue;
     }
 
-    /**
-     * This helps tests exit cleanly.
-     */
-    close() {
-        for (const name in this.queues) {
-            this.queues[name].queue.close();
-            clearTimeout(this.queues[name].bumpTimer);
-        }
-        if (this.pool) this.pool.close();
-        if (this.manager) this.manager.close();
-        this.queues = {};
-        this.pool = undefined;
-    }
-
     /**
      * Schedule the next bump timer
      * @param {string} key
@@ -107,14 +128,33 @@ export class Client {
      * @param {string} key
      */
     async bump(key) {
+        if (this.disconnected) return;
         // Set up the next bump first, in case this
         this.scheduleBump(key);
         const now = Date.now();
         const expiry = now + HEARTBEAT_TIMEOUT;
-        await this.redis.fCall('queasy_bump', {
+        const bumped = await this.redis.fCall('queasy_bump', {
             keys: [key],
             arguments: [this.clientId, String(now), String(expiry)],
         });
+
+        if (!bumped) {
+            // This client’s lock was lost and its jobs retried.
+            // We must stop processing jobs here to avoid duplication.
+            await this.close();
+            this.emit('disconnected', 'Lost locks, possible main thread freeze');
+        }
+    }
+
+    /**
+     * This marks this as disconnected.
+     */
+    async close() {
+        if (this.pool) await this.pool.close();
+        if (this.manager) await this.manager.close();
+        this.queues = {};
+        this.pool = undefined;
+        this.disconnected = true;
     }
 
     /**

package/src/constants.js

@@ -9,6 +9,7 @@ export const DEFAULT_RETRY_OPTIONS = {
     maxBackoff: 300_000, // 5 minutes
     size: 10,
     timeout: 60_000, // 1 minute
+    priority: 100,
 };
 
 /** @type {Required<JobUpdateOptions>} */
@@ -26,8 +27,10 @@ export const FAILJOB_RETRY_OPTIONS = {
     maxBackoff: 900_000, // 15 minutes
     size: 2,
     timeout: 60_000,
+    priority: 100,
 };
 
+export const LUA_FUNCTIONS_VERSION = '1.0';
 export const HEARTBEAT_INTERVAL = 5000; // 5 seconds
 export const HEARTBEAT_TIMEOUT = 10000; // 10 seconds
 export const WORKER_CAPACITY = 10;

package/src/pool.js

@@ -1,4 +1,4 @@
-import { cpus } from 'node:os';
+import { availableParallelism } from 'node:os';
 import { Worker } from 'node:worker_threads';
 import { WORKER_CAPACITY } from './constants.js';
 import { generateId } from './utils.js';
@@ -31,7 +31,7 @@ export class Pool {
 
         this.capacity = 0;
 
-        const count = targetCount ?? cpus().length;
+        const count = targetCount ?? availableParallelism();
         for (let i = 0; i < count; i++) this.createWorker();
     }
 
@@ -144,11 +144,8 @@ export class Pool {
     /**
      * Terminates all workers
      */
-    close() {
-        for (const { worker } of this.workers) {
-            worker.terminate();
-        }
-
+    async close() {
+        await Promise.all([...this.workers].map(async ({ worker }) => worker.terminate()));
         for (const [jobId, { reject, timer }] of this.activeJobs.entries()) {
             clearTimeout(timer);
             reject({

package/src/queasy.lua

@@ -113,9 +113,6 @@ local function do_retry(queue_key, id, retry_at)
     return { ok = 'OK' }
 end
 
--- Forward declaration
-local sweep
-
 -- Helper: Clear active job and unblock waiting job
 local function finish(queue_key, id, client_id, now)
     local waiting_job_key = get_waiting_job_key(queue_key, id)
@@ -183,6 +180,33 @@ local function handle_stall(queue_key, id, retry_at)
     return do_retry(queue_key, id, retry_at)
 end
 
+-- Sweep stalled clients
+local function sweep(queue_key, now)
+    local expiry_key = get_expiry_key(queue_key)
+
+    -- Find first stalled client
+    local stalled = redis.call('ZRANGEBYSCORE', expiry_key, 0, now, 'LIMIT', 0, 1)
+
+    if #stalled == 0 then return 0 end
+
+    local stalled_client_id = stalled[1]
+    local checkouts_key = get_checkouts_key(queue_key, stalled_client_id)
+
+    -- Get all job IDs checked out by this client
+    -- RESP3 returns SMEMBERS as { set = { id1 = true, id2 = true, ... } }
+    local members_resp = redis.call('SMEMBERS', checkouts_key)
+
+    for id, _ in pairs(members_resp['set']) do
+        handle_stall(queue_key, id, 0)
+    end
+
+    -- Clean up the stalled client
+    redis.call('ZREM', expiry_key, stalled_client_id)
+    redis.call('DEL', checkouts_key)
+
+    return 1
+end
+
 -- Dequeue jobs from waiting queue
 local function dequeue(queue_key, client_id, now, expiry, limit)
     local expiry_key = get_expiry_key(queue_key)
@@ -227,8 +251,9 @@ local function bump(queue_key, client_id, now, expiry)
     local expiry_key = get_expiry_key(queue_key)
 
     -- Check if this client exists in expiry set
-    local existing = redis.call('ZSCORE', expiry_key, client_id)
-    if not existing then
+    -- This can’t be skipped in favour of ZADD XX CH — when a client's new expiry
+    -- is the same as the old one, XX CH returns 0 but we need it to return 1
+    if not redis.call('ZSCORE', expiry_key, client_id) then
         return 0
     end
 
@@ -241,37 +266,6 @@ local function bump(queue_key, client_id, now, expiry)
     return 1
 end
 
--- Sweep stalled clients
-sweep = function(queue_key, now)
-    local expiry_key = get_expiry_key(queue_key)
-
-    -- Find first stalled client
-    local stalled = redis.call('ZRANGEBYSCORE', expiry_key, 0, now, 'LIMIT', 0, 1)
-
-    if #stalled == 0 then
-        return {}
-    end
-
-    local stalled_client_id = stalled[1]
-    local checkouts_key = get_checkouts_key(queue_key, stalled_client_id)
-
-    -- Get all job IDs checked out by this client
-    -- RESP3 returns SMEMBERS as { set = { id1 = true, id2 = true, ... } }
-    local members_resp = redis.call('SMEMBERS', checkouts_key)
-    local processed_jobs = {}
-
-    for id, _ in pairs(members_resp['set']) do
-        handle_stall(queue_key, id, 0)
-        table.insert(processed_jobs, id)
-    end
-
-    -- Clean up the stalled client
-    redis.call('ZREM', expiry_key, stalled_client_id)
-    redis.call('DEL', checkouts_key)
-
-    return processed_jobs
-end
-
 -- Register: queasy_dispatch
 redis.register_function {
     function_name = 'queasy_dispatch',
@@ -391,7 +385,7 @@ redis.register_function {
 redis.register_function {
     function_name = 'queasy_version',
     callback = function(keys, args)
-        return 1
+        return '__QUEASY_VERSION__'
     end,
     flags = {}
 }

package/src/queue.js

@@ -50,7 +50,8 @@ export class Queue {
      * @returns {Promise<void>}
      */
     async listen(handlerPath, { failHandler, failRetryOptions, ...retryOptions } = {}) {
-        if (!this.pool || !this.manager) throw new Error('Can’t listen on a non-processing client');
+        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 };
@@ -76,6 +77,7 @@ export class Queue {
      * @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,
@@ -94,6 +96,7 @@ export class Queue {
      * @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);
     }
 
@@ -148,14 +151,4 @@ export class Queue {
 
         return { count: jobs.length, promise };
     }
-
-    /**
-     * Stop the dequeue interval and bump timer for this queue
-     */
-    close() {
-        // if (this.dequeueInterval) {
-        //     clearInterval(this.dequeueInterval);
-        //     this.dequeueInterval = undefined;
-        // }
-    }
 }

package/src/utils.js

@@ -11,3 +11,29 @@ export function generateId(length = 20) {
     }
     return id;
 }
+
+/**
+ * Parse a semver string like '1.0' into { major, minor }
+ * Used by compareSemver
+ * @param {string?} version
+ * @returns {number[]}
+ */
+export function parseVersion(version) {
+    const parsed = String(version).split('.').map(Number);
+    if (parsed.some((n) => Number.isNaN(n))) return [0];
+    return parsed;
+}
+
+/**
+ * Compare two semver strings. Returns -1 if a < b, 0 if equal, 1 if a > b.
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {-1 | 0 | 1}
+ */
+export function compareSemver(a, b) {
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+    }
+    if (a.length !== b.length) return a.length < b.length ? -1 : 1;
+    return 0;
+}