@composurecdk/s3 0.1.2

package/dist/bucket-builder.d.ts

@@ -0,0 +1,103 @@
+import { Bucket, type BucketProps } from "aws-cdk-lib/aws-s3";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle } from "@composurecdk/core";
+/**
+ * Configuration properties for the S3 bucket builder.
+ *
+ * Extends the CDK {@link BucketProps} with additional builder-specific options.
+ */
+export interface BucketBuilderProps extends BucketProps {
+    /**
+     * Whether to automatically create an S3 access logging bucket.
+     *
+     * When `true`, the builder creates a dedicated logging bucket using
+     * {@link createBucketBuilder} (with secure defaults appropriate for log
+     * storage) and configures it as the server access logs destination. The
+     * logging bucket inherits secure defaults (block public access, encryption,
+     * enforceSSL, versioning for log integrity) with `removalPolicy: RETAIN`
+     * and access logging disabled to avoid recursion. The created logging
+     * bucket is returned in the build result as `accessLogsBucket`.
+     *
+     * When `false`, no logging bucket is created. You can still provide your
+     * own destination via `serverAccessLogsBucket`.
+     *
+     * This setting is ignored when `serverAccessLogsBucket` is provided — the
+     * user-supplied destination takes precedence.
+     */
+    accessLogging?: boolean;
+    /**
+     * The prefix applied to server access log object keys when the builder
+     * auto-creates a logging bucket.
+     *
+     * This setting is only used when {@link accessLogging} is `true` and no
+     * user-provided `serverAccessLogsBucket` is set.
+     *
+     * @default "logs/"
+     */
+    accessLogsPrefix?: string;
+}
+/**
+ * The build output of a {@link IBucketBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface BucketBuilderResult {
+    /** The S3 bucket construct created by the builder. */
+    bucket: Bucket;
+    /**
+     * The S3 bucket created for access logging, or `undefined` if access
+     * logging was disabled or the user provided their own destination.
+     */
+    accessLogsBucket?: Bucket;
+}
+/**
+ * A fluent builder for configuring and creating an Amazon S3 bucket.
+ *
+ * Each configuration property from the CDK {@link BucketProps} is exposed
+ * as an overloaded method: call with a value to set it (returns the builder
+ * for chaining), or call with no arguments to read the current value.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * an S3 bucket with the configured properties and returns a
+ * {@link BucketBuilderResult}.
+ *
+ * @example
+ * ```ts
+ * const site = createBucketBuilder()
+ *   .bucketName("my-website-bucket")
+ *   .versioned(false);
+ * ```
+ */
+export type IBucketBuilder = IBuilder<BucketBuilderProps, BucketBuilder>;
+declare class BucketBuilder implements Lifecycle<BucketBuilderResult> {
+    props: Partial<BucketBuilderProps>;
+    build(scope: IConstruct, id: string): BucketBuilderResult;
+}
+/**
+ * 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"] },
+ * );
+ * ```
+ */
+export declare function createBucketBuilder(): IBucketBuilder;
+export {};
+//# sourceMappingURL=bucket-builder.d.ts.map

package/dist/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,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG5E;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAEzE,cAAM,aAAc,YAAW,SAAS,CAAC,mBAAmB,CAAC;IAC3D,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAM;IAExC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,mBAAmB;CA4C1D;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}

package/dist/bucket-builder.js

@@ -0,0 +1,83 @@
+import { RemovalPolicy } from "aws-cdk-lib";
+import { Bucket } from "aws-cdk-lib/aws-s3";
+import { Builder } from "@composurecdk/core";
+import { BUCKET_DEFAULTS } from "./defaults.js";
+class BucketBuilder {
+    props = {};
+    build(scope, id) {
+        const { accessLogging, accessLogsPrefix, ...bucketProps } = this.props;
+        const { accessLogging: defaultAccessLogging, accessLogsPrefix: defaultLogsPrefix, ...cdkDefaults } = BUCKET_DEFAULTS;
+        const autoAccessLog = (accessLogging ?? defaultAccessLogging) && !bucketProps.serverAccessLogsBucket;
+        if (accessLogsPrefix !== undefined && !autoAccessLog) {
+            throw new Error("Cannot set 'accessLogsPrefix' when access logging is disabled or " +
+                "'serverAccessLogsBucket' is provided. Set 'serverAccessLogsPrefix' " +
+                "directly when using your own logging bucket.");
+        }
+        let accessLogsBucket;
+        let accessLogProps = {};
+        if (autoAccessLog) {
+            accessLogsBucket = createBucketBuilder()
+                .accessLogging(false)
+                .removalPolicy(RemovalPolicy.RETAIN)
+                .build(scope, `${id}AccessLogs`).bucket;
+            accessLogProps = {
+                serverAccessLogsBucket: accessLogsBucket,
+                serverAccessLogsPrefix: accessLogsPrefix ?? defaultLogsPrefix,
+            };
+        }
+        const mergedProps = {
+            ...cdkDefaults,
+            ...accessLogProps,
+            ...bucketProps,
+            ...autoDeleteProps(bucketProps, BUCKET_DEFAULTS),
+        };
+        return {
+            bucket: new Bucket(scope, id, mergedProps),
+            accessLogsBucket,
+        };
+    }
+}
+/**
+ * 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 === 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"] },
+ * );
+ * ```
+ */
+export function createBucketBuilder() {
+    return Builder(BucketBuilder);
+}
+//# sourceMappingURL=bucket-builder.js.map

