@composurecdk/sqs 0.8.7 → 0.9.1

package/dist/esm/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/esm/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/esm/grants.js

@@ -0,0 +1,25 @@
+import { grantVia } from "@composurecdk/core";
+/** Wraps one of {@link IQueue}'s native grant methods as a capability helper. */
+const capability = (apply) => (queue) => 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.
+ */
+export const 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/esm/grants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.js","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,QAAQ,EAAmB,MAAM,oBAAoB,CAAC;AAE3E,iFAAiF;AACjF,MAAM,UAAU,GACd,CAAC,KAAmD,EAAE,EAAE,CACxD,CAAC,KAAyB,EAAqB,EAAE,CAC/C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,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/esm/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/esm/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/esm/index.js

@@ -1,4 +1,7 @@
 export { createQueueBuilder, } from "./queue-builder.js";
+export { queueGrants } from "./grants.js";
 export { QUEUE_DEFAULTS } from "./defaults.js";
+export { DLQ_QUEUE_DEFAULTS } from "./dlq-defaults.js";
 export { QUEUE_ALARM_DEFAULTS } from "./queue-alarm-defaults.js";
+export { DLQ_ALARM_DEFAULTS } from "./dlq-alarm-defaults.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAe1C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/esm/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/esm/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/esm/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/esm/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"}

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

@@ -1,15 +1,21 @@
 import { TreatMissingData } from "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/
  */
 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

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

@@ -1 +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"}
+{"version":3,"file":"queue-alarm-defaults.js","sourceRoot":"","sources":["../../src/queue-alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAa9D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC;;;;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;CAC2B,CAAC"}

package/dist/esm/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/esm/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/esm/queue-alarm-profiles.js

@@ -0,0 +1,92 @@
+import { Duration } from "aws-cdk-lib";
+import { resolveAlarmThresholdBasis } from "@composurecdk/cloudwatch";
+import { QUEUE_ALARM_DEFAULTS } from "./queue-alarm-defaults.js";
+import { DLQ_AGE_ALARM_RETENTION_RATIO, DLQ_ALARM_DEFAULTS } from "./dlq-alarm-defaults.js";
+const METRIC_PERIOD = Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/** Metric factory for each recommended SQS alarm. */
+export const 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. */
+export const PRIMARY_ALARM_PROFILE = {
+    enablement: {
+        approximateAgeOfOldestMessage: true,
+        approximateNumberOfMessagesNotVisible: true,
+        approximateNumberOfMessagesVisible: false,
+    },
+    defaults: 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.approximateNumberOfMessagesNotVisible,
+        approximateNumberOfMessagesVisible: 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.
+ */
+export function dlqAlarmProfile(scope, retentionPeriod) {
+    const retentionSeconds = 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,
+            approximateAgeOfOldestMessage: {
+                ...DLQ_ALARM_DEFAULTS.approximateAgeOfOldestMessage,
+                threshold: Math.round(retentionSeconds * DLQ_AGE_ALARM_RETENTION_RATIO),
+            },
+        },
+        descriptions: DLQ_ALARM_DESCRIPTIONS,
+    };
+}
+//# sourceMappingURL=queue-alarm-profiles.js.map

package/dist/esm/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/esm/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.
@@ -16,11 +20,14 @@ export declare function resolveQueueAlarmDefinitions(queue: IQueue, config: Queu
  * @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 config - User-provided alarm configuration, or `false` to disable the
+ *   recommended alarms.
  * @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/esm/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;;;;;;;;;;;;;;;GAeG;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/esm/queue-alarms.js

@@ -1,49 +1,55 @@
-import { Duration } from "aws-cdk-lib";
-import { ComparisonOperator } from "aws-cdk-lib/aws-cloudwatch";
+import { ComparisonOperator, TreatMissingData } 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`;
+import { QUEUE_ALARM_METRICS } from "./queue-alarm-profiles.js";
+const QUEUE_ALARM_KEYS = Object.keys(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: 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.
  */
-export function resolveQueueAlarmDefinitions(queue, config) {
+export function resolveQueueAlarmDefinitions(queue, config, profile) {
     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;
+    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 = 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_METRICS[key](queue),
+                threshold: cfg.threshold,
+                comparisonOperator: 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
@@ -52,19 +58,19 @@ export function resolveQueueAlarmDefinitions(queue, config) {
  * @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 config - User-provided alarm configuration, or `false` to disable the
+ *   recommended alarms.
  * @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 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);
+export function createQueueAlarms(scope, id, queue, config, customAlarms, profile) {
+    const recommended = config === false || config?.enabled === false
+        ? []
+        : resolveQueueAlarmDefinitions(queue, config, profile);
     const custom = customAlarms.map((b) => b.resolve(queue));
     return createAlarms(scope, id, [...recommended, ...custom]);
 }

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

@@ -1 +1 @@
-{"version":3,"file":"queue-alarms.js","sourceRoot":"","sources":["../../src/queue-alarms.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"queue-alarms.js","sourceRoot":"","sources":["../../src/queue-alarms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAI9F,OAAO,EAA0B,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGpG,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAEhE,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAoB,CAAC;AAE7E;;;GAGG;AACH,MAAM,qBAAqB,GAAG;IAC5B,iBAAiB,EAAE,CAAC;IACpB,iBAAiB,EAAE,CAAC;IACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;CACjD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,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,kBAAkB,CAC5B,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,mBAAmB,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;gBACvC,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,kBAAkB,EAAE,kBAAkB,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;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAiB,EACjB,EAAU,EACV,KAAa,EACb,MAA4C,EAC5C,YAA8C,EAC9C,OAA0B;IAE1B,MAAM,WAAW,GACf,MAAM,KAAK,KAAK,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK;QAC3C,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,4BAA4B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAEzD,OAAO,YAAY,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,WAAW,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC"}