@composurecdk/sqs 0.8.7 → 0.9.0

package/README.md

@@ -4,23 +4,109 @@ SQS queue builder for [ComposureCDK](../../README.md).
 
 This package provides a fluent builder for SQS queues with secure, AWS-recommended defaults and built-in CloudWatch alarms. It wraps the CDK [Queue](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sqs.Queue.html) construct — refer to the CDK documentation for the full set of configurable properties.
 
-## Queue Builder
+## Queue roles
+
+`createQueueBuilder(role?)` is the single entry point for every queue type. The role selects the builder's **typed prop surface** (props that don't apply to a role don't exist on its builder), its defaults, its recommended-alarm profile, and its build-time validation:
+
+| Role                   | Queue type            | Surface & behaviour                                                                                              |
+| ---------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `"standard"` (default) | Standard, primary     | FIFO-only props excluded from the type (and rejected at build).                                                  |
+| `"fifo"`               | FIFO, primary         | `fifo: true` always; `queueName` typed to require the `.fifo` suffix; high-throughput mode validated.            |
+| `"dlq"`                | Standard, dead-letter | 14-day retention; inverted alarm set (any message alerts); `deadLetterQueue` excluded — a DLQ is terminal.       |
+| `"fifo-dlq"`           | FIFO, dead-letter     | The FIFO surface combined with the DLQ defaults and alarms — AWS requires a FIFO source's DLQ to itself be FIFO. |
+
+Every role shares the same [secure defaults](#secure-defaults), the same `Lifecycle`/`compose` integration, the same `addAlarm` escape hatch, and the same `QueueBuilderResult` shape. The role is ordinary builder state: `.copy()` preserves it, and adding a future role is a new table entry, not a new entry point.
 
 ```ts
 import { Duration } from "aws-cdk-lib";
 import { createQueueBuilder } from "@composurecdk/sqs";
 
-const orders = createQueueBuilder()
+const orders = createQueueBuilder() // "standard"
   .queueName("orders")
   .visibilityTimeout(Duration.seconds(60))
   .build(stack, "Orders");
 ```
 
-Every [QueueProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sqs.QueueProps.html) property is available as a fluent setter on the builder. FIFO queues are supported via the standard `fifo`, `contentBasedDeduplication`, and `fifoThroughputLimit` props — no FIFO-specific defaults are applied.
+## FIFO queues (`"fifo"`)
+
+```ts
+import { DeduplicationScope, FifoThroughputLimit } from "aws-cdk-lib/aws-sqs";
+
+const orderEvents = createQueueBuilder("fifo")
+  .queueName("order-events.fifo") // type requires the `.fifo` suffix
+  .contentBasedDeduplication(true)
+  .build(stack, "OrderEvents");
+
+// High-throughput FIFO — the dedup scope pairing is validated at build.
+const highTps = createQueueBuilder("fifo")
+  .queueName("order-events-ht.fifo")
+  .fifoThroughputLimit(FifoThroughputLimit.PER_MESSAGE_GROUP_ID)
+  .deduplicationScope(DeduplicationScope.MESSAGE_GROUP)
+  .build(stack, "OrderEventsHt");
+```
+
+FIFO-aware behaviour:
+
+- **`fifo: true` always.** The prop is not settable; the role is the switch.
+- **`queueName` is typed `` `${string}.fifo` ``** — AWS requires the suffix, so a bad name fails at compile time instead of synth. Omit the name to let CloudFormation generate a valid one.
+- **High-throughput coherence**: `fifoThroughputLimit: PER_MESSAGE_GROUP_ID` without `deduplicationScope: MESSAGE_GROUP` throws at build ([high-throughput FIFO](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/high-throughput-fifo.html)).
+- **Redrive type match**: a FIFO queue redriving to a standard DLQ (or vice versa) throws at build — AWS rejects the mismatch at deploy time otherwise.
+- **Alarms**: same set and thresholds as a standard queue. Since [November 2024](https://aws.amazon.com/about-aws/whats-new/2024/11/amazon-sqs-increases-in-flight-limit-fifo-queues/) FIFO queues share the standard 120,000 in-flight quota, so the in-flight threshold applies unchanged. FIFO throughput ceilings (300 TPS, or 3,000 with high-throughput mode) have no dedicated CloudWatch metric — if you need a "throughput wall" signal, add a custom alarm on `NumberOfMessagesSent` via `addAlarm`.
+
+## Dead-letter queues (`"dlq"`, `"fifo-dlq"`)
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+
+const system = compose(
+  {
+    ordersDlq: createQueueBuilder("dlq"),
+    orders: createQueueBuilder().deadLetterQueue(
+      ref("ordersDlq", (r) => ({ queue: r.queue, maxReceiveCount: 5 })),
+    ),
+  },
+  { ordersDlq: [], orders: ["ordersDlq"] },
+);
+
+// A FIFO primary requires a FIFO DLQ — one role, not a prop combination:
+const orderEventsDlq = createQueueBuilder("fifo-dlq")
+  .queueName("order-events-dlq.fifo")
+  .build(stack, "OrderEventsDlq");
+```
+
+DLQ-specific behaviour:
+
+| Property          | Default             | Rationale                                                                                                                                                                    |
+| ----------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `retentionPeriod` | `Duration.days(14)` | The SQS maximum. A DLQ exists to give operators a window to investigate and redrive failed messages — maximizing that window is the point. Exported as `DLQ_QUEUE_DEFAULTS`. |
+
+- **`deadLetterQueue` is excluded** from the type (and rejected at build): a DLQ is the terminal destination for failed messages. A queue with its own redrive policy is a primary queue.
+- Consider restricting which queues may redrive into the DLQ via `.redriveAllowPolicy(...)`.
+
+### DLQ alarms
+
+The recommended-alarm set inverts relative to a primary queue — the defaults are exported as `DLQ_ALARM_DEFAULTS`:
+
+| Alarm                                   |   Default on a DLQ    | Rationale                                                                                                                                                                                                                                                           |
+| --------------------------------------- | :-------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `approximateNumberOfMessagesVisible`    |       ✅ (> 0)        | Any message on a DLQ indicates a delivery failure that needs investigation.                                                                                                                                                                                         |
+| `approximateAgeOfOldestMessage`         | ✅ (75% of retention) | Nothing consumes a DLQ, so "consumer falling behind" is meaningless — instead this is the last call to investigate before SQS silently deletes the message at `retentionPeriod`. The threshold scales with the queue's actual retention (75% of `retentionPeriod`). |
+| `approximateNumberOfMessagesNotVisible` |          ❌           | Nothing is normally in flight on a DLQ. Opt back in via `recommendedAlarms` if you have a reason to watch it.                                                                                                                                                       |
+
+Every entry is individually overridable through the same `recommendedAlarms` API used for primary queues:
+
+```ts
+const ordersDlq = createQueueBuilder("dlq")
+  .recommendedAlarms({
+    approximateNumberOfMessagesVisible: { threshold: 5 }, // alert only once a small backlog builds
+    approximateAgeOfOldestMessage: false, // rely on the visible-messages alarm alone
+  })
+  .build(stack, "OrdersDlq");
+```
 
 ## Secure Defaults
 
-`createQueueBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+Every role applies the following defaults. Each can be overridden via the builder's fluent API.
 
 | Property                 | Default                       | Rationale                                                                                                                                                                                                                                                             |
 | ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -28,12 +114,12 @@ Every [QueueProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s
 | `encryption`             | `QueueEncryption.SQS_MANAGED` | Encrypts at rest with the SQS-managed key (SSE-SQS). KMS encryption is opt-in via `.encryption(QueueEncryption.KMS)` + `.encryptionMasterKey(key)`. ([SQS data protection](https://docs.aws.amazon.com/AmazonSQS/latest/SQSDeveloperGuide/sqs-data-protection.html))  |
 | `receiveMessageWaitTime` | `Duration.seconds(20)`        | Enables [long polling](https://docs.aws.amazon.com/AmazonSQS/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html#sqs-long-polling) — fewer empty receives, lower cost, lower latency. 20s is the SQS maximum.                                                    |
 
-`visibilityTimeout` is intentionally not defaulted — it must match the longest consumer processing time, which is workload-specific. `retentionPeriod` is also left at CDK's default of 4 days; bump it to 14 days if you need a longer replay window.
+`visibilityTimeout` is intentionally not defaulted — it must match the longest consumer processing time, which is workload-specific. `retentionPeriod` is left at CDK's default of 4 days on the primary roles (the dead-letter roles raise it to 14 days, see above).
 
-The defaults are exported as `QUEUE_DEFAULTS` for visibility and testing:
+The defaults are exported as `QUEUE_DEFAULTS` (shared) and `DLQ_QUEUE_DEFAULTS` (the dead-letter layer) for visibility and testing:
 
 ```ts
-import { QUEUE_DEFAULTS } from "@composurecdk/sqs";
+import { DLQ_QUEUE_DEFAULTS, QUEUE_DEFAULTS } from "@composurecdk/sqs";
 ```
 
 ### Overriding defaults
@@ -50,19 +136,19 @@ const queue = createQueueBuilder()
 
 The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS) by default. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.
 
+On the primary roles (`"standard"`, `"fifo"`):
+
 | Alarm                                   | Metric                                               | Default threshold | Rationale                                                                                                                                                                                                     |
 | --------------------------------------- | ---------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `approximateAgeOfOldestMessage`         | `ApproximateAgeOfOldestMessage` (Max, 1 min)         | > 300s (5 min)    | Primary "consumer falling behind" signal. Conservative starting point — tune to your SLA and `retentionPeriod`.                                                                                               |
 | `approximateNumberOfMessagesNotVisible` | `ApproximateNumberOfMessagesNotVisible` (Max, 1 min) | > 90,000          | 75% of the [120k in-flight messages](https://docs.aws.amazon.com/AmazonSQS/latest/SQSDeveloperGuide/quotas-messages.html#quotas-in-flight) per-queue quota. Proactive guardrail before receives are rejected. |
 
-These defaults target primary queues; dead-letter queues need different thresholds (any message on a DLQ is itself an alert).
-
-The third AWS-recommended SQS alarm, `ApproximateNumberOfMessagesVisible`, is not enabled by default — its useful threshold depends entirely on the application's processing capacity, and any generic value would be either noise or silence. Use `addAlarm` (see [Custom alarms](#custom-alarms)) to add it for workloads where you know the right threshold.
+The third AWS-recommended SQS alarm, `ApproximateNumberOfMessagesVisible`, is not enabled by default on a primary queue — its useful threshold depends entirely on the application's processing capacity, and any generic value would be either noise or silence. Enable it explicitly via `recommendedAlarms` with your own threshold (enabling it without one throws at build). On the dead-letter roles it is on by default with threshold > 0 (see [DLQ alarms](#dlq-alarms)).
 
-The defaults are exported as `QUEUE_ALARM_DEFAULTS` for visibility and testing:
+The defaults are exported as `QUEUE_ALARM_DEFAULTS` (primary) and `DLQ_ALARM_DEFAULTS` (dead-letter) for visibility and testing:
 
 ```ts
-import { QUEUE_ALARM_DEFAULTS } from "@composurecdk/sqs";
+import { DLQ_ALARM_DEFAULTS, QUEUE_ALARM_DEFAULTS } from "@composurecdk/sqs";
 ```
 
 ### Customizing thresholds
@@ -95,7 +181,7 @@ builder.recommendedAlarms({ approximateNumberOfMessagesNotVisible: false });
 
 ### Custom alarms
 
-Add custom alarms alongside the recommended ones via `addAlarm`. The callback receives an `AlarmDefinitionBuilder` typed to `IQueue`, so the metric factory has access to the queue's properties.
+Add custom alarms alongside the recommended ones via `addAlarm` (available in every role). The callback receives an `AlarmDefinitionBuilder` typed to `IQueue`, so the metric factory has access to the queue's properties.
 
 ```ts
 import { Duration } from "aws-cdk-lib";

package/dist/commonjs/dlq-alarm-defaults.d.ts

@@ -0,0 +1,53 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * Fraction of a dead-letter queue's `retentionPeriod` at which the
+ * `approximateAgeOfOldestMessage` alarm fires by default. Messages older
+ * than this have sat unattended for most of their retention window and
+ * are approaching silent deletion by SQS — the alarm is the last call to
+ * investigate and redrive them.
+ */
+export declare const DLQ_AGE_ALARM_RETENTION_RATIO = 0.75;
+/**
+ * AWS-recommended default alarm configuration for dead-letter queues
+ * built in a dead-letter role (`createQueueBuilder("dlq")` /
+ * `createQueueBuilder("fifo-dlq")`).
+ *
+ * The enabled set inverts relative to a primary queue:
+ *
+ * - `approximateNumberOfMessagesVisible` (> 0) is **on** — any message
+ *   on a DLQ indicates a delivery failure that needs investigation.
+ * - `approximateAgeOfOldestMessage` is **on**, re-framed: nothing
+ *   consumes a DLQ, so instead of "consumers falling behind" it fires
+ *   when the oldest message has used {@link DLQ_AGE_ALARM_RETENTION_RATIO}
+ *   of the queue's `retentionPeriod` — the threshold below is derived
+ *   from the default 14-day retention, and the builder scales it to the
+ *   actual retention period at build time.
+ * - `approximateNumberOfMessagesNotVisible` is **off** — nothing is
+ *   normally in flight on a DLQ. The baseline (shared with
+ *   {@link QUEUE_ALARM_DEFAULTS} via spread) applies if explicitly
+ *   re-enabled.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+ */
+export declare const DLQ_ALARM_DEFAULTS: {
+    approximateAgeOfOldestMessage: {
+        threshold: number;
+        evaluationPeriods: number;
+        datapointsToAlarm: number;
+        treatMissingData: TreatMissingData.NOT_BREACHING;
+    };
+    /** 0 — any message on a dead-letter queue is itself the alert. */
+    approximateNumberOfMessagesVisible: {
+        threshold: number;
+        evaluationPeriods: number;
+        datapointsToAlarm: number;
+        treatMissingData: TreatMissingData.NOT_BREACHING;
+    };
+    approximateNumberOfMessagesNotVisible: {
+        threshold: number;
+        evaluationPeriods: number;
+        datapointsToAlarm: number;
+        treatMissingData: TreatMissingData.NOT_BREACHING;
+    };
+};
+//# sourceMappingURL=dlq-alarm-defaults.d.ts.map

package/dist/commonjs/dlq-alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dlq-alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/dlq-alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAK9D;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;IAU7B,kEAAkE;;;;;;;;;;;;;CAOtC,CAAC"}

package/dist/commonjs/dlq-alarm-defaults.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DLQ_ALARM_DEFAULTS = exports.DLQ_AGE_ALARM_RETENTION_RATIO = void 0;
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const queue_alarm_defaults_js_1 = require("./queue-alarm-defaults.js");
+const dlq_defaults_js_1 = require("./dlq-defaults.js");
+/**
+ * Fraction of a dead-letter queue's `retentionPeriod` at which the
+ * `approximateAgeOfOldestMessage` alarm fires by default. Messages older
+ * than this have sat unattended for most of their retention window and
+ * are approaching silent deletion by SQS — the alarm is the last call to
+ * investigate and redrive them.
+ */
+exports.DLQ_AGE_ALARM_RETENTION_RATIO = 0.75;
+/**
+ * AWS-recommended default alarm configuration for dead-letter queues
+ * built in a dead-letter role (`createQueueBuilder("dlq")` /
+ * `createQueueBuilder("fifo-dlq")`).
+ *
+ * The enabled set inverts relative to a primary queue:
+ *
+ * - `approximateNumberOfMessagesVisible` (> 0) is **on** — any message
+ *   on a DLQ indicates a delivery failure that needs investigation.
+ * - `approximateAgeOfOldestMessage` is **on**, re-framed: nothing
+ *   consumes a DLQ, so instead of "consumers falling behind" it fires
+ *   when the oldest message has used {@link DLQ_AGE_ALARM_RETENTION_RATIO}
+ *   of the queue's `retentionPeriod` — the threshold below is derived
+ *   from the default 14-day retention, and the builder scales it to the
+ *   actual retention period at build time.
+ * - `approximateNumberOfMessagesNotVisible` is **off** — nothing is
+ *   normally in flight on a DLQ. The baseline (shared with
+ *   {@link QUEUE_ALARM_DEFAULTS} via spread) applies if explicitly
+ *   re-enabled.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+ */
+exports.DLQ_ALARM_DEFAULTS = {
+    ...queue_alarm_defaults_js_1.QUEUE_ALARM_DEFAULTS,
+    approximateAgeOfOldestMessage: {
+        threshold: dlq_defaults_js_1.DLQ_QUEUE_DEFAULTS.retentionPeriod.toSeconds() * exports.DLQ_AGE_ALARM_RETENTION_RATIO,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** 0 — any message on a dead-letter queue is itself the alert. */
+    approximateNumberOfMessagesVisible: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=dlq-alarm-defaults.js.map

package/dist/commonjs/dlq-alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dlq-alarm-defaults.js","sourceRoot":"","sources":["../../src/dlq-alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAE9D,uEAAiE;AACjE,uDAAuD;AAEvD;;;;;;GAMG;AACU,QAAA,6BAA6B,GAAG,IAAI,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACU,QAAA,kBAAkB,GAAG;IAChC,GAAG,8CAAoB;IAEvB,6BAA6B,EAAE;QAC7B,SAAS,EAAE,oCAAkB,CAAC,eAAe,CAAC,SAAS,EAAE,GAAG,qCAA6B;QACzF,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,kEAAkE;IAClE,kCAAkC,EAAE;QAClC,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CAC2B,CAAC"}

package/dist/commonjs/dlq-defaults.d.ts

@@ -0,0 +1,19 @@
+import { Duration } from "aws-cdk-lib";
+/**
+ * AWS-recommended defaults layered on top of {@link QUEUE_DEFAULTS} for
+ * queues built in a dead-letter role (`createQueueBuilder("dlq")` /
+ * `createQueueBuilder("fifo-dlq")`).
+ */
+export declare const DLQ_QUEUE_DEFAULTS: {
+    /**
+     * 14 days — the SQS maximum. A dead-letter queue exists to give
+     * operators a window to investigate and redrive failed messages, so
+     * maximizing that window is the point; the 4-day CDK default would let
+     * messages expire before anyone notices them. The Well-Architected
+     * Reliability Pillar calls for retaining failed messages long enough
+     * to analyse and reprocess them.
+     * @see https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html
+     */
+    retentionPeriod: Duration;
+};
+//# sourceMappingURL=dlq-defaults.d.ts.map

package/dist/commonjs/dlq-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dlq-defaults.d.ts","sourceRoot":"","sources":["../../src/dlq-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;IAC7B;;;;;;;;OAQG;;CAE0B,CAAC"}

package/dist/commonjs/dlq-defaults.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DLQ_QUEUE_DEFAULTS = void 0;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+/**
+ * AWS-recommended defaults layered on top of {@link QUEUE_DEFAULTS} for
+ * queues built in a dead-letter role (`createQueueBuilder("dlq")` /
+ * `createQueueBuilder("fifo-dlq")`).
+ */
+exports.DLQ_QUEUE_DEFAULTS = {
+    /**
+     * 14 days — the SQS maximum. A dead-letter queue exists to give
+     * operators a window to investigate and redrive failed messages, so
+     * maximizing that window is the point; the 4-day CDK default would let
+     * messages expire before anyone notices them. The Well-Architected
+     * Reliability Pillar calls for retaining failed messages long enough
+     * to analyse and reprocess them.
+     * @see https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html
+     */
+    retentionPeriod: aws_cdk_lib_1.Duration.days(14),
+};
+//# sourceMappingURL=dlq-defaults.js.map

package/dist/commonjs/dlq-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dlq-defaults.js","sourceRoot":"","sources":["../../src/dlq-defaults.ts"],"names":[],"mappings":";;;AAAA,6CAAuC;AAGvC;;;;GAIG;AACU,QAAA,kBAAkB,GAAG;IAChC;;;;;;;;OAQG;IACH,eAAe,EAAE,sBAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;CACL,CAAC"}

package/dist/commonjs/grants.d.ts

@@ -0,0 +1,19 @@
+import type { IGrantable } from "aws-cdk-lib/aws-iam";
+import type { IQueue } from "aws-cdk-lib/aws-sqs";
+import { type Grant, type Resolvable } from "@composurecdk/core";
+/**
+ * Consumer-side grant helpers for an SQS queue. Pass one to a grantee builder's
+ * `grant(...)` — e.g.
+ * `role.grant(queueGrants.consume(ref("queue", (r) => r.queue)))`.
+ *
+ * Each delegates to the queue's native `grant*` method. See ADR-0013.
+ */
+export declare const queueGrants: {
+    /** Receive and delete messages (`sqs:ReceiveMessage`, `DeleteMessage`, …). */
+    consume: (queue: Resolvable<IQueue>) => Grant<IGrantable>;
+    /** Send messages (`sqs:SendMessage`, `GetQueueAttributes`, …). */
+    send: (queue: Resolvable<IQueue>) => Grant<IGrantable>;
+    /** Purge the queue (`sqs:PurgeQueue`). */
+    purge: (queue: Resolvable<IQueue>) => Grant<IGrantable>;
+};
+//# sourceMappingURL=grants.d.ts.map

package/dist/commonjs/grants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,KAAK,KAAK,EAAY,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAQ3E;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;IACtB,8EAA8E;qBAXtE,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAe9C,kEAAkE;kBAf1D,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAmB9C,0CAA0C;mBAnBlC,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;CAuB/C,CAAC"}

package/dist/commonjs/grants.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queueGrants = void 0;
+const core_1 = require("@composurecdk/core");
+/** Wraps one of {@link IQueue}'s native grant methods as a capability helper. */
+const capability = (apply) => (queue) => (0, core_1.grantVia)(queue, apply);
+/**
+ * Consumer-side grant helpers for an SQS queue. Pass one to a grantee builder's
+ * `grant(...)` — e.g.
+ * `role.grant(queueGrants.consume(ref("queue", (r) => r.queue)))`.
+ *
+ * Each delegates to the queue's native `grant*` method. See ADR-0013.
+ */
+exports.queueGrants = {
+    /** Receive and delete messages (`sqs:ReceiveMessage`, `DeleteMessage`, …). */
+    consume: capability((queue, grantee) => {
+        queue.grantConsumeMessages(grantee);
+    }),
+    /** Send messages (`sqs:SendMessage`, `GetQueueAttributes`, …). */
+    send: capability((queue, grantee) => {
+        queue.grantSendMessages(grantee);
+    }),
+    /** Purge the queue (`sqs:PurgeQueue`). */
+    purge: capability((queue, grantee) => {
+        queue.grantPurge(grantee);
+    }),
+};
+//# sourceMappingURL=grants.js.map

package/dist/commonjs/grants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.js","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":";;;AAEA,6CAA2E;AAE3E,iFAAiF;AACjF,MAAM,UAAU,GACd,CAAC,KAAmD,EAAE,EAAE,CACxD,CAAC,KAAyB,EAAqB,EAAE,CAC/C,IAAA,eAAQ,EAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAE3B;;;;;;GAMG;AACU,QAAA,WAAW,GAAG;IACzB,8EAA8E;IAC9E,OAAO,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACrC,KAAK,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC,CAAC;IACF,kEAAkE;IAClE,IAAI,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QAClC,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC,CAAC;IACF,0CAA0C;IAC1C,KAAK,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACnC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC,CAAC;CACH,CAAC"}

package/dist/commonjs/index.d.ts

@@ -1,5 +1,10 @@
-export { createQueueBuilder, type IQueueBuilder, type QueueBuilderProps, type QueueBuilderResult, } from "./queue-builder.js";
+export { createQueueBuilder, type IQueueBuilder, type QueueBuilderResult, } from "./queue-builder.js";
+export { queueGrants } from "./grants.js";
+export { type QueueRole } from "./queue-role.js";
+export { type FifoQueueName, type QueueBuilderProps, type FifoQueueBuilderProps, type DlqQueueBuilderProps, type FifoDlqQueueBuilderProps, type QueueBuilderPropsByRole, } from "./queue-props.js";
 export { QUEUE_DEFAULTS } from "./defaults.js";
+export { DLQ_QUEUE_DEFAULTS } from "./dlq-defaults.js";
 export { type QueueAlarmConfig } from "./queue-alarm-config.js";
 export { QUEUE_ALARM_DEFAULTS } from "./queue-alarm-defaults.js";
+export { DLQ_ALARM_DEFAULTS } from "./dlq-alarm-defaults.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/commonjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAMjD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/commonjs/index.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QUEUE_ALARM_DEFAULTS = exports.QUEUE_DEFAULTS = exports.createQueueBuilder = void 0;
+exports.DLQ_ALARM_DEFAULTS = exports.QUEUE_ALARM_DEFAULTS = exports.DLQ_QUEUE_DEFAULTS = exports.QUEUE_DEFAULTS = exports.queueGrants = exports.createQueueBuilder = void 0;
 var queue_builder_js_1 = require("./queue-builder.js");
 Object.defineProperty(exports, "createQueueBuilder", { enumerable: true, get: function () { return queue_builder_js_1.createQueueBuilder; } });
+var grants_js_1 = require("./grants.js");
+Object.defineProperty(exports, "queueGrants", { enumerable: true, get: function () { return grants_js_1.queueGrants; } });
 var defaults_js_1 = require("./defaults.js");
 Object.defineProperty(exports, "QUEUE_DEFAULTS", { enumerable: true, get: function () { return defaults_js_1.QUEUE_DEFAULTS; } });
+var dlq_defaults_js_1 = require("./dlq-defaults.js");
+Object.defineProperty(exports, "DLQ_QUEUE_DEFAULTS", { enumerable: true, get: function () { return dlq_defaults_js_1.DLQ_QUEUE_DEFAULTS; } });
 var queue_alarm_defaults_js_1 = require("./queue-alarm-defaults.js");
 Object.defineProperty(exports, "QUEUE_ALARM_DEFAULTS", { enumerable: true, get: function () { return queue_alarm_defaults_js_1.QUEUE_ALARM_DEFAULTS; } });
+var dlq_alarm_defaults_js_1 = require("./dlq-alarm-defaults.js");
+Object.defineProperty(exports, "DLQ_ALARM_DEFAULTS", { enumerable: true, get: function () { return dlq_alarm_defaults_js_1.DLQ_ALARM_DEFAULTS; } });
 //# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,uDAK4B;AAJ1B,sHAAA,kBAAkB,OAAA;AAKpB,6CAA+C;AAAtC,6GAAA,cAAc,OAAA;AAEvB,qEAAiE;AAAxD,+HAAA,oBAAoB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,uDAI4B;AAH1B,sHAAA,kBAAkB,OAAA;AAIpB,yCAA0C;AAAjC,wGAAA,WAAW,OAAA;AAepB,6CAA+C;AAAtC,6GAAA,cAAc,OAAA;AACvB,qDAAuD;AAA9C,qHAAA,kBAAkB,OAAA;AAE3B,qEAAiE;AAAxD,+HAAA,oBAAoB,OAAA;AAC7B,iEAA6D;AAApD,2HAAA,kBAAkB,OAAA"}

package/dist/commonjs/queue-alarm-config.d.ts

@@ -1,9 +1,12 @@
 import type { AlarmConfig } from "@composurecdk/cloudwatch";
 /**
  * Controls which recommended alarms are created for an SQS queue.
- * All applicable alarms are enabled by default with AWS-recommended thresholds.
- * Set individual alarms to `false` to disable them, or provide an
- * {@link AlarmConfig} to tune thresholds.
+ * Which alarms are enabled by default — and their thresholds — depends
+ * on the queue's {@link QueueRole}: the primary roles (`"standard"`,
+ * `"fifo"`) and the dead-letter roles (`"dlq"`, `"fifo-dlq"`) invert
+ * which signals matter. Set an individual alarm to `false` to disable
+ * it, or provide an {@link AlarmConfig} to enable it (if off by
+ * default) or tune its thresholds (if on by default).
  *
  * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
  */
@@ -16,15 +19,16 @@ export interface QueueAlarmConfig {
     enabled?: boolean;
     /**
      * Alarm when the oldest unprocessed message in the queue has been
-     * waiting longer than the configured threshold. Primary signal that
-     * consumers are falling behind.
+     * waiting longer than the configured threshold.
+     *
+     * On a primary queue this is the primary signal that consumers are
+     * falling behind (default threshold: > 300 seconds). On a dead-letter
+     * queue it signals messages approaching the end of the queue's
+     * `retentionPeriod` unattended (default threshold: 75% of the
+     * retention period — see {@link DLQ_ALARM_DEFAULTS}).
      *
      * Metric: `AWS/SQS ApproximateAgeOfOldestMessage`, statistic Maximum,
      * period 1 minute.
-     * Default threshold: > 300 seconds (5 minutes).
-     *
-     * The default is conservative and should be tuned to the queue's
-     * SLA and `retentionPeriod`.
      *
      * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
      */
@@ -34,13 +38,45 @@ export interface QueueAlarmConfig {
      * messages approaches the SQS quota of 120,000 per queue. A breach
      * means new messages will start being rejected.
      *
+     * Enabled by default on primary queues (threshold: > 90,000 — 75% of
+     * the quota). Disabled by default on dead-letter queues, where nothing
+     * is normally in flight.
+     *
      * Metric: `AWS/SQS ApproximateNumberOfMessagesNotVisible`, statistic
      * Maximum, period 1 minute.
-     * Default threshold: > 90,000 (75% of the in-flight quota).
      *
-     * @see https://docs.aws.amazon.com/AmazonSQS/latest/SQSDeveloperGuide/quotas-messages.html#quotas-in-flight
+     * @see https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-messages.html#quotas-in-flight
      * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
      */
     approximateNumberOfMessagesNotVisible?: AlarmConfig | false;
+    /**
+     * Alarm when the queue has visible (available-to-receive) messages
+     * above the threshold.
+     *
+     * Disabled by default on a primary queue — messages waiting to be
+     * consumed are the normal state, and no generic threshold suits every
+     * workload's processing capacity. Enable it explicitly with a
+     * threshold sized to your consumers; enabling it on a primary queue
+     * without a threshold throws at build.
+     *
+     * Enabled by default on a dead-letter queue, where any message present
+     * is itself the alert (default threshold: > 0). See
+     * {@link DLQ_ALARM_DEFAULTS}.
+     *
+     * Metric: `AWS/SQS ApproximateNumberOfMessagesVisible`, statistic
+     * Maximum, period 1 minute.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+     */
+    approximateNumberOfMessagesVisible?: AlarmConfig | false;
 }
+/**
+ * Keys of the recommended SQS alarms a queue builder can create —
+ * every {@link QueueAlarmConfig} entry except the `enabled` master
+ * switch. Shared between the primary-queue defaults
+ * ({@link QUEUE_ALARM_DEFAULTS}) and the dead-letter-queue defaults
+ * ({@link DLQ_ALARM_DEFAULTS}) so every builder resolves the same
+ * config shape.
+ */
+export type QueueAlarmKey = Exclude<keyof QueueAlarmConfig, "enabled">;
 //# sourceMappingURL=queue-alarm-config.d.ts.map

package/dist/commonjs/queue-alarm-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue-alarm-config.d.ts","sourceRoot":"","sources":["../../src/queue-alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;OAaG;IACH,6BAA6B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEpD;;;;;;;;;;;OAWG;IACH,qCAAqC,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAC7D"}
+{"version":3,"file":"queue-alarm-config.d.ts","sourceRoot":"","sources":["../../src/queue-alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;OAcG;IACH,6BAA6B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEpD;;;;;;;;;;;;;;OAcG;IACH,qCAAqC,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAE5D;;;;;;;;;;;;;;;;;;OAkBG;IACH,kCAAkC,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAC1D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,gBAAgB,EAAE,SAAS,CAAC,CAAC"}

package/dist/commonjs/queue-alarm-defaults.d.ts

@@ -1,18 +1,53 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
 import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
-interface QueueAlarmDefaults {
-    enabled: true;
-    approximateAgeOfOldestMessage: AlarmConfigDefaults;
-    approximateNumberOfMessagesNotVisible: AlarmConfigDefaults;
-}
+import type { QueueAlarmKey } from "./queue-alarm-config.js";
 /**
- * AWS-recommended default alarm configuration for SQS queues.
+ * Shape of a recommended-alarm default set: an {@link AlarmConfigDefaults}
+ * baseline per recommended SQS alarm. Partial — an alarm with no entry
+ * has no generic default and requires an explicit threshold when
+ * enabled. Implemented by {@link QUEUE_ALARM_DEFAULTS} (primary queues)
+ * and {@link DLQ_ALARM_DEFAULTS} (dead-letter queues).
+ */
+export type QueueAlarmDefaults = Partial<Record<QueueAlarmKey, AlarmConfigDefaults>>;
+/**
+ * AWS-recommended default alarm configuration for primary
+ * (consumer-fed) SQS queues, standard and FIFO alike — since November
+ * 2024 FIFO queues share the standard 120,000 in-flight quota, so the
+ * same thresholds apply.
  *
- * Tuned for primary (consumer-fed) queues. Dead-letter queues need
- * different thresholds — any message on a DLQ is itself an alert,
- * whereas a primary queue with messages is normal.
+ * These are threshold baselines only — which alarms are *enabled* by
+ * default differs per builder: dead-letter queues invert the set (see
+ * {@link DLQ_ALARM_DEFAULTS}) because any message on a DLQ is itself an
+ * alert, whereas a primary queue with messages is normal. There is no
+ * entry for `approximateNumberOfMessagesVisible`: no generic threshold
+ * suits a primary queue, so enabling it requires an explicit threshold.
  *
  * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+ * @see https://aws.amazon.com/about-aws/whats-new/2024/11/amazon-sqs-increases-in-flight-limit-fifo-queues/
  */
-export declare const QUEUE_ALARM_DEFAULTS: QueueAlarmDefaults;
-export {};
+export declare const QUEUE_ALARM_DEFAULTS: {
+    /**
+     * 5 minutes. Conservative starting point for a "consumer falling
+     * behind" alarm. The right value depends on the workload's SLA and
+     * `retentionPeriod`; tune via `recommendedAlarms`.
+     */
+    approximateAgeOfOldestMessage: {
+        threshold: number;
+        evaluationPeriods: number;
+        datapointsToAlarm: number;
+        treatMissingData: TreatMissingData.NOT_BREACHING;
+    };
+    /**
+     * 90,000 — 75% of the SQS 120,000 in-flight message quota. Proactive
+     * guardrail; a breach means the queue is approaching the point where
+     * new messages will be rejected.
+     * @see https://docs.aws.amazon.com/AmazonSQS/latest/SQSDeveloperGuide/quotas-messages.html#quotas-in-flight
+     */
+    approximateNumberOfMessagesNotVisible: {
+        threshold: number;
+        evaluationPeriods: number;
+        datapointsToAlarm: number;
+        treatMissingData: TreatMissingData.NOT_BREACHING;
+    };
+};
 //# sourceMappingURL=queue-alarm-defaults.d.ts.map

package/dist/commonjs/queue-alarm-defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue-alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/queue-alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,kBAAkB;IAC1B,OAAO,EAAE,IAAI,CAAC;IACd,6BAA6B,EAAE,mBAAmB,CAAC;IACnD,qCAAqC,EAAE,mBAAmB,CAAC;CAC5D;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,kBA2BlC,CAAC"}
+{"version":3,"file":"queue-alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/queue-alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAErF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;OAIG;;;;;;;IAQH;;;;;OAKG;;;;;;;CAOyB,CAAC"}