package/dist/bucket-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-builder.js","sourceRoot":"","sources":["../src/bucket-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAoB,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAE,OAAO,EAAiC,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AA2EhD,MAAM,aAAa;IACjB,KAAK,GAAgC,EAAE,CAAC;IAExC,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QACvE,MAAM,EACJ,aAAa,EAAE,oBAAoB,EACnC,gBAAgB,EAAE,iBAAiB,EACnC,GAAG,WAAW,EACf,GAAG,eAAe,CAAC;QACpB,MAAM,aAAa,GACjB,CAAC,aAAa,IAAI,oBAAoB,CAAC,IAAI,CAAC,WAAW,CAAC,sBAAsB,CAAC;QAEjF,IAAI,gBAAgB,KAAK,SAAS,IAAI,CAAC,aAAa,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CACb,mEAAmE;gBACjE,qEAAqE;gBACrE,8CAA8C,CACjD,CAAC;QACJ,CAAC;QAED,IAAI,gBAAoC,CAAC;QACzC,IAAI,cAAc,GAAG,EAAE,CAAC;QAExB,IAAI,aAAa,EAAE,CAAC;YAClB,gBAAgB,GAAG,mBAAmB,EAAE;iBACrC,aAAa,CAAC,KAAK,CAAC;iBACpB,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC;iBACnC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC;YAC1C,cAAc,GAAG;gBACf,sBAAsB,EAAE,gBAAgB;gBACxC,sBAAsB,EAAE,gBAAgB,IAAI,iBAAiB;aAC9D,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG;YAClB,GAAG,WAAW;YACd,GAAG,cAAc;YACjB,GAAG,WAAW;YACd,GAAG,eAAe,CAAC,WAAW,EAAE,eAAe,CAAC;SAClC,CAAC;QAEjB,OAAO;YACL,MAAM,EAAE,IAAI,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;YAC1C,gBAAgB;SACjB,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CACtB,SAA+B,EAC/B,QAAqC;IAErC,MAAM,eAAe,GAAG,SAAS,CAAC,aAAa,IAAI,QAAQ,CAAC,aAAa,CAAC;IAC1E,IAAI,eAAe,KAAK,aAAa,CAAC,OAAO,IAAI,SAAS,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC3F,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;IACrC,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,OAAO,CAAoC,aAAa,CAAC,CAAC;AACnE,CAAC"}

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

