queasy 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,27 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__acp__Bash",
+      "mcp__acp__Write",
+      "mcp__acp__Edit",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:github.com)",
+      "Bash(find:*)",
+      "Bash(node --test:*)",
+      "Bash(node:*)",
+      "Bash(redis-cli:*)",
+      "Bash(npm test:*)",
+      "Bash(npm run typecheck:*)",
+      "Bash(for i in 1 2 3)",
+      "Bash(do echo \"=== Run $i ===\")",
+      "Bash(done)",
+      "Bash(npm run format:*)",
+      "Bash(npx biome migrate:*)",
+      "Bash(npm run lint:*)",
+      "Bash(npm run test:coverage:*)",
+      "Bash(git -C /home/aravind/code/queasy tag -l)",
+      "Bash(test:*)",
+      "Bash(git -C /home/aravind/code/queasy log --oneline -10)"
+    ]
+  }
+}

package/.luarc.json

@@ -0,0 +1,13 @@
+{
+    "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
+    "diagnostics": {
+        "globals": ["redis", "cjson"]
+    },
+    "runtime": {
+        "version": "Lua 5.1"
+    },
+    "workspace": {
+        "library": [],
+        "checkThirdParty": false
+    }
+}

package/.zed/settings.json

@@ -0,0 +1,39 @@
+// Folder-specific settings
+//
+// For a full list of overridable settings, and general information on folder-specific settings,
+// see the documentation: https://zed.dev/docs/configuring-zed#settings-files
+{
+    "languages": {
+        "JavaScript": {
+            "format_on_save": "on",
+            "formatter": { "language_server": { "name": "biome" } },
+            "code_actions_on_format": {
+                "source.fixAll.biome": true,
+                "source.organizeImports.biome": true
+            }
+        },
+        "TypeScript": {
+            "format_on_save": "on",
+            "formatter": { "language_server": { "name": "biome" } },
+            "code_actions_on_format": {
+                "source.fixAll.biome": true,
+                "source.organizeImports.biome": true
+            }
+        },
+        "TSX": {
+            "format_on_save": "on",
+            "formatter": { "language_server": { "name": "biome" } },
+            "code_actions_on_format": {
+                "source.fixAll.biome": true,
+                "source.organizeImports.biome": true
+            }
+        },
+        "JSON": { "format_on_save": "on", "formatter": { "language_server": { "name": "biome" } } },
+        "JSONC": {
+            "format_on_save": "on",
+            "formatter": { "language_server": { "name": "biome" } }
+        },
+        "CSS": { "format_on_save": "on", "formatter": { "language_server": { "name": "biome" } } },
+        "Lua": { "format_on_save": "on", "formatter": "language_server" }
+    }
+}

package/AGENTS.md

