@composurecdk/core 0.5.1 → 0.7.0

package/dist/builder.d.ts

@@ -9,6 +9,31 @@ type Constructor<T> = new () => T;
 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.
  *
@@ -20,6 +45,9 @@ interface ObjectWithProps<Props extends object> {
  * 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.
  */
@@ -27,11 +55,37 @@ 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.
@@ -39,8 +93,11 @@ export type IBuilder<Props extends object, T> = {
  * - For all other members: delegates directly to the underlying instance.
  *
  * @param constructor - The class to instantiate and wrap.
- * @returns A fluent {@link IBuilder} wrapping a new instance of `T`.
+ * @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>): IBuilder<Props, T>;
+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/builder.d.ts.map

@@ -1 +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;;;;;;;;;;;;;GAaG;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,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,KAAK,SAAS,MAAM,EAAE,CAAC,SAAS,eAAe,CAAC,KAAK,CAAC,EAC5E,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,GAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAoCpB"}
+{"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/builder.js

@@ -1,7 +1,34 @@
+/**
+ * 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 const COPY_STATE = Symbol.for("composurecdk.builder.copyState");
 /**
  * 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.
@@ -9,16 +36,29 @@
  * - For all other members: delegates directly to the underlying instance.
  *
  * @param constructor - The class to instantiate and wrap.
- * @returns A fluent {@link IBuilder} wrapping a new instance of `T`.
+ * @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 function Builder(constructor) {
-    const instance = new constructor();
+export function Builder(constructor, instance = new constructor()) {
     const methods = new Set(Object.getOwnPropertyNames(Object.getPrototypeOf(instance)).filter((key) => key !== "constructor" && typeof instance[key] === "function"));
     const proxy = new Proxy(instance, {
         get(target, prop) {
             if (typeof prop === "symbol") {
                 return Reflect.get(target, prop);
             }
+            if (prop === "copy") {
+                return () => {
+                    const next = new constructor();
+                    next.props = { ...target.props };
+                    const hook = target[COPY_STATE];
+                    if (typeof hook === "function") {
+                        hook.call(target, next);
+                    }
+                    return Builder(constructor, next);
+                };
+            }
             // Props getter/setter
             if (!methods.has(prop)) {
                 return (...args) => {

package/dist/builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,OAAO,CACrB,WAA2B;IAE3B,MAAM,QAAQ,GAAG,IAAI,WAAW,EAAE,CAAC;IACnC,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,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"}
+{"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/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/construct-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"construct-id.js","sourceRoot":"","sources":["../src/construct-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4CAA4C;AAC5C,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"}
+{"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/index.d.ts

@@ -1,4 +1,4 @@
-export { Builder, type IBuilder } from "./builder.js";
+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";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AACtD,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"}
+{"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/index.js

@@ -1,4 +1,4 @@
-export { Builder } from "./builder.js";
+export { Builder, COPY_STATE } from "./builder.js";
 export { constructId, sanitizeConstructId } from "./construct-id.js";
 export { compose, } from "./compose.js";
 export { CyclicDependencyError } from "./cyclic-dependency-error.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAiB,MAAM,cAAc,CAAC;AACtD,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"}
+{"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/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/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/testing.js

@@ -0,0 +1,121 @@
+/**
+ * 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 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/testing.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/core",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Composable CDK component system — lifecycle, dependency resolution, and builder pattern",
   "repository": {
     "type": "git",
@@ -13,6 +13,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing.js",
+      "types": "./dist/testing.d.ts"
     }
   },
   "files": [