sqs-consumer 10.2.0 → 10.2.1

package/.github/DISCUSSION_TEMPLATE/help.yml

@@ -8,6 +8,6 @@ body:
   - type: input
     attributes:
       label: Example
-      description: A link to a minimal reproduction is helpful for debugging! You can fork [this stackblitz setup](https://stackblitz.com/edit/sqs-consumer-starter) to get a reproduction setup quickly.
+      description: A link to a minimal reproduction is helpful for debugging! You can use one of our [existing examples](https://github.com/bbc/sqs-consumer-starter/tree/main/examples) to get a reproduction setup quickly.
     validations:
       required: false

package/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -32,7 +32,7 @@ body:
         Please add a link to a minimal reproduction.
         Note:
         - Please keep your example as simple and reproduceable as possible, try leaving out dependencies that are not required for reproduction.
-        - To create a shareable code example for web, you can use Stackblitz (https://stackblitz.com/edit/sqs-consumer-starter).
+        - To create a shareable code example for web, you can use one of our existing examples: (https://github.com/bbc/sqs-consumer-starter/tree/main/examples).
         - Please make sure the example is complete and runnable - e.g. avoid localhost URLs.
       placeholder: |
         e.g. Code Sandbox, Stackblitz, Expo Snack or TypeScript playground

package/CHANGELOG.md

@@ -1,13 +1,13 @@
-## [10.2.0](https://github.com/bbc/sqs-consumer/compare/v10.1.0...v10.2.0) (2024-04-30)
+## [10.2.1](https://github.com/bbc/sqs-consumer/compare/v10.2.0...v10.2.1) (2024-04-30)
 
 
-### Features
+### Bug Fixes
 
-* bumping to minor ([42cfda5](https://github.com/bbc/sqs-consumer/commit/42cfda59fa7da0ef85c50a3d1f79b6fbe21abf94))
+* build exclusive type files ([65008eb](https://github.com/bbc/sqs-consumer/commit/65008ebaab8aecbe806b8e7ab9be809de58518a9))
+* default extension for cjs ([bd9855b](https://github.com/bbc/sqs-consumer/commit/bd9855babedee1ea6506d8fc2901228e1cd31468))
+* types extension for cjs ([8bc6239](https://github.com/bbc/sqs-consumer/commit/8bc62396badf30bcf508309110a782aa6f4b9d8c))
 
 
 ### Chores
 
-* adding main and types back ([#493](https://github.com/bbc/sqs-consumer/issues/493)) ([c2ac256](https://github.com/bbc/sqs-consumer/commit/c2ac2567fc2bde5fad3279b451b5d63a72efa104))
-* don't add package.json for types dir ([6084f28](https://github.com/bbc/sqs-consumer/commit/6084f28c1c3efeb87978e2c0de76427029b57af5))
-* **release:** v10.1.0 ([244d6b5](https://github.com/bbc/sqs-consumer/commit/244d6b5c3f606e730ecb1cd748d7c8d567c5f2dc))
+* updating repro links ([48f452e](https://github.com/bbc/sqs-consumer/commit/48f452ee935a563b3d0c1043b552947da84886ea))

package/dist/cjs/consumer.d.ts

@@ -0,0 +1,137 @@
+/// <reference types="node" />
+import { ConsumerOptions, StopOptions, UpdatableOptions } from "./types.js";
+import { TypedEventEmitter } from "./emitter.js";
+/**
+ * [Usage](https://bbc.github.io/sqs-consumer/index.html#usage)
+ */
+export declare class Consumer extends TypedEventEmitter {
+    private pollingTimeoutId;
+    private stopped;
+    private queueUrl;
+    private handleMessage;
+    private handleMessageBatch;
+    private preReceiveMessageCallback?;
+    private postReceiveMessageCallback?;
+    private sqs;
+    private handleMessageTimeout;
+    private attributeNames;
+    private messageAttributeNames;
+    private shouldDeleteMessages;
+    private alwaysAcknowledge;
+    private batchSize;
+    private visibilityTimeout;
+    private terminateVisibilityTimeout;
+    private waitTimeSeconds;
+    private authenticationErrorTimeout;
+    private pollingWaitTimeMs;
+    private pollingCompleteWaitTimeMs;
+    private heartbeatInterval;
+    private isPolling;
+    private stopRequestedAtTimestamp;
+    abortController: AbortController;
+    constructor(options: ConsumerOptions);
+    /**
+     * Creates a new SQS consumer.
+     */
+    static create(options: ConsumerOptions): Consumer;
+    /**
+     * Start polling the queue for messages.
+     */
+    start(): void;
+    /**
+     * A reusable options object for sqs.send that's used to avoid duplication.
+     */
+    private get sqsSendOptions();
+    /**
+     * Stop polling the queue for messages (pre existing requests will still be made until concluded).
+     */
+    stop(options?: StopOptions): void;
+    /**
+     * Wait for final poll and in flight messages to complete.
+     * @private
+     */
+    private waitForPollingToComplete;
+    /**
+     * Returns the current status of the consumer.
+     * This includes whether it is running or currently polling.
+     */
+    get status(): {
+        isRunning: boolean;
+        isPolling: boolean;
+    };
+    /**
+     * Validates and then updates the provided option to the provided value.
+     * @param option The option to validate and then update
+     * @param value The value to set the provided option to
+     */
+    updateOption(option: UpdatableOptions, value: ConsumerOptions[UpdatableOptions]): void;
+    /**
+     * Emit one of the consumer's error events depending on the error received.
+     * @param err The error object to forward on
+     * @param message The message that the error occurred on
+     */
+    private emitError;
+    /**
+     * Poll for new messages from SQS
+     */
+    private poll;
+    /**
+     * Send a request to SQS to retrieve messages
+     * @param params The required params to receive messages from SQS
+     */
+    private receiveMessage;
+    /**
+     * Handles the response from AWS SQS, determining if we should proceed to
+     * the message handler.
+     * @param response The output from AWS SQS
+     */
+    private handleSqsResponse;
+    /**
+     * Process a message that has been received from SQS. This will execute the message
+     * handler and delete the message once complete.
+     * @param message The message that was delivered from SQS
+     */
+    private processMessage;
+    /**
+     * Process a batch of messages from the SQS queue.
+     * @param messages The messages that were delivered from SQS
+     */
+    private processMessageBatch;
+    /**
+     * Trigger a function on a set interval
+     * @param heartbeatFn The function that should be triggered
+     */
+    private startHeartbeat;
+    /**
+     * Change the visibility timeout on a message
+     * @param message The message to change the value of
+     * @param timeout The new timeout that should be set
+     */
+    private changeVisibilityTimeout;
+    /**
+     * Change the visibility timeout on a batch of messages
+     * @param messages The messages to change the value of
+     * @param timeout The new timeout that should be set
+     */
+    private changeVisibilityTimeoutBatch;
+    /**
+     * Trigger the applications handleMessage function
+     * @param message The message that was received from SQS
+     */
+    private executeHandler;
+    /**
+     * Execute the application's message batch handler
+     * @param messages The messages that should be forwarded from the SQS queue
+     */
+    private executeBatchHandler;
+    /**
+     * Delete a single message from SQS
+     * @param message The message to delete from the SQS queue
+     */
+    private deleteMessage;
+    /**
+     * Delete a batch of messages from the SQS queue.
+     * @param messages The messages that should be deleted from SQS
+     */
+    private deleteMessageBatch;
+}

package/dist/cjs/emitter.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="node" />
+import { EventEmitter } from "node:events";
+import { Events } from "./types.js";
+export declare class TypedEventEmitter extends EventEmitter {
+    /**
+     * Trigger a listener on all emitted events
+     * @param event The name of the event to listen to
+     * @param listener A function to trigger when the event is emitted
+     */
+    on<E extends keyof Events>(event: E, listener: (...args: Events[E]) => void): this;
+    /**
+     * Trigger a listener only once for an emitted event
+     * @param event The name of the event to listen to
+     * @param listener A function to trigger when the event is emitted
+     */
+    once<E extends keyof Events>(event: E, listener: (...args: Events[E]) => void): this;
+    /**
+     * Emits an event with the provided arguments
+     * @param event The name of the event to emit
+     */
+    emit<E extends keyof Events>(event: E, ...args: Events[E]): boolean;
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,44 @@
+import { AWSError } from "./types.js";
+declare class SQSError extends Error {
+    code: string;
+    statusCode: number;
+    service: string;
+    time: Date;
+    retryable: boolean;
+    fault: "client" | "server";
+    constructor(message: string);
+}
+declare class TimeoutError extends Error {
+    cause: Error;
+    time: Date;
+    constructor(message?: string);
+}
+declare class StandardError extends Error {
+    cause: Error;
+    time: Date;
+    constructor(message?: string);
+}
+/**
+ * Checks if the error provided should be treated as a connection error.
+ * @param err The error that was received.
+ */
+declare function isConnectionError(err: Error): boolean;
+/**
+ * Formats an AWSError the the SQSError type.
+ * @param err The error object that was received.
+ * @param message The message to send with the error.
+ */
+declare function toSQSError(err: AWSError, message: string): SQSError;
+/**
+ * Formats an Error to the StandardError type.
+ * @param err The error object that was received.
+ * @param message The message to send with the error.
+ */
+declare function toStandardError(err: Error, message: string): StandardError;
+/**
+ * Formats an Error to the TimeoutError type.
+ * @param err The error object that was received.
+ * @param message The message to send with the error.
+ */
+declare function toTimeoutError(err: TimeoutError, message: string): TimeoutError;
+export { SQSError, TimeoutError, isConnectionError, toSQSError, toStandardError, toTimeoutError, };

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export { Consumer } from "./consumer.js";
+export * from "./types.js";

package/dist/esm/logger.d.ts

@@ -0,0 +1,3 @@
+export declare const logger: {
+    debug: any;
+};

package/dist/esm/types.d.ts

@@ -0,0 +1,279 @@
+import { SQSClient, Message, QueueAttributeName } from "@aws-sdk/client-sqs";
+/**
+ * The options for the consumer.
+ */
+export interface ConsumerOptions {
+    /**
+     * The SQS queue URL.
+     */
+    queueUrl: string;
+    /**
+     * List of queue attributes to retrieve, see [AWS docs](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-sqs/Variable/QueueAttributeName/).
+     * @defaultvalue `[]`
+     */
+    attributeNames?: QueueAttributeName[];
+    /**
+     * List of message attributes to retrieve (i.e. `['name', 'address']`).
+     * @defaultvalue `[]`
+     */
+    messageAttributeNames?: string[];
+    /** @hidden */
+    stopped?: boolean;
+    /**
+     * The number of messages to request from SQS when polling (default `1`).
+     *
+     * This cannot be higher than the
+     * [AWS limit of 10](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-messages.html).
+     * @defaultvalue `1`
+     */
+    batchSize?: number;
+    /**
+     * The duration (in seconds) that the received messages are hidden from subsequent
+     * retrieve requests after being retrieved by a ReceiveMessage request.
+     */
+    visibilityTimeout?: number;
+    /**
+     * The duration (in seconds) for which the call will wait for a message to arrive in
+     * the queue before returning.
+     * @defaultvalue `20`
+     */
+    waitTimeSeconds?: number;
+    /**
+     * The duration (in milliseconds) to wait before retrying after an authentication error.
+     * @defaultvalue `10000`
+     */
+    authenticationErrorTimeout?: number;
+    /**
+     * The duration (in milliseconds) to wait before repolling the queue.
+     * @defaultvalue `0`
+     */
+    pollingWaitTimeMs?: number;
+    /**
+     * If you want the stop action to wait for the final poll to complete and in-flight messages
+     * to be processed before emitting 'stopped' set this to the max amount of time to wait.
+     * @defaultvalue `0`
+     */
+    pollingCompleteWaitTimeMs?: number;
+    /**
+     * If true, sets the message visibility timeout to 0 after a `processing_error`.
+     * @defaultvalue `false`
+     */
+    terminateVisibilityTimeout?: boolean;
+    /**
+     * The interval (in seconds) between requests to extend the message visibility timeout.
+     *
+     * On each heartbeat the visibility is extended by adding `visibilityTimeout` to
+     * the number of seconds since the start of the handler function.
+     *
+     * This value must less than `visibilityTimeout`.
+     */
+    heartbeatInterval?: number;
+    /**
+     * An optional [SQS Client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-sqs/classes/sqsclient.html)
+     * object to use if you need to configure the client manually.
+     */
+    sqs?: SQSClient;
+    /**
+     * The AWS region.
+     * @defaultValue process.env.AWS_REGION || `eu-west-1`
+     */
+    region?: string;
+    /**
+     * If false uses the QueueUrl hostname as the endpoint.
+     * @defaultValue `true`
+     */
+    useQueueUrlAsEndpoint?: boolean;
+    /**
+     * Time in ms to wait for `handleMessage` to process a message before timing out.
+     *
+     * Emits `timeout_error` on timeout. By default, if `handleMessage` times out,
+     * the unprocessed message returns to the end of the queue.
+     */
+    handleMessageTimeout?: number;
+    /**
+     * Default to `true`, if you don't want the package to delete messages from sqs
+     * set this to `false`.
+     * @defaultvalue `true`
+     */
+    shouldDeleteMessages?: boolean;
+    /**
+     * By default, the consumer will treat an empty object or array from either of the
+     * handlers as a acknowledgement of no messages and will not delete those messages as
+     * a result. Set this to `true` to always acknowledge all messages no matter the returned
+     * value.
+     * @defaultvalue `false`
+     */
+    alwaysAcknowledge?: boolean;
+    /**
+     * An `async` function (or function that returns a `Promise`) to be called whenever
+     * a message is received.
+     *
+     * In the case that you need to acknowledge the message, return an object containing
+     * the MessageId that you'd like to acknowledge.
+     */
+    handleMessage?(message: Message): Promise<Message | void>;
+    /**
+     * An `async` function (or function that returns a `Promise`) to be called whenever
+     * a batch of messages is received. Similar to `handleMessage` but will receive the
+     * list of messages, not each message individually.
+     *
+     * **If both are set, `handleMessageBatch` overrides `handleMessage`**.
+     *
+     * In the case that you need to ack only some of the messages, return an array with
+     * the successful messages only.
+     */
+    handleMessageBatch?(messages: Message[]): Promise<Message[] | void>;
+    /**
+     * An `async` function (or function that returns a `Promise`) to be called right
+     * before the SQS Client sends a receive message command.
+     *
+     * This function is usefull if SQS Client module exports have been modified, for
+     * example to add middlewares.
+     */
+    preReceiveMessageCallback?(): Promise<void>;
+    /**
+     * An `async` function (or function that returns a `Promise`) to be called right
+     * after the SQS Client sends a receive message command.
+     *
+     * This function is usefull if SQS Client module exports have been modified, for
+     * example to add middlewares.
+     */
+    postReceiveMessageCallback?(): Promise<void>;
+}
+/**
+ * A subset of the ConsumerOptions that can be updated at runtime.
+ */
+export type UpdatableOptions = "visibilityTimeout" | "batchSize" | "waitTimeSeconds" | "pollingWaitTimeMs";
+/**
+ * The options for the stop method.
+ */
+export interface StopOptions {
+    /**
+     * Default to `false`, if you want the stop action to also abort requests to SQS
+     * set this to `true`.
+     * @defaultvalue `false`
+     */
+    abort?: boolean;
+}
+/**
+ * These are the events that the consumer emits.
+ */
+export interface Events {
+    /**
+     * Fired after one batch of items (up to `batchSize`) has been successfully processed.
+     */
+    response_processed: [];
+    /**
+     * Fired when the queue is empty (All messages have been consumed).
+     */
+    empty: [];
+    /**
+     * Fired when a message is received.
+     */
+    message_received: [Message];
+    /**
+     * Fired when a message is successfully processed and removed from the queue.
+     */
+    message_processed: [Message];
+    /**
+     * Fired when an error occurs interacting with the queue.
+     *
+     * If the error correlates to a message, that message is included in Params
+     */
+    error: [Error, void | Message | Message[]];
+    /**
+     * Fired when `handleMessageTimeout` is supplied as an option and if
+     * `handleMessage` times out.
+     */
+    timeout_error: [Error, Message];
+    /**
+     * Fired when an error occurs processing the message.
+     */
+    processing_error: [Error, Message];
+    /**
+     * Fired when requests to SQS were aborted.
+     */
+    aborted: [];
+    /**
+     * Fired when the consumer starts its work..
+     */
+    started: [];
+    /**
+     * Fired when the consumer finally stops its work.
+     */
+    stopped: [];
+    /**
+     * Fired when an option is updated
+     */
+    option_updated: [UpdatableOptions, ConsumerOptions[UpdatableOptions]];
+    /**
+     * Fired when the Consumer is waiting for polling to complete before stopping.
+     */
+    waiting_for_polling_to_complete: [];
+    /**
+     * Fired when the Consumer has waited for polling to complete and is stopping due to a timeout.
+     */
+    waiting_for_polling_to_complete_timeout_exceeded: [];
+}
+/**
+ * The error object that is emitted with error events from AWS.
+ */
+export type AWSError = {
+    /**
+     * Name, eg. ConditionalCheckFailedException
+     */
+    name: string;
+    /**
+     * Human-readable error response message
+     */
+    message: string;
+    /**
+     * Non-standard stacktrace
+     */
+    stack?: string;
+    /**
+     * Whether the client or server are at fault.
+     */
+    readonly $fault?: "client" | "server";
+    /**
+     * The service that encountered the exception.
+     */
+    readonly $service?: string;
+    /**
+     * Indicates that an error MAY be retried by the client.
+     */
+    readonly $retryable?: {
+        /**
+         * Indicates that the error is a retryable throttling error.
+         */
+        readonly throttling?: boolean;
+    };
+    $metadata?: {
+        /**
+         * The status code of the last HTTP response received for this operation.
+         */
+        httpStatusCode?: number;
+        /**
+         * A unique identifier for the last request sent for this operation. Often
+         * requested by AWS service teams to aid in debugging.
+         */
+        requestId?: string;
+        /**
+         * A secondary identifier for the last request sent. Used for debugging.
+         */
+        extendedRequestId?: string;
+        /**
+         * A tertiary identifier for the last request sent. Used for debugging.
+         */
+        cfId?: string;
+        /**
+         * The number of times this operation was attempted.
+         */
+        attempts?: number;
+        /**
+         * The total amount of time (in milliseconds) that was spent waiting between
+         * retry attempts.
+         */
+        totalRetryDelay?: number;
+    };
+};

package/dist/esm/validation.d.ts

@@ -0,0 +1,16 @@
+import { ReceiveMessageCommandOutput } from "@aws-sdk/client-sqs";
+import { ConsumerOptions } from "./types.js";
+declare function validateOption(option: string, value: any, allOptions: {
+    [key: string]: any;
+}, strict?: boolean): void;
+/**
+ * Ensure that the required options have been set.
+ * @param options The options that have been set by the application.
+ */
+declare function assertOptions(options: ConsumerOptions): void;
+/**
+ * Determine if the response from SQS has messages in it.
+ * @param response The response from SQS.
+ */
+declare function hasMessages(response: ReceiveMessageCommandOutput): boolean;
+export { hasMessages, assertOptions, validateOption };

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "sqs-consumer",
-  "version": "10.2.0",
+  "version": "10.2.1",
   "description": "Build SQS-based Node applications without the boilerplate",
   "type": "module",
   "main": "dist/cjs/index.js",
-  "types": "dist/types/index.d.ts",
+  "types": "dist/cjs/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/types/index.d.ts",
-      "require": "./dist/cjs/index.js",
-      "import": "./dist/esm/index.js",
-      "default": "./dist/esm/index.js"
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
   "engines": {

package/tsconfig.cjs.json

@@ -4,6 +4,7 @@
     "outDir": "./dist/cjs",
     "module": "commonjs",
     "moduleResolution": "node",
-    "noEmit": false
+    "noEmit": false,
+    "declaration": true
   }
 }

package/tsconfig.esm.json

@@ -4,6 +4,7 @@
     "outDir": "./dist/esm",
     "module": "Node16",
     "moduleResolution": "Node16",
-    "noEmit": false
+    "noEmit": false,
+    "declaration": true
   }
 }

package/tsconfig.json

@@ -8,8 +8,7 @@
     "sourceMap": false,
     "allowJs": false,
     "noUnusedLocals": true,
-    "declaration": true,
-    "declarationDir": "dist/types"
+    "declaration": false
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist"]