AWS.SQS reference

CancelMessageMoveTask

Source: src/AWS/SQS/CancelMessageMoveTask.ts

Runtime binding for sqs:CancelMessageMoveTask (dead-letter queue redrive).

Bind this operation to the dead-letter Queue whose move task should be cancellable. Cancellation only stops messages that have not been moved yet; a task that already finished fails with the typed ResourceNotFoundException. The binding grants the host function sqs:CancelMessageMoveTask on the queue. Provide the CancelMessageMoveTaskHttp layer on the Function to implement the binding.

CancelMessageMoveTask: Dead-Letter Queue Redrive

// init (provide SQS.CancelMessageMoveTaskHttp on the Function)
const cancelMessageMoveTask = yield* SQS.CancelMessageMoveTask(dlq);

// runtime
yield* cancelMessageMoveTask({ TaskHandle: taskHandle });

ChangeMessageVisibility

Source: src/AWS/SQS/ChangeMessageVisibility.ts

Runtime binding for sqs:ChangeMessageVisibility.

Bind this operation to a Queue inside a function runtime to extend or shrink the visibility timeout of an in-flight message — e.g. extend it while a slow job is still processing, or set it to 0 to release the message back to the queue immediately. The binding grants the host function sqs:ChangeMessageVisibility on the queue. Provide the ChangeMessageVisibilityHttp layer on the Function to implement the binding.

ChangeMessageVisibility: Changing Message Visibility

Release a Message Back to the Queue

// init (provide SQS.ChangeMessageVisibilityHttp on the Function)
const changeMessageVisibility = yield* SQS.ChangeMessageVisibility(queue);

// runtime: make the message immediately receivable again
yield* changeMessageVisibility({
  ReceiptHandle: message.ReceiptHandle!,
  VisibilityTimeout: 0,
});

Extend Processing Time for a Slow Job

yield* changeMessageVisibility({
  ReceiptHandle: message.ReceiptHandle!,
  VisibilityTimeout: 600,
});

ChangeMessageVisibilityBatch

Source: src/AWS/SQS/ChangeMessageVisibilityBatch.ts

Runtime binding for sqs:ChangeMessageVisibilityBatch.

Bind this operation to a Queue inside a function runtime to change the visibility timeout of up to 10 in-flight messages per call with per-entry success/failure results. The binding grants the host function sqs:ChangeMessageVisibility on the queue. Provide the ChangeMessageVisibilityBatchHttp layer on the Function to implement the binding.

ChangeMessageVisibilityBatch: Changing Message Visibility

// init (provide SQS.ChangeMessageVisibilityBatchHttp on the Function)
const changeMessageVisibilityBatch =
  yield* SQS.ChangeMessageVisibilityBatch(queue);

// runtime
const result = yield* changeMessageVisibilityBatch({
  Entries: messages.map((message, index) => ({
    Id: `${index}`,
    ReceiptHandle: message.ReceiptHandle!,
    VisibilityTimeout: 0,
  })),
});
// result.Successful / result.Failed

DeleteMessage

Source: src/AWS/SQS/DeleteMessage.ts

Runtime binding for sqs:DeleteMessage.

Bind this operation to a Queue inside a function runtime to delete a message after it has been received and processed. The binding grants the host function sqs:DeleteMessage on the queue. Provide the DeleteMessageHttp layer on the Function to implement the binding.

DeleteMessage: Deleting Messages

// init (provide SQS.DeleteMessageHttp on the Function)
const deleteMessage = yield* SQS.DeleteMessage(queue);

// runtime: acknowledge a message received via ReceiveMessage
const result = yield* receiveMessage({ MaxNumberOfMessages: 1 });
const [message] = result.Messages ?? [];
if (message?.ReceiptHandle) {
  yield* deleteMessage({ ReceiptHandle: message.ReceiptHandle });
}

DeleteMessageBatch

Source: src/AWS/SQS/DeleteMessageBatch.ts

Runtime binding for sqs:DeleteMessageBatch.

Bind this operation to a Queue inside a function runtime to delete up to 10 received messages per call with per-entry success/failure results. The binding grants the host function sqs:DeleteMessage on the queue. Provide the DeleteMessageBatchHttp layer on the Function to implement the binding.

DeleteMessageBatch: Deleting Message Batches

// init (provide SQS.DeleteMessageBatchHttp on the Function)
const deleteMessageBatch = yield* SQS.DeleteMessageBatch(queue);

