@composurecdk/core 0.6.0 → 0.8.0

package/dist/commonjs/testing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Asserts that {@link IBuilder.copy | `.copy()`} returns an independent
+ * builder that preserves non-`props` state set via {@link COPY_STATE}.
+ *
+ * The helper is the standard way per-package tests verify each accumulator
+ * a builder holds outside `props`. It executes the following sequence and
+ * asserts the two invariants implied by ADR-0005:
+ *
+ * 1. Build a **baseline**: `factory()` then `configure()`.
+ * 2. Build the **copy**: `factory()`, `configure()`, then `.copy()`.
+ *    Apply `mutate()` to the original *after* the copy is taken.
+ * 3. Build the **original** (now carrying both `configure` and `mutate`).
+ *
+ * Note that the baseline is constructed via `factory()` rather than via
+ * `.copy()` — using `.copy()` would make the helper unable to detect a
+ * broken `[COPY_STATE]`, since both the "baseline" and the "copy" would
+ * drop the same state and still match.
+ *
+ * Then:
+ *
+ * - `inspect(copyResult)` must deep-equal `inspect(baselineResult)` —
+ *   the copy preserved exactly the state that `configure` set up.
+ *   A failure here means `[COPY_STATE]` is missing, incomplete, or buggy.
+ * - `inspect(originalResult)` must deep-not-equal `inspect(baselineResult)` —
+ *   `mutate` actually changed inspectable state. Without this sanity
+ *   check, a no-op `mutate` would let the first assertion pass
+ *   trivially, hiding an isolation bug.
+ *
+ * @param args.factory - Returns a fresh, unconfigured builder. Called
+ *   twice — the helper builds two independent instances so that the
+ *   build calls don't share construct scopes and so the baseline does
+ *   not depend on `.copy()`.
+ * @param args.configure - Applies the state under test (e.g. adds a
+ *   `customAlarm`, configures `#vpc`, appends a `subscription`). Called
+ *   on the baseline and on the original.
+ * @param args.mutate - Applied to the original *after* the copy is taken.
+ *   Must change something the `inspect` callback can see — typically a
+ *   second `configure`-shaped call that adds another item to the
+ *   accumulator under test.
+ * @param args.build - Calls `.build(scope, id)` against a fresh CDK
+ *   scope. Three separate scopes are required (one per build) — return a
+ *   freshly constructed scope each call. Reusing a scope across calls
+ *   surfaces as a CDK duplicate-id error rather than a silent leak.
+ * @param args.inspect - Extracts the slice of the build result whose
+ *   shape depends on the state under test (e.g.
+ *   `result => Object.keys(result.alarms)`).
+ *
+ * @example
+ * ```ts
+ * import { App, Stack } from "aws-cdk-lib";
+ * import { assertCopyPreservesState } from "@composurecdk/core/testing";
+ *
+ * assertCopyPreservesState({
+ *   factory: () => createCertificateBuilder().domainName("example.com"),
+ *   configure: (b) => b.customAlarm({ id: "FirstAlarm", ... }),
+ *   mutate: (b) => b.customAlarm({ id: "SecondAlarm", ... }),
+ *   build: (b) => b.build(new Stack(new App(), "S"), "Cert"),
+ *   inspect: (r) => Object.keys(r.alarms).sort(),
+ * });
+ * ```
+ */
+export declare function assertCopyPreservesState<B extends {
+    copy(): B;
+}, R>(args: {
+    factory: () => B;
+    configure: (builder: B) => void;
+    mutate: (builder: B) => void;
+    build: (builder: B) => R;
+    inspect: (result: R) => unknown;
+}): void;
+//# sourceMappingURL=testing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS;IAAE,IAAI,IAAI,CAAC,CAAA;CAAE,EAAE,CAAC,EAAE,IAAI,EAAE;IACzE,OAAO,EAAE,MAAM,CAAC,CAAC;IACjB,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAChC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAC7B,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;IACzB,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC;CACjC,GAAG,IAAI,CAsCP"}

