bunqueue-client 0.1.9 → 0.2.0

package/dist/types/src/shared/logger.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Structured Logger
+ * JSON-formatted logging for production environments
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    component: string;
+    message: string;
+    reqId?: string;
+    data?: Record<string, unknown>;
+}
+/** Logger class for structured logging */
+export declare class Logger {
+    private readonly component;
+    private static jsonMode;
+    private static level;
+    constructor(component: string);
+    /** Enable JSON output mode */
+    static enableJsonMode(): void;
+    /** Disable JSON output mode (use human-readable) */
+    static disableJsonMode(): void;
+    /** Set minimum log level */
+    static setLevel(level: LogLevel): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+    /** Emit debug diagnostics on stderr while preserving level filtering. */
+    debugToStderr(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    /** Emit informational diagnostics on stderr without inflating their severity. */
+    infoToStderr(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    private log;
+}
+/** Create a logger for a component */
+export declare function createLogger(component: string): Logger;
+/** Global loggers */
+export declare const serverLog: Logger;
+export declare const tcpLog: Logger;
+export declare const httpLog: Logger;
+export declare const wsLog: Logger;
+export declare const cronLog: Logger;
+export declare const statsLog: Logger;
+export declare const storageLog: Logger;
+export declare const queueLog: Logger;
+export declare const webhookLog: Logger;
+export declare const backupLog: Logger;

package/dist/types/src/shared/lru.d.ts

@@ -0,0 +1,9 @@
+/**
+ * LRU (Least Recently Used) Cache implementations
+ * Bounded collections with automatic eviction
+ */
+export { type MapLike, LRUMap } from "./lruMap.js";
+export { type SetLike, LRUSet } from "./lruSet.js";
+export { BoundedSet } from "./boundedSet.js";
+export { BoundedMap } from "./boundedMap.js";
+export { TTLMap } from "./ttlMap.js";

package/dist/types/src/shared/lruMap.d.ts

@@ -0,0 +1,42 @@
+/**
+ * LRU Map - Map with automatic least-recently-used eviction
+ */
+/** Map-like interface for LRU compatibility */
+export interface MapLike<K, V> {
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    readonly size: number;
+}
+/**
+ * LRU Map - automatically evicts least recently used entries
+ * Optimized with doubly-linked list for O(1) move-to-front
+ * without delete+re-insert overhead
+ */
+export declare class LRUMap<K, V> implements MapLike<K, V> {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly onEvict?;
+    private head;
+    private tail;
+    constructor(maxSize: number, onEvict?: (key: K, value: V) => void);
+    /** Move node to front (most recently used) - O(1) */
+    private moveToFront;
+    /** Remove node from list - O(1) */
+    private removeNode;
+    /** Add node to front - O(1) */
+    private addToFront;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[K, V]>;
+    forEach(callback: (value: V, key: K) => void): void;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+}

package/dist/types/src/shared/lruSet.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LRU Set - Set with automatic least-recently-used eviction
+ */
+/** Set-like interface for LRU compatibility */
+export interface SetLike<T> {
+    add(value: T): void;
+    has(value: T): boolean;
+    delete(value: T): boolean;
+    clear(): void;
+    readonly size: number;
+}
+/**
+ * LRU Set - automatically evicts least recently used entries
+ * Optimized with doubly-linked list for O(1) move-to-front
+ */
+export declare class LRUSet<T> implements SetLike<T> {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly onEvict?;
+    private head;
+    private tail;
+    constructor(maxSize: number, onEvict?: (value: T) => void);
+    /** Move node to front - O(1) */
+    private moveToFront;
+    /** Remove node from list - O(1) */
+    private removeNode;
+    /** Add node to front - O(1) */
+    private addToFront;
+    add(value: T): void;
+    has(value: T): boolean;
+    delete(value: T): boolean;
+    clear(): void;
+    get size(): number;
+    values(): IterableIterator<T>;
+    [Symbol.iterator](): IterableIterator<T>;
+}

package/dist/types/src/shared/minHeap.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Generic Min-Heap implementation with 4-ary branching
+ * 4-ary heap provides better cache locality than binary heap:
+ * - Children are stored closer together in memory
+ * - Reduces cache misses during bubbleDown (most frequent operation)
+ * - 4 comparisons per level vs 2, but fewer levels to traverse
+ *
+ * O(log₄ n) push/pop, O(1) peek
+ */
+export declare class MinHeap<T> {
+    private heap;
+    private readonly compare;
+    /** Branching factor - 4 provides optimal cache performance on modern CPUs */
+    private static readonly D;
+    /**
+     * Create a min-heap with custom comparator
+     * @param compare Returns negative if a < b, positive if a > b, 0 if equal
+     */
+    constructor(compare: (a: T, b: T) => number);
+    /** Get current size */
+    get size(): number;
+    /** Check if empty */
+    get isEmpty(): boolean;
+    /** Push item - O(log n) */
+    push(item: T): void;
+    /** Pop minimum item - O(log n) */
+    pop(): T | undefined;
+    /** Peek at minimum without removing - O(1) */
+    peek(): T | undefined;
+    /** Clear the heap */
+    clear(): void;
+    /** Get all items (for iteration) */
+    toArray(): T[];
+    /** Rebuild heap from array - O(n) */
+    buildFrom(items: T[]): void;
+    /** Remove item by predicate - O(n) */
+    removeWhere(predicate: (item: T) => boolean): T | undefined;
+    /** 4-ary bubbleUp: parent at floor((idx-1)/4) */
+    private bubbleUp;
+    /** 4-ary bubbleDown: children at D*idx+1 through D*idx+D */
+    private bubbleDown;
+    private swap;
+}

package/dist/types/src/shared/msgpack.d.ts

@@ -0,0 +1,3 @@
+export declare function encodeMessagePack(value: unknown): Uint8Array;
+/** Decode maps through safe own properties, preserving keys such as `__proto__`. */
+export declare function decodeMessagePack<T = unknown>(buffer: Uint8Array): T;

package/dist/types/src/shared/pausedView.d.ts

@@ -0,0 +1,19 @@
+/**
+ * BullMQ paused-view counts (#92).
+ *
+ * When a queue is paused, none of its ready jobs (waiting + prioritized) can be
+ * pulled, so they are reported under `paused` — and NOT in their own buckets, to
+ * avoid double-counting a single job. This mirrors the per-state lists, where a
+ * paused queue lists those jobs under `paused` and returns nothing for `waiting`
+ * / `prioritized`. Delayed and active jobs keep their own state.
+ *
+ * Single source of truth shared by every count surface that exposes the BullMQ
+ * `getJobCounts` shape (client SDK, TCP handler, dashboard detail), so they can
+ * never drift apart.
+ */
+export interface PausedDerivedCounts {
+    waiting: number;
+    prioritized: number;
+    paused: number;
+}
+export declare function pausedView(waiting: number, prioritized: number, isPaused: boolean): PausedDerivedCounts;

package/dist/types/src/shared/rwLock.d.ts

@@ -0,0 +1,22 @@
+/** Writer-priority read/write lock with FIFO writer handoff. */
+import type { LockGuard } from "./types/lock.js";
+export declare class RWLock {
+    private readers;
+    private writer;
+    private writerWaiting;
+    private readonly readerQueue;
+    private readonly writerQueue;
+    acquireRead(timeoutMs?: number): Promise<LockGuard>;
+    acquireWrite(timeoutMs?: number): Promise<LockGuard>;
+    getState(): {
+        readers: number;
+        writer: boolean;
+        writerWaiting: number;
+    };
+    private createWaiter;
+    private drain;
+    private takeWriter;
+    private grantReaders;
+    private createReadGuard;
+    private createWriteGuard;
+}

package/dist/types/src/shared/serialization.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Serialization utilities
+ * Handle BigInt and other special types for JSON serialization
+ */
+import type { Job } from "../domain/types/job.js";
+/** Compare Unicode text in the same code-point order as SQLite BINARY UTF-8 text. */
+export declare function compareSqliteBinaryText(left: string, right: string): number;
+/**
+ * Serialize a Job for JSON output
+ * Converts BigInt IDs to strings
+ */
+export declare function serializeJob(job: Job): Record<string, unknown>;
+/**
+ * Serialize multiple jobs
+ */
+export declare function serializeJobs(jobs: Job[]): Record<string, unknown>[];
+/**
+ * Custom JSON replacer for BigInt
+ */
+export declare function bigIntReplacer(_key: string, value: unknown): unknown;
+/**
+ * Stringify with BigInt support
+ */
+export declare function jsonStringify(value: unknown): string;

package/dist/types/src/shared/skipList.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Skip List with O(log n) operations
+ * - insert: O(log n)
+ * - delete: O(log n)
+ * - search: O(log n)
+ * - range query: O(log n + k) where k = results
+ */
+export declare class SkipList<T> {
+    private readonly maxLevel;
+    private readonly probability;
+    private readonly compare;
+    private readonly equals?;
+    private head;
+    private level;
+    private _size;
+    /**
+     * Create a skip list
+     * @param compare Comparator function (negative if a < b, positive if a > b, 0 if equal)
+     * @param maxLevel Maximum level (default 16, supports ~65k elements efficiently)
+     * @param probability Level promotion probability (default 0.5)
+     * @param equals Optional equality function for duplicate detection. If provided,
+     *               duplicates where equals returns true are skipped during insert.
+     *               If not provided, multiple entries with same comparator result are allowed.
+     */
+    constructor(compare: (a: T, b: T) => number, maxLevel?: number, probability?: number, equals?: (a: T, b: T) => boolean);
+    /** Current number of elements */
+    get size(): number;
+    /** Check if empty */
+    get isEmpty(): boolean;
+    /** Generate random level for new node */
+    private randomLevel;
+    /**
+     * Insert value - O(log n)
+     * If an equals function was provided to the constructor, duplicates
+     * (where equals returns true) are skipped. Otherwise, multiple entries
+     * with the same comparator result are allowed (sorted multiset behavior).
+     * @returns true if inserted, false if duplicate was skipped
+     */
+    insert(value: T): boolean;
+    /**
+     * Delete value - O(log n)
+     * @returns true if found and deleted
+     */
+    delete(value: T): boolean;
+    /**
+     * Delete by predicate - O(n) worst case, but typically O(log n + k)
+     * Useful when you need to match by a subset of fields
+     */
+    deleteWhere(predicate: (value: T) => boolean): T | null;
+    /**
+     * Find exact value - O(log n)
+     */
+    find(value: T): T | null;
+    /**
+     * Check if value exists - O(log n)
+     */
+    has(value: T): boolean;
+    /**
+     * Get first (minimum) element - O(1)
+     */
+    first(): T | null;
+    /**
+     * Remove and return first element - O(log n)
+     */
+    shift(): T | null;
+    /**
+     * Range query: get all values where comparator returns <= 0
+     * O(log n + k) where k = number of results
+     * @param maxValue Upper bound (inclusive)
+     * @param limit Maximum number of results
+     */
+    rangeUntil(maxValue: T, limit?: number): T[];
+    /**
+     * Get all values where predicate is true, starting from first
+     * Stops at first false (assumes sorted order matches predicate)
+     * O(k) where k = matching results
+     */
+    takeWhile(predicate: (value: T) => boolean, limit?: number): T[];
+    /**
+     * Iterate all values in order
+     */
+    values(): Generator<T>;
+    /**
+     * Convert to array
+     */
+    toArray(): T[];
+    /**
+     * Clear all elements
+     */
+    clear(): void;
+    /**
+     * Filter and remove elements matching predicate
+     * Returns removed elements
+     * O(n) but removes in-place
+     */
+    removeAll(predicate: (value: T) => boolean): T[];
+}

package/dist/types/src/shared/skipListNodes.d.ts

@@ -0,0 +1,6 @@
+import type { SkipNode } from "./types/skipList.js";
+export declare function randomSkipLevel(probability: number, maxLevel: number): number;
+export declare function createSkipHead<T>(maxLevel: number): SkipNode<T>;
+export declare function collectSkipRange<T>(first: SkipNode<T> | null, predicate: (value: T) => boolean, limit?: number): T[];
+export declare function iterateSkipValues<T>(first: SkipNode<T> | null): Generator<T>;
+export declare function removeMatchingSkipValues<T>(first: SkipNode<T> | null, predicate: (value: T) => boolean, remove: (value: T) => void): T[];

package/dist/types/src/shared/storageHealth.d.ts

@@ -0,0 +1,9 @@
+export interface StorageHealthStatus {
+    readonly diskFull: boolean;
+    readonly error: string | null;
+    readonly since: number | null;
+}
+/** A storage error is degraded even when the underlying failure is not a full disk. */
+export declare function isStorageDegraded(status: StorageHealthStatus): boolean;
+/** Project internal health into a client-safe copy without mutating runtime diagnostics. */
+export declare function clientStorageStatus(status: StorageHealthStatus): StorageHealthStatus;

package/dist/types/src/shared/ttlMap.d.ts

@@ -0,0 +1,81 @@
+/**
+ * TTL Map - entries expire after timeout
+ * Optimized with MinHeap for O(log n) insert and O(k) cleanup
+ */
+/**
+ * TTL Map - entries expire after timeout
+ * Optimized with MinHeap for O(log n) insert and O(k) cleanup
+ *
+ * IMPORTANT: You MUST call stop() when done with this instance to prevent memory leaks.
+ * The cleanup interval will keep running until stop() is called, preventing the instance
+ * from being garbage collected.
+ *
+ * @example
+ * ```typescript
+ * const map = new TTLMap<string, number>(60_000); // 60s TTL
+ * try {
+ *   map.set('key', 123);
+ *   // use map...
+ * } finally {
+ *   map.stop(); // REQUIRED: stops cleanup interval
+ * }
+ * ```
+ *
+ * Memory leak prevention:
+ * - Each heap entry stores (expiresAt, key)
+ * - During cleanup, we verify the key still exists in cache AND has matching expiresAt
+ * - Stale entries (deleted keys or updated TTLs) are skipped and removed from heap
+ * - Periodic compaction rebuilds heap when stale ratio exceeds threshold
+ */
+export declare class TTLMap<K, V> {
+    private readonly cache;
+    private readonly ttlMs;
+    private cleanupInterval;
+    /**
+     * Expiry heap: MinHeap of (expiresAt, key) for efficient cleanup
+     * O(log n) insert instead of O(n) with array splice
+     */
+    private readonly expiryHeap;
+    /** Count of stale entries in heap (deleted or updated keys) */
+    private staleCount;
+    /** Rebuild heap when stale entries exceed this ratio of heap size */
+    private static readonly COMPACTION_THRESHOLD;
+    /** Minimum heap size before considering compaction (avoid frequent rebuilds for small heaps) */
+    private static readonly MIN_COMPACTION_SIZE;
+    /**
+     * Create a new TTLMap instance.
+     *
+     * @param ttlMs - Default time-to-live for entries in milliseconds
+     * @param cleanupIntervalMs - Interval between cleanup runs (default: 60000ms / 1 minute).
+     *                           Lower values = more frequent cleanup but higher CPU usage.
+     *                           Set based on expected entry volume and TTL duration.
+     */
+    constructor(ttlMs: number, cleanupIntervalMs?: number);
+    private startCleanup;
+    /** O(k log n) cleanup where k = expired entries */
+    private cleanup;
+    /**
+     * Rebuild heap if stale entry ratio exceeds threshold
+     * This prevents unbounded heap growth from delete() and set() updates
+     */
+    private maybeCompact;
+    /** Rebuild heap with only valid entries - O(n log n) */
+    private rebuildHeap;
+    get(key: K): V | undefined;
+    /** O(log n) insert with MinHeap instead of O(n) with array splice */
+    set(key: K, value: V, ttlMs?: number): void;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    clear(): void;
+    /**
+     * Stop the cleanup interval. MUST be called when done with this instance
+     * to prevent memory leaks. The interval keeps a reference to the instance,
+     * preventing garbage collection until stop() is called.
+     */
+    stop(): void;
+    get size(): number;
+    /** Get heap size (for debugging/monitoring) */
+    get heapSize(): number;
+    /** Get count of stale heap entries (for debugging/monitoring) */
+    get staleEntryCount(): number;
+}

package/dist/types/src/shared/types/lock.d.ts

@@ -0,0 +1,7 @@
+export interface LockGuard {
+    release(): void;
+}
+export interface LockQueueEntry {
+    resolve: () => void;
+    cancelled: boolean;
+}

package/dist/types/src/shared/types/skipList.d.ts

@@ -0,0 +1,4 @@
+export interface SkipNode<T> {
+    value: T;
+    forward: Array<SkipNode<T> | null>;
+}

package/dist/types/src/shared/version.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Package version - imported from package.json
+ */
+export declare const VERSION: string;

package/dist/types/src/shared/webhookValidation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Webhook URL Validation
+ * SSRF prevention for webhook URLs — shared between server handlers and embedded SDK
+ */
+/** Validate webhook URL to prevent SSRF. Returns error message or null if valid. */
+export declare function validateWebhookUrl(url: string): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue-client",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Cross-runtime TypeScript client for the bunqueue job queue server — Node.js, Bun, Deno and Cloudflare Workers",
   "license": "MIT",
   "type": "module",
@@ -11,12 +11,17 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./legacy": {
+      "types": "./dist/legacy.d.ts",
+      "import": "./dist/legacy.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "src",
     "README.md",
+    "LEGACY.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
@@ -24,14 +29,22 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "bun ../../scripts/build-portable-client.ts && bun ../../scripts/check-client-parity.ts",
     "prepublishOnly": "bun run build",
     "test": "bun tests/e2e.ts",
+    "test:parity": "bun ../../scripts/check-client-parity.ts && BUNQUEUE_EMBEDDED=1 bun test ../../test/typescript-client-parity.test.ts ../../test/client-parity-*.test.ts ../../test/tcp-parity-*.test.ts",
+    "test:canonical": "bun tests/canonical-queue.mjs && bun tests/canonical-worker.mjs",
+    "test:shared-contract": "BUNQUEUE_EMBEDDED=1 bun test --parallel=4 --preload ../../scripts/client-parity/preload.ts ../../test/docs-queue-guide ../../test/docs-worker-guide ../../test/docs-quickstart.test.ts",
+    "test:property": "bun test tests/flow-plan.property.test.ts tests/flow-identity.property.test.ts tests/flow-plan.validation.test.ts tests/flow-plan.limits.test.ts tests/flow-plan.contract.test.ts tests/flow-commit.test.ts tests/worker-slot-signal.test.ts",
     "test:integration": "bun tests/integration.ts",
-    "lint": "biome lint src tests",
-    "format": "biome format --write src tests",
-    "check": "biome check src tests",
-    "test:workers": "bun pm pack --destination tests/workers && cd tests/workers && mv bunqueue-client-*.tgz bunqueue-client.tgz && rm -rf node_modules/bunqueue-client bun.lock && bun install --force && node run.mjs"
+    "test:soak": "bun tests/soak.ts",
+    "lint": "oxlint src tests",
+    "lint:fix": "oxlint --fix src tests",
+    "format": "oxfmt --write src tests",
+    "format:check": "oxfmt --check src tests",
+    "check:oxc": "bun run lint && bun run format:check",
+    "check": "bun run check:oxc",
+    "test:workers": "cd tests/workers && bun install --frozen-lockfile && cd ../.. && bun pm pack --destination tests/workers && cd tests/workers && mv bunqueue-client-*.tgz bunqueue-client.tgz && rm -rf node_modules/bunqueue-client && mkdir -p node_modules/bunqueue-client && tar -xzf bunqueue-client.tgz -C node_modules/bunqueue-client --strip-components=1 && node run.mjs"
   },
   "keywords": [
     "queue",
@@ -49,8 +62,13 @@
     "msgpackr": "^1.11.8"
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
-    "@types/node": "^22.0.0"
+    "@types/node-20": "npm:@types/node@20.19.43",
+    "@types/node-22": "npm:@types/node@22.20.4",
+    "fast-check": "4.9.0",
+    "oxfmt": "0.64.0",
+    "oxlint": "1.79.0",
+    "oxlint-tsgolint": "7.0.2001",
+    "typescript": "^5.7.0"
   },
   "author": "Egeo Minotti",
   "homepage": "https://bunqueue.dev/guide/sdks/",
@@ -63,4 +81,4 @@
     "url": "https://github.com/egeominotti/bunqueue/issues"
   },
   "sideEffects": false