// runtime: acknowledge messages received via ReceiveMessage
const result = yield* deleteMessageBatch({
  Entries: messages.map((message, index) => ({
    Id: `${index}`,
    ReceiptHandle: message.ReceiptHandle!,
  })),
});
// result.Successful / result.Failed

GetQueueAttributes

Source: src/AWS/SQS/GetQueueAttributes.ts

Runtime binding for sqs:GetQueueAttributes.

Bind this operation to a Queue inside a function runtime to read live queue attributes — e.g. ApproximateNumberOfMessages for queue-depth monitoring or backpressure decisions. The binding grants the host function sqs:GetQueueAttributes on the queue. Provide the GetQueueAttributesHttp layer on the Function to implement the binding.

GetQueueAttributes: Reading Queue Attributes

// init (provide SQS.GetQueueAttributesHttp on the Function)
const getQueueAttributes = yield* SQS.GetQueueAttributes(queue);

// runtime
const result = yield* getQueueAttributes({
  AttributeNames: ["ApproximateNumberOfMessages"],
});
const depth = Number(result.Attributes?.ApproximateNumberOfMessages ?? 0);

ListDeadLetterSourceQueues

Source: src/AWS/SQS/ListDeadLetterSourceQueues.ts

Runtime binding for sqs:ListDeadLetterSourceQueues.

Bind this operation to a dead-letter Queue inside a function runtime to enumerate the source queues whose redrivePolicy targets it. The binding grants the host function sqs:ListDeadLetterSourceQueues on the queue. Provide the ListDeadLetterSourceQueuesHttp layer on the Function to implement the binding.

ListDeadLetterSourceQueues: Dead-Letter Queue Redrive

// init (provide SQS.ListDeadLetterSourceQueuesHttp on the Function)
const listDeadLetterSourceQueues =
  yield* SQS.ListDeadLetterSourceQueues(dlq);

// runtime
const result = yield* listDeadLetterSourceQueues();
// result.queueUrls: URLs of every queue using `dlq` as its DLQ

ListMessageMoveTasks

Source: src/AWS/SQS/ListMessageMoveTasks.ts

Runtime binding for sqs:ListMessageMoveTasks (dead-letter queue redrive).

Bind this operation to a dead-letter Queue inside a function runtime to inspect the most recent message move tasks (up to 10) whose source is that queue — including their status, progress counters, and TaskHandle for cancellation. The binding grants the host function sqs:ListMessageMoveTasks on the queue. Provide the ListMessageMoveTasksHttp layer on the Function to implement the binding.

ListMessageMoveTasks: Dead-Letter Queue Redrive

// init (provide SQS.ListMessageMoveTasksHttp on the Function)
const listMessageMoveTasks = yield* SQS.ListMessageMoveTasks(dlq);

// runtime
const result = yield* listMessageMoveTasks();
for (const task of result.Results ?? []) {
  // task.Status, task.ApproximateNumberOfMessagesMoved, task.TaskHandle
}

PurgeQueue

Source: src/AWS/SQS/PurgeQueue.ts

Runtime binding for sqs:PurgeQueue.

Bind this operation to a Queue inside a function runtime to delete every message in the queue in one call. The purge takes up to 60 seconds to complete, and only one purge per queue is allowed every 60 seconds (a second call fails with the typed PurgeQueueInProgress error). The binding grants the host function sqs:PurgeQueue on the queue. Provide the PurgeQueueHttp layer on the Function to implement the binding.

PurgeQueue: Purging a Queue

// init (provide SQS.PurgeQueueHttp on the Function)
const purgeQueue = yield* SQS.PurgeQueue(queue);

// runtime: drop everything currently in the queue
yield* purgeQueue();

Queue

Source: src/AWS/SQS/Queue.ts

An Amazon SQS queue for reliable, decoupled message processing.

Queue owns the lifecycle of a standard or FIFO SQS queue. A queue name is auto-generated from the app, stage, and logical ID unless you provide one explicitly. The .fifo suffix follows the fifo setting, including for explicit names. Changing queue mode replaces the physical queue and updates downstream references; existing messages are not migrated.

queueName and fifo must be known before the queue is precreated; unresolved resource outputs in these identity properties fail with UnresolvedQueueIdentity. Mutable settings and policy bindings may reference other resource outputs, including the queue’s own ARN.

Queue: Creating Queues

Standard Queue

import * as SQS from "alchemy/AWS/SQS";

const queue = yield* SQS.Queue("OrdersQueue");

FIFO Queue

const queue = yield* SQS.Queue("OrdersFifoQueue", {
  fifo: true,
  contentBasedDeduplication: true,
});

Queue with Custom Settings

