sqs-consumer 6.1.0 → 6.2.0

package/dist/types.d.ts

@@ -1,33 +1,166 @@
+/// <reference types="node" />
 import { SQSClient, Message } from '@aws-sdk/client-sqs';
+import { EventEmitter } from 'events';
 export interface ConsumerOptions {
+    /**
+     * The SQS queue URL.
+     */
     queueUrl: string;
+    /**
+     * List of queue attributes to retrieve (i.e.
+     * `['All', 'ApproximateFirstReceiveTimestamp', 'ApproximateReceiveCount']`).
+     * @defaultvalue `[]`
+     */
     attributeNames?: string[];
+    /**
+     * 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 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 `eu-west-1`
+     */
     region?: string;
+    /**
+     * 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;
-    handleMessage?(message: Message): Promise<void>;
+    /**
+     * 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>;
 }
 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 the consumer finally stops its work.
+     */
     stopped: [];
 }
+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;
+}
 export type AWSError = {
     /**
      * Name, eg. ConditionalCheckFailedException

package/dist/types.js

@@ -1,2 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypedEventEmitter = void 0;
+const events_1 = require("events");
+class TypedEventEmitter extends events_1.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(event, listener) {
+        return super.on(event, listener);
+    }
+    /**
+     * 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(event, listener) {
+        return super.on(event, listener);
+    }
+    /**
+     * Emits an event with the provided arguments
+     * @param event The name of the event to emit
+     */
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+}
+exports.TypedEventEmitter = TypedEventEmitter;

package/dist/validation.d.ts

@@ -0,0 +1,13 @@
+import { ReceiveMessageCommandOutput } from '@aws-sdk/client-sqs';
+import { ConsumerOptions } from './types';
+/**
+ * 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 };

package/dist/validation.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertOptions = exports.hasMessages = void 0;
+const requiredOptions = [
+    'queueUrl',
+    // only one of handleMessage / handleMessagesBatch is required
+    'handleMessage|handleMessageBatch'
+];
+/**
+ * Ensure that the required options have been set.
+ * @param options The options that have been set by the application.
+ */
+function assertOptions(options) {
+    requiredOptions.forEach((option) => {
+        const possibilities = option.split('|');
+        if (!possibilities.find((p) => options[p])) {
+            throw new Error(`Missing SQS consumer option [ ${possibilities.join(' or ')} ].`);
+        }
+    });
+    if (options.batchSize > 10 || options.batchSize < 1) {
+        throw new Error('SQS batchSize option must be between 1 and 10.');
+    }
+    if (options.heartbeatInterval &&
+        !(options.heartbeatInterval < options.visibilityTimeout)) {
+        throw new Error('heartbeatInterval must be less than visibilityTimeout.');
+    }
+}
+exports.assertOptions = assertOptions;
+/**
+ * Determine if the response from SQS has messages in it.
+ * @param response The response from SQS.
+ */
+function hasMessages(response) {
+    return response.Messages && response.Messages.length > 0;
+}
+exports.hasMessages = hasMessages;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqs-consumer",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Build SQS-based Node applications without the boilerplate",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +17,8 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --loglevel warn --write \"**/*.{js,json,jsx,md,ts,tsx,html}\"",
     "format:check": "prettier --check \"**/*.{js,json,jsx,md,ts,tsx,html}\"",
-    "posttest": "npm run lint && npm run format:check"
+    "posttest": "npm run lint && npm run format:check",
+    "generate-docs": "typedoc"
   },
   "repository": {
     "type": "git",
@@ -26,7 +27,7 @@
   "bugs": {
     "url": "https://github.com/BBC/sqs-consumer/issues"
   },
-  "homepage": "https://github.com/BBC/sqs-consumer",
+  "homepage": "https://bbc.github.io/sqs-consumer/",
   "keywords": [
     "sqs",
     "queue",
@@ -37,26 +38,27 @@
     "@types/chai": "^4.3.4",
     "@types/debug": "^4.1.7",
     "@types/mocha": "^10.0.1",
-    "@types/node": "^16.18.7",
+    "@types/node": "^18.11.18",
     "@types/sinon": "^10.0.13",
     "chai": "^4.3.7",
-    "eslint": "^8.29.0",
+    "eslint": "^8.31.0",
     "eslint-config-iplayer-ts": "^4.1.0",
-    "eslint-config-prettier": "^4.3.0",
-    "mocha": "^10.1.0",
+    "eslint-config-prettier": "^8.5.0",
+    "mocha": "^10.2.0",
     "nyc": "^15.1.0",
     "p-event": "^4.2.0",
     "prettier": "^2.8.1",
-    "sinon": "^15.0.0",
+    "sinon": "^15.0.1",
     "ts-node": "^10.9.1",
+    "typedoc": "^0.23.23",
     "typescript": "^4.9.4"
   },
   "dependencies": {
-    "@aws-sdk/client-sqs": "^3.226.0",
+    "@aws-sdk/client-sqs": "^3.241.0",
     "debug": "^4.3.4"
   },
   "peerDependencies": {
-    "@aws-sdk/client-sqs": "^3.226.0"
+    "@aws-sdk/client-sqs": "^3.241.0"
   },
   "mocha": {
     "spec": "test/**/**/*.test.ts",
@@ -78,9 +80,7 @@
   "eslintConfig": {
     "extends": [
       "iplayer-ts",
-      "prettier",
-      "prettier/react",
-      "prettier/@typescript-eslint"
+      "prettier"
     ],
     "parserOptions": {
       "sourceType": "module"

package/src/bind.ts

@@ -1,7 +1,16 @@
+/**
+ * Determines if the property is a method
+ * @param propertyName the name of the property
+ * @param value the value of the property
+ */
 function isMethod(propertyName: string, value: any): boolean {
   return propertyName !== 'constructor' && typeof value === 'function';
 }
 
+/**
+ * Auto binds the provided properties
+ * @param obj an object containing the available properties
+ */
 export function autoBind(obj: object): void {
   const propertyNames = Object.getOwnPropertyNames(obj.constructor.prototype);
   propertyNames.forEach((propertyName) => {