@composurecdk/cloudformation 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +28 -10
  2. package/dist/stack-builder.d.ts +16 -34
  3. package/dist/stack-builder.d.ts.map +1 -1
  4. package/dist/stack-builder.js +11 -19
  5. package/dist/stack-builder.js.map +1 -1
  6. package/dist/strategies.d.ts +41 -12
  7. package/dist/strategies.d.ts.map +1 -1
  8. package/dist/strategies.js +43 -16
  9. package/dist/strategies.js.map +1 -1
  10. package/package.json +2 -2
package/README.md CHANGED
@@ -28,24 +28,20 @@ const { stack } = createStackBuilder()
28
28
  .build(app, "ServiceStack");
29
29
  ```
30
30
 
31
- ### Scope factory
31
+ ### Variants and snapshots with `.copy()`
32
32
 
33
- Convert a configured builder into a `ScopeFactory` for use with stack strategies:
33
+ `.copy()` returns an independent builder with the same configured state. Use it to derive variants from a shared base, or to snapshot a builder before handing it to a stack strategy that may be invoked after further mutations:
34
34
 
35
35
  ```ts
36
- const factory = createStackBuilder()
37
- .terminationProtection(true)
38
- .tag("team", "platform")
39
- .toScopeFactory();
36
+ const baseStack = createStackBuilder().tag("team", "platform");
40
37
 
41
- compose({ ... }, { ... })
42
- .withStackStrategy(singleStack(factory))
43
- .build(app, "MySystem");
38
+ const { stack: us } = baseStack.copy().description("US region").build(app, "UsStack");
39
+ const { stack: eu } = baseStack.copy().description("EU region").build(app, "EuStack");
44
40
  ```
45
41
 
46
42
  ## Stack Strategies
47
43
 
48
- Convenience wrappers around `@composurecdk/core`'s strategy primitives that default to creating Stacks via `createStackBuilder`. Pass an optional `ScopeFactory` to customise the Stack configuration.
44
+ Convenience wrappers around `@composurecdk/core`'s strategy primitives. Both accept a `Lifecycle<StackBuilderResult>` (typically an `IStackBuilder`) and default to a fresh `createStackBuilder()` per call.
49
45
 
50
46
  ### singleStack
51
47
 
@@ -59,6 +55,16 @@ compose({ handler, api }, { handler: [], api: ["handler"] })
59
55
  .build(app, "MySystem");
60
56
  ```
61
57
 
58
+ Pass a configured builder to apply tags, description, etc. to the strategy's stack. Use `.copy()` to snapshot the configuration when the original may be mutated later:
59
+
60
+ ```ts
61
+ const base = createStackBuilder().tag("team", "platform");
62
+
63
+ compose({ ... }, { ... })
64
+ .withStackStrategy(singleStack(base.copy()))
65
+ .build(app, "MySystem");
66
+ ```
67
+
62
68
  ### groupedStacks
63
69
 
64
70
  Groups components into named Stacks by a classifier function:
@@ -73,6 +79,18 @@ compose({ handler, api, table }, { ... })
73
79
  .build(app, "MySystem");
74
80
  ```
75
81
 
82
+ The same builder is invoked once per group key with `${systemId}-${group}` as the id, so any tags configured on the supplied builder propagate to every stack the strategy creates. As with `singleStack`, pass `builder.copy()` to snapshot the configuration when the original may be mutated after hand-off:
83
+
84
+ ```ts
85
+ const base = createStackBuilder().tag("team", "platform");
86
+
87
+ compose({ ... }, { ... })
88
+ .withStackStrategy(
89
+ groupedStacks((key) => (key === "table" ? "persistence" : "service"), base.copy()),
90
+ )
91
+ .build(app, "MySystem");
92
+ ```
93
+
76
94
  ## outputs
77
95
 
78
96
  A post-build hook that creates CloudFormation stack outputs from a composed system's build results. Output values can be concrete strings or `Ref`s that resolve against the system's results.
package/dist/stack-builder.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { Stack, type StackProps } from "aws-cdk-lib";
2
2
  import { type IConstruct } from "constructs";
3
- import { type IBuilder, type Lifecycle, type ScopeFactory } from "@composurecdk/core";
3
+ import { COPY_STATE, type IBuilder, type Lifecycle } from "@composurecdk/core";
4
4
  /**
5
5
  * The build output of a {@link IStackBuilder}. Contains the CDK Stack
6
6
  * created during {@link Lifecycle.build}.
@@ -16,14 +16,15 @@ export interface StackBuilderResult {
16
16
  * as an overloaded method: call with a value to set it (returns the builder
17
17
  * for chaining), or call with no arguments to read the current value.
18
18
  *
19
- * The builder implements {@link Lifecycle}, so it can be used directly as a
20
- * component in a {@link compose | composed system}. When built, it creates
21
- * a Stack with the configured properties and returns a
22
- * {@link StackBuilderResult}.
19
+ * The builder implements {@link Lifecycle}, so it can be used directly as
20
+ * a component in a {@link compose | composed system}, or handed to a stack
21
+ * strategy via {@link singleStack} / {@link groupedStacks}. When handing a
22
+ * builder to a strategy that may be invoked after further configuration of
23
+ * the original, pass `builder.copy()` to snapshot the current state.
23
24
  *
24
25
  * @example
25
26
  * ```ts
