@composurecdk/cloudwatch 0.7.0 → 0.8.1

package/README.md

@@ -46,6 +46,40 @@ The `description` method also accepts a factory for contextual descriptions:
 builder.description((def) => `Alert when invocations >= ${def.threshold} per minute`);
 ```
 
+### Rate and ratio alarms
+
+The metric factory may return either a `Metric` or a `MathExpression` (the
+exported `AlarmMetric` union), so rate/ratio alarms share the same definition
+shape:
+
+```ts
+import { MathExpression } from "aws-cdk-lib/aws-cloudwatch";
+
+new AlarmDefinitionBuilder<LambdaFunction>("errorRate")
+  // Guard the denominator: a divide-by-zero data point is dropped, which would
+  // otherwise push the alarm into INSUFFICIENT_DATA when there are no invocations.
+  .metric(
+    (fn) =>
+      new MathExpression({
+        expression: "IF(invocations > 0, errors / invocations, 0)",
+        usingMetrics: {
+          errors: fn.metricErrors(),
+          invocations: fn.metricInvocations(),
+        },
+        // Set the period on the expression — it overrides the period of every
+        // metric in usingMetrics (default 5 minutes otherwise).
+        period: Duration.minutes(1),
+      }),
+  )
+  .threshold(0.05)
+  .greaterThanOrEqual()
+  .treatMissingData(TreatMissingData.NOT_BREACHING);
+```
+
+Only single-time-series expressions can be alarmed: a `MathExpression` whose
+expression uses `SEARCH(...)` (or otherwise returns multiple series) is rejected
+by CloudWatch at deploy time.
+
 ## createAlarms
 
 Factory function that creates CDK [Alarm](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudwatch.Alarm.html) constructs from fully-resolved `AlarmDefinition`s. Returns a `Record<string, Alarm>` keyed by each definition's key.
@@ -123,6 +157,8 @@ alarmActionsPolicy(app, {
 });
 ```
 
