SQS Consumer
    Preparing search index...

    Interface ConsumerOptions

    The options for the consumer.

    interface ConsumerOptions {
        queueUrl: string;
        alwaysAcknowledge?: boolean;
        attributeNames?: QueueAttributeName[];
        authenticationErrorTimeout?: number;
        batchSize?: number;
        extendedAWSErrors?: boolean;
        handleMessageTimeout?: number;
        heartbeatInterval?: number;
        messageAttributeNames?: string[];
        messageSystemAttributeNames?: MessageSystemAttributeName[];
        pollingCompleteWaitTimeMs?: number;
        pollingWaitTimeMs?: number;
        region?: string;
        shouldDeleteMessages?: boolean;
        sqs?: SQSClient;
        strictReturn?: boolean;
        suppressFifoWarning?: boolean;
        terminateVisibilityTimeout?:
            | number
            | boolean
            | ((messages: Message[]) => number);
        useQueueUrlAsEndpoint?: boolean;
        visibilityTimeout?: number;
        waitTimeSeconds?: number;
        handleMessage?(message: Message): Promise<Message>;
        handleMessageBatch?(messages: Message[]): Promise<Message[]>;
        postReceiveMessageCallback?(): Promise<void>;
        preReceiveMessageCallback?(): Promise<void>;
    }
    Index

    Properties

    queueUrl alwaysAcknowledge? attributeNames? authenticationErrorTimeout? batchSize? extendedAWSErrors? handleMessageTimeout? heartbeatInterval? messageAttributeNames? messageSystemAttributeNames? pollingCompleteWaitTimeMs? pollingWaitTimeMs? region? shouldDeleteMessages? sqs? strictReturn? suppressFifoWarning? terminateVisibilityTimeout? useQueueUrlAsEndpoint? visibilityTimeout? waitTimeSeconds?

    Methods

    handleMessage? handleMessageBatch? postReceiveMessageCallback? preReceiveMessageCallback?

    Properties

    queueUrl: string

    The SQS queue URL.

    alwaysAcknowledge?: 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.

    false

    attributeNames?: QueueAttributeName[]

    List of queue attributes to retrieve, see AWS docs.

    []

    authenticationErrorTimeout?: number

    The duration (in milliseconds) to wait before retrying after an authentication error.

    10000

    batchSize?: number

    The number of messages to request from SQS when polling (default 1).

    This cannot be higher than the AWS limit of 10.

    1

    extendedAWSErrors?: boolean

    Set this to true if you want to receive additional information about the error that occurred from AWS, such as the response and metadata.

    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.

    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.

    messageAttributeNames?: string[]

    List of message attributes to retrieve (i.e. ['name', 'address']).

    []

    messageSystemAttributeNames?: MessageSystemAttributeName[]

    A list of attributes that need to be returned along with each message.

    []

    pollingCompleteWaitTimeMs?: 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.

    0

    pollingWaitTimeMs?: number

    The duration (in milliseconds) to wait before repolling the queue.

    0

    region?: string

    The AWS region.

    process.env.AWS_REGION || eu-west-1

    shouldDeleteMessages?: boolean

    Default to true, if you don't want the package to delete messages from sqs set this to false.

    true

    sqs?: SQSClient

    An optional SQS Client object to use if you need to configure the client manually.

    strictReturn?: boolean

    Set this to true if you want to enforce that message handlers must return a value. When enabled, handlers that return null will throw an error instead of treating it as "do not acknowledge".

    false

    This option will be turned on by default in a future release.

    suppressFifoWarning?: boolean

    Set this to true if you want to suppress the warning about FIFO queues.

    false

    terminateVisibilityTimeout?:
        | number
        | boolean
        | ((messages: Message[]) => number)

    If true, sets the message visibility timeout to 0 after a processing_error. You can also specify a different timeout using a number. If you would like to use exponential backoff, you can pass a function that returns a number and it will use that as the value for the timeout.

    false

    useQueueUrlAsEndpoint?: boolean

    Set this value to false to ignore the queueUrl and use the client's resolved endpoint, which may be a custom endpoint.

    true

    visibilityTimeout?: number

    The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a ReceiveMessage request.

    waitTimeSeconds?: number

    The duration (in seconds) for which the call will wait for a message to arrive in the queue before returning.

    20

    Methods

    • An async function (or function that returns a Promise) to be called whenever a message is received.

      Message Acknowledgment Behavior:

      • Returning undefined will NOT acknowledge the message (leaves it on queue for retry)
      • Returning the original message or a processed message will cause the message to be acknowledged and deleted
      • To explicitly acknowledge a specific message, return an object containing the MessageId you want to acknowledge

      Important: If alwaysAcknowledge is true, all messages will be acknowledged regardless of return value.

      Parameters

      • message: Message

      Returns Promise<Message>

      Returning void is discouraged and will be deprecated in a future release. Please return a Message or undefined.

    • 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.

      Message Acknowledgment Behavior:

      • Returning undefined will NOT acknowledge any messages (leaves them on queue for retry)
      • Returning the original message array or a processed array will cause all messages to be acknowledged and deleted
      • To prevent acknowledgment of all messages, return undefined or an empty array []
      • To selectively acknowledge messages, return an array containing only the messages you want to acknowledge

      Important: If alwaysAcknowledge is true, all messages will be acknowledged regardless of return value.

      Parameters

      • messages: Message[]

      Returns Promise<Message[]>

      Returning void is discouraged and will be deprecated in a future release. Please return an array of Messages or undefined.

    • 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.

      Returns Promise<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.

      Returns Promise<void>

    Settings

    Member Visibility

    On This Page

    Properties
    Methods