bunqueue-client 0.1.4 → 0.1.6

package/dist/flow.js

@@ -4,6 +4,7 @@
  * UpdateParent fix-up, rollback via Cancel on failure).
  */
 import { Connection } from './connection.js';
+import { CommandError } from './errors.js';
 import { compact } from './frame.js';
 import { Job } from './job.js';
 import { jobPayload, wireJobOptions } from './types.js';
@@ -13,7 +14,14 @@ export class FlowProducer {
     constructor(opts = {}) {
         this.connection =
             opts.connection ??
-                new Connection({ host: opts.host, port: opts.port, token: opts.token, tls: opts.tls });
+                new Connection({
+                    host: opts.host,
+                    port: opts.port,
+                    token: opts.token,
+                    tls: opts.tls,
+                    logger: opts.logger,
+                    onTelemetry: opts.onTelemetry,
+                });
         this.ownsConnection = opts.connection === undefined;
     }
     /** Add a flow tree. Children are created (and processed) BEFORE their parent. */
@@ -43,7 +51,7 @@ export class FlowProducer {
     }
     /** Fetch a flow tree starting from a job id (recursive over childrenIds). */
     getFlow(opts) {
-        return this.fetchNode(opts.id, opts.depth ?? Number.POSITIVE_INFINITY, opts.maxChildren);
+        return this.fetchNode(opts.id, opts.depth ?? Number.POSITIVE_INFINITY, opts.maxChildren, new Set());
     }
     /** Add a sequential chain: step[0] → step[1] → ... via dependsOn. */
     async addChain(steps) {
@@ -57,13 +65,15 @@ export class FlowProducer {
                     ...jobPayload(step.name, step.data),
                     __flowParentId: prevId ?? undefined,
                 });
-                const response = await this.connection.call(compact({
+                // Connection.call compacts internally, so no outer compact() is needed
+                // (nesting it confused generic inference of `data`/`response`).
+                const response = await this.connection.call({
                     cmd: 'PUSH',
                     queue: step.queueName,
                     data,
                     ...wireJobOptions(step.opts),
                     dependsOn: prevId ? [prevId] : undefined,
-                }));
+                });
                 const id = String(response.id);
                 jobIds.push(id);
                 prevId = id;
@@ -156,8 +166,24 @@ export class FlowProducer {
         }
         return parentJobId;
     }
