@composurecdk/cloudformation 0.1.0

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

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

package/dist/index.js.map

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

package/dist/stack-builder.d.ts

@@ -0,0 +1,101 @@
+import { Stack, type StackProps } from "aws-cdk-lib";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle, type ScopeFactory } from "@composurecdk/core";
+/**
+ * The build output of a {@link IStackBuilder}. Contains the CDK Stack
+ * created during {@link Lifecycle.build}.
+ */
+export interface StackBuilderResult {
+    /** The CDK Stack created by the builder. */
+    stack: Stack;
+}
+/**
+ * A fluent builder for configuring and creating a CloudFormation Stack.
+ *
+ * Each configuration property from the CDK {@link StackProps} is exposed
+ * as an overloaded method: call with a value to set it (returns the builder
+ * for chaining), or call with no arguments to read the current value.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * a Stack with the configured properties and returns a
+ * {@link StackBuilderResult}.
+ *
+ * @example
+ * ```ts
+ * const stack = createStackBuilder()
+ *   .description("Network infrastructure")
+ *   .terminationProtection(true)
+ *   .build(app, "NetworkStack");
+ * ```
+ */
+export type IStackBuilder = IBuilder<StackProps, StackBuilder> & {
+    /**
+     * Adds a tag to the Stack. Tags are applied to the Stack and propagate
+     * to all resources within it.
+     *
+     * @param key - The tag key.
+     * @param value - The tag value.
+     * @returns The builder for chaining.
+     */
+    tag(key: string, value: string): IStackBuilder;
+    /**
+     * Returns a {@link ScopeFactory} that creates Stacks with the builder's
+     * configured properties. Use this to integrate with
+     * {@link singleStack} or {@link groupedStacks} strategies.
+     *
+     * @returns A factory function compatible with stack strategies.
+     *
+     * @example
+     * ```ts
+     * const factory = createStackBuilder()
+     *   .terminationProtection(true)
+     *   .toScopeFactory();
+     *
+     * compose({ ... }, { ... })
+     *   .withStackStrategy(singleStack(factory))
+     *   .build(app, "MySystem");
+     * ```
+     */
+    toScopeFactory(): ScopeFactory;
+};
+declare class StackBuilder implements Lifecycle<StackBuilderResult> {
+    props: Partial<StackProps>;
+    private readonly tags;
+    tag(key: string, value: string): this;
+    toScopeFactory(): ScopeFactory;
+    build(scope: IConstruct, id: string): StackBuilderResult;
+}
+/**
+ * Creates a new {@link IStackBuilder} for configuring a CloudFormation Stack.
+ *
+ * This is the entry point for declarative stack configuration. The returned
+ * builder exposes every {@link StackProps} property as a fluent setter/getter,
+ * plus {@link IStackBuilder.tag | .tag()} for adding tags and
+ * {@link IStackBuilder.toScopeFactory | .toScopeFactory()} for integration
+ * with stack strategies.
+ *
+ * @returns A fluent builder for a CloudFormation Stack.
+ *
+ * @example
+ * ```ts
+ * // Build a stack directly
+ * const { stack } = createStackBuilder()
+ *   .description("Service layer")
+ *   .terminationProtection(true)
+ *   .build(app, "ServiceStack");
+ *
+ * // Use as a scope factory with strategies
+ * const factory = createStackBuilder()
+ *   .terminationProtection(true)
+ *   .tag("team", "platform")
+ *   .toScopeFactory();
+ *
+ * compose({ ... }, { ... })
+ *   .withStackStrategy(singleStack(factory))
+ *   .build(app, "MySystem");
+ * ```
+ */
+export declare function createStackBuilder(): IStackBuilder;
+export {};
+//# sourceMappingURL=stack-builder.d.ts.map

package/dist/stack-builder.d.ts.map

@@ -0,0 +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;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAE/C,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"}

package/dist/stack-builder.js

@@ -0,0 +1,62 @@
+import { Stack, Tags } from "aws-cdk-lib";
+import { Builder } from "@composurecdk/core";
+class StackBuilder {
+    props = {};
+    tags = [];
+    tag(key, value) {
+        this.tags.push([key, value]);
+        return this;
+    }
+    toScopeFactory() {
+        const props = { ...this.props };
+        const tags = [...this.tags];
+        return (scope, id) => {
+            const stack = new Stack(scope, id, props);
+            tags.forEach(([key, value]) => {
+                Tags.of(stack).add(key, value);
+            });
+            return stack;
+        };
+    }
+    build(scope, id) {
+        const stack = new Stack(scope, id, this.props);
+        this.tags.forEach(([key, value]) => {
+            Tags.of(stack).add(key, value);
+        });
+        return { stack };
+    }
+}
+/**
+ * Creates a new {@link IStackBuilder} for configuring a CloudFormation Stack.
+ *
+ * This is the entry point for declarative stack configuration. The returned
+ * builder exposes every {@link StackProps} property as a fluent setter/getter,
+ * plus {@link IStackBuilder.tag | .tag()} for adding tags and
+ * {@link IStackBuilder.toScopeFactory | .toScopeFactory()} for integration
+ * with stack strategies.
+ *
+ * @returns A fluent builder for a CloudFormation Stack.
+ *
+ * @example
+ * ```ts
+ * // Build a stack directly
+ * const { stack } = createStackBuilder()
+ *   .description("Service layer")
+ *   .terminationProtection(true)
+ *   .build(app, "ServiceStack");
+ *
+ * // Use as a scope factory with strategies
+ * const factory = createStackBuilder()
+ *   .terminationProtection(true)
+ *   .tag("team", "platform")
+ *   .toScopeFactory();
+ *
+ * compose({ ... }, { ... })
+ *   .withStackStrategy(singleStack(factory))
+ *   .build(app, "MySystem");
+ * ```
+ */
+export function createStackBuilder() {
+    return Builder(StackBuilder);
+}
+//# sourceMappingURL=stack-builder.js.map