26
- * const stack = createStackBuilder()
27
+ * const { stack } = createStackBuilder()
27
28
  * .description("Network infrastructure")
28
29
  * .terminationProtection(true)
29
30
  * .build(app, "NetworkStack");
@@ -39,31 +40,12 @@ export type IStackBuilder = IBuilder<StackProps, StackBuilder> & {
39
40
  * @returns The builder for chaining.
40
41
  */
41
42
  tag(key: string, value: string): IStackBuilder;
42
- /**
43
- * Returns a {@link ScopeFactory} that creates Stacks with the builder's
44
- * configured properties. Use this to integrate with
45
- * {@link singleStack} or {@link groupedStacks} strategies.
46
- *
47
- * @returns A factory function compatible with stack strategies.
48
- *
49
- * @example
50
- * ```ts
51
- * const factory = createStackBuilder()
52
- * .terminationProtection(true)
53
- * .toScopeFactory();
54
- *
55
- * compose({ ... }, { ... })
56
- * .withStackStrategy(singleStack(factory))
57
- * .build(app, "MySystem");
58
- * ```
59
- */
60
- toScopeFactory(): ScopeFactory;
61
43
  };
62
44
  declare class StackBuilder implements Lifecycle<StackBuilderResult> {
63
45
  #private;
64
46
  props: Partial<StackProps>;
65
47
  tag(key: string, value: string): this;
66
- toScopeFactory(): ScopeFactory;
48
+ [COPY_STATE](next: StackBuilder): void;
67
49
  build(scope: IConstruct, id: string): StackBuilderResult;
68
50
  }
69
51
  /**
@@ -71,9 +53,9 @@ declare class StackBuilder implements Lifecycle<StackBuilderResult> {
71
53
  *
72
54
  * This is the entry point for declarative stack configuration. The returned
73
55
  * builder exposes every {@link StackProps} property as a fluent setter/getter,
74
- * plus {@link IStackBuilder.tag | .tag()} for adding tags and
75
- * {@link IStackBuilder.toScopeFactory | .toScopeFactory()} for integration
76
- * with stack strategies.
56
+ * plus {@link IStackBuilder.tag | .tag()} for adding tags. It implements
57
+ * {@link Lifecycle}, so it composes naturally and can be passed to
58
+ * {@link singleStack} or {@link groupedStacks}.
77
59
  *
78
60
  * @returns A fluent builder for a CloudFormation Stack.
79
61
  *
@@ -85,14 +67,14 @@ declare class StackBuilder implements Lifecycle<StackBuilderResult> {
85
67
  * .terminationProtection(true)
86
68
  * .build(app, "ServiceStack");
87
69
  *
88
- * // Use as a scope factory with strategies
89
- * const factory = createStackBuilder()
70
+ * // Hand a configured builder to a strategy. Use `.copy()` to snapshot
71
+ * // when the original may be mutated further.
72
+ * const base = createStackBuilder()
90
73
  * .terminationProtection(true)
91
- * .tag("team", "platform")
92
- * .toScopeFactory();
74
+ * .tag("team", "platform");
93
75
  *
94
76
  * compose({ ... }, { ... })
95
- * .withStackStrategy(singleStack(factory))
77
+ * .withStackStrategy(singleStack(base.copy()))
96
78
  * .build(app, "MySystem");
97
79
  * ```
98
80
  */