-}
+}

package/src/ack-batcher.ts

@@ -10,13 +10,14 @@
 
 import type { Connection } from './connection.js';
 import { compact } from './frame.js';
+import { ignoredAckIndices } from './terminal-outcome.js';
 
 export interface AckItem {
   id: string;
   token: string;
   result: unknown;
-  /** Called once the batch settles: `err` set on failure, undefined on ack. */
-  onSettled: (err?: unknown) => void;
+  /** `applied` is defined only after a successful, authoritative response. */
+  onSettled: (err?: unknown, applied?: boolean) => void;
 }
 
 export class AckBatcher {
@@ -52,8 +53,9 @@ export class AckBatcher {
     // a throwing callback can neither be re-invoked with an error (double
     // settle) nor starve the remaining items of their callback.
     let error: unknown;
+    let ignoredIndices: ReadonlySet<number> = new Set();
     try {
-      await this.connection.call(
+      const response = await this.connection.call(
         compact({
           cmd: 'ACKB',
           ids: batch.map((b) => b.id),
@@ -61,12 +63,13 @@ export class AckBatcher {
           results: batch.map((b) => b.result),
         }) as { cmd: string }
       );
+      ignoredIndices = ignoredAckIndices(response.data, batch);
     } catch (err) {
       error = err ?? new Error('ACKB failed');
     }
-    for (const item of batch) {
+    for (let index = 0; index < batch.length; index++) {
       try {
-        item.onSettled(error);
+        batch[index].onSettled(error, error === undefined ? !ignoredIndices.has(index) : undefined);
       } catch {
         // A callback error (e.g. an unhandled 'error' emit in the worker)
         // must never prevent the other items from settling.

package/src/bunqueue/bunqueue-api.ts

@@ -11,7 +11,7 @@ import type { DlqFilter, DlqStats } from './dlq-rate-limit.js';
 import type { CircuitState, TriggerRule } from './types.js';
 
 type Raw = Record<string, unknown>;
-// biome-ignore lint/suspicious/noExplicitAny: mixin context needs the erased generic instance
+// oxlint-disable-next-line typescript/no-explicit-any -- mixin context needs the erased generic instance
 type Ctx = Bunqueue<any, any>;
 
 export const bunqueueApi = {

package/src/bunqueue/bunqueue.ts

@@ -26,7 +26,7 @@ import type { BunqueueMiddleware, BunqueueOptions } from './types.js';
 
 type Raw = Record<string, unknown>;
 
-// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: prototype-mixin composition — Object.assign below installs exactly the methods BunqueueApi declares
+// oxlint-disable-next-line typescript/no-unsafe-declaration-merging -- prototype-mixin composition installs the BunqueueApi methods with Object.assign below
 export class Bunqueue<T = unknown, R = unknown> {
   readonly name: string;
   readonly queue: Queue<T>;
@@ -219,6 +219,7 @@ export class Bunqueue<T = unknown, R = unknown> {
   }
 }
 
+// oxlint-disable-next-line typescript/no-empty-object-type -- declaration merging exposes the methods installed below
 export interface Bunqueue<T = unknown, R = unknown> extends BunqueueApi<T, R> {}
 
 Object.assign(Bunqueue.prototype, bunqueueApi);

package/src/canonical-transport/bun-sqlite-types.ts

@@ -0,0 +1,22 @@
+/**
+ * Declaration-only stand-in for Bun's `bun:sqlite` module in the published
+ * type graph. The embedded engine runs only under Bun; the portable build
+ * points engine declarations here so Node, Deno and Workers consumers never
+ * need Bun's global type declarations. Nothing imports this at runtime.
+ */
+export interface Statement {
+  run(...parameters: unknown[]): unknown;
+  get(...parameters: unknown[]): unknown;
+  all(...parameters: unknown[]): unknown[];
+  values(...parameters: unknown[]): unknown[][];
+  finalize(): void;
+}
+
+export interface Database {
+  prepare(sql: string): Statement;
+  query(sql: string): Statement;
+  run(sql: string, ...parameters: unknown[]): unknown;
+  exec(sql: string, ...parameters: unknown[]): unknown;
+  transaction<T extends (...parameters: never[]) => unknown>(run: T): T;
+  close(throwOnError?: boolean): void;
+}