sqs-consumer 6.1.0 → 6.2.1

package/.github/CONTRIBUTING.md

@@ -6,7 +6,7 @@ Thank you for your interest in contributing to the sqs-consumer.
 - We aim for 100% test coverage. Please write tests for any new functionality or changes.
 - Any API changes should be fully documented.
 - Make sure your code meets our linting standards. Run `npm run lint` to check your code.
-- Maintain the existing coding style. There are some settings in `.jsbeautifyrc` to help.
+- Maintain the existing coding style.
 - Be mindful of others when making suggestions and/or code reviewing.
 
 ## Reporting Issues

package/.github/workflows/coverage.yml

@@ -23,6 +23,10 @@ jobs:
         uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: NPM Audit
+        run: npx audit-ci
 
       - name: Install Node Modules
         run: npm ci
@@ -30,6 +34,6 @@ jobs:
       - name: Report Coverage
         uses: paambaati/codeclimate-action@v3.2.0
         env:
-          CC_TEST_REPORTER_ID: 2d851f8f3a9348ac4f43262305037f80a730c2660fda50af8ae4d445fd89333b
+          CC_TEST_REPORTER_ID: 760097cb88b4c685dce427cf94a8e12a5f082774d06b4f4f5daef839ffc07821
         with:
           coverageCommand: npm run lcov

package/.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18.x
+          cache: 'npm'
+
+      - name: NPM Audit
+        run: npx audit-ci
+
+      - name: Install Node Modules
+        run: npm ci
+
+      - name: Build Docs
+        run: npm run generate-docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: './public'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

package/.github/workflows/test.yml

@@ -23,12 +23,18 @@ jobs:
         uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
-
-      - name: Install Node Modules
-        run: npm ci
+          cache: 'npm'
 
       - name: NPM Audit
         run: npx audit-ci
 
+      - name: Install Node Modules
+        run: npm ci
+
       - name: Run Tests and Linting
         run: npm run test
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: test-reports-${{ matrix.node-version }}
+          path: test/reports/

package/.prettierignore

@@ -1,4 +1,6 @@
 node_modules
 coverage
 bake-scripts
-dist
+dist
+public
+test/reports

package/README.md