@@ -0,0 +1,112 @@
+import { BucketDeployment, type BucketDeploymentProps, type ISource } from "aws-cdk-lib/aws-s3-deployment";
+import { type IBucket } from "aws-cdk-lib/aws-s3";
+import { type IDistribution } from "aws-cdk-lib/aws-cloudfront";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+/**
+ * Configuration properties for the S3 bucket deployment builder.
+ *
+ * Extends the CDK {@link BucketDeploymentProps} but replaces
+ * `destinationBucket` and `distribution` with builder-managed fields that
+ * support {@link Resolvable} for cross-component wiring via {@link ref}.
+ *
+ * `sources` is set via the builder's fluent API rather than the constructor.
+ */
+export interface BucketDeploymentBuilderProps extends Omit<BucketDeploymentProps, "sources" | "destinationBucket" | "distribution"> {
+    /**
+     * The sources from which to deploy content. Typically created with
+     * `Source.asset("./path")` or `Source.data("key", "content")`.
+     */
+    sources?: ISource[];
+}
+/**
+ * The build output of a {@link IBucketDeploymentBuilder}.
+ */
+export interface BucketDeploymentBuilderResult {
+    /** The CDK BucketDeployment construct created by the builder. */
+    deployment: BucketDeployment;
+}
+/**
+ * A fluent builder for configuring and creating an S3 BucketDeployment.
+ *
+ * Each configuration property from the CDK {@link BucketDeploymentProps} is
+ * exposed as an overloaded method: call with a value to set it (returns the
+ * builder for chaining), or call with no arguments to read the current value.
+ *
+ * The `destinationBucket` and `distribution` are set via dedicated methods
+ * that accept {@link Resolvable} values for cross-component wiring.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}.
+ *
+ * @example
+ * ```ts
+ * const deploy = createBucketDeploymentBuilder()
+ *   .sources([Source.asset("./site")])
+ *   .destinationBucket(ref("site", (r: BucketBuilderResult) => r.bucket))
+ *   .distribution(ref("cdn", (r: DistributionBuilderResult) => r.distribution))
+ *   .distributionPaths(["/*"]);
+ * ```
+ */
+export type IBucketDeploymentBuilder = IBuilder<BucketDeploymentBuilderProps, BucketDeploymentBuilder>;
+declare class BucketDeploymentBuilder implements Lifecycle<BucketDeploymentBuilderResult> {
+    props: Partial<BucketDeploymentBuilderProps>;
+    private _destinationBucket?;
+    private _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: Resolvable<IBucket>): 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: Resolvable<IDistribution>): this;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): BucketDeploymentBuilderResult;
+}
+/**
+ * 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"] },
+ * );
+ * ```
+ */
+export declare function createBucketDeploymentBuilder(): IBucketDeploymentBuilder;
+export {};
+//# sourceMappingURL=bucket-deployment-builder.d.ts.map

package/dist/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,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,OAAO,EACb,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAG5B;;;;;;;;GAQG;AACH,MAAM,WAAW,4BACf,SAAQ,IAAI,CAAC,qBAAqB,EAAE,SAAS,GAAG,mBAAmB,GAAG,cAAc,CAAC;IACrF;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,iEAAiE;IACjE,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAC7C,4BAA4B,EAC5B,uBAAuB,CACxB,CAAC;AAEF,cAAM,uBAAwB,YAAW,SAAS,CAAC,6BAA6B,CAAC;IAC/E,KAAK,EAAE,OAAO,CAAC,4BAA4B,CAAC,CAAM;IAClD,OAAO,CAAC,kBAAkB,CAAC,CAAsB;IACjD,OAAO,CAAC,aAAa,CAAC,CAA4B;IAElD;;;;;;;;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,KAAK,CACH,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,6BAA6B;CA8CjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,6BAA6B,IAAI,wBAAwB,CAExE"}

package/dist/bucket-deployment-builder.js

@@ -0,0 +1,104 @@
+import { BucketDeployment, } from "aws-cdk-lib/aws-s3-deployment";
+import { Builder, resolve, } from "@composurecdk/core";
+import { BUCKET_DEPLOYMENT_DEFAULTS } from "./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;
+    }
+    build(scope, id, context) {
+        const ctx = context ?? {};
+        const resolvedBucket = this._destinationBucket
+            ? 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
+            ? resolve(this._distribution, ctx)
+            : undefined;
+        // Only apply distributionPaths default when a distribution is present;
+        // CDK throws if distributionPaths is set without a distribution.
+        const { distributionPaths: _distPaths, ...defaultsWithoutPaths } = BUCKET_DEPLOYMENT_DEFAULTS;
+        const effectiveDefaults = resolvedDistribution
+            ? BUCKET_DEPLOYMENT_DEFAULTS
+            : defaultsWithoutPaths;
+        const mergedProps = {
+            ...effectiveDefaults,
+            ...deployProps,
+            ...(resolvedDistribution ? { distribution: resolvedDistribution } : {}),
+            sources,
+            destinationBucket: resolvedBucket,
+        };
+        return {
+            deployment: new BucketDeployment(scope, id, mergedProps),
+        };
+    }
+}
+/**
+ * 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"] },
+ * );
+ * ```
+ */
+export function createBucketDeploymentBuilder() {
+    return Builder(BucketDeploymentBuilder);
+}
+//# sourceMappingURL=bucket-deployment-builder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-deployment-builder.js","sourceRoot":"","sources":["../src/bucket-deployment-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,GAGjB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,OAAO,EAGP,OAAO,GAER,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAuD7E,MAAM,uBAAuB;IAC3B,KAAK,GAA0C,EAAE,CAAC;IAC1C,kBAAkB,CAAuB;IACzC,aAAa,CAA6B;IAElD;;;;;;;;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,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,OAAO,CAAC,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;YAC7C,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;YAClC,CAAC,CAAC,SAAS,CAAC;QAEd,uEAAuE;QACvE,iEAAiE;QACjE,MAAM,EAAE,iBAAiB,EAAE,UAAU,EAAE,GAAG,oBAAoB,EAAE,GAAG,0BAA0B,CAAC;QAC9F,MAAM,iBAAiB,GAAG,oBAAoB;YAC5C,CAAC,CAAC,0BAA0B;YAC5B,CAAC,CAAC,oBAAoB,CAAC;QAEzB,MAAM,WAAW,GAAG;YAClB,GAAG,iBAAiB;YACpB,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,gBAAgB,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;SACzD,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,6BAA6B;IAC3C,OAAO,OAAO,CAAwD,uBAAuB,CAAC,CAAC;AACjG,CAAC"}

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

