@composurecdk/sqs 0.7.0

package/README.md

@@ -0,0 +1,131 @@
+# @composurecdk/sqs
+
+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
+
+```ts
+import { Duration } from "aws-cdk-lib";
+import { createQueueBuilder } from "@composurecdk/sqs";
+
+const orders = createQueueBuilder()
+  .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.
+
+## Secure Defaults
+
+`createQueueBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property                 | Default                       | Rationale                                                                                                                                                                                                                                                             |
+| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enforceSSL`             | `true`                        | Denies any request that doesn't use TLS (resource policy `Deny` on `aws:SecureTransport: false`). Mirrors the SNS topic default. ([SNS/SQS security best practices](https://docs.aws.amazon.com/AmazonSQS/latest/SQSDeveloperGuide/sqs-security-best-practices.html)) |
+| `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.
+
+The defaults are exported as `QUEUE_DEFAULTS` for visibility and testing:
+
+```ts
+import { QUEUE_DEFAULTS } from "@composurecdk/sqs";
+```
+
+### Overriding defaults
+
+```ts
+const queue = createQueueBuilder()
+  .queueName("my-queue")
+  .enforceSSL(false)
+  .receiveMessageWaitTime(Duration.seconds(0))
+  .build(stack, "MyQueue");
+```
+
+## Recommended Alarms
+
+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.
+
+| 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 defaults are exported as `QUEUE_ALARM_DEFAULTS` for visibility and testing:
+
+```ts
+import { QUEUE_ALARM_DEFAULTS } from "@composurecdk/sqs";
+```
+
+### Customizing thresholds
+
+Override individual alarm properties via `recommendedAlarms`. Unspecified fields keep their defaults.
+
+```ts
+const queue = createQueueBuilder()
+  .queueName("orders")
+  .recommendedAlarms({
+    approximateAgeOfOldestMessage: { threshold: 60, evaluationPeriods: 3 },
+  });
+```
+
+### Disabling alarms
+
+Disable all recommended alarms:
+
+```ts
+builder.recommendedAlarms(false);
+// or
+builder.recommendedAlarms({ enabled: false });
+```
+
+Disable individual alarms:
+
+```ts
+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.
+
+```ts
+import { Duration } from "aws-cdk-lib";
+
+const queue = createQueueBuilder()
+  .queueName("orders")
+  .addAlarm("highEmptyReceiveRate", (alarm) =>
+    alarm
+      .metric((queue) => queue.metricNumberOfEmptyReceives({ period: Duration.minutes(1) }))
+      .threshold(1000)
+      .greaterThan()
+      .description("Queue receiving an unusually high number of empty receives."),
+  );
+```
+
+### Applying alarm actions
+
+Alarms are returned in the build result as `Record<string, Alarm>`:
+
+```ts
+const result = createQueueBuilder().queueName("orders").build(stack, "Orders");
+
+const alertTopic = new Topic(stack, "AlertTopic");
+for (const alarm of Object.values(result.alarms)) {
+  alarm.addAlarmAction(new SnsAction(alertTopic));
+}
+```
+
+For composing the alarm-actions wiring across multiple builders in a single `compose` system, see [`alarmActionsPolicy`](../cloudwatch/README.md) in `@composurecdk/cloudwatch`.
+
+## Examples
+
+- [OrderProcessorStack](../examples/src/order-processor-app.ts) — Primary SQS queue with recommended alarms routed to a sibling SNS alert topic.

package/dist/defaults.d.ts

@@ -0,0 +1,8 @@
+import { type QueueProps } from "aws-cdk-lib/aws-sqs";
+/**
+ * Secure, AWS-recommended defaults applied to every SQS queue built
+ * with {@link createQueueBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+export declare const QUEUE_DEFAULTS: Partial<QueueProps>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,CAAC,UAAU,CA4B9C,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,35 @@
+import { Duration } from "aws-cdk-lib";
+import { QueueEncryption } from "aws-cdk-lib/aws-sqs";
+/**
+ * Secure, AWS-recommended defaults applied to every SQS queue built
+ * with {@link createQueueBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+export const QUEUE_DEFAULTS = {
+    /**
+     * Reject any request that does not use TLS. Adds a resource policy
+     * `Deny` on `aws:SecureTransport: false`, the same control applied to
+     * SNS topics by {@link createTopicBuilder}.
+     * @see https://docs.aws.amazon.com/AmazonSQS/latest/SQSDeveloperGuide/sqs-security-best-practices.html
+     */
+    enforceSSL: true,
+    /**
+     * Encrypt messages at rest with the SQS-managed key (SSE-SQS). This
+     * is the safe baseline; bring-your-own KMS encryption is opt-in via
+     * `.encryptionMasterKey(...)` paired with `.encryption(QueueEncryption.KMS)`.
+     * CDK already defaults newly-created queues to SSE-SQS — making it
+     * explicit here keeps the default discoverable and stable across CDK
+     * versions.
+     * @see https://docs.aws.amazon.com/AmazonSQS/latest/SQSDeveloperGuide/sqs-data-protection.html
+     */
+    encryption: QueueEncryption.SQS_MANAGED,
+    /**
+     * Enable long polling. Holds `ReceiveMessage` connections open for up
+     * to 20 seconds while waiting for messages, which cuts both the cost
+     * of empty receives and the perceived delivery latency of low-traffic
+     * queues. The 20s value is the SQS maximum.
+     * @see https://docs.aws.amazon.com/AmazonSQS/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html#sqs-long-polling
+     */
+    receiveMessageWaitTime: Duration.seconds(20),
+};
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,eAAe,EAAmB,MAAM,qBAAqB,CAAC;AAEvE;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwB;IACjD;;;;;OAKG;IACH,UAAU,EAAE,IAAI;IAEhB;;;;;;;;OAQG;IACH,UAAU,EAAE,eAAe,CAAC,WAAW;IAEvC;;;;;;OAMG;IACH,sBAAsB,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;CAC7C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createQueueBuilder, type IQueueBuilder, type QueueBuilderProps, type QueueBuilderResult, } from "./queue-builder.js";
+export { QUEUE_DEFAULTS } from "./defaults.js";
+export { type QueueAlarmConfig } from "./queue-alarm-config.js";
+export { QUEUE_ALARM_DEFAULTS } from "./queue-alarm-defaults.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createQueueBuilder, } from "./queue-builder.js";
+export { QUEUE_DEFAULTS } from "./defaults.js";
+export { QUEUE_ALARM_DEFAULTS } from "./queue-alarm-defaults.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAInB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

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

@@ -0,0 +1,46 @@
+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.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+ */
+export interface QueueAlarmConfig {
+    /**
+     * Master switch: set to `false` to disable all recommended alarms.
+     * Individual alarms can also be disabled via their own entry.
+     * @default true
+     */
+    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.
+     *
+     * 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
+     */
+    approximateAgeOfOldestMessage?: AlarmConfig | false;
+    /**
+     * Alarm when the number of in-flight (received but not yet deleted)
+     * messages approaches the SQS quota of 120,000 per queue. A breach
+     * means new messages will start being rejected.
+     *
+     * 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/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+     */
+    approximateNumberOfMessagesNotVisible?: AlarmConfig | false;
+}
+//# sourceMappingURL=queue-alarm-config.d.ts.map

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

@@ -0,0 +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"}

package/dist/queue-alarm-config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=queue-alarm-config.js.map

package/dist/queue-alarm-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-alarm-config.js","sourceRoot":"","sources":["../src/queue-alarm-config.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,18 @@
+import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
+interface QueueAlarmDefaults {
+    enabled: true;
+    approximateAgeOfOldestMessage: AlarmConfigDefaults;
+    approximateNumberOfMessagesNotVisible: AlarmConfigDefaults;
+}
+/**
+ * AWS-recommended default alarm configuration for SQS queues.
+ *
+ * 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.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+ */
+export declare const QUEUE_ALARM_DEFAULTS: QueueAlarmDefaults;
+export {};
+//# sourceMappingURL=queue-alarm-defaults.d.ts.map

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

@@ -0,0 +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"}

package/dist/queue-alarm-defaults.js

@@ -0,0 +1,37 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * AWS-recommended default alarm configuration for SQS queues.
+ *
+ * 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.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+ */
+export const QUEUE_ALARM_DEFAULTS = {
+    enabled: true,
+    /**
+     * 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: 300,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        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: 90_000,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=queue-alarm-defaults.js.map

package/dist/queue-alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-alarm-defaults.js","sourceRoot":"","sources":["../src/queue-alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAS9D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAuB;IACtD,OAAO,EAAE,IAAI;IAEb;;;;OAIG;IACH,6BAA6B,EAAE;QAC7B,SAAS,EAAE,GAAG;QACd,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;;;OAKG;IACH,qCAAqC,EAAE;QACrC,SAAS,EAAE,MAAM;QACjB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/queue-alarms.d.ts

@@ -0,0 +1,26 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { IQueue } from "aws-cdk-lib/aws-sqs";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { QueueAlarmConfig } from "./queue-alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an SQS queue.
+ */
+export declare function resolveQueueAlarmDefinitions(queue: IQueue, config: QueueAlarmConfig | undefined): AlarmDefinition[];
+/**
+ * Creates AWS-recommended CloudWatch alarms for an SQS queue, merging
+ * recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param queue - The SQS queue to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+ */
+export declare function createQueueAlarms(scope: IConstruct, id: string, queue: IQueue, config: QueueAlarmConfig | false | undefined, customAlarms?: AlarmDefinitionBuilder<IQueue>[]): Record<string, Alarm>;
+//# sourceMappingURL=queue-alarms.d.ts.map

package/dist/queue-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-alarms.d.ts","sourceRoot":"","sources":["../src/queue-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAsB,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAMhE;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,eAAe,EAAE,CA+CnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,GAAG,KAAK,GAAG,SAAS,EAC5C,YAAY,GAAE,sBAAsB,CAAC,MAAM,CAAC,EAAO,GAClD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/queue-alarms.js

@@ -0,0 +1,71 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator } from "aws-cdk-lib/aws-cloudwatch";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { QUEUE_ALARM_DEFAULTS } from "./queue-alarm-defaults.js";
+const METRIC_PERIOD = Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an SQS queue.
+ */
+export function resolveQueueAlarmDefinitions(queue, config) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.approximateAgeOfOldestMessage !== false) {
+        const cfg = resolveAlarmConfig(config?.approximateAgeOfOldestMessage, QUEUE_ALARM_DEFAULTS.approximateAgeOfOldestMessage);
+        definitions.push({
+            key: "approximateAgeOfOldestMessage",
+            alarmName: cfg.alarmName,
+            metric: queue.metricApproximateAgeOfOldestMessage({ period: METRIC_PERIOD }),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `SQS queue's oldest message has been waiting longer than the threshold, ` +
+                `indicating consumers are falling behind. Threshold: > ${String(cfg.threshold)} seconds in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.approximateNumberOfMessagesNotVisible !== false) {
+        const cfg = resolveAlarmConfig(config?.approximateNumberOfMessagesNotVisible, QUEUE_ALARM_DEFAULTS.approximateNumberOfMessagesNotVisible);
+        definitions.push({
+            key: "approximateNumberOfMessagesNotVisible",
+            alarmName: cfg.alarmName,
+            metric: queue.metricApproximateNumberOfMessagesNotVisible({ period: METRIC_PERIOD }),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `SQS queue's in-flight messages are approaching the 120,000 per-queue quota; ` +
+                `further receives will be rejected once the quota is hit. ` +
+                `Threshold: > ${String(cfg.threshold)} in-flight in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * Creates AWS-recommended CloudWatch alarms for an SQS queue, merging
+ * recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param queue - The SQS queue to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+ */
+export function createQueueAlarms(scope, id, queue, config, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? QUEUE_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveQueueAlarmDefinitions(queue, config);
+    const custom = customAlarms.map((b) => b.resolve(queue));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=queue-alarms.js.map

package/dist/queue-alarms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-alarms.js","sourceRoot":"","sources":["../src/queue-alarms.ts"],"names":[],"mappings":"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"}

package/dist/queue-builder.d.ts

@@ -0,0 +1,111 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type IQueue, Queue, type QueueProps } from "aws-cdk-lib/aws-sqs";
+import { type IConstruct } from "constructs";
+import { COPY_STATE, type Lifecycle } from "@composurecdk/core";
+import { type ITaggedBuilder } from "@composurecdk/cloudformation";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { QueueAlarmConfig } from "./queue-alarm-config.js";
+/**
+ * Configuration properties for the SQS queue builder.
+ *
+ * Extends the CDK {@link QueueProps} with additional builder-specific options.
+ */
+export interface QueueBuilderProps extends QueueProps {
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * By default, the builder creates recommended alarms with sensible
+     * thresholds for every applicable metric. Individual alarms can be
+     * customized or disabled. Set to `false` to disable all alarms.
+     *
+     * No alarm actions are configured by default since notification
+     * methods are user-specific. Access alarms from the build result
+     * or use an `afterBuild` hook to apply actions.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+     */
+    recommendedAlarms?: QueueAlarmConfig | false;
+}
+/**
+ * The build output of an {@link IQueueBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface QueueBuilderResult {
+    /** The SQS queue construct created by the builder. */
+    queue: Queue;
+    /**
+     * CloudWatch alarms created for the queue, keyed by alarm name.
+     *
+     * Includes both AWS-recommended alarms and any custom alarms added
+     * via {@link IQueueBuilder.addAlarm}. Access individual alarms
+     * by key (e.g., `result.alarms.approximateAgeOfOldestMessage`).
+     *
+     * No alarm actions are configured — apply them via the result or an
+     * `afterBuild` hook.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
+     */
+    alarms: Record<string, Alarm>;
+}
+/**
+ * A fluent builder for configuring and creating an AWS SQS queue.
+ *
+ * Each configuration property from the CDK {@link QueueProps} is exposed
+ * as an overloaded method: call with a value to set it (returns the builder
+ * for chaining), or call with no arguments to read the current value.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * an SQS queue with the configured properties and returns a
+ * {@link QueueBuilderResult}.
+ *
+ * The builder also creates AWS-recommended CloudWatch alarms by default.
+ * Alarms can be customized or disabled via the `recommendedAlarms` property.
+ * Custom alarms can be added via the {@link addAlarm} method.
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sqs.Queue.html
+ *
+ * @example
+ * ```ts
+ * const orders = createQueueBuilder()
+ *   .queueName("orders")
+ *   .visibilityTimeout(Duration.seconds(60));
+ * ```
+ */
+export type IQueueBuilder = ITaggedBuilder<QueueBuilderProps, QueueBuilder>;
+declare class QueueBuilder implements Lifecycle<QueueBuilderResult> {
+    #private;
+    props: Partial<QueueBuilderProps>;
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<IQueue>) => AlarmDefinitionBuilder<IQueue>): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: QueueBuilder): void;
+    build(scope: IConstruct, id: string): QueueBuilderResult;
+}
+/**
+ * Creates a new {@link IQueueBuilder} for configuring an AWS SQS queue.
+ *
+ * This is the entry point for defining an SQS queue component. The returned
+ * builder exposes every {@link QueueBuilderProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS SQS queue.
+ *
+ * @example
+ * ```ts
+ * const orders = createQueueBuilder()
+ *   .queueName("orders")
+ *   .visibilityTimeout(Duration.seconds(60));
+ *
+ * // Use standalone:
+ * const result = orders.build(stack, "Orders");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { orders, alerts: createTopicBuilder() },
+ *   { orders: [], alerts: [] },
+ * );
+ * ```
+ */
+export declare function createQueueBuilder(): IQueueBuilder;
+export {};
+//# sourceMappingURL=queue-builder.d.ts.map

package/dist/queue-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-builder.d.ts","sourceRoot":"","sources":["../src/queue-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAIhE;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,KAAK,EAAE,KAAK,CAAC;IAEb;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;AAE5E,cAAM,YAAa,YAAW,SAAS,CAAC,kBAAkB,CAAC;;IACzD,KAAK,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAM;IAGvC,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,MAAM,CAAC,KAAK,sBAAsB,CAAC,MAAM,CAAC,GACnF,IAAI;IAKP,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAIxC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,kBAAkB;CAczD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAElD"}

package/dist/queue-builder.js

@@ -0,0 +1,57 @@
+import { Queue } from "aws-cdk-lib/aws-sqs";
+import { COPY_STATE } from "@composurecdk/core";
+import { taggedBuilder } from "@composurecdk/cloudformation";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { createQueueAlarms } from "./queue-alarms.js";
+import { QUEUE_DEFAULTS } from "./defaults.js";
+class QueueBuilder {
+    props = {};
+    #customAlarms = [];
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target) {
+        target.#customAlarms.push(...this.#customAlarms);
+    }
+    build(scope, id) {
+        const { recommendedAlarms: alarmConfig, ...queueProps } = this.props;
+        const mergedProps = {
+            ...QUEUE_DEFAULTS,
+            ...queueProps,
+        };
+        const queue = new Queue(scope, id, mergedProps);
+        const alarms = createQueueAlarms(scope, id, queue, alarmConfig, this.#customAlarms);
+        return { queue, alarms };
+    }
+}
+/**
+ * Creates a new {@link IQueueBuilder} for configuring an AWS SQS queue.
+ *
+ * This is the entry point for defining an SQS queue component. The returned
+ * builder exposes every {@link QueueBuilderProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS SQS queue.
+ *
+ * @example
+ * ```ts
+ * const orders = createQueueBuilder()
+ *   .queueName("orders")
+ *   .visibilityTimeout(Duration.seconds(60));
+ *
+ * // Use standalone:
+ * const result = orders.build(stack, "Orders");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { orders, alerts: createTopicBuilder() },
+ *   { orders: [], alerts: [] },
+ * );
+ * ```
+ */
+export function createQueueBuilder() {
+    return taggedBuilder(QueueBuilder);
+}
+//# sourceMappingURL=queue-builder.js.map

package/dist/queue-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-builder.js","sourceRoot":"","sources":["../src/queue-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,EAAmB,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EAAE,UAAU,EAAkB,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAuB,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AA0E/C,MAAM,YAAY;IAChB,KAAK,GAA+B,EAAE,CAAC;IAC9B,aAAa,GAAqC,EAAE,CAAC;IAE9D,QAAQ,CACN,GAAW,EACX,SAAoF;QAEpF,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,sBAAsB,CAAS,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAoB;QAC/B,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAErE,MAAM,WAAW,GAAG;YAClB,GAAG,cAAc;YACjB,GAAG,UAAU;SACO,CAAC;QAEvB,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QAEhD,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAEpF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,aAAa,CAAkC,YAAY,CAAC,CAAC;AACtE,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@composurecdk/sqs",
+  "version": "0.7.0",
+  "description": "Composable SQS queue builder with well-architected defaults",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laazyj/composureCDK",
+    "directory": "packages/sqs"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [],
+  "author": "Jason Duffett (https://github.com/laazyj)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@composurecdk/cloudformation": "^0.7.0",
+    "@composurecdk/cloudwatch": "^0.7.0",
+    "@composurecdk/core": "^0.7.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "aws-cdk-lib": "^2.253.1",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
+  }
+}