-    async fetchNode(id, depth, maxChildren) {
-        const response = await this.connection.call({ cmd: 'GetJob', id });
+    async fetchNode(id, depth, maxChildren, visited) {
+        if (visited.has(id))
+            return null; // cycle guard: id already on the current path
+        visited.add(id);
+        // A missing job — the root, or a child removed via removeOnComplete/cancel
+        // (childrenIds is a static push-time list, never pruned) — yields null and
+        // is skipped, returning the surviving partial tree instead of throwing.
+        let response;
+        try {
+            response = await this.connection.call({ cmd: 'GetJob', id });
+        }
+        catch (err) {
+            // Only 'Job not found' means a removed node; a real server error must not
+            // masquerade as a missing child and yield a misleading partial tree.
+            if (err instanceof CommandError && /not found/i.test(err.message))
+                return null;
+            throw err;
+        }
         const raw = response.job;
         if (!raw)
             return null;
@@ -167,7 +193,7 @@ export class FlowProducer {
         const limit = maxChildren ?? job.childrenIds.length;
         const children = [];
         for (const childId of job.childrenIds.slice(0, limit)) {
-            const child = await this.fetchNode(childId, depth - 1, maxChildren);
+            const child = await this.fetchNode(childId, depth - 1, maxChildren, visited);
             if (child)
                 children.push(child);
         }

package/dist/index.d.ts

@@ -7,16 +7,21 @@ export type { DlqFilter, DlqStats } from './bunqueue/dlq-rate-limit.js';
 export type { BatchConfig, BatchProcessor, BunqueueConnection, BunqueueDebounceConfig, BunqueueDeduplicationConfig, BunqueueDlqConfig, BunqueueMiddleware, BunqueueOptions, CircuitBreakerConfig, CircuitState, JobTtlConfig, PriorityAgingConfig, RateLimiterOptions, RetryConfig, RetryStrategy, TriggerRule, } from './bunqueue/types.js';
 export type { Command, ConnectionOptions, Response, TlsOption } from './connection.js';
 export { Connection } from './connection.js';
+export { ConnectionPool } from './connection-pool.js';
+export type { ConnectionLike } from './connection-types.js';
 export { AuthError, BunqueueError, CommandError, CommandTimeoutError, ConnectionClosedError, UnrecoverableError, } from './errors.js';
 export { FlowProducer } from './flow.js';
 export type { FlowJob, FlowProducerOptions, FlowStep, GetFlowOptions, JobNode, } from './flow-types.js';
 export { MAX_FRAME_SIZE, PROTOCOL_VERSION } from './frame.js';
 export type { JobRaw } from './job.js';
 export { Job } from './job.js';
+export type { Logger, LogLevel, Observability, TelemetryEvent, TelemetryHandler, } from './observability.js';
+export { consoleLogger, noopLogger } from './observability.js';
 export type { BulkJobEntry, QueueOptions } from './queue.js';
 export { Queue } from './queue.js';
 export type { SchedulerOptions } from './queue-admin.js';
+export type { BatchResponse, CountResponse, DataResponse, JobCountsResponse, JobResponse, JobsResponse, OkResponse, PausedResponse, ProgressResponse, PulledJobResponse, PulledJobsResponse, ResultResponse, StateResponse, WaitJobResponse, } from './responses.js';
 export type { BackoffOptions, DeduplicationOptions, JobCounts, JobOptions, JobStateName, RepeatOptions, } from './types.js';
 export { Worker } from './worker.js';
-export type { Processor, WorkerOptions } from './worker-types.js';
-export declare const __version__ = "0.1.2";
+export type { AckBatchOptions, Processor, WorkerOptions } from './worker-types.js';
+export declare const __version__ = "0.1.6";

package/dist/index.js

@@ -5,10 +5,12 @@
 // Simple Mode (Bunqueue): all-in-one Queue + Worker, 1:1 with the official client
 export { Bunqueue } from './bunqueue/bunqueue.js';
 export { Connection } from './connection.js';
+export { ConnectionPool } from './connection-pool.js';
 export { AuthError, BunqueueError, CommandError, CommandTimeoutError, ConnectionClosedError, UnrecoverableError, } from './errors.js';
 export { FlowProducer } from './flow.js';
 export { MAX_FRAME_SIZE, PROTOCOL_VERSION } from './frame.js';
 export { Job } from './job.js';
+export { consoleLogger, noopLogger } from './observability.js';
 export { Queue } from './queue.js';
 export { Worker } from './worker.js';
-export const __version__ = '0.1.2';
+export const __version__ = '0.1.6';

package/dist/job.d.ts

@@ -2,7 +2,7 @@
  * Job wrapper: read view over the server job record + per-job operations.
  * Mirrors the official TS client's Job surface (TCP mode).
  */
-import type { Connection } from './connection.js';
+import type { ConnectionLike } from './connection-types.js';
 export type JobRaw = Record<string, unknown>;
 export type ProgressHook = (job: Job, progress: number) => void;
 export declare class Job<T = unknown> {
@@ -10,7 +10,7 @@ export declare class Job<T = unknown> {
     readonly token: string | undefined;
     private readonly conn;
     private readonly onProgress;
-    constructor(raw: JobRaw, connection?: Connection, token?: string, onProgress?: ProgressHook);
+    constructor(raw: JobRaw, connection?: ConnectionLike, token?: string, onProgress?: ProgressHook);
     get id(): string;
     get queue(): string;
     get data(): T;

package/dist/observability.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Observability primitives: a pluggable structured logger and a telemetry
+ * sink. Zero hard dependencies — wire your own OpenTelemetry / Prometheus /
+ * logging stack through these interfaces. Defaults are no-ops, so the SDK is
+ * silent unless you opt in.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Logger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/** Silent logger (the default). */
+export declare const noopLogger: Logger;
+/**
+ * A console-backed logger. Levels below `min` are dropped. Opt-in — pass it as
+ * `logger` when you want the SDK to log to the console.
+ */
+export declare function consoleLogger(min?: LogLevel): Logger;
+/** A single telemetry data point. A discriminated union keyed on `type`. */
+export type TelemetryEvent = {
+    type: 'command';
+    cmd: string;
+    reqId: string;
+    durationMs: number;
+    ok: boolean;
+} | {
+    type: 'command_timeout';
+    cmd: string;
+    reqId: string;
+} | {
+    type: 'connect';
+    host: string;
+    port: number;
+    generation: number;
+    durationMs: number;
+} | {
+    type: 'disconnect';
+    host: string;
+    port: number;
+    generation: number;
+} | {
+    type: 'reconnect_scheduled';
+    host: string;
+    port: number;
+    attempt: number;
+    delayMs: number;
+} | {
+    type: 'auth';
+    ok: boolean;
+} | {
+    type: 'backpressure';
+    inFlight: number;
+    maxInFlight: number;
+};
+export type TelemetryHandler = (event: TelemetryEvent) => void;
+/** Lifecycle telemetry types that are ALSO emitted as EventEmitter events. */
+export declare const LIFECYCLE_EVENTS: readonly ["connect", "disconnect", "reconnect_scheduled"];
+export interface Observability {
+    /** Structured logger; defaults to {@link noopLogger}. */
+    logger?: Logger;
+    /**
+     * Telemetry sink for metrics and tracing. Receives every command's latency,
+     * connect/disconnect/reconnect, auth and backpressure events. Bridge it to
+     * OpenTelemetry spans or Prometheus counters without the SDK depending on
+     * either.
+     */
+    onTelemetry?: TelemetryHandler;
+}
+/** High-resolution monotonic clock (Node/Bun/Deno all expose `performance`). */
+export declare const nowMs: () => number;
+/**
+ * Fans a telemetry event out to (1) the telemetry sink, (2) the logger, and
+ * (3) — for lifecycle events — the owning EventEmitter, so users can both
+ * scrape metrics and attach imperative `connection.on('connect', …)` handlers.
+ */
+export declare class Telemetry {
+    private readonly logger;
+    private readonly sink;
+    private readonly emit;
+    constructor(obs: Observability | undefined, emit: (event: string, payload: unknown) => void);
+    /** Observability must never break the client: swallow consumer errors. */
+    private static safely;
+    get log(): Logger;
+    /** Record a completed command's latency and outcome. */
+    command(cmd: string, reqId: string, startMs: number, ok: boolean): void;
+    timeout(cmd: string, reqId: string): void;
+    connected(host: string, port: number, generation: number, startMs: number): void;
+    disconnected(host: string, port: number, generation: number): void;
+    reconnectScheduled(host: string, port: number, attempt: number, delayMs: number): void;
+    auth(ok: boolean): void;
+    backpressure(inFlight: number, maxInFlight: number): void;
+    private dispatch;
+}

package/dist/observability.js

@@ -0,0 +1,110 @@
+/**
+ * Observability primitives: a pluggable structured logger and a telemetry
+ * sink. Zero hard dependencies — wire your own OpenTelemetry / Prometheus /
+ * logging stack through these interfaces. Defaults are no-ops, so the SDK is
+ * silent unless you opt in.
+ */
+/** Silent logger (the default). */
+export const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+/**
+ * A console-backed logger. Levels below `min` are dropped. Opt-in — pass it as
+ * `logger` when you want the SDK to log to the console.
+ */
+export function consoleLogger(min = 'info') {
+    const floor = LEVELS[min];
+    const line = (lvl, msg, meta) => {
+        if (LEVELS[lvl] < floor)
+            return;
+        const suffix = meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';
+        const sink = lvl === 'debug' ? console.log : console[lvl];
+        sink(`[bunqueue] ${lvl} ${msg}${suffix}`);
+    };
+    return {
+        debug: (m, meta) => line('debug', m, meta),
+        info: (m, meta) => line('info', m, meta),
+        warn: (m, meta) => line('warn', m, meta),
+        error: (m, meta) => line('error', m, meta),
+    };
+}
+/** Lifecycle telemetry types that are ALSO emitted as EventEmitter events. */
+export const LIFECYCLE_EVENTS = ['connect', 'disconnect', 'reconnect_scheduled'];
+/** High-resolution monotonic clock (Node/Bun/Deno all expose `performance`). */
+export const nowMs = () => performance.now();
+/**
+ * Fans a telemetry event out to (1) the telemetry sink, (2) the logger, and
+ * (3) — for lifecycle events — the owning EventEmitter, so users can both
+ * scrape metrics and attach imperative `connection.on('connect', …)` handlers.
+ */
+export class Telemetry {
+    logger;
+    sink;
+    emit;
+    constructor(obs, emit) {
+        // Wrap the user logger so a throwing logger can never break the transport
+        // hot path (dispatch runs inside socket 'data' handlers and connect).
+        const inner = obs?.logger ?? noopLogger;
+        this.logger =
+            inner === noopLogger
+                ? inner
+                : {
+                    debug: (m, meta) => Telemetry.safely(() => inner.debug(m, meta)),
+                    info: (m, meta) => Telemetry.safely(() => inner.info(m, meta)),
+                    warn: (m, meta) => Telemetry.safely(() => inner.warn(m, meta)),
+                    error: (m, meta) => Telemetry.safely(() => inner.error(m, meta)),
+                };
+        this.sink = obs?.onTelemetry;
+        this.emit = emit;
+    }
+    /** Observability must never break the client: swallow consumer errors. */
+    static safely(fn) {
+        try {
+            fn();
+        }
+        catch {
+            /* consumer logging/telemetry error — intentionally ignored */
+        }
+    }
+    get log() {
+        return this.logger;
+    }
+    /** Record a completed command's latency and outcome. */
+    command(cmd, reqId, startMs, ok) {
+        this.dispatch({ type: 'command', cmd, reqId, durationMs: nowMs() - startMs, ok });
+    }
+    timeout(cmd, reqId) {
+        this.logger.warn('command timed out', { cmd, reqId });
+        this.dispatch({ type: 'command_timeout', cmd, reqId });
+    }
+    connected(host, port, generation, startMs) {
+        this.logger.info('connected', { host, port, generation });
+        this.dispatch({ type: 'connect', host, port, generation, durationMs: nowMs() - startMs });
+    }
+    disconnected(host, port, generation) {
+        this.logger.info('disconnected', { host, port, generation });
+        this.dispatch({ type: 'disconnect', host, port, generation });
+    }
+    reconnectScheduled(host, port, attempt, delayMs) {
+        this.logger.warn('reconnect scheduled', { host, port, attempt, delayMs });
+        this.dispatch({ type: 'reconnect_scheduled', host, port, attempt, delayMs });
+    }
+    auth(ok) {
+        this.dispatch({ type: 'auth', ok });
+    }
+    backpressure(inFlight, maxInFlight) {
+        this.dispatch({ type: 'backpressure', inFlight, maxInFlight });
+    }
+    dispatch(event) {
+        // A throwing sink or lifecycle listener must never break the transport:
+        // dispatch runs inside socket 'data' handlers and the connect path.
+        Telemetry.safely(() => this.sink?.(event));
+        if (LIFECYCLE_EVENTS.includes(event.type)) {
+            Telemetry.safely(() => this.emit(event.type, event));
+        }
+    }
+}

package/dist/queue-control.js

@@ -11,8 +11,7 @@ export const controlMethods = {
         await this.call({ cmd: 'Resume', queue: this.name });
     },
     async isPaused() {
-        const response = await this.call({ cmd: 'IsPaused', queue: this.name });
-        return response.paused === true;
+        return (await this.call({ cmd: 'IsPaused', queue: this.name })).paused === true;
     },
     async drain() {
         await this.call({ cmd: 'Drain', queue: this.name });
@@ -23,7 +22,7 @@ export const controlMethods = {
     /** Remove old jobs; returns how many were removed. */
     async clean(graceMs, limit, state) {
         const response = await this.call(compact({ cmd: 'Clean', queue: this.name, grace: graceMs, limit, state }));
-        return Number(response.count ?? 0);
+        return response.count ?? 0;
     },
     async remove(id) {
         await this.call({ cmd: 'Cancel', id });
@@ -37,7 +36,7 @@ export const controlMethods = {
     /** Promote delayed jobs to waiting; returns how many were promoted. */
     async promoteJobs(opts = {}) {
         const response = await this.call(compact({ cmd: 'PromoteJobs', queue: this.name, count: opts.count }));
-        return Number(response.count ?? 0);
+        return response.count ?? 0;
     },
     /** BullMQ contract: failed → waiting. */
     async retryJob(id) {
@@ -48,7 +47,9 @@ export const controlMethods = {
             await this.call({ cmd: 'RetryCompleted', queue: this.name });
             return;
         }
-        await this.call(compact({ cmd: 'RetryDlq', queue: this.name, count: opts.count }));
+        // `count` is accepted for API parity but not sent: the server has no
+        // partial RetryDlq — it retries the whole DLQ (BullMQ semantics).
+        await this.call({ cmd: 'RetryDlq', queue: this.name });
     },
     async retryCompleted(id) {
         await this.call(compact({ cmd: 'RetryCompleted', queue: this.name, id }));

package/dist/queue-query.d.ts

@@ -32,7 +32,14 @@ export declare const queryMethods: {
     removeChildDependency(this: Ctx, id: string): Promise<void>;
     /** Remove all still-unprocessed children of a parent job. */
     removeUnprocessedChildren(this: Ctx, id: string): Promise<void>;
-    /** Block until the job finishes; returns its result. */
+    /**
+     * Block until the job completes; returns its result.
+     * The server's WaitJob waiter resolves only on completion, replying
+     * `{ok:true, completed:false}` (no result) otherwise — so returning undefined
+     * would be indistinguishable from a genuine undefined result. On
+     * non-completion we probe the state: a `failed` job throws CommandError (it
+     * will not complete), everything else throws CommandTimeoutError.
+     */
     waitForJob<R = unknown>(this: Ctx, id: string, ttlMs?: number): Promise<R>;
     /** BullMQ v5 alias for waitForJob (queueEvents param unused over TCP). */
     waitJobUntilFinished<R = unknown>(this: Ctx, id: string, _queueEvents?: unknown, ttlMs?: number): Promise<R>;
@@ -50,7 +57,7 @@ export declare const queryMethods: {
     getWaitingChildrenCount(this: Ctx): Promise<number>;
     count(this: Ctx): Promise<number>;
     getCountsPerPriority(this: Ctx): Promise<Record<string, number>>;
-    addJobLog(this: Ctx, id: string, message: string): Promise<void>;
+    addJobLog(this: Ctx, id: string, message: string, level?: "info" | "warn" | "error"): Promise<void>;
     getJobLogs(this: Ctx, id: string, start?: number, end?: number): Promise<string[]>;
     clearJobLogs(this: Ctx, id: string, keepLogs?: number): Promise<void>;
 };

package/dist/queue-query.js

@@ -2,7 +2,7 @@
  * Queue query surface: job lookup, state, results, counts, logs, children.
  * Methods are merged onto Queue.prototype by queue.ts.
  */
-import { CommandError } from './errors.js';
+import { CommandError, CommandTimeoutError } from './errors.js';
 import { compact } from './frame.js';
 import { Job } from './job.js';
 function unwrapValues(response) {
@@ -13,8 +13,7 @@ export const queryMethods = {
     async getJob(id) {
         try {
             const response = await this.call({ cmd: 'GetJob', id });
-            const raw = response.job;
-            return raw ? new Job(raw, this.connection) : null;
+            return response.job ? new Job(response.job, this.connection) : null;
         }
         catch (err) {
             if (err instanceof CommandError)
@@ -25,8 +24,7 @@ export const queryMethods = {
     async getJobByCustomId(customId) {
         try {
             const response = await this.call({ cmd: 'GetJobByCustomId', customId });
-            const raw = response.job;
-            return raw ? new Job(raw, this.connection) : null;
+            return response.job ? new Job(response.job, this.connection) : null;
         }
         catch (err) {
             if (err instanceof CommandError)
@@ -49,11 +47,12 @@ export const queryMethods = {
             offset: start,
             limit: end - start,
         }));
-        const jobs = (response.jobs ?? []);
-        return jobs.map((raw) => new Job(raw, this.connection));
+        return (response.jobs ?? []).map((raw) => new Job(raw, this.connection));
     },
     getWaiting(start, end) {
-        return this.getJobs({ state: ['waiting', 'prioritized'], start, end });
+        // Only the 'waiting' bucket — prioritized jobs live in a separate bucket
+        // (getPrioritized), matching BullMQ and the Python SDK / reference client.
+        return this.getJobs({ state: 'waiting', start, end });
     },
     getDelayed(start, end) {
         return this.getJobs({ state: 'delayed', start, end });
@@ -74,12 +73,10 @@ export const queryMethods = {
         return this.getJobs({ state: 'waiting-children', start, end });
     },
     async getJobState(id) {
-        const response = await this.call({ cmd: 'GetState', id });
-        return String(response.state);
+        return (await this.call({ cmd: 'GetState', id })).state;
     },
     async getResult(id) {
-        const response = await this.call({ cmd: 'GetResult', id });
-        return response.result;
+        return (await this.call({ cmd: 'GetResult', id })).result;
     },
     async getChildrenValues(id) {
         return unwrapValues(await this.call({ cmd: 'GetChildrenValues', id }));
@@ -98,9 +95,28 @@ export const queryMethods = {
     async removeUnprocessedChildren(id) {
         await this.call({ cmd: 'RemoveUnprocessedChildren', id });
     },
-    /** Block until the job finishes; returns its result. */
+    /**
+     * Block until the job completes; returns its result.
+     * The server's WaitJob waiter resolves only on completion, replying
+     * `{ok:true, completed:false}` (no result) otherwise — so returning undefined
+     * would be indistinguishable from a genuine undefined result. On
+     * non-completion we probe the state: a `failed` job throws CommandError (it
+     * will not complete), everything else throws CommandTimeoutError.
+     */
     async waitForJob(id, ttlMs = 30_000) {
         const response = await this.call({ cmd: 'WaitJob', id, timeout: ttlMs }, ttlMs + 5000);
+        if (response.completed !== true) {
+            let state;
+            try {
+                state = await this.getJobState(id);
+            }
+            catch {
+                /* ignore probe failure; fall through to timeout */
+            }
+            if (state === 'failed')
+                throw new CommandError(`job ${id} failed before completion`);
+            throw new CommandTimeoutError(`waitUntilFinished timed out after ${ttlMs}ms`);
+        }
         return response.result;
     },
     /** BullMQ v5 alias for waitForJob (queueEvents param unused over TCP). */
@@ -109,19 +125,16 @@ export const queryMethods = {
     },
     async getProgress(id) {
         const response = await this.call({ cmd: 'GetProgress', id });
-        return {
-            progress: Number(response.progress ?? 0),
-            message: response.message ?? null,
-        };
+        return { progress: response.progress ?? 0, message: response.message ?? null };
     },
     // ------------------------------------------------------------------- counts
     async getJobCounts() {
-        const response = await this.call({ cmd: 'GetJobCounts', queue: this.name });
-        return response.counts;
+        return (await this.call({ cmd: 'GetJobCounts', queue: this.name })).counts;
     },
     async getWaitingCount() {
-        const counts = await this.getJobCounts();
-        return counts.waiting + counts.prioritized;
+        // 'waiting' only — prioritized jobs are counted by getPrioritizedCount,
+        // matching BullMQ and the Python SDK / reference client.
+        return (await this.getJobCounts()).waiting;
     },
     async getActiveCount() {
         return (await this.getJobCounts()).active;
@@ -142,22 +155,27 @@ export const queryMethods = {
         return (await this.getJobCounts())['waiting-children'];
     },
     async count() {
-        const response = await this.call({ cmd: 'Count', queue: this.name });
-        return Number(response.count ?? 0);
+        return (await this.call({ cmd: 'Count', queue: this.name })).count ?? 0;
     },
     async getCountsPerPriority() {
         const response = await this.call({ cmd: 'GetCountsPerPriority', queue: this.name });
         return (response.counts ?? response.data ?? {});
     },
     // --------------------------------------------------------------------- logs
-    async addJobLog(id, message) {
-        await this.call({ cmd: 'AddLog', id, message });
+    async addJobLog(id, message, level) {
+        await this.call(compact({ cmd: 'AddLog', id, message, level }));
     },
     async getJobLogs(id, start, end) {
         const response = await this.call(compact({ cmd: 'GetLogs', id, start, end }));
         const data = (response.data ?? {});
         const logs = (data.logs ?? response.logs ?? []);
-        return logs.map((row) => (typeof row === 'string' ? row : String(row.message ?? row)));
+        // Format as `[level] message` (reference client parity); never drop level.
+        return logs.map((row) => {
+            if (typeof row === 'string')
+                return row;
+            const r = row;
+            return r.level ? `[${r.level}] ${r.message}` : String(r.message ?? row);
+        });
     },
     async clearJobLogs(id, keepLogs) {
         await this.call(compact({ cmd: 'ClearLogs', id, keepLogs }));

package/dist/queue.d.ts

@@ -9,18 +9,27 @@
  * exposes them on the type.
  */
 import { Connection, type Response, type TlsOption } from './connection.js';
+import type { ConnectionLike } from './connection-types.js';
 import { Job } from './job.js';
+import type { Observability } from './observability.js';
 import { type QueueAdminApi } from './queue-admin.js';
 import { type QueueControlApi } from './queue-control.js';
 import { type QueueQueryApi } from './queue-query.js';
 import { type JobOptions } from './types.js';
-export interface QueueOptions {
+export interface QueueOptions extends Observability {
     host?: string;
     port?: number;
     token?: string;
     tls?: TlsOption;
     connection?: Connection;
     commandTimeoutMs?: number;
+    /** Max in-flight commands before backpressure kicks in (0 = unbounded). */
+    maxInFlight?: number;
+    /**
+     * Fan producer commands across N connections (round-robin) for throughput.
+     * >1 builds a ConnectionPool; default 1 = a single connection.
+     */
+    poolSize?: number;
 }
 export interface BulkJobEntry<T = unknown> {
     name: string;
@@ -29,13 +38,13 @@ export interface BulkJobEntry<T = unknown> {
 }
 export declare class Queue<T = unknown> {
     readonly name: string;
-    readonly connection: Connection;
+    readonly connection: ConnectionLike;
     private readonly ownsConnection;
     constructor(name: string, opts?: QueueOptions);
     /** Send a raw command on this queue's connection (used by area modules). */
-    call(command: Record<string, unknown> & {
+    call<R = Response>(command: Record<string, unknown> & {
         cmd: string;
-    }, timeoutMs?: number): Promise<Response>;
+    }, timeoutMs?: number): Promise<R>;
     /** Add a job; returns a Job stub carrying the assigned id. */
     add(name: string, data: T, opts?: JobOptions): Promise<Job<T>>;
     /** Add many jobs in one round-trip; returns Job stubs. */