@composurecdk/route53 0.3.3

package/README.md

@@ -0,0 +1,122 @@
+# @composurecdk/route53
+
+Route 53 hosted zone and record builders for [ComposureCDK](../../README.md).
+
+This package provides fluent builders for Route 53 public hosted zones and for the record types most commonly needed when fronting an AWS workload (A/AAAA alias, CNAME, TXT). It wraps the CDK [aws-route53](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_route53-readme.html) constructs — refer to the CDK documentation for the full set of configurable properties.
+
+## Hosted Zone Builder
+
+```ts
+import { createHostedZoneBuilder } from "@composurecdk/route53";
+
+const zone = createHostedZoneBuilder()
+  .zoneName("example.com")
+  .comment("Primary customer-facing domain")
+  .build(stack, "SiteZone");
+```
+
+Every [PublicHostedZoneProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_route53.PublicHostedZoneProps.html) property is available as a fluent setter on the builder.
+
+### Query logging
+
+Route 53 is a global service, but DNS query logs are emitted in `us-east-1` only — the CloudWatch log group that receives them must live there regardless of where the hosted zone is declared. This is an AWS service constraint, not a restriction on where your hosted zone or records can live.
+
+Supply a pre-configured log group via `.queryLogsLogGroupArn(arn)`. The log group must:
+
+- Be in `us-east-1`.
+- Have a resource policy granting `route53.amazonaws.com` permission to `logs:PutLogEvents` and `logs:CreateLogStream`.
+
+Auto-creating the log group and resource policy on the user's behalf is planned — see [#44](https://github.com/laazyj/composureCDK/issues/44). Once implemented, enabling query logging will become a single opt-in property with the log group + resource policy wired by default.
+
+## Record Builders
+
+```ts
+import {
+  createARecordBuilder,
+  createAaaaRecordBuilder,
+  createCnameRecordBuilder,
+  createTxtRecordBuilder,
+  cloudfrontAliasTarget,
+} from "@composurecdk/route53";
+
+createARecordBuilder()
+  .zone(zone)
+  .target(cloudfrontAliasTarget(distribution))
+  .build(stack, "ApexAlias");
+
+createTxtRecordBuilder()
+  .zone(zone)
+  .recordName("_dmarc")
+  .values(["v=DMARC1; p=reject"])
+  .build(stack, "Dmarc");
+```
+
+### Alias targets
+
+For AWS-service records, prefer A/AAAA alias records over CNAMEs. Alias records:
+
+- Are free to resolve (CNAMEs are billed per query).
+- Work at the zone apex (CNAMEs cannot coexist with the mandatory apex SOA/NS records).
+- Resolve in a single hop (CNAMEs chain to a second lookup).
+- Track AWS-managed DNS changes automatically (CNAMEs must be updated manually if the target's DNS name changes).
+- Support both IPv4 (A) and IPv6 (AAAA) from the same alias target.
+
+Use `createCnameRecordBuilder` only when the target is not an AWS resource (or the AWS resource does not expose an alias target), and never at the zone apex.
+
+| Helper                                | Points at                                        |
+| ------------------------------------- | ------------------------------------------------ |
+| `cloudfrontAliasTarget(distribution)` | A `cloudfront.IDistribution`                     |
+| `apiGatewayAliasTarget(api)`          | An `apigateway.RestApiBase` with a custom domain |
+| `apiGatewayDomainAliasTarget(domain)` | A shared `apigateway.DomainName`                 |
+
+Each helper accepts a `Resolvable`, so targets produced by other composed components (e.g. `@composurecdk/cloudfront`) can be wired in via `ref()`.
+
+## Secure Defaults
+
+| Builder                    | Property         | Default               | Rationale                                               |
+| -------------------------- | ---------------- | --------------------- | ------------------------------------------------------- |
+| `createHostedZoneBuilder`  | `addTrailingDot` | `true`                | Matches RFC 1035 and the CDK default; unambiguous apex. |
+| `createARecordBuilder`     | `ttl`            | `Duration.minutes(5)` | Balances propagation latency against DNS cache churn.   |
+| `createAaaaRecordBuilder`  | `ttl`            | `Duration.minutes(5)` | Same rationale as A records.                            |
+| `createCnameRecordBuilder` | `ttl`            | `Duration.minutes(5)` | Same rationale as A records.                            |
+| `createTxtRecordBuilder`   | `ttl`            | `Duration.minutes(5)` | Same rationale as A records.                            |
+
+The defaults are exported as `HOSTED_ZONE_DEFAULTS`, `A_RECORD_DEFAULTS`, `AAAA_RECORD_DEFAULTS`, `CNAME_RECORD_DEFAULTS`, and `TXT_RECORD_DEFAULTS` for visibility and testing.
+
+## Recommended Alarms
+
+Route 53 health checks expose a `HealthCheckStatus` metric that [AWS recommends alarming on](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Route53). This package does not yet expose a `HealthCheckBuilder`; once it does, the recommended alarm will be enabled by default alongside the health check. Tracked in [#45](https://github.com/laazyj/composureCDK/issues/45).
+
+## Composing with ACM and CloudFront
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import { createCertificateBuilder, type CertificateBuilderResult } from "@composurecdk/acm";
+import {
+  createDistributionBuilder,
+  type DistributionBuilderResult,
+} from "@composurecdk/cloudfront";
+import {
+  createHostedZoneBuilder,
+  createARecordBuilder,
+  cloudfrontAliasTarget,
+  type HostedZoneBuilderResult,
+} from "@composurecdk/route53";
+
+compose(
+  {
+    zone: createHostedZoneBuilder().zoneName("example.com"),
+    cert: createCertificateBuilder()
+      .domainName("example.com")
+      .validationZone(ref("zone", (r: HostedZoneBuilderResult) => r.hostedZone)),
+    cdn: createDistributionBuilder()
+      .domainNames(["example.com"])
+      .certificate(ref("cert", (r: CertificateBuilderResult) => r.certificate))
+      .origin(/* ... */),
+    apex: createARecordBuilder()
+      .zone(ref("zone", (r: HostedZoneBuilderResult) => r.hostedZone))
+      .target(cloudfrontAliasTarget(ref("cdn", (r: DistributionBuilderResult) => r.distribution))),
+  },
+  { zone: [], cert: ["zone"], cdn: ["cert"], apex: ["zone", "cdn"] },
+).build(stack, "Site");
+```

package/dist/a-record-builder.d.ts

@@ -0,0 +1,56 @@
+import { ARecord, type ARecordProps, type IHostedZone, type RecordTarget } from "aws-cdk-lib/aws-route53";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+/**
+ * Configuration properties for the Route53 A record builder.
+ *
+ * Extends the CDK {@link ARecordProps} but replaces `zone` and `target` with
+ * {@link Resolvable} variants so they can be wired from other components in a
+ * composed system via {@link ref}.
+ */
+export interface ARecordBuilderProps extends Omit<ARecordProps, "zone" | "target"> {
+    /**
+     * The hosted zone in which to create the record. Accepts a {@link Resolvable}
+     * so a zone produced by a composed {@link createHostedZoneBuilder} can be
+     * wired in via {@link ref}.
+     */
+    zone?: Resolvable<IHostedZone>;
+    /**
+     * The record target. Accepts a {@link Resolvable} so alias targets derived
+     * from composed components (e.g. a CloudFront distribution) can be wired in
+     * via {@link ref} or the helpers in `./alias-targets.js`.
+     */
+    target?: Resolvable<RecordTarget>;
+}
+/**
+ * The build output of an {@link IARecordBuilder}.
+ */
+export interface ARecordBuilderResult {
+    /** The Route53 A record construct created by the builder. */
+    record: ARecord;
+}
+/**
+ * A fluent builder for configuring and creating a Route53 A record (typically
+ * an alias record pointing at a CloudFront distribution, ALB, API Gateway
+ * custom domain, or another A-record-capable target).
+ *
+ * @example
+ * ```ts
+ * const apex = createARecordBuilder()
+ *   .zone(ref("zone", (r: HostedZoneBuilderResult) => r.hostedZone))
+ *   .target(cloudfrontAliasTarget(ref("cdn", (r: DistributionBuilderResult) => r.distribution)));
+ * ```
+ */
+export type IARecordBuilder = IBuilder<ARecordBuilderProps, ARecordBuilder>;
+declare class ARecordBuilder implements Lifecycle<ARecordBuilderResult> {
+    props: Partial<ARecordBuilderProps>;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): ARecordBuilderResult;
+}
+/**
+ * Creates a new {@link IARecordBuilder} for configuring a Route53 A record.
+ *
+ * @returns A fluent builder for a Route53 A record.
+ */
+export declare function createARecordBuilder(): IARecordBuilder;
+export {};
+//# sourceMappingURL=a-record-builder.d.ts.map

package/dist/a-record-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a-record-builder.d.ts","sourceRoot":"","sources":["../src/a-record-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAG5B;;;;;;GAMG;AACH,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,QAAQ,CAAC;IAChF;;;;OAIG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAE/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC;AAE5E,cAAM,cAAe,YAAW,SAAS,CAAC,oBAAoB,CAAC;IAC7D,KAAK,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAM;IAEzC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,oBAAoB;CAwB7F;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,CAEtD"}

package/dist/a-record-builder.js

@@ -0,0 +1,35 @@
+import { ARecord, } from "aws-cdk-lib/aws-route53";
+import { Builder, resolve, } from "@composurecdk/core";
+import { A_RECORD_DEFAULTS } from "./defaults.js";
+class ARecordBuilder {
+    props = {};
+    build(scope, id, context) {
+        const { zone, target, ...rest } = this.props;
+        if (!zone) {
+            throw new Error(`ARecordBuilder "${id}" requires a zone. Call .zone() with an IHostedZone.`);
+        }
+        if (!target) {
+            throw new Error(`ARecordBuilder "${id}" requires a target. Call .target() with a RecordTarget.`);
+        }
+        const resolvedContext = context ?? {};
+        const resolvedTarget = resolve(target, resolvedContext);
+        const isAlias = resolvedTarget.aliasTarget !== undefined;
+        const mergedProps = {
+            ...(isAlias ? {} : A_RECORD_DEFAULTS),
+            ...rest,
+            zone: resolve(zone, resolvedContext),
+            target: resolvedTarget,
+        };
+        const record = new ARecord(scope, id, mergedProps);
+        return { record };
+    }
+}
+/**
+ * Creates a new {@link IARecordBuilder} for configuring a Route53 A record.
+ *
+ * @returns A fluent builder for a Route53 A record.
+ */
+export function createARecordBuilder() {
+    return Builder(ARecordBuilder);
+}
+//# sourceMappingURL=a-record-builder.js.map

package/dist/a-record-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a-record-builder.js","sourceRoot":"","sources":["../src/a-record-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,GAIR,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,OAAO,EAGP,OAAO,GAER,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AA+ClD,MAAM,cAAc;IAClB,KAAK,GAAiC,EAAE,CAAC;IAEzC,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,OAAgC;QACnE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAC7C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,mBAAmB,EAAE,sDAAsD,CAAC,CAAC;QAC/F,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,mBAAmB,EAAE,0DAA0D,CAChF,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,OAAO,IAAI,EAAE,CAAC;QACtC,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,cAAc,CAAC,WAAW,KAAK,SAAS,CAAC;QACzD,MAAM,WAAW,GAAG;YAClB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC;YACrC,GAAG,IAAI;YACP,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,eAAe,CAAC;YACpC,MAAM,EAAE,cAAc;SACP,CAAC;QAElB,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QACnD,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,OAAO,CAAsC,cAAc,CAAC,CAAC;AACtE,CAAC"}

package/dist/aaaa-record-builder.d.ts

@@ -0,0 +1,44 @@
+import { AaaaRecord, type AaaaRecordProps, type IHostedZone, type RecordTarget } from "aws-cdk-lib/aws-route53";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+/**
+ * Configuration properties for the Route53 AAAA (IPv6) record builder.
+ *
+ * Extends the CDK {@link AaaaRecordProps} but replaces `zone` and `target`
+ * with {@link Resolvable} variants so they can be wired from other components
+ * in a composed system.
+ */
+export interface AaaaRecordBuilderProps extends Omit<AaaaRecordProps, "zone" | "target"> {
+    /** The hosted zone in which to create the record. */
+    zone?: Resolvable<IHostedZone>;
+    /** The record target. */
+    target?: Resolvable<RecordTarget>;
+}
+/**
+ * The build output of an {@link IAaaaRecordBuilder}.
+ */
+export interface AaaaRecordBuilderResult {
+    /** The Route53 AAAA record construct created by the builder. */
+    record: AaaaRecord;
+}
+/**
+ * A fluent builder for configuring and creating a Route53 AAAA (IPv6) record.
+ *
+ * Use this alongside an A record to expose a CloudFront distribution or ALB
+ * over both IPv4 and IPv6 — AWS alias targets support both families from a
+ * single resource.
+ */
+export type IAaaaRecordBuilder = IBuilder<AaaaRecordBuilderProps, AaaaRecordBuilder>;
+declare class AaaaRecordBuilder implements Lifecycle<AaaaRecordBuilderResult> {
+    props: Partial<AaaaRecordBuilderProps>;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): AaaaRecordBuilderResult;
+}
+/**
+ * Creates a new {@link IAaaaRecordBuilder} for configuring a Route53 AAAA
+ * (IPv6) record.
+ *
+ * @returns A fluent builder for a Route53 AAAA record.
+ */
+export declare function createAaaaRecordBuilder(): IAaaaRecordBuilder;
+export {};
+//# sourceMappingURL=aaaa-record-builder.d.ts.map

package/dist/aaaa-record-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aaaa-record-builder.d.ts","sourceRoot":"","sources":["../src/aaaa-record-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAG5B;;;;;;GAMG;AACH,MAAM,WAAW,sBAAuB,SAAQ,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,QAAQ,CAAC;IACtF,qDAAqD;IACrD,IAAI,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAC/B,yBAAyB;IACzB,MAAM,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,gEAAgE;IAChE,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,sBAAsB,EAAE,iBAAiB,CAAC,CAAC;AAErF,cAAM,iBAAkB,YAAW,SAAS,CAAC,uBAAuB,CAAC;IACnE,KAAK,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAM;IAE5C,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,uBAAuB;CA0BhG;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,kBAAkB,CAE5D"}

package/dist/aaaa-record-builder.js

@@ -0,0 +1,36 @@
+import { AaaaRecord, } from "aws-cdk-lib/aws-route53";
+import { Builder, resolve, } from "@composurecdk/core";
+import { AAAA_RECORD_DEFAULTS } from "./defaults.js";
+class AaaaRecordBuilder {
+    props = {};
+    build(scope, id, context) {
+        const { zone, target, ...rest } = this.props;
+        if (!zone) {
+            throw new Error(`AaaaRecordBuilder "${id}" requires a zone. Call .zone() with an IHostedZone.`);
+        }
+        if (!target) {
+            throw new Error(`AaaaRecordBuilder "${id}" requires a target. Call .target() with a RecordTarget.`);
+        }
+        const resolvedContext = context ?? {};
+        const resolvedTarget = resolve(target, resolvedContext);
+        const isAlias = resolvedTarget.aliasTarget !== undefined;
+        const mergedProps = {
+            ...(isAlias ? {} : AAAA_RECORD_DEFAULTS),
+            ...rest,
+            zone: resolve(zone, resolvedContext),
+            target: resolvedTarget,
+        };
+        const record = new AaaaRecord(scope, id, mergedProps);
+        return { record };
+    }
+}
+/**
+ * Creates a new {@link IAaaaRecordBuilder} for configuring a Route53 AAAA
+ * (IPv6) record.
+ *
+ * @returns A fluent builder for a Route53 AAAA record.
+ */
+export function createAaaaRecordBuilder() {
+    return Builder(AaaaRecordBuilder);
+}
+//# sourceMappingURL=aaaa-record-builder.js.map

package/dist/aaaa-record-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aaaa-record-builder.js","sourceRoot":"","sources":["../src/aaaa-record-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,GAIX,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,OAAO,EAGP,OAAO,GAER,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAiCrD,MAAM,iBAAiB;IACrB,KAAK,GAAoC,EAAE,CAAC;IAE5C,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,OAAgC;QACnE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAC7C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CACb,sBAAsB,EAAE,sDAAsD,CAC/E,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,sBAAsB,EAAE,0DAA0D,CACnF,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,OAAO,IAAI,EAAE,CAAC;QACtC,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,cAAc,CAAC,WAAW,KAAK,SAAS,CAAC;QACzD,MAAM,WAAW,GAAG;YAClB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,oBAAoB,CAAC;YACxC,GAAG,IAAI;YACP,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,eAAe,CAAC;YACpC,MAAM,EAAE,cAAc;SACJ,CAAC;QAErB,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QACtD,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,OAAO,CAA4C,iBAAiB,CAAC,CAAC;AAC/E,CAAC"}

package/dist/alias-targets.d.ts

@@ -0,0 +1,34 @@
+import { type IDistribution } from "aws-cdk-lib/aws-cloudfront";
+import { type IDomainName, type RestApiBase } from "aws-cdk-lib/aws-apigateway";
+import { RecordTarget } from "aws-cdk-lib/aws-route53";
+import { type Resolvable } from "@composurecdk/core";
+/**
+ * Builds an alias {@link RecordTarget} for a CloudFront distribution, usable
+ * as the `target` of an A or AAAA record. Accepts a {@link Resolvable} so a
+ * distribution produced by a composed `@composurecdk/cloudfront` component
+ * can be wired in via {@link ref}.
+ *
+ * @example
+ * ```ts
+ * createARecordBuilder()
+ *   .zone(ref("zone", (r: HostedZoneBuilderResult) => r.hostedZone))
+ *   .target(cloudfrontAliasTarget(
+ *     ref("cdn", (r: DistributionBuilderResult) => r.distribution),
+ *   ));
+ * ```
+ */
+export declare function cloudfrontAliasTarget(distribution: Resolvable<IDistribution>): Resolvable<RecordTarget>;
+/**
+ * Builds an alias {@link RecordTarget} for an API Gateway REST API that has a
+ * custom domain name configured via {@link RestApiBase}. Accepts a
+ * {@link Resolvable}.
+ */
+export declare function apiGatewayAliasTarget(api: Resolvable<RestApiBase>): Resolvable<RecordTarget>;
+/**
+ * Builds an alias {@link RecordTarget} for an API Gateway custom domain name
+ * (`apigateway.DomainName`). Use this when you manage the domain name resource
+ * separately from the REST API (e.g. to share a custom domain across multiple
+ * APIs). Accepts a {@link Resolvable}.
+ */
+export declare function apiGatewayDomainAliasTarget(domain: Resolvable<IDomainName>): Resolvable<RecordTarget>;
+//# sourceMappingURL=alias-targets.d.ts.map

package/dist/alias-targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias-targets.d.ts","sourceRoot":"","sources":["../src/alias-targets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,UAAU,CAAC,aAAa,CAAC,GACtC,UAAU,CAAC,YAAY,CAAC,CAI1B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,UAAU,CAAC,YAAY,CAAC,CAI5F;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,GAC9B,UAAU,CAAC,YAAY,CAAC,CAI1B"}

package/dist/alias-targets.js

@@ -0,0 +1,45 @@
+import { RecordTarget } from "aws-cdk-lib/aws-route53";
+import { ApiGateway, ApiGatewayDomain, CloudFrontTarget } from "aws-cdk-lib/aws-route53-targets";
+import { isRef } from "@composurecdk/core";
+/**
+ * Builds an alias {@link RecordTarget} for a CloudFront distribution, usable
+ * as the `target` of an A or AAAA record. Accepts a {@link Resolvable} so a
+ * distribution produced by a composed `@composurecdk/cloudfront` component
+ * can be wired in via {@link ref}.
+ *
+ * @example
+ * ```ts
+ * createARecordBuilder()
+ *   .zone(ref("zone", (r: HostedZoneBuilderResult) => r.hostedZone))
+ *   .target(cloudfrontAliasTarget(
+ *     ref("cdn", (r: DistributionBuilderResult) => r.distribution),
+ *   ));
+ * ```
+ */
+export function cloudfrontAliasTarget(distribution) {
+    return isRef(distribution)
+        ? distribution.map((d) => RecordTarget.fromAlias(new CloudFrontTarget(d)))
+        : RecordTarget.fromAlias(new CloudFrontTarget(distribution));
+}
+/**
+ * Builds an alias {@link RecordTarget} for an API Gateway REST API that has a
+ * custom domain name configured via {@link RestApiBase}. Accepts a
+ * {@link Resolvable}.
+ */
+export function apiGatewayAliasTarget(api) {
+    return isRef(api)
+        ? api.map((a) => RecordTarget.fromAlias(new ApiGateway(a)))
+        : RecordTarget.fromAlias(new ApiGateway(api));
+}
+/**
+ * Builds an alias {@link RecordTarget} for an API Gateway custom domain name
+ * (`apigateway.DomainName`). Use this when you manage the domain name resource
+ * separately from the REST API (e.g. to share a custom domain across multiple
+ * APIs). Accepts a {@link Resolvable}.
+ */
+export function apiGatewayDomainAliasTarget(domain) {
+    return isRef(domain)
+        ? domain.map((d) => RecordTarget.fromAlias(new ApiGatewayDomain(d)))
+        : RecordTarget.fromAlias(new ApiGatewayDomain(domain));
+}
+//# sourceMappingURL=alias-targets.js.map

package/dist/alias-targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias-targets.js","sourceRoot":"","sources":["../src/alias-targets.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,EAAE,KAAK,EAAmB,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CACnC,YAAuC;IAEvC,OAAO,KAAK,CAAC,YAAY,CAAC;QACxB,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,gBAAgB,CAAC,YAAY,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAA4B;IAChE,OAAO,KAAK,CAAC,GAAG,CAAC;QACf,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAA+B;IAE/B,OAAO,KAAK,CAAC,MAAM,CAAC;QAClB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/cname-record-builder.d.ts

@@ -0,0 +1,42 @@
+import { CnameRecord, type CnameRecordProps, type IHostedZone } from "aws-cdk-lib/aws-route53";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+/**
+ * Configuration properties for the Route53 CNAME record builder.
+ *
+ * Extends the CDK {@link CnameRecordProps} but replaces `zone` with a
+ * {@link Resolvable} so it can be wired from composed components.
+ */
+export interface CnameRecordBuilderProps extends Omit<CnameRecordProps, "zone"> {
+    /** The hosted zone in which to create the record. */
+    zone?: Resolvable<IHostedZone>;
+}
+/**
+ * The build output of an {@link ICnameRecordBuilder}.
+ */
+export interface CnameRecordBuilderResult {
+    /** The Route53 CNAME record construct created by the builder. */
+    record: CnameRecord;
+}
+/**
+ * A fluent builder for configuring and creating a Route53 CNAME record.
+ *
+ * Prefer {@link createARecordBuilder | A / AAAA alias records} when pointing
+ * at AWS resources — alias records are free, resolve in one hop, and can be
+ * used at the apex. Use CNAME for non-AWS targets or for sub-domain
+ * redirections where an alias is not available.
+ */
+export type ICnameRecordBuilder = IBuilder<CnameRecordBuilderProps, CnameRecordBuilder>;
+declare class CnameRecordBuilder implements Lifecycle<CnameRecordBuilderResult> {
+    props: Partial<CnameRecordBuilderProps>;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): CnameRecordBuilderResult;
+}
+/**
+ * Creates a new {@link ICnameRecordBuilder} for configuring a Route53 CNAME
+ * record.
+ *
+ * @returns A fluent builder for a Route53 CNAME record.
+ */
+export declare function createCnameRecordBuilder(): ICnameRecordBuilder;
+export {};
+//# sourceMappingURL=cname-record-builder.d.ts.map

package/dist/cname-record-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cname-record-builder.d.ts","sourceRoot":"","sources":["../src/cname-record-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC/F,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAG5B;;;;;GAKG;AACH,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAC7E,qDAAqD;IACrD,IAAI,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,CAAC;AAExF,cAAM,kBAAmB,YAAW,SAAS,CAAC,wBAAwB,CAAC;IACrE,KAAK,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAM;IAE7C,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,wBAAwB;CAgCjG;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,mBAAmB,CAE9D"}

package/dist/cname-record-builder.js

@@ -0,0 +1,40 @@
+import { CnameRecord } from "aws-cdk-lib/aws-route53";
+import { Builder, resolve, } from "@composurecdk/core";
+import { CNAME_RECORD_DEFAULTS } from "./defaults.js";
+class CnameRecordBuilder {
+    props = {};
+    build(scope, id, context) {
+        const { zone, domainName, recordName, ...rest } = this.props;
+        if (!zone) {
+            throw new Error(`CnameRecordBuilder "${id}" requires a zone. Call .zone() with an IHostedZone.`);
+        }
+        if (!domainName) {
+            throw new Error(`CnameRecordBuilder "${id}" requires a domainName. ` +
+                `Call .domainName() with the target host (what the CNAME points to).`);
+        }
+        if (!recordName) {
+            throw new Error(`CnameRecordBuilder "${id}" requires a recordName. ` +
+                `Call .recordName() with the subdomain — CNAME records cannot be at the zone apex.`);
+        }
+        const resolvedContext = context ?? {};
+        const mergedProps = {
+            ...CNAME_RECORD_DEFAULTS,
+            ...rest,
+            domainName,
+            recordName,
+            zone: resolve(zone, resolvedContext),
+        };
+        const record = new CnameRecord(scope, id, mergedProps);
+        return { record };
+    }
+}
+/**
+ * Creates a new {@link ICnameRecordBuilder} for configuring a Route53 CNAME
+ * record.
+ *
+ * @returns A fluent builder for a Route53 CNAME record.
+ */
+export function createCnameRecordBuilder() {
+    return Builder(CnameRecordBuilder);
+}
+//# sourceMappingURL=cname-record-builder.js.map

package/dist/cname-record-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cname-record-builder.js","sourceRoot":"","sources":["../src/cname-record-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA2C,MAAM,yBAAyB,CAAC;AAE/F,OAAO,EACL,OAAO,EAGP,OAAO,GAER,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AA+BtD,MAAM,kBAAkB;IACtB,KAAK,GAAqC,EAAE,CAAC;IAE7C,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,OAAgC;QACnE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAC7D,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CACb,uBAAuB,EAAE,sDAAsD,CAChF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CACb,uBAAuB,EAAE,2BAA2B;gBAClD,qEAAqE,CACxE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CACb,uBAAuB,EAAE,2BAA2B;gBAClD,mFAAmF,CACtF,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,OAAO,IAAI,EAAE,CAAC;QACtC,MAAM,WAAW,GAAG;YAClB,GAAG,qBAAqB;YACxB,GAAG,IAAI;YACP,UAAU;YACV,UAAU;YACV,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,eAAe,CAAC;SACjB,CAAC;QAEtB,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QACvD,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,OAAO,CAA8C,kBAAkB,CAAC,CAAC;AAClF,CAAC"}

package/dist/defaults.d.ts

@@ -0,0 +1,36 @@
+import type { HostedZoneBuilderProps } from "./hosted-zone-builder.js";
+import type { ARecordBuilderProps } from "./a-record-builder.js";
+import type { AaaaRecordBuilderProps } from "./aaaa-record-builder.js";
+import type { CnameRecordBuilderProps } from "./cname-record-builder.js";
+import type { TxtRecordBuilderProps } from "./txt-record-builder.js";
+/**
+ * Secure, AWS-recommended defaults applied to every public hosted zone built
+ * with {@link createHostedZoneBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ *
+ * Query logging is not enabled by default: Route53 query logs must be written
+ * to a CloudWatch log group in `us-east-1` with a resource policy granting
+ * `route53.amazonaws.com` write access. Opt in explicitly by calling
+ * `.queryLogsLogGroupArn(...)` with a pre-configured log group.
+ */
+export declare const HOSTED_ZONE_DEFAULTS: Partial<HostedZoneBuilderProps>;
+/**
+ * Defaults for {@link createARecordBuilder}. Overridable via the fluent API.
+ * The builder skips the `ttl` default for alias targets — AWS ignores TTL on
+ * alias records and CDK emits a warning when one is set.
+ */
+export declare const A_RECORD_DEFAULTS: Partial<ARecordBuilderProps>;
+/**
+ * Defaults for {@link createAaaaRecordBuilder}. Overridable via the fluent API.
+ * Same alias-target caveat as {@link A_RECORD_DEFAULTS}.
+ */
+export declare const AAAA_RECORD_DEFAULTS: Partial<AaaaRecordBuilderProps>;
+/**
+ * Defaults for {@link createCnameRecordBuilder}. Overridable via the fluent API.
+ */
+export declare const CNAME_RECORD_DEFAULTS: Partial<CnameRecordBuilderProps>;
+/**
+ * Defaults for {@link createTxtRecordBuilder}. Overridable via the fluent API.
+ */
+export declare const TXT_RECORD_DEFAULTS: Partial<TxtRecordBuilderProps>;
+//# 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":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,CAAC,sBAAsB,CAMhE,CAAC;AAaF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,CAAC,mBAAmB,CAE1D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,CAAC,sBAAsB,CAEhE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,uBAAuB,CAElE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,qBAAqB,CAE9D,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,56 @@
+import { Duration } from "aws-cdk-lib";
+/**
+ * Secure, AWS-recommended defaults applied to every public hosted zone built
+ * with {@link createHostedZoneBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ *
+ * Query logging is not enabled by default: Route53 query logs must be written
+ * to a CloudWatch log group in `us-east-1` with a resource policy granting
+ * `route53.amazonaws.com` write access. Opt in explicitly by calling
+ * `.queryLogsLogGroupArn(...)` with a pre-configured log group.
+ */
+export const HOSTED_ZONE_DEFAULTS = {
+    /**
+     * Add a trailing dot to the zone name so the apex is an unambiguous
+     * fully-qualified domain. Matches the CDK default and RFC 1035.
+     */
+    addTrailingDot: true,
+};
+/**
+ * Default TTL applied to records built by this package when no TTL is set.
+ *
+ * Five minutes balances propagation latency against downstream DNS cache
+ * churn. For alias records pointing at dynamic AWS resources (CloudFront,
+ * ALB), this matches AWS guidance.
+ *
+ * @see https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-cloudfront-distribution.html
+ */
+const DEFAULT_RECORD_TTL = Duration.minutes(5);
+/**
+ * Defaults for {@link createARecordBuilder}. Overridable via the fluent API.
+ * The builder skips the `ttl` default for alias targets — AWS ignores TTL on
+ * alias records and CDK emits a warning when one is set.
+ */
+export const A_RECORD_DEFAULTS = {
+    ttl: DEFAULT_RECORD_TTL,
+};
+/**
+ * Defaults for {@link createAaaaRecordBuilder}. Overridable via the fluent API.
+ * Same alias-target caveat as {@link A_RECORD_DEFAULTS}.
+ */
+export const AAAA_RECORD_DEFAULTS = {
+    ttl: DEFAULT_RECORD_TTL,
+};
+/**
+ * Defaults for {@link createCnameRecordBuilder}. Overridable via the fluent API.
+ */
+export const CNAME_RECORD_DEFAULTS = {
+    ttl: DEFAULT_RECORD_TTL,
+};
+/**
+ * Defaults for {@link createTxtRecordBuilder}. Overridable via the fluent API.
+ */
+export const TXT_RECORD_DEFAULTS = {
+    ttl: DEFAULT_RECORD_TTL,
+};
+//# 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,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAoC;IACnE;;;OAGG;IACH,cAAc,EAAE,IAAI;CACrB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAE/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAiC;IAC7D,GAAG,EAAE,kBAAkB;CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAoC;IACnE,GAAG,EAAE,kBAAkB;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAqC;IACrE,GAAG,EAAE,kBAAkB;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAmC;IACjE,GAAG,EAAE,kBAAkB;CACxB,CAAC"}

package/dist/hosted-zone-builder.d.ts

@@ -0,0 +1,75 @@
+import { PublicHostedZone, type PublicHostedZoneProps } from "aws-cdk-lib/aws-route53";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle } from "@composurecdk/core";
+/**
+ * Configuration properties for the Route53 public hosted zone builder.
+ *
+ * Aliases the CDK {@link PublicHostedZoneProps} so every zone property is
+ * available as a fluent setter on the builder. No additional builder-specific
+ * options are defined today — query logging requires a pre-configured log
+ * group (see {@link PublicHostedZoneProps.queryLogsLogGroupArn | queryLogsLogGroupArn})
+ * which the user supplies directly.
+ */
+export type HostedZoneBuilderProps = PublicHostedZoneProps;
+/**
+ * The build output of an {@link IHostedZoneBuilder}. Contains the CDK
+ * constructs created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface HostedZoneBuilderResult {
+    /** The Route53 public hosted zone construct created by the builder. */
+    hostedZone: PublicHostedZone;
+}
+/**
+ * A fluent builder for configuring and creating a Route53 public hosted zone.
+ *
+ * Each configuration property from the CDK {@link PublicHostedZoneProps} 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 a
+ * public hosted zone with the configured properties and returns a
+ * {@link HostedZoneBuilderResult}.
+ *
+ * @example
+ * ```ts
+ * const zone = createHostedZoneBuilder()
+ *   .zoneName("example.com")
+ *   .comment("Primary customer-facing domain");
+ * ```
+ */
+export type IHostedZoneBuilder = IBuilder<HostedZoneBuilderProps, HostedZoneBuilder>;
+declare class HostedZoneBuilder implements Lifecycle<HostedZoneBuilderResult> {
+    props: Partial<HostedZoneBuilderProps>;
+    build(scope: IConstruct, id: string): HostedZoneBuilderResult;
+}
+/**
+ * Creates a new {@link IHostedZoneBuilder} for configuring a Route53 public
+ * hosted zone.
+ *
+ * This is the entry point for defining a public hosted zone component. The
+ * returned builder exposes every {@link HostedZoneBuilderProps} property as a
+ * fluent setter/getter and implements {@link Lifecycle} for use with
+ * {@link compose}.
+ *
+ * @returns A fluent builder for a Route53 public hosted zone.
+ *
+ * @example
+ * ```ts
+ * const zone = createHostedZoneBuilder().zoneName("example.com");
+ *
+ * // Use standalone:
+ * const result = zone.build(stack, "SiteZone");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { zone, cert: createCertificateBuilder()
+ *       .domainName("example.com")
+ *       .validationZone(ref("zone", (r: HostedZoneBuilderResult) => r.hostedZone)) },
+ *   { zone: [], cert: ["zone"] },
+ * );
+ * ```
+ */
+export declare function createHostedZoneBuilder(): IHostedZoneBuilder;
+export {};
+//# sourceMappingURL=hosted-zone-builder.d.ts.map

package/dist/hosted-zone-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-zone-builder.d.ts","sourceRoot":"","sources":["../src/hosted-zone-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG5E;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG,qBAAqB,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,sBAAsB,EAAE,iBAAiB,CAAC,CAAC;AAErF,cAAM,iBAAkB,YAAW,SAAS,CAAC,uBAAuB,CAAC;IACnE,KAAK,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAM;IAE5C,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,uBAAuB;CAiB9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,uBAAuB,IAAI,kBAAkB,CAE5D"}

package/dist/hosted-zone-builder.js

@@ -0,0 +1,49 @@
+import { PublicHostedZone } from "aws-cdk-lib/aws-route53";
+import { Builder } from "@composurecdk/core";
+import { HOSTED_ZONE_DEFAULTS } from "./defaults.js";
+class HostedZoneBuilder {
+    props = {};
+    build(scope, id) {
+        if (!this.props.zoneName) {
+            throw new Error(`HostedZoneBuilder "${id}" requires a zoneName. ` +
+                `Call .zoneName() with a fully-qualified domain.`);
+        }
+        const mergedProps = {
+            ...HOSTED_ZONE_DEFAULTS,
+            ...this.props,
+        };
+        const hostedZone = new PublicHostedZone(scope, id, mergedProps);
+        return { hostedZone };
+    }
+}
+/**
+ * Creates a new {@link IHostedZoneBuilder} for configuring a Route53 public
+ * hosted zone.
+ *
+ * This is the entry point for defining a public hosted zone component. The
+ * returned builder exposes every {@link HostedZoneBuilderProps} property as a
+ * fluent setter/getter and implements {@link Lifecycle} for use with
+ * {@link compose}.
+ *
+ * @returns A fluent builder for a Route53 public hosted zone.
+ *
+ * @example
+ * ```ts
+ * const zone = createHostedZoneBuilder().zoneName("example.com");
+ *
+ * // Use standalone:
+ * const result = zone.build(stack, "SiteZone");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { zone, cert: createCertificateBuilder()
+ *       .domainName("example.com")
+ *       .validationZone(ref("zone", (r: HostedZoneBuilderResult) => r.hostedZone)) },
+ *   { zone: [], cert: ["zone"] },
+ * );
+ * ```
+ */
+export function createHostedZoneBuilder() {
+    return Builder(HostedZoneBuilder);
+}
+//# sourceMappingURL=hosted-zone-builder.js.map

package/dist/hosted-zone-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-zone-builder.js","sourceRoot":"","sources":["../src/hosted-zone-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAA8B,MAAM,yBAAyB,CAAC;AAEvF,OAAO,EAAE,OAAO,EAAiC,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA2CrD,MAAM,iBAAiB;IACrB,KAAK,GAAoC,EAAE,CAAC;IAE5C,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,sBAAsB,EAAE,yBAAyB;gBAC/C,iDAAiD,CACpD,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG;YAClB,GAAG,oBAAoB;YACvB,GAAG,IAAI,CAAC,KAAK;SACW,CAAC;QAE3B,MAAM,UAAU,GAAG,IAAI,gBAAgB,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QAEhE,OAAO,EAAE,UAAU,EAAE,CAAC;IACxB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,OAAO,CAA4C,iBAAiB,CAAC,CAAC;AAC/E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createHostedZoneBuilder, type HostedZoneBuilderResult, type IHostedZoneBuilder, } from "./hosted-zone-builder.js";
+export { createARecordBuilder, type ARecordBuilderResult, type IARecordBuilder, } from "./a-record-builder.js";
+export { createAaaaRecordBuilder, type AaaaRecordBuilderResult, type IAaaaRecordBuilder, } from "./aaaa-record-builder.js";
+export { createCnameRecordBuilder, type CnameRecordBuilderResult, type ICnameRecordBuilder, } from "./cname-record-builder.js";
+export { createTxtRecordBuilder, type TxtRecordBuilderResult, type ITxtRecordBuilder, } from "./txt-record-builder.js";
+export { cloudfrontAliasTarget, apiGatewayAliasTarget, apiGatewayDomainAliasTarget, } from "./alias-targets.js";
+export { HOSTED_ZONE_DEFAULTS, A_RECORD_DEFAULTS, AAAA_RECORD_DEFAULTS, CNAME_RECORD_DEFAULTS, TXT_RECORD_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,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { createHostedZoneBuilder, } from "./hosted-zone-builder.js";
+export { createARecordBuilder, } from "./a-record-builder.js";
+export { createAaaaRecordBuilder, } from "./aaaa-record-builder.js";
+export { createCnameRecordBuilder, } from "./cname-record-builder.js";
+export { createTxtRecordBuilder, } from "./txt-record-builder.js";
+export { cloudfrontAliasTarget, apiGatewayAliasTarget, apiGatewayDomainAliasTarget, } from "./alias-targets.js";
+export { HOSTED_ZONE_DEFAULTS, A_RECORD_DEFAULTS, AAAA_RECORD_DEFAULTS, CNAME_RECORD_DEFAULTS, TXT_RECORD_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,uBAAuB,GAGxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,uBAAuB,GAGxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,wBAAwB,GAGzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,sBAAsB,GAGvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,eAAe,CAAC"}

package/dist/txt-record-builder.d.ts

@@ -0,0 +1,38 @@
+import { TxtRecord, type TxtRecordProps, type IHostedZone } from "aws-cdk-lib/aws-route53";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+/**
+ * Configuration properties for the Route53 TXT record builder.
+ *
+ * Extends the CDK {@link TxtRecordProps} but replaces `zone` with a
+ * {@link Resolvable} so it can be wired from composed components.
+ */
+export interface TxtRecordBuilderProps extends Omit<TxtRecordProps, "zone"> {
+    /** The hosted zone in which to create the record. */
+    zone?: Resolvable<IHostedZone>;
+}
+/**
+ * The build output of an {@link ITxtRecordBuilder}.
+ */
+export interface TxtRecordBuilderResult {
+    /** The Route53 TXT record construct created by the builder. */
+    record: TxtRecord;
+}
+/**
+ * A fluent builder for configuring and creating a Route53 TXT record.
+ *
+ * Commonly used for SPF, DKIM, DMARC, and domain-verification tokens.
+ */
+export type ITxtRecordBuilder = IBuilder<TxtRecordBuilderProps, TxtRecordBuilder>;
+declare class TxtRecordBuilder implements Lifecycle<TxtRecordBuilderResult> {
+    props: Partial<TxtRecordBuilderProps>;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): TxtRecordBuilderResult;
+}
+/**
+ * Creates a new {@link ITxtRecordBuilder} for configuring a Route53 TXT record.
+ *
+ * @returns A fluent builder for a Route53 TXT record.
+ */
+export declare function createTxtRecordBuilder(): ITxtRecordBuilder;
+export {};
+//# sourceMappingURL=txt-record-builder.d.ts.map

package/dist/txt-record-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"txt-record-builder.d.ts","sourceRoot":"","sources":["../src/txt-record-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3F,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAG5B;;;;;GAKG;AACH,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC;IACzE,qDAAqD;IACrD,IAAI,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,qBAAqB,EAAE,gBAAgB,CAAC,CAAC;AAElF,cAAM,gBAAiB,YAAW,SAAS,CAAC,sBAAsB,CAAC;IACjE,KAAK,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAM;IAE3C,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,sBAAsB;CAyB/F;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,iBAAiB,CAE1D"}

package/dist/txt-record-builder.js

@@ -0,0 +1,34 @@
+import { TxtRecord } from "aws-cdk-lib/aws-route53";
+import { Builder, resolve, } from "@composurecdk/core";
+import { TXT_RECORD_DEFAULTS } from "./defaults.js";
+class TxtRecordBuilder {
+    props = {};
+    build(scope, id, context) {
+        const { zone, values, ...rest } = this.props;
+        if (!zone) {
+            throw new Error(`TxtRecordBuilder "${id}" requires a zone. Call .zone() with an IHostedZone.`);
+        }
+        if (!values || values.length === 0) {
+            throw new Error(`TxtRecordBuilder "${id}" requires non-empty values. ` +
+                `Call .values() with one or more TXT record strings.`);
+        }
+        const resolvedContext = context ?? {};
+        const mergedProps = {
+            ...TXT_RECORD_DEFAULTS,
+            ...rest,
+            values,
+            zone: resolve(zone, resolvedContext),
+        };
+        const record = new TxtRecord(scope, id, mergedProps);
+        return { record };
+    }
+}
+/**
+ * Creates a new {@link ITxtRecordBuilder} for configuring a Route53 TXT record.
+ *
+ * @returns A fluent builder for a Route53 TXT record.
+ */
+export function createTxtRecordBuilder() {
+    return Builder(TxtRecordBuilder);
+}
+//# sourceMappingURL=txt-record-builder.js.map

package/dist/txt-record-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"txt-record-builder.js","sourceRoot":"","sources":["../src/txt-record-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyC,MAAM,yBAAyB,CAAC;AAE3F,OAAO,EACL,OAAO,EAGP,OAAO,GAER,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AA4BpD,MAAM,gBAAgB;IACpB,KAAK,GAAmC,EAAE,CAAC;IAE3C,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,OAAgC;QACnE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAC7C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CACb,qBAAqB,EAAE,sDAAsD,CAC9E,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,qBAAqB,EAAE,+BAA+B;gBACpD,qDAAqD,CACxD,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,OAAO,IAAI,EAAE,CAAC;QACtC,MAAM,WAAW,GAAG;YAClB,GAAG,mBAAmB;YACtB,GAAG,IAAI;YACP,MAAM;YACN,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,eAAe,CAAC;SACnB,CAAC;QAEpB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QACrD,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,OAAO,CAA0C,gBAAgB,CAAC,CAAC;AAC5E,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@composurecdk/route53",
+  "version": "0.3.3",
+  "description": "Composable Route53 hosted zone and record builders with well-architected defaults",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laazyj/composureCDK",
+    "directory": "packages/route53"
+  },
+  "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.3.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "aws-cdk-lib": "^2.250.0",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
+  }
+}