package/dist/commonjs/testing.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertCopyPreservesState = assertCopyPreservesState;
+/**
+ * Asserts that {@link IBuilder.copy | `.copy()`} returns an independent
+ * builder that preserves non-`props` state set via {@link COPY_STATE}.
+ *
+ * The helper is the standard way per-package tests verify each accumulator
+ * a builder holds outside `props`. It executes the following sequence and
+ * asserts the two invariants implied by ADR-0005:
+ *
+ * 1. Build a **baseline**: `factory()` then `configure()`.
+ * 2. Build the **copy**: `factory()`, `configure()`, then `.copy()`.
+ *    Apply `mutate()` to the original *after* the copy is taken.
+ * 3. Build the **original** (now carrying both `configure` and `mutate`).
+ *
+ * Note that the baseline is constructed via `factory()` rather than via
+ * `.copy()` — using `.copy()` would make the helper unable to detect a
+ * broken `[COPY_STATE]`, since both the "baseline" and the "copy" would
+ * drop the same state and still match.
+ *
+ * Then:
+ *
+ * - `inspect(copyResult)` must deep-equal `inspect(baselineResult)` —
+ *   the copy preserved exactly the state that `configure` set up.
+ *   A failure here means `[COPY_STATE]` is missing, incomplete, or buggy.
+ * - `inspect(originalResult)` must deep-not-equal `inspect(baselineResult)` —
+ *   `mutate` actually changed inspectable state. Without this sanity
+ *   check, a no-op `mutate` would let the first assertion pass
+ *   trivially, hiding an isolation bug.
+ *
+ * @param args.factory - Returns a fresh, unconfigured builder. Called
+ *   twice — the helper builds two independent instances so that the
+ *   build calls don't share construct scopes and so the baseline does
+ *   not depend on `.copy()`.
+ * @param args.configure - Applies the state under test (e.g. adds a
+ *   `customAlarm`, configures `#vpc`, appends a `subscription`). Called
+ *   on the baseline and on the original.
+ * @param args.mutate - Applied to the original *after* the copy is taken.
+ *   Must change something the `inspect` callback can see — typically a
+ *   second `configure`-shaped call that adds another item to the
+ *   accumulator under test.
+ * @param args.build - Calls `.build(scope, id)` against a fresh CDK
+ *   scope. Three separate scopes are required (one per build) — return a
+ *   freshly constructed scope each call. Reusing a scope across calls
+ *   surfaces as a CDK duplicate-id error rather than a silent leak.
+ * @param args.inspect - Extracts the slice of the build result whose
+ *   shape depends on the state under test (e.g.
+ *   `result => Object.keys(result.alarms)`).
+ *
+ * @example
+ * ```ts
+ * import { App, Stack } from "aws-cdk-lib";
+ * import { assertCopyPreservesState } from "@composurecdk/core/testing";
+ *
+ * assertCopyPreservesState({
+ *   factory: () => createCertificateBuilder().domainName("example.com"),
+ *   configure: (b) => b.customAlarm({ id: "FirstAlarm", ... }),
+ *   mutate: (b) => b.customAlarm({ id: "SecondAlarm", ... }),
+ *   build: (b) => b.build(new Stack(new App(), "S"), "Cert"),
+ *   inspect: (r) => Object.keys(r.alarms).sort(),
+ * });
+ * ```
+ */
+function assertCopyPreservesState(args) {
+    const { factory, configure, mutate, build, inspect } = args;
+    const baseline = factory();
+    configure(baseline);
+    const baselineState = inspect(build(baseline));
+    const original = factory();
+    configure(original);
+    if (typeof original.copy !== "function") {
+        throw new Error("assertCopyPreservesState: builder returned by `factory` has no `.copy()` method. " +
+            "Pass a builder produced by `Builder()` / `taggedBuilder()` from `@composurecdk/core` / `@composurecdk/cloudformation`.");
+    }
+    const copy = original.copy();
+    mutate(original);
+    const originalState = inspect(build(original));
+    const copyState = inspect(build(copy));
+    if (deepEqual(originalState, baselineState)) {
+        throw new Error("assertCopyPreservesState: `mutate` did not change inspectable state on the original — " +
+            "the test cannot detect a leak through `.copy()`. Make `mutate` and `inspect` cover " +
+            "the same accumulator.\n" +
+            `  baseline: ${format(baselineState)}\n` +
+            `  original: ${format(originalState)}`);
+    }
+    if (!deepEqual(copyState, baselineState)) {
+        throw new Error("assertCopyPreservesState: `.copy()` did not preserve state set by `configure`. " +
+            "The builder is missing, incomplete, or has a buggy `[COPY_STATE]` hook (see ADR-0005).\n" +
+            `  baseline: ${format(baselineState)}\n` +
+            `  copy:     ${format(copyState)}`);
+    }
+}
+function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" || a === null)
+        return false;
+    if (typeof b !== "object" || b === null)
+        return false;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEqual(item, b[i]));
+    }
+    if (Array.isArray(b))
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    const bRec = b;
+    return aKeys.every((k) => Object.prototype.hasOwnProperty.call(bRec, k) &&
+        deepEqual(a[k], bRec[k]));
+}
+function format(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=testing.js.map

package/dist/commonjs/testing.js.map

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

package/dist/esm/builder.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Constructs an instance of `T`.
+ */
+type Constructor<T> = new () => T;
+/**
+ * Constrains `T` to have a mutable `props` property of type `Props`.
+ * Classes used with {@link Builder} must expose their configuration this way.
+ */
+interface ObjectWithProps<Props extends object> {
+    props: Partial<Props>;
+}
+/**
+ * Optional hook a builder class can implement to clone non-`props` state
+ * during {@link IBuilder.copy}.
+ *
+ * The default `.copy()` shallow-clones `props` and wraps a fresh instance.
+ * State stored outside `props` (private fields, internal accumulators) is
+ * invisible to that default. A class with such state defines a method
+ * keyed by this symbol to copy it onto the new instance.
+ *
+ * See ADR-0005 for the full protocol, including how decorator layers
+ * participate.
+ *
+ * @example
+ * ```ts
+ * class StackBuilder {
+ *   props: Partial<StackProps> = {};
+ *   readonly #tags: [string, string][] = [];
+ *
+ *   [COPY_STATE](target: StackBuilder): void {
+ *     target.#tags.push(...this.#tags);
+ *   }
+ * }
+ * ```
+ */
+export declare const COPY_STATE: unique symbol;
+/**
+ * A fluent builder interface generated from a props type and a target class.
+ *
+ * For each key in `Props`, the builder exposes an overloaded method:
+ * - Called with an argument: sets the prop value and returns the builder for chaining.
+ * - Called with no arguments: returns the current prop value.
+ *
+ * Methods from `T` that return `T` (chainable methods) have their return type
+ * replaced to return the builder. All other members of `T` pass through as-is,
+ * allowing methods like `build()` to be called directly on the builder.
+ *
+ * Every builder also exposes {@link IBuilder.copy | `.copy()`}, which returns
+ * an independent builder with the same configured state.
+ *
+ * @typeParam Props - The configurable properties.
+ * @typeParam T - The target class the builder wraps.
+ */
+export type IBuilder<Props extends object, T> = {
+    [K in keyof Props]-?: ((arg: Props[K]) => IBuilder<Props, T>) & (() => Props[K]);
+} & {
+    [K in keyof T]: T[K] extends (...args: infer A) => T ? (...args: A) => IBuilder<Props, T> : T[K];
+} & {
+    /**
+     * Returns an independent builder with the same configured props and any
+     * state that the underlying class copies via {@link COPY_STATE}.
+     *
+     * Mutations to the returned builder do not affect the original, and
+     * vice versa.
+     *
+     * `props` is shallow-cloned (`{ ...this.props }`). Top-level keys are
+     * independent; nested object references (CDK constructs, IRoles, IVpcs,
+     * etc.) are shared by design — they are construct identities, not
+     * configuration data. Builders with internal lists/maps/sets that should
+     * be deep-cloned implement {@link COPY_STATE}.
+     *
+     * Use cases:
+     * - **Variant authoring** — derive multiple builders from a shared base
+     *   (`const us = base.copy().region("us-east-1")`).
+     * - **Strategy hand-off snapshot** — pass an isolated builder to a stack
+     *   strategy (`singleStack(base.copy())`) so later mutations to the
+     *   original don't leak into the strategy's lazy `build()`.
+     *
+     * See ADR-0005 for the design rationale.
+     */
+    copy(): IBuilder<Props, T>;
+};
+/**
+ * Creates a fluent builder wrapping an instance of `T`.
+ *
+ * The builder is backed by a {@link Proxy} that intercepts property access:
+ * - For `copy`: returns a function that produces an independent builder with
+ *   the same configured state (see {@link IBuilder.copy}).
+ * - For keys in `Props`: returns a getter/setter function. When called with a
+ *   value, it sets the prop and returns the builder. When called with no args,
+ *   it returns the current value.
+ * - For methods on `T` that return `T`: wraps them to return the builder instead.
+ * - For all other members: delegates directly to the underlying instance.
+ *
+ * @param constructor - The class to instantiate and wrap.
+ * @param instance - Optional pre-existing instance to wrap. Defaults to
+ *   `new constructor()`. Used internally by {@link IBuilder.copy} to wrap a
+ *   freshly cloned instance without re-running the constructor for new state.
+ * @returns A fluent {@link IBuilder} wrapping `instance`.
+ */
+export declare function Builder<Props extends object, T extends ObjectWithProps<Props>>(constructor: Constructor<T>, instance?: T): IBuilder<Props, T>;
+export {};
+//# sourceMappingURL=builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/builder.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,KAAK,WAAW,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC;AAElC;;;GAGG;AACH,UAAU,eAAe,CAAC,KAAK,SAAS,MAAM;IAC5C,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,UAAU,eAA+C,CAAC;AAEvE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,QAAQ,CAAC,KAAK,SAAS,MAAM,EAAE,CAAC,IAAI;KAC7C,CAAC,IAAI,MAAM,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;CACjF,GAAG;KACD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACjG,GAAG;IACF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,KAAK,SAAS,MAAM,EAAE,CAAC,SAAS,eAAe,CAAC,KAAK,CAAC,EAC5E,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,EAC3B,QAAQ,GAAE,CAAqB,GAC9B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CA+CpB"}

package/dist/esm/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/builder.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAiDvE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,OAAO,CACrB,WAA2B,EAC3B,WAAc,IAAI,WAAW,EAAE;IAE/B,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAChE,CAAC,GAAG,EAAE,EAAE,CACN,GAAG,KAAK,aAAa,IAAI,OAAQ,QAAoC,CAAC,GAAG,CAAC,KAAK,UAAU,CAC5F,CACF,CAAC;IAEF,MAAM,KAAK,GAAuB,IAAI,KAAK,CAAC,QAAQ,EAAE;QACpD,GAAG,CAAC,MAAS,EAAE,IAAqB;YAClC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAY,CAAC;YAC9C,CAAC;YAED,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpB,OAAO,GAAG,EAAE;oBACV,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;oBAC/B,IAAI,CAAC,KAAK,GAAG,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;oBACjC,MAAM,IAAI,GAAI,MAA6C,CAAC,UAAU,CAAC,CAAC;oBACxE,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;wBAC9B,IAA0B,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;oBACjD,CAAC;oBACD,OAAO,OAAO,CAAW,WAAW,EAAE,IAAI,CAAC,CAAC;gBAC9C,CAAC,CAAC;YACJ,CAAC;YAED,sBAAsB;YACtB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvB,OAAO,CAAC,GAAG,IAAe,EAAE,EAAE;oBAC5B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;wBACtB,OAAO,MAAM,CAAC,KAAK,CAAC,IAAmB,CAAC,CAAC;oBAC3C,CAAC;oBACD,MAAM,CAAC,KAAK,CAAC,IAAmB,CAAC,GAAG,IAAI,CAAC,CAAC,CAAuB,CAAC;oBAClE,OAAO,KAAK,CAAC;gBACf,CAAC,CAAC;YACJ,CAAC;YAED,gEAAgE;YAChE,MAAM,MAAM,GAAI,MAAkC,CAAC,IAAI,CAAiC,CAAC;YACzF,OAAO,CAAC,GAAG,IAAe,EAAE,EAAE;gBAC5B,MAAM,MAAM,GAAY,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACnD,OAAO,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;YAC5C,CAAC,CAAC;QACJ,CAAC;KACF,CAAuB,CAAC;IAEzB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/esm/compose.d.ts

@@ -0,0 +1,177 @@
+import { type IConstruct } from "constructs";
+import { type Lifecycle } from "./lifecycle.js";
+import { type StackStrategy } from "./stack-strategy.js";
+/**
+ * Maps a record of {@link Lifecycle} components to a record of their build outputs.
+ * Each property's type is derived from the return type of the corresponding
+ * component's `build` method, preserving full type information through composition.
+ *
+ * @typeParam T - A record where every value implements {@link Lifecycle}.
+ */
+type BuildResult<T extends {
+    [Property in keyof T]: Lifecycle;
+}> = {
+    [Property in keyof T]: ReturnType<T[Property]["build"]>;
+};
+/**
+ * Declares which other components a component depends on within a system.
+ * Dependencies are expressed as an array of component keys. During build,
+ * the resolved outputs of these components are passed as the component's context.
+ *
+ * @typeParam Components - The full set of components in the system.
+ */
+type Dependency<Components extends Record<string, Lifecycle>> = (keyof Components)[];
+/**
+ * A callback invoked after all components in a composed system have been
+ * built. Receives the top-level scope, system id, the fully-typed build
+ * results of every component, and a record mapping each component key to
+ * the scope it was built into.
+ *
+ * `componentScopes` makes per-component scopes visible to hooks so they can
+ * attach additional constructs to the same stack a given component was
+ * routed to — useful under {@link ComposedSystem.withStacks} or
+ * {@link ComposedSystem.withStackStrategy}, where different components may
+ * live in different stacks.
+ *
+ * Domain-specific packages provide helper functions that return hooks. For
+ * example, `@composurecdk/cloudformation` exports {@link outputs} which
+ * creates `CfnOutput` constructs from {@link Ref}-based definitions.
+ *
+ * @typeParam T - The build result type of the composed system.
+ *
+ * @example
+ * ```ts
+ * const logResults: AfterBuildHook<{ site: BucketBuilderResult }> =
+ *   (_scope, _id, results) => {
+ *     console.log("Bucket:", results.site.bucket.bucketName);
+ *   };
+ * ```
+ */
+export type AfterBuildHook<T extends object> = (scope: IConstruct, id: string, results: T, componentScopes: {
+    readonly [K in keyof T]: IConstruct;
+}) => void;
+/**
+ * A {@link Lifecycle} produced by {@link compose}, extended with methods
+ * for controlling how components are routed to scopes and for registering
+ * post-build hooks.
+ *
+ * Because `ComposedSystem` extends `Lifecycle`, a composed system can be
+ * nested as a component inside another `compose` call — composition is
+ * recursive.
+ */
+export interface ComposedSystem<Components extends Record<string, Lifecycle>> extends Lifecycle<BuildResult<Components>> {
+    /**
+     * Returns a new {@link Lifecycle} that routes components to specific scopes
+     * (typically Stacks) during build. Components not listed in the map use the
+     * default scope passed to `build`.
+     *
+     * Accepts any `IConstruct`, so `Stack`, `DeploymentStack`, or custom
+     * subclasses all work.
+     *
+     * @param stacks - A partial map from component key to scope.
+     * @returns A {@link Lifecycle} with stack routing applied.
+     *
+     * @example
+     * ```ts
+     * compose({ handler, api }, { handler: [], api: ["handler"] })
+     *   .withStacks({ handler: serviceStack, api: apiStack })
+     *   .build(app, "MySystem");
+     * ```
+     */
+    withStacks(stacks: {
+        [K in keyof Components]?: IConstruct;
+    }): ConfiguredSystem<Components>;
+    /**
+     * Returns a new {@link ConfiguredSystem} that uses a {@link StackStrategy}
+     * to determine each component's scope during build. The returned system
+     * supports further chaining of {@link ConfiguredSystem.afterBuild | .afterBuild()} hooks.
+     *
+     * Mutually exclusive with {@link withStacks} — calling one locks the
+     * stack routing; further stack-routing methods are not available on the
+     * returned {@link ConfiguredSystem}.
+     *
+     * @param strategy - The strategy that resolves scopes for components.
+     * @returns A {@link ConfiguredSystem} with strategy-based stack routing applied.
+     *
+     * @example
+     * ```ts
+     * compose({ handler, api, table }, { ... })
+     *   .withStackStrategy(groupedStacks(
+     *     key => key === "table" ? "persistence" : "service",
+     *     (app, id) => new Stack(app, id),
+     *   ))
+     *   .afterBuild(outputs({ ... }))
+     *   .build(app, "MySystem");
+     * ```
+     */
+    withStackStrategy(strategy: StackStrategy): ConfiguredSystem<Components>;
+    /**
+     * Returns a new {@link ConfiguredSystem} that invokes the given hook after
+     * all components have been built. The hook receives the scope, system id,
+     * and the fully-typed build results.
+     *
+     * Multiple hooks can be chained — each `.afterBuild()` appends to the
+     * hook list and returns the same {@link ConfiguredSystem} for further
+     * chaining.
+     *
+     * This is the extension point for adding post-build behaviour to a
+     * composed system without modifying the system itself. Domain-specific
+     * packages provide helper functions that return hooks — for example,
+     * `outputs()` from `@composurecdk/cloudformation` creates CfnOutput
+     * constructs.
+     *
+     * @param hook - A callback invoked after all components are built.
+     * @returns A {@link ConfiguredSystem} with the hook applied.
+     *
+     * @example
+     * ```ts
+     * compose({ site, cdn }, { site: [], cdn: ["site"] })
+     *   .afterBuild(outputs({
+     *     Url: { value: ref("cdn", r => r.distribution.domainName) },
+     *   }))
+     *   .build(stack, "MySystem");
+     * ```
+     */
+    afterBuild(hook: AfterBuildHook<BuildResult<Components>>): ConfiguredSystem<Components>;
+}
+/**
+ * A {@link Lifecycle} with stack routing or post-build hooks applied.
+ * Returned by {@link ComposedSystem.withStacks},
+ * {@link ComposedSystem.withStackStrategy}, and
+ * {@link ComposedSystem.afterBuild}.
+ *
+ * Supports chaining further {@link afterBuild} hooks. Stack routing methods
+ * are not available — they are mutually exclusive and must be chosen on
+ * the original {@link ComposedSystem}.
+ */
+export interface ConfiguredSystem<Components extends Record<string, Lifecycle>> extends Lifecycle<BuildResult<Components>> {
+    /**
+     * Appends a post-build hook. Multiple hooks can be chained; they execute
+     * in registration order after all components have been built.
+     *
+     * @param hook - A callback invoked after all components are built.
+     * @returns This {@link ConfiguredSystem} for further chaining.
+     */
+    afterBuild(hook: AfterBuildHook<BuildResult<Components>>): ConfiguredSystem<Components>;
+}
+/**
+ * Composes a set of {@link Lifecycle} components into a single system that
+ * manages their build order and dependency resolution.
+ *
+ * A directed acyclic graph is built eagerly from the declared dependencies.
+ * Cyclic dependencies are detected at composition time and throw immediately.
+ * When `build` is called, components are built in topological order, each
+ * receiving the build outputs of its dependencies as its context.
+ *
+ * The returned {@link ComposedSystem} is a {@link Lifecycle}, so it can be
+ * nested as a component in a larger `compose` call.
+ *
+ * @param components - A record of named {@link Lifecycle} components.
+ * @param dependencies - For each component, the list of other component keys it depends on.
+ * @returns A {@link ComposedSystem} whose build output is the combined {@link BuildResult} of all components.
+ */
+export declare function compose<Components extends Record<string, Lifecycle>>(components: Components, dependencies: {
+    [Property in keyof Components]: Dependency<Components>;
+}): ComposedSystem<Components>;
+export {};
+//# sourceMappingURL=compose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/compose.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,KAAK,WAAW,CAAC,CAAC,SAAS;KAAG,QAAQ,IAAI,MAAM,CAAC,GAAG,SAAS;CAAE,IAAI;KAChE,QAAQ,IAAI,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;CACxD,CAAC;AAEF;;;;;;GAMG;AACH,KAAK,UAAU,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,UAAU,CAAC,EAAE,CAAC;AA+BrF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,CAC7C,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,CAAC,EACV,eAAe,EAAE;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,UAAU;CAAE,KACrD,IAAI,CAAC;AAEV;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAE,SAAQ,SAAS,CAC7F,WAAW,CAAC,UAAU,CAAC,CACxB;IACC;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,MAAM,EAAE;SAAG,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,EAAE,UAAU;KAAE,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAE3F;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;CACzF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAE,SAAQ,SAAS,CAC/F,WAAW,CAAC,UAAU,CAAC,CACxB;IACC;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;CACzF;AA0HD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAClE,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE;KAAG,QAAQ,IAAI,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC;CAAE,GACvE,cAAc,CAAC,UAAU,CAAC,CAE5B"}

package/dist/esm/compose.js.map

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

package/dist/esm/construct-id.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Utilities for producing safe CDK construct IDs from arbitrary strings.
+ *
+ * The `constructs` library uses `/` as the path separator between construct
+ * IDs. When user-supplied strings (DNS names, ARNs, filesystem paths) are
+ * passed through to a construct ID, any embedded `/` silently gets rewritten
+ * to `--`, which produces unreadable CloudFormation logical IDs. Control
+ * characters are likewise unsafe.
+ *
+ * These helpers consolidate that sanitization in one place so every builder
+ * in the monorepo applies the same constraints.
+ */
+/**
+ * Return a construct-ID-safe copy of `raw` by replacing unsafe characters
+ * (`/` and control characters) with a single `-`.
+ *
+ * Does not touch other characters — CDK construct IDs are otherwise
+ * permissive, and collapsing further (e.g., to PascalCase) would destroy
+ * information a reader expects to see in the synthesised tree.
+ *
+ * @example
+ * ```ts
+ * sanitizeConstructId("a/b")       // "a-b"
+ * sanitizeConstructId("_sip._tcp") // "_sip._tcp" (unchanged)
+ * ```
+ */
+export declare function sanitizeConstructId(raw: string): string;
+/**
+ * Join the supplied parts into a single construct ID. Falsy parts are
+ * dropped; each remaining part is passed through {@link sanitizeConstructId}
+ * and the results are joined with `-`.
+ *
+ * Intended for composing IDs from a mix of static prefixes and user-supplied
+ * fragments — the sanitization step means callers don't have to reason about
+ * what characters their inputs might contain.
+ *
+ * @example
+ * ```ts
+ * constructId("records", "a", "api")   // "records-a-api"
+ * constructId("zone", undefined, "www") // "zone-www"
+ * constructId("records", "a/b")         // "records-a-b"
+ * ```
+ */
+export declare function constructId(...parts: readonly (string | undefined | null | false)[]): string;
+//# sourceMappingURL=construct-id.d.ts.map

package/dist/esm/construct-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"construct-id.d.ts","sourceRoot":"","sources":["../../src/construct-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,GAAG,KAAK,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,KAAK,CAAC,EAAE,GAAG,MAAM,CAK5F"}

package/dist/{construct-id.js → esm/construct-id.js}

@@ -10,7 +10,7 @@
  * These helpers consolidate that sanitization in one place so every builder
  * in the monorepo applies the same constraints.
  */
-// eslint-disable-next-line no-control-regex
+// eslint-disable-next-line no-control-regex -- the regex must literally match control characters to strip them from construct IDs
 const UNSAFE = /[/\x00-\x1f\x7f]/g;
 /**
  * Return a construct-ID-safe copy of `raw` by replacing unsafe characters

package/dist/esm/construct-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"construct-id.js","sourceRoot":"","sources":["../../src/construct-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,kIAAkI;AAClI,MAAM,MAAM,GAAG,mBAAmB,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,GAAG,KAAqD;IAClF,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;SACjE,GAAG,CAAC,mBAAmB,CAAC;SACxB,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/dist/esm/cyclic-dependency-error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Thrown when {@link compose} detects a cycle in the component dependency graph.
+ * Carries the detected cycles so callers can inspect or report them programmatically.
+ */
+export declare class CyclicDependencyError extends Error {
+    readonly cycles: string[][];
+    /**
+     * @param cycles - Each element is an array of component keys forming a cycle.
+     */
+    constructor(cycles: string[][]);
+}
+//# sourceMappingURL=cyclic-dependency-error.d.ts.map

package/dist/esm/cyclic-dependency-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cyclic-dependency-error.d.ts","sourceRoot":"","sources":["../../src/cyclic-dependency-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAIlB,MAAM,EAAE,MAAM,EAAE,EAAE;IAH9C;;OAEG;gBACyB,MAAM,EAAE,MAAM,EAAE,EAAE;CAI/C"}

package/dist/esm/cyclic-dependency-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cyclic-dependency-error.js","sourceRoot":"","sources":["../../src/cyclic-dependency-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAIlB;IAH5B;;OAEG;IACH,YAA4B,MAAkB;QAC5C,KAAK,CAAC,iCAAiC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAD7D,WAAM,GAAN,MAAM,CAAY;QAE5C,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}

