bunqueue-client 0.1.9 → 0.2.1

package/dist/types/src/client/sandboxed/runtime/log.d.ts

@@ -0,0 +1 @@
+export declare function log(level: 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>): void;

package/dist/types/src/client/sandboxed/runtime/pool.d.ts

@@ -0,0 +1,11 @@
+import type { Job as DomainJob } from "../../../domain/types/job.js";
+import type { IPCResponse, WorkerProcess } from "../types/index.js";
+import { SandboxedLifecycle } from "./lifecycle.js";
+export declare abstract class SandboxedPool<T = unknown> extends SandboxedLifecycle<T> {
+    protected spawnWorker(index: number): Promise<void>;
+    protected pullLoop(): Promise<void>;
+    protected recycleIdleWorkers(): void;
+    protected abstract dispatch(worker: WorkerProcess, job: DomainJob, token: string | null): void;
+    protected abstract handleMessage(worker: WorkerProcess, message: IPCResponse): void;
+    protected abstract handleCrash(worker: WorkerProcess, index: number, reportError?: boolean): void;
+}

package/dist/types/src/client/sandboxed/runtime/recovery.d.ts

@@ -0,0 +1,11 @@
+import { type Job as DomainJob } from "../../../domain/types/job.js";
+import type { Job } from "../../types.js";
+import type { WorkerProcess } from "../types/index.js";
+import { SandboxedDispatch } from "./dispatch.js";
+export declare class SandboxedRecovery<T = unknown> extends SandboxedDispatch<T> {
+    protected handleCrash(worker: WorkerProcess, index: number, reportError?: boolean): void;
+    protected startHeartbeat(): void;
+    protected sendHeartbeat(): Promise<void>;
+    protected safeEmitError(error: Error): void;
+    protected createEventJob(domainJob: DomainJob): Job;
+}

package/dist/types/src/client/sandboxed/runtime/state.d.ts

