@fgiova/sqs-consumer 3.3.0 → 3.5.0

package/README.md

@@ -86,9 +86,10 @@ const consumer = new SQSConsumer({
 | messageAttributeNames | string[]                    | []      | The message attribute names to be included in the response                                                                                   |
 | attributeNames        | string[]                    | []      | The attribute names to be included in the response                                                                                           |
 | errorDelaySeconds     | number                      | 0       | Seconds a failed message stays invisible before it can be received again                                                                     |
-| errorDelayBackoff     | (attempt: number) => number |         | Returns the delay in seconds for a failed message, given its `ApproximateReceiveCount`. Takes precedence over `errorDelaySeconds` |
+| errorDelayBackoff     | (attempt: number, message: Message) => number |  | Returns the delay in seconds for a failed message, given its `ApproximateReceiveCount` and the message itself. Takes precedence over `errorDelaySeconds` |
+| maxReceiveCount       | number / (attempt: number, message: Message) => number |  | Receive count after which a failed message triggers `onMaxReceiveCountExceeded`. A function receives the `ApproximateReceiveCount` and the message, and returns the threshold |
 
-Delays are truncated to an integer and clamped to the SQS range 0–43200 seconds. When `errorDelayBackoff` is set, `ApproximateReceiveCount` is added to `attributeNames` automatically. If `errorDelayBackoff` throws, the error is reported to `onSQSError` and `errorDelaySeconds` is used instead.
+Delays are truncated to an integer and clamped to the SQS range 0–43200 seconds. When `errorDelayBackoff` is set, `ApproximateReceiveCount` is added to `attributeNames` automatically. If `errorDelayBackoff` throws, the error is reported to `onSQSError` together with the message and `errorDelaySeconds` is used instead.
 
 > **Note:** SQS counts the 12-hour visibility limit from when the message was received, not from when the delay is set. A delay that exceeds the remaining time (roughly `43200 - executionTimeout - visibility extensions`) is silently rejected by SQS and the message is retried after its current visibility timeout. Keep delays well below 12 hours, and keep their sum below the queue's `MessageRetentionPeriod`, or the message expires without reaching the DLQ.
 >
@@ -105,6 +106,23 @@ const consumer = new SQSConsumer({
 });
 ```
 
+When a message fails and its `ApproximateReceiveCount` reaches `maxReceiveCount`, the `onMaxReceiveCountExceeded` hook is called with the message and its receive count. **The message is deleted unless a hook returns `false`**, including when no hook is registered: return `false` to release it with the usual error delay instead. When `maxReceiveCount` is set, `ApproximateReceiveCount` is added to `attributeNames` automatically. If the `maxReceiveCount` function throws, the error is reported to `onSQSError` together with the message and the message is released.
+
+> **Note:** if the queue has a redrive policy, set `maxReceiveCount` below the queue's own `maxReceiveCount`, or SQS moves the message to the DLQ before the hook is called.
+
+```typescript
+const consumer = new SQSConsumer({
+	queueARN: "arn:aws:sqs:eu-central-1:000000000000:test",
+	handler: async (message) => { /* ... */ },
+	consumerOptions: {
+		maxReceiveCount: 5,
+	},
+});
+consumer.addHook("onMaxReceiveCountExceeded", async (message, count) => {
+	await archive(message); // keep a copy, then let the consumer delete it
+});
+```
+
 ### Hooks
 | Option           | Type                                                                  | Description                                                         |
 |------------------|-----------------------------------------------------------------------|---------------------------------------------------------------------|
@@ -113,6 +131,7 @@ const consumer = new SQSConsumer({
 | 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          |
+| onMaxReceiveCountExceeded | (message: Message, count: number) => Promise<boolean> | Called when a failed message reaches `maxReceiveCount`. Return `false` to keep the message, otherwise it is deleted |
 | 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     |

package/dist/cjs/hooks.d.ts

@@ -1,7 +1,7 @@
 /** biome-ignore-all lint/complexity/noBannedTypes: Function required as generic */
 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 HookName = "onStart" | "onStop" | "onPoll" | "onMessage" | "onHandlerSuccess" | "onHandlerTimeout" | "onHandlerError" | "onMaxReceiveCountExceeded" | "onSuccess" | "onError" | "onSQSError";
 export type HookSignatureMap = {
     onStart: {
         args: [sqsConsumer: unknown];
@@ -31,6 +31,10 @@ export type HookSignatureMap = {
         args: [message: Message, error: Error];
         return: boolean;
     };
+    onMaxReceiveCountExceeded: {
+        args: [message: Message, count: number];
+        return: boolean;
+    };
     onSuccess: {
         args: [message: Message];
         return: boolean;

package/dist/cjs/hooks.js

@@ -39,6 +39,11 @@ class Hooks {
                 throwable: false,
                 type: "boolean-return",
             },
+            onMaxReceiveCountExceeded: {
+                S: Symbol("maxReceiveCountExceeded"),
+                throwable: false,
+                type: "boolean-return",
+            },
             onSuccess: {
                 S: Symbol("success"),
                 throwable: false,
@@ -64,6 +69,7 @@ class Hooks {
             [this.hookSymbols.onHandlerSuccess.S]: [],
             [this.hookSymbols.onHandlerTimeout.S]: [],
             [this.hookSymbols.onHandlerError.S]: [],
+            [this.hookSymbols.onMaxReceiveCountExceeded.S]: [],
             [this.hookSymbols.onSuccess.S]: [],
             [this.hookSymbols.onError.S]: [],
             [this.hookSymbols.onSQSError.S]: [],

package/dist/cjs/index.d.ts

@@ -24,7 +24,8 @@ type ConsumerOptions = {
     messageAttributeNames?: string[];
     attributeNames?: string[];
     errorDelaySeconds?: number;
-    errorDelayBackoff?: (attempt: number) => number;
+    errorDelayBackoff?: (attempt: number, message: Message) => number;
+    maxReceiveCount?: number | ((attempt: number, message: Message) => number);
 };
 type ConsumerHookName = Exclude<HookName, "onStart" | "onStop">;
 export type HooksOptions = {

package/dist/cjs/index.js

@@ -45,13 +45,15 @@ class SQSConsumer {
             attributeNames: [
                 ...new Set([
                     ...(options.consumerOptions?.attributeNames ?? []),
-                    ...(options.consumerOptions?.errorDelayBackoff
+                    ...(options.consumerOptions?.errorDelayBackoff ||
+                        options.consumerOptions?.maxReceiveCount !== undefined
                         ? ["ApproximateReceiveCount"]
                         : []),
                 ]),
             ],
             errorDelaySeconds: options.consumerOptions?.errorDelaySeconds ?? 0,
             errorDelayBackoff: options.consumerOptions?.errorDelayBackoff,
+            maxReceiveCount: options.consumerOptions?.maxReceiveCount,
         };
         this.sqsClient =
             options.clientOptions?.sqsClient ??
@@ -150,14 +152,36 @@ class SQSConsumer {
         for (const result of messagesResults) {
             if (result.error) {
                 let delaySeconds = this.consumerOptions.errorDelaySeconds;
+                const maxReceiveCount = this.consumerOptions.maxReceiveCount;
+                if (maxReceiveCount !== undefined) {
+                    try {
+                        const receiveCount = Number(
+                        /* c8 ignore next 1 */
+                        result.message.Attributes?.ApproximateReceiveCount ?? 0);
+                        if (receiveCount >=
+                            (typeof maxReceiveCount === "function"
+                                ? maxReceiveCount(receiveCount, result.message)
+                                : maxReceiveCount)) {
+                            const toDelete = await this.hooks.runHook("onMaxReceiveCountExceeded", result.message, receiveCount);
+                            if (toDelete) {
+                                // biome-ignore lint/style/noNonNullAssertion: ReceiptHandle must be present here
+                                candidatesToDelete.push(result.message.ReceiptHandle);
+                                continue;
+                            }
+                        }
+                    }
+                    catch (e) {
+                        await this.hooks.runHook("onSQSError", e, result.message);
+                    }
+                }
                 if (this.consumerOptions.errorDelayBackoff) {
                     try {
                         delaySeconds = this.consumerOptions.errorDelayBackoff(
                         /* c8 ignore next 1 */
-                        Number(result.message.Attributes?.ApproximateReceiveCount ?? 0));
+                        Number(result.message.Attributes?.ApproximateReceiveCount ?? 0), result.message);
                     }
                     catch (e) {
-                        await this.hooks.runHook("onSQSError", e);
+                        await this.hooks.runHook("onSQSError", e, result.message);
                     }
                 }
                 candidateToRelease.push({

package/dist/esm/hooks.d.mts

@@ -1,7 +1,7 @@
 /** biome-ignore-all lint/complexity/noBannedTypes: Function required as generic */
 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 HookName = "onStart" | "onStop" | "onPoll" | "onMessage" | "onHandlerSuccess" | "onHandlerTimeout" | "onHandlerError" | "onMaxReceiveCountExceeded" | "onSuccess" | "onError" | "onSQSError";
 export type HookSignatureMap = {
     onStart: {
         args: [sqsConsumer: unknown];
@@ -31,6 +31,10 @@ export type HookSignatureMap = {
         args: [message: Message, error: Error];
         return: boolean;
     };
+    onMaxReceiveCountExceeded: {
+        args: [message: Message, count: number];
+        return: boolean;
+    };
     onSuccess: {
         args: [message: Message];
         return: boolean;

package/dist/esm/hooks.mjs

@@ -36,6 +36,11 @@ export class Hooks {
                 throwable: false,
                 type: "boolean-return",
             },
+            onMaxReceiveCountExceeded: {
+                S: Symbol("maxReceiveCountExceeded"),
+                throwable: false,
+                type: "boolean-return",
+            },
             onSuccess: {
                 S: Symbol("success"),
                 throwable: false,
@@ -61,6 +66,7 @@ export class Hooks {
             [this.hookSymbols.onHandlerSuccess.S]: [],
             [this.hookSymbols.onHandlerTimeout.S]: [],
             [this.hookSymbols.onHandlerError.S]: [],
+            [this.hookSymbols.onMaxReceiveCountExceeded.S]: [],
             [this.hookSymbols.onSuccess.S]: [],
             [this.hookSymbols.onError.S]: [],
             [this.hookSymbols.onSQSError.S]: [],

package/dist/esm/index.d.mts

@@ -24,7 +24,8 @@ type ConsumerOptions = {
     messageAttributeNames?: string[];
     attributeNames?: string[];
     errorDelaySeconds?: number;
-    errorDelayBackoff?: (attempt: number) => number;
+    errorDelayBackoff?: (attempt: number, message: Message) => number;
+    maxReceiveCount?: number | ((attempt: number, message: Message) => number);
 };
 type ConsumerHookName = Exclude<HookName, "onStart" | "onStop">;
 export type HooksOptions = {

package/dist/esm/index.mjs

@@ -38,13 +38,15 @@ export class SQSConsumer {
             attributeNames: [
                 ...new Set([
                     ...(options.consumerOptions?.attributeNames ?? []),
-                    ...(options.consumerOptions?.errorDelayBackoff
+                    ...(options.consumerOptions?.errorDelayBackoff ||
+                        options.consumerOptions?.maxReceiveCount !== undefined
                         ? ["ApproximateReceiveCount"]
                         : []),
                 ]),
             ],
             errorDelaySeconds: options.consumerOptions?.errorDelaySeconds ?? 0,
             errorDelayBackoff: options.consumerOptions?.errorDelayBackoff,
+            maxReceiveCount: options.consumerOptions?.maxReceiveCount,
         };
         this.sqsClient =
             options.clientOptions?.sqsClient ??
@@ -143,14 +145,36 @@ export class SQSConsumer {
         for (const result of messagesResults) {
             if (result.error) {
                 let delaySeconds = this.consumerOptions.errorDelaySeconds;
+                const maxReceiveCount = this.consumerOptions.maxReceiveCount;
+                if (maxReceiveCount !== undefined) {
+                    try {
+                        const receiveCount = Number(
+                        /* c8 ignore next 1 */
+                        result.message.Attributes?.ApproximateReceiveCount ?? 0);
+                        if (receiveCount >=
+                            (typeof maxReceiveCount === "function"
+                                ? maxReceiveCount(receiveCount, result.message)
+                                : maxReceiveCount)) {
+                            const toDelete = await this.hooks.runHook("onMaxReceiveCountExceeded", result.message, receiveCount);
+                            if (toDelete) {
+                                // biome-ignore lint/style/noNonNullAssertion: ReceiptHandle must be present here
+                                candidatesToDelete.push(result.message.ReceiptHandle);
+                                continue;
+                            }
+                        }
+                    }
+                    catch (e) {
+                        await this.hooks.runHook("onSQSError", e, result.message);
+                    }
+                }
                 if (this.consumerOptions.errorDelayBackoff) {
                     try {
                         delaySeconds = this.consumerOptions.errorDelayBackoff(
                         /* c8 ignore next 1 */
-                        Number(result.message.Attributes?.ApproximateReceiveCount ?? 0));
+                        Number(result.message.Attributes?.ApproximateReceiveCount ?? 0), result.message);
                     }
                     catch (e) {
-                        await this.hooks.runHook("onSQSError", e);
+                        await this.hooks.runHook("onSQSError", e, result.message);
                     }
                 }
                 candidateToRelease.push({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fgiova/sqs-consumer",
-	"version": "3.3.0",
+	"version": "3.5.0",
 	"main": "./dist/cjs/index.js",
 	"types": "./dist/cjs/index.d.ts",
 	"exports": {