sqs-consumer 6.1.0 → 6.2.0

package/dist/consumer.js

@@ -3,74 +3,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Consumer = void 0;
 const client_sqs_1 = require("@aws-sdk/client-sqs");
 const debug_1 = require("debug");
-const events_1 = require("events");
+const types_1 = require("./types");
 const bind_1 = require("./bind");
 const errors_1 = require("./errors");
+const validation_1 = require("./validation");
 const debug = (0, debug_1.default)('sqs-consumer');
-const requiredOptions = [
-    'queueUrl',
-    // only one of handleMessage / handleMessagesBatch is required
-    'handleMessage|handleMessageBatch'
-];
-function createTimeout(duration) {
-    let timeout;
-    const pending = new Promise((_, reject) => {
-        timeout = setTimeout(() => {
-            reject(new errors_1.TimeoutError());
-        }, duration);
-    });
-    return [timeout, pending];
-}
-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.');
-    }
-}
-function isConnectionError(err) {
-    if (err instanceof errors_1.SQSError) {
-        return (err.statusCode === 403 ||
-            err.code === 'CredentialsError' ||
-            err.code === 'UnknownEndpoint' ||
-            err.code === 'AWS.SimpleQueueService.NonExistentQueue');
-    }
-    return false;
-}
-function toSQSError(err, message) {
-    var _a, _b;
-    const sqsError = new errors_1.SQSError(message);
-    sqsError.code = err.name;
-    sqsError.statusCode = (_a = err.$metadata) === null || _a === void 0 ? void 0 : _a.httpStatusCode;
-    sqsError.retryable = (_b = err.$retryable) === null || _b === void 0 ? void 0 : _b.throttling;
-    sqsError.service = err.$service;
-    sqsError.fault = err.$fault;
-    sqsError.time = new Date();
-    return sqsError;
-}
-function hasMessages(response) {
-    return response.Messages && response.Messages.length > 0;
-}
-class Consumer extends events_1.EventEmitter {
+/**
+ * [Usage](https://bbc.github.io/sqs-consumer/index.html#usage)
+ */
+class Consumer extends types_1.TypedEventEmitter {
     constructor(options) {
         var _a, _b, _c, _d;
         super();
-        assertOptions(options);
+        this.pollingTimeoutId = undefined;
+        this.heartbeatTimeoutId = undefined;
+        this.handleMessageTimeoutId = undefined;
+        this.stopped = true;
+        (0, validation_1.assertOptions)(options);
         this.queueUrl = options.queueUrl;
         this.handleMessage = options.handleMessage;
         this.handleMessageBatch = options.handleMessageBatch;
         this.handleMessageTimeout = options.handleMessageTimeout;
         this.attributeNames = options.attributeNames || [];
         this.messageAttributeNames = options.messageAttributeNames || [];
-        this.stopped = true;
         this.batchSize = options.batchSize || 1;
         this.visibilityTimeout = options.visibilityTimeout;
         this.terminateVisibilityTimeout =
@@ -88,21 +43,15 @@ class Consumer extends events_1.EventEmitter {
                 });
         (0, bind_1.autoBind)(this);
     }
-    emit(event, ...args) {
-        return super.emit(event, ...args);
-    }
-    on(event, listener) {
-        return super.on(event, listener);
-    }
-    once(event, listener) {
-        return super.once(event, listener);
-    }
-    get isRunning() {
-        return !this.stopped;
-    }
+    /**
+     * Creates a new SQS consumer.
+     */
     static create(options) {
         return new Consumer(options);
     }
+    /**
+     * Start polling the queue for messages.
+     */
     start() {
         if (this.stopped) {
             debug('Starting consumer');
@@ -110,117 +59,38 @@ class Consumer extends events_1.EventEmitter {
             this.poll();
         }
     }
+    /**
+     * Stop polling the queue for messages (pre existing requests will still be made until concluded).
+     */
     stop() {
-        debug('Stopping consumer');
-        this.stopped = true;
-    }
-    async handleSqsResponse(response) {
-        debug('Received SQS response');
-        debug(response);
-        if (response) {
-            if (hasMessages(response)) {
-                if (this.handleMessageBatch) {
-                    // prefer handling messages in batch when available
-                    await this.processMessageBatch(response.Messages);
-                }
-                else {
-                    await Promise.all(response.Messages.map(this.processMessage));
-                }
-                this.emit('response_processed');
-            }
-            else {
-                this.emit('empty');
-            }
-        }
-    }
-    async processMessage(message) {
-        this.emit('message_received', message);
-        let heartbeat;
-        try {
-            if (this.heartbeatInterval) {
-                heartbeat = this.startHeartbeat(async () => {
-                    return this.changeVisibilityTimeout(message, this.visibilityTimeout);
-                });
-            }
-            await this.executeHandler(message);
-            await this.deleteMessage(message);
-            this.emit('message_processed', message);
-        }
-        catch (err) {
-            this.emitError(err, message);
-            if (this.terminateVisibilityTimeout) {
-                await this.changeVisibilityTimeout(message, 0);
-            }
-        }
-        finally {
-            clearInterval(heartbeat);
-        }
-    }
-    async receiveMessage(params) {
-        try {
-            return await this.sqs.send(new client_sqs_1.ReceiveMessageCommand(params));
-        }
-        catch (err) {
-            throw toSQSError(err, `SQS receive message failed: ${err.message}`);
-        }
-    }
-    async deleteMessage(message) {
-        if (!this.shouldDeleteMessages) {
-            debug('Skipping message delete since shouldDeleteMessages is set to false');
+        if (this.stopped) {
+            debug('Consumer was already stopped');
             return;
         }
-        debug('Deleting message %s', message.MessageId);
-        const deleteParams = {
-            QueueUrl: this.queueUrl,
-            ReceiptHandle: message.ReceiptHandle
-        };
-        try {
-            await this.sqs.send(new client_sqs_1.DeleteMessageCommand(deleteParams));
-        }
-        catch (err) {
-            throw toSQSError(err, `SQS delete message failed: ${err.message}`);
-        }
-    }
-    async executeHandler(message) {
-        let timeout;
-        let pending;
-        try {
-            if (this.handleMessageTimeout) {
-                [timeout, pending] = createTimeout(this.handleMessageTimeout);
-                await Promise.race([this.handleMessage(message), pending]);
-            }
-            else {
-                await this.handleMessage(message);
-            }
-        }
-        catch (err) {
-            if (err instanceof errors_1.TimeoutError) {
-                err.message = `Message handler timed out after ${this.handleMessageTimeout}ms: Operation timed out.`;
-            }
-            else if (err instanceof Error) {
-                err.message = `Unexpected message handler failure: ${err.message}`;
-            }
-            throw err;
-        }
-        finally {
-            clearTimeout(timeout);
+        debug('Stopping consumer');
+        this.stopped = true;
+        if (this.pollingTimeoutId) {
+            clearTimeout(this.pollingTimeoutId);
+            this.pollingTimeoutId = undefined;
         }
+        this.emit('stopped');
     }
-    async changeVisibilityTimeout(message, timeout) {
-        try {
-            const input = {
-                QueueUrl: this.queueUrl,
-                ReceiptHandle: message.ReceiptHandle,
-                VisibilityTimeout: timeout
-            };
-            return await this.sqs.send(new client_sqs_1.ChangeMessageVisibilityCommand(input));
-        }
-        catch (err) {
-            this.emit('error', toSQSError(err, `Error changing visibility timeout: ${err.message}`), message);
-        }
+    /**
+     * Returns the current polling state of the consumer: `true` if it is actively polling, `false` if it is not.
+     */
+    get isRunning() {
+        return !this.stopped;
     }
+    /**
+     * 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
+     */
     emitError(err, message) {
-        if (err.name === errors_1.SQSError.name) {
+        if (!message) {
+            this.emit('error', err);
+        }
+        else if (err.name === errors_1.SQSError.name) {
             this.emit('error', err, message);
         }
         else if (err instanceof errors_1.TimeoutError) {
@@ -230,56 +100,121 @@ class Consumer extends events_1.EventEmitter {
             this.emit('processing_error', err, message);
         }
     }
+    /**
+     * Poll for new messages from SQS
+     */
     poll() {
         if (this.stopped) {
-            this.emit('stopped');
+            debug('Poll was called while consumer was stopped, cancelling poll...');
             return;
         }
         debug('Polling for messages');
-        const receiveParams = {
+        let currentPollingTimeout = this.pollingWaitTimeMs;
+        this.receiveMessage({
             QueueUrl: this.queueUrl,
             AttributeNames: this.attributeNames,
             MessageAttributeNames: this.messageAttributeNames,
             MaxNumberOfMessages: this.batchSize,
             WaitTimeSeconds: this.waitTimeSeconds,
             VisibilityTimeout: this.visibilityTimeout
-        };
-        let currentPollingTimeout = this.pollingWaitTimeMs;
-        this.receiveMessage(receiveParams)
+        })
             .then(this.handleSqsResponse)
             .catch((err) => {
-            this.emit('error', err);
-            if (isConnectionError(err)) {
+            this.emitError(err);
+            if ((0, errors_1.isConnectionError)(err)) {
                 debug('There was an authentication error. Pausing before retrying.');
                 currentPollingTimeout = this.authenticationErrorTimeout;
             }
             return;
         })
             .then(() => {
-            setTimeout(this.poll, currentPollingTimeout);
+            if (this.pollingTimeoutId) {
+                clearTimeout(this.pollingTimeoutId);
+            }
+            this.pollingTimeoutId = setTimeout(this.poll, currentPollingTimeout);
         })
             .catch((err) => {
-            this.emit('error', err);
+            this.emitError(err);
         });
     }
-    async processMessageBatch(messages) {
-        messages.forEach((message) => {
+    /**
+     * Send a request to SQS to retrieve messages
+     * @param params The required params to receive messages from SQS
+     */
+    async receiveMessage(params) {
+        try {
+            return await this.sqs.send(new client_sqs_1.ReceiveMessageCommand(params));
+        }
+        catch (err) {
+            throw (0, errors_1.toSQSError)(err, `SQS receive message failed: ${err.message}`);
+        }
+    }
+    /**
+     * Handles the response from AWS SQS, determining if we should proceed to
+     * the message handler.
+     * @param response The output from AWS SQS
+     */
+    async handleSqsResponse(response) {
+        if ((0, validation_1.hasMessages)(response)) {
+            if (this.handleMessageBatch) {
+                await this.processMessageBatch(response.Messages);
+            }
+            else {
+                await Promise.all(response.Messages.map(this.processMessage));
+            }
+            this.emit('response_processed');
+        }
+        else if (response) {
+            this.emit('empty');
+        }
+    }
+    /**
+     * 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
+     */
+    async processMessage(message) {
+        try {
             this.emit('message_received', message);
-        });
-        let heartbeat;
+            if (this.heartbeatInterval) {
+                this.heartbeatTimeoutId = this.startHeartbeat(message);
+            }
+            const ackedMessage = await this.executeHandler(message);
+            if ((ackedMessage === null || ackedMessage === void 0 ? void 0 : ackedMessage.MessageId) === message.MessageId) {
+                await this.deleteMessage(message);
+                this.emit('message_processed', message);
+            }
+        }
+        catch (err) {
+            this.emitError(err, message);
+            if (this.terminateVisibilityTimeout) {
+                await this.changeVisibilityTimeout(message, 0);
+            }
+        }
+        finally {
+            clearInterval(this.heartbeatTimeoutId);
+            this.heartbeatTimeoutId = undefined;
+        }
+    }
+    /**
+     * Process a batch of messages from the SQS queue.
+     * @param messages The messages that were delivered from SQS
+     */
+    async processMessageBatch(messages) {
         try {
+            messages.forEach((message) => {
+                this.emit('message_received', message);
+            });
             if (this.heartbeatInterval) {
-                heartbeat = this.startHeartbeat(async () => {
-                    return this.changeVisibilityTimeoutBatch(messages, this.visibilityTimeout);
-                });
+                this.heartbeatTimeoutId = this.startHeartbeat(null, messages);
             }
             const ackedMessages = await this.executeBatchHandler(messages);
-            if (ackedMessages.length > 0) {
+            if ((ackedMessages === null || ackedMessages === void 0 ? void 0 : ackedMessages.length) > 0) {
                 await this.deleteMessageBatch(ackedMessages);
+                ackedMessages.forEach((message) => {
+                    this.emit('message_processed', message);
+                });
             }
-            ackedMessages.forEach((message) => {
-                this.emit('message_processed', message);
-            });
         }
         catch (err) {
             this.emit('error', err, messages);
@@ -288,62 +223,154 @@ class Consumer extends events_1.EventEmitter {
             }
         }
         finally {
-            clearInterval(heartbeat);
+            clearInterval(this.heartbeatTimeoutId);
+            this.heartbeatTimeoutId = undefined;
         }
     }
-    async deleteMessageBatch(messages) {
-        if (!this.shouldDeleteMessages) {
-            debug('Skipping message delete since shouldDeleteMessages is set to false');
-            return;
+    /**
+     * Trigger a function on a set interval
+     * @param heartbeatFn The function that should be triggered
+     */
+    startHeartbeat(message, messages) {
+        return setInterval(() => {
+            if (this.handleMessageBatch) {
+                return this.changeVisibilityTimeoutBatch(messages, this.visibilityTimeout);
+            }
+            else {
+                return this.changeVisibilityTimeout(message, this.visibilityTimeout);
+            }
+        }, this.heartbeatInterval * 1000);
+    }
+    /**
+     * 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
+     */
+    async changeVisibilityTimeout(message, timeout) {
+        try {
+            const input = {
+                QueueUrl: this.queueUrl,
+                ReceiptHandle: message.ReceiptHandle,
+                VisibilityTimeout: timeout
+            };
+            return await this.sqs.send(new client_sqs_1.ChangeMessageVisibilityCommand(input));
         }
-        debug('Deleting messages %s', messages.map((msg) => msg.MessageId).join(' ,'));
-        const deleteParams = {
+        catch (err) {
+            this.emit('error', (0, errors_1.toSQSError)(err, `Error changing visibility timeout: ${err.message}`), message);
+        }
+    }
+    /**
+     * 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
+     */
+    async changeVisibilityTimeoutBatch(messages, timeout) {
+        const params = {
             QueueUrl: this.queueUrl,
             Entries: messages.map((message) => ({
                 Id: message.MessageId,
-                ReceiptHandle: message.ReceiptHandle
+                ReceiptHandle: message.ReceiptHandle,
+                VisibilityTimeout: timeout
             }))
         };
         try {
-            await this.sqs.send(new client_sqs_1.DeleteMessageBatchCommand(deleteParams));
+            return await this.sqs.send(new client_sqs_1.ChangeMessageVisibilityBatchCommand(params));
         }
         catch (err) {
-            throw toSQSError(err, `SQS delete message failed: ${err.message}`);
+            this.emit('error', (0, errors_1.toSQSError)(err, `Error changing visibility timeout: ${err.message}`), messages);
         }
     }
+    /**
+     * Trigger the applications handleMessage function
+     * @param message The message that was received from SQS
+     */
+    async executeHandler(message) {
+        try {
+            let result;
+            if (this.handleMessageTimeout) {
+                const pending = new Promise((_, reject) => {
+                    this.handleMessageTimeoutId = setTimeout(() => {
+                        reject(new errors_1.TimeoutError());
+                    }, this.handleMessageTimeout);
+                });
+                result = await Promise.race([this.handleMessage(message), pending]);
+            }
+            else {
+                result = await this.handleMessage(message);
+            }
+            return result instanceof Object ? result : message;
+        }
+        catch (err) {
+            err.message =
+                err instanceof errors_1.TimeoutError
+                    ? `Message handler timed out after ${this.handleMessageTimeout}ms: Operation timed out.`
+                    : `Unexpected message handler failure: ${err.message}`;
+            throw err;
+        }
+        finally {
+            if (this.handleMessageTimeoutId) {
+                clearTimeout(this.handleMessageTimeoutId);
+            }
+        }
+    }
+    /**
+     * Execute the application's message batch handler
+     * @param messages The messages that should be forwarded from the SQS queue
+     */
     async executeBatchHandler(messages) {
         try {
             const result = await this.handleMessageBatch(messages);
-            if (result instanceof Object) {
-                return result;
-            }
-            return messages;
+            return result instanceof Object ? result : messages;
         }
         catch (err) {
             err.message = `Unexpected message handler failure: ${err.message}`;
             throw err;
         }
     }
-    async changeVisibilityTimeoutBatch(messages, timeout) {
-        const params = {
+    /**
+     * Delete a single message from SQS
+     * @param message The message to delete from the SQS queue
+     */
+    async deleteMessage(message) {
+        if (!this.shouldDeleteMessages) {
+            debug('Skipping message delete since shouldDeleteMessages is set to false');
+            return;
+        }
+        debug('Deleting message %s', message.MessageId);
+        const deleteParams = {
+            QueueUrl: this.queueUrl,
+            ReceiptHandle: message.ReceiptHandle
+        };
+        try {
+            await this.sqs.send(new client_sqs_1.DeleteMessageCommand(deleteParams));
+        }
+        catch (err) {
+            throw (0, errors_1.toSQSError)(err, `SQS delete message failed: ${err.message}`);
+        }
+    }
+    /**
+     * Delete a batch of messages from the SQS queue.
+     * @param messages The messages that should be deleted from SQS
+     */
+    async deleteMessageBatch(messages) {
+        if (!this.shouldDeleteMessages) {
+            debug('Skipping message delete since shouldDeleteMessages is set to false');
+            return;
+        }
+        debug('Deleting messages %s', messages.map((msg) => msg.MessageId).join(' ,'));
+        const deleteParams = {
             QueueUrl: this.queueUrl,
             Entries: messages.map((message) => ({
                 Id: message.MessageId,
-                ReceiptHandle: message.ReceiptHandle,
-                VisibilityTimeout: timeout
+                ReceiptHandle: message.ReceiptHandle
             }))
         };
         try {
-            return await this.sqs.send(new client_sqs_1.ChangeMessageVisibilityBatchCommand(params));
+            await this.sqs.send(new client_sqs_1.DeleteMessageBatchCommand(deleteParams));
         }
         catch (err) {
-            this.emit('error', toSQSError(err, `Error changing visibility timeout: ${err.message}`), messages);
+            throw (0, errors_1.toSQSError)(err, `SQS delete message failed: ${err.message}`);
         }
     }
-    startHeartbeat(heartbeatFn) {
-        return setInterval(() => {
-            heartbeatFn();
-        }, this.heartbeatInterval * 1000);
-    }
 }
 exports.Consumer = Consumer;

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import { AWSError } from './types';
 declare class SQSError extends Error {
     code: string;
     statusCode: number;
@@ -10,4 +11,15 @@ declare class SQSError extends Error {
 declare class TimeoutError extends Error {
     constructor(message?: string);
 }
-export { SQSError, TimeoutError };
+/**
+ * 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 that the error occurred on.
+ */
+declare function toSQSError(err: AWSError, message: string): SQSError;
+export { SQSError, TimeoutError, isConnectionError, toSQSError };

package/dist/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TimeoutError = exports.SQSError = void 0;
+exports.toSQSError = exports.isConnectionError = exports.TimeoutError = exports.SQSError = void 0;
 class SQSError extends Error {
     constructor(message) {
         super(message);
@@ -16,3 +16,34 @@ class TimeoutError extends Error {
     }
 }
 exports.TimeoutError = TimeoutError;
+/**
+ * Checks if the error provided should be treated as a connection error.
+ * @param err The error that was received.
+ */
+function isConnectionError(err) {
+    if (err instanceof SQSError) {
+        return (err.statusCode === 403 ||
+            err.code === 'CredentialsError' ||
+            err.code === 'UnknownEndpoint' ||
+            err.code === 'AWS.SimpleQueueService.NonExistentQueue');
+    }
+    return false;
+}
+exports.isConnectionError = isConnectionError;
+/**
+ * Formats an AWSError the the SQSError type.
+ * @param err The error object that was received.
+ * @param message The message that the error occurred on.
+ */
+function toSQSError(err, message) {
+    var _a, _b;
+    const sqsError = new SQSError(message);
+    sqsError.code = err.name;
+    sqsError.statusCode = (_a = err.$metadata) === null || _a === void 0 ? void 0 : _a.httpStatusCode;
+    sqsError.retryable = (_b = err.$retryable) === null || _b === void 0 ? void 0 : _b.throttling;
+    sqsError.service = err.$service;
+    sqsError.fault = err.$fault;
+    sqsError.time = new Date();
+    return sqsError;
+}
+exports.toSQSError = toSQSError;