@@ -0,0 +1,102 @@
+This file provides guidance to coding agents working in this repository.
+
+## Commands
+
+```sh
+npm test                  # Run all tests (requires Redis on localhost:6379)
+npm test -- --test-name-pattern="pattern"  # Run tests matching a pattern
+npm test -- test/queue.test.js             # Run a single test file
+npm run lint              # Lint with Biome
+npm run format            # Auto-format with Biome
+npm run typecheck         # TypeScript check via jsconfig.json (JSDoc types)
+npm run docker:up         # Start Redis via Docker Compose
+npm run docker:down       # Stop Redis
+```
+
+Tests require a running Redis instance. Use `docker:up` first if needed.
+
+## Architecture
+
+Queasy is a Redis-backed job queue for Node.js with **at-least-once** delivery semantics, singleton jobs (only one active job per ID), fail handlers, and worker-thread-based processing.
+
+### JS layer
+
+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/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.
+- **`src/errors.js`**: `PermanentError` (thrown to skip retries) and `StallError`.
+- **`src/utils.js`**: `generateId()` helper.
+- **`src/types.ts`**: JSDoc type definitions for IDE support (not runtime code).
+
+### Lua layer (`src/queasy.lua`)
+
+All queue state mutations are atomic Redis functions registered under the `queasy` library. The Lua functions are the single source of truth for state transitions — no queue logic should be duplicated in JS.
+
+Each registered function calls `redis.setresp(3)` for RESP3 typed responses.
+
+### Redis data structures
+
+All keys for a queue named `foo` share the `{foo}` hash tag for cluster compatibility:
+
+| Key pattern | Type | Purpose |
+|---|---|---|
+| `{foo}` | Sorted set | Waiting jobs. Score = `run_at`. Blocked jobs have score `-run_at` (negative, so they're excluded by the `ZRANGEBYSCORE 0 now` in dequeue). |
+| `{foo}:expiry` | Sorted set | Client heartbeat expiries. Member = `client_id`, score = expiry timestamp. |
+| `{foo}:checkouts:{client_id}` | Set | Job IDs currently checked out by this client. |
+| `{foo}:waiting_job:{id}` | Hash | Metadata for a waiting job (`id`, `data`, `retry_count`, `stall_count`, and update flags if blocked). |
+| `{foo}:active_job:{id}` | Hash | Metadata for an active job (same fields, moved via `RENAME` on dequeue). |
+
+### Job lifecycle
+
+`dispatch` → waiting set → `dequeue` → active (hash renamed, added to client's checkouts) → `finish` (success) or `retry` (retriable failure) or stall (via `sweep`)
+
+Key state transitions in Lua:
+- **Blocked jobs**: When dispatching a job whose `id` already has an `active_job` hash, the waiting entry gets a negative score to prevent dequeue. On `finish`, the negative score is flipped positive to unblock.
+- **Retry** (`do_retry`): `RENAME`s `active_job` back to `waiting_job` and `ZADD`s with the backoff timestamp. If a blocked waiting job exists for the same id, its saved update flags are re-applied.
+- **Permanent failure** (`fail`): Dispatches a new job into the fail queue (`{name}-fail`) with `data = [original_id, job_data, error]`, then calls `finish` to clean up.
+- **Stall detection** (`sweep`): Embedded inside `bump` and `dequeue` — not a standalone registered function. Finds clients in the expiry set whose score is <= `now`, retrieves their checkouts via `SMEMBERS`, calls `handle_stall` on each job, then cleans up the client.
+
+### Heartbeats
+
+Heartbeats are **per-client, per-queue** (not per-job). The JS side sends `queasy_bump` calls at `HEARTBEAT_INTERVAL = 5000ms`. The Lua side stores client expiry in the `{queue}:expiry` sorted set with a score of `now + HEARTBEAT_TIMEOUT` (10000ms). If a client's expiry passes, `sweep` returns all its checked-out jobs to the waiting state with incremented `stall_count`.
+
+`bump` returns `0` if the client was already swept (removed from the expiry set), signaling the JS side that it has been evicted.
+
+### Update semantics on re-dispatch
+
+When dispatching a job with an existing `id`, the `update_data`, `update_run_at`, and `reset_counts` flags control which fields are overwritten vs. preserved (`HSET` vs. `HSETNX` in Lua). If the job is blocked (active copy exists), these flags are stored in the waiting hash and re-applied when the blocked job is eventually retried via `do_retry`.
+
+## Lua function reference
+
+| Function | Keys | Args | Purpose |
+|---|---|---|---|
+| `queasy_dispatch` | `{queue}` | id, run_at, data, update_data, update_run_at, reset_counts | Add/update a waiting job |
+| `queasy_dequeue` | `{queue}` | client_id, now, expiry, limit | Dequeue ready jobs; also triggers sweep |
+| `queasy_cancel` | `{queue}` | id | Remove a waiting job |
+| `queasy_bump` | `{queue}` | client_id, now, expiry | Client heartbeat; also triggers sweep. Returns 0 if client was evicted. |
+| `queasy_finish` | `{queue}` | id, client_id, now | Job completed; unblocks waiting job if any |
+| `queasy_retry` | `{queue}` | id, client_id, retry_at, now | Retriable failure; increments retry_count, calls do_retry |
+| `queasy_fail` | `{queue}`, `{fail_queue}` | id, client_id, fail_job_id, fail_job_data, now | Permanent failure; dispatches fail job, then finishes original |
+| `queasy_version` | (none) | (none) | Returns library version (currently 1) |
+
+Note: `sweep`, `do_retry`, `handle_stall`, `finish`, `dispatch` also exist as internal Lua helpers but are not registered as Redis functions.
+
+## Test structure
+
+- `test/redis-functions.test.js` — Tests Lua functions directly via `redis.fCall()`. Exercises all state transitions at the Redis level.
+- `test/queue.test.js` — Tests the JS `Client`/`Queue` API (dispatch, cancel, listen). The `listen()` tests use fixture handlers in `test/fixtures/`.
+- `test/fixtures/` — Minimal handler modules. Each exports a `handle(data, job)` function.
+
+Queue names in tests use `{curly-brace}` syntax (e.g., `{test-api-queue}`) to keep all related keys on the same Redis node.
+
+## Conventions
+
+- ESM modules throughout (`"type": "module"` in package.json).
+- JSDoc types with a `types.ts` file for IDE support; run `npm run typecheck` to verify.
+- Biome for formatting (tabs, single quotes, 100-char width). Run `npm run format` before committing.
+- Lua booleans are passed as strings (`'true'`/`'false'`) between JS and Lua — comparisons in Lua use string equality (e.g., `args[4] == 'true'`).
+- `redis.setresp(3)` is called in each registered Lua function for RESP3 typed responses. This means `HGETALL` returns `{ map = {...} }`, `SMEMBERS` returns `{ set = {...} }`, `ZSCORE` returns `{ double = number }`, etc.

package/CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```sh
+npm test                  # Run all tests (requires Redis on localhost:6379)
+npm test -- --test-name-pattern="pattern"  # Run tests matching a pattern
+node --test test/queue.test.js             # Run a single test file
+npm run lint              # Lint with Biome
+npm run format            # Auto-format with Biome
+npm run typecheck         # TypeScript check via jsconfig.json (JSDoc types)
+npm run docker:up         # Start Redis via Docker Compose
+npm run docker:down       # Stop Redis
+```
+
+Tests require a running Redis instance. Use `docker:up` first if needed.
+
+## Architecture
+
+Queasy is a Redis-backed job queue with **at-least-once** delivery semantics. The core logic lives in two layers:
+
+- **JS layer** (`src/queue.js`): The `queue()` factory returns `{ dispatch, cancel, listen }`. On first use, it uploads the Lua script to Redis via `FUNCTION LOAD REPLACE`. A `WeakSet` (`initializedClients`) tracks which Redis clients have already had the functions loaded. `listen()` is currently a TODO stub.
+- **Lua layer** (`src/queasy.lua`): All queue state mutations are atomic Redis functions registered under the `queasy` library. No queue logic should be duplicated in JS — the Lua functions are the single source of truth for state transitions.
+
+### Redis data structures
+
+All keys for a queue named `foo` share the `{foo}` hash tag for cluster compatibility:
+
+| Key pattern | Type | Purpose |
+|---|---|---|
+| `{foo}:waiting` | Sorted set | Waiting jobs. Score = `run_at`. Blocked jobs have score `-run_at` (negative, so they're excluded from dequeue). |
+| `{foo}:active` | Sorted set | Active jobs. Member = `{id}:{worker_id}`, score = heartbeat deadline (`now + 10s`). |
+| `{foo}:waiting_job:{id}` | Hash | Metadata for a waiting job. |
+| `{foo}:active_job:{id}` | Hash | Metadata for an active job (same fields, moved via RENAME on dequeue). |
+
+### Job lifecycle
+
+`dispatch` → waiting set → `dequeue` → active set → `finish` (success) or `retry`/`fail` (failure) or `sweep` (stall)
+
+Key state transitions in Lua:
+- **Blocked jobs**: When dispatching a job whose `id` already has an active job, the waiting entry gets a negative score to prevent dequeue. On `finish` or `do_retry`, the negative score is flipped positive to unblock.
+- **Retry**: `do_retry` RENAMEs `active_job` back to `waiting_job` and ZADDs with a backoff `next_run_at`. If a blocked waiting job exists for the same id, it is re-dispatched after the retry.
+- **Permanent failure**: `fail` checks if a `{queue}-fail:waiting` key exists (i.e., a failure queue has been dispatched to). If so, it creates a new job there with `data = [original_id, job_data, error]`, then calls `finish` to clean up.
+- **Stall detection**: `sweep` scans the active set for entries whose heartbeat deadline has passed, then calls `handle_stall` which increments `stall_count` and either retries or calls `fail`.
+
+### Heartbeats
+
+`ACTIVE_TIMEOUT_MS = 10000` (10s) in Lua. The JS side sends `queasy_bump` calls at `HEARTBEAT_INTERVAL = 5000` (5s) to keep active jobs alive.
+
+### Update semantics on re-dispatch
+
+When dispatching a job with an existing `id`, the `update_data`, `update_run_at`, `update_retry_strategy`, and `reset_counts` flags control which fields are overwritten vs. preserved (HSET vs. HSETNX in Lua). If the job is blocked (active copy exists), these flags are stored in the waiting hash and re-applied when the blocked job is eventually dispatched.
+
+## Lua function reference
+
+| Function | Keys | Args | When called |
+|---|---|---|---|
+| `queasy_dispatch` | waiting, active | id, run_at, data, retry opts, update flags | Adding/updating a job |
+| `queasy_cancel` | waiting | id | Removing a waiting job |
+| `queasy_dequeue` | waiting, active | worker_id, now, limit | Polling for ready jobs |
+| `queasy_bump` | active | id, worker_id, now | Heartbeat keepalive |
+| `queasy_finish` | waiting, active | id, worker_id | Job completed successfully |
+| `queasy_retry` | waiting, active | id, worker_id, next_run_at, error | Job failed, may retry or fail permanently |
+| `queasy_fail` | waiting, active | id, worker_id, error | Permanent failure |
+| `queasy_sweep` | waiting, active | now, next_run_at | Detecting stalled jobs |
+
+## Test structure
+
+- `test/redis-functions.test.js` — Tests Lua functions directly via `redis.fCall()`. Exercises all state transitions at the Redis level.
+- `test/queue.test.js` — Tests the JS `queue()` API (dispatch, cancel, listen). The `listen()` tests use fixture handlers in `test/fixtures/`.
+- `test/fixtures/` — Minimal handler modules (`success-handler`, `failure-handler`, `slow-handler`, `data-logger-handler`, `permanent-error-handler`). Each exports a `handle(data, job)` function.
+
+Queue names in tests use `{curly-brace}` syntax (e.g., `{test-api-queue}`) to keep all related keys on the same Redis node.
+
+## Conventions
+
+- ESM modules throughout (`"type": "module"` in package.json).
+- JSDoc types with a `types.ts` file for IDE support; run `npm run typecheck` to verify.
+- Biome for formatting (tabs, single quotes, 100-char width). Run `npm run format` before committing.
+- All Lua booleans arrive as strings (`'true'`/`'false'`) from `redis.fCall` — comparisons in Lua must use string equality.
+- `redis.setresp(3)` is called in each registered function to get RESP3 map responses (needed for `HGETALL` returning `{ map: {...} }` instead of a flat array).

package/License.md

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright 2026 github.com/aravindet
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/Readme.md

@@ -0,0 +1,130 @@
+# Queasy 🤢
+
+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.
+- **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
+- **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 _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.
+
+### Job attributes
+
+- `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?
+
+### Job lifecycle
+
+1. A job when first dispatched is created in the _waiting_ state, unless there is a currently active job with the same ID. In that case, it is created in the _blocked_ state.
+2. Jobs are dequeued from the _waiting_ state and enter the _active_ state.
+3. When an active job finishes or fails permanently, it is deleted. Any blocked job with the same ID then moves to the _waiting_ state. (A new job may also be added to the separate fail queue.) 
+4. When an active job stalls or fails (with retries left), it returns to the _waiting_ state. Any blocked job with the same ID then updates this waiting job.
+
+### Worker capacity
+
+When the client is created, a pool of worker threads are created. Every worker is initialized with 100 units of _capacity_. When a handler is registered, it specifies its _size_ using the same units. When a worker starts processing a job with that handler, its capacity is decreased by this size; this is reversed when that job completes or fails.
+
+Queues are dequeued based on their priority and the ratio of available capacity to handler size.
+
+### Timeout handling
+
+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.
+
+### 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.
+
+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.
+
+## API
+
+### `client(redisConnection, workerCount)`
+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.
+
+
+### `client.queue(name)`
+
+Returns a queue object for interacting with this named queue at the defined Redis server.
+- name is a string queue name. Redis data structures related to a queue will be placed on the same node in a Redis cluster.
+
+### `queue.dispatch(data, options)`
+
+Adds a job to the queue. `data` may be any JSON value, which will be passed unchanged to the workers. Options may include:
+- `id`: alphanumeric string; if not provided, a unique random string is generated
+- `runAt`: number; wall clock timestamp before which this job must not be run; default: 0
+
+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
+
+Returns a promise that resolves to the job ID when the job has been added to Redis.
+
+### `queue.cancel(id)`
+
+Removes the job with the given ID if it exists in the waiting state, no-op otherwise.
+
+Returns a promise that resolves to a boolean (true if a job with this ID existed and has been removed).
+
+### `queue.listen(handler, options)`
+Attaches handlers to a queue to process jobs that are added to it.
+- `handler`: The path to a JavaScript module that exports the task handler
+
+The following options control retry behavior:
+- `maxRetries`: number; default: 10
+- `maxStalls`: 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
+
+Additional options affect failure handling:
+- `failHandler`: The path to a JavaScript module that exports the handler for failure jobs
+- `failRetryOptions`: Retry options (as above) for the failure jobs
+
+## Handlers
+
+Every handler module must have a named export `handle`, a function that is called with each job.
+
+### Task handlers
+
+It receives two arguments:
+- `data`, the JSON value passed to dispatch
+- `job`, a Job object contains the job attributes except 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.
+
+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.
+
+If it returns any value apart from a Promise that rejects, the job is considered to have completed successfully.
+
+### 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.
+
+If this function throws an error (or returns a Promise that rejects), it is retried using exponential backoff.

package/biome.json

@@ -0,0 +1,28 @@
+{
+    "$schema": "https://biomejs.dev/schemas/2.3.14/schema.json",
+    "assist": { "actions": { "source": { "organizeImports": "on" } } },
+    "linter": {
+        "enabled": true,
+        "rules": {
+            "recommended": true,
+            "complexity": {
+                "noForEach": "off"
+            },
+            "style": {
+                "useNodejsImportProtocol": "error"
+            }
+        }
+    },
+    "formatter": {
+        "enabled": true,
+        "indentStyle": "space",
+        "indentWidth": 4,
+        "lineWidth": 100
+    },
+    "javascript": {
+        "formatter": {
+            "quoteStyle": "single",
+            "trailingCommas": "es5"
+        }
+    }
+}

package/doc/Implementation.md

@@ -0,0 +1,70 @@
+## Implementation
+
+### Data structures
+
+Two sorted sets: `{queue}:waiting` and `{queue}:active`  
+Two hash families: `{queue}:waiting_job:{id}` and `{queue}:active_job:{id}`
+
+Hash fields: `data`, `max_retries`, `max_stalls`, `min_backoff`, `max_backoff`, `retry_count`, `stall_count`, and update flags (`update_data`, `update_run_at`, `update_retry_strategy`, `reset_counts`)
+
+**Waiting set**: members are job `id`, scores are `run_at` (or `-run_at` for blocked jobs)  
+**Active set**: members are `{id}:{worker_id}`, scores are heartbeat deadlines
+
+**Blocked jobs**: jobs with an active job sharing the same `id` (score is negative to prevent dequeuing)
+
+### Adding a job (dispatch)
+
+- HSET/HSETNX fields in `waiting_job:{id}` based on update flags
+- Check if `active_job:{id}` EXISTS to determine if blocked
+- Set score to `-run_at` if blocked, else `run_at`
+- If blocked, save update flags in waiting hash for later application
+- ZADD to waiting set with appropriate flags (NX, GT, LT, or none) based on `update_run_at`
+
+### Canceling a job (cancel)
+
+- ZREM from waiting set
+- DEL `waiting_job:{id}`
+
+### Dequeuing jobs (dequeue)
+
+- ZRANGEBYSCORE on waiting set for positive scores ≤ now
+- For each job: ZREM from waiting set, RENAME `waiting_job:{id}` to `active_job:{id}`
+- ZADD `{id}:{worker_id}` to active set with score = now + 10000ms
+
+### Heartbeat (bump)
+
+- ZADD `{id}:{worker_id}` to active set with score = now + 10000ms and XX flag (update only if exists)
+
+### Job completion (finish)
+
+- ZREM `{id}:{worker_id}` from active set
+- DEL `active_job:{id}`
+- If job exists in waiting set with negative score, flip score to positive and re-add with ZADD
+
+### Retriable failure (retry)
+
+- ZREM `{id}:{worker_id}` from active set
+- Increment `retry_count` in `active_job:{id}`
+- If `retry_count >= max_retries`, call fail; otherwise call do_retry
+
+### Retry logic (do_retry)
+
+- If blocked job exists in waiting: get its data, DEL waiting hash, RENAME active to waiting, ZADD with next_run_at, re-dispatch blocked job
+- Otherwise: RENAME active to waiting, ZADD with next_run_at
+
+### Permanent failure (fail)
+
+- Check if `{queue}-fail:waiting` EXISTS
+- If yes: generate new ID, create failure job with data `[original_id, job_data, error]`, dispatch to fail queue
+- Call finish to clean up
+
+### Stalled jobs (sweep)
+
+- ZRANGEBYSCORE on active set for scores ≤ now (limit 100)
+- For each stalled job: parse `{id}:{worker_id}`, call handle_stall
+
+### Stall handling (handle_stall)
+
+- ZREM from active set
+- Increment `stall_count` in `active_job:{id}`
+- If `stall_count >= max_stalls`, call fail; otherwise call do_retry

package/docker-compose.yml

@@ -0,0 +1,19 @@
+version: '3.8'
+
+services:
+  redis:
+    image: redis:7-alpine
+    container_name: queasy-redis
+    ports:
+      - '6379:6379'
+    command: redis-server --save 60 1 --loglevel warning
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  redis-data:

package/jsconfig.json

@@ -0,0 +1,17 @@
+{
+    "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/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "queasy",
+    "version": "0.1.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:watch": "node --test --watch",
+        "lint": "biome check .",
+        "lint:fix": "biome check --write .",
+        "format": "biome format --write .",
+        "typecheck": "tsc --noEmit -p jsconfig.json",
+        "docker:up": "docker compose up -d",
+        "docker:down": "docker compose down",
+        "docker:logs": "docker compose logs -f"
+    },
+    "keywords": [
+        "queue",
+        "redis",
+        "job",
+        "task",
+        "worker"
+    ],
+    "author": "",
+    "license": "ISC",
+    "peerDependencies": {
+        "redis": "^5.10.0"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.3.14",
+        "@types/node": "^25.2.0",
+        "redis": "^5.10.0",
+        "typescript": "^5.9.3"
+    }
+}