bunqueue-client 0.1.9 → 0.2.0

package/src/legacy.ts

@@ -0,0 +1,91 @@
+/**
+ * bunqueue-client — cross-runtime TypeScript SDK for bunqueue (TCP mode).
+ * Works on Node.js ≥20, Bun and Deno ≥2 (uses only node: builtins + msgpackr).
+ */
+
+// Simple Mode (Bunqueue): all-in-one Queue + Worker, 1:1 with the official client
+export { Bunqueue } from './bunqueue/bunqueue.js';
+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,
+  SerializationError,
+  UnrecoverableError,
+} from './errors.js';
+export { FlowProducer } from './flow.js';
+export type {
+  FlowJob,
+  FlowOptions,
+  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,
+  TelemetryErrorOperation,
+  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 { AckBatchOptions, Processor, WorkerEventMap, WorkerOptions } from './worker-types.js';
+
+export const __version__ = '0.2.0';

package/src/observability.ts

@@ -45,6 +45,8 @@ export function consoleLogger(min: LogLevel = 'info'): Logger {
 }
 
 /** A single telemetry data point. A discriminated union keyed on `type`. */
+export type TelemetryErrorOperation = 'connect' | 'socket' | 'write' | 'serialization';
+
 export type TelemetryEvent =
   | { type: 'command'; cmd: string; reqId: string; durationMs: number; ok: boolean }
   | { type: 'command_timeout'; cmd: string; reqId: string }
@@ -52,7 +54,14 @@ export type TelemetryEvent =
   | { 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 };
+  | { type: 'backpressure'; inFlight: number; maxInFlight: number }
+  | {
+      type: 'error';
+      operation: TelemetryErrorOperation;
+      errorType: string;
+      message: string;
+      code?: string;
+    };
 
 export type TelemetryHandler = (event: TelemetryEvent) => void;
 
@@ -74,6 +83,13 @@ export interface Observability {
 /** High-resolution monotonic clock (Node/Bun/Deno all expose `performance`). */
 export const nowMs = (): number => performance.now();
 
+const ERROR_MESSAGES: Record<TelemetryErrorOperation, string> = {
+  connect: 'connection failed',
+  socket: 'socket failed',
+  write: 'socket write failed',
+  serialization: 'command serialization failed',
+};
+
 /**
  * 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
@@ -147,6 +163,48 @@ export class Telemetry {
     this.dispatch({ type: 'backpressure', inFlight, maxInFlight });
   }
 
+  /**
+   * Report transport failures without forwarding raw messages: those can
+   * contain remote-controlled text or application data in third-party errors.
+   */
+  error(operation: TelemetryErrorOperation, error: unknown): void {
+    const errorType =
+      error instanceof Error && /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(error.name)
+        ? error.name
+        : 'Error';
+    const rawCode =
+      typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+    const code =
+      typeof rawCode === 'string' && /^[A-Z0-9_]{1,32}$/.test(rawCode) ? rawCode : undefined;
+    const event: TelemetryEvent = {
+      type: 'error',
+      operation,
+      errorType,
+      message: ERROR_MESSAGES[operation],
+      ...(code ? { code } : {}),
+    };
+    this.logger.error(event.message, { operation, errorType, ...(code ? { code } : {}) });
+    this.dispatch(event);
+  }
+
+  capture<T>(operation: TelemetryErrorOperation, fn: () => T): T {
+    try {
+      return fn();
+    } catch (error) {
+      this.error(operation, error);
+      throw error;
+    }
+  }
+
+  async captureAsync<T>(operation: TelemetryErrorOperation, promise: Promise<T>): Promise<T> {
+    try {
+      return await promise;
+    } catch (error) {
+      this.error(operation, error);
+      throw error;
+    }
+  }
+
   private dispatch(event: TelemetryEvent): void {
     // A throwing sink or lifecycle listener must never break the transport:
     // dispatch runs inside socket 'data' handlers and the connect path.

package/src/queue-admin.ts

@@ -6,7 +6,7 @@
 import { CommandError } from './errors.js';
 import { compact } from './frame.js';
 import type { Queue } from './queue.js';
-import { type JobOptions, jobPayload, wireJobOptions } from './types.js';
+import { type JobOptions, wireJobOptions } from './types.js';
 
 type Ctx = Queue<unknown>;
 type Raw = Record<string, unknown>;
@@ -70,9 +70,8 @@ export const adminMethods = {
 
   // -------------------------------------------------- rate limit / concurrency
 
-  /** `duration` accepted for signature parity; the TCP wire carries only `limit`. */
-  async setGlobalRateLimit(this: Ctx, max: number, _duration?: number): Promise<void> {
-    await this.call({ cmd: 'RateLimit', queue: this.name, limit: max });
+  async setGlobalRateLimit(this: Ctx, max: number, duration?: number): Promise<void> {
+    await this.call({ cmd: 'RateLimit', queue: this.name, limit: max, duration });
   },
 
   async removeGlobalRateLimit(this: Ctx): Promise<void> {
@@ -104,8 +103,9 @@ export const adminMethods = {
       compact({
         cmd: 'Cron',
         name: schedulerId,
+        jobName: template.name ?? schedulerId,
         queue: this.name,
-        data: jobPayload(template.name ?? schedulerId, template.data ?? {}),
+        data: 'data' in template ? template.data : {},
         schedule: repeat.pattern,
         repeatEvery: repeat.every,
         priority: template.opts?.priority,

package/src/queue-control.ts

@@ -110,16 +110,18 @@ export const controlMethods = {
     await this.call({ cmd: 'ChangePriority', id, priority: opts.priority, lifo: opts.lifo });
   },
 
-  async changeJobDelay(this: Ctx, id: string, delayMs: number): Promise<void> {
-    await this.call({ cmd: 'ChangeDelay', id, delay: delayMs });
+  async changeJobDelay(this: Ctx, id: string, delayMs: number, token?: string): Promise<void> {
+    await this.call(compact({ cmd: 'ChangeDelay', id, delay: delayMs, token }) as { cmd: string });
   },
 
-  async moveJobToWait(this: Ctx, id: string): Promise<void> {
-    await this.call({ cmd: 'MoveToWait', id });
+  async moveJobToWait(this: Ctx, id: string, token?: string): Promise<void> {
+    await this.call(compact({ cmd: 'MoveToWait', id, token }) as { cmd: string });
   },
 
-  async moveJobToDelayed(this: Ctx, id: string, delayMs: number): Promise<void> {
-    await this.call({ cmd: 'MoveToDelayed', id, delay: delayMs });
+  async moveJobToDelayed(this: Ctx, id: string, delayMs: number, token?: string): Promise<void> {
+    await this.call(
+      compact({ cmd: 'MoveToDelayed', id, delay: delayMs, token }) as { cmd: string }
+    );
   },
 
   async extendJobLock(this: Ctx, id: string, token: string, durationMs: number): Promise<void> {

package/src/queue.ts

@@ -41,7 +41,7 @@ export interface BulkJobEntry<T = unknown> {
   opts?: JobOptions;
 }
 
-// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: prototype-mixin composition — Object.assign at the bottom installs exactly the methods the merged interface declares
+// oxlint-disable-next-line typescript/no-unsafe-declaration-merging -- prototype-mixin composition installs the declared methods with Object.assign below
 export class Queue<T = unknown> {
   readonly name: string;
   readonly connection: ConnectionLike;
@@ -83,10 +83,10 @@ export class Queue<T = unknown> {
     const response = await this.call({
       cmd: 'PUSH',
       queue: this.name,
-      data: payload,
+      ...payload,
       ...wireJobOptions(opts),
     });
-    return new Job<T>({ id: response.id, queue: this.name, data: payload }, this.connection);
+    return new Job<T>({ id: response.id, queue: this.name, ...payload }, this.connection);
   }
 
   /** Add many jobs in one round-trip; returns Job stubs. */
@@ -101,12 +101,16 @@ export class Queue<T = unknown> {
         opts.customId = opts.jobId;
         delete opts.jobId;
       }
-      return { data: jobPayload(entry.name, entry.data), ...opts };
+      return { ...jobPayload(entry.name, entry.data), ...opts };
     });
     const response = await this.call({ cmd: 'PUSHB', queue: this.name, jobs: inputs });
     const ids = (response.ids ?? []) as string[];
     return ids.map(
-      (id, i) => new Job<T>({ id, queue: this.name, data: inputs[i].data }, this.connection)
+      (id, i) =>
+        new Job<T>(
+          { id, queue: this.name, name: inputs[i].name, data: inputs[i].data },
+          this.connection
+        )
     );
   }
 
@@ -134,6 +138,6 @@ export class Queue<T = unknown> {
  * The declaration merging is intentional and safe: Object.assign below
  * installs exactly the methods the interface declares. The unused type
  * parameter is required — merged interfaces must repeat the class generics. */
-// biome-ignore lint/correctness/noUnusedVariables: generic must match the class declaration
+// oxlint-disable-next-line no-unused-vars -- generic must match the class declaration
 export interface Queue<T = unknown> extends QueueQueryApi, QueueControlApi, QueueAdminApi {}
 Object.assign(Queue.prototype, queryMethods, controlMethods, adminMethods);

package/src/serialization.ts

@@ -0,0 +1,93 @@
+/** Safe command serialization for the bunqueue wire protocol. */
+
+import { pack } from 'msgpackr';
+import type { Command } from './connection-types.js';
+import { SerializationError } from './errors.js';
+import { frame } from './frame.js';
+
+const invalid = (reason: string): never => {
+  throw new SerializationError(`cannot serialize command as MessagePack: ${reason}`);
+};
+
+function normalizeWireValue(value: unknown, active: WeakSet<object>): unknown {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) invalid('numbers must be finite');
+    return value;
+  }
+  if (typeof value === 'bigint') invalid('BigInt is not JavaScript-safe on the broker');
+  if (typeof value === 'undefined') invalid('nested undefined values are not portable');
+  if (typeof value === 'symbol' || typeof value === 'function') {
+    invalid(`${typeof value} values are unsupported`);
+  }
+  if (typeof value !== 'object') invalid('unsupported value');
+  const objectValue = value as object;
+
+  if (value instanceof Date) {
+    if (!Number.isFinite(value.getTime())) invalid('invalid Date');
+    return new Date(value.getTime());
+  }
+  if (value instanceof Uint8Array || value instanceof ArrayBuffer) return value;
+  if (active.has(objectValue)) invalid('cyclic structures are unsupported');
+  active.add(objectValue);
+  try {
+    if (Array.isArray(value)) {
+      return Array.from(value, (entry) => normalizeWireValue(entry, active));
+    }
+    if (value instanceof Map) {
+      const normalized = new Map<string, unknown>();
+      for (const [key, entry] of value) {
+        if (typeof key !== 'string') invalid('map keys must be strings');
+        normalized.set(key as string, normalizeWireValue(entry, active));
+      }
+      return normalized;
+    }
+    const prototype = Object.getPrototypeOf(objectValue);
+    if (prototype !== Object.prototype && prototype !== null) {
+      invalid('only plain objects, arrays, maps, dates, and binary values are supported');
+    }
+    const normalized = Object.create(null) as Record<string, unknown>;
+    for (const key of Reflect.ownKeys(objectValue)) {
+      if (typeof key !== 'string') invalid('symbol object keys are unsupported');
+      const stringKey = key as string;
+      const descriptor = Object.getOwnPropertyDescriptor(objectValue, stringKey);
+      if (!descriptor?.enumerable) continue;
+      if (!('value' in descriptor)) invalid('accessor properties are unsupported');
+      normalized[stringKey] = normalizeWireValue(descriptor.value, active);
+    }
+    return normalized;
+  } finally {
+    active.delete(objectValue);
+  }
+}
+
+function prepareCommand(command: Command, reqId: string): Record<string, unknown> {
+  const envelope = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(command)) {
+    if (typeof key !== 'string') invalid('symbol command keys are unsupported');
+    const stringKey = key as string;
+    const descriptor = Object.getOwnPropertyDescriptor(command, stringKey);
+    if (!descriptor?.enumerable) continue;
+    if (!('value' in descriptor)) invalid('accessor command properties are unsupported');
+    if (descriptor.value === undefined) continue;
+    envelope[stringKey] = descriptor.value;
+  }
+  envelope.reqId = reqId;
+  return normalizeWireValue(envelope, new WeakSet()) as Record<string, unknown>;
+}
+
+/**
+ * Encode and frame a command before it occupies an in-flight request slot.
+ *
+ * MessagePack may reject values such as cyclic objects. Normalize every such
+ * encoder failure to the public SDK error hierarchy; `frame()` already uses
+ * the same typed error for an oversized encoded body.
+ */
+export function serializeCommand(command: Command, reqId: string): Buffer {
+  try {
+    return frame(pack(prepareCommand(command, reqId)));
+  } catch (error) {
+    if (error instanceof SerializationError) throw error;
+    throw new SerializationError('cannot serialize command as MessagePack');
+  }
+}

package/src/terminal-outcome.ts

@@ -0,0 +1,58 @@
+interface AckEntry {
+  readonly id: string;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function validatedIndices(value: unknown, size: number): number[] {
+  if (!Array.isArray(value)) throw new Error('Invalid ACKB ignoredIndices response');
+  const seen = new Set<number>();
+  for (const index of value) {
+    if (!Number.isInteger(index) || index < 0 || index >= size || seen.has(index)) {
+      throw new Error('Invalid ACKB ignoredIndices response');
+    }
+    seen.add(index);
+  }
+  return [...seen];
+}
+
+function validatedIds(value: unknown): string[] {
+  if (!Array.isArray(value) || value.some((id) => typeof id !== 'string')) {
+    throw new Error('Invalid ACKB ignoredIds response');
+  }
+  return value as string[];
+}
+
+/** Parse structured ACKB evidence while preserving duplicate job-ID positions. */
+export function ignoredAckIndices(data: unknown, batch: readonly AckEntry[]): ReadonlySet<number> {
+  if (data === undefined) return new Set();
+  const payload = record(data);
+  if (!payload) throw new Error('Invalid ACKB response data');
+  const hasIndices = Object.hasOwn(payload, 'ignoredIndices');
+  const hasIds = Object.hasOwn(payload, 'ignoredIds');
+  if (!hasIndices) throw new Error('Invalid ACKB ignoredIndices response');
+
+  const ids = hasIds ? validatedIds(payload.ignoredIds) : null;
+  const indices = validatedIndices(payload.ignoredIndices, batch.length);
+  if (ids) {
+    if (ids.length !== indices.length) throw new Error('Mismatched ACKB ignored evidence');
+    for (let offset = 0; offset < indices.length; offset++) {
+      if (batch[indices[offset]]?.id !== ids[offset]) {
+        throw new Error('Mismatched ACKB ignored evidence');
+      }
+    }
+  }
+  return new Set(indices);
+}
+
+/** Parse a single ACK/FAIL response; historical applied responses have no data. */
+export function terminalOutcomeWasApplied(data: unknown): boolean {
+  if (data === undefined) return true;
+  const payload = record(data);
+  if (payload?.applied === false && payload.reason === 'already-finalized') return false;
+  throw new Error('Invalid terminal outcome response data');
+}

package/src/types.ts

@@ -104,12 +104,9 @@ export function wireJobOptions(opts: JobOptions = {}): Record<string, unknown> {
   });
 }
 
-/** The job name travels inside `data`, mirroring the official client. */
-export function jobPayload(name: string, data: unknown): Record<string, unknown> {
-  if (data && typeof data === 'object' && !Array.isArray(data)) {
-    return { name, ...(data as Record<string, unknown>) };
-  }
-  return data === undefined || data === null ? { name } : { name, payload: data };
+/** Build the protocol-owned name field without changing user data. */
+export function jobPayload(name: string, data: unknown): { name: string; data: unknown } {
+  return { name, data };
 }
 
 export interface JobCounts {

package/src/worker-base.ts

@@ -7,6 +7,7 @@ import { randomBytes } from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import { hostname } from 'node:os';
 import { Connection } from './connection.js';
+import type { Response } from './connection-types.js';
 import {
   MAX_POLL_TIMEOUT_MS,
   sleep,
@@ -182,13 +183,15 @@ export class WorkerBase<T = unknown, R = unknown> extends EventEmitter {
     this.emit('closed');
   }
 
-  /** Dispatch a command, routing failures to 'error'. Returns whether the
-   * command reached the server — callers gate success-only side effects
-   * ('completed'/'failed' emits, counters) on it. */
-  protected async safeCall(command: Record<string, unknown> & { cmd: string }): Promise<boolean> {
+  /** Dispatch a command and route failures to 'error'. The optional outcome
+   * parser decides whether a successful response authorizes local effects. */
+  protected async safeCall(
+    command: Record<string, unknown> & { cmd: string },
+    outcome: (response: Response) => boolean = () => true
+  ): Promise<boolean> {
     try {
-      await this.connection.call(command);
-      return true;
+      const response = await this.connection.call(command);
+      return outcome(response);
     } catch (err) {
       this.emit('error', err instanceof Error ? err : new Error(String(err)));
       return false;

package/src/worker-slot-signal.ts

@@ -0,0 +1,23 @@
+/** One-shot wake-up used by the pull loop while every worker slot is busy. */
+export class SlotSignal {
+  private waiter: (() => void) | null = null;
+
+  wait(timeoutMs: number): Promise<void> {
+    return new Promise((resolve) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (this.waiter === finish) this.waiter = null;
+        resolve();
+      };
+      const timer = setTimeout(finish, timeoutMs);
+      this.waiter = finish;
+    });
+  }
+
+  notify(): void {
+    this.waiter?.();
+  }
+}

package/src/worker.ts

@@ -12,7 +12,9 @@ import { CommandTimeoutError, ConnectionClosedError, UnrecoverableError } from '
 import { compact } from './frame.js';
 import { Job } from './job.js';
 import type { PulledJobsResponse } from './responses.js';
+import { terminalOutcomeWasApplied } from './terminal-outcome.js';
 import { WorkerBase } from './worker-base.js';
+import { SlotSignal } from './worker-slot-signal.js';
 import {
   MAX_STACK_LINES,
   type Processor,
@@ -24,6 +26,7 @@ import {
 export class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
   private readonly processor: Processor<T, R>;
   private readonly ackBatcher: AckBatcher | null;
+  private readonly slotSignal = new SlotSignal();
 
   constructor(queue: string, processor: Processor<T, R>, opts: WorkerOptions = {}) {
     super(queue, opts);
@@ -83,7 +86,7 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
   private async pollOnce(): Promise<void> {
     const free = this.concurrency - this.active.size;
     if (free <= 0) {
-      await sleep(20);
+      await this.slotSignal.wait(20);
       return;
     }
 
@@ -140,11 +143,11 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
           id: job.id,
           token,
           result: result ?? undefined,
-          onSettled: (err) => {
+          onSettled: (err, applied) => {
             this.finishJob(job.id);
             if (err) {
               this.emit('error', err instanceof Error ? err : new Error(String(err)));
-            } else {
+            } else if (applied) {
               this.processed += 1;
               this.emit('completed', job, result);
             }
@@ -153,7 +156,8 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
         return;
       }
       const acked = await this.safeCall(
-        compact({ cmd: 'ACK', id: job.id, token, result: result ?? undefined }) as { cmd: string }
+        compact({ cmd: 'ACK', id: job.id, token, result: result ?? undefined }) as { cmd: string },
+        (response) => terminalOutcomeWasApplied(response.data)
       );
       // Free the slot BEFORE emitting: a throwing 'completed' listener must
       // not leak the active slot (same rationale as the batched path).
@@ -177,7 +181,8 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
           error: error.message || error.name,
           stack,
           unrecoverable: err instanceof UnrecoverableError ? true : undefined,
-        }) as { cmd: string }
+        }) as { cmd: string },
+        (response) => terminalOutcomeWasApplied(response.data)
       );
       this.finishJob(job.id);
       // Same asymmetry guard as the ACK path: if the FAIL never reached the
@@ -192,6 +197,7 @@ export class Worker<T = unknown, R = unknown> extends WorkerBase<T, R> {
   private finishJob(id: string): void {
     this.active.delete(id);
     this.cancelledJobs.delete(id);
+    this.slotSignal.notify();
   }
 
   // --------------------------------------------------------------- heartbeat

package/dist/backpressure.js

@@ -1,39 +0,0 @@
-/**
- * Backpressure gate: bounds the number of in-flight commands on a connection.
- *
- * When the in-flight count reaches `max`, `acquire()` parks the caller until a
- * slot frees (a pending command settles). This turns unbounded memory growth
- * under a fast producer / slow server into cooperative flow control. `max <= 0`
- * disables the gate (unbounded, the default).
- */
-export class Backpressure {
-    max;
-    onWait;
-    waiters = [];
-    constructor(max, onWait) {
-        this.max = max;
-        this.onWait = onWait;
-    }
-    /** Resolve immediately if under the limit, else park until a slot frees. */
-    acquire(inFlight) {
-        if (this.max <= 0 || inFlight < this.max)
-            return;
-        this.onWait?.();
-        return new Promise((resolve) => {
-            this.waiters.push(resolve);
-        });
-    }
-    /** Release one parked caller (call when a pending command settles). */
-    release() {
-        this.waiters.shift()?.();
-    }
-    /** Release every parked caller (call on teardown so none hang forever). */
-    clear() {
-        while (this.waiters.length > 0)
-            this.waiters.shift()?.();
-    }
-    /** Number of callers currently parked. */
-    get waiting() {
-        return this.waiters.length;
-    }
-}

package/dist/bunqueue/aging.js

@@ -1,53 +0,0 @@
-/**
- * Bunqueue Simple Mode — priority aging.
- * Port of src/client/bunqueue/aging.ts: automatically boosts the priority of
- * old waiting jobs. Same semantics; the job scan goes over TCP (GetJobs on
- * the waiting and prioritized states) instead of the embedded manager.
- */
-export class PriorityAger {
-    timer = null;
-    config;
-    queue;
-    constructor(config, queue) {
-        this.config = config;
-        this.queue = queue;
-    }
-    start() {
-        const interval = this.config.interval ?? 60000;
-        this.timer = setInterval(() => {
-            void this.tick();
-        }, interval);
-        this.timer.unref?.();
-    }
-    async tick() {
-        const minAge = this.config.minAge ?? 60000;
-        const boost = this.config.boost ?? 1;
-        const maxPriority = this.config.maxPriority ?? 100;
-        const maxScan = this.config.maxScan ?? 100;
-        // Both waiting and prioritized jobs (priority > 0 means "prioritized")
-        const [waiting, prioritized] = await Promise.all([
-            this.queue.getJobs({ state: 'waiting', start: 0, end: maxScan }),
-            this.queue.getJobs({ state: 'prioritized', start: 0, end: maxScan }),
-        ]);
-        const jobs = [...waiting, ...prioritized];
-        const now = Date.now();
-        for (const job of jobs) {
-            const age = now - job.timestamp;
-            if (age >= minAge && job.priority < maxPriority) {
-                const newPriority = Math.min(job.priority + boost, maxPriority);
-                try {
-                    await this.queue.changeJobPriority(job.id, { priority: newPriority });
-                }
-                catch {
-                    // Best-effort — the job may have been processed meanwhile
-                }
-            }
-        }
-    }
-    destroy() {
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = null;
-        }
-    }
-}