@composurecdk/lambda 0.7.0 → 0.8.0

package/dist/esm/event-sources/sqs-event-source.js

@@ -0,0 +1,76 @@
+import { MetricType } from "aws-cdk-lib/aws-lambda";
+import { SqsEventSource } from "aws-cdk-lib/aws-lambda-event-sources";
+import { isRef } from "@composurecdk/core";
+import { composureEventSource } from "./composure-event-source.js";
+/**
+ * Secure, AWS-recommended defaults applied to every SQS event source built
+ * with {@link sqsEventSource}. Each property can be overridden via the
+ * factory's `props` argument.
+ */
+export const DEFAULT_SQS_EVENT_SOURCE_PROPS = {
+    /**
+     * Report partial batch failures so a single poison message does not fail
+     * the whole batch and force redelivery of already-processed records. CDK
+     * defaults this to `false`.
+     * @see https://aws.amazon.com/blogs/compute/implementing-aws-well-architected-best-practices-for-amazon-sqs-part-3/
+     * @see https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html#services-sqs-batchfailurereporting
+     */
+    reportBatchItemFailures: true,
+    /**
+     * Enable the per-mapping `EventCount` ESM metrics (`FailedInvokeEventCount`,
+     * `DroppedEventCount`, …). They emit only when opted in, and the
+     * event-source contextual alarms on {@link IFunctionBuilder} depend on them.
+     * @see https://aws.amazon.com/blogs/compute/introducing-new-event-source-mapping-esm-metrics-for-aws-lambda/
+     */
+    metricsConfig: { metrics: [MetricType.EVENT_COUNT] },
+};
+/**
+ * Wraps an SQS queue as a Lambda {@link IEventSource}, deferring resolution
+ * when the queue is a `ref()` to a sibling component's output.
+ *
+ * Follows the `events/targets` factory shape: register the result with
+ * {@link IFunctionBuilder.addEventSource} and the builder resolves the
+ * `ref()`, attaches the source, and (because `addEventSource` calls
+ * `source.bind(fn)`) grants the function's least-privilege execution role
+ * permission to consume the queue.
+ *
+ * Applies {@link DEFAULT_SQS_EVENT_SOURCE_PROPS}; pass `props` to override.
+ *
+ * ## Cross-component invariants (not enforced)
+ *
+ * AWS Well-Architected guidance spans the queue and the function:
+ * - the source queue's visibility timeout should be ≥ 6× the function
+ *   timeout, leaving room for Lambda to retry a throttled batch;
+ * - the source queue's redrive `maxReceiveCount` should be ≥ 5 before the DLQ.
+ *
+ * These are not validated here — the queue often arrives as a `ref()` that is
+ * not resolvable at configuration time. Tracked in laazyj/composureCDK#123
+ * and #124.
+ *
+ * @param queue - The source queue, concrete or a `ref()` to a sibling.
+ * @param props - Overrides for {@link DEFAULT_SQS_EVENT_SOURCE_PROPS} and any
+ *   other {@link SqsEventSourceProps}.
+ *
+ * @example
+ * ```ts
+ * compose(
+ *   {
+ *     orders: createQueueBuilder().queueName("orders"),
+ *     processor: createFunctionBuilder()
+ *       .runtime(Runtime.NODEJS_22_X)
+ *       .handler("index.handler")
+ *       .code(Code.fromAsset("lambda"))
+ *       .addEventSource("orders", sqsEventSource(ref("orders", (r) => r.queue))),
+ *   },
+ *   { orders: [], processor: ["orders"] },
+ * );
+ * ```
+ */
+export function sqsEventSource(queue, props) {
+    const merged = { ...DEFAULT_SQS_EVENT_SOURCE_PROPS, ...props };
+    const source = isRef(queue)
+        ? queue.map((resolved) => new SqsEventSource(resolved, merged))
+        : new SqsEventSource(queue, merged);
+    return composureEventSource("sqs", source);
+}
+//# sourceMappingURL=sqs-event-source.js.map

package/dist/esm/event-sources/sqs-event-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/sqs-event-source.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,cAAc,EAA4B,MAAM,sCAAsC,CAAC;AAEhG,OAAO,EAAE,KAAK,EAAmB,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAA6B,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAE9F;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAGvC;IACF;;;;;;OAMG;IACH,uBAAuB,EAAE,IAAI;IAE7B;;;;;OAKG;IACH,aAAa,EAAE,EAAE,OAAO,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAyB,EACzB,KAA2B;IAE3B,MAAM,MAAM,GAAwB,EAAE,GAAG,8BAA8B,EAAE,GAAG,KAAK,EAAE,CAAC;IACpF,MAAM,MAAM,GAA6B,KAAK,CAAC,KAAK,CAAC;QACnD,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC/D,CAAC,CAAC,IAAI,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtC,OAAO,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/esm/function-alarms.d.ts

