@composurecdk/lambda 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @composurecdk/lambda
+
+Lambda builders for [ComposureCDK](../../README.md).
+
+This package provides a fluent builder for AWS Lambda functions with secure, AWS-recommended defaults. It wraps the CDK [Function](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html) construct — refer to the CDK documentation for the full set of configurable properties.
+
+## Function Builder
+
+```ts
+import { createFunctionBuilder } from "@composurecdk/lambda";
+
+const handler = createFunctionBuilder()
+  .runtime(Runtime.NODEJS_22_X)
+  .handler("index.handler")
+  .code(Code.fromAsset("lambda"))
+  .build(stack, "MyFunction");
+```
+
+Every [FunctionProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.FunctionProps.html) property is available as a fluent setter on the builder.
+
+## Secure Defaults
+
+`createFunctionBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property        | Default  | Rationale                                                                            |
+| --------------- | -------- | ------------------------------------------------------------------------------------ |
+| `tracing`       | `ACTIVE` | Enables X-Ray distributed tracing for observability.                                 |
+| `loggingFormat` | `JSON`   | Structured logs for CloudWatch Logs Insights auto-discovery and consistent querying. |
+
+These defaults are guided by the [AWS Well-Architected Serverless Applications Lens](https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/opex-distributed-tracing.html).
+
+The defaults are exported as `FUNCTION_DEFAULTS` for visibility and testing:
+
+```ts
+import { FUNCTION_DEFAULTS } from "@composurecdk/lambda";
+```
+
+### Overriding defaults
+
+```ts
+import { LoggingFormat, Tracing } from "aws-cdk-lib/aws-lambda";
+
+const handler = createFunctionBuilder()
+  .runtime(Runtime.NODEJS_22_X)
+  .handler("index.handler")
+  .code(Code.fromAsset("lambda"))
+  .tracing(Tracing.PASS_THROUGH)
+  .loggingFormat(LoggingFormat.TEXT)
+  .build(stack, "MyFunction");
+```
+
+## Examples
+
+- [LambdaApiStack](../examples/src/lambda-api-app.ts) — REST API backed by a Lambda function, wired with `ref`
+- [DualFunctionStack](../examples/src/dual-function-app.ts) — Two Lambda functions with different configurations
+- [MultiStackApp](../examples/src/multi-stack-app.ts) — Lambda split across stacks via `.withStacks()`
+- [StrategyStackApp](../examples/src/strategy-stack-app.ts) — Lambda split across stacks via `.withStackStrategy()`

package/dist/defaults.d.ts

@@ -0,0 +1,8 @@
+import { type FunctionProps } from "aws-cdk-lib/aws-lambda";
+/**
+ * Secure, AWS-recommended defaults applied to every Lambda function built
+ * with {@link createFunctionBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+export declare const FUNCTION_DEFAULTS: Partial<FunctionProps>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,CAAC,aAAa,CAapD,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,20 @@
+import { LoggingFormat, Tracing } from "aws-cdk-lib/aws-lambda";
+/**
+ * Secure, AWS-recommended defaults applied to every Lambda function built
+ * with {@link createFunctionBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+export const FUNCTION_DEFAULTS = {
+    /**
+     * Enable AWS X-Ray active tracing for distributed request tracking.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/opex-distributed-tracing.html
+     */
+    tracing: Tracing.ACTIVE,
+    /**
+     * Emit logs as structured JSON for CloudWatch Logs Insights auto-discovery
+     * and consistent querying across services.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/opex-logging.html
+     */
+    loggingFormat: LoggingFormat.JSON,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAsB,MAAM,wBAAwB,CAAC;AAEpF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA2B;IACvD;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC,MAAM;IAEvB;;;;OAIG;IACH,aAAa,EAAE,aAAa,CAAC,IAAI;CAClC,CAAC"}

package/dist/function-builder.d.ts

@@ -0,0 +1,69 @@
+import { Function as LambdaFunction, type FunctionProps } from "aws-cdk-lib/aws-lambda";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle } from "@composurecdk/core";
+type FunctionBuilderProps = FunctionProps;
+/**
+ * The build output of a {@link IFunctionBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface FunctionBuilderResult {
+    /** The Lambda function construct created by the builder. */
+    function: LambdaFunction;
+}
+/**
+ * A fluent builder for configuring and creating an AWS Lambda function.
+ *
+ * Each configuration property from the CDK {@link FunctionProps} 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 Lambda function with the configured properties and returns a
+ * {@link FunctionBuilderResult}.
+ *
+ * @example
+ * ```ts
+ * const handler = createFunctionBuilder()
+ *   .runtime(Runtime.NODEJS_22_X)
+ *   .handler("index.handler")
+ *   .code(Code.fromAsset("lambda"))
+ *   .memorySize(256)
+ *   .timeout(Duration.seconds(30));
+ * ```
+ */
+export type IFunctionBuilder = IBuilder<FunctionBuilderProps, FunctionBuilder>;
+declare class FunctionBuilder implements Lifecycle<FunctionBuilderResult> {
+    props: Partial<FunctionBuilderProps>;
+    build(scope: IConstruct, id: string): FunctionBuilderResult;
+}
+/**
+ * Creates a new {@link IFunctionBuilder} for configuring an AWS Lambda function.
+ *
+ * This is the entry point for defining a Lambda function component. The returned
+ * builder exposes every {@link FunctionProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS Lambda function.
+ *
+ * @example
+ * ```ts
+ * const handler = createFunctionBuilder()
+ *   .runtime(Runtime.NODEJS_22_X)
+ *   .handler("index.handler")
+ *   .code(Code.fromAsset("lambda"))
+ *   .timeout(Duration.seconds(30));
+ *
+ * // Use standalone:
+ * const result = handler.build(stack, "MyFunction");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { handler, table: createTableBuilder() },
+ *   { handler: ["table"], table: [] },
+ * );
+ * ```
+ */
+export declare function createFunctionBuilder(): IFunctionBuilder;
+export {};
+//# sourceMappingURL=function-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"function-builder.d.ts","sourceRoot":"","sources":["../src/function-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG5E,KAAK,oBAAoB,GAAG,aAAa,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAC;AAE/E,cAAM,eAAgB,YAAW,SAAS,CAAC,qBAAqB,CAAC;IAC/D,KAAK,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAM;IAE1C,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,qBAAqB;CAS5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD"}

package/dist/function-builder.js

@@ -0,0 +1,46 @@
+import { Function as LambdaFunction } from "aws-cdk-lib/aws-lambda";
+import { Builder } from "@composurecdk/core";
+import { FUNCTION_DEFAULTS } from "./defaults.js";
+class FunctionBuilder {
+    props = {};
+    build(scope, id) {
+        const mergedProps = {
+            ...FUNCTION_DEFAULTS,
+            ...this.props,
+        };
+        return {
+            function: new LambdaFunction(scope, id, mergedProps),
+        };
+    }
+}
+/**
+ * Creates a new {@link IFunctionBuilder} for configuring an AWS Lambda function.
+ *
+ * This is the entry point for defining a Lambda function component. The returned
+ * builder exposes every {@link FunctionProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS Lambda function.
+ *
+ * @example
+ * ```ts
+ * const handler = createFunctionBuilder()
+ *   .runtime(Runtime.NODEJS_22_X)
+ *   .handler("index.handler")
+ *   .code(Code.fromAsset("lambda"))
+ *   .timeout(Duration.seconds(30));
+ *
+ * // Use standalone:
+ * const result = handler.build(stack, "MyFunction");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { handler, table: createTableBuilder() },
+ *   { handler: ["table"], table: [] },
+ * );
+ * ```
+ */
+export function createFunctionBuilder() {
+    return Builder(FunctionBuilder);
+}
+//# sourceMappingURL=function-builder.js.map

package/dist/function-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-builder.js","sourceRoot":"","sources":["../src/function-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAsB,MAAM,wBAAwB,CAAC;AAExF,OAAO,EAAE,OAAO,EAAiC,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAqClD,MAAM,eAAe;IACnB,KAAK,GAAkC,EAAE,CAAC;IAE1C,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,WAAW,GAAG;YAClB,GAAG,iBAAiB;YACpB,GAAG,IAAI,CAAC,KAAK;SACU,CAAC;QAC1B,OAAO;YACL,QAAQ,EAAE,IAAI,cAAc,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;SACrD,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,OAAO,CAAwC,eAAe,CAAC,CAAC;AACzE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createFunctionBuilder, type FunctionBuilderResult, type IFunctionBuilder, } from "./function-builder.js";
+export { FUNCTION_DEFAULTS } from "./defaults.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,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createFunctionBuilder, } from "./function-builder.js";
+export { FUNCTION_DEFAULTS } from "./defaults.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,qBAAqB,GAGtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@composurecdk/lambda",
+  "version": "0.1.0",
+  "description": "Composable Lambda function builder with well-architected defaults",
+  "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"
+  }
+}