@composurecdk/lambda 0.7.0 → 0.8.1

package/dist/commonjs/function-builder.js

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFunctionBuilder = createFunctionBuilder;
+const aws_iam_1 = require("aws-cdk-lib/aws-iam");
+const aws_lambda_1 = require("aws-cdk-lib/aws-lambda");
+const core_1 = require("@composurecdk/core");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const iam_1 = require("@composurecdk/iam");
+const logs_1 = require("@composurecdk/logs");
+const function_alarms_js_1 = require("./function-alarms.js");
+const defaults_js_1 = require("./defaults.js");
+const composure_event_source_js_1 = require("./event-sources/composure-event-source.js");
+const LOGS_WRITER_POLICY_NAME = "LogsWriter";
+class FunctionBuilder {
+    props = {};
+    #customAlarms = [];
+    #eventSources = [];
+    #configureRole;
+    #useCdkAutoRole = false;
+    addAlarm(key, configure) {
+        this.#customAlarms.push(configure(new cloudwatch_1.AlarmDefinitionBuilder(key)));
+        return 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, source) {
+        if (this.#eventSources.some((e) => e.key === key)) {
+            throw new Error(`FunctionBuilder.addEventSource: duplicate key "${key}". Each event source must use a unique key.`);
+        }
+        this.#eventSources.push({ key, source });
+        return 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) {
+        this.#configureRole = fn;
+        return 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.#useCdkAutoRole = true;
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [core_1.COPY_STATE](target) {
+        target.#customAlarms.push(...this.#customAlarms);
+        target.#eventSources.push(...this.#eventSources);
+        target.#configureRole = this.#configureRole;
+        target.#useCdkAutoRole = this.#useCdkAutoRole;
+    }
+    build(scope, id, context = {}) {
+        const { role: roleResolvable, recommendedAlarms: alarmConfig, ...functionProps } = this.props;
+        const seamCount = (roleResolvable !== undefined ? 1 : 0) +
+            (this.#configureRole !== undefined ? 1 : 0) +
+            (this.#useCdkAutoRole ? 1 : 0);
+        if (seamCount > 1) {
+            throw new Error(`FunctionBuilder "${id}": .role(), .configureRole(), and .useCdkAutoRole() are mutually exclusive`);
+        }
+        let logGroup;
+        let logGroupProps = {};
+        if (!this.props.logGroup) {
+            logGroup = (0, logs_1.createLogGroupBuilder)().build(scope, `${id}LogGroup`).logGroup;
+            logGroupProps = { logGroup };
+        }
+        let role;
+        if (roleResolvable !== undefined) {
+            role = (0, core_1.resolve)(roleResolvable, context);
+        }
+        else if (!this.#useCdkAutoRole) {
+            role = this.#buildDefaultRole(scope, id, context, (logGroup ?? this.props.logGroup));
+        }
+        const mergedProps = {
+            ...defaults_js_1.FUNCTION_DEFAULTS,
+            ...logGroupProps,
+            ...functionProps,
+            ...(role ? { role } : {}),
+        };
+        const fn = new aws_lambda_1.Function(scope, id, mergedProps);
+        const eventSources = {};
+        const attachedEventSources = [];
+        for (const entry of this.#eventSources) {
+            const outer = (0, core_1.resolve)(entry.source, context);
+            let kind = "unknown";
+            let eventSource;
+            if ((0, composure_event_source_js_1.isComposureEventSource)(outer)) {
+                kind = outer.kind;
+                eventSource = (0, core_1.resolve)(outer.source, context);
+            }
+            else {
+                eventSource = outer;
+            }
+            // Attach after the function exists so the `source.bind(fn)` that
+            // `addEventSource` performs grants the consume permission onto the
+            // builder's least-privilege role; the mapping UUID is only readable
+            // once bound.
+            fn.addEventSource(eventSource);
+            eventSources[entry.key] = eventSource;
+            attachedEventSources.push({
+                key: entry.key,
+                kind,
+                eventSourceMappingId: composure_event_source_js_1.EVENT_SOURCE_MAPPING_ID_READERS[kind]?.(eventSource),
+            });
+        }
+        const alarms = (0, function_alarms_js_1.createFunctionAlarms)(scope, id, fn, alarmConfig, mergedProps, attachedEventSources, this.#customAlarms);
+        const resolvedRole = role ?? fn.role;
+        if (!resolvedRole) {
+            throw new Error(`FunctionBuilder "${id}": Lambda function has no execution role.`);
+        }
+        return { function: fn, role: resolvedRole, logGroup, alarms, eventSources };
+    }
+    #buildDefaultRole(scope, id, context, logGroup) {
+        if (!logGroup) {
+            throw new Error(`FunctionBuilder "${id}": cannot build the default execution role without a log group.`);
+        }
+        const logGroupArn = logGroup.logGroupArn;
+        const roleBuilder = (0, iam_1.createServiceRoleBuilder)("lambda.amazonaws.com").addInlinePolicyStatements(LOGS_WRITER_POLICY_NAME, [
+            (0, iam_1.createStatementBuilder)()
+                .allow()
+                .actions(["logs:CreateLogStream", "logs:PutLogEvents"])
+                .resources([logGroupArn, `${logGroupArn}:log-stream:*`]),
+        ]);
+        // CDK attaches AWSLambdaVPCAccessExecutionRole only when it constructs
+        // the role itself; when we supply the role we must add it ourselves.
+        if (this.props.vpc) {
+            roleBuilder.managedPolicies([
+                ...(roleBuilder.managedPolicies() ?? []),
+                aws_iam_1.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaVPCAccessExecutionRole"),
+            ]);
+        }
+        if (this.#configureRole) {
+            this.#configureRole(guardLogsWriter(roleBuilder, id));
+        }
+        return roleBuilder.build(scope, `${id}ExecutionRole`, context).role;
+    }
+}
+/**
+ * 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: [] },
+ * );
+ * ```
+ */
+function createFunctionBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(FunctionBuilder);
+}
+/**
+ * Wraps a role builder so a user configurator that calls
+ * `addInlinePolicyStatements("LogsWriter", ...)` fails loudly. RoleBuilder
+ * stores inline policies in an internal array and the resulting record uses
+ * the policy name as a key — a duplicate `LogsWriter` would silently
+ * overwrite the scoped log policy and re-introduce wildcard log access.
+ */
+function guardLogsWriter(rb, functionId) {
+    const original = rb.addInlinePolicyStatements.bind(rb);
+    return new Proxy(rb, {
+        get(target, prop, receiver) {
+            if (prop === "addInlinePolicyStatements") {
+                const guarded = (name, statements) => {
+                    if (name === LOGS_WRITER_POLICY_NAME) {
+                        throw new Error(`FunctionBuilder "${functionId}": cannot add an inline policy named ` +
+                            `"${LOGS_WRITER_POLICY_NAME}" via .configureRole — the builder already ` +
+                            `attaches one scoped to the function's log group. Use a different ` +
+                            `name or call .role(...) to take full control of the role.`);
+                    }
+                    return original(name, statements);
+                };
+                return guarded;
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+//# sourceMappingURL=function-builder.js.map

package/dist/commonjs/function-builder.js.map

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

package/dist/{index.d.ts → commonjs/index.d.ts}

@@ -2,4 +2,6 @@ export { createFunctionBuilder, type FunctionBuilderProps, type FunctionBuilderR
 export { FUNCTION_DEFAULTS } from "./defaults.js";
 export { type FunctionAlarmConfig, type PercentageAlarmConfig } from "./alarm-config.js";
 export { FUNCTION_ALARM_DEFAULTS } from "./alarm-defaults.js";
+export { type ComposureEventSource, type EventSourceKind, } from "./event-sources/composure-event-source.js";
+export { sqsEventSource, DEFAULT_SQS_EVENT_SOURCE_PROPS, } from "./event-sources/sqs-event-source.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/commonjs/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,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,cAAc,EACd,8BAA8B,GAC/B,MAAM,qCAAqC,CAAC"}

package/dist/commonjs/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SQS_EVENT_SOURCE_PROPS = exports.sqsEventSource = exports.FUNCTION_ALARM_DEFAULTS = exports.FUNCTION_DEFAULTS = exports.createFunctionBuilder = void 0;
+var function_builder_js_1 = require("./function-builder.js");
+Object.defineProperty(exports, "createFunctionBuilder", { enumerable: true, get: function () { return function_builder_js_1.createFunctionBuilder; } });
+var defaults_js_1 = require("./defaults.js");
+Object.defineProperty(exports, "FUNCTION_DEFAULTS", { enumerable: true, get: function () { return defaults_js_1.FUNCTION_DEFAULTS; } });
+var alarm_defaults_js_1 = require("./alarm-defaults.js");
+Object.defineProperty(exports, "FUNCTION_ALARM_DEFAULTS", { enumerable: true, get: function () { return alarm_defaults_js_1.FUNCTION_ALARM_DEFAULTS; } });
+var sqs_event_source_js_1 = require("./event-sources/sqs-event-source.js");
+Object.defineProperty(exports, "sqsEventSource", { enumerable: true, get: function () { return sqs_event_source_js_1.sqsEventSource; } });
+Object.defineProperty(exports, "DEFAULT_SQS_EVENT_SOURCE_PROPS", { enumerable: true, get: function () { return sqs_event_source_js_1.DEFAULT_SQS_EVENT_SOURCE_PROPS; } });
+//# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAK+B;AAJ7B,4HAAA,qBAAqB,OAAA;AAKvB,6CAAkD;AAAzC,gHAAA,iBAAiB,OAAA;AAE1B,yDAA8D;AAArD,4HAAA,uBAAuB,OAAA;AAKhC,2EAG6C;AAF3C,qHAAA,cAAc,OAAA;AACd,qIAAA,8BAA8B,OAAA"}

package/dist/commonjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/esm/alarm-config.d.ts

@@ -0,0 +1,114 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Configuration for a percentage-based contextual alarm.
+ *
+ * Derived from {@link AlarmConfig} with `threshold` replaced by
+ * `thresholdPercent`. These alarms derive their threshold as a
+ * percentage of a function property (e.g., timeout or reserved
+ * concurrency). The threshold automatically adjusts when the base
+ * value changes, keeping the alarm true to its definition.
+ *
+ * For a fixed absolute threshold, disable the recommended alarm and
+ * add a custom one via {@link IFunctionBuilder.addAlarm}.
+ */
+export type PercentageAlarmConfig = Omit<AlarmConfig, "threshold"> & {
+    /**
+     * Threshold as a fraction of the base value (e.g., `0.9` = 90%).
+     * Must be between 0 and 1 (exclusive of 0).
+     */
+    thresholdPercent?: number;
+};
+/**
+ * Type for percentage-based defaults. Mirrors {@link AlarmConfigDefaults}:
+ * every tunable field is required, but `alarmName` is intentionally not.
+ */
+export type PercentageAlarmConfigDefaults = Required<Omit<PercentageAlarmConfig, "alarmName">>;
+/**
+ * Controls which recommended alarms are created for a Lambda function.
+ * All alarms are enabled by default with AWS-recommended thresholds.
+ * Set individual alarms to `false` to disable them, or provide an
+ * {@link AlarmConfig} or {@link PercentageAlarmConfig} to tune thresholds.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
+ */
+export interface FunctionAlarmConfig {
+    /**
+     * Master switch: set to `false` to disable all recommended alarms.
+     * Individual alarms can also be disabled via their own entry.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Alarm when the function produces invocation errors.
+     *
+     * Metric: `AWS/Lambda Errors`, statistic Sum, period 1 minute.
+     * Default threshold: > 0 errors.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
+     */
+    errors?: AlarmConfig | false;
+    /**
+     * Alarm when invocations are throttled.
+     *
+     * Metric: `AWS/Lambda Throttles`, statistic Sum, period 1 minute.
+     * Default threshold: > 0 throttles.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
+     */
+    throttles?: AlarmConfig | false;
+    /**
+     * Alarm when p99 duration approaches the configured timeout.
+     *
+     * Only created when the function has a `timeout` configured, since
+     * the threshold is derived as a percentage of the timeout value.
+     *
+     * Metric: `AWS/Lambda Duration`, statistic p99, period 1 minute.
+     * Default: 90% of the function timeout (`thresholdPercent: 0.9`).
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
+     */
+    duration?: PercentageAlarmConfig | false;
+    /**
+     * Alarm when concurrent executions approach the reserved limit.
+     *
+     * Only created when `reservedConcurrentExecutions` is configured,
+     * since the threshold is derived as a percentage of the reserved limit.
+     *
+     * Metric: `AWS/Lambda ConcurrentExecutions`, statistic Maximum, period 1 minute.
+     * Default: 80% of reservedConcurrentExecutions (`thresholdPercent: 0.8`).
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
+     */
+    concurrentExecutions?: PercentageAlarmConfig | false;
+    /**
+     * Alarm when an event source fails to invoke the function.
+     *
+     * Contextual: one alarm is created per event source attached via
+     * {@link IFunctionBuilder.addEventSource} whose kind emits per-mapping ESM
+     * metrics (currently SQS). The created alarm's key is the event source's
+     * key suffixed with `FailedInvocations` (e.g. `ordersFailedInvocations`);
+     * this config tunes every such alarm.
+     *
+     * Metric: `AWS/Lambda FailedInvokeEventCount`, statistic Sum, period 1
+     * minute, dimensioned on the event source mapping. Default threshold: > 0.
+     *
+     * @see https://aws.amazon.com/blogs/compute/introducing-new-event-source-mapping-esm-metrics-for-aws-lambda/
+     */
+    eventSourceFailedInvocations?: AlarmConfig | false;
+    /**
+     * Alarm when an event source drops events after exhausting retries or TTL.
+     *
+     * Contextual: one alarm is created per event source attached via
+     * {@link IFunctionBuilder.addEventSource} whose kind emits per-mapping ESM
+     * metrics (currently SQS). The created alarm's key is the event source's
+     * key suffixed with `DroppedEvents` (e.g. `ordersDroppedEvents`); this
+     * config tunes every such alarm.
+     *
+     * Metric: `AWS/Lambda DroppedEventCount`, statistic Sum, period 1 minute,
+     * dimensioned on the event source mapping. Default threshold: > 0.
+     *
+     * @see https://aws.amazon.com/blogs/compute/introducing-new-event-source-mapping-esm-metrics-for-aws-lambda/
+     */
+    eventSourceDroppedEvents?: AlarmConfig | false;
+}
+//# sourceMappingURL=alarm-config.d.ts.map

package/dist/esm/alarm-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG;IACnE;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC,IAAI,CAAC,qBAAqB,EAAE,WAAW,CAAC,CAAC,CAAC;AAE/F;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAE7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAErD;;;;;;;;;;;;;OAaG;IACH,4BAA4B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEnD;;;;;;;;;;;;;OAaG;IACH,wBAAwB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAChD"}

package/dist/esm/alarm-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.js","sourceRoot":"","sources":["../../src/alarm-config.ts"],"names":[],"mappings":""}

package/dist/esm/alarm-defaults.d.ts

@@ -0,0 +1,19 @@
+import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
+import type { PercentageAlarmConfigDefaults } from "./alarm-config.js";
+interface FunctionAlarmDefaults {
+    enabled: true;
+    errors: AlarmConfigDefaults;
+    throttles: AlarmConfigDefaults;
+    duration: PercentageAlarmConfigDefaults;
+    concurrentExecutions: PercentageAlarmConfigDefaults;
+    eventSourceFailedInvocations: AlarmConfigDefaults;
+    eventSourceDroppedEvents: AlarmConfigDefaults;
+}
+/**
+ * AWS-recommended default alarm configuration for Lambda functions.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda
+ */
+export declare const FUNCTION_ALARM_DEFAULTS: FunctionAlarmDefaults;
+export {};
+//# sourceMappingURL=alarm-defaults.d.ts.map

package/dist/esm/alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC;AAEvE,UAAU,qBAAqB;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;IAC5B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,EAAE,6BAA6B,CAAC;IACxC,oBAAoB,EAAE,6BAA6B,CAAC;IACpD,4BAA4B,EAAE,mBAAmB,CAAC;IAClD,wBAAwB,EAAE,mBAAmB,CAAC;CAC/C;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,qBAwDrC,CAAC"}

package/dist/{alarm-defaults.js → esm/alarm-defaults.js}

@@ -40,5 +40,19 @@ export const FUNCTION_ALARM_DEFAULTS = {
         datapointsToAlarm: 3,
         treatMissingData: TreatMissingData.NOT_BREACHING,
     },
+    /** Any failed invocation from an event source is worth investigating; threshold 0. */
+    eventSourceFailedInvocations: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** Any dropped event is lost work; threshold 0. */
+    eventSourceDroppedEvents: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
 };
 //# sourceMappingURL=alarm-defaults.js.map

package/dist/esm/alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAc9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA0B;IAC5D,OAAO,EAAE,IAAI;IAEb,qDAAqD;IACrD,MAAM,EAAE;QACN,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,6DAA6D;IAC7D,SAAS,EAAE;QACT,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;OAGG;IACH,QAAQ,EAAE;QACR,gBAAgB,EAAE,GAAG;QACrB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;OAGG;IACH,oBAAoB,EAAE;QACpB,gBAAgB,EAAE,GAAG;QACrB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,sFAAsF;IACtF,4BAA4B,EAAE;QAC5B,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,mDAAmD;IACnD,wBAAwB,EAAE;QACxB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/esm/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/esm/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/esm/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/esm/event-sources/composure-event-source.d.ts

@@ -0,0 +1,76 @@
+import type { IEventSource } from "aws-cdk-lib/aws-lambda";
+import type { Resolvable } from "@composurecdk/core";
+/**
+ * Discriminator for the kind of event source a {@link ComposureEventSource}
+ * wraps. `FunctionBuilder` keys its contextual alarms and invariant checks
+ * off this value so it never has to `instanceof` CDK internals.
+ *
+ * `"unknown"` is the kind assigned to a bare {@link IEventSource} passed
+ * straight to {@link IFunctionBuilder.addEventSource} as an escape hatch —
+ * the builder still attaches it, but cannot reason about it.
+ */
+export type EventSourceKind = "sqs" | "unknown";
+/** @internal — brands {@link ComposureEventSource} so the guard is unambiguous. */
+declare const COMPOSURE_EVENT_SOURCE: unique symbol;
+/**
+ * A `Resolvable`-aware event source produced by a ComposureCDK factory
+ * (e.g. {@link sqsEventSource}).
+ *
+ * Follows the `events/targets` factory shape — the factory wraps the
+ * underlying CDK event source and resolves any `ref()` to a sibling
+ * component at build time — and additionally tags it with a
+ * {@link EventSourceKind} discriminator so `FunctionBuilder` can pick the
+ * right contextual alarms without inspecting CDK internals.
+ *
+ * Construct one via a factory rather than by hand; the brand is private.
+ */
+export interface ComposureEventSource {
+    /** @internal */
+    readonly [COMPOSURE_EVENT_SOURCE]: true;
+    /** The kind of source, used to dispatch contextual alarms and checks. */
+    readonly kind: EventSourceKind;
+    /**
+     * The wrapped CDK event source, deferred behind a {@link Resolvable} when
+     * the factory was handed a `ref()` to a sibling component's output.
+     */
+    readonly source: Resolvable<IEventSource>;
+}
+/** @internal — assembles a branded {@link ComposureEventSource}. */
+export declare function composureEventSource(kind: EventSourceKind, source: Resolvable<IEventSource>): ComposureEventSource;
+/**
+ * Reads the event source mapping UUID off a bound CDK source, keyed by
+ * {@link EventSourceKind}. Defined only for kinds whose per-mapping ESM
+ * metrics back contextual alarms (currently SQS); `FunctionBuilder` invokes
+ * the reader after `addEventSource` so the binding exists. Keying off `kind`
+ * — like {@link EVENT_SOURCE_ALARM_SPECS} — keeps the builder from
+ * `instanceof`-ing CDK source classes.
+ *
+ * @internal
+ */
+export declare const EVENT_SOURCE_MAPPING_ID_READERS: Record<EventSourceKind, ((bound: IEventSource) => string) | undefined>;
+/**
+ * Type guard distinguishing a {@link ComposureEventSource} from a bare
+ * {@link IEventSource} escape-hatch value.
+ */
+export declare function isComposureEventSource(value: ComposureEventSource | IEventSource): value is ComposureEventSource;
+/**
+ * An event source resolved and attached to a function during build, carrying
+ * the metadata the alarm machinery needs to emit contextual alarms.
+ *
+ * @internal — the contract between `FunctionBuilder.build()` and the
+ *   event-source alarm machinery in `function-alarms.ts`.
+ */
+export interface AttachedEventSource {
+    /** The key the source was registered under via `addEventSource`. */
+    key: string;
+    /** The kind of source, used to dispatch contextual alarms. */
+    kind: EventSourceKind;
+    /**
+     * The event source mapping UUID, populated for kinds whose per-mapping
+     * ESM metrics back contextual alarms (currently SQS only). The contextual
+     * alarms key off this dimension.
+     */
+    eventSourceMappingId?: string;
+}
+export {};
+//# sourceMappingURL=composure-event-source.d.ts.map

package/dist/esm/event-sources/composure-event-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composure-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,SAAS,CAAC;AAEhD,mFAAmF;AACnF,QAAA,MAAM,sBAAsB,eAAgD,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB;IAChB,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC;IAExC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;CAC3C;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,GAC/B,oBAAoB,CAEtB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAClD,eAAe,EACf,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,GAAG,SAAS,CAO9C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAAG,YAAY,GACzC,KAAK,IAAI,oBAAoB,CAE/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IAEZ,8DAA8D;IAC9D,IAAI,EAAE,eAAe,CAAC;IAEtB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B"}

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

@@ -0,0 +1,31 @@
+/** @internal — brands {@link ComposureEventSource} so the guard is unambiguous. */
+const COMPOSURE_EVENT_SOURCE = Symbol.for("composurecdk.lambda.eventSource");
+/** @internal — assembles a branded {@link ComposureEventSource}. */
+export function composureEventSource(kind, source) {
+    return { [COMPOSURE_EVENT_SOURCE]: true, kind, source };
+}
+/**
+ * Reads the event source mapping UUID off a bound CDK source, keyed by
+ * {@link EventSourceKind}. Defined only for kinds whose per-mapping ESM
+ * metrics back contextual alarms (currently SQS); `FunctionBuilder` invokes
+ * the reader after `addEventSource` so the binding exists. Keying off `kind`
+ * — like {@link EVENT_SOURCE_ALARM_SPECS} — keeps the builder from
+ * `instanceof`-ing CDK source classes.
+ *
+ * @internal
+ */
+export const EVENT_SOURCE_MAPPING_ID_READERS = {
+    // Safe: the `"sqs"` kind is only ever assigned by `sqsEventSource()`, which
+    // constructs the `SqsEventSource` in the same call — kind and concrete class
+    // move in lockstep.
+    sqs: (bound) => bound.eventSourceMappingId,
+    unknown: undefined,
+};
+/**
+ * Type guard distinguishing a {@link ComposureEventSource} from a bare
+ * {@link IEventSource} escape-hatch value.
+ */
+export function isComposureEventSource(value) {
+    return COMPOSURE_EVENT_SOURCE in value;
+}
+//# sourceMappingURL=composure-event-source.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"composure-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":"AAeA,mFAAmF;AACnF,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;AA4B7E,oEAAoE;AACpE,MAAM,UAAU,oBAAoB,CAClC,IAAqB,EACrB,MAAgC;IAEhC,OAAO,EAAE,CAAC,sBAAsB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAGxC;IACF,4EAA4E;IAC5E,6EAA6E;IAC7E,oBAAoB;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAE,KAAwB,CAAC,oBAAoB;IAC9D,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAA0C;IAE1C,OAAO,sBAAsB,IAAI,KAAK,CAAC;AACzC,CAAC"}

package/dist/esm/event-sources/sqs-event-source.d.ts

@@ -0,0 +1,54 @@
+import { type SqsEventSourceProps } from "aws-cdk-lib/aws-lambda-event-sources";
+import type { IQueue } from "aws-cdk-lib/aws-sqs";
+import { type Resolvable } from "@composurecdk/core";
+import { type 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 declare const DEFAULT_SQS_EVENT_SOURCE_PROPS: Pick<SqsEventSourceProps, "reportBatchItemFailures" | "metricsConfig">;
+/**
+ * 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 declare function sqsEventSource(queue: Resolvable<IQueue>, props?: SqsEventSourceProps): ComposureEventSource;
+//# sourceMappingURL=sqs-event-source.d.ts.map

package/dist/esm/event-sources/sqs-event-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/sqs-event-source.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,KAAK,oBAAoB,EAAwB,MAAM,6BAA6B,CAAC;AAE9F;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,IAAI,CAC/C,mBAAmB,EACnB,yBAAyB,GAAG,eAAe,CAkB5C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,CAAC,EAAE,mBAAmB,GAC1B,oBAAoB,CAMtB"}