queasy 0.2.0 → 0.3.1

package/{src → dist}/pool.js

@@ -1,42 +1,23 @@
 import { availableParallelism } from 'node:os';
 import { Worker } from 'node:worker_threads';
-import { WORKER_CAPACITY } from './constants.js';
-import { generateId } from './utils.js';
-
-/** @typedef {import('./types').DoneMessage} DoneMessage */
-/** @typedef {import('./types').Job} Job */
-
-/** @typedef {{
- *      worker: Worker,
- *      capacity: number,
- *      id: string,
- *      jobCount: number,
- *      stalledJobs: Set<string>
- * }} WorkerEntry */
-
-/** @typedef {{
- *      resolve: (value: DoneMessage) => void,
- *      reject: (reason: DoneMessage) => void,
- *      size: number,
- *      timer: NodeJS.Timeout
- *  }} JobEntry */
-
+import { WORKER_CAPACITY } from "./constants.js";
+import { generateId } from "./utils.js";
 export class Pool {
-    /** @param {number?} targetCount - Number of desired workers */
+    workers;
+    activeJobs;
+    capacity;
     constructor(targetCount) {
-        /** @type {Set<WorkerEntry>} */
         this.workers = new Set();
-        /** @type {Map<string, JobEntry>} */
         this.activeJobs = new Map();
-
         this.capacity = 0;
-
         const count = targetCount ?? availableParallelism();
-        for (let i = 0; i < count; i++) this.createWorker();
+        for (let i = 0; i < count; i++)
+            this.createWorker();
     }
-
     createWorker() {
-        const worker = new Worker(new URL('./worker.js', import.meta.url));
+        // Copy file extension from current file so it works in src and dist.
+        const workerFilename = `./worker${import.meta.url.slice(-3)}`;
+        const worker = new Worker(new URL(workerFilename, import.meta.url));
         const entry = {
             worker,
             capacity: WORKER_CAPACITY,
@@ -48,11 +29,6 @@ export class Pool {
         worker.on('message', (message) => this.handleWorkerMessage(entry, message));
         this.workers.add(entry);
     }
-
-    /**
-     * @param {WorkerEntry} workerEntry
-     * @param {DoneMessage} message
-     */
     handleWorkerMessage(workerEntry, message) {
         const { jobId, error } = message;
         const jobEntry = this.activeJobs.get(jobId);
@@ -64,44 +40,24 @@ export class Pool {
         workerEntry.capacity += jobEntry.size;
         this.capacity += jobEntry.size;
         workerEntry.jobCount -= 1;
-
-        // If this job was previously marked as stalled, unmark it.
-        if (workerEntry.stalledJobs.has(jobId)) workerEntry.stalledJobs.delete(jobId);
-
+        if (workerEntry.stalledJobs.has(jobId))
+            workerEntry.stalledJobs.delete(jobId);
         this.activeJobs.delete(jobId);
         jobEntry[error ? 'reject' : 'resolve'](message);
-
-        // If this worker is no longer in the the pool, check if it can be terminated.
-        if (!this.workers.has(workerEntry)) this.terminateIfEmpty(workerEntry);
+        if (!this.workers.has(workerEntry))
+            this.terminateIfEmpty(workerEntry);
     }
-
-    /**
-     *
-     * @param {WorkerEntry} workerEntry
-     * @param {string} jobId
-     */
     handleTimeout(workerEntry, jobId) {
         workerEntry.stalledJobs.add(jobId);
-
-        // Remove and replace this worker in the pool (if it wasn’t already).
-        if (this.workers.delete(workerEntry)) this.createWorker();
+        if (this.workers.delete(workerEntry))
+            this.createWorker();
         this.capacity -= workerEntry.capacity;
-
-        // If this is the last job in this worker, terminate it.
         this.terminateIfEmpty(workerEntry);
     }
-
-    /**
-     * Stops adding new jobs to a worker if it has stalled jobs.
-     * Terminates workers if all remaining jobs are stalled.
-     * @param {WorkerEntry} workerEntry
-     * @returns
-     */
     async terminateIfEmpty({ stalledJobs, jobCount, worker }) {
-        // Don't destroy if there are still non-stalled jobs running.
-        if (jobCount > stalledJobs.size) return;
+        if (jobCount > stalledJobs.size)
+            return;
         await worker.terminate();
-
         for (const jobId of stalledJobs) {
             const jobEntry = this.activeJobs.get(jobId);
             this.activeJobs.delete(jobId);
@@ -112,26 +68,15 @@ export class Pool {
             });
         }
     }
-
-    /**
-     * Processes a job to the most free worker
-     * @param {string} handlerPath
-     * @param {Job} job
-     * @param {number} size
-     * @param {number} timeout - Maximum time in ms
-     * @returns {Promise<DoneMessage>}
-     */
     process(handlerPath, job, size, timeout) {
-        // Find worker with most capacity
         let workerEntry = null;
         for (const entry of this.workers) {
-            if (!workerEntry || entry.capacity > workerEntry.capacity) workerEntry = entry;
+            if (!workerEntry || entry.capacity > workerEntry.capacity)
+                workerEntry = entry;
         }
-
-        if (!workerEntry) throw Error('Can’t process job without workers');
-
+        if (!workerEntry)
+            throw Error("Can't process job without workers");
         const timer = setTimeout(() => this.handleTimeout(workerEntry, job.id), timeout);
-
         return new Promise((resolve, reject) => {
             this.activeJobs.set(job.id, { resolve, reject, size, timer });
             workerEntry.capacity -= size;
@@ -140,10 +85,6 @@ export class Pool {
             workerEntry.worker.postMessage({ op: 'exec', handlerPath, job });
         });
     }
-
-    /**
-     * Terminates all workers
-     */
     async close() {
         await Promise.all([...this.workers].map(async ({ worker }) => worker.terminate()));
         for (const [jobId, { reject, timer }] of this.activeJobs.entries()) {
@@ -154,8 +95,8 @@ export class Pool {
                 error: { name: 'StallError', message: 'Pool is closing', kind: 'stall' },
             });
         }
-
         this.workers = new Set();
         this.activeJobs.clear();
     }
 }
+//# sourceMappingURL=pool.js.map

package/dist/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"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"}

package/dist/queasy.lua

@@ -0,0 +1,390 @@
+#!lua name=queasy
+
+--[[
+Queasy: Redis Lua functions for job queue management
+
+Key structure:
+- {queue} - sorted set of waiting job IDs (score = run_at or -run_at if blocked)
+- {queue}:expiry - sorted set of client heartbeat expiries (member = client_id, score = expiry)
+- {queue}:checkouts:{client_id} - set of job IDs checked out by this client
+- {queue}:waiting_job:{id} - hash with job data for waiting jobs
+- {queue}:active_job:{id} - hash with job data for active jobs
+]]
+
+-- Key helpers
+local function get_waiting_job_key(queue_key, id)
+    return queue_key .. ':waiting_job:' .. id
+end
+
+local function get_active_job_key(queue_key, id)
+    return queue_key .. ':active_job:' .. id
+end
+
+local function get_expiry_key(queue_key)
+    return queue_key .. ':expiry'
+end
+
+local function get_checkouts_key(queue_key, client_id)
+    return queue_key .. ':checkouts:' .. client_id
+end
+
+-- Helper: Add job to waiting queue with appropriate flags
+local function add_to_waiting(queue_key, id, score, update_run_at)
+    local flag = nil
+
+    if update_run_at == 'false' then
+        flag = 'NX'
+    elseif update_run_at == 'if_later' then
+        flag = score >= 0 and 'GT' or 'LT'
+    elseif update_run_at == 'if_earlier' then
+        flag = score >= 0 and 'LT' or 'GT'
+    end
+
+    if flag then
+        redis.call('ZADD', queue_key, flag, score, id)
+    else
+        redis.call('ZADD', queue_key, score, id)
+    end
+end
+
+-- Helper: Upsert job to waiting queue
+local function dispatch(
+    queue_key,
+    id, run_at, data,
+    update_data, update_run_at, reset_counts
+)
+    local waiting_job_key = get_waiting_job_key(queue_key, id)
+    local active_job_key = get_active_job_key(queue_key, id)
+
+    -- id is always stored so that HGETALL (e.g. during dequeue) includes it
+    redis.call('HSET', waiting_job_key, 'id', id)
+
+    -- If reset_counts is true, reset counters to 0, otherwise initialize them
+    redis.call(reset_counts and 'HSET' or 'HSETNX', waiting_job_key, 'retry_count', '0')
+    redis.call(reset_counts and 'HSET' or 'HSETNX', waiting_job_key, 'stall_count', '0')
+
+    -- Handle data
+    redis.call(update_data and 'HSET' or 'HSETNX', waiting_job_key, 'data', data)
+
+    -- Check if there's an active job with this ID
+    local is_blocked = redis.call('EXISTS', active_job_key) == 1
+    local score = is_blocked and -tonumber(run_at) or tonumber(run_at)
+
+    if is_blocked then
+        -- save these flags in case they need to be applied later
+        redis.call('HSET', waiting_job_key,
+            'reset_counts', tostring(reset_counts),
+            'update_data', tostring(update_data),
+            'update_run_at', update_run_at)
+    end
+
+    -- Add to waiting queue
+    add_to_waiting(queue_key, id, score, update_run_at)
+
+    return { ok = 'OK' }
+end
+
+-- Helper: Move job back to waiting for retry
+local function do_retry(queue_key, id, retry_at)
+    local waiting_job_key = get_waiting_job_key(queue_key, id)
+    local active_job_key = get_active_job_key(queue_key, id)
+
+    local existing_score = redis.call('ZSCORE', queue_key, id)
+
+    if existing_score then
+        local run_at = -existing_score.double
+        local job = redis.call('HGETALL', waiting_job_key)['map']
+
+        redis.call('RENAME', active_job_key, waiting_job_key)
+        redis.call('ZADD', queue_key, retry_at, id)
+
+        if next(job) then
+            dispatch(
+                queue_key,
+                id, run_at, job.data,
+                job.update_data == 'true', job.update_run_at, job.reset_counts == 'true'
+            )
+        end
+    else
+        redis.call('RENAME', active_job_key, waiting_job_key)
+        redis.call('ZADD', queue_key, retry_at, id)
+    end
+
+    return { ok = 'OK' }
+end
+
+-- 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)
+    local active_job_key = get_active_job_key(queue_key, id)
+    local checkouts_key = get_checkouts_key(queue_key, client_id)
+
+    redis.call('SREM', checkouts_key, id)
+    redis.call('DEL', active_job_key)
+
+    local score = redis.call('ZSCORE', queue_key, id)
+
+    if score then
+        score = tonumber(score.double)
+        if score < 0 then
+            score = -score
+        end
+
+        local update_run_at = redis.call('HGET', waiting_job_key, 'update_run_at') or 'true'
+        add_to_waiting(queue_key, id, score, update_run_at)
+    end
+
+    return { ok = 'OK' }
+end
+
+-- Helper: Handle permanent failure
+-- Creates a fail job and finishes the original job
+local function fail(queue_key, fail_queue_key, id, client_id, fail_job_id, fail_job_data, now)
+    -- Dispatch the fail job
+    dispatch(fail_queue_key,
+        fail_job_id, 0, fail_job_data,
+        'false', 'false', 'false')
+
+    -- Finish the original job
+    finish(queue_key, id, client_id, now)
+
+    return { ok = 'OK' }
+end
+
+-- Helper: Handle retriable failure
+local function retry(queue_key, id, client_id, retry_at, now)
+    local active_job_key = get_active_job_key(queue_key, id)
+    local checkouts_key = get_checkouts_key(queue_key, client_id)
+
+    redis.call('SREM', checkouts_key, id)
+
+    local retry_count = tonumber(redis.call('HGET', active_job_key, 'retry_count'))
+
+    retry_count = retry_count + 1
+    redis.call('HSET', active_job_key, 'retry_count', retry_count)
+
+    local result = do_retry(queue_key, id, retry_at)
+
+    return result
+end
+
+-- Helper: Handle stalled job
+local function handle_stall(queue_key, id, retry_at)
+    local active_job_key = get_active_job_key(queue_key, id)
+
+    local stall_count = tonumber(redis.call('HGET', active_job_key, 'stall_count'))
+
+    stall_count = stall_count + 1
+    redis.call('HSET', active_job_key, 'stall_count', stall_count)
+
+    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)
+    local checkouts_key = get_checkouts_key(queue_key, client_id)
+    local jobs = redis.call('ZRANGEBYSCORE', queue_key, 0, now, 'LIMIT', 0, limit)
+    local result = {}
+
+    for _, id in ipairs(jobs) do
+        redis.call('ZREM', queue_key, id)
+        local waiting_job_key = get_waiting_job_key(queue_key, id)
+        local active_job_key = get_active_job_key(queue_key, id)
+
+        redis.call('RENAME', waiting_job_key, active_job_key)
+        local job = redis.call('HGETALL', active_job_key)
+
+        redis.call('SADD', checkouts_key, id)
+        table.insert(result, job)
+    end
+
+    -- Add this client to queue and bump its expiry
+    redis.call('ZADD', expiry_key, expiry, client_id)
+
+    -- Sweep stalled clients
+    sweep(queue_key, now)
+
+    return result
+end
+
+-- Cancel a waiting job
+local function cancel(queue_key, id)
+    local waiting_job_key = get_waiting_job_key(queue_key, id)
+    local removed = redis.call('ZREM', queue_key, id)
+    if removed == 1 then
+        redis.call('DEL', waiting_job_key)
+    end
+    return removed
+end
+
+-- Bump heartbeat for client and sweep stalled clients
+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
+    -- 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
+
+    -- Update expiry
+    redis.call('ZADD', expiry_key, 'XX', expiry, client_id)
+
+    -- Sweep stalled clients
+    sweep(queue_key, now)
+
+    return 1
+end
+
+-- Register: queasy_dispatch
+redis.register_function {
+    function_name = 'queasy_dispatch',
+    callback = function(keys, args)
+        local queue_key = keys[1]
+        local id = args[1]
+        local run_at = tonumber(args[2])
+        local data = args[3]
+        local update_data = args[4] == 'true'
+        local update_run_at = args[5]
+        local reset_counts = args[6] == 'true'
+
+        redis.setresp(3)
+        return dispatch(
+            queue_key,
+            id, run_at, data,
+            update_data, update_run_at, reset_counts
+        )
+    end,
+    flags = {}
+}
+
+-- Register: queasy_dequeue
+redis.register_function {
+    function_name = 'queasy_dequeue',
+    callback = function(keys, args)
+        local queue_key = keys[1]
+        local client_id = args[1]
+        local now = tonumber(args[2])
+        local expiry = tonumber(args[3])
+        local limit = tonumber(args[4])
+
+        redis.setresp(3)
+        return dequeue(queue_key, client_id, now, expiry, limit)
+    end,
+    flags = {}
+}
+
+-- Register: queasy_cancel
+redis.register_function {
+    function_name = 'queasy_cancel',
+    callback = function(keys, args)
+        local queue_key = keys[1]
+        local id = args[1]
+
+        redis.setresp(3)
+        return cancel(queue_key, id)
+    end,
+    flags = {}
+}
+
+-- Register: queasy_bump
+redis.register_function {
+    function_name = 'queasy_bump',
+    callback = function(keys, args)
+        local queue_key = keys[1]
+        local client_id = args[1]
+        local now = tonumber(args[2])
+        local expiry = tonumber(args[3])
+
+        redis.setresp(3)
+        return bump(queue_key, client_id, now, expiry)
+    end,
+    flags = {}
+}
+
+-- Register: queasy_finish
+redis.register_function {
+    function_name = 'queasy_finish',
+    callback = function(keys, args)
+        local queue_key = keys[1]
+        local id = args[1]
+        local client_id = args[2]
+        local now = tonumber(args[3])
+
+        redis.setresp(3)
+        return finish(queue_key, id, client_id, now)
+    end,
+    flags = {}
+}
+
+-- Register: queasy_retry
+redis.register_function {
+    function_name = 'queasy_retry',
+    callback = function(keys, args)
+        local queue_key = keys[1]
+        local id = args[1]
+        local client_id = args[2]
+        local retry_at = tonumber(args[3])
+        local now = tonumber(args[5])
+
+        redis.setresp(3)
+        return retry(queue_key, id, client_id, retry_at, now)
+    end,
+    flags = {}
+}
+
+-- Register: queasy_fail
+redis.register_function {
+    function_name = 'queasy_fail',
+    callback = function(keys, args)
+        local queue_key = keys[1]
+        local fail_queue_key = keys[2]
+        local id = args[1]
+        local client_id = args[2]
+        local fail_job_id = args[3]
+        local fail_job_data = args[4]
+        local now = tonumber(args[5])
+
+        redis.setresp(3)
+        return fail(queue_key, fail_queue_key, id, client_id, fail_job_id, fail_job_data, now)
+    end,
+    flags = {}
+}
+
+-- Register: queasy_version
+redis.register_function {
+    function_name = 'queasy_version',
+    callback = function(keys, args)
+        return '__QUEASY_VERSION__'
+    end,
+    flags = {}
+}