const queue = yield* SQS.Queue("ProcessingQueue", {
  visibilityTimeout: "2 minutes",
  messageRetentionPeriod: "1 day",
  receiveMessageWaitTime: "20 seconds",
});

Queue: Adopting an Existing Queue

import * as Alchemy from "alchemy";
import * as SQS from "alchemy/AWS/SQS";

const audit = yield* SQS.Queue("Audit");
const orders = yield* SQS.Queue("Orders", {
  queueName: "existing-orders",
  tags: { auditQueue: audit.queueArn },
}).pipe(Alchemy.adopt(true));

Explicit adoption preserves the queue identity and messages while reconciling settings, policies, and tags, even when mutable properties depend on other resources.

Queue: Dead-Letter Queues

Route failures to a dead-letter queue

const dlq = yield* SQS.Queue("OrdersDLQ");
const orders = yield* SQS.Queue("Orders", {
  redrivePolicy: {
    deadLetterTargetArn: dlq.queueArn,
    maxReceiveCount: 3,
  },
});

Authorize source queues on the dead-letter queue

const dlq = yield* SQS.Queue("OrdersDLQ", {
  redriveAllowPolicy: {
    redrivePermission: "byQueue",
    sourceQueueArns: [orders.queueArn],
  },
});

Queue: Encryption

SSE-SQS (SQS-managed keys)

const queue = yield* SQS.Queue("SecureQueue", {
  sqsManagedSseEnabled: true,
});

SSE-KMS (AWS-managed key)

const queue = yield* SQS.Queue("KmsQueue", {
  kmsMasterKeyId: "alias/aws/sqs",
  kmsDataKeyReusePeriod: "5 minutes",
});

Queue: Sending Messages

Bind send operations in the init phase and use them in runtime handlers.

// init
const sendMessage = yield* SQS.SendMessage(queue);

return {
  fetch: Effect.gen(function* () {
    // runtime
    yield* sendMessage({
      MessageBody: JSON.stringify({ orderId: "123" }),
    });
    return HttpServerResponse.text("Queued");
  }),
};

Queue: Event Sources

Process messages from a queue using a Lambda event source mapping. Messages are automatically deleted after successful processing.

// init
yield* SQS.consumeQueueMessages(queue,
  Effect.fn(function* (message) {
    yield* Effect.log(`Received: ${message.body}`);
  }),
);

QueueEventSource

Source: src/AWS/SQS/QueueEventSource.ts

Event source connecting an SQS Queue to the hosting compute (Lambda function or ServerHost process).

The contract is a Binding.Service; the host-specific implementation layers are Lambda.QueueEventSource (event-source mapping + runtime dispatch) and Server.SQSQueueEventSource (long-poll receive loop). Consume it through the consumeQueueMessages helper.

QueueEventSource: Consuming a Queue

export default WorkerFunction.make(
  { main: import.meta.url },
  Effect.gen(function* () {
    const queue = yield* SQS.Queue("Jobs");

    // registers the event-source mapping and the runtime dispatcher
    yield* SQS.consumeQueueMessages(queue, { batchSize: 10 }, (records) =>
      records.pipe(
        Stream.runForEach((record) => Effect.log(record.body)),
      ),
    );
  }).pipe(Effect.provide(Lambda.QueueEventSource)),
);

QueueSink

Source: src/AWS/SQS/QueueSink.ts

A batching sink over SQS SendMessageBatch (10 entries / 256 KiB per call). Per-entry failures with SenderFault: false (throttling, internal errors) are retried on a bounded schedule; SenderFault: true failures are permanent and dropped. Exhausting retries fails the sink with a typed BatchRetryExhaustedError carrying the stranded entries.

The binding grants the host function sqs:SendMessage and sqs:SendMessageBatch on the queue. Provide the QueueSinkHttp layer (which itself needs SendMessageBatchHttp) on the Function to implement the binding.

QueueSink: Streaming Messages into a Queue

Run a Stream into a Queue

// init (provide SQS.QueueSinkHttp + SQS.SendMessageBatchHttp on the Function)
const sink = yield* SQS.QueueSink(queue);

// runtime: batching, size limits, and transient-failure retry are handled
// by the sink — each element is a SendMessageBatchRequestEntry minus `Id`.
yield* Stream.fromIterable(messages).pipe(
  Stream.map((message) => ({ MessageBody: message })),
  Stream.run(sink),
);

Forward Event-Source Records into a Result Queue

const sink = yield* SQS.QueueSink(resultQueue);