package/dist/stack-builder.js.map

@@ -0,0 +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;IACf,IAAI,GAAuB,EAAE,CAAC;IAE/C,GAAG,CAAC,GAAW,EAAE,KAAa;QAC5B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7B,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,IAAI,CAAC,CAAC;QAC5B,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,KAAmB,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YACjC,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,CAAkB,CAAC;AAC1E,CAAC"}

package/dist/strategies.d.ts

@@ -0,0 +1,41 @@
+import { type ScopeFactory, type StackStrategy } from "@composurecdk/core";
+/**
+ * Creates a strategy that places all components in a single Stack.
+ *
+ * The Stack is created lazily on the first call to `resolve` and reused for
+ * all subsequent components.
+ *
+ * @param factory - Optional factory for creating the Stack. Defaults to
+ *   a plain CDK `Stack` via {@link createStackBuilder}.
+ * @returns A {@link StackStrategy} that groups all components into one Stack.
+ *
+ * @example
+ * ```ts
+ * compose({ handler, api }, { handler: [], api: ["handler"] })
+ *   .withStackStrategy(singleStack())
+ *   .build(app, "MySystem");
+ * ```
+ */
+export declare function singleStack(factory?: ScopeFactory): StackStrategy;
+/**
+ * Creates a strategy that groups components into named Stacks determined by
+ * a classifier function.
+ *
+ * Components that return the same group key share a Stack. Stacks are created
+ * lazily as new group keys are encountered.
+ *
+ * @param classify - A function that maps a component key to a group name.
+ * @param factory - Optional factory for creating Stacks. Defaults to
+ *   a plain CDK `Stack` via {@link createStackBuilder}. The factory receives
+ *   `${systemId}-${group}` as the id.
+ * @returns A {@link StackStrategy} that groups components by classifier output.
+ *
+ * @example
+ * ```ts
+ * compose({ handler, api, table }, { ... })
+ *   .withStackStrategy(groupedStacks(key => key === "table" ? "persistence" : "service"))
+ *   .build(app, "MySystem");
+ * ```
+ */
+export declare function groupedStacks(classify: (componentKey: string) => string, factory?: ScopeFactory): StackStrategy;
+//# sourceMappingURL=strategies.d.ts.map

package/dist/strategies.d.ts.map

@@ -0,0 +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"}

package/dist/strategies.js

@@ -0,0 +1,49 @@
+import { singleStack as coreSingleStack, groupedStacks as coreGroupedStacks, } from "@composurecdk/core";
+import { createStackBuilder } from "./stack-builder.js";
+function defaultFactory() {
+    return createStackBuilder().toScopeFactory();
+}
+/**
+ * Creates a strategy that places all components in a single Stack.
+ *
+ * The Stack is created lazily on the first call to `resolve` and reused for
+ * all subsequent components.
+ *
+ * @param factory - Optional factory for creating the Stack. Defaults to
+ *   a plain CDK `Stack` via {@link createStackBuilder}.
+ * @returns A {@link StackStrategy} that groups all components into one Stack.
+ *
+ * @example
+ * ```ts
+ * compose({ handler, api }, { handler: [], api: ["handler"] })
+ *   .withStackStrategy(singleStack())
+ *   .build(app, "MySystem");
+ * ```
+ */
+export function singleStack(factory) {
+    return coreSingleStack(factory ?? defaultFactory());
+}
+/**
+ * Creates a strategy that groups components into named Stacks determined by
+ * a classifier function.
+ *
+ * Components that return the same group key share a Stack. Stacks are created
+ * lazily as new group keys are encountered.
+ *
+ * @param classify - A function that maps a component key to a group name.
+ * @param factory - Optional factory for creating Stacks. Defaults to
+ *   a plain CDK `Stack` via {@link createStackBuilder}. The factory receives
+ *   `${systemId}-${group}` as the id.
+ * @returns A {@link StackStrategy} that groups components by classifier output.
+ *
+ * @example
+ * ```ts
+ * compose({ handler, api, table }, { ... })
+ *   .withStackStrategy(groupedStacks(key => key === "table" ? "persistence" : "service"))
+ *   .build(app, "MySystem");
+ * ```
+ */
+export function groupedStacks(classify, factory) {
+    return coreGroupedStacks(classify, factory ?? defaultFactory());
+}
+//# sourceMappingURL=strategies.js.map

package/dist/strategies.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@composurecdk/cloudformation",
+  "version": "0.1.0",
+  "description": "Composable CloudFormation stack builder and stack assignment strategies",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "keywords": [],
+  "author": "Jason Duffett (https://github.com/laazyj)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@composurecdk/core": "^0.1.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "aws-cdk-lib": "^2.245.0",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}