package/dist/queue.d.ts

@@ -0,0 +1,22 @@
+import type { Client } from './client.ts';
+import type { Manager } from './manager.ts';
+import type { Pool } from './pool.ts';
+import type { HandlerOptions, JobOptions, ListenOptions } from './types.ts';
+export declare class Queue {
+    key: string;
+    client: Client;
+    pool: Pool | undefined;
+    manager: Manager | undefined;
+    handlerOptions: Required<HandlerOptions> | undefined;
+    handlerPath: string | undefined;
+    failKey: string | undefined;
+    constructor(key: string, client: Client, pool: Pool | undefined, manager: Manager | undefined);
+    listen(handlerPath: string, options?: ListenOptions): Promise<void>;
+    dispatch(data: any, options?: JobOptions): Promise<string>;
+    cancel(id: string): Promise<boolean>;
+    dequeue(count: number): Promise<{
+        count: number;
+        promise: Promise<unknown[]>;
+    }>;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAe,cAAc,EAAO,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG9F,qBAAa,KAAK;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC;IACvB,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IACrD,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEhB,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS;IAUvF,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBvE,QAAQ,CAEV,IAAI,EAAE,GAAG,EACT,OAAO,GAAE,UAAe,GACzB,OAAO,CAAC,MAAM,CAAC;IAcZ,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKpC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;KAAE,CAAC;CAyCxF"}

package/dist/queue.js

@@ -0,0 +1,81 @@
+import { DEFAULT_RETRY_OPTIONS, FAILJOB_RETRY_OPTIONS } from "./constants.js";
+import { generateId } from "./utils.js";
+export class Queue {
+    key;
+    client;
+    pool;
+    manager;
+    handlerOptions;
+    handlerPath;
+    failKey;
+    constructor(key, client, pool, manager) {
+        this.key = key;
+        this.client = client;
+        this.pool = pool;
+        this.manager = manager;
+        this.handlerOptions = undefined;
+        this.handlerPath = undefined;
+        this.failKey = undefined;
+    }
+    async listen(handlerPath, options = {}) {
+        const { failHandler, failRetryOptions, ...retryOptions } = options;
+        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 };
+        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(this);
+    }
+    async dispatch(
+    // biome-ignore lint/suspicious/noExplicitAny: Data is any serializable value
+    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;
+    }
+    async cancel(id) {
+        if (this.client.disconnected)
+            throw new Error("Can't cancel: client disconnected");
+        return await this.client.cancel(this.key, id);
+    }
+    async dequeue(count) {
+        const pool = this.pool;
+        const handlerPath = this.handlerPath;
+        const { maxRetries, maxStalls, maxBackoff, minBackoff, size, timeout } = this.handlerOptions;
+        const jobs = await this.client.dequeue(this.key, count);
+        const promise = Promise.all(jobs.map(async (job) => {
+            if (job.stallCount >= maxStalls) {
+                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 } = 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);
+                await this.client.retry(this.key, job.id, Math.max(retryAt, backoffUntil));
+            }
+        }));
+        return { count: jobs.length, promise };
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"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"}