BeeQueueStore — Bee-Queue Redis-backed queue

BeeQueueStore — Bee-Queue Redis-backed queue Overview Bee-Queue is a fast, lightweight Redis-backed job queue, not a database. A single Queue object (bound to a queue name) both produces jobs — queue.createJob(data) built into a job, then .save()d — and consumes them via queue.process(handler). There is no query language and no SQL-shaped access pattern. Because none of that fits the SQL-shaped Dialect interface, BeeQueueStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes Bee-Queue's real create/process/getJob operations (enqueue/process/getJob/remove/stats) directly rather than forcing them into a query(sql) shape. Identity: Property | Value | --------- | ------------- | name | 'beequeue' | library | 'bee-queue' | Queue-scoped caching Each Bee-Queue queue is a distinct object per name. This store keeps a Map of one Queue per queue name (created and cached on first use) plus a Set tracking which names already have a process() handler registered. A second enqueue() on the same name reuses the cached Queue; because Bee-Queue allows only one process() per Queue object, a repeat process() on the same name is a no-op. All queues are closed and both collections cleared on disconnect(). Lazy loading — not a hard dependency bee-queue is not a hard dependency of this package. It is an optional peer, loaded lazily via require('bee-queue') inside connect() rather than a top-level import. Importing this module therefore does not require the driver to be installed — it is only needed when a Bee-Queue store is actually connected. Bee-Queue opens Redis connections per Queue; connect() here just resolves the Queue constructor. Injected client BeeQueueStoreOptions accepts a pre-built client — the bee-queue Queue constructor (its default export), or any stand-in. When provided, connect() adopts it directly and does not require('bee-queue'). This is how the test suite injects a mock (no driver, no network). Connection Build a store from connection options and call connect(): The settings object is passed to every Queue the store constructs. Failures resolving the driver are wrapped in a ConnectionError (a message containing ECONNREFUSED is normalized to 'Connection refused'). Option | Type | Purpose | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | settings | any | Bee-Queue settings passed to every Queue (e.g. { redis: { host, port } }, isWorker, removeOnSuccess). Defaults to { redis: { host: '127.0.0.1', port: 6379 } }. | client | any | A pre-built bee-queue Queue constructor (or stand-in). When set, the driver is not required. | Injected-client form Methods Driver failures are wrapped in a DatabaseError (message Bee-Queue <action> failed: ..., preserving the original error). Using the store before connect() (or after disconnect()) throws a ConnectionError. Lifecycle Method | Signature | Behavior | ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Adopts an injected client, otherwise lazy-requires bee-queue (resolving the Queue constructor). Idempotent when already connected. Wraps failures in ConnectionError. | disconnect | disconnect(): Promise<void> | close()s every cached Queue, clears the queue map and the processing set, and drops the constructor. | isConnected | isConnected(): boolean | true only when connected and the Queue constructor is present. | getClient | getClient(): any | Returns the underlying bee-queue Queue constructor. Throws ConnectionError if not connected. | Queue operations Method | Signature | Behavior | --------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | enqueue | enqueue(queue: string, jobData: unknown, opts?: BeeQueueEnqueueOptions): Promise<string> | Gets (or creates + caches) the Queue for queue, builds a job with queue.createJob(jobData), applies any retries/delayUntil/timeout via the chainable builder, .save()s it, and returns the assigned id. | process | process(queue: string, handler: (job: any) => any \| Promise<any>, opts?: BeeQueueProcessOptions): Promise<any> | Registers the worker handler via queue.process(concurrency, handler) (or queue.process(handler) when no concurrency). A repeat call on the same queue name is a no-op (Bee-Queue allows one process() per queue). Returns the Queue. | getJob | getJob(queue: string, id: string): Promise<any> | Fetches a job by id via queue.getJob(id). | remove | remove(queue: string, id: string): Promise<void> | Removes a job by id: uses queue.removeJob(id) when available, otherwise fetches the job and calls job.remove(). | stats | stats(queue: string): Promise<any> | Returns job counts by state via queue.getJobCounts() when available, otherwise falls back to queue.checkHealth(). | Supporting types: Example Verification status Unit / mock-verified only. The tests in tests/nosql/beequeue.test.ts are fully mock-driven: a fake Queue constructor whose instances expose spied createJob/process/getJob/removeJob/getJobCounts/close (and a chainable job with retries/delayUntil/timeout/save) is injected via BeeQueueStoreOptions.client, so connect() adopts it and skips require('bee-queue'). The real bee-queue package is not installed, and there is no live Redis and no network in the test run. What this proves: name/library identity and injected-constructor adoption without loading the driver. Lifecycle: ConnectionError when using the store before connecting. enqueue creating a job, applying retries/timeout via the chainable builder, saving, and returning the id; caching one Queue per name across enqueues. process registering the handler once per queue via queue.process(concurrency, handler) (repeat is a no-op). getJob delegating to queue.getJob; remove using queue.removeJob; stats returning getJobCounts(). Error handling: createJob/save failures wrapped in DatabaseError. What this does not prove: live execution against real Redis via Bee-Queue. Constructor/method shapes are verified against the driver's documented contract, but end-to-end execution over the wire has not been exercised here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories