@composurecdk/s3 0.7.0 → 0.8.0

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,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEnC;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACpC"}

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/commonjs/alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/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;IAClC,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAkBnC,CAAC"}

package/dist/commonjs/alarm-defaults.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUCKET_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+/**
+ * AWS-recommended default alarm configuration for S3 buckets.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+ */
+exports.BUCKET_ALARM_DEFAULTS = {
+    enabled: true,
+    /** Any server-side error is worth investigating; threshold 0. */
+    serverErrors: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** Any client-side error pattern is worth investigating; threshold 0. */
+    clientErrors: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=alarm-defaults.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAS9D;;;;GAIG;AACU,QAAA,qBAAqB,GAAwB;IACxD,OAAO,EAAE,IAAI;IAEb,iEAAiE;IACjE,YAAY,EAAE;QACZ,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,yEAAyE;IACzE,YAAY,EAAE;QACZ,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-alarms.d.ts","sourceRoot":"","sources":["../../src/bucket-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAqC,MAAM,4BAA4B,CAAC;AAC3F,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AA2B3D;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,cAAc,EAAE,aAAa,EAAE,GAC9B,eAAe,EAAE,CAyCnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,cAAc,EAAE,aAAa,EAAE,EAC/B,YAAY,GAAE,sBAAsB,CAAC,MAAM,CAAC,EAAO,GAClD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/commonjs/bucket-alarms.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBucketAlarmDefinitions = resolveBucketAlarmDefinitions;
+exports.createBucketAlarms = createBucketAlarms;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const alarm_defaults_js_1 = require("./alarm-defaults.js");
+const METRIC_PERIOD = aws_cdk_lib_1.Duration.minutes(5);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minutes`;
+/**
+ * Creates an S3 request metric with the correct namespace and dimensions.
+ */
+function s3RequestMetric(bucket, filterId, metricName, statistic) {
+    return new aws_cloudwatch_1.Metric({
+        namespace: "AWS/S3",
+        metricName,
+        dimensionsMap: {
+            BucketName: bucket.bucketName,
+            FilterId: filterId,
+        },
+        statistic,
+        period: METRIC_PERIOD,
+    });
+}
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an S3 bucket.
+ *
+ * Creates alarms for each entry in `metricsConfigs`, keyed as
+ * `{alarmType}:{filterId}` (e.g. `serverErrors:EntireBucket`).
+ */
+function resolveBucketAlarmDefinitions(bucket, config, metricsConfigs) {
+    if (config?.enabled === false)
+        return [];
+    if (metricsConfigs.length === 0)
+        return [];
+    const definitions = [];
+    for (const metrics of metricsConfigs) {
+        const filterId = metrics.id;
+        if (config?.serverErrors !== false) {
+            const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.serverErrors, alarm_defaults_js_1.BUCKET_ALARM_DEFAULTS.serverErrors);
+            definitions.push({
+                key: `serverErrors:${filterId}`,
+                alarmName: cfg.alarmName,
+                metric: s3RequestMetric(bucket, filterId, "5xxErrors", aws_cloudwatch_1.Stats.SUM),
+                threshold: cfg.threshold,
+                comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+                evaluationPeriods: cfg.evaluationPeriods,
+                datapointsToAlarm: cfg.datapointsToAlarm,
+                treatMissingData: cfg.treatMissingData,
+                description: `S3 bucket is returning server-side errors (filter: ${filterId}). Threshold: > ${String(cfg.threshold)} 5xx errors in ${METRIC_PERIOD_LABEL}.`,
+            });
+        }
+        if (config?.clientErrors !== false) {
+            const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.clientErrors, alarm_defaults_js_1.BUCKET_ALARM_DEFAULTS.clientErrors);
+            definitions.push({
+                key: `clientErrors:${filterId}`,
+                alarmName: cfg.alarmName,
+                metric: s3RequestMetric(bucket, filterId, "4xxErrors", aws_cloudwatch_1.Stats.SUM),
+                threshold: cfg.threshold,
+                comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+                evaluationPeriods: cfg.evaluationPeriods,
+                datapointsToAlarm: cfg.datapointsToAlarm,
+                treatMissingData: cfg.treatMissingData,
+                description: `S3 bucket is returning client-side errors (filter: ${filterId}). Threshold: > ${String(cfg.threshold)} 4xx errors in ${METRIC_PERIOD_LABEL}.`,
+            });
+        }
+    }
+    return definitions;
+}
+/**
+ * Creates AWS-recommended CloudWatch alarms for an S3 bucket,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * Alarms are created for each entry in `metricsConfigs` (from
+ * {@link BucketProps.metrics}). If no metrics configurations are
+ * provided, only custom alarms are created.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param bucket - The S3 bucket to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param metricsConfigs - The bucket's request metrics configurations.
+ * @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#S3
+ */
+function createBucketAlarms(scope, id, bucket, config, metricsConfigs, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? alarm_defaults_js_1.BUCKET_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveBucketAlarmDefinitions(bucket, config, metricsConfigs);
+    const custom = customAlarms.map((b) => b.resolve(bucket));
+    return (0, cloudwatch_1.createAlarms)(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=bucket-alarms.js.map

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-builder.d.ts","sourceRoot":"","sources":["../../src/bucket-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAC9B,KAAK,GACL;IACE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,cAAc,CAAC;CACnD,CAAC;AAEN;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAC9C,WAAW,EACX,wBAAwB,GAAG,wBAAwB,CACpD;IACC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAE1C;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;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;IAGxC,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;IAIzC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,mBAAmB;CA+B1D;AAgED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}

package/dist/commonjs/bucket-builder.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBucketBuilder = createBucketBuilder;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_s3_1 = require("aws-cdk-lib/aws-s3");
+const core_1 = require("@composurecdk/core");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const bucket_alarms_js_1 = require("./bucket-alarms.js");
+const defaults_js_1 = require("./defaults.js");
+class BucketBuilder {
+    props = {};
+    #customAlarms = [];
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new cloudwatch_1.AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [core_1.COPY_STATE](target) {
+        target.#customAlarms.push(...this.#customAlarms);
+    }
+    build(scope, id) {
+        const { serverAccessLogs, recommendedAlarms: alarmConfig, ...bucketProps } = this.props;
+        const { serverAccessLogs: defaultServerAccessLogs, ...cdkDefaults } = defaults_js_1.BUCKET_DEFAULTS;
+        const cfg = serverAccessLogs ?? defaultServerAccessLogs;
+        const { accessLogsBucket, accessLogProps } = resolveAccessLogs(scope, id, cfg);
+        const mergedProps = {
+            ...cdkDefaults,
+            ...accessLogProps,
+            ...bucketProps,
+            ...autoDeleteProps(bucketProps, defaults_js_1.BUCKET_DEFAULTS),
+        };
+        const bucket = new aws_s3_1.Bucket(scope, id, mergedProps);
+        const alarms = (0, bucket_alarms_js_1.createBucketAlarms)(scope, id, bucket, alarmConfig, bucketProps.metrics ?? [], this.#customAlarms);
+        return {
+            bucket,
+            accessLogsBucket,
+            alarms,
+        };
+    }
+}
+function resolveAccessLogs(scope, id, cfg) {
+    if (cfg === false || cfg === undefined) {
+        return { accessLogProps: {} };
+    }
+    if (cfg.destination !== undefined) {
+        if (cfg.configure !== undefined) {
+            throw new Error("serverAccessLogs: 'configure' cannot be combined with 'destination' — " +
+                "the destination bucket is user-managed and not built by this builder.");
+        }
+        return {
+            accessLogProps: {
+                serverAccessLogsBucket: cfg.destination,
+                ...(cfg.prefix !== undefined ? { serverAccessLogsPrefix: cfg.prefix } : {}),
+            },
+        };
+    }
+    let subBuilder = createBucketBuilder()
+        .serverAccessLogs(false)
+        .versioned(false)
+        .removalPolicy(aws_cdk_lib_1.RemovalPolicy.RETAIN)
+        .lifecycleRules(defaults_js_1.DEFAULT_ACCESS_LOG_BUCKET_LIFECYCLE_RULES);
+    if (cfg.configure) {
+        subBuilder = cfg.configure(subBuilder);
+    }
+    const accessLogsBucket = subBuilder.build(scope, `${id}AccessLogs`).bucket;
+    return {
+        accessLogsBucket,
+        accessLogProps: {
+            serverAccessLogsBucket: accessLogsBucket,
+            ...(cfg.prefix !== undefined ? { serverAccessLogsPrefix: cfg.prefix } : {}),
+        },
+    };
+}
+/**
+ * Returns `{ autoDeleteObjects: true }` when the effective removal policy is
+ * `DESTROY` and the user has not explicitly set `autoDeleteObjects`.
+ *
+ * CDK requires `autoDeleteObjects` to be paired with `removalPolicy: DESTROY`,
+ * but forgetting it causes a non-empty-bucket error on stack deletion. This
+ * helper bridges that gap so that switching to `DESTROY` Just Works.
+ */
+function autoDeleteProps(userProps, defaults) {
+    const effectivePolicy = userProps.removalPolicy ?? defaults.removalPolicy;
+    if (effectivePolicy === aws_cdk_lib_1.RemovalPolicy.DESTROY && userProps.autoDeleteObjects === undefined) {
+        return { autoDeleteObjects: true };
+    }
+    return {};
+}
+/**
+ * Creates a new {@link IBucketBuilder} for configuring an Amazon S3 bucket.
+ *
+ * This is the entry point for defining an S3 bucket component. The returned
+ * builder exposes every {@link BucketProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an Amazon S3 bucket.
+ *
+ * @example
+ * ```ts
+ * const site = createBucketBuilder()
+ *   .bucketName("my-site")
+ *   .versioned(false);
+ *
+ * // Use standalone:
+ * const result = site.build(stack, "SiteBucket");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { site, cdn: createDistributionBuilder() },
+ *   { site: [], cdn: ["site"] },
+ * );
+ * ```
+ */
+function createBucketBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(BucketBuilder);
+}
+//# sourceMappingURL=bucket-builder.js.map

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

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

package/dist/commonjs/bucket-deployment-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-deployment-builder.d.ts","sourceRoot":"","sources":["../../src/bucket-deployment-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAA8B,MAAM,+BAA+B,CAAC;AAC7F,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,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;AAGlF,OAAO,EAAE,KAAK,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,iEAAiE;IACjE,UAAU,EAAE,gBAAgB,CAAC;IAE7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,wBAAwB,GAAG,cAAc,CACnD,4BAA4B,EAC5B,uBAAuB,CACxB,CAAC;AAEF,cAAM,uBAAwB,YAAW,SAAS,CAAC,6BAA6B,CAAC;;IAC/E,KAAK,EAAE,OAAO,CAAC,4BAA4B,CAAC,CAAM;IAIlD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI;IAKpD;;;;;;;;;OASG;IACH,YAAY,CAAC,YAAY,EAAE,UAAU,CAAC,aAAa,CAAC,GAAG,IAAI;IAK3D,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI;IAKnD,KAAK,CACH,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,6BAA6B;CAiDjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,6BAA6B,IAAI,wBAAwB,CAIxE"}

package/dist/commonjs/bucket-deployment-builder.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBucketDeploymentBuilder = createBucketDeploymentBuilder;
+const aws_s3_deployment_1 = require("aws-cdk-lib/aws-s3-deployment");
+const core_1 = require("@composurecdk/core");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const logs_1 = require("@composurecdk/logs");
+const bucket_deployment_defaults_js_1 = require("./bucket-deployment-defaults.js");
+class BucketDeploymentBuilder {
+    props = {};
+    #destinationBucket;
+    #distribution;
+    /**
+     * Sets the destination bucket for the deployment.
+     *
+     * Accepts a concrete {@link IBucket} or a {@link Ref} that resolves to one
+     * at build time.
+     *
+     * @param bucket - The bucket or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    destinationBucket(bucket) {
+        this.#destinationBucket = bucket;
+        return this;
+    }
+    /**
+     * Sets the CloudFront distribution to invalidate on deployment.
+     *
+     * Accepts a concrete {@link IDistribution} or a {@link Ref} that resolves
+     * to one at build time. This is optional — deployments can target a bucket
+     * without CloudFront invalidation.
+     *
+     * @param distribution - The distribution or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    distribution(distribution) {
+        this.#distribution = distribution;
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [core_1.COPY_STATE](target) {
+        target.#destinationBucket = this.#destinationBucket;
+        target.#distribution = this.#distribution;
+    }
+    build(scope, id, context) {
+        const ctx = context ?? {};
+        const resolvedBucket = this.#destinationBucket
+            ? (0, core_1.resolve)(this.#destinationBucket, ctx)
+            : undefined;
+        if (!resolvedBucket) {
+            throw new Error(`BucketDeploymentBuilder "${id}" requires a destination bucket. ` +
+                `Call .destinationBucket() with an IBucket or a Ref to one.`);
+        }
+        const { sources, ...deployProps } = this.props;
+        if (!sources || sources.length === 0) {
+            throw new Error(`BucketDeploymentBuilder "${id}" requires at least one source. ` +
+                `Call .sources() with an array of ISource.`);
+        }
+        const resolvedDistribution = this.#distribution ? (0, core_1.resolve)(this.#distribution, ctx) : undefined;
+        // Auto-create a managed LogGroup for the deployment's backing Lambda
+        // unless the user supplied their own, matching the Lambda builder pattern.
+        let logGroup;
+        let logGroupProps = {};
+        if (!deployProps.logGroup) {
+            logGroup = (0, logs_1.createLogGroupBuilder)().build(scope, `${id}LogGroup`).logGroup;
+            logGroupProps = { logGroup };
+        }
+        const mergedProps = {
+            ...(0, bucket_deployment_defaults_js_1.effectiveDefaults)(!!resolvedDistribution),
+            ...logGroupProps,
+            ...deployProps,
+            ...(resolvedDistribution ? { distribution: resolvedDistribution } : {}),
+            sources,
+            destinationBucket: resolvedBucket,
+        };
+        return {
+            deployment: new aws_s3_deployment_1.BucketDeployment(scope, id, mergedProps),
+            logGroup,
+        };
+    }
+}
+/**
+ * Creates a new {@link IBucketDeploymentBuilder} for deploying content to an
+ * S3 bucket with optional CloudFront cache invalidation.
+ *
+ * This is the entry point for defining an S3 deployment component. The
+ * returned builder exposes {@link BucketDeploymentBuilderProps} properties as
+ * fluent setters/getters, plus {@link IBucketDeploymentBuilder.destinationBucket | destinationBucket()}
+ * and {@link IBucketDeploymentBuilder.distribution | distribution()} for
+ * cross-component wiring with Ref support. It implements {@link Lifecycle}
+ * for use with {@link compose}.
+ *
+ * @returns A fluent builder for an S3 BucketDeployment.
+ *
+ * @example
+ * ```ts
+ * const deploy = createBucketDeploymentBuilder()
+ *   .sources([Source.asset("./site")])
+ *   .destinationBucket(ref("site", (r: BucketBuilderResult) => r.bucket))
+ *   .distribution(ref("cdn", (r: DistributionBuilderResult) => r.distribution))
+ *   .distributionPaths(["/*"]);
+ *
+ * // Use standalone:
+ * const result = deploy.build(stack, "Deploy");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { site: createBucketBuilder(), cdn: createDistributionBuilder(), deploy },
+ *   { site: [], cdn: ["site"], deploy: ["site", "cdn"] },
+ * );
+ * ```
+ */
+function createBucketDeploymentBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(BucketDeploymentBuilder);
+}
+//# sourceMappingURL=bucket-deployment-builder.js.map

package/dist/commonjs/bucket-deployment-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-deployment-builder.js","sourceRoot":"","sources":["../../src/bucket-deployment-builder.ts"],"names":[],"mappings":";;AA0LA,sEAIC;AA9LD,qEAA6F;AAK7F,6CAA0F;AAC1F,iEAAkF;AAClF,6CAA2D;AAC3D,mFAAoE;AAoDpE,MAAM,uBAAuB;IAC3B,KAAK,GAA0C,EAAE,CAAC;IAClD,kBAAkB,CAAuB;IACzC,aAAa,CAA6B;IAE1C;;;;;;;;OAQG;IACH,iBAAiB,CAAC,MAA2B;QAC3C,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;OASG;IACH,YAAY,CAAC,YAAuC;QAClD,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,CAAC,iBAAU,CAAC,CAAC,MAA+B;QAC1C,MAAM,CAAC,kBAAkB,GAAG,IAAI,CAAC,kBAAkB,CAAC;QACpD,MAAM,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;IAC5C,CAAC;IAED,KAAK,CACH,KAAiB,EACjB,EAAU,EACV,OAAgC;QAEhC,MAAM,GAAG,GAAG,OAAO,IAAI,EAAE,CAAC;QAE1B,MAAM,cAAc,GAAG,IAAI,CAAC,kBAAkB;YAC5C,CAAC,CAAC,IAAA,cAAO,EAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,CAAC;YACvC,CAAC,CAAC,SAAS,CAAC;QAEd,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,4BAA4B,EAAE,mCAAmC;gBAC/D,4DAA4D,CAC/D,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAE/C,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACb,4BAA4B,EAAE,kCAAkC;gBAC9D,2CAA2C,CAC9C,CAAC;QACJ,CAAC;QAED,MAAM,oBAAoB,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAA,cAAO,EAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE/F,qEAAqE;QACrE,2EAA2E;QAC3E,IAAI,QAA8B,CAAC;QACnC,IAAI,aAAa,GAAG,EAAE,CAAC;QAEvB,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;YAC1B,QAAQ,GAAG,IAAA,4BAAqB,GAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC;YAC1E,aAAa,GAAG,EAAE,QAAQ,EAAE,CAAC;QAC/B,CAAC;QAED,MAAM,WAAW,GAAG;YAClB,GAAG,IAAA,iDAAiB,EAAC,CAAC,CAAC,oBAAoB,CAAC;YAC5C,GAAG,aAAa;YAChB,GAAG,WAAW;YACd,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,OAAO;YACP,iBAAiB,EAAE,cAAc;SACT,CAAC;QAE3B,OAAO;YACL,UAAU,EAAE,IAAI,oCAAgB,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;YACxD,QAAQ;SACT,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,SAAgB,6BAA6B;IAC3C,OAAO,IAAA,8BAAa,EAClB,uBAAuB,CACxB,CAAC;AACJ,CAAC"}

package/dist/commonjs/bucket-deployment-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-deployment-defaults.d.ts","sourceRoot":"","sources":["../../src/bucket-deployment-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAmDjF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGtC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,OAAO,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAEjG"}

package/dist/commonjs/bucket-deployment-defaults.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUCKET_DEPLOYMENT_DEFAULTS = void 0;
+exports.effectiveDefaults = effectiveDefaults;
+/**
+ * Defaults that apply regardless of whether a CloudFront distribution is
+ * present. Split from distribution-specific defaults so the builder can
+ * merge without runtime filtering.
+ */
+const BASE_DEFAULTS = {
+    /**
+     * Remove files from the destination bucket that are not present in the
+     * source, keeping the bucket in sync with the deployed assets and
+     * preventing stale content from being served.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/operational-excellence-pillar/ops_evolve_ops_learned_from_experience.html
+     */
+    prune: true,
+    /**
+     * Allocate 256 MiB to the deployment Lambda. The CDK default of 128 MiB
+     * is insufficient for deployments with more than a handful of files and
+     * can cause silent failures or timeouts.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_withstand_component_failures_avoid_hard_coded_limits.html
+     * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment-readme.html#memory-limit
+     */
+    memoryLimit: 256,
+    /**
+     * Do not retain deployed files when the stack is deleted. This aligns
+     * with `prune: true` semantics — the deployment keeps the bucket in
+     * sync with the source, so retaining stale files on deletion is
+     * inconsistent. The destination bucket's own removal policy governs
+     * whether the bucket itself is retained.
+     * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeploymentProps.html#retainondelete
+     */
+    retainOnDelete: false,
+};
+/**
+ * Defaults that only apply when a CloudFront distribution is configured.
+ * CDK throws if `distributionPaths` is set without a distribution.
+ */
+const DISTRIBUTION_DEFAULTS = {
+    /**
+     * Invalidate all paths by default so that deployed content is immediately
+     * visible through CloudFront. Uses a wildcard path which counts as a
+     * single invalidation path. For deployments that only change a subset of
+     * files, override with specific paths to reduce origin fetches.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_withstand_component_failures_static_stability.html
+     */
+    distributionPaths: ["/*"],
+};
+/**
+ * Secure, AWS-recommended defaults applied to every S3 BucketDeployment
+ * built with {@link createBucketDeploymentBuilder}. Each property can be
+ * individually overridden via the builder's fluent API.
+ */
+exports.BUCKET_DEPLOYMENT_DEFAULTS = {
+    ...BASE_DEFAULTS,
+    ...DISTRIBUTION_DEFAULTS,
+};
+/**
+ * Returns the appropriate defaults based on whether a CloudFront
+ * distribution is present. CDK throws if `distributionPaths` is set
+ * without a distribution, so distribution-specific defaults are only
+ * included when applicable.
+ */
+function effectiveDefaults(hasDistribution) {
+    return hasDistribution ? { ...BASE_DEFAULTS, ...DISTRIBUTION_DEFAULTS } : BASE_DEFAULTS;
+}
+//# sourceMappingURL=bucket-deployment-defaults.js.map

package/dist/commonjs/bucket-deployment-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-deployment-defaults.js","sourceRoot":"","sources":["../../src/bucket-deployment-defaults.ts"],"names":[],"mappings":";;;AAmEA,8CAEC;AAnED;;;;GAIG;AACH,MAAM,aAAa,GAA0C;IAC3D;;;;;OAKG;IACH,KAAK,EAAE,IAAI;IAEX;;;;;;OAMG;IACH,WAAW,EAAE,GAAG;IAEhB;;;;;;;OAOG;IACH,cAAc,EAAE,KAAK;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,qBAAqB,GAA0C;IACnE;;;;;;OAMG;IACH,iBAAiB,EAAE,CAAC,IAAI,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACU,QAAA,0BAA0B,GAAG;IACxC,GAAG,aAAa;IAChB,GAAG,qBAAqB;CACzB,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,eAAwB;IACxD,OAAO,eAAe,CAAC,CAAC,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,qBAAqB,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;AAC1F,CAAC"}

package/dist/commonjs/bucket-deployment-props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-deployment-props.d.ts","sourceRoot":"","sources":["../../src/bucket-deployment-props.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAEpF;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA6B,SAAQ,IAAI,CACxD,qBAAqB,EACrB,SAAS,GAAG,mBAAmB,GAAG,cAAc,CACjD;IACC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;CACrB"}

package/dist/commonjs/bucket-deployment-props.js

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

package/dist/commonjs/bucket-deployment-props.js.map

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE7F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAe9D;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,EAAE,aAAa,EAczD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yCAAyC,EAAE,aAAa,EAMpE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,kBAAkB,CA6DvD,CAAC"}

package/dist/commonjs/defaults.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUCKET_DEFAULTS = exports.DEFAULT_ACCESS_LOG_BUCKET_LIFECYCLE_RULES = exports.DEFAULT_BUCKET_LIFECYCLE_RULES = void 0;
+const aws_s3_1 = require("aws-cdk-lib/aws-s3");
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+/**
+ * Aborts multipart uploads that have not completed within 7 days. AWS recommends
+ * this rule on every bucket — orphaned upload parts are billed as storage but
+ * never become objects, so the rule is pure cost hygiene with no functional
+ * downside.
+ *
+ * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpu-abort-incomplete-mpu-lifecycle-config.html
+ */
+const ABORT_INCOMPLETE_MULTIPART_UPLOADS = {
+    id: "AbortIncompleteMultipartUploadAfter7Days",
+    abortIncompleteMultipartUploadAfter: aws_cdk_lib_1.Duration.days(7),
+};
+/**
+ * Lifecycle rules applied to general-purpose buckets built with
+ * {@link createBucketBuilder}. Bounds storage cost from orphaned multipart
+ * parts and from accumulated noncurrent versions of objects in versioned
+ * buckets, while preserving a generous recovery window.
+ *
+ * Users who need different rules can override the entire set via the
+ * `.lifecycleRules([...])` builder method.
+ */
+exports.DEFAULT_BUCKET_LIFECYCLE_RULES = [
+    ABORT_INCOMPLETE_MULTIPART_UPLOADS,
+    {
+        /**
+         * Buckets default to `versioned: true`, so replaced and deleted objects
+         * accumulate as noncurrent versions indefinitely. Expiring them after a
+         * year preserves a long recovery window for "oops" deletions while
+         * preventing unbounded storage growth.
+         *
+         * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-configuration-examples.html
+         */
+        id: "ExpireNoncurrentVersionsAfter365Days",
+        noncurrentVersionExpiration: aws_cdk_lib_1.Duration.days(365),
+    },
+];
+/**
+ * Lifecycle rules applied to auto-created S3 server access log buckets and
+ * CloudFront access log buckets. Mirrors the 2-year retention used by
+ * {@link LOG_GROUP_DEFAULTS} so the audit window is consistent across log
+ * destinations in the library.
+ *
+ * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+ */
+exports.DEFAULT_ACCESS_LOG_BUCKET_LIFECYCLE_RULES = [
+    ABORT_INCOMPLETE_MULTIPART_UPLOADS,
+    {
+        id: "ExpireAccessLogsAfter2Years",
+        expiration: aws_cdk_lib_1.Duration.days(731),
+    },
+];
+/**
+ * Secure, AWS-recommended defaults applied to every S3 bucket built
+ * with {@link createBucketBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+exports.BUCKET_DEFAULTS = {
+    /**
+     * Auto-create a dedicated logging bucket and write S3 server access logs
+     * to it under the `logs/` prefix. Access logging provides an audit trail
+     * of all object-level operations for security monitoring and
+     * troubleshooting.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+     */
+    serverAccessLogs: { prefix: "logs/" },
+    /**
+     * Block all public access to the bucket. S3 buckets should not be
+     * publicly accessible unless explicitly required (e.g. static website
+     * hosting via CloudFront OAC).
+     * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html
+     */
+    blockPublicAccess: aws_s3_1.BlockPublicAccess.BLOCK_ALL,
+    /**
+     * Enable server-side encryption with S3-managed keys (SSE-S3).
+     * This is the default and lowest-cost encryption option.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/protecting-data-at-rest.html
+     */
+    encryption: aws_s3_1.BucketEncryption.S3_MANAGED,
+    /**
+     * Enforce SSL/TLS for all requests to the bucket.
+     * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html
+     */
+    enforceSSL: true,
+    /**
+     * Enable versioning to protect against accidental deletions and
+     * support rollback.
+     * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html
+     */
+    versioned: true,
+    /**
+     * Bound storage cost on every bucket: abort orphaned multipart uploads
+     * after 7 days and expire noncurrent object versions after 365 days.
+     *
+     * Override with `.lifecycleRules([...])` to supply your own rule set —
+     * the array is replaced wholesale, consistent with how every other
+     * builder default is overridden.
+     *
+     * @see {@link DEFAULT_BUCKET_LIFECYCLE_RULES}
+     */
+    lifecycleRules: exports.DEFAULT_BUCKET_LIFECYCLE_RULES,
+    /**
+     * Retain the bucket on stack deletion to prevent data loss.
+     *
+     * When overridden to `RemovalPolicy.DESTROY`, the builder automatically
+     * enables `autoDeleteObjects` (unless explicitly set to `false`) so that
+     * non-empty buckets can be cleanly removed during stack deletion.
+     *
+     * @see https://docs.aws.amazon.com/cdk/v2/guide/resources.html#resources_removal
+     */
+    removalPolicy: aws_cdk_lib_1.RemovalPolicy.RETAIN,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/commonjs/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":";;;AAAA,+CAA6F;AAC7F,6CAAsD;AAGtD;;;;;;;GAOG;AACH,MAAM,kCAAkC,GAAkB;IACxD,EAAE,EAAE,0CAA0C;IAC9C,mCAAmC,EAAE,sBAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;CACtD,CAAC;AAEF;;;;;;;;GAQG;AACU,QAAA,8BAA8B,GAAoB;IAC7D,kCAAkC;IAClC;QACE;;;;;;;WAOG;QACH,EAAE,EAAE,sCAAsC;QAC1C,2BAA2B,EAAE,sBAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;KAChD;CACF,CAAC;AAEF;;;;;;;GAOG;AACU,QAAA,yCAAyC,GAAoB;IACxE,kCAAkC;IAClC;QACE,EAAE,EAAE,6BAA6B;QACjC,UAAU,EAAE,sBAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;KAC/B;CACF,CAAC;AAEF;;;;GAIG;AACU,QAAA,eAAe,GAAgC;IAC1D;;;;;;;OAOG;IACH,gBAAgB,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;IAErC;;;;;OAKG;IACH,iBAAiB,EAAE,0BAAiB,CAAC,SAAS;IAE9C;;;;OAIG;IACH,UAAU,EAAE,yBAAgB,CAAC,UAAU;IAEvC;;;OAGG;IACH,UAAU,EAAE,IAAI;IAEhB;;;;OAIG;IACH,SAAS,EAAE,IAAI;IAEf;;;;;;;;;OASG;IACH,cAAc,EAAE,sCAA8B;IAE9C;;;;;;;;OAQG;IACH,aAAa,EAAE,2BAAa,CAAC,MAAM;CACpC,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,yCAAyC,EACzC,8BAA8B,GAC/B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EACL,6BAA6B,EAC7B,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,GAC9B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,KAAK,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AACjF,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}