package/dist/esm/index.d.ts

@@ -0,0 +1,8 @@
+export { Builder, COPY_STATE, type IBuilder } from "./builder.js";
+export { constructId, sanitizeConstructId } from "./construct-id.js";
+export { compose, type ComposedSystem, type ConfiguredSystem, type AfterBuildHook, } from "./compose.js";
+export { CyclicDependencyError } from "./cyclic-dependency-error.js";
+export { type Lifecycle } from "./lifecycle.js";
+export { Ref, ref, resolve, isRef, type Resolvable } from "./ref.js";
+export { type StackStrategy, type ScopeFactory, singleStack, groupedStacks, } from "./stack-strategy.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,WAAW,EACX,aAAa,GACd,MAAM,qBAAqB,CAAC"}

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAiB,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EACL,OAAO,GAIR,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAmB,MAAM,UAAU,CAAC;AACrE,OAAO,EAGL,WAAW,EACX,aAAa,GACd,MAAM,qBAAqB,CAAC"}

package/dist/esm/lifecycle.d.ts

@@ -0,0 +1,23 @@
+import { type IConstruct } from "constructs";
+/**
+ * Base type for the dependency context passed to a component's {@link Lifecycle.build} method.
+ * A record of named dependencies, each being a record of their build outputs.
+ */
+type LifecycleComponentBase = Record<string, object>;
+/**
+ * The core interface for all ComposureCDK components. A `Lifecycle` represents
+ * a unit of infrastructure that can be built within a CDK construct tree.
+ *
+ * Components implement this interface to define what resources they create
+ * and what dependencies they require. The {@link compose} function assembles
+ * components into a system, resolving dependencies and invoking `build` in
+ * the correct order.
+ *
+ * @typeParam T - The record of resources and values this component produces when built.
+ * @typeParam Context - The resolved dependencies this component requires, keyed by component name.
+ */
+export interface Lifecycle<T extends object = object, Context extends LifecycleComponentBase = LifecycleComponentBase> {
+    build(scope: IConstruct, id: string, context?: Context): T;
+}
+export {};
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;GAGG;AACH,KAAK,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS,CACxB,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,OAAO,SAAS,sBAAsB,GAAG,sBAAsB;IAE/D,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC;CAC5D"}

package/dist/esm/lifecycle.js.map

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