@fgiova/sqs-consumer 2.2.1 → 3.1.0

package/README.md

@@ -29,6 +29,25 @@ const consumer = new SQSConsumer({
 
 ```
 
+## Handler cancellation on timeout
+
+When `handlerOptions.executionTimeout` triggers, the consumer aborts the in-flight handler via an `AbortSignal` exposed through `AsyncLocalStorage`. The handler does not need to receive the signal as an argument — it is retrieved on demand using the `getAbortSignal` helper. Pass it to any cancellable async API (`fetch`, `undici`, timers, streams) to release resources promptly and avoid zombie handlers retaining memory after a timeout.
+
+```typescript
+import { SQSConsumer, getAbortSignal } from '@fgiova/sqs-consumer'
+
+const consumer = new SQSConsumer({
+    queueARN: "arn:aws:sqs:eu-central-1:000000000000:test-queue-hooks",
+    handler: async (message) => {
+        const signal = getAbortSignal();
+        const res = await fetch("https://api.example.com/work", { signal });
+        return res.json();
+    }
+});
+```
+
+`getAbortSignal()` returns `undefined` when called outside a handler execution context. Handlers that ignore it keep working unchanged.
+
 ## Options
 | Option          | Type                                | Default | Description                                        |
 |-----------------|-------------------------------------|---------|----------------------------------------------------|
@@ -39,15 +58,15 @@ const consumer = new SQSConsumer({
 | handlerOptions  | HandlerOptions                      |         | The options for the handler                        |
 | clientOptions   | ClientOptions                       |         | The options for the client                         |
 | consumerOptions | ConsumerOptions                     |         | The options for the consumer                       |
-| hooks           | Hooks                               |         | The hooks to be called on specific events          |
+| hooks           | HooksOptions                        |         | The hooks to be called on specific events          |
 
 ### HandlerOptions
-| Option            | Type    | Default | Description                                                                                              |
-|-------------------|---------|---------|----------------------------------------------------------------------------------------------------------|
-| deleteMessage     | boolean | true    | Whether to delete the message after handling (if handler execute without any error)                      |
-| extendVisibility  | boolean | true    | Whether to extend the visibility timeout during message handling                                         |
-| excuteTimeout     | number  | 30000   | The timeout for the handler execution in ms                                                              |
-| parallelExecution | boolean | true    | If true execute handler in parallel for each batch of messages received, otherwise execute consecutively |
+| Option                  | Type    | Default | Description                                                                                              |
+|-------------------------|---------|---------|----------------------------------------------------------------------------------------------------------|
+| deleteMessage           | boolean | true    | Whether to delete the message after handling (if handler execute without any error)                      |
+| extendVisibilityTimeout | boolean | true    | Whether to extend the visibility timeout during message handling                                         |
+| executionTimeout        | number  | 30000   | The timeout for the handler execution in ms                                                              |
+| parallelExecution       | boolean | true    | If true execute handler in parallel for each batch of messages received, otherwise execute consecutively |
 
 ### ClientOptions
 | Option           | Type                   | Default | Description                                                                                               |
@@ -56,7 +75,7 @@ const consumer = new SQSConsumer({
 | endpoint         | string                 |         | The endpoint to be used for the client. If not provided, the endpoint will be inferred from the queueARN. |
 | undiciOptions    | Pool.Options           |         | The options for the undici client.                                                                        |
 | signer           | Signer / SignerOptions |         | The signer to be used for signing requests. If not provided, a new singleton signer will be created.      |
-| destroySigner    | boolean                | false   | Whether to destroy the signer when the consumer is destroyed.                                             |
+| destroySigner    | boolean                | true    | Whether to destroy the signer when the consumer is destroyed.                                             |
 
 ### ConsumerOptions
 | Option                | Type     | Default | Description                                                |
@@ -68,17 +87,16 @@ const consumer = new SQSConsumer({
 | attributeNames        | string[] | []      | The attribute names to be included in the response         |
 
 ### Hooks
-| Option           | Type                                                                  | Description                                                          |
-|------------------|-----------------------------------------------------------------------|----------------------------------------------------------------------|
-| onPoll           | (messages: Message[]) => Promise<Message[]>                           | Called when the consumer polls for messages                          |
-| onMessage        | (message: Message) => Promise<Message>                                | Called when the consumer receives a message                          |
-| onHandle         | (message: Message) => Promise<Message>                                | Called when the consumer handles a message                           |
-| onHandlerSuccess | (message: Message) => Promise<Message>                                | Called when the consumer handles a message successfully              |
-| onHandlerTimeout | (message: Message) => Promise<Message>                                | Called when the consumer handler execution exceed executionTimeout   |
-| onHandlerError   | (message: Message, error: Error) => Promise<Boolean>                  | Called when the consumer handler execution throws an error           |
-| onSuccess        | (message: Message) => Promise<Message>                                | Called when the consumer handler execution finishes successfully     |
-| onError          | ( hook: HookName, message: Message, error: Error) => Promise<Boolean> | Called when the consumer handler execution throws an uncaught error  |
-| onSQSError       | (error: Error, message?: Message) => Promise<void>                    | Called when the consumer receives an error from the SQS service      |
+| Option           | Type                                                                  | Description                                                         |
+|------------------|-----------------------------------------------------------------------|---------------------------------------------------------------------|
+| onPoll           | (messages: Message[]) => Promise<Message[]>                           | Called when the consumer polls for messages                         |
+| onMessage        | (message: Message) => Promise<Message>                                | Called when the consumer receives a message                         |
+| onHandlerSuccess | (message: Message) => Promise<Message>                                | Called when the consumer handles a message successfully             |
+| onHandlerTimeout | (message: Message) => Promise<boolean>                                | Called when the consumer handler execution exceed executionTimeout  |
+| onHandlerError   | (message: Message, error: Error) => Promise<boolean>                  | Called when the consumer handler execution throws an error          |
+| onSuccess        | (message: Message) => Promise<boolean>                                | Called when the consumer handler execution finishes successfully    |
+| onError          | (hook: HookName, message: Message, error: Error) => Promise<boolean>  | Called when the consumer handler execution throws an uncaught error |
+| onSQSError       | (error: Error, message?: Message) => Promise<void>                    | Called when the consumer receives an error from the SQS service     |
 
 ## API
 
@@ -86,7 +104,8 @@ const consumer = new SQSConsumer({
 SQSConsumer(options: SQSConsumerOptions)
 SQSConsumer.start(): Promise<void>
 SQSConsumer.stop(destroyConsumer = false): Promise<void>
-SQSConsumer.addHook(hookname: string, func: Function): void
+SQSConsumer.addHook<H extends HookName>(hookName: H, value: HookCallback<H>): this
+getAbortSignal(): AbortSignal | undefined
 ```
 
 ## License

package/dist/cjs/context.d.ts

@@ -0,0 +1,7 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+type HandlerContext = {
+    signal: AbortSignal;
+};
+export declare const handlerContext: AsyncLocalStorage<HandlerContext>;
+export declare function getAbortSignal(): AbortSignal | undefined;
+export {};

package/dist/cjs/context.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handlerContext = void 0;
+exports.getAbortSignal = getAbortSignal;
+const node_async_hooks_1 = require("node:async_hooks");
+exports.handlerContext = new node_async_hooks_1.AsyncLocalStorage();
+function getAbortSignal() {
+    return exports.handlerContext.getStore()?.signal;
+}

package/dist/cjs/errors.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TimeoutError = void 0;
 class TimeoutError extends Error {
     constructor(message) {
-        /* c8 ignore next 1 */
         super(message || "Timeout Error");
         this.name = "TimeoutError";
     }

package/dist/cjs/hooks.d.ts

@@ -2,13 +2,56 @@
 import type { Message } from "@fgiova/mini-sqs-client";
 import type { Logger } from "./logger";
 export type HookName = "onStart" | "onStop" | "onPoll" | "onMessage" | "onHandlerSuccess" | "onHandlerTimeout" | "onHandlerError" | "onSuccess" | "onError" | "onSQSError";
+export type HookSignatureMap = {
+    onStart: {
+        args: [sqsConsumer: unknown];
+        return: undefined;
+    };
+    onStop: {
+        args: [sqsConsumer: unknown];
+        return: undefined;
+    };
+    onPoll: {
+        args: [messages: Message[]];
+        return: Message[];
+    };
+    onMessage: {
+        args: [message: Message];
+        return: Message;
+    };
+    onHandlerSuccess: {
+        args: [message: Message];
+        return: Message;
+    };
+    onHandlerTimeout: {
+        args: [message: Message];
+        return: boolean;
+    };
+    onHandlerError: {
+        args: [message: Message, error: Error];
+        return: boolean;
+    };
+    onSuccess: {
+        args: [message: Message];
+        return: boolean;
+    };
+    onError: {
+        args: [hook: HookName, message: Message, error: Error];
+        return: boolean;
+    };
+    onSQSError: {
+        args: [error: Error, message?: Message];
+        return: undefined;
+    };
+};
+export type HookCallback<H extends HookName> = (...args: HookSignatureMap[H]["args"]) => HookSignatureMap[H]["return"] | Promise<HookSignatureMap[H]["return"]> | void | Promise<void> | undefined;
 export declare class Hooks {
     private readonly hookSymbols;
     private readonly hooks;
     private readonly logger;
     constructor(logger?: Logger);
-    addHook(hook: HookName, fn: Function): void;
-    runHook(hook: HookName, ...args: any[]): Promise<boolean | void | Message | Message[]>;
+    addHook<H extends HookName>(hook: H, fn: HookCallback<H>): void;
+    runHook<H extends HookName>(hook: H, ...args: HookSignatureMap[H]["args"]): Promise<HookSignatureMap[H]["return"]>;
     private runHookWithVoidReturn;
     private runHookWithMessageReturn;
     private runHookWithBooleanReturn;

package/dist/cjs/hooks.js

@@ -75,31 +75,36 @@ class Hooks {
             throw new Error(`Invalid hook ${hook}`);
         this.hooks[hookSymbol.S]?.push(fn);
     }
-    // biome-ignore lint/suspicious/noExplicitAny: args can be anything
     async runHook(hook, ...args) {
         const hookSymbol = this.hookSymbols[hook];
+        // biome-ignore lint/suspicious/noExplicitAny: internal cast for generic dispatch
+        const hookArgs = args;
         try {
             if (!hookSymbol)
                 throw new Error(`Invalid hook ${hook}`);
             switch (hookSymbol.type) {
                 case "boolean-return":
-                    return await this.runHookWithBooleanReturn(hookSymbol, ...args);
+                    return (await this.runHookWithBooleanReturn(hookSymbol, ...hookArgs));
                 case "message-return": {
-                    const [message, ...someArgs] = args;
-                    return await this.runHookWithMessageReturn(hookSymbol, message, ...someArgs);
+                    const [message, ...someArgs] = hookArgs;
+                    return (await this.runHookWithMessageReturn(hookSymbol, message, ...someArgs));
                 }
                 case "void":
-                    return await this.runHookWithVoidReturn(hookSymbol, ...args);
+                    return (await this.runHookWithVoidReturn(hookSymbol, ...hookArgs));
             }
-            /* c8 ignore next 1 */
             // biome-ignore lint/suspicious/noExplicitAny: error type is not important
         }
-        catch (error) {
-            error.message = `Error running hook ${hook}: ${error.message}`;
+        catch (originalError) {
+            const newError = new Error(
+            /* c8 ignore next */
+            `Error running hook ${hook}: ${originalError?.message ?? originalError}`);
+            newError.cause = originalError;
             if (hookSymbol.throwable !== false)
-                throw error;
-            this.logger.error(error);
+                throw newError;
+            this.logger.error(newError);
         }
+        // biome-ignore lint/suspicious/noExplicitAny: fallthrough for non-throwable error paths
+        return undefined;
     }
     async runHookWithVoidReturn(hookSymbol, 
     // biome-ignore lint/suspicious/noExplicitAny: args can be anything

package/dist/cjs/index.d.ts

@@ -1,8 +1,9 @@
 import type { Signer, SignerOptions } from "@fgiova/aws-signature";
 import { type Message, MiniSQSClient } from "@fgiova/mini-sqs-client";
 import type { Pool } from "undici";
-import { type HookName } from "./hooks";
+import { type HookCallback, type HookName } from "./hooks";
 import type { Logger } from "./logger";
+export { getAbortSignal } from "./context";
 type HandlerOptions = {
     deleteMessage?: boolean;
     extendVisibilityTimeout?: boolean;
@@ -23,18 +24,9 @@ type ConsumerOptions = {
     messageAttributeNames?: string[];
     attributeNames?: string[];
 };
-type hookReturnMessages = Promise<Message[]> | Message[] | Promise<void> | void | undefined;
-type hookReturnMessage = Promise<Message> | Message | Promise<void> | void | undefined;
-type hookReturnBoolean = Promise<boolean> | boolean | Promise<void> | void | undefined;
+type ConsumerHookName = Exclude<HookName, "onStart" | "onStop">;
 export type HooksOptions = {
-    onPoll?: (messages: Message[]) => hookReturnMessages;
-    onMessage?: (message: Message) => hookReturnMessage;
-    onHandlerSuccess?: (message: Message) => hookReturnMessage;
-    onHandlerTimeout?: (message: Message) => hookReturnBoolean;
-    onHandlerError?: (message: Message, error: Error) => hookReturnBoolean;
-    onSuccess?: (message: Message) => hookReturnBoolean;
-    onError?: (hook: HookName, message: Message, error: Error) => hookReturnBoolean;
-    onSQSError?: (error: Error, message?: Message) => Promise<void>;
+    [H in ConsumerHookName]?: HookCallback<H>;
 };
 export type SQSConsumerOptions = {
     queueARN: string;
@@ -68,16 +60,5 @@ export declare class SQSConsumer {
     start(): Promise<void>;
     stop(destroy?: boolean): Promise<void>;
     get isRunning(): boolean;
-    addHook(hookName: "onStart", value: (sqsConsumer: SQSConsumerOptions) => void): this;
-    addHook(hookName: "onStop", value: (sqsConsumer: SQSConsumerOptions) => void): this;
-    addHook(hookName: "onPoll", value: (messages: Message[]) => Promise<Message[]>): this;
-    addHook(hookName: "onMessage", value: (message: Message) => Promise<Message>): this;
-    addHook(hookName: "onHandlerSuccess", value: (message: Message) => Promise<Message>): this;
-    addHook(hookName: "onHandlerTimeout", value: (message: Message) => Promise<boolean>): this;
-    addHook(hookName: "onHandlerError", value: (message: Message, error: Error) => Promise<boolean>): this;
-    addHook(hookName: "onSuccess", value: (message: Message) => Promise<boolean>): this;
-    addHook(hookName: "onError", value: (hook: HookName, message: Message, error: Error) => Promise<boolean>): this;
-    addHook(hookName: "onSQSError", value: (error: Error, message?: Message) => Promise<void>): this;
-    addHook(hookName: HookName, value: Function): this;
+    addHook<H extends HookName>(hookName: H, value: HookCallback<H>): this;
 }
-export {};

package/dist/cjs/index.js

@@ -3,16 +3,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SQSConsumer = void 0;
-/** biome-ignore-all lint/complexity/noBannedTypes: Function required as generic */
+exports.SQSConsumer = exports.getAbortSignal = void 0;
 const promises_1 = require("node:timers/promises");
 const mini_sqs_client_1 = require("@fgiova/mini-sqs-client");
 // @ts-expect-error
 const unpromise_1 = require("@watchable/unpromise");
 // @ts-expect-error
 const p_map_1 = __importDefault(require("p-map"));
+const context_1 = require("./context");
 const errors_1 = require("./errors");
 const hooks_1 = require("./hooks");
+var context_2 = require("./context");
+Object.defineProperty(exports, "getAbortSignal", { enumerable: true, get: function () { return context_2.getAbortSignal; } });
 class SQSConsumer {
     constructor(options) {
         this.messagesOnFly = 0;
@@ -50,6 +52,7 @@ class SQSConsumer {
             for (const [key, value] of Object.entries(options.hooks)) {
                 if (typeof value !== "function")
                     throw new Error(`${key} must be a function`);
+                // biome-ignore lint/suspicious/noExplicitAny: dynamic registration loses type correlation
                 this.addHook(key, value);
             }
         }
@@ -77,20 +80,28 @@ class SQSConsumer {
         }
     }
     async runHandler(handler, message) {
+        let timeoutId = null;
+        const abortController = new AbortController();
         try {
             let handlerResult;
             if (this.handlerOptions.executionTimeout) {
+                const handlerPromise = context_1.handlerContext.run({ signal: abortController.signal }, () => handler(message));
+                // Swallow late rejection of the loser when timeout wins the race,
+                // otherwise it surfaces as an unhandledRejection.
+                handlerPromise.catch(() => { });
                 handlerResult = await unpromise_1.Unpromise.race([
-                    handler(message),
+                    handlerPromise,
                     new Promise((_resolve, reject) => {
-                        setTimeout(() => {
-                            reject(new errors_1.TimeoutError("Handler execution timed out"));
+                        timeoutId = setTimeout(() => {
+                            const err = new errors_1.TimeoutError("Handler execution timed out");
+                            abortController.abort(err);
+                            reject(err);
                         }, this.handlerOptions.executionTimeout);
                     }),
                 ]);
             }
             else {
-                handlerResult = await handler(message);
+                handlerResult = await context_1.handlerContext.run({ signal: abortController.signal }, () => handler(message));
             }
             await this.hooks.runHook("onHandlerSuccess", message);
             return handlerResult;
@@ -103,6 +114,10 @@ class SQSConsumer {
                 await this.hooks.runHook("onHandlerError", message, error);
             }
             throw error;
+        } /* c8 ignore next 2 */
+        finally {
+            if (timeoutId)
+                clearTimeout(timeoutId);
         }
     }
     haExtendVisibilityTimeout(messages, visibilityTimeout) {
@@ -133,65 +148,75 @@ class SQSConsumer {
                 // biome-ignore lint/style/noNonNullAssertion: ReceiptHandle must be present here
                 candidatesToDelete.push(result.message.ReceiptHandle);
             }
-            if (candidatesToDelete.length)
-                await this.sqsClient.deleteMessageBatch(this.queueARN, candidatesToDelete);
-            if (candidateToRelease.length)
-                await this.sqsClient.changeMessageVisibilityBatch(this.queueARN, candidateToRelease, 0);
+        }
+        if (candidatesToDelete.length) {
+            await this.sqsClient.deleteMessageBatch(this.queueARN, candidatesToDelete);
+        }
+        if (candidateToRelease.length) {
+            await this.sqsClient.changeMessageVisibilityBatch(this.queueARN, candidateToRelease, 0);
         }
     }
     async pollMessages() {
-        if (!this.running)
-            return;
-        try {
-            this.polling = true;
-            /* c8 ignore next 1 */
-            const visibilityTimeout = this.consumerOptions.visibilityTimeout ?? 30;
-            const messagesResult = await this.sqsClient.receiveMessage(this.queueARN, {
-                WaitTimeSeconds: this.consumerOptions.waitTimeSeconds,
-                MaxNumberOfMessages: this.consumerOptions.itemsPerRequest,
-                VisibilityTimeout: visibilityTimeout,
-                MessageAttributeNames: this.consumerOptions.messageAttributeNames,
-                AttributeNames: this.consumerOptions.attributeNames,
-            });
-            /* c8 ignore next 1 */
-            const messages = messagesResult.Messages ?? [];
-            const totalMessages = messages.length;
-            this.messagesOnFly += totalMessages;
-            await this.hooks.runHook("onPoll", messages);
-            if (messages.length) {
-                const haTimeout = this.haExtendVisibilityTimeout(messages, visibilityTimeout);
-                this.messagesOnFly += messages.length - totalMessages;
-                if (this.handlerOptions.parallelExecution !== false) {
-                    const results = await (0, p_map_1.default)(messages, async (message) => {
-                        return await this.runOnMessageHook(message);
-                    }, {
-                        concurrency: 10,
-                        stopOnError: false,
-                    });
-                    await this.deleteMessages(results);
-                    this.messagesOnFly -= messages.length;
-                }
-                else {
-                    const handlingMessages = [...messages];
-                    for (let i = 0; i < handlingMessages.length; i++) {
-                        const result = await this.runOnMessageHook(handlingMessages[i]);
-                        await this.deleteMessages([result]);
-                        messages.splice(i, 1);
-                        this.messagesOnFly -= 1;
+        let consecutiveErrors = 0;
+        while (this.running) {
+            try {
+                this.polling = true;
+                /* c8 ignore next 1 */
+                const visibilityTimeout = this.consumerOptions.visibilityTimeout ?? 30;
+                const messagesResult = await this.sqsClient.receiveMessage(this.queueARN, {
+                    WaitTimeSeconds: this.consumerOptions.waitTimeSeconds,
+                    MaxNumberOfMessages: this.consumerOptions.itemsPerRequest,
+                    VisibilityTimeout: visibilityTimeout,
+                    MessageAttributeNames: this.consumerOptions.messageAttributeNames,
+                    AttributeNames: this.consumerOptions.attributeNames,
+                });
+                const messages = await this.hooks.runHook("onPoll", 
+                /* c8 ignore next 1 */
+                messagesResult.Messages ?? []);
+                this.messagesOnFly += messages.length;
+                if (messages.length) {
+                    const haTimeout = this.haExtendVisibilityTimeout(messages, visibilityTimeout);
+                    try {
+                        if (this.handlerOptions.parallelExecution !== false) {
+                            try {
+                                const results = await (0, p_map_1.default)(messages, async (message) => {
+                                    return await this.runOnMessageHook(message);
+                                }, {
+                                    concurrency: 10,
+                                    stopOnError: false,
+                                });
+                                await this.deleteMessages(results);
+                            }
+                            finally {
+                                this.messagesOnFly -= messages.length;
+                            }
+                        }
+                        else {
+                            const handlingMessages = [...messages];
+                            for (let i = 0; i < handlingMessages.length; i++) {
+                                try {
+                                    const result = await this.runOnMessageHook(handlingMessages[i]);
+                                    await this.deleteMessages([result]);
+                                }
+                                finally {
+                                    this.messagesOnFly -= 1;
+                                }
+                            }
+                        }
+                    }
+                    finally {
+                        if (haTimeout)
+                            clearInterval(haTimeout);
                     }
                 }
-                if (haTimeout)
-                    clearInterval(haTimeout);
+                consecutiveErrors = 0;
             }
-            else {
-                this.messagesOnFly -= totalMessages;
+            catch (e) {
+                await this.hooks.runHook("onSQSError", e);
+                await (0, promises_1.setTimeout)(Math.min(1000 * 2 ** consecutiveErrors++, 30000));
             }
+            this.polling = false;
         }
-        catch (e) {
-            await this.hooks.runHook("onSQSError", e);
-        }
-        this.polling = false;
-        await this.pollMessages();
     }
     async start() {
         try {
@@ -223,7 +248,6 @@ class SQSConsumer {
             await this.hooks.runHook("onStop", this);
         }
     }
-    /* c8 ignore next 3 */
     get isRunning() {
         return this.running;
     }

package/dist/esm/context.d.mts

@@ -0,0 +1,7 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+type HandlerContext = {
+    signal: AbortSignal;
+};
+export declare const handlerContext: AsyncLocalStorage<HandlerContext>;
+export declare function getAbortSignal(): AbortSignal | undefined;
+export {};

package/dist/esm/context.mjs

@@ -0,0 +1,5 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export const handlerContext = new AsyncLocalStorage();
+export function getAbortSignal() {
+    return handlerContext.getStore()?.signal;
+}

package/dist/esm/errors.mjs

@@ -1,6 +1,5 @@
 export class TimeoutError extends Error {
     constructor(message) {
-        /* c8 ignore next 1 */
         super(message || "Timeout Error");
         this.name = "TimeoutError";
     }

package/dist/esm/hooks.d.mts

@@ -2,13 +2,56 @@
 import type { Message } from "@fgiova/mini-sqs-client";
 import type { Logger } from "./logger.mjs";
 export type HookName = "onStart" | "onStop" | "onPoll" | "onMessage" | "onHandlerSuccess" | "onHandlerTimeout" | "onHandlerError" | "onSuccess" | "onError" | "onSQSError";
+export type HookSignatureMap = {
+    onStart: {
+        args: [sqsConsumer: unknown];
+        return: undefined;
+    };
+    onStop: {
+        args: [sqsConsumer: unknown];
+        return: undefined;
+    };
+    onPoll: {
+        args: [messages: Message[]];
+        return: Message[];
+    };
+    onMessage: {
+        args: [message: Message];
+        return: Message;
+    };
+    onHandlerSuccess: {
+        args: [message: Message];
+        return: Message;
+    };
+    onHandlerTimeout: {
+        args: [message: Message];
+        return: boolean;
+    };
+    onHandlerError: {
+        args: [message: Message, error: Error];
+        return: boolean;
+    };
+    onSuccess: {
+        args: [message: Message];
+        return: boolean;
+    };
+    onError: {
+        args: [hook: HookName, message: Message, error: Error];
+        return: boolean;
+    };
+    onSQSError: {
+        args: [error: Error, message?: Message];
+        return: undefined;
+    };
+};
+export type HookCallback<H extends HookName> = (...args: HookSignatureMap[H]["args"]) => HookSignatureMap[H]["return"] | Promise<HookSignatureMap[H]["return"]> | void | Promise<void> | undefined;
 export declare class Hooks {
     private readonly hookSymbols;
     private readonly hooks;
     private readonly logger;
     constructor(logger?: Logger);
-    addHook(hook: HookName, fn: Function): void;
-    runHook(hook: HookName, ...args: any[]): Promise<boolean | void | Message | Message[]>;
+    addHook<H extends HookName>(hook: H, fn: HookCallback<H>): void;
+    runHook<H extends HookName>(hook: H, ...args: HookSignatureMap[H]["args"]): Promise<HookSignatureMap[H]["return"]>;
     private runHookWithVoidReturn;
     private runHookWithMessageReturn;
     private runHookWithBooleanReturn;

package/dist/esm/hooks.mjs

@@ -72,31 +72,36 @@ export class Hooks {
             throw new Error(`Invalid hook ${hook}`);
         this.hooks[hookSymbol.S]?.push(fn);
     }
-    // biome-ignore lint/suspicious/noExplicitAny: args can be anything
     async runHook(hook, ...args) {
         const hookSymbol = this.hookSymbols[hook];
+        // biome-ignore lint/suspicious/noExplicitAny: internal cast for generic dispatch
+        const hookArgs = args;
         try {
             if (!hookSymbol)
                 throw new Error(`Invalid hook ${hook}`);
             switch (hookSymbol.type) {
                 case "boolean-return":
-                    return await this.runHookWithBooleanReturn(hookSymbol, ...args);
+                    return (await this.runHookWithBooleanReturn(hookSymbol, ...hookArgs));
                 case "message-return": {
-                    const [message, ...someArgs] = args;
-                    return await this.runHookWithMessageReturn(hookSymbol, message, ...someArgs);
+                    const [message, ...someArgs] = hookArgs;
+                    return (await this.runHookWithMessageReturn(hookSymbol, message, ...someArgs));
                 }
                 case "void":
-                    return await this.runHookWithVoidReturn(hookSymbol, ...args);
+                    return (await this.runHookWithVoidReturn(hookSymbol, ...hookArgs));
             }
-            /* c8 ignore next 1 */
             // biome-ignore lint/suspicious/noExplicitAny: error type is not important
         }
-        catch (error) {
-            error.message = `Error running hook ${hook}: ${error.message}`;
+        catch (originalError) {
+            const newError = new Error(
+            /* c8 ignore next */
+            `Error running hook ${hook}: ${originalError?.message ?? originalError}`);
+            newError.cause = originalError;
             if (hookSymbol.throwable !== false)
-                throw error;
-            this.logger.error(error);
+                throw newError;
+            this.logger.error(newError);
         }
+        // biome-ignore lint/suspicious/noExplicitAny: fallthrough for non-throwable error paths
+        return undefined;
     }
     async runHookWithVoidReturn(hookSymbol, 
     // biome-ignore lint/suspicious/noExplicitAny: args can be anything

package/dist/esm/index.d.mts

@@ -1,8 +1,9 @@
 import type { Signer, SignerOptions } from "@fgiova/aws-signature";
 import { type Message, MiniSQSClient } from "@fgiova/mini-sqs-client";
 import type { Pool } from "undici";
-import { type HookName } from "./hooks.mjs";
+import { type HookCallback, type HookName } from "./hooks.mjs";
 import type { Logger } from "./logger.mjs";
+export { getAbortSignal } from "./context.mjs";
 type HandlerOptions = {
     deleteMessage?: boolean;
     extendVisibilityTimeout?: boolean;
@@ -23,18 +24,9 @@ type ConsumerOptions = {
     messageAttributeNames?: string[];
     attributeNames?: string[];
 };
-type hookReturnMessages = Promise<Message[]> | Message[] | Promise<void> | void | undefined;
-type hookReturnMessage = Promise<Message> | Message | Promise<void> | void | undefined;
-type hookReturnBoolean = Promise<boolean> | boolean | Promise<void> | void | undefined;
+type ConsumerHookName = Exclude<HookName, "onStart" | "onStop">;
 export type HooksOptions = {
-    onPoll?: (messages: Message[]) => hookReturnMessages;
-    onMessage?: (message: Message) => hookReturnMessage;
-    onHandlerSuccess?: (message: Message) => hookReturnMessage;
-    onHandlerTimeout?: (message: Message) => hookReturnBoolean;
-    onHandlerError?: (message: Message, error: Error) => hookReturnBoolean;
-    onSuccess?: (message: Message) => hookReturnBoolean;
-    onError?: (hook: HookName, message: Message, error: Error) => hookReturnBoolean;
-    onSQSError?: (error: Error, message?: Message) => Promise<void>;
+    [H in ConsumerHookName]?: HookCallback<H>;
 };
 export type SQSConsumerOptions = {
     queueARN: string;
@@ -68,16 +60,5 @@ export declare class SQSConsumer {
     start(): Promise<void>;
     stop(destroy?: boolean): Promise<void>;
     get isRunning(): boolean;
-    addHook(hookName: "onStart", value: (sqsConsumer: SQSConsumerOptions) => void): this;
-    addHook(hookName: "onStop", value: (sqsConsumer: SQSConsumerOptions) => void): this;
-    addHook(hookName: "onPoll", value: (messages: Message[]) => Promise<Message[]>): this;
-    addHook(hookName: "onMessage", value: (message: Message) => Promise<Message>): this;
-    addHook(hookName: "onHandlerSuccess", value: (message: Message) => Promise<Message>): this;
-    addHook(hookName: "onHandlerTimeout", value: (message: Message) => Promise<boolean>): this;
-    addHook(hookName: "onHandlerError", value: (message: Message, error: Error) => Promise<boolean>): this;
-    addHook(hookName: "onSuccess", value: (message: Message) => Promise<boolean>): this;
-    addHook(hookName: "onError", value: (hook: HookName, message: Message, error: Error) => Promise<boolean>): this;
-    addHook(hookName: "onSQSError", value: (error: Error, message?: Message) => Promise<void>): this;
-    addHook(hookName: HookName, value: Function): this;
+    addHook<H extends HookName>(hookName: H, value: HookCallback<H>): this;
 }
-export {};

package/dist/esm/index.mjs

@@ -1,12 +1,13 @@
-/** biome-ignore-all lint/complexity/noBannedTypes: Function required as generic */
 import { setTimeout as setTimeoutAsync } from "node:timers/promises";
 import { MiniSQSClient } from "@fgiova/mini-sqs-client";
 // @ts-expect-error
 import { Unpromise } from "@watchable/unpromise";
 // @ts-expect-error
 import pMap from "p-map";
+import { handlerContext } from "./context.mjs";
 import { TimeoutError } from "./errors.mjs";
 import { Hooks } from "./hooks.mjs";
+export { getAbortSignal } from "./context.mjs";
 export class SQSConsumer {
     constructor(options) {
         this.messagesOnFly = 0;
@@ -44,6 +45,7 @@ export class SQSConsumer {
             for (const [key, value] of Object.entries(options.hooks)) {
                 if (typeof value !== "function")
                     throw new Error(`${key} must be a function`);
+                // biome-ignore lint/suspicious/noExplicitAny: dynamic registration loses type correlation
                 this.addHook(key, value);
             }
         }
@@ -71,20 +73,28 @@ export class SQSConsumer {
         }
     }
     async runHandler(handler, message) {
+        let timeoutId = null;
+        const abortController = new AbortController();
         try {
             let handlerResult;
             if (this.handlerOptions.executionTimeout) {
+                const handlerPromise = handlerContext.run({ signal: abortController.signal }, () => handler(message));
+                // Swallow late rejection of the loser when timeout wins the race,
+                // otherwise it surfaces as an unhandledRejection.
+                handlerPromise.catch(() => { });
                 handlerResult = await Unpromise.race([
-                    handler(message),
+                    handlerPromise,
                     new Promise((_resolve, reject) => {
-                        setTimeout(() => {
-                            reject(new TimeoutError("Handler execution timed out"));
+                        timeoutId = setTimeout(() => {
+                            const err = new TimeoutError("Handler execution timed out");
+                            abortController.abort(err);
+                            reject(err);
                         }, this.handlerOptions.executionTimeout);
                     }),
                 ]);
             }
             else {
-                handlerResult = await handler(message);
+                handlerResult = await handlerContext.run({ signal: abortController.signal }, () => handler(message));
             }
             await this.hooks.runHook("onHandlerSuccess", message);
             return handlerResult;
@@ -97,6 +107,10 @@ export class SQSConsumer {
                 await this.hooks.runHook("onHandlerError", message, error);
             }
             throw error;
+        } /* c8 ignore next 2 */
+        finally {
+            if (timeoutId)
+                clearTimeout(timeoutId);
         }
     }
     haExtendVisibilityTimeout(messages, visibilityTimeout) {
@@ -127,65 +141,75 @@ export class SQSConsumer {
                 // biome-ignore lint/style/noNonNullAssertion: ReceiptHandle must be present here
                 candidatesToDelete.push(result.message.ReceiptHandle);
             }
-            if (candidatesToDelete.length)
-                await this.sqsClient.deleteMessageBatch(this.queueARN, candidatesToDelete);
-            if (candidateToRelease.length)
-                await this.sqsClient.changeMessageVisibilityBatch(this.queueARN, candidateToRelease, 0);
+        }
+        if (candidatesToDelete.length) {
+            await this.sqsClient.deleteMessageBatch(this.queueARN, candidatesToDelete);
+        }
+        if (candidateToRelease.length) {
+            await this.sqsClient.changeMessageVisibilityBatch(this.queueARN, candidateToRelease, 0);
         }
     }
     async pollMessages() {
-        if (!this.running)
-            return;
-        try {
-            this.polling = true;
-            /* c8 ignore next 1 */
-            const visibilityTimeout = this.consumerOptions.visibilityTimeout ?? 30;
-            const messagesResult = await this.sqsClient.receiveMessage(this.queueARN, {
-                WaitTimeSeconds: this.consumerOptions.waitTimeSeconds,
-                MaxNumberOfMessages: this.consumerOptions.itemsPerRequest,
-                VisibilityTimeout: visibilityTimeout,
-                MessageAttributeNames: this.consumerOptions.messageAttributeNames,
-                AttributeNames: this.consumerOptions.attributeNames,
-            });
-            /* c8 ignore next 1 */
-            const messages = messagesResult.Messages ?? [];
-            const totalMessages = messages.length;
-            this.messagesOnFly += totalMessages;
-            await this.hooks.runHook("onPoll", messages);
-            if (messages.length) {
-                const haTimeout = this.haExtendVisibilityTimeout(messages, visibilityTimeout);
-                this.messagesOnFly += messages.length - totalMessages;
-                if (this.handlerOptions.parallelExecution !== false) {
-                    const results = await pMap(messages, async (message) => {
-                        return await this.runOnMessageHook(message);
-                    }, {
-                        concurrency: 10,
-                        stopOnError: false,
-                    });
-                    await this.deleteMessages(results);
-                    this.messagesOnFly -= messages.length;
-                }
-                else {
-                    const handlingMessages = [...messages];
-                    for (let i = 0; i < handlingMessages.length; i++) {
-                        const result = await this.runOnMessageHook(handlingMessages[i]);
-                        await this.deleteMessages([result]);
-                        messages.splice(i, 1);
-                        this.messagesOnFly -= 1;
+        let consecutiveErrors = 0;
+        while (this.running) {
+            try {
+                this.polling = true;
+                /* c8 ignore next 1 */
+                const visibilityTimeout = this.consumerOptions.visibilityTimeout ?? 30;
+                const messagesResult = await this.sqsClient.receiveMessage(this.queueARN, {
+                    WaitTimeSeconds: this.consumerOptions.waitTimeSeconds,
+                    MaxNumberOfMessages: this.consumerOptions.itemsPerRequest,
+                    VisibilityTimeout: visibilityTimeout,
+                    MessageAttributeNames: this.consumerOptions.messageAttributeNames,
+                    AttributeNames: this.consumerOptions.attributeNames,
+                });
+                const messages = await this.hooks.runHook("onPoll", 
+                /* c8 ignore next 1 */
+                messagesResult.Messages ?? []);
+                this.messagesOnFly += messages.length;
+                if (messages.length) {
+                    const haTimeout = this.haExtendVisibilityTimeout(messages, visibilityTimeout);
+                    try {
+                        if (this.handlerOptions.parallelExecution !== false) {
+                            try {
+                                const results = await pMap(messages, async (message) => {
+                                    return await this.runOnMessageHook(message);
+                                }, {
+                                    concurrency: 10,
+                                    stopOnError: false,
+                                });
+                                await this.deleteMessages(results);
+                            }
+                            finally {
+                                this.messagesOnFly -= messages.length;
+                            }
+                        }
+                        else {
+                            const handlingMessages = [...messages];
+                            for (let i = 0; i < handlingMessages.length; i++) {
+                                try {
+                                    const result = await this.runOnMessageHook(handlingMessages[i]);
+                                    await this.deleteMessages([result]);
+                                }
+                                finally {
+                                    this.messagesOnFly -= 1;
+                                }
+                            }
+                        }
+                    }
+                    finally {
+                        if (haTimeout)
+                            clearInterval(haTimeout);
                     }
                 }
-                if (haTimeout)
-                    clearInterval(haTimeout);
+                consecutiveErrors = 0;
             }
-            else {
-                this.messagesOnFly -= totalMessages;
+            catch (e) {
+                await this.hooks.runHook("onSQSError", e);
+                await setTimeoutAsync(Math.min(1000 * 2 ** consecutiveErrors++, 30000));
             }
+            this.polling = false;
         }
-        catch (e) {
-            await this.hooks.runHook("onSQSError", e);
-        }
-        this.polling = false;
-        await this.pollMessages();
     }
     async start() {
         try {
@@ -217,7 +241,6 @@ export class SQSConsumer {
             await this.hooks.runHook("onStop", this);
         }
     }
-    /* c8 ignore next 3 */
     get isRunning() {
         return this.running;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fgiova/sqs-consumer",
-	"version": "2.2.1",
+	"version": "3.1.0",
 	"main": "./dist/cjs/index.js",
 	"types": "./dist/cjs/index.d.ts",
 	"exports": {
@@ -44,7 +44,7 @@
 		"access": "public"
 	},
 	"engines": {
-		"node": ">=20.14.1"
+		"node": "^22.14.0 || >= 24.10.0"
 	},
 	"tap": {
 		"show-full-coverage": true,
@@ -56,25 +56,27 @@
 		]
 	},
 	"dependencies": {
-		"@fgiova/mini-sqs-client": "^3.4.0",
+		"@fgiova/mini-sqs-client": "^5.0.0",
 		"@watchable/unpromise": "^1.0.2",
 		"p-map": "^7.0.3"
 	},
 	"peerDependencies": {
-		"@fgiova/aws-signature": "^3.2.0"
+		"@fgiova/aws-signature": "^4.0.0"
 	},
 	"devDependencies": {
 		"@aws-sdk/client-sqs": "^3.758.0",
-		"@biomejs/biome": "2.2.2",
+		"@biomejs/biome": "2.3.15",
 		"@fgiova/cjs-esm-ts-builder": "^1.2.0",
 		"@semantic-release/changelog": "^6.0.3",
 		"@semantic-release/git": "^10.0.1",
-		"@tsconfig/node20": "^20.1.4",
-		"@types/node": "^20.17.23",
-		"conventional-changelog-conventionalcommits": "^8.0.0",
-		"semantic-release": "^24.2.3",
+		"@semantic-release/npm": "^13.1.4",
+		"@tsconfig/node22": "^22.0.5",
+		"@types/node": "^22.19.11",
+		"conventional-changelog-conventionalcommits": "^9.1.0",
+		"dotenv": "^17.2.4",
+		"semantic-release": "^25.0.3",
 		"tap": "^21.1.0",
-		"testcontainers": "^11.5.1",
+		"testcontainers": "^11.11.0",
 		"ts-node": "^10.9.2",
 		"typescript": "^5.8.2"
 	}