@@ -0,0 +1,31 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { Function as LambdaFunction, FunctionProps } from "aws-cdk-lib/aws-lambda";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { FunctionAlarmConfig } from "./alarm-config.js";
+import type { AttachedEventSource } from "./event-sources/composure-event-source.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s, applying contextual logic for timeout-based
+ * duration and reserved-concurrency-based concurrent execution alarms.
+ */
+export declare function resolveFunctionAlarmDefinitions(fn: LambdaFunction, config: FunctionAlarmConfig | undefined, props: Pick<FunctionProps, "timeout" | "reservedConcurrentExecutions">, eventSources?: AttachedEventSource[]): AlarmDefinition[];
+/**
+ * Creates AWS-recommended CloudWatch alarms for a Lambda function,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param fn - The Lambda function to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param props - The merged function props, used for contextual alarm thresholds.
+ * @param eventSources - Event sources attached to the function, used for
+ *   per-event-source contextual alarms.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
+ */
+export declare function createFunctionAlarms(scope: IConstruct, id: string, fn: LambdaFunction, config: FunctionAlarmConfig | false | undefined, props: Pick<FunctionProps, "timeout" | "reservedConcurrentExecutions">, eventSources?: AttachedEventSource[], customAlarms?: AlarmDefinitionBuilder<LambdaFunction>[]): Record<string, Alarm>;
+//# sourceMappingURL=function-alarms.d.ts.map

package/dist/esm/function-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-alarms.d.ts","sourceRoot":"","sources":["../../src/function-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,KAAK,EAKX,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,QAAQ,IAAI,cAAc,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AA2CrF;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,mBAAmB,GAAG,SAAS,EACvC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,8BAA8B,CAAC,EACtE,YAAY,GAAE,mBAAmB,EAAO,GACvC,eAAe,EAAE,CAqGnB;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,mBAAmB,GAAG,KAAK,GAAG,SAAS,EAC/C,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,8BAA8B,CAAC,EACtE,YAAY,GAAE,mBAAmB,EAAO,EACxC,YAAY,GAAE,sBAAsB,CAAC,cAAc,CAAC,EAAO,GAC1D,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/{function-alarms.js → esm/function-alarms.js}

@@ -1,15 +1,40 @@
 import { Duration } from "aws-cdk-lib";
-import { ComparisonOperator, Stats, } from "aws-cdk-lib/aws-cloudwatch";
+import { ComparisonOperator, Metric, Stats, } from "aws-cdk-lib/aws-cloudwatch";
 import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
 import { FUNCTION_ALARM_DEFAULTS } from "./alarm-defaults.js";
 const METRIC_PERIOD = Duration.minutes(1);
 const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * Contextual alarm specs keyed by source kind: each attached event source
+ * of a kind contributes one alarm per spec, dimensioned on its mapping UUID.
+ *
+ * @see https://aws.amazon.com/blogs/compute/introducing-new-event-source-mapping-esm-metrics-for-aws-lambda/
+ */
+const EVENT_SOURCE_ALARM_SPECS = {
+    sqs: [
+        {
+            keySuffix: "FailedInvocations",
+            configKey: "eventSourceFailedInvocations",
+            metricName: "FailedInvokeEventCount",
+            describe: (key, threshold) => `Lambda event source "${key}" is failing to invoke the function. ` +
+                `Threshold: > ${String(threshold)} failed invocations in ${METRIC_PERIOD_LABEL}.`,
+        },
+        {
+            keySuffix: "DroppedEvents",
+            configKey: "eventSourceDroppedEvents",
+            metricName: "DroppedEventCount",
+            describe: (key, threshold) => `Lambda event source "${key}" is dropping events after exhausting retries or TTL. ` +
+                `Threshold: > ${String(threshold)} dropped events in ${METRIC_PERIOD_LABEL}.`,
+        },
+    ],
+    unknown: [],
+};
 /**
  * Resolves the recommended alarm configuration into fully-resolved
  * {@link AlarmDefinition}s, applying contextual logic for timeout-based
  * duration and reserved-concurrency-based concurrent execution alarms.
  */
-export function resolveFunctionAlarmDefinitions(fn, config, props) {
+export function resolveFunctionAlarmDefinitions(fn, config, props, eventSources = []) {
     if (config?.enabled === false)
         return [];
     const definitions = [];
@@ -76,8 +101,46 @@ export function resolveFunctionAlarmDefinitions(fn, config, props) {
             description: `Lambda function concurrent executions approaching reserved concurrency limit. Threshold: >= ${String(threshold)} (${String(cfg.thresholdPercent * 100)}% of ${String(reservedConcurrency)} reserved).`,
         });
     }
+    for (const eventSource of eventSources) {
+        // The ESM metrics that back these alarms are dimensioned on the mapping
+        // UUID; without it (e.g. a bare escape-hatch source) there is nothing to
+        // alarm on.
+        if (eventSource.eventSourceMappingId === undefined)
+            continue;
+        for (const spec of EVENT_SOURCE_ALARM_SPECS[eventSource.kind]) {
+            const userConfig = config?.[spec.configKey];
+            if (userConfig === false)
+                continue;
+            const cfg = resolveAlarmConfig(userConfig, FUNCTION_ALARM_DEFAULTS[spec.configKey]);
+            definitions.push({
+                key: `${eventSource.key}${spec.keySuffix}`,
+                alarmName: cfg.alarmName,
+                metric: eventSourceMetric(eventSource.eventSourceMappingId, spec.metricName),
+                threshold: cfg.threshold,
+                comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+                evaluationPeriods: cfg.evaluationPeriods,
+                datapointsToAlarm: cfg.datapointsToAlarm,
+                treatMissingData: cfg.treatMissingData,
+                description: spec.describe(eventSource.key, cfg.threshold),
+            });
+        }
+    }
     return definitions;
 }
+/**
+ * Builds an `AWS/Lambda` event source mapping metric. These per-mapping ESM
+ * metrics are dimensioned on `EventSourceMappingUUID` rather than
+ * `FunctionName`, so they cannot use the function's built-in metric helpers.
+ */
+function eventSourceMetric(eventSourceMappingId, metricName) {
+    return new Metric({
+        namespace: "AWS/Lambda",
+        metricName,
+        dimensionsMap: { EventSourceMappingUUID: eventSourceMappingId },
+        statistic: Stats.SUM,
+        period: METRIC_PERIOD,
+    });
+}
 /**
  * Creates AWS-recommended CloudWatch alarms for a Lambda function,
  * merging recommended definitions with any custom alarm builders.
@@ -87,18 +150,20 @@ export function resolveFunctionAlarmDefinitions(fn, config, props) {
  * @param fn - The Lambda function to create alarms for.
  * @param config - User-provided alarm configuration, or `false` to disable all.
  * @param props - The merged function props, used for contextual alarm thresholds.
+ * @param eventSources - Event sources attached to the function, used for
+ *   per-event-source contextual alarms.
  * @param customAlarms - Custom alarm builders added via `addAlarm()`.
  * @returns A record mapping alarm keys to their created Alarm constructs.
  *
  * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
  */
-export function createFunctionAlarms(scope, id, fn, config, props, customAlarms = []) {
+export function createFunctionAlarms(scope, id, fn, config, props, eventSources = [], customAlarms = []) {
     if (config === false)
         return {};
     const enabled = config?.enabled ?? FUNCTION_ALARM_DEFAULTS.enabled;
     if (!enabled)
         return {};
-    const recommended = resolveFunctionAlarmDefinitions(fn, config, props);
+    const recommended = resolveFunctionAlarmDefinitions(fn, config, props, eventSources);
     const custom = customAlarms.map((b) => b.resolve(fn));
     return createAlarms(scope, id, [...recommended, ...custom]);
 }

package/dist/esm/function-alarms.js.map

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

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

@@ -0,0 +1,252 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type IRole } from "aws-cdk-lib/aws-iam";
+import { Function as LambdaFunction, type FunctionProps, type IEventSource } from "aws-cdk-lib/aws-lambda";
+import type { LogGroup } from "aws-cdk-lib/aws-logs";
+import { type IConstruct } from "constructs";
+import { COPY_STATE, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { type ITaggedBuilder } from "@composurecdk/cloudformation";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { type IRoleBuilder } from "@composurecdk/iam";
+import type { FunctionAlarmConfig } from "./alarm-config.js";
+import { type ComposureEventSource } from "./event-sources/composure-event-source.js";
+/**
+ * Configuration properties for the Lambda function builder.
+ *
+ * Extends the CDK {@link FunctionProps} with builder-specific options. The
+ * `role` prop is widened to {@link Resolvable} so a role built by a sibling
+ * component can be referenced via `ref(...)` at configuration time.
+ */
+export interface FunctionBuilderProps extends Omit<FunctionProps, "role"> {
+    /**
+     * The IAM execution role to attach to the function. When set, the builder
+     * skips creating its own role and the auto-created `LogsWriter` inline
+     * policy is **not** added — the caller is fully responsible for the role's
+     * permissions.
+     *
+     * Accepts a concrete {@link IRole} or a {@link Resolvable} for
+     * cross-component wiring (e.g. `ref("sharedRole", r => r.role)`).
+     *
+     * Mutually exclusive with {@link IFunctionBuilder.configureRole} and
+     * {@link IFunctionBuilder.useCdkAutoRole}.
+     */
+    role?: Resolvable<IRole>;
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * By default, the builder creates recommended alarms with sensible
+     * thresholds for every applicable metric. Individual alarms can be
+     * customized or disabled. Set to `false` to disable all alarms.
+     *
+     * No alarm actions are configured by default since notification
+     * methods are user-specific. Access alarms from the build result
+     * or use an `afterBuild` hook to apply actions.
+     *
+     * Contextual alarms are only created when the corresponding function
+     * configuration is present: `duration` when `timeout` is set,
+     * `concurrentExecutions` when `reservedConcurrentExecutions` is set, and
+     * the event-source alarms (`eventSourceFailedInvocations`,
+     * `eventSourceDroppedEvents`) once an event source is attached via
+     * {@link IFunctionBuilder.addEventSource}.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
+     */
+    recommendedAlarms?: FunctionAlarmConfig | false;
+}
+/**
+ * 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;
+    /**
+     * The IAM execution role attached to the function. Always populated:
+     * - if the caller supplied a role via {@link IFunctionBuilder.role}, this
+     *   is that role;
+     * - if {@link IFunctionBuilder.useCdkAutoRole} was called, this is CDK's
+     *   auto-created role;
+     * - otherwise, this is the explicit role the builder constructed via
+     *   `@composurecdk/iam`'s `createServiceRoleBuilder`, with an inline
+     *   `LogsWriter` policy scoped to the function's auto-created log group.
+     */
+    role: IRole;
+    /**
+     * The CloudWatch LogGroup created for the function, or `undefined` if
+     * the user provided their own via the `logGroup` property.
+     *
+     * By default the builder creates a managed LogGroup using
+     * {@link createLogGroupBuilder} with well-architected defaults (retention
+     * policy, removal policy). This follows AWS CDK guidance to create a
+     * `LogGroup` explicitly rather than relying on the auto-created default,
+     * which cannot be configured via CDK.
+     *
+     * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda-readme.html
+     * @see https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs-loggroups.html
+     */
+    logGroup?: LogGroup;
+    /**
+     * CloudWatch alarms created for the function, keyed by alarm name.
+     *
+     * Includes both AWS-recommended alarms and any custom alarms added
+     * via {@link IFunctionBuilder.addAlarm}. Access individual alarms
+     * by key (e.g., `result.alarms.errors`).
+     *
+     * No alarm actions are configured — apply them via the result or an
+     * `afterBuild` hook.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
+     */
+    alarms: Record<string, Alarm>;
+    /**
+     * Event sources attached to the function via
+     * {@link IFunctionBuilder.addEventSource}, keyed by the key passed to that
+     * call. Each value is the resolved CDK {@link IEventSource} — for sources
+     * built by a ComposureCDK factory (e.g. {@link sqsEventSource}) the
+     * concrete type is preserved, so callers can read back post-`bind()` state
+     * such as `eventSourceMappingId`.
+     *
+     * Always present — `{}` when no event sources were added.
+     */
+    eventSources: Record<string, IEventSource>;
+}
+/**
+ * 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}.
+ *
+ * Unless a user-supplied `logGroup` is provided, the builder automatically
+ * creates a managed CloudWatch LogGroup via {@link createLogGroupBuilder}
+ * with well-architected defaults (retention, removal policy) and wires it
+ * to the function. This ensures full control over log lifecycle and follows
+ * AWS CDK guidance to create a LogGroup explicitly.
+ *
+ * ## Execution role
+ *
+ * By default the builder creates an explicit IAM role via
+ * `@composurecdk/iam`'s `createServiceRoleBuilder("lambda.amazonaws.com")`,
+ * with an inline `LogsWriter` policy granting `logs:CreateLogStream` and
+ * `logs:PutLogEvents` scoped to the function's auto-created log group.
+ * This replaces CDK's default auto-role (which attaches the
+ * `AWSLambdaBasicExecutionRole` managed policy granting wildcard log
+ * access) with a least-privilege role.
+ *
+ * Three override seams are available, in order of preference:
+ *
+ * 1. {@link IFunctionBuilder.configureRole} — extend the default role
+ *    builder with additional inline policies, etc.
+ * 2. {@link IFunctionBuilder.role} — supply a fully external role; no
+ *    `LogsWriter` policy is added.
+ * 3. {@link IFunctionBuilder.useCdkAutoRole} — opt back into CDK's
+ *    auto-created role with `AWSLambdaBasicExecutionRole`.
+ *
+ * The seams are mutually exclusive; combining any two throws at build time.
+ *
+ * The builder also creates AWS-recommended CloudWatch alarms by default.
+ * Alarms can be customized or disabled via the `recommendedAlarms` property.
+ * Custom alarms can be added via the {@link addAlarm} method.
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda-readme.html
+ *
+ * @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 = ITaggedBuilder<FunctionBuilderProps, FunctionBuilder>;
+declare class FunctionBuilder implements Lifecycle<FunctionBuilderResult> {
+    #private;
+    props: Partial<FunctionBuilderProps>;
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<LambdaFunction>) => AlarmDefinitionBuilder<LambdaFunction>): this;
+    /**
+     * Register an event source to be attached to the function at build time.
+     *
+     * A Lambda function can have many event sources of mixed types, so this
+     * hook is repeatable and typed to the common {@link IEventSource}. Pass a
+     * {@link ComposureEventSource} from a ComposureCDK factory (e.g. {@link sqsEventSource})
+     * or a bare concrete {@link IEventSource}.
+     *
+     * At build time the source is resolved and attached *after* the function
+     * (and its least-privilege execution role) exist, so the `source.bind(fn)`
+     * that `addEventSource` performs grants the consume permission onto the
+     * builder's role. The resolved source is exposed on
+     * {@link FunctionBuilderResult.eventSources} under `key`.
+     *
+     * Sources built by a recognised factory also enable contextual alarms —
+     * see {@link FunctionBuilderProps.recommendedAlarms}.
+     *
+     * @throws If `key` was already used by a previous `addEventSource` call.
+     */
+    addEventSource(key: string, source: Resolvable<ComposureEventSource | IEventSource>): this;
+    /**
+     * Extend the default execution-role builder with additional configuration
+     * (inline policies, managed-policy attachments, description, etc.).
+     *
+     * The callback receives the internal {@link IRoleBuilder} that the function
+     * builder will use to construct the role. Calling `configureRole` more than
+     * once replaces the previous callback. The default `LogsWriter` inline
+     * policy is added before the callback runs; supplying another inline
+     * policy with the name `LogsWriter` throws at build time.
+     *
+     * Mutually exclusive with {@link role} and {@link useCdkAutoRole}.
+     */
+    configureRole(fn: (rb: IRoleBuilder) => unknown): this;
+    /**
+     * Opt back into CDK's auto-created execution role attached to the
+     * `AWSLambdaBasicExecutionRole` managed policy.
+     *
+     * **Not the recommended path.** The default builder-created role grants
+     * `logs:CreateLogStream` and `logs:PutLogEvents` scoped to the function's
+     * own log group; CDK's auto-role grants those actions on `*` and also
+     * permits `logs:CreateLogGroup` arbitrarily. Use this escape hatch only
+     * when matching an existing stack's logical IDs during a phased migration
+     * or when the wildcard log surface is a deliberate trade-off.
+     *
+     * Mutually exclusive with {@link role} and {@link configureRole}.
+     */
+    useCdkAutoRole(): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: FunctionBuilder): void;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): 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 FunctionBuilderProps} 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/esm/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,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,KAAK,KAAK,EAAiB,MAAM,qBAAqB,CAAC;AAChE,OAAO,EACL,QAAQ,IAAI,cAAc,EAC1B,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,2CAA2C,CAAC;AAInD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC;IACvE;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAEzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAAiB,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,QAAQ,EAAE,cAAc,CAAC;IAEzB;;;;;;;;;OASG;IACH,IAAI,EAAE,KAAK,CAAC;IAEZ;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE9B;;;;;;;;;OASG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAC;AAOrF,cAAM,eAAgB,YAAW,SAAS,CAAC,qBAAqB,CAAC;;IAC/D,KAAK,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAM;IAM1C,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CACT,KAAK,EAAE,sBAAsB,CAAC,cAAc,CAAC,KAC1C,sBAAsB,CAAC,cAAc,CAAC,GAC1C,IAAI;IAKP;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,oBAAoB,GAAG,YAAY,CAAC,GAAG,IAAI;IAU1F;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,GAAG,IAAI;IAKtD;;;;;;;;;;;;OAYG;IACH,cAAc,IAAI,IAAI;IAKtB,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAO3C,KAAK,CACH,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,qBAAqB;CAyHzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD"}