sqs-consumer 6.1.0 → 6.2.0

package/src/errors.ts

@@ -1,3 +1,5 @@
+import { AWSError } from './types';
+
 class SQSError extends Error {
   code: string;
   statusCode: number;
@@ -20,4 +22,37 @@ class TimeoutError extends Error {
   }
 }
 
-export { SQSError, TimeoutError };
+/**
+ * Checks if the error provided should be treated as a connection error.
+ * @param err The error that was received.
+ */
+function isConnectionError(err: Error): boolean {
+  if (err instanceof SQSError) {
+    return (
+      err.statusCode === 403 ||
+      err.code === 'CredentialsError' ||
+      err.code === 'UnknownEndpoint' ||
+      err.code === 'AWS.SimpleQueueService.NonExistentQueue'
+    );
+  }
+  return false;
+}
+
+/**
+ * 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: AWSError, message: string): SQSError {
+  const sqsError = new SQSError(message);
+  sqsError.code = err.name;
+  sqsError.statusCode = err.$metadata?.httpStatusCode;
+  sqsError.retryable = err.$retryable?.throttling;
+  sqsError.service = err.$service;
+  sqsError.fault = err.$fault;
+  sqsError.time = new Date();
+
+  return sqsError;
+}
+
+export { SQSError, TimeoutError, isConnectionError, toSQSError };

package/src/types.ts

@@ -1,36 +1,181 @@
 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 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 {
+    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<E extends keyof Events>(
+    event: E,
+    listener: (...args: Events[E]) => void
+  ): this {
+    return super.on(event, listener);
+  }
+  /**
+   * 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 {
+    return super.emit(event, ...args);
+  }
+}
+
 export type AWSError = {
   /**
    * Name, eg. ConditionalCheckFailedException

package/src/validation.ts

@@ -0,0 +1,45 @@
+import { ReceiveMessageCommandOutput } from '@aws-sdk/client-sqs';
+
+import { ConsumerOptions } from './types';
+
+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: ConsumerOptions): void {
+  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.');
+  }
+}
+
+/**
+ * Determine if the response from SQS has messages in it.
+ * @param response The response from SQS.
+ */
+function hasMessages(response: ReceiveMessageCommandOutput): boolean {
+  return response.Messages && response.Messages.length > 0;
+}
+
+export { hasMessages, assertOptions };

package/typedoc.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "sort": ["kind", "instance-first", "required-first", "alphabetical"],
+  "treatWarningsAsErrors": false,
+  "searchInComments": true,
+  "entryPoints": ["./src/index.ts"],
+  "out": "public",
+  "name": "SQS Consumer",
+  "hideGenerator": true,
+  "navigationLinks": {
+    "GitHub": "https://github.com/bbc/sqs-consumer"
+  }
+}