@@ -0,0 +1,39 @@
+import { EventEmitter } from 'events';
+import type { Job } from "../../types.js";
+import { type TcpConnectionPool } from "../../tcpPool.js";
+import { type QueueOps } from "../queueOps.js";
+import type { RequiredSandboxedWorkerOptions, SandboxedWorkerOptions, WorkerProcess } from "../types/index.js";
+export declare abstract class SandboxedState<T = unknown> extends EventEmitter {
+    on(event: 'ready' | 'closed', listener: () => void): this;
+    on(event: 'active', listener: (job: Job<T>) => void): this;
+    on(event: 'completed', listener: (job: Job<T>, result: unknown) => void): this;
+    on(event: 'failed', listener: (job: Job<T>, error: Error) => void): this;
+    on(event: 'progress', listener: (job: Job<T>, progress: number) => void): this;
+    on(event: 'log', listener: (job: Job<T>, message: string) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    once(event: 'ready' | 'closed', listener: () => void): this;
+    once(event: 'active', listener: (job: Job<T>) => void): this;
+    once(event: 'completed', listener: (job: Job<T>, result: unknown) => void): this;
+    once(event: 'failed', listener: (job: Job<T>, error: Error) => void): this;
+    once(event: 'progress', listener: (job: Job<T>, progress: number) => void): this;
+    once(event: 'log', listener: (job: Job<T>, message: string) => void): this;
+    once(event: 'error', listener: (error: Error) => void): this;
+    protected readonly queueName: string;
+    protected readonly options: RequiredSandboxedWorkerOptions;
+    protected readonly workers: WorkerProcess[];
+    protected running: boolean;
+    protected pullPromise: Promise<void> | null;
+    protected wrapperPath: string | null;
+    protected readonly ops: QueueOps;
+    protected readonly tcp: TcpConnectionPool | null;
+    protected readonly workerId: string;
+    protected heartbeatTimer: ReturnType<typeof setInterval> | null;
+    protected readonly heartbeatInterval: number;
+    protected readonly idleTimeout: number;
+    protected readonly idleRecycleMs: number;
+    protected readonly autoStart: boolean;
+    protected readonly autoStartPollMs: number;
+    protected lastActivityTime: number;
+    protected autoStartTimer: ReturnType<typeof setInterval> | null;
+    constructor(queueName: string, options: SandboxedWorkerOptions);
+}

package/dist/types/src/client/sandboxed/types/index.d.ts

@@ -0,0 +1,2 @@
+export type { RequiredSandboxedWorkerOptions, SandboxedWorkerOptions } from "./options.js";
+export type { IPCRequest, IPCResponse, WorkerProcess } from "./process.js";

package/dist/types/src/client/sandboxed/types/options.d.ts

@@ -0,0 +1,27 @@
+import type { SharedManager } from "../../manager.js";
+import type { ConnectionOptions } from "../../types.js";
+export interface SandboxedWorkerOptions {
+    processor: string;
+    concurrency?: number;
+    maxMemory?: number;
+    timeout?: number;
+    autoRestart?: boolean;
+    maxRestarts?: number;
+    pollInterval?: number;
+    manager?: SharedManager;
+    connection?: ConnectionOptions;
+    heartbeatInterval?: number;
+    idleTimeout?: number;
+    idleRecycleMs?: number;
+    autoStart?: boolean;
+    autoStartPollMs?: number;
+}
+export interface RequiredSandboxedWorkerOptions {
+    processor: string;
+    concurrency: number;
+    maxMemory: number;
+    timeout: number;
+    autoRestart: boolean;
+    maxRestarts: number;
+    pollInterval: number;
+}

package/dist/types/src/client/sandboxed/types/process.d.ts

@@ -0,0 +1,39 @@
+import type { Job as DomainJob } from "../../../domain/types/job.js";
+/**
+ * The pool only posts jobs to and terminates a sandbox thread: Bun's Web Worker
+ * here, a worker_threads adapter in bunqueue-client. Portable types keep the
+ * published declarations free of Bun and DOM globals.
+ */
+export interface SandboxThread {
+    postMessage(message: unknown): void;
+    terminate(): unknown;
+}
+export interface WorkerProcess {
+    worker: SandboxThread;
+    busy: boolean;
+    currentJob: DomainJob | null;
+    currentToken: string | null;
+    restarts: number;
+    timeoutId: ReturnType<typeof setTimeout> | null;
+    lastIdleAt: number;
+    terminated: boolean;
+}
+export interface IPCRequest {
+    type: 'job';
+    job: {
+        id: string;
+        name: string;
+        data: unknown;
+        queue: string;
+        attempts: number;
+        parentId?: string;
+    };
+}
+export interface IPCResponse {
+    type: 'result' | 'error' | 'progress' | 'log' | 'fail' | 'ready';
+    jobId?: string;
+    result?: unknown;
+    error?: string;
+    progress?: number;
+    message?: string;
+}

package/dist/types/src/client/sandboxed/worker.d.ts

@@ -0,0 +1,4 @@
+/** Public SandboxedWorker façade. Runtime lives in sandboxed/runtime/. */
+import { SandboxedRecovery } from "./runtime/recovery.js";
+export declare class SandboxedWorker<T = unknown> extends SandboxedRecovery<T> {
+}

package/dist/types/src/client/sandboxed/wrapper.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Worker Wrapper Script Generator
+ * Creates the wrapper script that loads processor in worker process
+ */
+/**
+ * Create wrapper script file that loads the processor
+ */
+export declare function createWrapperScript(queueName: string, processorPath: string): Promise<string>;
+/**
+ * Cleanup wrapper script file
+ */
+export declare function cleanupWrapperScript(wrapperPath: string | null): Promise<void>;

package/dist/types/src/client/sandboxedWorker.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SandboxedWorker - Re-exports from sandboxed module
+ * @deprecated Import from './sandboxed' instead
+ */
+export type { SandboxedWorkerOptions } from "./sandboxed/index.js";
+export { SandboxedWorker } from "./sandboxed/index.js";

package/dist/types/src/client/tcp/client.d.ts

@@ -0,0 +1,6 @@
+/** Production TCP client façade. */
+import { TcpClientLifecycle } from "./runtime/lifecycle.js";
+export { ClientClosedError } from "./errors.js";
+/** Behavior is composed from focused connection, health, and command layers. */
+export declare class TcpClient extends TcpClientLifecycle {
+}

package/dist/types/src/client/tcp/commandQueue.d.ts

@@ -0,0 +1,23 @@
+import type { PendingCommand } from "./types.js";
+/** Pending-command queue with reqId-based in-flight tracking. */
+export declare class CommandQueue {
+    private readonly pendingCommands;
+    private pendingQueue;
+    private currentCommand;
+    private commandIdCounter;
+    private readonly inFlightByReqId;
+    getCurrentCommand(): PendingCommand | null;
+    setCurrentCommand(command: PendingCommand | null): void;
+    hasPending(): boolean;
+    getInFlightCount(): number;
+    canSendMore(maxInFlight: number): boolean;
+    addInFlight(command: PendingCommand): void;
+    getByReqId(reqId: string): PendingCommand | undefined;
+    removeByReqId(reqId: string): PendingCommand | undefined;
+    enqueue(command: PendingCommand): void;
+    nextId(): number;
+    dequeue(): PendingCommand | null;
+    remove(id: number): boolean;
+    rejectAll(error: Error): void;
+    clearCurrent(error?: Error): void;
+}

package/dist/types/src/client/tcp/connection.d.ts

@@ -0,0 +1,4 @@
+/** Stable low-level TCP connection import surface. */
+export { CommandQueue } from "./commandQueue.js";
+export { buildClientTls, createConnection, tlsRequiresVerification } from "./transport.js";
+export type { ConnectionEvents, ConnectionResult, ConnectionTarget } from "./transport.js";

package/dist/types/src/client/tcp/errors.d.ts

@@ -0,0 +1,6 @@
+/** Synthetic rejection issued when a client closes with commands pending. */
+export declare class ClientClosedError extends Error {
+    constructor(message?: string);
+}
+/** Install the process filter for synthetic close rejections if none is active. */
+export declare function installClientClosedFilter(): void;

package/dist/types/src/client/tcp/health.d.ts

@@ -0,0 +1,60 @@
+/**
+ * TCP Health Tracker
+ * Monitors connection health with ping and latency tracking
+ */
+import type { ConnectionHealth } from "./types.js";
+/** Health tracker configuration */
+export interface HealthConfig {
+    pingInterval: number;
+    maxPingFailures: number;
+    /**
+     * Consecutive command timeouts before the link is concluded dead (0 = off).
+     * Optional for backward compatibility; defaults to 3 when omitted.
+     */
+    maxCommandTimeouts?: number;
+}
+/**
+ * Tracks connection health metrics
+ */
+export declare class HealthTracker {
+    private readonly config;
+    private consecutivePingFailures;
+    private consecutiveCommandTimeouts;
+    private lastSuccessAt;
+    private lastErrorAt;
+    private connectedAt;
+    private totalCommands;
+    private totalErrors;
+    private readonly latencyHistory;
+    private pingTimer;
+    private static readonly MAX_LATENCY_HISTORY;
+    constructor(config: HealthConfig);
+    /** Record successful command */
+    recordSuccess(latencyMs: number): void;
+    /** Record command error */
+    recordError(): void;
+    /** Record command sent (for total count) */
+    recordCommandSent(): void;
+    /** Record connection established */
+    recordConnected(): void;
+    /** Record ping success */
+    recordPingSuccess(latencyMs: number): void;
+    /** Record ping failure, returns true if max failures reached */
+    recordPingFailure(): boolean;
+    /**
+     * Record a command timeout. Returns true when the configured consecutive
+     * threshold is reached (and the feature is enabled), signalling the caller to
+     * force a reconnect. Any intervening success resets the counter, so this only
+     * fires on a sustained run of timeouts — the signature of a dead/half-open
+     * socket where writes succeed but no response ever comes back.
+     */
+    recordCommandTimeout(): boolean;
+    /** Get current health metrics */
+    getHealth(state: 'connected' | 'connecting' | 'disconnected' | 'closed'): ConnectionHealth;
+    /** Start ping timer */
+    startPing(pingFn: () => Promise<void>): void;
+    /** Stop ping timer */
+    stopPing(): void;
+    /** Record latency for averaging */
+    private recordLatency;
+}

package/dist/types/src/client/tcp/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * TCP Client Module
+ * Re-exports all TCP client components
+ */
+export type { ConnectionOptions, ConnectionHealth, PendingCommand, SocketWrapper, ClientTlsOptions, } from "./types.js";
+export { DEFAULT_CONNECTION } from "./types.js";
+export { HealthTracker, type HealthConfig } from "./health.js";
+export { ReconnectManager, type ReconnectConfig } from "./reconnect.js";
+export { createConnection, CommandQueue } from "./connection.js";
+export { TcpClient } from "./client.js";
+export { getSharedTcpClient, closeSharedTcpClient } from "./shared.js";

package/dist/types/src/client/tcp/reconnect.d.ts

@@ -0,0 +1,47 @@
+/**
+ * TCP Reconnection Manager
+ * Handles automatic reconnection with exponential backoff
+ */
+import { EventEmitter } from 'events';
+/** Reconnection configuration */
+export interface ReconnectConfig {
+    maxReconnectAttempts: number;
+    reconnectDelay: number;
+    maxReconnectDelay: number;
+    autoReconnect: boolean;
+}
+/**
+ * Manages reconnection attempts with exponential backoff
+ */
+export declare class ReconnectManager extends EventEmitter {
+    private readonly config;
+    on(event: 'maxReconnectAttemptsReached', listener: () => void): this;
+    on(event: 'reconnecting', listener: (data: {
+        attempt: number;
+        delay: number;
+    }) => void): this;
+    once(event: 'maxReconnectAttemptsReached', listener: () => void): this;
+    once(event: 'reconnecting', listener: (data: {
+        attempt: number;
+        delay: number;
+    }) => void): this;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private closed;
+    constructor(config: ReconnectConfig);
+    /** Mark as closed (prevents further reconnects) */
+    setClosed(closed: boolean): void;
+    /** Check if closed */
+    isClosed(): boolean;
+    /** Reset reconnect attempts (call on successful connect) */
+    reset(): void;
+    /** Cancel pending reconnection */
+    cancelReconnect(): void;
+    /** Check if reconnection is allowed */
+    canReconnect(): boolean;
+    /**
+     * Schedule reconnection with exponential backoff
+     * Returns false if max attempts reached
+     */
+    scheduleReconnect(connectFn: () => Promise<void>): boolean;
+}

package/dist/types/src/client/tcp/runtime/commands.d.ts

@@ -0,0 +1,9 @@
+import type { HelloResponse } from "../../../domain/types/response.js";
+import { TcpClientHealth } from "./health.js";
+/** Command framing, queueing, pipelining, and timeout handling. */
+export declare abstract class TcpClientCommands extends TcpClientHealth {
+    hello(): Promise<HelloResponse>;
+    protected sendDirect(command: Record<string, unknown>): Promise<Record<string, unknown>>;
+    protected processQueue(): void;
+    send(command: Record<string, unknown>): Promise<Record<string, unknown>>;
+}

package/dist/types/src/client/tcp/runtime/connectivity.d.ts

@@ -0,0 +1,13 @@
+import { TcpClientState } from "./state.js";
+/** Connection establishment and authentication lifecycle. */
+export declare abstract class TcpClientConnectivity extends TcpClientState {
+    protected abstract handleData(frame: Uint8Array): void;
+    protected abstract handleClose(): void;
+    protected abstract processQueue(): void;
+    protected abstract sendDirect(command: Record<string, unknown>): Promise<Record<string, unknown>>;
+    connect(): Promise<void>;
+    protected abstract ping(): Promise<boolean>;
+    private waitForConnection;
+    private doConnect;
+    private authenticate;
+}

package/dist/types/src/client/tcp/runtime/health.d.ts

@@ -0,0 +1,14 @@
+import { TcpClientConnectivity } from "./connectivity.js";
+/** Response dispatch, health tracking, and reconnect decisions. */
+export declare abstract class TcpClientHealth extends TcpClientConnectivity {
+    protected handleData(frame: Uint8Array): void;
+    protected handleClose(): void;
+    ping(): Promise<boolean>;
+    protected abstract send(command: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private handlePingFailure;
+    protected handleCommandTimeout(): void;
+    private forceReconnect;
+    getHealth(): import("../index.js").ConnectionHealth;
+    protected abstract getState(): 'connected' | 'connecting' | 'disconnected' | 'closed';
+    protected generateReqId(): string;
+}

package/dist/types/src/client/tcp/runtime/lifecycle.d.ts

@@ -0,0 +1,8 @@
+import { TcpClientCommands } from "./commands.js";
+/** Public shutdown and connection-state inspection. */
+export declare class TcpClientLifecycle extends TcpClientCommands {
+    close(): void;
+    isConnected(): boolean;
+    getState(): 'connected' | 'connecting' | 'disconnected' | 'closed';
+    getInFlightCount(): number;
+}

package/dist/types/src/client/tcp/runtime/state.d.ts

@@ -0,0 +1,50 @@
+import { EventEmitter } from 'events';
+import { CommandQueue } from "../connection.js";
+import { HealthTracker } from "../health.js";
+import { ReconnectManager } from "../reconnect.js";
+import type { ConnectionOptions, SocketWrapper } from "../types.js";
+import type { JobEvent } from "../../../domain/types/queue.js";
+/** Shared TCP client state and event contract. */
+export declare class TcpClientState extends EventEmitter {
+    on(event: 'connected' | 'disconnected' | 'maxReconnectAttemptsReached', listener: () => void): this;
+    on(event: 'reconnecting', listener: (data: {
+        attempt: number;
+        delay: number;
+    }) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    on(event: 'warning', listener: (data: {
+        type: string;
+        reqId?: string;
+    }) => void): this;
+    on(event: 'queueEvent', listener: (event: JobEvent) => void): this;
+    on(event: 'health', listener: (data: {
+        type: string;
+        latency?: number;
+        reason?: string;
+    }) => void): this;
+    once(event: 'connected' | 'disconnected' | 'maxReconnectAttemptsReached', listener: () => void): this;
+    once(event: 'reconnecting', listener: (data: {
+        attempt: number;
+        delay: number;
+    }) => void): this;
+    once(event: 'error', listener: (error: Error) => void): this;
+    once(event: 'warning', listener: (data: {
+        type: string;
+        reqId?: string;
+    }) => void): this;
+    once(event: 'queueEvent', listener: (event: JobEvent) => void): this;
+    once(event: 'health', listener: (data: {
+        type: string;
+        latency?: number;
+        reason?: string;
+    }) => void): this;
+    protected socket: SocketWrapper | null;
+    protected connected: boolean;
+    protected connecting: boolean;
+    protected readonly options: Required<ConnectionOptions>;
+    protected readonly health: HealthTracker;
+    protected readonly reconnect: ReconnectManager;
+    protected readonly commands: CommandQueue;
+    protected reqIdCounter: number;
+    constructor(options?: Partial<ConnectionOptions>);
+}

package/dist/types/src/client/tcp/shared.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared TCP Client Instances
+ * One shared client per distinct connection target. Keyed by
+ * host/port/token/tls so callers with different configs (notably TLS vs
+ * plaintext to the same server) never receive each other's connection.
+ */
+import type { ConnectionOptions } from "./types.js";
+import { TcpClient } from "./client.js";
+/** Get shared TCP client for the given connection target */
+export declare function getSharedTcpClient(options?: Partial<ConnectionOptions>): TcpClient;
+/** Close all shared clients */
+export declare function closeSharedTcpClient(): void;

package/dist/types/src/client/tcp/transport.d.ts

@@ -0,0 +1,18 @@
+import type { ClientTlsOptions, SocketWrapper } from "./types.js";
+export interface ConnectionEvents {
+    onData: (frame: Uint8Array) => void;
+    onClose: () => void;
+    onError: (error: Error) => void;
+}
+export interface ConnectionResult {
+    socket: SocketWrapper;
+    cleanup: () => void;
+}
+export interface ConnectionTarget {
+    host?: string;
+    port?: number;
+    tls?: boolean | ClientTlsOptions;
+}
+export declare function buildClientTls(tls: boolean | ClientTlsOptions | undefined): true | Record<string, unknown> | undefined;
+export declare function tlsRequiresVerification(tls: boolean | ClientTlsOptions | undefined): boolean;
+export declare function createConnection(target: ConnectionTarget, connectTimeout: number, events: ConnectionEvents): Promise<ConnectionResult>;

package/dist/types/src/client/tcp/types/command.d.ts

@@ -0,0 +1,9 @@
+export interface PendingCommand {
+    id: number;
+    reqId: string;
+    command: Record<string, unknown>;
+    resolve: (value: Record<string, unknown>) => void;
+    reject: (error: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+    promise?: Promise<Record<string, unknown>>;
+}

package/dist/types/src/client/tcp/types/connection.d.ts

@@ -0,0 +1,31 @@
+import type { ClientTlsOptions } from "./tls.js";
+export interface ConnectionOptions {
+    host: string;
+    port: number;
+    token?: string;
+    tls?: boolean | ClientTlsOptions;
+    maxReconnectAttempts?: number;
+    reconnectDelay?: number;
+    maxReconnectDelay?: number;
+    connectTimeout?: number;
+    commandTimeout?: number;
+    autoReconnect?: boolean;
+    pingInterval?: number;
+    maxPingFailures?: number;
+    maxCommandTimeouts?: number;
+    pipelining?: boolean;
+    maxInFlight?: number;
+}
+export interface ConnectionHealth {
+    healthy: boolean;
+    state: 'connected' | 'connecting' | 'disconnected' | 'closed';
+    lastSuccessAt: number | null;
+    lastErrorAt: number | null;
+    avgLatencyMs: number;
+    consecutivePingFailures: number;
+    consecutiveCommandTimeouts: number;
+    totalCommands: number;
+    totalErrors: number;
+    uptimeMs: number;
+}
+export declare const DEFAULT_CONNECTION: Required<ConnectionOptions>;

package/dist/types/src/client/tcp/types/index.d.ts

@@ -0,0 +1,5 @@
+export type { PendingCommand } from "./command.js";
+export { DEFAULT_CONNECTION } from "./connection.js";
+export type { ConnectionHealth, ConnectionOptions } from "./connection.js";
+export type { FrameParser, SocketWrapper } from "./socket.js";
+export type { ClientTlsOptions } from "./tls.js";

package/dist/types/src/client/tcp/types/socket.d.ts

@@ -0,0 +1,8 @@
+export interface SocketWrapper {
+    write: (data: Uint8Array | string) => void;
+    end: () => void;
+    frameParser: FrameParser;
+}
+export interface FrameParser {
+    addData(data: Uint8Array): Uint8Array[];
+}

package/dist/types/src/client/tcp/types/tls.d.ts

@@ -0,0 +1,4 @@
+export interface ClientTlsOptions {
+    rejectUnauthorized?: boolean;
+    caFile?: string;
+}

package/dist/types/src/client/tcp/types.d.ts

@@ -0,0 +1,2 @@
+/** Backwards-compatible barrel for TCP client types. */
+export * from "./types/index.js";

package/dist/types/src/client/tcpClient.d.ts

@@ -0,0 +1,6 @@
+/**
+ * TCP Client - Re-exports from tcp module
+ * @deprecated Import from './tcp' instead
+ */
+export type { ConnectionOptions, ConnectionHealth } from "./tcp/index.js";
+export { DEFAULT_CONNECTION, TcpClient, getSharedTcpClient, closeSharedTcpClient } from "./tcp/index.js";

package/dist/types/src/client/tcpPool.d.ts

@@ -0,0 +1,69 @@
+/**
+ * TCP Connection Pool
+ * Manages multiple TCP connections for parallel operations
+ */
+import { type ConnectionOptions, type ConnectionHealth } from "./tcpClient.js";
+export interface PoolOptions extends Partial<ConnectionOptions> {
+    /** Number of connections in pool (default: 4) */
+    poolSize?: number;
+}
+/**
+ * Connection pool for parallel TCP operations
+ * Load-aware distribution - prefers connected clients with capacity
+ */
+export declare class TcpConnectionPool {
+    private readonly clients;
+    private readonly options;
+    private currentIndex;
+    private closed;
+    private refCount;
+    private poolKey;
+    constructor(options?: PoolOptions);
+    /** Connect all clients in pool */
+    connect(): Promise<void>;
+    /** Get next client with load-aware selection */
+    private getNextClient;
+    /** Send command using next available connection */
+    send(command: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Send multiple commands in parallel across pool */
+    sendParallel(commands: Array<Record<string, unknown>>): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Invoke `cb` whenever a pooled connection (re)establishes. TcpClient emits
+     * 'connected' on every successful connect, including reconnects. Used by
+     * Worker to re-register after a reconnect (the server drops registration when
+     * the registering connection closes and each reconnect gets a fresh clientId).
+     */
+    onReconnect(cb: () => void): void;
+    /** Check if any connection is ready */
+    isConnected(): boolean;
+    /** Get number of connected clients */
+    getConnectedCount(): number;
+    /** Get pool size */
+    getPoolSize(): number;
+    /** Increment reference count (for shared pools) */
+    addRef(): void;
+    /** Decrement reference count and close if zero */
+    release(): void;
+    /** Set pool key for shared pool cleanup */
+    setPoolKey(key: string): void;
+    /** Close all connections */
+    close(): void;
+    /** Check if pool is closed */
+    isClosed(): boolean;
+    /** Get aggregated health metrics for the pool */
+    getHealth(): {
+        healthy: boolean;
+        connectedCount: number;
+        totalCount: number;
+        clients: ConnectionHealth[];
+        avgLatencyMs: number;
+        totalCommands: number;
+        totalErrors: number;
+    };
+}
+/** Get or create shared connection pool */
+export declare function getSharedPool(options?: PoolOptions): TcpConnectionPool;
+/** Release shared pool reference */
+export declare function releaseSharedPool(pool: TcpConnectionPool): void;
+/** Close all shared pools */
+export declare function closeAllSharedPools(): void;

package/dist/types/src/client/types/connection.d.ts

@@ -0,0 +1,30 @@
+import type { ClientTlsOptions } from "../tcp/types.js";
+import type { JobOptions } from "./options.js";
+export type { ClientTlsOptions } from "../tcp/types.js";
+export interface ConnectionOptions {
+    host?: string;
+    port?: number;
+    socketPath?: string;
+    tls?: boolean | ClientTlsOptions;
+    token?: string;
+    poolSize?: number;
+    pingInterval?: number;
+    commandTimeout?: number;
+    maxCommandTimeouts?: number;
+    pipelining?: boolean;
+    maxInFlight?: number;
+}
+export interface AutoBatchOptions {
+    enabled?: boolean;
+    maxSize?: number;
+    maxDelayMs?: number;
+}
+export interface QueueOptions {
+    defaultJobOptions?: JobOptions;
+    connection?: ConnectionOptions;
+    embedded?: boolean;
+    /** Must match the process-wide embedded manager when one is already active. */
+    dataPath?: string;
+    autoBatch?: AutoBatchOptions;
+    prefixKey?: string;
+}