amqplib 1.1.0 → 1.2.0

package/.github/workflows/test.yml

@@ -47,5 +47,8 @@ jobs:
 
       - run: echo 'HELO\n\n\n\n' | nc localhost 5672 | grep AMQP
 
+      # Check TypeScript types
+      - run: npm run typecheck
+
       # Run the tests
       - run: make test

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change log for amqplib
 
+## v1.2.0
+- Add bundled TypeScript type definitions (fixes #843)
+
+## v1.1.1
+- Forward `handler-error` events from the underlying connection to the recovery wrapper, so listeners attached to `RecoveringPromiseModel`/`RecoveringCallbackModel` receive handler errors
+
 ## v1.1.0
 - Add connection recovery via `connectWithRecoveryPromise` and `connectWithRecoveryCallback` — automatically reconnects on connection loss with configurable backoff delay, jitter, and retry limits (thanks [@ShiriNmi1520](https://github.com/ShiriNmi1520))
 

package/callback_api.d.ts

@@ -0,0 +1,209 @@
+import events = require('events');
+import {
+  ChannelOptions,
+  ConsumeMessage,
+  GetMessage,
+  Message,
+  Options,
+  Replies,
+  ServerProperties,
+  SocketOptions,
+} from './lib/properties';
+export * from './lib/properties';
+
+export interface Connection extends events.EventEmitter {
+  close(callback?: (err: Error) => void): void;
+  createChannel(callback: (err: Error, channel: Channel) => void): Channel;
+  createChannel(options: ChannelOptions, callback: (err: Error, channel: Channel) => void): Channel;
+  createConfirmChannel(callback: (err: Error, confirmChannel: ConfirmChannel) => void): ConfirmChannel;
+  createConfirmChannel(options: ChannelOptions, callback: (err: Error, confirmChannel: ConfirmChannel) => void): ConfirmChannel;
+  readonly connection: {
+    readonly serverProperties: ServerProperties;
+  };
+  updateSecret(newSecret: Buffer, reason: string, callback?: (err: Error) => void): void;
+
+  on(event: 'close', listener: (err?: Error) => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'blocked', listener: (reason: string) => void): this;
+  on(event: 'unblocked', listener: () => void): this;
+  on(event: 'update-secret-ok', listener: () => void): this;
+  on(event: 'handler-error', listener: (err: Error, eventName: string) => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+export interface Channel extends events.EventEmitter {
+  readonly connection: Connection;
+
+  on(event: 'close', listener: () => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'drain', listener: () => void): this;
+  on(event: 'ack', listener: (fields: { deliveryTag: number; multiple: boolean }) => void): this;
+  on(event: 'nack', listener: (fields: { deliveryTag: number; multiple: boolean; requeue: boolean }) => void): this;
+  on(event: 'cancel', listener: (fields: { consumerTag: string }) => void): this;
+  on(event: 'delivery', listener: (message: ConsumeMessage) => void): this;
+  on(event: 'return', listener: (message: Message) => void): this;
+  on(event: 'handler-error', listener: (err: Error, eventName: string) => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+
+  close(callback?: (err: Error) => void): void;
+
+  assertQueue(queue?: string, options?: Options.AssertQueue, callback?: (err: Error, ok: Replies.AssertQueue) => void): void;
+  checkQueue(queue: string, callback?: (err: Error, ok: Replies.AssertQueue) => void): void;
+
+  deleteQueue(queue: string, options?: Options.DeleteQueue, callback?: (err: Error, ok: Replies.DeleteQueue) => void): void;
+  purgeQueue(queue: string, callback?: (err: Error, ok: Replies.PurgeQueue) => void): void;
+
+  bindQueue(
+    queue: string,
+    source: string,
+    pattern: string,
+    args?: any,
+    callback?: (err: Error, ok: Replies.Empty) => void,
+  ): void;
+  unbindQueue(
+    queue: string,
+    source: string,
+    pattern: string,
+    args?: any,
+    callback?: (err: Error, ok: Replies.Empty) => void,
+  ): void;
+
+  assertExchange(
+    exchange: string,
+    type: 'direct' | 'topic' | 'headers' | 'fanout' | 'match' | string,
+    options?: Options.AssertExchange,
+    callback?: (err: Error, ok: Replies.AssertExchange) => void,
+  ): void;
+  checkExchange(exchange: string, callback?: (err: Error, ok: Replies.Empty) => void): void;
+
+  deleteExchange(exchange: string, options?: Options.DeleteExchange, callback?: (err: Error, ok: Replies.Empty) => void): void;
+
+  bindExchange(
+    destination: string,
+    source: string,
+    pattern: string,
+    args?: any,
+    callback?: (err: Error, ok: Replies.Empty) => void,
+  ): void;
+  unbindExchange(
+    destination: string,
+    source: string,
+    pattern: string,
+    args?: any,
+    callback?: (err: Error, ok: Replies.Empty) => void,
+  ): void;
+
+  publish(exchange: string, routingKey: string, content: Buffer, options?: Options.Publish): boolean;
+  sendToQueue(queue: string, content: Buffer, options?: Options.Publish): boolean;
+
+  consume(
+    queue: string,
+    onMessage: (msg: ConsumeMessage | null) => void,
+    options?: Options.Consume,
+    callback?: (err: Error, ok: Replies.Consume) => void,
+  ): void;
+
+  cancel(consumerTag: string, callback?: (err: Error, ok: Replies.Empty) => void): void;
+  get(queue: string, options?: Options.Get, callback?: (err: Error, ok: GetMessage | false) => void): void;
+
+  ack(message: Message, allUpTo?: boolean): void;
+  ackAll(): void;
+
+  nack(message: Message, allUpTo?: boolean, requeue?: boolean): void;
+  nackAll(requeue?: boolean): void;
+  reject(message: Message, requeue?: boolean): void;
+
+  prefetch(count: number, global?: boolean, callback?: (err: Error, ok: Replies.Empty) => void): void;
+  recover(callback?: (err: Error, ok: Replies.Empty) => void): void;
+}
+
+export interface ConfirmChannel extends Channel {
+  publish(
+    exchange: string,
+    routingKey: string,
+    content: Buffer,
+    options?: Options.Publish,
+    callback?: (err: Error, ok: Replies.Empty) => void,
+  ): boolean;
+  sendToQueue(
+    queue: string,
+    content: Buffer,
+    options?: Options.Publish,
+    callback?: (err: Error, ok: Replies.Empty) => void,
+  ): boolean;
+
+  waitForConfirms(callback?: (err?: Error) => void): void;
+}
+
+export declare class IllegalOperationError extends Error {
+  name: 'IllegalOperationError';
+  stackAtStateChange: string | undefined;
+  constructor(msg: string, stack?: string);
+}
+
+export declare const credentials: {
+  plain(username: string, password: string): {
+    mechanism: string;
+    response(): Buffer;
+    username: string;
+    password: string;
+  };
+  amqplain(username: string, password: string): {
+    mechanism: string;
+    response(): Buffer;
+    username: string;
+    password: string;
+  };
+  external(): {
+    mechanism: string;
+    response(): Buffer;
+  };
+};
+
+export interface RecoveryOptions {
+  /** Initial reconnect delay in milliseconds. Default: 100 */
+  initialDelay?: number;
+  /** Maximum reconnect delay in milliseconds. Default: 30000 */
+  maxDelay?: number;
+  /** Backoff multiplier applied to delay on each attempt. Default: 2 */
+  factor?: number;
+  /** Jitter factor (0–1) applied to delay to avoid thundering herd. Default: 0.2 */
+  jitter?: number;
+  /** Maximum number of reconnect attempts. Default: Infinity */
+  maxRetries?: number;
+  /** Optional setup function called after each successful connection */
+  setup?: ((model: Connection) => Promise<void>) | ((model: Connection, done: (err?: Error) => void) => void);
+}
+
+export interface RecoveringConnection extends events.EventEmitter {
+  close(callback?: (err: Error) => void): void;
+  createChannel(callback: (err: Error, channel: Channel) => void): Channel;
+  createChannel(options: ChannelOptions, callback: (err: Error, channel: Channel) => void): Channel;
+  createConfirmChannel(callback: (err: Error, confirmChannel: ConfirmChannel) => void): ConfirmChannel;
+  createConfirmChannel(options: ChannelOptions, callback: (err: Error, confirmChannel: ConfirmChannel) => void): ConfirmChannel;
+  updateSecret(newSecret: Buffer, reason: string, callback?: (err: Error) => void): void;
+
+  on(event: 'connect', listener: (model: Connection) => void): this;
+  on(event: 'disconnect', listener: (err: Error) => void): this;
+  on(event: 'connect-failed', listener: (err: Error) => void): this;
+  on(event: 'reconnect-scheduled', listener: (info: { attempt: number; delay: number; error: Error }) => void): this;
+  on(event: 'reconnect-failed', listener: (err: Error) => void): this;
+  on(event: 'blocked', listener: (reason: string) => void): this;
+  on(event: 'unblocked', listener: () => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'update-secret-ok', listener: () => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+export declare function connect(callback: (err: Error, connection: Connection) => void): void;
+export declare function connect(url: string | Options.Connect, callback: (err: Error, connection: Connection) => void): void;
+export declare function connect(
+  url: string | Options.Connect,
+  socketOptions: SocketOptions,
+  callback: (err: Error, connection: Connection) => void,
+): void;
+export declare function connect(
+  url: string | Options.Connect,
+  socketOptions: SocketOptions & { recovery: RecoveryOptions | true },
+  callback: (err: Error, connection: RecoveringConnection) => void,
+): RecoveringConnection;

package/index.d.ts

@@ -0,0 +1,171 @@
+import events = require('events');
+import {
+  ChannelOptions,
+  ConsumeMessage,
+  GetMessage,
+  Message,
+  Options,
+  Replies,
+  ServerProperties,
+  SocketOptions,
+} from './lib/properties';
+export * from './lib/properties';
+
+export interface Connection {
+  readonly serverProperties: ServerProperties;
+}
+
+export interface ChannelModel extends events.EventEmitter {
+  close(): Promise<void>;
+  createChannel(options?: ChannelOptions): Promise<Channel>;
+  createConfirmChannel(options?: ChannelOptions): Promise<ConfirmChannel>;
+  readonly connection: Connection;
+  updateSecret(newSecret: Buffer, reason: string): Promise<void>;
+
+  on(event: 'close', listener: (err?: Error) => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'blocked', listener: (reason: string) => void): this;
+  on(event: 'unblocked', listener: () => void): this;
+  on(event: 'update-secret-ok', listener: () => void): this;
+  on(event: 'handler-error', listener: (err: Error, eventName: string) => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+export interface Channel extends events.EventEmitter {
+  readonly connection: Connection;
+
+  on(event: 'close', listener: () => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'drain', listener: () => void): this;
+  on(event: 'ack', listener: (fields: { deliveryTag: number; multiple: boolean }) => void): this;
+  on(event: 'nack', listener: (fields: { deliveryTag: number; multiple: boolean; requeue: boolean }) => void): this;
+  on(event: 'cancel', listener: (fields: { consumerTag: string }) => void): this;
+  on(event: 'delivery', listener: (message: ConsumeMessage) => void): this;
+  on(event: 'return', listener: (message: Message) => void): this;
+  on(event: 'handler-error', listener: (err: Error, eventName: string) => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+
+  close(): Promise<void>;
+
+  assertQueue(queue?: string, options?: Options.AssertQueue): Promise<Replies.AssertQueue>;
+  checkQueue(queue: string): Promise<Replies.AssertQueue>;
+
+  deleteQueue(queue: string, options?: Options.DeleteQueue): Promise<Replies.DeleteQueue>;
+  purgeQueue(queue: string): Promise<Replies.PurgeQueue>;
+
+  bindQueue(queue: string, source: string, pattern: string, args?: any): Promise<Replies.Empty>;
+  unbindQueue(queue: string, source: string, pattern: string, args?: any): Promise<Replies.Empty>;
+
+  assertExchange(
+    exchange: string,
+    type: 'direct' | 'topic' | 'headers' | 'fanout' | 'match' | string,
+    options?: Options.AssertExchange,
+  ): Promise<Replies.AssertExchange>;
+  checkExchange(exchange: string): Promise<Replies.Empty>;
+
+  deleteExchange(exchange: string, options?: Options.DeleteExchange): Promise<Replies.Empty>;
+
+  bindExchange(destination: string, source: string, pattern: string, args?: any): Promise<Replies.Empty>;
+  unbindExchange(destination: string, source: string, pattern: string, args?: any): Promise<Replies.Empty>;
+
+  publish(exchange: string, routingKey: string, content: Buffer, options?: Options.Publish): boolean;
+  sendToQueue(queue: string, content: Buffer, options?: Options.Publish): boolean;
+
+  consume(
+    queue: string,
+    onMessage: (msg: ConsumeMessage | null) => void,
+    options?: Options.Consume,
+  ): Promise<Replies.Consume>;
+
+  cancel(consumerTag: string): Promise<Replies.Empty>;
+  get(queue: string, options?: Options.Get): Promise<GetMessage | false>;
+
+  ack(message: Message, allUpTo?: boolean): void;
+  ackAll(): void;
+
+  nack(message: Message, allUpTo?: boolean, requeue?: boolean): void;
+  nackAll(requeue?: boolean): void;
+  reject(message: Message, requeue?: boolean): void;
+
+  prefetch(count: number, global?: boolean): Promise<Replies.Empty>;
+  recover(): Promise<Replies.Empty>;
+}
+
+export interface ConfirmChannel extends Channel {
+  publish(
+    exchange: string,
+    routingKey: string,
+    content: Buffer,
+    options?: Options.Publish,
+    callback?: (err: any, ok: Replies.Empty) => void,
+  ): boolean;
+  sendToQueue(
+    queue: string,
+    content: Buffer,
+    options?: Options.Publish,
+    callback?: (err: any, ok: Replies.Empty) => void,
+  ): boolean;
+
+  waitForConfirms(): Promise<void>;
+}
+
+export declare class IllegalOperationError extends Error {
+  name: 'IllegalOperationError';
+  stackAtStateChange: string | undefined;
+  constructor(msg: string, stack?: string);
+}
+
+export declare const credentials: {
+  plain(username: string, password: string): {
+    mechanism: string;
+    response(): Buffer;
+    username: string;
+    password: string;
+  };
+  amqplain(username: string, password: string): {
+    mechanism: string;
+    response(): Buffer;
+    username: string;
+    password: string;
+  };
+  external(): {
+    mechanism: string;
+    response(): Buffer;
+  };
+};
+
+export interface RecoveryOptions {
+  /** Initial reconnect delay in milliseconds. Default: 100 */
+  initialDelay?: number;
+  /** Maximum reconnect delay in milliseconds. Default: 30000 */
+  maxDelay?: number;
+  /** Backoff multiplier applied to delay on each attempt. Default: 2 */
+  factor?: number;
+  /** Jitter factor (0–1) applied to delay to avoid thundering herd. Default: 0.2 */
+  jitter?: number;
+  /** Maximum number of reconnect attempts. Default: Infinity */
+  maxRetries?: number;
+  /** Optional setup function called after each successful connection */
+  setup?: ((model: ChannelModel) => Promise<void>) | ((model: ChannelModel, done: (err?: Error) => void) => void);
+}
+
+export interface RecoveringChannelModel extends events.EventEmitter {
+  close(): Promise<void>;
+  createChannel(options?: ChannelOptions): Promise<Channel>;
+  createConfirmChannel(options?: ChannelOptions): Promise<ConfirmChannel>;
+  updateSecret(newSecret: Buffer, reason: string): Promise<void>;
+
+  on(event: 'connect', listener: (model: ChannelModel) => void): this;
+  on(event: 'disconnect', listener: (err: Error) => void): this;
+  on(event: 'connect-failed', listener: (err: Error) => void): this;
+  on(event: 'reconnect-scheduled', listener: (info: { attempt: number; delay: number; error: Error }) => void): this;
+  on(event: 'reconnect-failed', listener: (err: Error) => void): this;
+  on(event: 'blocked', listener: (reason: string) => void): this;
+  on(event: 'unblocked', listener: () => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'update-secret-ok', listener: () => void): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+}
+
+export declare function connect(url: string | Options.Connect, socketOptions: SocketOptions & { recovery: RecoveryOptions | true }): Promise<RecoveringChannelModel>;
+export declare function connect(url: string | Options.Connect, socketOptions?: SocketOptions): Promise<ChannelModel>;

package/lefthook.yml

@@ -10,5 +10,8 @@ pre-commit:
       glob: "**/*.js"
       run: npx biome lint {staged_files} --write
       stage_fixed: true
+    typecheck:
+      glob: "{**/*.d.ts,types/*.ts}"
+      run: npm run typecheck
     test:
       run: npm test

package/lib/properties.d.ts

@@ -0,0 +1,208 @@
+import * as tls from 'tls';
+
+export namespace Replies {
+  interface Empty {}
+  interface AssertQueue {
+    queue: string;
+    messageCount: number;
+    consumerCount: number;
+  }
+  interface PurgeQueue {
+    messageCount: number;
+  }
+  interface DeleteQueue {
+    messageCount: number;
+  }
+  interface AssertExchange {
+    exchange: string;
+  }
+  interface Consume {
+    consumerTag: string;
+  }
+}
+
+export namespace Options {
+  interface Connect {
+    protocol?: string;
+    hostname?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    locale?: string;
+    frameMax?: number;
+    heartbeat?: number;
+    vhost?: string;
+    channelMax?: number;
+    credentials?: {
+      mechanism: string;
+      response(): Buffer;
+      username?: string;
+      password?: string;
+    };
+  }
+
+  interface AssertQueue {
+    exclusive?: boolean;
+    durable?: boolean;
+    autoDelete?: boolean;
+    arguments?: any;
+    messageTtl?: number;
+    expires?: number;
+    deadLetterExchange?: string;
+    deadLetterRoutingKey?: string;
+    maxLength?: number;
+    maxPriority?: number;
+    overflow?: string;
+    queueMode?: string;
+  }
+
+  interface DeleteQueue {
+    ifUnused?: boolean;
+    ifEmpty?: boolean;
+  }
+
+  interface AssertExchange {
+    durable?: boolean;
+    internal?: boolean;
+    autoDelete?: boolean;
+    alternateExchange?: string;
+    arguments?: any;
+  }
+
+  interface DeleteExchange {
+    ifUnused?: boolean;
+  }
+
+  interface Publish {
+    expiration?: string | number;
+    userId?: string;
+    CC?: string | string[];
+    mandatory?: boolean;
+    persistent?: boolean;
+    deliveryMode?: boolean | number;
+    BCC?: string | string[];
+    contentType?: string;
+    contentEncoding?: string;
+    headers?: any;
+    priority?: number;
+    correlationId?: string;
+    replyTo?: string;
+    messageId?: string;
+    timestamp?: number;
+    type?: string;
+    appId?: string;
+  }
+
+  interface Consume {
+    consumerTag?: string;
+    noLocal?: boolean;
+    noAck?: boolean;
+    exclusive?: boolean;
+    priority?: number;
+    arguments?: any;
+  }
+
+  interface Get {
+    noAck?: boolean;
+  }
+}
+
+export interface SocketOptions extends tls.ConnectionOptions {
+  noDelay?: boolean;
+  timeout?: number;
+  keepAlive?: boolean;
+  keepAliveDelay?: number;
+  clientProperties?: Record<string, unknown>;
+  credentials?: {
+    mechanism: string;
+    response(): Buffer;
+    username?: string;
+    password?: string;
+  };
+}
+
+export interface ChannelOptions {
+  highWaterMark?: number;
+}
+
+export interface Message {
+  content: Buffer;
+  fields: MessageFields;
+  properties: MessageProperties;
+}
+
+export interface GetMessage extends Message {
+  fields: GetMessageFields;
+}
+
+export interface ConsumeMessage extends Message {
+  fields: ConsumeMessageFields;
+}
+
+export interface CommonMessageFields {
+  deliveryTag: number;
+  redelivered: boolean;
+  exchange: string;
+  routingKey: string;
+}
+
+export interface MessageFields extends CommonMessageFields {
+  messageCount?: number;
+  consumerTag?: string;
+}
+
+export interface GetMessageFields extends CommonMessageFields {
+  messageCount: number;
+}
+
+export interface ConsumeMessageFields extends CommonMessageFields {
+  consumerTag: string;
+}
+
+export interface MessageProperties {
+  contentType: any | undefined;
+  contentEncoding: any | undefined;
+  headers: MessagePropertyHeaders | undefined;
+  deliveryMode: any | undefined;
+  priority: any | undefined;
+  correlationId: any | undefined;
+  replyTo: any | undefined;
+  expiration: any | undefined;
+  messageId: any | undefined;
+  timestamp: any | undefined;
+  type: any | undefined;
+  userId: any | undefined;
+  appId: any | undefined;
+  clusterId: any | undefined;
+}
+
+export interface MessagePropertyHeaders {
+  'x-first-death-exchange'?: string;
+  'x-first-death-queue'?: string;
+  'x-first-death-reason'?: string;
+  'x-death'?: XDeath[];
+  [key: string]: any;
+}
+
+export interface XDeath {
+  count: number;
+  reason: 'rejected' | 'expired' | 'maxlen';
+  queue: string;
+  time: {
+    '!': 'timestamp';
+    value: number;
+  };
+  exchange: string;
+  'original-expiration'?: any;
+  'routing-keys': string[];
+}
+
+export interface ServerProperties {
+  host: string;
+  product: string;
+  version: string;
+  platform: string;
+  copyright?: string;
+  information: string;
+  [key: string]: string | undefined;
+}

package/lib/recovery.js

@@ -220,12 +220,14 @@ class RecoveringCore extends EventEmitter {
     const onUnblocked = () => this.emit('unblocked');
     const onConnectionError = (err) => this.emit('error', err);
     const onUpdateSecretOk = () => this.emit('update-secret-ok');
+    const onHandlerError = (err, event) => this.emit('handler-error', err, event);
 
     model.on('close', onClose);
     model.on('blocked', onBlocked);
     model.on('unblocked', onUnblocked);
     model.on('error', onConnectionError);
     model.on('update-secret-ok', onUpdateSecretOk);
+    model.on('handler-error', onHandlerError);
 
     this._modelListeners = {
       model,
@@ -234,17 +236,19 @@ class RecoveringCore extends EventEmitter {
       onUnblocked,
       onConnectionError,
       onUpdateSecretOk,
+      onHandlerError,
     };
   }
 
   _unbindModel() {
     if (!this._modelListeners) return;
-    const { model, onClose, onBlocked, onUnblocked, onConnectionError, onUpdateSecretOk } = this._modelListeners;
+    const { model, onClose, onBlocked, onUnblocked, onConnectionError, onUpdateSecretOk, onHandlerError } = this._modelListeners;
     model.removeListener('close', onClose);
     model.removeListener('blocked', onBlocked);
     model.removeListener('unblocked', onUnblocked);
     model.removeListener('error', onConnectionError);
     model.removeListener('update-secret-ok', onUpdateSecretOk);
+    model.removeListener('handler-error', onHandlerError);
     model.on('error', () => {});
     this._modelListeners = null;
   }
@@ -366,6 +370,7 @@ function wireCommonEvents(source, target) {
     'unblocked',
     'error',
     'update-secret-ok',
+    'handler-error',
   ].forEach((eventName) => {
     source.on(eventName, (...args) => target.emit(eventName, ...args));
   });

package/package.json

@@ -2,7 +2,18 @@
   "name": "amqplib",
   "homepage": "http://amqp-node.github.io/amqplib/",
   "main": "./channel_api.js",
-  "version": "1.1.0",
+  "version": "1.2.0",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./channel_api.js"
+    },
+    "./callback_api": {
+      "types": "./callback_api.d.ts",
+      "default": "./callback_api.js"
+    }
+  },
   "description": "An AMQP 0-9-1 (e.g., RabbitMQ) library and client.",
   "repository": {
     "type": "git",
@@ -16,8 +27,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.2.2",
+    "@types/node": "^25.6.0",
     "claire": "0.4.1",
     "lefthook": "^1.12.3",
+    "typescript": "^5.9.3",
     "uglify-js": "2.8.x"
   },
   "scripts": {
@@ -26,7 +39,8 @@
     "rabbitmq-3": "docker run -d --rm --name rabbitmq -p 5672:5672 rabbitmq:3.12-alpine",
     "rabbitmq-4": "docker run -d --rm --name rabbitmq -p 5672:5672 rabbitmq:4.2-alpine",
     "format": "biome format . --write",
-    "lint": "biome lint --max-diagnostics=1000 ."
+    "lint": "biome lint --max-diagnostics=1000 .",
+    "typecheck": "tsc --noEmit -p tsconfig.types.json"
   },
   "keywords": [
     "AMQP",

package/test/recovery.test.js

@@ -167,6 +167,38 @@ describe('recovery', () => {
     assert(client);
   });
 
+  it('handler-error from underlying model is forwarded to recovery wrapper', async () => {
+    const models = [];
+    let opened = 0;
+
+    function openModel() {
+      const model = new FakePromiseModel(++opened);
+      models.push(model);
+      return Promise.resolve(model);
+    }
+
+    const client = await recovery.connectWithRecoveryPromise(openModel, {
+      initialDelay: 1,
+      maxDelay: 1,
+      jitter: 0,
+    });
+
+    const expectedErr = new Error('user close handler explodes');
+
+    await new Promise((resolve) => {
+      client.on('handler-error', (err, event) => {
+        assert.strictEqual(err, expectedErr);
+        assert.strictEqual(event, 'close');
+        resolve();
+      });
+
+      // Simulate a handler throwing in a 'close' listener on the underlying model
+      models[0].emit('handler-error', expectedErr, 'close');
+    });
+
+    await client.close();
+  });
+
   it('promise recovery fails after max retries', async () => {
     let attempts = 0;