@composurecdk/sqs 0.8.6 → 0.9.0

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

@@ -3,16 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.QUEUE_ALARM_DEFAULTS = void 0;
 const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
 /**
- * AWS-recommended default alarm configuration for SQS queues.
+ * 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/
  */
 exports.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

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

@@ -1 +1 @@
-{"version":3,"file":"queue-alarm-defaults.js","sourceRoot":"","sources":["../../src/queue-alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAS9D;;;;;;;;GAQG;AACU,QAAA,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,iCAAgB,CAAC,aAAa;KACjD;IAED;;;;;OAKG;IACH,qCAAqC,EAAE;QACrC,SAAS,EAAE,MAAM;QACjB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}
+{"version":3,"file":"queue-alarm-defaults.js","sourceRoot":"","sources":["../../src/queue-alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAa9D;;;;;;;;;;;;;;;GAeG;AACU,QAAA,oBAAoB,GAAG;IAClC;;;;OAIG;IACH,6BAA6B,EAAE;QAC7B,SAAS,EAAE,GAAG;QACd,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;;;OAKG;IACH,qCAAqC,EAAE;QACrC,SAAS,EAAE,MAAM;QACjB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CAC2B,CAAC"}

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

@@ -0,0 +1,37 @@
+import { Duration } from "aws-cdk-lib";
+import type { IQueue } from "aws-cdk-lib/aws-sqs";
+import type { IConstruct } from "constructs";
+import type { AlarmMetric } from "@composurecdk/cloudwatch";
+import type { QueueAlarmKey } from "./queue-alarm-config.js";
+import type { QueueAlarmDefaults } from "./queue-alarm-defaults.js";
+/** Metric factory for each recommended SQS alarm. */
+export declare const QUEUE_ALARM_METRICS: Record<QueueAlarmKey, (queue: IQueue) => AlarmMetric>;
+/**
+ * How a queue builder interprets the recommended-alarm set: which alarms
+ * are created without explicit opt-in, the default thresholds each alarm
+ * merges against (an alarm with no baseline requires an explicit
+ * threshold when enabled), and the description each produces. Primary
+ * queues and dead-letter queues need different profiles because the
+ * alarm semantics invert — see {@link DLQ_ALARM_DEFAULTS}.
+ */
+export interface QueueAlarmProfile {
+    /** Whether each alarm is created when the user hasn't configured it. */
+    enablement: Record<QueueAlarmKey, boolean>;
+    /** Default config each alarm merges user overrides against. */
+    defaults: QueueAlarmDefaults;
+    /** Alarm description, given the resolved threshold. */
+    descriptions: Record<QueueAlarmKey, (threshold: number) => string>;
+}
+/** Recommended-alarm profile for primary (consumer-fed) queues, standard and FIFO. */
+export declare const PRIMARY_ALARM_PROFILE: QueueAlarmProfile;
+/**
+ * Recommended-alarm profile for dead-letter queues. The age alarm's
+ * default threshold is {@link DLQ_AGE_ALARM_RETENTION_RATIO} of the
+ * queue's resolved `retentionPeriod`, so it keeps firing before messages
+ * age out even when retention is tuned. When the retention is an
+ * unresolved token there is no basis to derive from — the age alarm is
+ * skipped with an acknowledgeable warning (unless explicitly configured
+ * with a threshold), per the library-wide derived-threshold convention.
+ */
+export declare function dlqAlarmProfile(scope: IConstruct, retentionPeriod: Duration | undefined): QueueAlarmProfile;
+//# sourceMappingURL=queue-alarm-profiles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queue-alarm-profiles.d.ts","sourceRoot":"","sources":["../../src/queue-alarm-profiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAOpE,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,WAAW,CAOrF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAC3C,+DAA+D;IAC/D,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;CACpE;AAOD,sFAAsF;AACtF,eAAO,MAAM,qBAAqB,EAAE,iBAgBnC,CAAC;AAkCF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,QAAQ,GAAG,SAAS,GACpC,iBAAiB,CAwBnB"}

package/dist/commonjs/queue-alarm-profiles.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRIMARY_ALARM_PROFILE = exports.QUEUE_ALARM_METRICS = void 0;
+exports.dlqAlarmProfile = dlqAlarmProfile;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const queue_alarm_defaults_js_1 = require("./queue-alarm-defaults.js");
+const dlq_alarm_defaults_js_1 = require("./dlq-alarm-defaults.js");
+const METRIC_PERIOD = aws_cdk_lib_1.Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/** Metric factory for each recommended SQS alarm. */
+exports.QUEUE_ALARM_METRICS = {
+    approximateAgeOfOldestMessage: (queue) => queue.metricApproximateAgeOfOldestMessage({ period: METRIC_PERIOD }),
+    approximateNumberOfMessagesNotVisible: (queue) => queue.metricApproximateNumberOfMessagesNotVisible({ period: METRIC_PERIOD }),
+    approximateNumberOfMessagesVisible: (queue) => queue.metricApproximateNumberOfMessagesVisible({ period: METRIC_PERIOD }),
+};
+const describeInFlight = (threshold) => `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(threshold)} in-flight in ${METRIC_PERIOD_LABEL}.`;
+/** Recommended-alarm profile for primary (consumer-fed) queues, standard and FIFO. */
+exports.PRIMARY_ALARM_PROFILE = {
+    enablement: {
+        approximateAgeOfOldestMessage: true,
+        approximateNumberOfMessagesNotVisible: true,
+        approximateNumberOfMessagesVisible: false,
+    },
+    defaults: queue_alarm_defaults_js_1.QUEUE_ALARM_DEFAULTS,
+    descriptions: {
+        approximateAgeOfOldestMessage: (threshold) => `SQS queue's oldest message has been waiting longer than the threshold, ` +
+            `indicating consumers are falling behind. Threshold: > ${String(threshold)} seconds in ${METRIC_PERIOD_LABEL}.`,
+        approximateNumberOfMessagesNotVisible: describeInFlight,
+        approximateNumberOfMessagesVisible: (threshold) => `Queue has more visible messages waiting than expected for this workload. ` +
+            `Threshold: > ${String(threshold)} in ${METRIC_PERIOD_LABEL}.`,
+    },
+};
+const DLQ_ALARM_ENABLEMENT = {
+    approximateAgeOfOldestMessage: true,
+    approximateNumberOfMessagesNotVisible: false,
+    approximateNumberOfMessagesVisible: true,
+};
+const DLQ_ALARM_DESCRIPTIONS = {
+    approximateAgeOfOldestMessage: (threshold) => `Dead-letter queue's oldest message is approaching the queue's retentionPeriod — ` +
+        `investigate and redrive it before SQS deletes it. ` +
+        `Threshold: > ${String(threshold)} seconds in ${METRIC_PERIOD_LABEL}.`,
+    approximateNumberOfMessagesNotVisible: describeInFlight,
+    approximateNumberOfMessagesVisible: (threshold) => `Dead-letter queue has messages present — any message here indicates a delivery ` +
+        `failure that needs investigation. Threshold: > ${String(threshold)} in ${METRIC_PERIOD_LABEL}.`,
+};
+/**
+ * The dead-letter profile when the retention period is an unresolved
+ * token: the retention-derived age alarm has no basis to derive from,
+ * so it is off (an explicit user threshold still re-enables it); the
+ * rest of the DLQ set is unchanged.
+ */
+const DLQ_TOKEN_RETENTION_ALARM_PROFILE = {
+    enablement: { ...DLQ_ALARM_ENABLEMENT, approximateAgeOfOldestMessage: false },
+    defaults: {
+        approximateNumberOfMessagesNotVisible: dlq_alarm_defaults_js_1.DLQ_ALARM_DEFAULTS.approximateNumberOfMessagesNotVisible,
+        approximateNumberOfMessagesVisible: dlq_alarm_defaults_js_1.DLQ_ALARM_DEFAULTS.approximateNumberOfMessagesVisible,
+    },
+    descriptions: DLQ_ALARM_DESCRIPTIONS,
+};
+/**
+ * Recommended-alarm profile for dead-letter queues. The age alarm's
+ * default threshold is {@link DLQ_AGE_ALARM_RETENTION_RATIO} of the
+ * queue's resolved `retentionPeriod`, so it keeps firing before messages
+ * age out even when retention is tuned. When the retention is an
+ * unresolved token there is no basis to derive from — the age alarm is
+ * skipped with an acknowledgeable warning (unless explicitly configured
+ * with a threshold), per the library-wide derived-threshold convention.
+ */
+function dlqAlarmProfile(scope, retentionPeriod) {
+    const retentionSeconds = (0, cloudwatch_1.resolveAlarmThresholdBasis)({
+        scope,
+        value: retentionPeriod,
+        resolve: (duration) => duration.toSeconds(),
+        isUnresolved: (duration) => duration.isUnresolved(),
+        warningId: "@composurecdk/sqs:dlq-age-alarm-token-retention",
+        alarmLabel: "dead-letter queue message-age",
+        suppressHint: "recommendedAlarms({ approximateAgeOfOldestMessage: false })",
+    });
+    if (retentionSeconds === undefined)
+        return DLQ_TOKEN_RETENTION_ALARM_PROFILE;
+    return {
+        enablement: DLQ_ALARM_ENABLEMENT,
+        defaults: {
+            ...dlq_alarm_defaults_js_1.DLQ_ALARM_DEFAULTS,
+            approximateAgeOfOldestMessage: {
+                ...dlq_alarm_defaults_js_1.DLQ_ALARM_DEFAULTS.approximateAgeOfOldestMessage,
+                threshold: Math.round(retentionSeconds * dlq_alarm_defaults_js_1.DLQ_AGE_ALARM_RETENTION_RATIO),
+            },
+        },
+        descriptions: DLQ_ALARM_DESCRIPTIONS,
+    };
+}
+//# sourceMappingURL=queue-alarm-profiles.js.map

package/dist/commonjs/queue-alarm-profiles.js.map

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

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

@@ -4,11 +4,15 @@ import type { IConstruct } from "constructs";
 import type { AlarmDefinition } from "@composurecdk/cloudwatch";
 import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
 import type { QueueAlarmConfig } from "./queue-alarm-config.js";
+import type { QueueAlarmProfile } from "./queue-alarm-profiles.js";
 /**
  * Resolves the recommended alarm configuration into fully-resolved
  * {@link AlarmDefinition}s for an SQS queue.
+ *
+ * @param profile - The builder's alarm profile: which alarms are created
+ *   without explicit opt-in and the defaults they merge against.
  */
-export declare function resolveQueueAlarmDefinitions(queue: IQueue, config: QueueAlarmConfig | undefined): AlarmDefinition[];
+export declare function resolveQueueAlarmDefinitions(queue: IQueue, config: QueueAlarmConfig | undefined, profile: QueueAlarmProfile): AlarmDefinition[];
 /**
  * Creates AWS-recommended CloudWatch alarms for an SQS queue, merging
  * recommended definitions with any custom alarm builders.
@@ -18,9 +22,11 @@ export declare function resolveQueueAlarmDefinitions(queue: IQueue, config: Queu
  * @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()`.
+ * @param profile - The builder's alarm profile; see
+ *   {@link resolveQueueAlarmDefinitions}.
  * @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>;
+export declare function createQueueAlarms(scope: IConstruct, id: string, queue: IQueue, config: QueueAlarmConfig | false | undefined, customAlarms: AlarmDefinitionBuilder<IQueue>[], profile: QueueAlarmProfile): Record<string, Alarm>;
 //# sourceMappingURL=queue-alarms.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"queue-alarms.d.ts","sourceRoot":"","sources":["../../src/queue-alarms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAwC,MAAM,4BAA4B,CAAC;AAC9F,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,EAAiB,MAAM,yBAAyB,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAenE;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,GAAG,SAAS,EACpC,OAAO,EAAE,iBAAiB,GACzB,eAAe,EAAE,CAoCnB;AAED;;;;;;;;;;;;;;GAcG;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,EAAE,sBAAsB,CAAC,MAAM,CAAC,EAAE,EAC9C,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAQvB"}

package/dist/commonjs/queue-alarms.js

@@ -2,52 +2,58 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveQueueAlarmDefinitions = resolveQueueAlarmDefinitions;
 exports.createQueueAlarms = createQueueAlarms;
-const aws_cdk_lib_1 = require("aws-cdk-lib");
 const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
 const cloudwatch_1 = require("@composurecdk/cloudwatch");
-const queue_alarm_defaults_js_1 = require("./queue-alarm-defaults.js");
-const METRIC_PERIOD = aws_cdk_lib_1.Duration.minutes(1);
-const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+const queue_alarm_profiles_js_1 = require("./queue-alarm-profiles.js");
+const QUEUE_ALARM_KEYS = Object.keys(queue_alarm_profiles_js_1.QUEUE_ALARM_METRICS);
+/**
+ * Non-threshold baseline for alarms enabled without a profile default —
+ * the threshold itself must come from the user's config.
+ */
+const OPT_IN_ALARM_BASELINE = {
+    evaluationPeriods: 1,
+    datapointsToAlarm: 1,
+    treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+};
 /**
  * Resolves the recommended alarm configuration into fully-resolved
  * {@link AlarmDefinition}s for an SQS queue.
+ *
+ * @param profile - The builder's alarm profile: which alarms are created
+ *   without explicit opt-in and the defaults they merge against.
  */
-function resolveQueueAlarmDefinitions(queue, config) {
+function resolveQueueAlarmDefinitions(queue, config, profile) {
     if (config?.enabled === false)
         return [];
-    const definitions = [];
-    if (config?.approximateAgeOfOldestMessage !== false) {
-        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.approximateAgeOfOldestMessage, queue_alarm_defaults_js_1.QUEUE_ALARM_DEFAULTS.approximateAgeOfOldestMessage);
-        definitions.push({
-            key: "approximateAgeOfOldestMessage",
-            alarmName: cfg.alarmName,
-            metric: queue.metricApproximateAgeOfOldestMessage({ period: METRIC_PERIOD }),
-            threshold: cfg.threshold,
-            comparisonOperator: aws_cloudwatch_1.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 = (0, cloudwatch_1.resolveAlarmConfig)(config?.approximateNumberOfMessagesNotVisible, queue_alarm_defaults_js_1.QUEUE_ALARM_DEFAULTS.approximateNumberOfMessagesNotVisible);
-        definitions.push({
-            key: "approximateNumberOfMessagesNotVisible",
-            alarmName: cfg.alarmName,
-            metric: queue.metricApproximateNumberOfMessagesNotVisible({ period: METRIC_PERIOD }),
-            threshold: cfg.threshold,
-            comparisonOperator: aws_cloudwatch_1.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;
+    return QUEUE_ALARM_KEYS.flatMap((key) => {
+        const userConfig = config?.[key];
+        if (userConfig === false)
+            return [];
+        if (userConfig === undefined && !profile.enablement[key])
+            return [];
+        const baseline = profile.defaults[key];
+        if (baseline === undefined && userConfig?.threshold === undefined) {
+            throw new Error(`Queue "${queue.node.id}": the "${key}" alarm has no generic default threshold for ` +
+                `this queue type — no value fits every workload. Supply one explicitly, e.g. ` +
+                `recommendedAlarms({ ${key}: { threshold: … } }).`);
+        }
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(userConfig, 
+        // userConfig.threshold is present whenever baseline is not — the guard above ensures it.
+        baseline ?? { ...OPT_IN_ALARM_BASELINE, threshold: userConfig?.threshold ?? 0 });
+        return [
+            {
+                key,
+                alarmName: cfg.alarmName,
+                metric: queue_alarm_profiles_js_1.QUEUE_ALARM_METRICS[key](queue),
+                threshold: cfg.threshold,
+                comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+                evaluationPeriods: cfg.evaluationPeriods,
+                datapointsToAlarm: cfg.datapointsToAlarm,
+                treatMissingData: cfg.treatMissingData,
+                description: profile.descriptions[key](cfg.threshold),
+            },
+        ];
+    });
 }
 /**
  * Creates AWS-recommended CloudWatch alarms for an SQS queue, merging
@@ -58,17 +64,18 @@ function resolveQueueAlarmDefinitions(queue, config) {
  * @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()`.
+ * @param profile - The builder's alarm profile; see
+ *   {@link resolveQueueAlarmDefinitions}.
  * @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
  */
-function createQueueAlarms(scope, id, queue, config, customAlarms = []) {
+function createQueueAlarms(scope, id, queue, config, customAlarms, profile) {
     if (config === false)
         return {};
-    const enabled = config?.enabled ?? queue_alarm_defaults_js_1.QUEUE_ALARM_DEFAULTS.enabled;
-    if (!enabled)
+    if (!(config?.enabled ?? true))
         return {};
-    const recommended = resolveQueueAlarmDefinitions(queue, config);
+    const recommended = resolveQueueAlarmDefinitions(queue, config, profile);
     const custom = customAlarms.map((b) => b.resolve(queue));
     return (0, cloudwatch_1.createAlarms)(scope, id, [...recommended, ...custom]);
 }

package/dist/commonjs/queue-alarms.js.map

@@ -1 +1 @@
-{"version":3,"file":"queue-alarms.js","sourceRoot":"","sources":["../../src/queue-alarms.ts"],"names":[],"mappings":";;AAgBA,oEAkDC;AAeD,8CAgBC;AAjGD,6CAAuC;AACvC,+DAA4E;AAI5E,yDAAoG;AAEpG,uEAAiE;AAEjE,MAAM,aAAa,GAAG,sBAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC1C,MAAM,mBAAmB,GAAG,GAAG,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,CAAC,SAAS,CAAC;AAE1E;;;GAGG;AACH,SAAgB,4BAA4B,CAC1C,KAAa,EACb,MAAoC;IAEpC,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAEzC,MAAM,WAAW,GAAsB,EAAE,CAAC;IAE1C,IAAI,MAAM,EAAE,6BAA6B,KAAK,KAAK,EAAE,CAAC;QACpD,MAAM,GAAG,GAAG,IAAA,+BAAkB,EAC5B,MAAM,EAAE,6BAA6B,EACrC,8CAAoB,CAAC,6BAA6B,CACnD,CAAC;QACF,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,+BAA+B;YACpC,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,MAAM,EAAE,KAAK,CAAC,mCAAmC,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;YAC5E,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,kBAAkB,EAAE,mCAAkB,CAAC,sBAAsB;YAC7D,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACtC,WAAW,EACT,yEAAyE;gBACzE,yDAAyD,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,eAAe,mBAAmB,GAAG;SACtH,CAAC,CAAC;IACL,CAAC;IAED,IAAI,MAAM,EAAE,qCAAqC,KAAK,KAAK,EAAE,CAAC;QAC5D,MAAM,GAAG,GAAG,IAAA,+BAAkB,EAC5B,MAAM,EAAE,qCAAqC,EAC7C,8CAAoB,CAAC,qCAAqC,CAC3D,CAAC;QACF,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,uCAAuC;YAC5C,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,MAAM,EAAE,KAAK,CAAC,2CAA2C,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;YACpF,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,kBAAkB,EAAE,mCAAkB,CAAC,sBAAsB;YAC7D,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACtC,WAAW,EACT,8EAA8E;gBAC9E,2DAA2D;gBAC3D,gBAAgB,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,iBAAiB,mBAAmB,GAAG;SAC/E,CAAC,CAAC;IACL,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,iBAAiB,CAC/B,KAAiB,EACjB,EAAU,EACV,KAAa,EACb,MAA4C,EAC5C,eAAiD,EAAE;IAEnD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAEhC,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,8CAAoB,CAAC,OAAO,CAAC;IAChE,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,MAAM,WAAW,GAAG,4BAA4B,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAEzD,OAAO,IAAA,yBAAY,EAAC,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,WAAW,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"queue-alarms.js","sourceRoot":"","sources":["../../src/queue-alarms.ts"],"names":[],"mappings":";;AA4BA,oEAwCC;AAiBD,8CAeC;AApGD,+DAA8F;AAI9F,yDAAoG;AAGpG,uEAAgE;AAEhE,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,6CAAmB,CAAoB,CAAC;AAE7E;;;GAGG;AACH,MAAM,qBAAqB,GAAG;IAC5B,iBAAiB,EAAE,CAAC;IACpB,iBAAiB,EAAE,CAAC;IACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;CACjD,CAAC;AAEF;;;;;;GAMG;AACH,SAAgB,4BAA4B,CAC1C,KAAa,EACb,MAAoC,EACpC,OAA0B;IAE1B,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAEzC,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC,GAAG,EAAqB,EAAE;QACzD,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,UAAU,KAAK,KAAK;YAAE,OAAO,EAAE,CAAC;QACpC,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAEpE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ,KAAK,SAAS,IAAI,UAAU,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;YAClE,MAAM,IAAI,KAAK,CACb,UAAU,KAAK,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,+CAA+C;gBAClF,8EAA8E;gBAC9E,uBAAuB,GAAG,wBAAwB,CACrD,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,IAAA,+BAAkB,EAC5B,UAAU;QACV,yFAAyF;QACzF,QAAQ,IAAI,EAAE,GAAG,qBAAqB,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,IAAI,CAAC,EAAE,CAChF,CAAC;QACF,OAAO;YACL;gBACE,GAAG;gBACH,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,MAAM,EAAE,6CAAmB,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;gBACvC,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,kBAAkB,EAAE,mCAAkB,CAAC,sBAAsB;gBAC7D,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;gBACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;gBACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;gBACtC,WAAW,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC;aACtD;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,iBAAiB,CAC/B,KAAiB,EACjB,EAAU,EACV,KAAa,EACb,MAA4C,EAC5C,YAA8C,EAC9C,OAA0B;IAE1B,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAChC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,IAAI,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAE1C,MAAM,WAAW,GAAG,4BAA4B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACzE,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAEzD,OAAO,IAAA,yBAAY,EAAC,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,WAAW,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC"}

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

@@ -4,31 +4,12 @@ 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";
+import type { QueueBuilderExtensionProps, QueueBuilderPropsByRole } from "./queue-props.js";
+import { type QueueRole } from "./queue-role.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.
+ * The build output of {@link createQueueBuilder}, identical across every
+ * {@link QueueRole}. Contains the CDK constructs created during
+ * {@link Lifecycle.build}, keyed by role.
  */
 export interface QueueBuilderResult {
     /** The SQS queue construct created by the builder. */
@@ -37,8 +18,8 @@ export interface QueueBuilderResult {
      * 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`).
+     * via `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.
@@ -48,21 +29,37 @@ export interface QueueBuilderResult {
     alarms: Record<string, Alarm>;
 }
 /**
- * A fluent builder for configuring and creating an AWS SQS queue.
+ * The builder's full internal prop store: the CDK {@link QueueProps},
+ * the builder-only extensions, and the queue's role. The public surface
+ * per role is the narrowed view in {@link QueueBuilderPropsByRole} —
+ * this type exists so one `QueueBuilder` implementation can back every
+ * role.
+ */
+interface InternalQueueBuilderProps extends QueueProps, QueueBuilderExtensionProps {
+    /**
+     * The queue's role, set by `createQueueBuilder(role)`. Stored as a
+     * prop (not a private field) so it is data: `.copy()` preserves it
+     * for free and it is inspectable on the builder.
+     */
+    queueRole?: QueueRole;
+}
+/**
+ * A fluent builder for configuring and creating an AWS SQS queue in a
+ * given {@link QueueRole}.
  *
- * Each configuration property from the CDK {@link QueueProps} is exposed
- * as an overloaded method: call with a value to set it (returns the builder
+ * Each configuration property applicable to the role 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 prop surface is exact per role — FIFO-only props exist only on
+ * the FIFO roles, and `deadLetterQueue` does not exist on the
+ * dead-letter roles.
  *
- * 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
+ * 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, the role's
+ * defaults, and the role's recommended CloudWatch alarms, returning 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
@@ -70,42 +67,62 @@ export interface QueueBuilderResult {
  * const orders = createQueueBuilder()
  *   .queueName("orders")
  *   .visibilityTimeout(Duration.seconds(60));
+ *
+ * const orderEvents = createQueueBuilder("fifo")
+ *   .queueName("order-events.fifo")
+ *   .contentBasedDeduplication(true);
+ *
+ * const ordersDlq = createQueueBuilder("dlq").queueName("orders-dlq");
  * ```
  */
-export type IQueueBuilder = ITaggedBuilder<QueueBuilderProps, QueueBuilder>;
+export type IQueueBuilder<R extends QueueRole = "standard"> = ITaggedBuilder<QueueBuilderPropsByRole[R], QueueBuilder>;
 declare class QueueBuilder implements Lifecycle<QueueBuilderResult> {
     #private;
-    props: Partial<QueueBuilderProps>;
+    props: Partial<InternalQueueBuilderProps>;
     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.
+ * Creates a new {@link IQueueBuilder} for configuring an AWS SQS queue
+ * in the given role.
  *
- * 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}.
+ * This is the single entry point for every queue type. The role — see
+ * {@link QueueRole} for the full catalogue — selects the builder's
+ * typed prop surface, its Well-Architected defaults, its
+ * recommended-alarm profile, and its build-time validation:
  *
- * @returns A fluent builder for an AWS SQS queue.
+ * - `createQueueBuilder()` / `createQueueBuilder("standard")` — primary
+ *   standard queue.
+ * - `createQueueBuilder("fifo")` — primary FIFO queue.
+ * - `createQueueBuilder("dlq")` — standard dead-letter queue.
+ * - `createQueueBuilder("fifo-dlq")` — FIFO dead-letter queue (the DLQ
+ *   for a FIFO source must itself be FIFO).
  *
- * @example
- * ```ts
- * const orders = createQueueBuilder()
- *   .queueName("orders")
- *   .visibilityTimeout(Duration.seconds(60));
+ * The returned builder exposes every prop applicable to the role as a
+ * fluent setter/getter and implements {@link Lifecycle} for use with
+ * {@link compose}.
  *
- * // Use standalone:
- * const result = orders.build(stack, "Orders");
+ * @param role - The queue's role. Defaults to `"standard"`.
+ * @returns A fluent builder for an AWS SQS queue in that role.
  *
- * // Or compose into a system:
+ * @example
+ * ```ts
+ * // A FIFO primary queue redriving to a FIFO dead-letter queue:
  * const system = compose(
- *   { orders, alerts: createTopicBuilder() },
- *   { orders: [], alerts: [] },
+ *   {
+ *     orderEventsDlq: createQueueBuilder("fifo-dlq").queueName("order-events-dlq.fifo"),
+ *     orderEvents: createQueueBuilder("fifo")
+ *       .queueName("order-events.fifo")
+ *       .contentBasedDeduplication(true)
+ *       .deadLetterQueue(ref("orderEventsDlq", (r) => ({ queue: r.queue, maxReceiveCount: 5 }))),
+ *   },
+ *   { orderEventsDlq: [], orderEvents: ["orderEventsDlq"] },
  * );
  * ```
  */
 export declare function createQueueBuilder(): IQueueBuilder;
+export declare function createQueueBuilder<R extends QueueRole>(role: R): IQueueBuilder<R>;
 export {};
 //# sourceMappingURL=queue-builder.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"queue-builder.d.ts","sourceRoot":"","sources":["../../src/queue-builder.ts"],"names":[],"mappings":"AACA,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;AAehE;;;;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;CAgBzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAElD"}
+{"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,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAOxE;;;;GAIG;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;;;;;;GAMG;AACH,UAAU,yBAA0B,SAAQ,UAAU,EAAE,0BAA0B;IAChF;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,SAAS,GAAG,UAAU,IAAI,cAAc,CAC1E,uBAAuB,CAAC,CAAC,CAAC,EAC1B,YAAY,CACb,CAAC;AAEF,cAAM,YAAa,YAAW,SAAS,CAAC,kBAAkB,CAAC;;IACzD,KAAK,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAM;IAG/C,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;CA+BzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAAC;AACpD,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC"}