+The policy is implemented as a CDK [Aspect](https://docs.aws.amazon.com/cdk/v2/guide/aspects.html) — it has no dependency on `@composurecdk/core` and works in any CDK app. Because aspects fire during synth, the policy can be registered before or after the alarms it targets, and there is **no need to wrap the call in `afterBuild`** — calling `alarmActionsPolicy(app, …)` at app scope outside any `compose()` chain is the recommended shape. The only constraint is that any `IAlarmAction` instances in the config (e.g. `new SnsAction(topic)`) must reference constructs that already exist when the policy is called.
+
 Per-alarm routing is expressed as rules. Matchers can be a substring (tested against both the alarm's `id` and `path`), a `RegExp` (tested against `path`), or a predicate receiving the full match context. Rules append actions on top of `defaults`; set `replaceDefaults: true` on a rule to suppress defaults for its matched alarms.
 
 ```ts
@@ -137,7 +173,30 @@ alarmActionsPolicy(app, {
 
 All three action states are supported: `alarmActions`, `okActions`, and `insufficientDataActions`.
 
-The policy is implemented as a CDK [Aspect](https://docs.aws.amazon.com/cdk/v2/guide/aspects.html) — it has no dependency on `@composurecdk/core` and works in any CDK app. Because aspects fire during synth, the policy can be registered before or after the alarms it targets. The only constraint is that any `IAlarmAction` instances in the config (e.g. `new SnsAction(topic)`) must reference constructs that already exist when the policy is called.
+### Per-scope routing: different topics for different stacks
+
+Rules route by _alarm identity_ (id, path, predicate). When you instead need to route by _scope_ — e.g. one SNS topic for everything in `us-east-1` and another for the primary region — call `alarmActionsPolicy` multiple times, once per target scope. If the topics are themselves built by the composed system, this is the case where wrapping in [`afterBuild`](../core/README.md) is load-bearing: the closure captures the build `results` so each call can reference its topic.
+
+```ts
+compose(
+  { usEast1Alerts: createTopicBuilder(), siteAlerts: createTopicBuilder() },
+  {
+    /* … */
+  },
+)
+  .withStacks({ usEast1Alerts: usEast1AlertsStack, siteAlerts: siteStack })
+  .afterBuild((_scope, _id, results) => {
+    alarmActionsPolicy(usEast1AlertsStack, {
+      defaults: { alarmActions: [new SnsAction(results.usEast1Alerts.topic)] },
+    });
+    alarmActionsPolicy(siteStack, {
+      defaults: { alarmActions: [new SnsAction(results.siteAlerts.topic)] },
+    });
+  })
+  .build(app, "MySystem");
+```
+
+If a _single_ topic covers the whole app, prefer the top-level form above — `afterBuild` adds nothing in that case.
 
 ### Limitation: L2 alarms only
 

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

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC"}

package/dist/commonjs/alarm-config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=alarm-config.js.map

package/dist/{alarm-config.js.map → commonjs/alarm-config.js.map}

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

package/dist/{alarm-definition-builder.d.ts → commonjs/alarm-definition-builder.d.ts}

@@ -1,19 +1,19 @@
-import { type Metric, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
-import type { AlarmDefinition } from "./alarm-definition.js";
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import type { AlarmDefinition, AlarmMetric } from "./alarm-definition.js";
 import type { AlarmName } from "./alarm-name.js";
 /**
  * Fluent builder for constructing deferred {@link AlarmDefinition}s.
  *
- * Stores a metric factory `(construct: T) => Metric` at configuration time.
- * Call {@link resolve} during build to invoke the factory and produce a
- * complete {@link AlarmDefinition}.
+ * Stores a metric factory `(construct: T) => AlarmMetric` at configuration time
+ * (a `Metric` or a `MathExpression`). Call {@link resolve} during build to
+ * invoke the factory and produce a complete {@link AlarmDefinition}.
  *
  * @typeParam TConstruct - The construct type the metric factory receives.
  */
 export declare class AlarmDefinitionBuilder<TConstruct> {
     #private;
     constructor(key: string);
-    metric(factory: (construct: TConstruct) => Metric): this;
+    metric(factory: (construct: TConstruct) => AlarmMetric): this;
     /**
      * Sets an explicit CloudWatch alarm name. When unset, {@link createAlarms}
      * derives a default from the stack name, builder id, and alarm key. Use

package/dist/commonjs/alarm-definition-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-definition-builder.d.ts","sourceRoot":"","sources":["../../src/alarm-definition-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;GAQG;AACH,qBAAa,sBAAsB,CAAC,UAAU;;gBAWhC,GAAG,EAAE,MAAM;IAIvB,MAAM,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,WAAW,GAAG,IAAI;IAK7D;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAKhC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK9B,WAAW,IAAI,IAAI;IAKnB,kBAAkB,IAAI,IAAI;IAK1B,QAAQ,IAAI,IAAI;IAKhB,eAAe,IAAI,IAAI;IAKvB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKlC,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKlC,gBAAgB,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI;IAKnD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,UAAU,EAAE,eAAe,KAAK,MAAM,CAAC,GAAG,IAAI;IAK3E;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,UAAU,GAAG,eAAe;CAwBhD"}

package/dist/commonjs/alarm-definition-builder.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlarmDefinitionBuilder = void 0;
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+/**
+ * Fluent builder for constructing deferred {@link AlarmDefinition}s.
+ *
+ * Stores a metric factory `(construct: T) => AlarmMetric` at configuration time
+ * (a `Metric` or a `MathExpression`). Call {@link resolve} during build to
+ * invoke the factory and produce a complete {@link AlarmDefinition}.
+ *
+ * @typeParam TConstruct - The construct type the metric factory receives.
+ */
+class AlarmDefinitionBuilder {
+    #key;
+    #alarmName;
+    #metricFactory;
+    #threshold = 0;
+    #comparisonOperator = aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD;
+    #evaluationPeriods = 1;
+    #datapointsToAlarm = 1;
+    #treatMissingData = aws_cloudwatch_1.TreatMissingData.NOT_BREACHING;
+    #description = "";
+    constructor(key) {
+        this.#key = key;
+    }
+    metric(factory) {
+        this.#metricFactory = factory;
+        return this;
+    }
+    /**
+     * Sets an explicit CloudWatch alarm name. When unset, {@link createAlarms}
+     * derives a default from the stack name, builder id, and alarm key. Use
+     * the {@link alarmName} helper to construct branded values.
+     */
+    alarmName(name) {
+        this.#alarmName = name;
+        return this;
+    }
+    threshold(value) {
+        this.#threshold = value;
+        return this;
+    }
+    greaterThan() {
+        this.#comparisonOperator = aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD;
+        return this;
+    }
+    greaterThanOrEqual() {
+        this.#comparisonOperator = aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD;
+        return this;
+    }
+    lessThan() {
+        this.#comparisonOperator = aws_cloudwatch_1.ComparisonOperator.LESS_THAN_THRESHOLD;
+        return this;
+    }
+    lessThanOrEqual() {
+        this.#comparisonOperator = aws_cloudwatch_1.ComparisonOperator.LESS_THAN_OR_EQUAL_TO_THRESHOLD;
+        return this;
+    }
+    evaluationPeriods(n) {
+        this.#evaluationPeriods = n;
+        return this;
+    }
+    datapointsToAlarm(n) {
+        this.#datapointsToAlarm = n;
+        return this;
+    }
+    treatMissingData(treatment) {
+        this.#treatMissingData = treatment;
+        return this;
+    }
+    description(text) {
+        this.#description = text;
+        return this;
+    }
+    /**
+     * Resolves the deferred metric factory against a construct and
+     * returns a complete {@link AlarmDefinition}.
+     *
+     * @throws If {@link metric} was not called before resolve.
+     */
+    resolve(construct) {
+        if (!this.#metricFactory) {
+            throw new Error(`AlarmDefinitionBuilder "${this.#key}": metric() must be called before resolve()`);
+        }
+        const definition = {
+            key: this.#key,
+            alarmName: this.#alarmName,
+            metric: this.#metricFactory(construct),
+            threshold: this.#threshold,
+            comparisonOperator: this.#comparisonOperator,
+            evaluationPeriods: this.#evaluationPeriods,
+            datapointsToAlarm: this.#datapointsToAlarm,
+            treatMissingData: this.#treatMissingData,
+            description: "",
+        };
+        definition.description =
+            typeof this.#description === "function" ? this.#description(definition) : this.#description;
+        return definition;
+    }
+}
+exports.AlarmDefinitionBuilder = AlarmDefinitionBuilder;
+//# sourceMappingURL=alarm-definition-builder.js.map

package/dist/commonjs/alarm-definition-builder.js.map

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

package/dist/commonjs/alarm-definition.d.ts

@@ -0,0 +1,31 @@
+import type { ComparisonOperator, MathExpression, Metric, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import type { AlarmName } from "./alarm-name.js";
+/**
+ * A metric an alarm can be created from: either a single {@link Metric} or a
+ * {@link MathExpression} (e.g. a rate/ratio like `errors / invocations`).
+ *
+ * Both classes carry `createAlarm(...)` — it is declared on the concrete
+ * classes, not on `IMetric` — so this union is exactly what {@link createAlarms}
+ * needs to call. When using a `MathExpression`, set its `period` explicitly:
+ * the expression overrides the period of every metric in `usingMetrics`.
+ */
+export type AlarmMetric = Metric | MathExpression;
+/**
+ * A fully-resolved alarm descriptor. All fields are required —
+ * this is the canonical form consumed by {@link createAlarms}.
+ *
+ * `alarmName` is the only optional field: when omitted, {@link createAlarms}
+ * derives a default via `defaultAlarmName(scope, id, key)`.
+ */
+export interface AlarmDefinition {
+    key: string;
+    alarmName?: AlarmName;
+    metric: AlarmMetric;
+    threshold: number;
+    comparisonOperator: ComparisonOperator;
+    evaluationPeriods: number;
+    datapointsToAlarm: number;
+    treatMissingData: TreatMissingData;
+    description: string;
+}
+//# sourceMappingURL=alarm-definition.d.ts.map

package/dist/commonjs/alarm-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-definition.d.ts","sourceRoot":"","sources":["../../src/alarm-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,MAAM,EACN,gBAAgB,EACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,cAAc,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/commonjs/alarm-definition.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=alarm-definition.js.map

package/dist/{alarm-definition.js.map → commonjs/alarm-definition.js.map}

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

package/dist/commonjs/alarm-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-name.d.ts","sourceRoot":"","sources":["../../src/alarm-name.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAKrE;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAclD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,SAAM,GAAG,SAAS,CAG/E;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ3C"}

package/dist/commonjs/alarm-name.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.alarmName = alarmName;
+exports.joinAlarmName = joinAlarmName;
+exports.kebab = kebab;
+const VALID_CHARS = /^[A-Za-z0-9\-_./#:()+ =@]+$/;
+const MAX_LEN = 255;
+/**
+ * Validates and brands a string as an {@link AlarmName}. The string is used
+ * verbatim — no sanitisation — so what the caller writes is exactly what
+ * appears in CloudWatch.
+ *
+ * @throws If the input is empty, exceeds 255 chars, or contains characters
+ * outside CloudWatch's allowed set: `[A-Za-z0-9-_./#:()+ =@]`.
+ */
+function alarmName(input) {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        throw new Error("alarm name cannot be empty");
+    }
+    if (trimmed.length > MAX_LEN) {
+        throw new Error(`alarm name exceeds ${String(MAX_LEN)} chars: "${trimmed}"`);
+    }
+    if (!VALID_CHARS.test(trimmed)) {
+        throw new Error(`alarm name contains invalid characters (allowed: A-Z a-z 0-9 - _ . / # : ( ) + = @ space): "${trimmed}"`);
+    }
+    return trimmed;
+}
+/**
+ * Builds an {@link AlarmName} by kebab-casing each segment and joining with
+ * `sep`. Empty segments after kebab-casing are dropped, so callers can pass
+ * e.g. `Stack.of(scope).stackName` without worrying about token-resolution
+ * artefacts.
+ */
+function joinAlarmName(segments, sep = "/") {
+    const parts = segments.map(kebab).filter((s) => s.length > 0);
+    return alarmName(parts.join(sep));
+}
+/**
+ * Lower-cases and hyphenates a string: splits camelCase / PascalCase /
+ * snake_case / dotted boundaries into hyphen-separated lowercase words.
+ */
+function kebab(input) {
+    return input
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .replace(/[_\s.]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .toLowerCase();
+}
+//# sourceMappingURL=alarm-name.js.map

package/dist/commonjs/alarm-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-name.js","sourceRoot":"","sources":["../../src/alarm-name.ts"],"names":[],"mappings":";;AAoBA,8BAcC;AAQD,sCAGC;AAMD,sBAQC;AAlDD,MAAM,WAAW,GAAG,6BAA6B,CAAC;AAClD,MAAM,OAAO,GAAG,GAAG,CAAC;AAEpB;;;;;;;GAOG;AACH,SAAgB,SAAS,CAAC,KAAa;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,CAAC,OAAO,CAAC,YAAY,OAAO,GAAG,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,+FAA+F,OAAO,GAAG,CAC1G,CAAC;IACJ,CAAC;IACD,OAAO,OAAoB,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,QAA2B,EAAE,GAAG,GAAG,GAAG;IAClE,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9D,OAAO,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,SAAgB,KAAK,CAAC,KAAa;IACjC,OAAO,KAAK;SACT,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,WAAW,EAAE,CAAC;AACnB,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-alarms.d.ts","sourceRoot":"","sources":["../../src/create-alarms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAO7D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,eAAe,EAAE,GAC7B,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAsBvB"}

package/dist/commonjs/create-alarms.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAlarms = createAlarms;
+const default_alarm_name_js_1 = require("./default-alarm-name.js");
+function capitalize(s) {
+    return s[0].toUpperCase() + s.slice(1);
+}
+/**
+ * Creates CDK {@link Alarm} constructs from fully-resolved {@link AlarmDefinition}s.
+ *
+ * Validates that all definition keys are unique before creating alarms. Each
+ * alarm's `AlarmName` is taken verbatim from `def.alarmName` when supplied;
+ * otherwise it is derived from the scope, `id`, and `def.key` via
+ * {@link defaultAlarmName}.
+ *
+ * @param scope - CDK construct scope.
+ * @param id - Base identifier; each alarm's construct id is `${id}${Capitalize(key)}Alarm`.
+ * @param definitions - Fully-resolved alarm definitions.
+ * @returns A record mapping each definition's key to its created Alarm.
+ * @throws If duplicate keys are found in the definitions.
+ */
+function createAlarms(scope, id, definitions) {
+    const alarms = {};
+    for (const def of definitions) {
+        if (def.key in alarms) {
+            throw new Error(`Duplicate alarm key "${def.key}". Custom alarms cannot use the same key as a recommended alarm. ` +
+                `Disable the recommended alarm first, or use a different key.`);
+        }
+        alarms[def.key] = def.metric.createAlarm(scope, `${id}${capitalize(def.key)}Alarm`, {
+            alarmName: def.alarmName ?? (0, default_alarm_name_js_1.defaultAlarmName)(scope, id, def.key),
+            threshold: def.threshold,
+            evaluationPeriods: def.evaluationPeriods,
+            datapointsToAlarm: def.datapointsToAlarm,
+            treatMissingData: def.treatMissingData,
+            comparisonOperator: def.comparisonOperator,
+            alarmDescription: def.description,
+        });
+    }
+    return alarms;
+}
+//# sourceMappingURL=create-alarms.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-alarms.js","sourceRoot":"","sources":["../../src/create-alarms.ts"],"names":[],"mappings":";;AAuBA,oCA0BC;AA9CD,mEAA2D;AAE3D,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,YAAY,CAC1B,KAAiB,EACjB,EAAU,EACV,WAA8B;IAE9B,MAAM,MAAM,GAA0B,EAAE,CAAC;IAEzC,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,IAAI,GAAG,CAAC,GAAG,IAAI,MAAM,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,wBAAwB,GAAG,CAAC,GAAG,mEAAmE;gBAChG,8DAA8D,CACjE,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE;YAClF,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,IAAA,wCAAgB,EAAC,KAAK,EAAE,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC;YAChE,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACtC,kBAAkB,EAAE,GAAG,CAAC,kBAAkB;YAC1C,gBAAgB,EAAE,GAAG,CAAC,WAAW;SAClC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/commonjs/default-alarm-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-alarm-name.d.ts","sourceRoot":"","sources":["../../src/default-alarm-name.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,KAAK,SAAS,EAAiB,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAGtF"}

package/dist/commonjs/default-alarm-name.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultAlarmName = defaultAlarmName;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const alarm_name_js_1 = require("./alarm-name.js");
+/**
+ * Builds a human-readable, stack-scoped {@link AlarmName} from the alarm's
+ * scope, base id, and key.
+ *
+ * Format: `${stackName}/${kebab(id)}/${kebab(key)}`. Slashes are valid in
+ * CloudWatch alarm names and render hierarchy clearly in the console.
+ *
+ * Used by {@link createAlarms} as the fallback whenever an explicit
+ * `alarmName` is not supplied on the {@link AlarmDefinition}.
+ */
+function defaultAlarmName(scope, id, key) {
+    const stackName = aws_cdk_lib_1.Stack.of(scope).stackName;
+    return (0, alarm_name_js_1.joinAlarmName)([stackName, id, key]);
+}
+//# sourceMappingURL=default-alarm-name.js.map

package/dist/commonjs/default-alarm-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-alarm-name.js","sourceRoot":"","sources":["../../src/default-alarm-name.ts"],"names":[],"mappings":";;AAcA,4CAGC;AAjBD,6CAAoC;AAEpC,mDAAgE;AAEhE;;;;;;;;;GASG;AACH,SAAgB,gBAAgB,CAAC,KAAiB,EAAE,EAAU,EAAE,GAAW;IACzE,MAAM,SAAS,GAAG,mBAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC;IAC5C,OAAO,IAAA,6BAAa,EAAC,CAAC,SAAS,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC"}

package/dist/{index.d.ts → commonjs/index.d.ts}

@@ -1,5 +1,5 @@
 export type { AlarmConfig, AlarmConfigDefaults } from "./alarm-config.js";
-export type { AlarmDefinition } from "./alarm-definition.js";
+export type { AlarmDefinition, AlarmMetric } from "./alarm-definition.js";
 export { AlarmDefinitionBuilder } from "./alarm-definition-builder.js";
 export { type AlarmName, alarmName } from "./alarm-name.js";
 export { defaultAlarmName } from "./default-alarm-name.js";

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,YAAY,EACV,wBAAwB,EACxB,iBAAiB,EACjB,YAAY,GACb,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,yBAAyB,GAC/B,MAAM,iCAAiC,CAAC"}

package/dist/commonjs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.alarmNamePolicy = exports.alarmActionsPolicy = exports.resolveAlarmConfig = exports.createAlarms = exports.defaultAlarmName = exports.alarmName = exports.AlarmDefinitionBuilder = void 0;
+var alarm_definition_builder_js_1 = require("./alarm-definition-builder.js");
+Object.defineProperty(exports, "AlarmDefinitionBuilder", { enumerable: true, get: function () { return alarm_definition_builder_js_1.AlarmDefinitionBuilder; } });
+var alarm_name_js_1 = require("./alarm-name.js");
+Object.defineProperty(exports, "alarmName", { enumerable: true, get: function () { return alarm_name_js_1.alarmName; } });
+var default_alarm_name_js_1 = require("./default-alarm-name.js");
+Object.defineProperty(exports, "defaultAlarmName", { enumerable: true, get: function () { return default_alarm_name_js_1.defaultAlarmName; } });
+var create_alarms_js_1 = require("./create-alarms.js");
+Object.defineProperty(exports, "createAlarms", { enumerable: true, get: function () { return create_alarms_js_1.createAlarms; } });
+var resolve_alarm_config_js_1 = require("./resolve-alarm-config.js");
+Object.defineProperty(exports, "resolveAlarmConfig", { enumerable: true, get: function () { return resolve_alarm_config_js_1.resolveAlarmConfig; } });
+var alarm_actions_policy_js_1 = require("./policies/alarm-actions-policy.js");
+Object.defineProperty(exports, "alarmActionsPolicy", { enumerable: true, get: function () { return alarm_actions_policy_js_1.alarmActionsPolicy; } });
+var alarm_name_policy_js_1 = require("./policies/alarm-name-policy.js");
+Object.defineProperty(exports, "alarmNamePolicy", { enumerable: true, get: function () { return alarm_name_policy_js_1.alarmNamePolicy; } });
+//# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAEA,6EAAuE;AAA9D,qIAAA,sBAAsB,OAAA;AAC/B,iDAA4D;AAAnC,0GAAA,SAAS,OAAA;AAClC,iEAA2D;AAAlD,yHAAA,gBAAgB,OAAA;AACzB,uDAAkD;AAAzC,gHAAA,YAAY,OAAA;AACrB,qEAAyF;AAAhF,6HAAA,kBAAkB,OAAA;AAC3B,8EAAwE;AAA/D,6HAAA,kBAAkB,OAAA;AAM3B,wEAKyC;AAJvC,uHAAA,eAAe,OAAA"}

package/dist/commonjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/{policies → commonjs/policies}/alarm-actions-policy.d.ts

@@ -1,4 +1,4 @@
-import { type IAlarmAction } from "aws-cdk-lib/aws-cloudwatch";
+import type { IAlarmAction } from "aws-cdk-lib/aws-cloudwatch";
 import { type IConstruct } from "constructs";
 import { type AlarmRuleScope } from "./policy-matcher.js";
 export type { AlarmMatchContext, AlarmMatcher } from "./policy-matcher.js";
@@ -23,17 +23,25 @@ export interface AlarmActionsPolicyConfig {
     skipIfAlreadyConfigured?: boolean;
 }
 /**
- * Attaches CloudWatch alarm actions to every `Alarm` and `CompositeAlarm`
- * (L2) construct in the subtree under `scope`.
+ * Registers a CDK {@link https://docs.aws.amazon.com/cdk/v2/guide/aspects.html | Aspect}
+ * on `scope` that attaches CloudWatch alarm actions to every `Alarm` and
+ * `CompositeAlarm` (L2) construct in the subtree at synth time. Call once
+ * with any scope — an `App`, a `Stack`, or the scope passed to `.build()`
+ * for a composed system; alarms added after the call still pick up the
+ * policy, so call ordering is irrelevant as
+ * long as it happens before `app.synth()`. In particular, there is no need
+ * to wrap this call in `afterBuild` — the Aspect runs after the construct
+ * tree is finalised, not at call time. The only temporal constraint is that
+ * any `IAlarmAction` instances in `config` (e.g. `new SnsAction(topic)`)
+ * must reference constructs that already exist when the policy is called.
  *
- * The policy installs a CDK {@link https://docs.aws.amazon.com/cdk/v2/guide/aspects.html | Aspect}
- * that fires during the synth prepare phase, so late-added alarms are also
- * covered. Detection uses the jsii type guards
- * `CfnAlarm.isCfnAlarm` / `CfnCompositeAlarm.isCfnCompositeAlarm` on the L1
- * resource; the L2 parent is found via duck-typing on `addAlarmAction`.
- * Actions are attached through the L2 so that `IAlarmAction.bind()` runs and
- * permissions are wired correctly. Bare `CfnAlarm` nodes (created without an
- * L2 wrapper) are detected but silently skipped.
+ * Detection uses the version-portable `isCfnAlarm` / `isCfnCompositeAlarm`
+ * guards (`CfnResource.isCfnResource` + `cfnResourceType`, so they work below
+ * aws-cdk-lib 2.231.0) on the L1 resource; the L2 parent is found via
+ * duck-typing on `addAlarmAction`. Actions are attached through
+ * the L2 so that `IAlarmAction.bind()` runs and permissions are wired
+ * correctly. Bare `CfnAlarm` nodes (created without an L2 wrapper) are
+ * detected but silently skipped.
  *
  * `defaults` apply to every matched alarm; `rules` append additional actions.
  * A rule matches if any of its `match` entries matches. Set

package/dist/commonjs/policies/alarm-actions-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-actions-policy.d.ts","sourceRoot":"","sources":["../../../src/policies/alarm-actions-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAuC,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACpG,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,cAAc,EAIpB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE3E,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,uBAAuB,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1C;AAED,uFAAuF;AACvF,MAAM,WAAW,eAAgB,SAAQ,cAAc,EAAE,cAAc;IACrE,iEAAiE;IACjE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,oDAAoD;AACpD,MAAM,WAAW,wBAAwB;IACvC,kGAAkG;IAClG,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,mFAAmF;IACnF,KAAK,CAAC,EAAE,eAAe,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AA4DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAkD5F"}