@composurecdk/cloudformation 0.1.2 → 0.3.0

package/README.md

@@ -0,0 +1,107 @@
+# @composurecdk/cloudformation
+
+CloudFormation builders for [ComposureCDK](../../README.md).
+
+This package provides a fluent builder for CloudFormation Stacks, convenience stack strategies, and a post-build hook for creating CloudFormation outputs from composed systems.
+
+## Stack Builder
+
+```ts
+import { createStackBuilder } from "@composurecdk/cloudformation";
+
+const { stack } = createStackBuilder()
+  .description("Network infrastructure")
+  .terminationProtection(true)
+  .build(app, "NetworkStack");
+```
+
+Every [StackProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.StackProps.html) property is available as a fluent setter on the builder.
+
+### Tags
+
+Add tags that propagate to all resources within the stack:
+
+```ts
+const { stack } = createStackBuilder()
+  .tag("team", "platform")
+  .tag("environment", "production")
+  .build(app, "ServiceStack");
+```
+
+### Scope factory
+
+Convert a configured builder into a `ScopeFactory` for use with stack strategies:
+
+```ts
+const factory = createStackBuilder()
+  .terminationProtection(true)
+  .tag("team", "platform")
+  .toScopeFactory();
+
+compose({ ... }, { ... })
+  .withStackStrategy(singleStack(factory))
+  .build(app, "MySystem");
+```
+
+## Stack Strategies
+
+Convenience wrappers around `@composurecdk/core`'s strategy primitives that default to creating Stacks via `createStackBuilder`. Pass an optional `ScopeFactory` to customise the Stack configuration.
+
+### singleStack
+
+Places all components in a single auto-created Stack:
+
+```ts
+import { singleStack } from "@composurecdk/cloudformation";
+
+compose({ handler, api }, { handler: [], api: ["handler"] })
+  .withStackStrategy(singleStack())
+  .build(app, "MySystem");
+```
+
+### groupedStacks
+
+Groups components into named Stacks by a classifier function:
+
+```ts
+import { groupedStacks } from "@composurecdk/cloudformation";
+
+compose({ handler, api, table }, { ... })
+  .withStackStrategy(
+    groupedStacks((key) => (key === "table" ? "persistence" : "service")),
+  )
+  .build(app, "MySystem");
+```
+
+## outputs
+
+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.
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import { outputs } from "@composurecdk/cloudformation";
+
+compose(
+  { site: createBucketBuilder(), cdn: createDistributionBuilder() },
+  { site: [], cdn: ["site"] },
+)
+  .afterBuild(
+    outputs({
+      DistributionUrl: {
+        value: ref("cdn", (r) => `https://${r.distribution.distributionDomainName}`),
+        description: "CloudFront distribution URL",
+      },
+      BucketName: {
+        value: ref("site", (r) => r.bucket.bucketName),
+        description: "S3 bucket name for site content",
+      },
+    }),
+  )
+  .build(stack, "StaticWebsite");
+```
+
+## Examples
+
+- [MultiStackApp](../examples/src/multi-stack-app.ts) — REST API + Lambda split across stacks via `.withStacks()`
+- [StrategyStackApp](../examples/src/strategy-stack-app.ts) — REST API + Lambda split across stacks via `.withStackStrategy()`
+- [StaticWebsiteStack](../examples/src/static-website/app.ts) — CloudFormation outputs with `afterBuild` and `outputs`

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { createStackBuilder, type IStackBuilder, type StackBuilderResult, } from "./stack-builder.js";
 export { singleStack, groupedStacks } from "./strategies.js";
+export { outputs, type OutputDefinition, type OutputDefinitions } from "./outputs.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { createStackBuilder, } from "./stack-builder.js";
 export { singleStack, groupedStacks } from "./strategies.js";
+export { outputs } from "./outputs.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAiD,MAAM,cAAc,CAAC"}

package/dist/outputs.d.ts

@@ -0,0 +1,60 @@
+import { type AfterBuildHook, type Resolvable } from "@composurecdk/core";
+/**
+ * Defines a CloudFormation stack output with a value that can be a
+ * {@link Resolvable} — either a concrete string or a {@link Ref} that
+ * resolves against the system's build results at build time.
+ */
+export interface OutputDefinition {
+    /** The output value, or a Ref that resolves to one. */
+    value: Resolvable<string>;
+    /** A description of the output. */
+    description?: string;
+    /**
+     * The name under which the output is exported for cross-stack references.
+     * When set, this creates a CloudFormation Export.
+     */
+    exportName?: string;
+}
+/**
+ * A record of output definitions keyed by logical output name.
+ */
+export type OutputDefinitions = Record<string, OutputDefinition>;
+/**
+ * Returns an {@link AfterBuildHook} that creates CloudFormation stack outputs
+ * from the composed system's build results.
+ *
+ * Each output definition's `value` can be a concrete string or a {@link Ref}
+ * that is resolved against the build results. This enables outputs that
+ * reference values produced by composed components without breaking the
+ * composition abstraction.
+ *
+ * Intended for use with {@link ComposedSystem.afterBuild}.
+ *
+ * @param defs - A record of output definitions keyed by logical name.
+ * @returns An {@link AfterBuildHook} that creates `CfnOutput` constructs.
+ *
+ * @example
+ * ```ts
+ * import { compose, ref } from "@composurecdk/core";
+ * import { outputs } from "@composurecdk/cloudformation";
+ *
+ * compose(
+ *   { site: createBucketBuilder(), cdn: createDistributionBuilder() },
+ *   { site: [], cdn: ["site"] },
+ * )
+ *   .afterBuild(outputs({
+ *     DistributionUrl: {
+ *       value: ref("cdn", (r: DistributionBuilderResult) =>
+ *         `https://${r.distribution.distributionDomainName}`),
+ *       description: "CloudFront distribution URL",
+ *     },
+ *     BucketName: {
+ *       value: ref("site", (r: BucketBuilderResult) => r.bucket.bucketName),
+ *       description: "S3 bucket name for site content",
+ *     },
+ *   }))
+ *   .build(stack, "StaticWebsite");
+ * ```
+ */
+export declare function outputs(defs: OutputDefinitions): AfterBuildHook<object>;
+//# sourceMappingURL=outputs.d.ts.map

package/dist/outputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputs.d.ts","sourceRoot":"","sources":["../src/outputs.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAW,MAAM,oBAAoB,CAAC;AAEnF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE1B,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAAC,MAAM,CAAC,CAYvE"}

package/dist/outputs.js

@@ -0,0 +1,52 @@
+import { CfnOutput } from "aws-cdk-lib";
+import { resolve } from "@composurecdk/core";
+/**
+ * Returns an {@link AfterBuildHook} that creates CloudFormation stack outputs
+ * from the composed system's build results.
+ *
+ * Each output definition's `value` can be a concrete string or a {@link Ref}
+ * that is resolved against the build results. This enables outputs that
+ * reference values produced by composed components without breaking the
+ * composition abstraction.
+ *
+ * Intended for use with {@link ComposedSystem.afterBuild}.
+ *
+ * @param defs - A record of output definitions keyed by logical name.
+ * @returns An {@link AfterBuildHook} that creates `CfnOutput` constructs.
+ *
+ * @example
+ * ```ts
+ * import { compose, ref } from "@composurecdk/core";
+ * import { outputs } from "@composurecdk/cloudformation";
+ *
+ * compose(
+ *   { site: createBucketBuilder(), cdn: createDistributionBuilder() },
+ *   { site: [], cdn: ["site"] },
+ * )
+ *   .afterBuild(outputs({
+ *     DistributionUrl: {
+ *       value: ref("cdn", (r: DistributionBuilderResult) =>
+ *         `https://${r.distribution.distributionDomainName}`),
+ *       description: "CloudFront distribution URL",
+ *     },
+ *     BucketName: {
+ *       value: ref("site", (r: BucketBuilderResult) => r.bucket.bucketName),
+ *       description: "S3 bucket name for site content",
+ *     },
+ *   }))
+ *   .build(stack, "StaticWebsite");
+ * ```
+ */
+export function outputs(defs) {
+    return (scope, _id, results) => {
+        const resultAsContext = results;
+        for (const [name, def] of Object.entries(defs)) {
+            new CfnOutput(scope, name, {
+                value: resolve(def.value, resultAsContext),
+                ...(def.description !== undefined ? { description: def.description } : {}),
+                ...(def.exportName !== undefined ? { exportName: def.exportName } : {}),
+            });
+        }
+    };
+}
+//# sourceMappingURL=outputs.js.map

package/dist/outputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputs.js","sourceRoot":"","sources":["../src/outputs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAwC,OAAO,EAAE,MAAM,oBAAoB,CAAC;AA0BnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,OAAO,CAAC,IAAuB;IAC7C,OAAO,CAAC,KAAiB,EAAE,GAAW,EAAE,OAAe,EAAE,EAAE;QACzD,MAAM,eAAe,GAAG,OAAiC,CAAC;QAE1D,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/C,IAAI,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE;gBACzB,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,eAAe,CAAC;gBAC1C,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1E,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACxE,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/cloudformation",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Composable CloudFormation stack builder and stack assignment strategies",
   "repository": {
     "type": "git",
@@ -35,7 +35,7 @@
   },
   "type": "module",
   "peerDependencies": {
-    "@composurecdk/core": "^0.1.0",
+    "@composurecdk/core": "^0.3.0",
     "aws-cdk-lib": "^2.0.0",
     "constructs": "^10.0.0"
   },