@@ -2,15 +2,17 @@
 
 [![NPM downloads](https://img.shields.io/npm/dm/sqs-consumer.svg?style=flat)](https://npmjs.org/package/sqs-consumer)
 [![Build Status](https://github.com/bbc/sqs-consumer/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/bbc/sqs-consumer/actions/workflows/test.yml)
-[![Code Climate](https://codeclimate.com/github/BBC/sqs-consumer/badges/gpa.svg)](https://codeclimate.com/github/BBC/sqs-consumer)
-[![Test Coverage](https://codeclimate.com/github/BBC/sqs-consumer/badges/coverage.svg)](https://codeclimate.com/github/BBC/sqs-consumer)
+[![Maintainability](https://api.codeclimate.com/v1/badges/16ec3f59e73bc898b7ff/maintainability)](https://codeclimate.com/github/bbc/sqs-consumer/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/16ec3f59e73bc898b7ff/test_coverage)](https://codeclimate.com/github/bbc/sqs-consumer/test_coverage)
 
 Build SQS-based applications without the boilerplate. Just define an async function that handles the SQS message processing.
 
 ## Installation
 
+To install this package, simply enter the following command into your terminal (or the variant of whatever package manager you are using):
+
 ```bash
-npm install sqs-consumer --save-dev
+npm install --save-dev sqs-consumer
 ```
 
 > **Note**
@@ -43,16 +45,14 @@ app.on('processing_error', (err) => {
 app.start();
 ```
 
-- The queue is polled continuously for messages using [long polling](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-long-polling.html).
+- The queue is polled continuously for messages using [long polling](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-long-polling.html).
 - Messages are deleted from the queue once the handler function has completed successfully.
-- Throwing an error (or returning a rejected promise) from the handler function will cause the message to be left on the queue. An [SQS redrive policy](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/SQSDeadLetterQueue.html) can be used to move messages that cannot be processed to a dead letter queue.
+- Throwing an error (or returning a rejected promise) from the handler function will cause the message to be left on the queue. An [SQS redrive policy](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/SQSDeadLetterQueue.html) can be used to move messages that cannot be processed to a dead letter queue.
 - By default messages are processed one at a time – a new message won't be received until the first one has been processed. To process messages in parallel, use the `batchSize` option [detailed below](#options).
 
-You can also find some examples of sqs-consumer implemented in various ways within the [examples directory](./examples/).
-
 ### Credentials
 
-By default the consumer will look for AWS credentials in the places [specified by the AWS SDK](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html#Setting_AWS_Credentials). The simplest option is to export your credentials as environment variables:
+By default the consumer will look for AWS credentials in the places [specified by the AWS SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html#Setting_AWS_Credentials). The simplest option is to export your credentials as environment variables:
 
 ```bash
 export AWS_SECRET_ACCESS_KEY=...
@@ -102,28 +102,7 @@ Consumer will receive and delete messages from the SQS queue. Ensure `sqs:Receiv
 
 ### `Consumer.create(options)`
 
-Creates a new SQS consumer.
-
-#### Options
-
-| Option                       | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                            |
-| ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `queueUrl`                   | String    | The SQS queue URL                                                                                                                                                                                                                                                                                                                                                                                      |
-| `region`                     | String    | The AWS region (default `eu-west-1`)                                                                                                                                                                                                                                                                                                                                                                   |
-| `handleMessage`              | Function  | An `async` function (or function that returns a `Promise`) to be called whenever a message is received. Receives an SQS message object as its first argument.                                                                                                                                                                                                                                          |
-| `handleMessageBatch`         | Function  | 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. |
-| `handleMessageTimeout`       | Number    | 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.                                                                                                                                                                                    |
-| `attributeNames`             | Array     | List of queue attributes to retrieve (i.e. `['All', 'ApproximateFirstReceiveTimestamp', 'ApproximateReceiveCount']`).                                                                                                                                                                                                                                                                                  |
-| `messageAttributeNames`      | Array     | List of message attributes to retrieve (i.e. `['name', 'address']`).                                                                                                                                                                                                                                                                                                                                   |
-| `batchSize`                  | Number    | 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).                                                                                                                                                                              |
-| `visibilityTimeout`          | Number    | The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a ReceiveMessage request.                                                                                                                                                                                                                                                   |
-| `heartbeatInterval`          | Number    | 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`.                                                                                                                       |
-| `terminateVisibilityTimeout` | Boolean   | If true, sets the message visibility timeout to 0 after a `processing_error` (defaults to `false`).                                                                                                                                                                                                                                                                                                    |
-| `waitTimeSeconds`            | Number    | The duration (in seconds) for which the call will wait for a message to arrive in the queue before returning (defaults to `20`).                                                                                                                                                                                                                                                                       |
-| `authenticationErrorTimeout` | Number    | The duration (in milliseconds) to wait before retrying after an authentication error (defaults to `10000`).                                                                                                                                                                                                                                                                                            |
-| `pollingWaitTimeMs`          | Number    | The duration (in milliseconds) to wait before repolling the queue (defaults to `0`).                                                                                                                                                                                                                                                                                                                   |
-| `sqs`                        | SQSClient | 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                                                                                                                                                                                                                  |
-| `shouldDeleteMessages`       | Boolean   | Default to `true`, if you don't want the package to delete messages from sqs set this to `false`                                                                                                                                                                                                                                                                                                       |
+Creates a new SQS consumer using the [defined options](https://bbc.github.io/sqs-consumer/interfaces/ConsumerOptions.html).
 
 ### `consumer.start()`
 
@@ -131,7 +110,7 @@ Start polling the queue for messages.
 
 ### `consumer.stop()`
 
-Stop polling the queue for messages.
+Stop polling the queue for messages (pre existing requests will still be made until concluded).
 
 ### `consumer.isRunning`
 
@@ -139,19 +118,14 @@ Returns the current polling state of the consumer: `true` if it is actively poll
 
 ### Events
 
-Each consumer is an [`EventEmitter`](http://nodejs.org/api/events.html) and emits the following events:
+Each consumer is an [`EventEmitter`](https://nodejs.org/api/events.html) and [emits these events](https://bbc.github.io/sqs-consumer/interfaces/Events.html).
+
+## Contributing
+
+We welcome and appreciate contributions for anyone who would like to take the time to fix a bug or implement a new feature.
 
-| Event                | Params             | Description                                                                                                                     |
-| -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| `error`              | `err`, `[message]` | Fired when an error occurs interacting with the queue. If the error correlates to a message, that message is included in Params |
-| `processing_error`   | `err`, `message`   | Fired when an error occurs processing the message.                                                                              |
-| `timeout_error`      | `err`, `message`   | Fired when `handleMessageTimeout` is supplied as an option and if `handleMessage` times out.                                    |
-| `message_received`   | `message`          | Fired when a message is received.                                                                                               |
-| `message_processed`  | `message`          | Fired when a message is successfully processed and removed from the queue.                                                      |
-| `response_processed` | None               | Fired after one batch of items (up to `batchSize`) has been successfully processed.                                             |
-| `stopped`            | None               | Fired when the consumer finally stops its work.                                                                                 |
-| `empty`              | None               | Fired when the queue is empty (All messages have been consumed).                                                                |
+But before you get started, [please read the contributing guidelines](https://github.com/bbc/sqs-consumer/blob/main/.github/CONTRIBUTING.md) and [code of conduct](https://github.com/bbc/sqs-consumer/blob/main/.github/CODE_OF_CONDUCT.md).
 
-### Contributing
+## License
 
-See contributing [guidelines](https://github.com/bbc/sqs-consumer/blob/main/.github/CONTRIBUTING.md).
+SQS Consumer is distributed under the Apache License, Version 2.0, see [LICENSE](https://github.com/bbc/sqs-consumer/blob/main/LICENSE) for more information.

package/dist/bind.d.ts

@@ -1 +1,5 @@
+/**
+ * Auto binds the provided properties
+ * @param obj an object containing the available properties
+ */
 export declare function autoBind(obj: object): void;

package/dist/bind.js

@@ -1,9 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.autoBind = void 0;
+/**
+ * Determines if the property is a method
+ * @param propertyName the name of the property
+ * @param value the value of the property
+ */
 function isMethod(propertyName, value) {
     return propertyName !== 'constructor' && typeof value === 'function';
 }
+/**
+ * Auto binds the provided properties
+ * @param obj an object containing the available properties
+ */
 function autoBind(obj) {
     const propertyNames = Object.getOwnPropertyNames(obj.constructor.prototype);
     propertyNames.forEach((propertyName) => {

package/dist/consumer.d.ts

@@ -1,42 +1,111 @@
-/// <reference types="node" />
-import { EventEmitter } from 'events';
-import { ConsumerOptions, Events } from './types';
-export declare class Consumer extends EventEmitter {
+import { ConsumerOptions, TypedEventEmitter } from './types';
+/**
+ * [Usage](https://bbc.github.io/sqs-consumer/index.html#usage)
+ */
+export declare class Consumer extends TypedEventEmitter {
+    private pollingTimeoutId;
+    private heartbeatTimeoutId;
+    private handleMessageTimeoutId;
+    private stopped;
     private queueUrl;
     private handleMessage;
     private handleMessageBatch;
+    private sqs;
     private handleMessageTimeout;
     private attributeNames;
     private messageAttributeNames;
-    private stopped;
+    private shouldDeleteMessages;
     private batchSize;
     private visibilityTimeout;
+    private terminateVisibilityTimeout;
     private waitTimeSeconds;
     private authenticationErrorTimeout;
     private pollingWaitTimeMs;
-    private terminateVisibilityTimeout;
     private heartbeatInterval;
-    private sqs;
-    private shouldDeleteMessages;
     constructor(options: ConsumerOptions);
-    emit<T extends keyof Events>(event: T, ...args: Events[T]): boolean;
-    on<T extends keyof Events>(event: T, listener: (...args: Events[T]) => void): this;
-    once<T extends keyof Events>(event: T, listener: (...args: Events[T]) => void): this;
-    get isRunning(): boolean;
+    /**
+     * Creates a new SQS consumer.
+     */
     static create(options: ConsumerOptions): Consumer;
+    /**
+     * Start polling the queue for messages.
+     */
     start(): void;
+    /**
+     * Stop polling the queue for messages (pre existing requests will still be made until concluded).
+     */
     stop(): void;
-    private handleSqsResponse;
-    private processMessage;
-    private receiveMessage;
-    private deleteMessage;
-    private executeHandler;
-    private changeVisibilityTimeout;
+    /**
+     * Returns the current polling state of the consumer: `true` if it is actively polling, `false` if it is not.
+     */
+    get isRunning(): boolean;
+    /**
+     * 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;
-    private deleteMessageBatch;
-    private executeBatchHandler;
-    private changeVisibilityTimeoutBatch;
+    /**
+     * 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;
 }