@fgiova/sqs-consumer 3.0.0 → 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                                        |
 |-----------------|-------------------------------------|---------|----------------------------------------------------|
@@ -86,6 +105,7 @@ SQSConsumer(options: SQSConsumerOptions)
 SQSConsumer.start(): Promise<void>
 SQSConsumer.stop(destroyConsumer = false): Promise<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/index.d.ts

@@ -3,6 +3,7 @@ import { type Message, MiniSQSClient } from "@fgiova/mini-sqs-client";
 import type { Pool } from "undici";
 import { type HookCallback, type HookName } from "./hooks";
 import type { Logger } from "./logger";
+export { getAbortSignal } from "./context";
 type HandlerOptions = {
     deleteMessage?: boolean;
     extendVisibilityTimeout?: boolean;
@@ -61,4 +62,3 @@ export declare class SQSConsumer {
     get isRunning(): boolean;
     addHook<H extends HookName>(hookName: H, value: HookCallback<H>): this;
 }
-export {};

package/dist/cjs/index.js

@@ -3,15 +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;
+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;
@@ -78,20 +81,27 @@ 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) => {
                         timeoutId = setTimeout(() => {
-                            reject(new errors_1.TimeoutError("Handler execution timed out"));
+                            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;

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/index.d.mts

@@ -3,6 +3,7 @@ import { type Message, MiniSQSClient } from "@fgiova/mini-sqs-client";
 import type { Pool } from "undici";
 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;
@@ -61,4 +62,3 @@ export declare class SQSConsumer {
     get isRunning(): boolean;
     addHook<H extends HookName>(hookName: H, value: HookCallback<H>): this;
 }
-export {};

package/dist/esm/index.mjs

@@ -4,8 +4,10 @@ import { MiniSQSClient } from "@fgiova/mini-sqs-client";
 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;
@@ -72,20 +74,27 @@ 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) => {
                         timeoutId = setTimeout(() => {
-                            reject(new TimeoutError("Handler execution timed out"));
+                            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;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fgiova/sqs-consumer",
-	"version": "3.0.0",
+	"version": "3.1.0",
 	"main": "./dist/cjs/index.js",
 	"types": "./dist/cjs/index.d.ts",
 	"exports": {
@@ -56,7 +56,7 @@
 		]
 	},
 	"dependencies": {
-		"@fgiova/mini-sqs-client": "^4.0.0",
+		"@fgiova/mini-sqs-client": "^5.0.0",
 		"@watchable/unpromise": "^1.0.2",
 		"p-map": "^7.0.3"
 	},