@composurecdk/ec2 0.7.0 → 0.8.0

package/dist/commonjs/instance-volume-attachments.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVolumeAttachments = createVolumeAttachments;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const aws_ec2_1 = require("aws-cdk-lib/aws-ec2");
+const core_1 = require("@composurecdk/core");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const instance_volume_attachment_defaults_js_1 = require("./instance-volume-attachment-defaults.js");
+const STALLED_IO_PERIOD = aws_cdk_lib_1.Duration.minutes(1);
+const STALLED_IO_PERIOD_LABEL = `${String(STALLED_IO_PERIOD.toMinutes())} minute`;
+function resolveInstanceAz(instanceProps) {
+    if (instanceProps.availabilityZone && !aws_cdk_lib_1.Token.isUnresolved(instanceProps.availabilityZone)) {
+        return instanceProps.availabilityZone;
+    }
+    let selected;
+    try {
+        selected = instanceProps.vpc.selectSubnets(instanceProps.vpcSubnets);
+    }
+    catch {
+        // selectSubnets() throws for several unrelated reasons (no matching subnets,
+        // unresolved tokens, etc.). The validation is best-effort — if we can't
+        // resolve a concrete AZ, fall through and let CFN surface the real failure.
+        return undefined;
+    }
+    return selected.availabilityZones.find((az) => !aws_cdk_lib_1.Token.isUnresolved(az));
+}
+function unwrapVolume(resolved) {
+    if ("volumeId" in resolved) {
+        return resolved;
+    }
+    return resolved.volume;
+}
+function volumeAttachmentMetric(volume, instance, metricName, statistic, period) {
+    return new aws_cloudwatch_1.Metric({
+        namespace: "AWS/EBS",
+        metricName,
+        dimensionsMap: {
+            VolumeId: volume.volumeId,
+            InstanceId: instance.instanceId,
+        },
+        statistic,
+        period,
+    });
+}
+function resolveVolumeAttachmentAlarmDefinitions(attachmentKey, volume, instance, config) {
+    if (config === false)
+        return [];
+    const enabled = config?.enabled ?? instance_volume_attachment_defaults_js_1.VOLUME_ATTACHMENT_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return [];
+    if (config?.volumeStalledIo === false)
+        return [];
+    const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.volumeStalledIo, instance_volume_attachment_defaults_js_1.VOLUME_ATTACHMENT_ALARM_DEFAULTS.volumeStalledIo);
+    return [
+        {
+            key: `${attachmentKey}.volumeStalledIo`,
+            alarmName: cfg.alarmName,
+            metric: volumeAttachmentMetric(volume, instance, "VolumeStalledIOCheck", aws_cloudwatch_1.Stats.MAXIMUM, STALLED_IO_PERIOD),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EBS volume attachment "${attachmentKey}" is reporting a stalled I/O condition. ` +
+                `Threshold: >= ${String(cfg.threshold)} (max) over ${String(cfg.evaluationPeriods)} x ${STALLED_IO_PERIOD_LABEL}. ` +
+                `Note: VolumeStalledIOCheck is published only for Nitro-instance attachments.`,
+        },
+    ];
+}
+/**
+ * Creates a {@link CfnVolumeAttachment} for each pending attachment and
+ * (when configured) the per-attachment recommended alarms. Synth-time AZ
+ * alignment is validated when both the volume's AZ and the instance's
+ * effective AZ are concrete strings.
+ *
+ * @returns The created `CfnVolumeAttachment`s keyed by attachment key,
+ *   plus the per-attachment alarms keyed by `${attachmentKey}.${alarmKey}`
+ *   so they can be flat-merged into the instance's `alarms` record.
+ */
+function createVolumeAttachments(scope, id, instance, instanceProps, attachments, context) {
+    const attachmentRecords = {};
+    const alarmDefinitions = [];
+    // Resolve the instance AZ once — it is the same for every attachment.
+    const instanceAz = attachments.length > 0 ? resolveInstanceAz(instanceProps) : undefined;
+    for (const pending of attachments) {
+        const resolved = (0, core_1.resolve)(pending.volumeRef, context);
+        const volume = unwrapVolume(resolved);
+        if (instanceAz !== undefined && !aws_cdk_lib_1.Token.isUnresolved(volume.availabilityZone)) {
+            if (volume.availabilityZone !== instanceAz) {
+                throw new Error(`attachVolume "${pending.key}": volume is in availability zone "${volume.availabilityZone}" ` +
+                    `but the instance is in "${instanceAz}". ` +
+                    `EBS volumes can only attach to instances in the same AZ.`);
+            }
+        }
+        const attachment = new aws_ec2_1.CfnVolumeAttachment(scope, `${id}${pending.key}Attachment`, {
+            device: pending.options.device,
+            instanceId: instance.instanceId,
+            volumeId: volume.volumeId,
+        });
+        attachmentRecords[pending.key] = attachment;
+        alarmDefinitions.push(...resolveVolumeAttachmentAlarmDefinitions(pending.key, volume, instance, pending.options.recommendedAlarms));
+    }
+    const alarms = alarmDefinitions.length > 0 ? (0, cloudwatch_1.createAlarms)(scope, id, alarmDefinitions) : {};
+    return { attachments: attachmentRecords, alarms };
+}
+//# sourceMappingURL=instance-volume-attachments.js.map

package/dist/commonjs/instance-volume-attachments.js.map

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

package/dist/commonjs/package.json

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-alarm-config.d.ts","sourceRoot":"","sources":["../../src/volume-alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACpC"}

package/dist/commonjs/volume-alarm-config.js

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

package/dist/commonjs/volume-alarm-config.js.map

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/volume-alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,mBAAmB;IAC3B,OAAO,EAAE,IAAI,CAAC;IACd,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAgBnC,CAAC"}

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

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOLUME_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+/**
+ * AWS-recommended default alarm configuration for EBS volumes.
+ *
+ * Thresholds are sourced from the CloudWatch Best Practice Recommended
+ * Alarms guide. Thresholds may reasonably be tuned per-workload; defaults
+ * bias toward catching obvious issues without excessive noise.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EBS
+ */
+exports.VOLUME_ALARM_DEFAULTS = {
+    enabled: true,
+    /**
+     * Burst credit balance is a percentage. Below 20% the volume is
+     * approaching throttling to baseline performance — early warning to
+     * upsize, switch to a non-burstable type (e.g. `gp3`), or investigate
+     * unexpectedly heavy I/O. The 3-of-3 evaluation at 5-minute granularity
+     * suppresses transient dips around backup windows.
+     */
+    burstBalance: {
+        threshold: 20,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 3,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=volume-alarm-defaults.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-alarm-defaults.js","sourceRoot":"","sources":["../../src/volume-alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAQ9D;;;;;;;;GAQG;AACU,QAAA,qBAAqB,GAAwB;IACxD,OAAO,EAAE,IAAI;IAEb;;;;;;OAMG;IACH,YAAY,EAAE;QACZ,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-alarms.d.ts","sourceRoot":"","sources":["../../src/volume-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAqC,MAAM,4BAA4B,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAgB,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AACrF,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,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AA4ClE;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,UAAU,EAAE,mBAAmB,GAAG,SAAS,GAC1C,eAAe,EAAE,CAqBnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,UAAU,EAAE,mBAAmB,GAAG,SAAS,EAC3C,YAAY,GAAE,sBAAsB,CAAC,MAAM,CAAC,EAAO,GAClD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/commonjs/volume-alarms.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVolumeAlarmDefinitions = resolveVolumeAlarmDefinitions;
+exports.createVolumeAlarms = createVolumeAlarms;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const aws_ec2_1 = require("aws-cdk-lib/aws-ec2");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const volume_alarm_defaults_js_1 = require("./volume-alarm-defaults.js");
+/**
+ * BurstBalance is published at 5-minute granularity for burstable volume
+ * types. A shorter period yields missing data rather than higher resolution.
+ *
+ * @see https://docs.aws.amazon.com/ebs/latest/userguide/using_cloudwatch_ebs.html
+ */
+const BURST_METRIC_PERIOD = aws_cdk_lib_1.Duration.minutes(5);
+const BURST_METRIC_PERIOD_LABEL = `${String(BURST_METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * EBS volume types that publish a `BurstBalance` metric. `gp2` accrues IOPS
+ * credits; `st1` and `sc1` accrue throughput credits. Other types
+ * (`gp3`, `io1`, `io2`, `standard`) have no burst credit model.
+ *
+ * @see https://docs.aws.amazon.com/ebs/latest/userguide/using_cloudwatch_ebs.html
+ */
+const BURSTABLE_VOLUME_TYPES = new Set([
+    aws_ec2_1.EbsDeviceVolumeType.GP2,
+    aws_ec2_1.EbsDeviceVolumeType.ST1,
+    aws_ec2_1.EbsDeviceVolumeType.SC1,
+]);
+function isBurstableVolumeType(volumeType) {
+    return volumeType !== undefined && BURSTABLE_VOLUME_TYPES.has(volumeType);
+}
+function volumeMetric(volume, metricName, statistic, period) {
+    return new aws_cloudwatch_1.Metric({
+        namespace: "AWS/EBS",
+        metricName,
+        dimensionsMap: { VolumeId: volume.volumeId },
+        statistic,
+        period,
+    });
+}
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s, applying contextual logic for the
+ * burstable-only credit alarm.
+ */
+function resolveVolumeAlarmDefinitions(volume, config, volumeType) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.burstBalance !== false && isBurstableVolumeType(volumeType)) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.burstBalance, volume_alarm_defaults_js_1.VOLUME_ALARM_DEFAULTS.burstBalance);
+        definitions.push({
+            key: "burstBalance",
+            alarmName: cfg.alarmName,
+            metric: volumeMetric(volume, "BurstBalance", aws_cloudwatch_1.Stats.AVERAGE, BURST_METRIC_PERIOD),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.LESS_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EBS burstable volume burst credit balance is low — baseline-IOPS throttling is imminent. Threshold: < ${String(cfg.threshold)}% (average) over ${String(cfg.evaluationPeriods)} x ${BURST_METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * Creates AWS-recommended CloudWatch alarms for an EBS volume,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param volume - The EBS volume to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param volumeType - Resolved volume type, used to gate the contextual
+ *   burst-balance alarm.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EBS
+ */
+function createVolumeAlarms(scope, id, volume, config, volumeType, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? volume_alarm_defaults_js_1.VOLUME_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveVolumeAlarmDefinitions(volume, config, volumeType);
+    const custom = customAlarms.map((b) => b.resolve(volume));
+    return (0, cloudwatch_1.createAlarms)(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=volume-alarms.js.map

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-builder.d.ts","sourceRoot":"","sources":["../../src/volume-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAIlE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAC9C,WAAW,EACX,kBAAkB,GAAG,eAAe,CACrC;IACC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IAEjC;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAE/E,cAAM,aAAc,YAAW,SAAS,CAAC,mBAAmB,CAAC;;IAC3D,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAM;IAIxC;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,gBAAgB,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI;IAK5D;;;;;;;;OAQG;IACH,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,aAAa,GAAG,IAAI;IAKzC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,mBAAmB;CAkC5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}

package/dist/commonjs/volume-builder.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVolumeBuilder = createVolumeBuilder;
+const aws_ec2_1 = require("aws-cdk-lib/aws-ec2");
+const core_1 = require("@composurecdk/core");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const volume_alarms_js_1 = require("./volume-alarms.js");
+const volume_defaults_js_1 = require("./volume-defaults.js");
+class VolumeBuilder {
+    props = {};
+    #customAlarms = [];
+    #availabilityZone;
+    /**
+     * Sets the Availability Zone the volume will be created in.
+     *
+     * Accepts a concrete AZ string or a {@link Ref} that resolves to one at
+     * build time. This is how cross-component wiring works — e.g., to a
+     * sibling {@link IVpcBuilder} via
+     * `ref<VpcBuilderResult>("network").map(r => r.vpc.availabilityZones[0])`.
+     *
+     * @param availabilityZone - The AZ string or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    availabilityZone(availabilityZone) {
+        this.#availabilityZone = availabilityZone;
+        return this;
+    }
+    /**
+     * Adds a custom CloudWatch alarm to be created alongside the recommended
+     * alarms. The provided callback receives an {@link AlarmDefinitionBuilder}
+     * scoped to the built {@link Volume}; configure it fluently and return it.
+     *
+     * @param key - A unique key for the alarm (used to generate the alarm id).
+     * @param configure - Callback that configures the alarm definition.
+     * @returns This builder for chaining.
+     */
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new cloudwatch_1.AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [core_1.COPY_STATE](target) {
+        target.#availabilityZone = this.#availabilityZone;
+        target.#customAlarms.push(...this.#customAlarms);
+    }
+    build(scope, id, context) {
+        const resolvedAz = this.#availabilityZone
+            ? (0, core_1.resolve)(this.#availabilityZone, context)
+            : undefined;
+        if (resolvedAz === undefined) {
+            throw new Error(`VolumeBuilder "${id}" requires an availability zone. ` +
+                `Call .availabilityZone() with a string or a Ref to one.`);
+        }
+        const { recommendedAlarms: alarmConfig, encryptionKey, ...volumeProps } = this.props;
+        const mergedProps = {
+            ...volume_defaults_js_1.VOLUME_DEFAULTS,
+            ...volumeProps,
+            availabilityZone: resolvedAz,
+            ...(encryptionKey !== undefined ? { encryptionKey: (0, core_1.resolve)(encryptionKey, context) } : {}),
+        };
+        const volume = new aws_ec2_1.Volume(scope, id, mergedProps);
+        const alarms = (0, volume_alarms_js_1.createVolumeAlarms)(scope, id, volume, alarmConfig, mergedProps.volumeType, this.#customAlarms);
+        return { volume, alarms };
+    }
+}
+/**
+ * Creates a new {@link IVolumeBuilder} for configuring an AWS EBS volume.
+ *
+ * This is the entry point for defining an EBS volume component. The
+ * returned builder exposes every {@link VolumeBuilderProps} property as a
+ * fluent setter/getter, plus
+ * {@link IVolumeBuilder.availabilityZone | .availabilityZone()} for
+ * cross-component AZ wiring with Ref support. It implements
+ * {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS EBS volume.
+ *
+ * @example
+ * ```ts
+ * const data = createVolumeBuilder()
+ *   .availabilityZone(ref<VpcBuilderResult>("network").map(r => r.vpc.availabilityZones[0]))
+ *   .size(Size.gibibytes(50));
+ *
+ * // Use standalone:
+ * const result = data.build(stack, "Data", { network });
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { network: createVpcBuilder(), data },
+ *   { network: [], data: ["network"] },
+ * );
+ * ```
+ */
+function createVolumeBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(VolumeBuilder);
+}
+//# sourceMappingURL=volume-builder.js.map

package/dist/commonjs/volume-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"volume-builder.js","sourceRoot":"","sources":["../../src/volume-builder.ts"],"names":[],"mappings":";;AAsOA,kDAEC;AAvOD,iDAA+D;AAG/D,6CAA0F;AAC1F,iEAAkF;AAClF,yDAAkE;AAElE,yDAAwD;AACxD,6DAAuD;AAiHvD,MAAM,aAAa;IACjB,KAAK,GAAgC,EAAE,CAAC;IAC/B,aAAa,GAAqC,EAAE,CAAC;IAC9D,iBAAiB,CAAsB;IAEvC;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,gBAAoC;QACnD,IAAI,CAAC,iBAAiB,GAAG,gBAAgB,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CACN,GAAW,EACX,SAAoF;QAEpF,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,mCAAsB,CAAS,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,CAAC,iBAAU,CAAC,CAAC,MAAqB;QAChC,MAAM,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAClD,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,OAAgC;QACnE,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB;YACvC,CAAC,CAAC,IAAA,cAAO,EAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC;YAC1C,CAAC,CAAC,SAAS,CAAC;QAEd,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,kBAAkB,EAAE,mCAAmC;gBACrD,yDAAyD,CAC5D,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAErF,MAAM,WAAW,GAAG;YAClB,GAAG,oCAAe;YAClB,GAAG,WAAW;YACd,gBAAgB,EAAE,UAAU;YAC5B,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAA,cAAO,EAAC,aAAa,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5E,CAAC;QAEjB,MAAM,MAAM,GAAG,IAAI,gBAAM,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QAElD,MAAM,MAAM,GAAG,IAAA,qCAAkB,EAC/B,KAAK,EACL,EAAE,EACF,MAAM,EACN,WAAW,EACX,WAAW,CAAC,UAAU,EACtB,IAAI,CAAC,aAAa,CACnB,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,mBAAmB;IACjC,OAAO,IAAA,8BAAa,EAAoC,aAAa,CAAC,CAAC;AACzE,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-defaults.d.ts","sourceRoot":"","sources":["../../src/volume-defaults.ts"],"names":[],"mappings":"AACA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,WAAW,CAkChD,CAAC"}

package/dist/commonjs/volume-defaults.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOLUME_DEFAULTS = void 0;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_ec2_1 = require("aws-cdk-lib/aws-ec2");
+/**
+ * Secure, AWS-recommended defaults applied to every EBS volume built with
+ * {@link createVolumeBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ *
+ * Three properties intentionally have no default — they are application-
+ * specific and must be supplied explicitly:
+ *   - `availabilityZone` (via the builder's `.availabilityZone()` method)
+ *   - `size`
+ *   - `iops` / `throughput` (only when opting into a volume type that
+ *     requires them, e.g. `io1`/`io2`)
+ */
+exports.VOLUME_DEFAULTS = {
+    /**
+     * GP3 is the current-generation general-purpose SSD — cheaper and faster
+     * than GP2 at equivalent sizes, and matches the root-volume choice in
+     * {@link INSTANCE_DEFAULTS}.
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/general-purpose.html
+     */
+    volumeType: aws_ec2_1.EbsDeviceVolumeType.GP3,
+    /**
+     * Encrypt the volume at rest. Defaults to the account's default EBS KMS
+     * key; pass an `encryptionKey` to use a customer-managed key (CMK) for
+     * sensitive workloads per SEC08-BP02.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_protect_data_rest_encrypt.html
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html
+     */
+    encrypted: true,
+    /**
+     * When EBS detects inconsistent data on boot it disables I/O until the
+     * operator acknowledges. For a persistent data volume the safer default
+     * is to let I/O resume so the instance can come up unattended; override
+     * to `false` for workloads that prefer to block on potential corruption.
+     * @see https://docs.aws.amazon.com/ebs/latest/userguide/monitoring-volume-events.html
+     */
+    autoEnableIo: true,
+    /**
+     * Mirrors `BUCKET_DEFAULTS.removalPolicy`. A destroyed volume is
+     * unrecoverable; an orphaned volume is a $/month nuisance. Err on the
+     * side of retention — flip to `DESTROY` explicitly for ephemeral data.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_planning_for_recovery_back_up_data.html
+     */
+    removalPolicy: aws_cdk_lib_1.RemovalPolicy.RETAIN,
+};
+//# sourceMappingURL=volume-defaults.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-defaults.js","sourceRoot":"","sources":["../../src/volume-defaults.ts"],"names":[],"mappings":";;;AAAA,6CAA4C;AAC5C,iDAA4E;AAE5E;;;;;;;;;;;GAWG;AACU,QAAA,eAAe,GAAyB;IACnD;;;;;OAKG;IACH,UAAU,EAAE,6BAAmB,CAAC,GAAG;IAEnC;;;;;;OAMG;IACH,SAAS,EAAE,IAAI;IAEf;;;;;;OAMG;IACH,YAAY,EAAE,IAAI;IAElB;;;;;OAKG;IACH,aAAa,EAAE,2BAAa,CAAC,MAAM;CACpC,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-builder.d.ts","sourceRoot":"","sources":["../../src/vpc-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGlF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GACtB,KAAK,GACL;IACE,gFAAgF;IAChF,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;CACvD,CAAC;AAEN;;;;;;GAMG;AACH,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC;IACjE,wFAAwF;IACxF,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,GAAG,CAAC;IAET;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,QAAQ,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;AAItE,cAAM,UAAW,YAAW,SAAS,CAAC,gBAAgB,CAAC;IACrD,KAAK,EAAE,OAAO,CAAC,eAAe,CAAC,CAAM;IAErC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,gBAAgB;CAgBvD;AA2CD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAE9C"}

package/dist/commonjs/vpc-builder.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVpcBuilder = createVpcBuilder;
+const aws_ec2_1 = require("aws-cdk-lib/aws-ec2");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const logs_1 = require("@composurecdk/logs");
+const vpc_defaults_js_1 = require("./vpc-defaults.js");
+const DEFAULT_FLOW_LOG_KEY = "DefaultFlowLog";
+class VpcBuilder {
+    props = {};
+    build(scope, id) {
+        const { flowLogs: flowLogsConfig, ...vpcProps } = this.props;
+        const { flowLogsLogGroup, flowLogProps } = resolveFlowLogs(scope, id, flowLogsConfig);
+        const mergedProps = {
+            ...vpc_defaults_js_1.VPC_DEFAULTS,
+            ...flowLogProps,
+            ...vpcProps,
+        };
+        return {
+            vpc: new aws_ec2_1.Vpc(scope, id, mergedProps),
+            flowLogsLogGroup,
+        };
+    }
+}
+function resolveFlowLogs(scope, id, cfg) {
+    if (cfg === false) {
+        return { flowLogProps: {} };
+    }
+    if (cfg?.destination !== undefined) {
+        if (cfg.configure !== undefined) {
+            throw new Error("flowLogs: 'configure' cannot be combined with 'destination' — " +
+                "the destination is user-managed and not built by this builder.");
+        }
+        return {
+            flowLogProps: {
+                flowLogs: { [DEFAULT_FLOW_LOG_KEY]: { destination: cfg.destination } },
+            },
+        };
+    }
+    let subBuilder = (0, logs_1.createLogGroupBuilder)();
+    if (cfg?.configure) {
+        subBuilder = cfg.configure(subBuilder);
+    }
+    const flowLogsLogGroup = subBuilder.build(scope, `${id}FlowLogsLogGroup`).logGroup;
+    return {
+        flowLogsLogGroup,
+        flowLogProps: {
+            flowLogs: {
+                [DEFAULT_FLOW_LOG_KEY]: {
+                    destination: aws_ec2_1.FlowLogDestination.toCloudWatchLogs(flowLogsLogGroup),
+                },
+            },
+        },
+    };
+}
+/**
+ * Creates a new {@link IVpcBuilder} for configuring an AWS VPC.
+ *
+ * This is the entry point for defining a VPC component. The returned builder
+ * exposes every {@link VpcBuilderProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS VPC.
+ *
+ * @example
+ * ```ts
+ * const network = createVpcBuilder().maxAzs(3).natGateways(3);
+ *
+ * // Use standalone:
+ * const result = network.build(stack, "Network");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { network, server: createInstanceBuilder() },
+ *   { network: [], server: ["network"] },
+ * );
+ * ```
+ */
+function createVpcBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(VpcBuilder);
+}
+//# sourceMappingURL=vpc-builder.js.map

package/dist/commonjs/vpc-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-builder.js","sourceRoot":"","sources":["../../src/vpc-builder.ts"],"names":[],"mappings":";;AAgLA,4CAEC;AAlLD,iDAA6E;AAI7E,iEAAkF;AAClF,6CAAkF;AAClF,uDAAiD;AAmFjD,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAE9C,MAAM,UAAU;IACd,KAAK,GAA6B,EAAE,CAAC;IAErC,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAE7D,MAAM,EAAE,gBAAgB,EAAE,YAAY,EAAE,GAAG,eAAe,CAAC,KAAK,EAAE,EAAE,EAAE,cAAc,CAAC,CAAC;QAEtF,MAAM,WAAW,GAAG;YAClB,GAAG,8BAAY;YACf,GAAG,YAAY;YACf,GAAG,QAAQ;SACZ,CAAC;QAEF,OAAO;YACL,GAAG,EAAE,IAAI,aAAG,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;YACpC,gBAAgB;SACjB,CAAC;IACJ,CAAC;CACF;AAED,SAAS,eAAe,CACtB,KAAiB,EACjB,EAAU,EACV,GAA+B;IAE/B,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QAClB,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;IAC9B,CAAC;IAED,IAAI,GAAG,EAAE,WAAW,KAAK,SAAS,EAAE,CAAC;QACnC,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACb,gEAAgE;gBAC9D,gEAAgE,CACnE,CAAC;QACJ,CAAC;QACD,OAAO;YACL,YAAY,EAAE;gBACZ,QAAQ,EAAE,EAAE,CAAC,oBAAoB,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE;aACvE;SACF,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,GAAG,IAAA,4BAAqB,GAAE,CAAC;IACzC,IAAI,GAAG,EAAE,SAAS,EAAE,CAAC;QACnB,UAAU,GAAG,GAAG,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IACD,MAAM,gBAAgB,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,kBAAkB,CAAC,CAAC,QAAQ,CAAC;IAEnF,OAAO;QACL,gBAAgB;QAChB,YAAY,EAAE;YACZ,QAAQ,EAAE;gBACR,CAAC,oBAAoB,CAAC,EAAE;oBACtB,WAAW,EAAE,4BAAkB,CAAC,gBAAgB,CAAC,gBAAgB,CAAC;iBACnE;aACF;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,gBAAgB;IAC9B,OAAO,IAAA,8BAAa,EAA8B,UAAU,CAAC,CAAC;AAChE,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-defaults.d.ts","sourceRoot":"","sources":["../../src/vpc-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,QAAQ,CA6C1C,CAAC"}

package/dist/commonjs/vpc-defaults.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VPC_DEFAULTS = void 0;
+/**
+ * Secure, cost-conscious defaults applied to every VPC built with
+ * {@link createVpcBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ *
+ * Subnet layout uses CDK defaults (one public + one private-with-egress
+ * subnet per AZ) — override `subnetConfiguration` for custom topologies.
+ *
+ * Flow logs are created separately by the builder (not via this defaults
+ * object) so the destination log group can be auto-managed with
+ * well-architected retention/removal policies.
+ */
+exports.VPC_DEFAULTS = {
+    /**
+     * Two availability zones strike a balance between high availability
+     * and cost. Override to 3+ AZs for production workloads that need
+     * stricter HA guarantees.
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html
+     */
+    maxAzs: 2,
+    /**
+     * Single NAT gateway is a cost-conscious default. Production HA
+     * workloads should override this to match `maxAzs` so a single-AZ
+     * NAT failure does not partition private-subnet egress.
+     * @see https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html
+     */
+    natGateways: 1,
+    /**
+     * Required for internal DNS resolution for most AWS managed services
+     * (ALB, RDS, VPC endpoints). Default-on in AWS but set explicitly for
+     * safety across CDK feature-flag configurations.
+     * @see https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html
+     */
+    enableDnsSupport: true,
+    /**
+     * Required alongside DNS support for instances to receive public DNS
+     * hostnames. Needed for most hostname-based TLS and service discovery
+     * scenarios.
+     * @see https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html
+     */
+    enableDnsHostnames: true,
+    /**
+     * Strip all rules from the default security group. This prevents
+     * accidentally using the default SG (which allows all intra-SG
+     * traffic and no ingress) and forces explicit SG design — a
+     * foundational well-architected security practice.
+     *
+     * Also enabled by the `@aws-cdk/aws-ec2:restrictDefaultSecurityGroup`
+     * feature flag; we set it explicitly so the guarantee holds regardless
+     * of CDK context configuration.
+     * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Vpc.html#restrictdefaultsecuritygroup
+     */
+    restrictDefaultSecurityGroup: true,
+};
+//# sourceMappingURL=vpc-defaults.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-defaults.js","sourceRoot":"","sources":["../../src/vpc-defaults.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACU,QAAA,YAAY,GAAsB;IAC7C;;;;;OAKG;IACH,MAAM,EAAE,CAAC;IAET;;;;;OAKG;IACH,WAAW,EAAE,CAAC;IAEd;;;;;OAKG;IACH,gBAAgB,EAAE,IAAI;IAEtB;;;;;OAKG;IACH,kBAAkB,EAAE,IAAI;IAExB;;;;;;;;;;OAUG;IACH,4BAA4B,EAAE,IAAI;CACnC,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,14 @@
+export { createInstanceBuilder, type IInstanceBuilder, type InstanceBuilderProps, type InstanceBuilderResult, } from "./instance-builder.js";
+export { INSTANCE_DEFAULTS } from "./instance-defaults.js";
+export { type InstanceAlarmConfig } from "./instance-alarm-config.js";
+export { INSTANCE_ALARM_DEFAULTS } from "./instance-alarm-defaults.js";
+export { type AttachVolumeOptions } from "./instance-volume-attachments.js";
+export { type VolumeAttachmentAlarmConfig } from "./instance-volume-attachment-config.js";
+export { VOLUME_ATTACHMENT_ALARM_DEFAULTS } from "./instance-volume-attachment-defaults.js";
+export { createVolumeBuilder, type IVolumeBuilder, type VolumeBuilderProps, type VolumeBuilderResult, } from "./volume-builder.js";
+export { VOLUME_DEFAULTS } from "./volume-defaults.js";
+export { type VolumeAlarmConfig } from "./volume-alarm-config.js";
+export { VOLUME_ALARM_DEFAULTS } from "./volume-alarm-defaults.js";
+export { createVpcBuilder, type FlowLogsConfig, type IVpcBuilder, type VpcBuilderProps, type VpcBuilderResult, } from "./vpc-builder.js";
+export { VPC_DEFAULTS } from "./vpc-defaults.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AAC1F,OAAO,EAAE,gCAAgC,EAAE,MAAM,0CAA0C,CAAC;AAE5F,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAItB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EAAE,gCAAgC,EAAE,MAAM,0CAA0C,CAAC;AAE5F,OAAO,EACL,mBAAmB,GAIpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EACL,gBAAgB,GAKjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}