yield* SQS.consumeQueueMessages(sourceQueue, (records) =>
  records.pipe(
    Stream.map((record) => ({ MessageBody: record.body })),
    Stream.run(sink),
    Effect.orDie,
  ),
);

ReceiveMessage

Source: src/AWS/SQS/ReceiveMessage.ts

Runtime binding for sqs:ReceiveMessage.

Bind this operation to a Queue inside a function runtime to poll messages on demand. The binding grants the host function sqs:ReceiveMessage on the queue. Provide the ReceiveMessageHttp layer on the Function to implement the binding.

For push-based consumption (Lambda event-source mapping) use consumeQueueMessages instead of polling manually.

ReceiveMessage: Receiving Messages

// init (provide SQS.ReceiveMessageHttp on the Function)
const receiveMessage = yield* SQS.ReceiveMessage(queue);

// runtime: long-poll for up to 10 messages
const result = yield* receiveMessage({
  MaxNumberOfMessages: 10,
  WaitTimeSeconds: 2,
});
for (const message of result.Messages ?? []) {
  // message.Body, message.ReceiptHandle
}

SendMessage

Source: src/AWS/SQS/SendMessage.ts

Runtime binding for sqs:SendMessage.

Bind this operation to a Queue inside a function runtime to get a callable that automatically injects the QueueUrl. The binding grants the host function sqs:SendMessage on the queue. Provide the SendMessageHttp layer on the Function to implement the binding.

SendMessage: Sending Messages

Send a Message from a Lambda Function

export class ApiFunction extends Lambda.Function<Lambda.Function>()(
  "ApiFunction",
) {}

export default ApiFunction.make(
  { main: import.meta.url, functionUrl: true },
  Effect.gen(function* () {
    const queue = yield* SQS.Queue("Jobs");

    // init: bind the operation to the queue (grants sqs:SendMessage)
    const sendMessage = yield* SQS.SendMessage(queue);

    return {
      fetch: Effect.gen(function* () {
        // runtime: QueueUrl is injected automatically
        const result = yield* sendMessage({ MessageBody: "hello" });
        return yield* HttpServerResponse.json({
          messageId: result.MessageId,
        });
      }).pipe(Effect.orDie),
    };
  }).pipe(Effect.provide(SQS.SendMessageHttp)),
);

Delay Delivery

yield* sendMessage({ MessageBody: "process later", DelaySeconds: 60 });

SendMessageBatch

Source: src/AWS/SQS/SendMessageBatch.ts

Runtime binding for sqs:SendMessageBatch.

Bind this operation to a Queue inside a function runtime to send up to 10 messages per call with per-entry success/failure results. The binding grants the host function sqs:SendMessage on the queue. Provide the SendMessageBatchHttp layer on the Function to implement the binding.

For an unbounded stream of messages with automatic batching and bounded retry of transient per-entry failures, prefer QueueSink.

SendMessageBatch: Sending Message Batches

// init (provide SQS.SendMessageBatchHttp on the Function)
const sendMessageBatch = yield* SQS.SendMessageBatch(queue);

// runtime
const result = yield* sendMessageBatch({
  Entries: messages.map((body, index) => ({
    Id: `${index}`,
    MessageBody: body,
  })),
});
// result.Successful / result.Failed

StartMessageMoveTask

Source: src/AWS/SQS/StartMessageMoveTask.ts

Runtime binding for sqs:StartMessageMoveTask (dead-letter queue redrive).

Bind this operation to a dead-letter Queue (the redrive source) inside a function runtime to start moving its messages. Redrive requires more than the start permission alone, so the binding grants the host function sqs:StartMessageMoveTask, sqs:ReceiveMessage, sqs:DeleteMessage, and sqs:GetQueueAttributes on the source queue.

Pass a destination Queue at bind time to redrive into a specific queue (grants sqs:SendMessage + sqs:GetQueueAttributes on it and injects its ARN as DestinationArn). Without a destination, messages are redriven to their original source queues — which requires sqs:SendMessage on those queues, so the binding grants sqs:SendMessage on * in that mode.

Provide the StartMessageMoveTaskHttp layer on the Function to implement the binding.

StartMessageMoveTask: Dead-Letter Queue Redrive

Redrive a DLQ into a Specific Queue

// init (provide SQS.StartMessageMoveTaskHttp on the Function)
const startMessageMoveTask = yield* SQS.StartMessageMoveTask(dlq, {
  destination: ordersQueue,
});

// runtime
const { TaskHandle } = yield* startMessageMoveTask();

Rate-Limited Redrive

yield* startMessageMoveTask({ MaxNumberOfMessagesPerSecond: 10 });