@@ -0,0 +1,8 @@
+import type { BucketDeploymentBuilderProps } from "./bucket-deployment-builder.js";
+/**
+ * Sensible defaults applied to every S3 BucketDeployment built with
+ * {@link createBucketDeploymentBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+export declare const BUCKET_DEPLOYMENT_DEFAULTS: Partial<BucketDeploymentBuilderProps>;
+//# sourceMappingURL=bucket-deployment-defaults.d.ts.map

package/dist/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,gCAAgC,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,OAAO,CAAC,4BAA4B,CAc5E,CAAC"}

package/dist/bucket-deployment-defaults.js

@@ -0,0 +1,20 @@
+/**
+ * Sensible defaults applied to every S3 BucketDeployment built with
+ * {@link createBucketDeploymentBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+export const BUCKET_DEPLOYMENT_DEFAULTS = {
+    /**
+     * Invalidate all paths by default so that deployed content is immediately
+     * visible through CloudFront.
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html
+     */
+    distributionPaths: ["/*"],
+    /**
+     * Remove files from the destination bucket that are not present in the
+     * source, keeping the bucket in sync with the deployed assets.
+     * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeploymentProps.html#prune
+     */
+    prune: true,
+};
+//# sourceMappingURL=bucket-deployment-defaults.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-deployment-defaults.js","sourceRoot":"","sources":["../src/bucket-deployment-defaults.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAA0C;IAC/E;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,IAAI,CAAC;IAEzB;;;;OAIG;IACH,KAAK,EAAE,IAAI;CACZ,CAAC"}

package/dist/defaults.d.ts

@@ -0,0 +1,8 @@
+import type { BucketBuilderProps } from "./bucket-builder.js";
+/**
+ * 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.
+ */
+export declare const BUCKET_DEFAULTS: Partial<BucketBuilderProps>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,kBAAkB,CAqDvD,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,56 @@
+import { BlockPublicAccess, BucketEncryption } from "aws-cdk-lib/aws-s3";
+import { RemovalPolicy } from "aws-cdk-lib";
+/**
+ * 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.
+ */
+export const BUCKET_DEFAULTS = {
+    /**
+     * Automatically create an access logging bucket for S3 server access logs.
+     * 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
+     */
+    accessLogging: true,
+    /**
+     * Default prefix for server access log object keys in the auto-created
+     * logging bucket.
+     */
+    accessLogsPrefix: "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: 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: 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,
+    /**
+     * 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: RemovalPolicy.RETAIN,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAgC;IAC1D;;;;;OAKG;IACH,aAAa,EAAE,IAAI;IAEnB;;;OAGG;IACH,gBAAgB,EAAE,OAAO;IAEzB;;;;;OAKG;IACH,iBAAiB,EAAE,iBAAiB,CAAC,SAAS;IAE9C;;;;OAIG;IACH,UAAU,EAAE,gBAAgB,CAAC,UAAU;IAEvC;;;OAGG;IACH,UAAU,EAAE,IAAI;IAEhB;;;;OAIG;IACH,SAAS,EAAE,IAAI;IAEf;;;;;;;;OAQG;IACH,aAAa,EAAE,aAAa,CAAC,MAAM;CACpC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createBucketBuilder, type BucketBuilderResult, type IBucketBuilder, } from "./bucket-builder.js";
+export { BUCKET_DEFAULTS } from "./defaults.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/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,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createBucketBuilder, } from "./bucket-builder.js";
+export { BUCKET_DEFAULTS } from "./defaults.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAGpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@composurecdk/s3",
+  "version": "0.1.2",
+  "description": "Composable S3 bucket builder with well-architected defaults",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laazyj/composureCDK",
+    "directory": "packages/s3"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "keywords": [],
+  "author": "Jason Duffett (https://github.com/laazyj)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@composurecdk/core": "^0.1.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "aws-cdk-lib": "^2.245.0",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}