package/dist/stack-builder.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"stack-builder.d.ts","sourceRoot":"","sources":["../src/stack-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAQ,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE/F;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC,GAAG;IAC/D;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IAE/C;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,IAAI,YAAY,CAAC;CAChC,CAAC;AAEF,cAAM,YAAa,YAAW,SAAS,CAAC,kBAAkB,CAAC;;IACzD,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAM;IAGhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKrC,cAAc,IAAI,YAAY;IAY9B,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,kBAAkB;CAOzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAElD"}
1
+ {"version":3,"file":"stack-builder.d.ts","sourceRoot":"","sources":["../src/stack-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAQ,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAExF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC,GAAG;IAC/D;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;CAChD,CAAC;AAEF,cAAM,YAAa,YAAW,SAAS,CAAC,kBAAkB,CAAC;;IACzD,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAM;IAGhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKrC,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAItC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,kBAAkB;CAOzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAElD"}
package/dist/stack-builder.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { Stack, Tags } from "aws-cdk-lib";
2
- import { Builder } from "@composurecdk/core";
2
+ import { Builder, COPY_STATE } from "@composurecdk/core";
3
3
  class StackBuilder {
4
4
  props = {};
5
5
  #tags = [];
@@ -7,16 +7,8 @@ class StackBuilder {
7
7
  this.#tags.push([key, value]);
8
8
  return this;
9
9
  }
10
- toScopeFactory() {
11
- const props = { ...this.props };
12
- const tags = [...this.#tags];
13
- return (scope, id) => {
14
- const stack = new Stack(scope, id, props);
15
- tags.forEach(([key, value]) => {
16
- Tags.of(stack).add(key, value);
17
- });
18
- return stack;
19
- };
10
+ [COPY_STATE](next) {
11
+ next.#tags.push(...this.#tags);
20
12
  }
21
13
  build(scope, id) {
22
14
  const stack = new Stack(scope, id, this.props);
@@ -31,9 +23,9 @@ class StackBuilder {
31
23
  *
32
24
  * This is the entry point for declarative stack configuration. The returned
33
25
  * builder exposes every {@link StackProps} property as a fluent setter/getter,
34
- * plus {@link IStackBuilder.tag | .tag()} for adding tags and
35
- * {@link IStackBuilder.toScopeFactory | .toScopeFactory()} for integration
36
- * with stack strategies.
26
+ * plus {@link IStackBuilder.tag | .tag()} for adding tags. It implements
27
+ * {@link Lifecycle}, so it composes naturally and can be passed to
28
+ * {@link singleStack} or {@link groupedStacks}.
37
29
  *
38
30
  * @returns A fluent builder for a CloudFormation Stack.
39
31
  *
@@ -45,14 +37,14 @@ class StackBuilder {
45
37
  * .terminationProtection(true)
46
38
  * .build(app, "ServiceStack");
47
39
  *
48
- * // Use as a scope factory with strategies
49
- * const factory = createStackBuilder()
40
+ * // Hand a configured builder to a strategy. Use `.copy()` to snapshot
41
+ * // when the original may be mutated further.
42
+ * const base = createStackBuilder()
50
43
  * .terminationProtection(true)
51
- * .tag("team", "platform")
52
- * .toScopeFactory();
44
+ * .tag("team", "platform");
53
45
  *
54
46
  * compose({ ... }, { ... })
55
- * .withStackStrategy(singleStack(factory))
47
+ * .withStackStrategy(singleStack(base.copy()))
56
48
  * .build(app, "MySystem");
57
49
  * ```
58
50
  */
package/dist/stack-builder.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"stack-builder.js","sourceRoot":"","sources":["../src/stack-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAmB,IAAI,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAoD,MAAM,oBAAoB,CAAC;AA+D/F,MAAM,YAAY;IAChB,KAAK,GAAwB,EAAE,CAAC;IACvB,KAAK,GAAuB,EAAE,CAAC;IAExC,GAAG,CAAC,GAAW,EAAE,KAAa;QAC5B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,cAAc;QACZ,MAAM,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,OAAO,CAAC,KAAiB,EAAE,EAAU,EAAE,EAAE;YACvC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;gBAC5B,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACjC,CAAC,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YAClC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAA2B,YAAY,CAAC,CAAC;AACzD,CAAC"}
1
+ {"version":3,"file":"stack-builder.js","sourceRoot":"","sources":["../src/stack-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAmB,IAAI,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAiC,MAAM,oBAAoB,CAAC;AA4CxF,MAAM,YAAY;IAChB,KAAK,GAAwB,EAAE,CAAC;IACvB,KAAK,GAAuB,EAAE,CAAC;IAExC,GAAG,CAAC,GAAW,EAAE,KAAa;QAC5B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,CAAC,UAAU,CAAC,CAAC,IAAkB;QAC7B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YAClC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAA2B,YAAY,CAAC,CAAC;AACzD,CAAC"}
package/dist/strategies.d.ts CHANGED
@@ -1,12 +1,20 @@
1
- import { type ScopeFactory, type StackStrategy } from "@composurecdk/core";
1
+ import { type Lifecycle, type StackStrategy } from "@composurecdk/core";
2
+ import { type StackBuilderResult } from "./stack-builder.js";
2
3
  /**
3
4
  * Creates a strategy that places all components in a single Stack.
4
5
  *
5
- * The Stack is created lazily on the first call to `resolve` and reused for
6
- * all subsequent components.
6
+ * The Stack is created lazily on the first call to `resolve` and reused
7
+ * for all subsequent components. The supplied `builder` is invoked at that
8
+ * point as `builder.build(scope, id).stack`, so any tags applied via the
9
+ * builder's `.tag()` method land on the resulting Stack.
7
10
  *
8
- * @param factory - Optional factory for creating the Stack. Defaults to
9
- * a plain CDK `Stack` via {@link createStackBuilder}.
11
+ * The builder's `build()` is called lazily. If the original may be mutated
12
+ * after this call, pass `builder.copy()` to snapshot the configuration.
13
+ *
14
+ * @param builder - Optional builder for configuring the Stack. Defaults to
15
+ * a fresh {@link createStackBuilder} per call, producing a plain Stack
16
+ * with no extra configuration. For non-Stack scope types, use
17
+ * `singleStack` from `@composurecdk/core` directly with a `ScopeFactory`.
10
18
  * @returns A {@link StackStrategy} that groups all components into one Stack.
11
19
  *
12
20
  * @example
@@ -14,20 +22,33 @@ import { type ScopeFactory, type StackStrategy } from "@composurecdk/core";
14
22
  * compose({ handler, api }, { handler: [], api: ["handler"] })
15
23
  * .withStackStrategy(singleStack())
16
24
  * .build(app, "MySystem");
25
+ *
26
+ * // With a configured builder:
27
+ * const base = createStackBuilder().tag("team", "platform");
28
+ * compose({ ... }, { ... })
29
+ * .withStackStrategy(singleStack(base.copy()))
30
+ * .build(app, "MySystem");
17
31
  * ```
18
32
  */
19
- export declare function singleStack(factory?: ScopeFactory): StackStrategy;
33
+ export declare function singleStack(builder?: Lifecycle<StackBuilderResult>): StackStrategy;
20
34
  /**
21
35
  * Creates a strategy that groups components into named Stacks determined by
22
36
  * a classifier function.
23
37
  *
24
- * Components that return the same group key share a Stack. Stacks are created
25
- * lazily as new group keys are encountered.
38
+ * Components that return the same group key share a Stack. Stacks are
39
+ * created lazily as new group keys are encountered. The supplied `builder`
40
+ * is invoked once per group as `builder.build(scope, id).stack` with
41
+ * `id = ${systemId}-${group}`, so any configured tags propagate to every
42
+ * Stack the strategy creates.
43
+ *
44
+ * The builder's `build()` is called lazily. If the original may be mutated
45
+ * after this call, pass `builder.copy()` to snapshot the configuration.
26
46
  *
27
47
  * @param classify - A function that maps a component key to a group name.
28
- * @param factory - Optional factory for creating Stacks. Defaults to
29
- * a plain CDK `Stack` via {@link createStackBuilder}. The factory receives
30
- * `${systemId}-${group}` as the id.
48
+ * @param builder - Optional builder for configuring each Stack. Defaults to
49
+ * a fresh {@link createStackBuilder} per call. For non-Stack scope types,
50
+ * use `groupedStacks` from `@composurecdk/core` directly with a
51
+ * `ScopeFactory`.
31
52
  * @returns A {@link StackStrategy} that groups components by classifier output.
32
53
  *
33
54
  * @example
@@ -35,7 +56,15 @@ export declare function singleStack(factory?: ScopeFactory): StackStrategy;
35
56
  * compose({ handler, api, table }, { ... })
36
57
  * .withStackStrategy(groupedStacks(key => key === "table" ? "persistence" : "service"))
37
58
  * .build(app, "MySystem");
59
+ *
60
+ * // With a configured builder, snapshotted via .copy():
61
+ * const base = createStackBuilder().tag("team", "platform");
62
+ * compose({ ... }, { ... })
63
+ * .withStackStrategy(
64
+ * groupedStacks(key => key === "table" ? "persistence" : "service", base.copy()),
65
+ * )
66
+ * .build(app, "MySystem");
38
67
  * ```
39
68
  */
40
- export declare function groupedStacks(classify: (componentKey: string) => string, factory?: ScopeFactory): StackStrategy;
69
+ export declare function groupedStacks(classify: (componentKey: string) => string, builder?: Lifecycle<StackBuilderResult>): StackStrategy;
41
70
  //# sourceMappingURL=strategies.d.ts.map
package/dist/strategies.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../src/strategies.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,aAAa,EAGnB,MAAM,oBAAoB,CAAC;AAO5B;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,aAAa,CAEjE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,EAC1C,OAAO,CAAC,EAAE,YAAY,GACrB,aAAa,CAEf"}
1
+ {"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../src/strategies.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,kBAAkB,CAAC,GAAG,aAAa,CAGlF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,EAC1C,OAAO,CAAC,EAAE,SAAS,CAAC,kBAAkB,CAAC,GACtC,aAAa,CAGf"}
package/dist/strategies.js CHANGED
@@ -1,16 +1,20 @@
1
1
  import { singleStack as coreSingleStack, groupedStacks as coreGroupedStacks, } from "@composurecdk/core";
2
2
  import { createStackBuilder } from "./stack-builder.js";
3
- function defaultFactory() {
4
- return createStackBuilder().toScopeFactory();
5
- }
6
3
  /**
7
4
  * Creates a strategy that places all components in a single Stack.
8
5
  *
9
- * The Stack is created lazily on the first call to `resolve` and reused for
10
- * all subsequent components.
6
+ * The Stack is created lazily on the first call to `resolve` and reused
7
+ * for all subsequent components. The supplied `builder` is invoked at that
8
+ * point as `builder.build(scope, id).stack`, so any tags applied via the
9
+ * builder's `.tag()` method land on the resulting Stack.
10
+ *
11
+ * The builder's `build()` is called lazily. If the original may be mutated
12
+ * after this call, pass `builder.copy()` to snapshot the configuration.
11
13
  *
12
- * @param factory - Optional factory for creating the Stack. Defaults to
13
- * a plain CDK `Stack` via {@link createStackBuilder}.
14
+ * @param builder - Optional builder for configuring the Stack. Defaults to
15
+ * a fresh {@link createStackBuilder} per call, producing a plain Stack
16
+ * with no extra configuration. For non-Stack scope types, use
17
+ * `singleStack` from `@composurecdk/core` directly with a `ScopeFactory`.
14
18
  * @returns A {@link StackStrategy} that groups all components into one Stack.
15
19
  *
16
20
  * @example
@@ -18,22 +22,36 @@ function defaultFactory() {
18
22
  * compose({ handler, api }, { handler: [], api: ["handler"] })
19
23
  * .withStackStrategy(singleStack())
20
24
  * .build(app, "MySystem");
25
+ *
26
+ * // With a configured builder:
27
+ * const base = createStackBuilder().tag("team", "platform");
28
+ * compose({ ... }, { ... })
29
+ * .withStackStrategy(singleStack(base.copy()))
30
+ * .build(app, "MySystem");
21
31
  * ```
22
32
  */
23
- export function singleStack(factory) {
24
- return coreSingleStack(factory ?? defaultFactory());
33
+ export function singleStack(builder) {
34
+ const stackBuilder = builder ?? createStackBuilder();
35
+ return coreSingleStack((scope, id) => stackBuilder.build(scope, id).stack);
25
36
  }
26
37
  /**
27
38
  * Creates a strategy that groups components into named Stacks determined by
28
39
  * a classifier function.
29
40
  *
30
- * Components that return the same group key share a Stack. Stacks are created
31
- * lazily as new group keys are encountered.
41
+ * Components that return the same group key share a Stack. Stacks are
42
+ * created lazily as new group keys are encountered. The supplied `builder`
43
+ * is invoked once per group as `builder.build(scope, id).stack` with
44
+ * `id = ${systemId}-${group}`, so any configured tags propagate to every
45
+ * Stack the strategy creates.
46
+ *
47
+ * The builder's `build()` is called lazily. If the original may be mutated
48
+ * after this call, pass `builder.copy()` to snapshot the configuration.
32
49
  *
33
50
  * @param classify - A function that maps a component key to a group name.
34
- * @param factory - Optional factory for creating Stacks. Defaults to
35
- * a plain CDK `Stack` via {@link createStackBuilder}. The factory receives
36
- * `${systemId}-${group}` as the id.
51
+ * @param builder - Optional builder for configuring each Stack. Defaults to
52
+ * a fresh {@link createStackBuilder} per call. For non-Stack scope types,
53
+ * use `groupedStacks` from `@composurecdk/core` directly with a
54
+ * `ScopeFactory`.
37
55
  * @returns A {@link StackStrategy} that groups components by classifier output.
38
56
  *
39
57
  * @example
@@ -41,9 +59,18 @@ export function singleStack(factory) {
41
59
  * compose({ handler, api, table }, { ... })
42
60
  * .withStackStrategy(groupedStacks(key => key === "table" ? "persistence" : "service"))
43
61
  * .build(app, "MySystem");
62
+ *
63
+ * // With a configured builder, snapshotted via .copy():
64
+ * const base = createStackBuilder().tag("team", "platform");
65
+ * compose({ ... }, { ... })
66
+ * .withStackStrategy(
67
+ * groupedStacks(key => key === "table" ? "persistence" : "service", base.copy()),
68
+ * )
69
+ * .build(app, "MySystem");
44
70
  * ```
45
71
  */
46
- export function groupedStacks(classify, factory) {
47
- return coreGroupedStacks(classify, factory ?? defaultFactory());
72
+ export function groupedStacks(classify, builder) {
73
+ const stackBuilder = builder ?? createStackBuilder();
74
+ return coreGroupedStacks(classify, (scope, id) => stackBuilder.build(scope, id).stack);
48
75
  }
49
76
  //# sourceMappingURL=strategies.js.map
package/dist/strategies.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"strategies.js","sourceRoot":"","sources":["../src/strategies.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,WAAW,IAAI,eAAe,EAC9B,aAAa,IAAI,iBAAiB,GACnC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,SAAS,cAAc;IACrB,OAAO,kBAAkB,EAAE,CAAC,cAAc,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAAC,OAAsB;IAChD,OAAO,eAAe,CAAC,OAAO,IAAI,cAAc,EAAE,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAC3B,QAA0C,EAC1C,OAAsB;IAEtB,OAAO,iBAAiB,CAAC,QAAQ,EAAE,OAAO,IAAI,cAAc,EAAE,CAAC,CAAC;AAClE,CAAC"}
1
+ {"version":3,"file":"strategies.js","sourceRoot":"","sources":["../src/strategies.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,WAAW,IAAI,eAAe,EAC9B,aAAa,IAAI,iBAAiB,GACnC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAA2B,MAAM,oBAAoB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,WAAW,CAAC,OAAuC;IACjE,MAAM,YAAY,GAAG,OAAO,IAAI,kBAAkB,EAAE,CAAC;IACrD,OAAO,eAAe,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,aAAa,CAC3B,QAA0C,EAC1C,OAAuC;IAEvC,MAAM,YAAY,GAAG,OAAO,IAAI,kBAAkB,EAAE,CAAC;IACrD,OAAO,iBAAiB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AACzF,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@composurecdk/cloudformation",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "Composable CloudFormation stack builder and stack assignment strategies",
5
5
  "repository": {
6
6
  "type": "git",
@@ -35,7 +35,7 @@
35
35
  },
36
36
  "type": "module",
37
37
  "peerDependencies": {
38
- "@composurecdk/core": "^0.5.0",
38
+ "@composurecdk/core": "^0.6.0",
39
39
  "aws-cdk-lib": "^2.0.0",
40
40
  "constructs": "^10.0.0"
41
41
  },