sqs-producer

The producer.send() method allows you to enqueue messages. You can pass an array of strings (where the string is the body) or an array of message objects for more control.

Supported message object properties:

• id: A unique identifier (defaults to the body if not provided).
• body: The message content.
• delaySeconds: A number between 0 and 900 to delay the message.
• messageAttributes: An object containing metadata (e.g., String or Binary).
• groupId: Required for FIFO queues or for implementing fair queue behavior in standard queues.
• deduplicationId: Required for FIFO queues (unless content-based deduplication is enabled).

// Send simple strings
await producer.send(["msg1", "msg2"]);

// Send complex message objects
await producer.send([
  {
    id: "id1",
    body: "Hello world",
    messageAttributes: {
      attr1: { DataType: "String", StringValue: "stringValue" },
      attr2: { DataType: "Binary", BinaryValue: new Buffer("binaryValue") },
    },
  },
  {
    id: "id2",
    body: "Delayed message",
    delaySeconds: 5,
  },
]);

// Send to a FIFO queue
await producer.send({
  id: "testId",
  body: "FIFO message",
  groupId: "group1234",
  deduplicationId: "abcdef123456",
});

When initializing the producer, you provide a ProducerOptions object to configure the target queue and the AWS client behavior.

Key configuration options include:

• queueUrl (required): The URL of the SQS queue.
• batchSize (optional): The number of messages to send in a single batch.
• sqs (optional): An existing SQSClient instance. If omitted, a new client is created.
• region (optional): The AWS region. Defaults to eu-west-1 if not provided or found in the AWS_REGION environment variable.
• useQueueUrlAsEndpoint (optional): If true (default), the queueUrl is used as the request endpoint. Set to false to use the client's resolved endpoint (useful for custom endpoints).

import { SQSClient } from "@aws-sdk/client-sqs";

const options: ProducerOptions = {
  queueUrl: "https://sqs.eu-west-1.amazonaws.com/123456789012/my-queue",
  batchSize: 10,
  region: "eu-west-1",
  sqs: new SQSClient({ region: "eu-west-1" })
};

To use sqs-producer, instantiate the Producer class or use the Producer.create() static method. You must provide a queueUrl.

Optional configuration includes:

• batchSize: The number of messages to send in each SQS batch (defaults to 10). Must be between 1 and 10.
• sqs: An existing instance of SQSClient from @aws-sdk/client-sqs. If not provided, a new client is created.
• region: The AWS region (defaults to eu-west-1 or process.env.AWS_REGION).
• useQueueUrlAsEndpoint: Determines if the queueUrl should be used as the endpoint (defaults to true).
• Any other valid options for the AWS SDK SQSClient can be passed in the options object.

import { Producer } from 'sqs-producer';

// Using the static create method
const producer = Producer.create({
  queueUrl: 'https://sqs.eu-west-1.amazonaws.com/123456789012/my-queue',
  batchSize: 5,
  region: 'eu-west-1'
});

// Or using the constructor
const producerAlt = new Producer({
  queueUrl: 'https://sqs.eu-west-1.amazonaws.com/123456789012/my-queue'
});

The send() method allows you to dispatch messages to your SQS queue. It accepts a single string, a single Message object, or an array containing both strings and Message objects.

Internally, the producer automatically handles batching based on the batchSize configured during initialization. If you provide more messages than the batchSize, the producer will recursively send multiple batches until all messages are processed.

Returns: A promise that resolves to an array of SendMessageBatchResultEntry[] representing the successful messages.

Errors: If any messages in the batch fail to send, the method throws a FailedMessagesError containing the IDs of the failed messages.

// Sending a single string message
await producer.send('hello world');

// Sending an array of mixed strings and Message objects
await producer.send([
  'message one',
  { id: 'msg-2', body: 'message two' },
  { id: 'msg-3', body: 'message three' }
]);