@composurecdk/lambda 0.7.0 → 0.8.0

package/dist/commonjs/function-alarms.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFunctionAlarmDefinitions = resolveFunctionAlarmDefinitions;
+exports.createFunctionAlarms = createFunctionAlarms;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const alarm_defaults_js_1 = require("./alarm-defaults.js");
+const METRIC_PERIOD = aws_cdk_lib_1.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.
+ */
+function resolveFunctionAlarmDefinitions(fn, config, props, eventSources = []) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.errors !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.errors, alarm_defaults_js_1.FUNCTION_ALARM_DEFAULTS.errors);
+        definitions.push({
+            key: "errors",
+            alarmName: cfg.alarmName,
+            metric: fn.metricErrors({ period: METRIC_PERIOD }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Lambda function is producing invocation errors. Threshold: > ${String(cfg.threshold)} errors in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.throttles !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.throttles, alarm_defaults_js_1.FUNCTION_ALARM_DEFAULTS.throttles);
+        definitions.push({
+            key: "throttles",
+            alarmName: cfg.alarmName,
+            metric: fn.metricThrottles({ period: METRIC_PERIOD }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Lambda function invocations are being throttled. Threshold: > ${String(cfg.threshold)} throttles in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    const timeoutMs = props.timeout?.toMilliseconds();
+    if (config?.duration !== false && timeoutMs !== undefined) {
+        const cfg = resolvePercentageAlarmConfig(config?.duration, alarm_defaults_js_1.FUNCTION_ALARM_DEFAULTS.duration);
+        const threshold = Math.round(timeoutMs * cfg.thresholdPercent);
+        definitions.push({
+            key: "duration",
+            alarmName: cfg.alarmName,
+            metric: fn.metricDuration({ period: METRIC_PERIOD, statistic: aws_cloudwatch_1.Stats.percentile(99) }),
+            threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Lambda function p99 duration is approaching the configured timeout. Threshold: > ${String(threshold)}ms (${String(cfg.thresholdPercent * 100)}% of ${String(timeoutMs)}ms timeout).`,
+        });
+    }
+    const reservedConcurrency = props.reservedConcurrentExecutions;
+    if (config?.concurrentExecutions !== false && reservedConcurrency !== undefined) {
+        const cfg = resolvePercentageAlarmConfig(config?.concurrentExecutions, alarm_defaults_js_1.FUNCTION_ALARM_DEFAULTS.concurrentExecutions);
+        const threshold = Math.round(reservedConcurrency * cfg.thresholdPercent);
+        definitions.push({
+            key: "concurrentExecutions",
+            alarmName: cfg.alarmName,
+            metric: fn.metric("ConcurrentExecutions", {
+                period: METRIC_PERIOD,
+                statistic: aws_cloudwatch_1.Stats.MAXIMUM,
+            }),
+            threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            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 = (0, cloudwatch_1.resolveAlarmConfig)(userConfig, alarm_defaults_js_1.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: aws_cloudwatch_1.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 aws_cloudwatch_1.Metric({
+        namespace: "AWS/Lambda",
+        metricName,
+        dimensionsMap: { EventSourceMappingUUID: eventSourceMappingId },
+        statistic: aws_cloudwatch_1.Stats.SUM,
+        period: METRIC_PERIOD,
+    });
+}
+/**
+ * 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
+ */
+function createFunctionAlarms(scope, id, fn, config, props, eventSources = [], customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? alarm_defaults_js_1.FUNCTION_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveFunctionAlarmDefinitions(fn, config, props, eventSources);
+    const custom = customAlarms.map((b) => b.resolve(fn));
+    return (0, cloudwatch_1.createAlarms)(scope, id, [...recommended, ...custom]);
+}
+/**
+ * Resolves a percentage-based alarm config by layering user overrides
+ * onto the defaults.
+ */
+function resolvePercentageAlarmConfig(userConfig, defaults) {
+    const thresholdPercent = userConfig?.thresholdPercent ?? defaults.thresholdPercent;
+    if (thresholdPercent <= 0 || thresholdPercent > 1) {
+        throw new Error(`thresholdPercent must be between 0 (exclusive) and 1 (inclusive), got ${String(thresholdPercent)}.`);
+    }
+    return {
+        alarmName: userConfig?.alarmName,
+        thresholdPercent,
+        evaluationPeriods: userConfig?.evaluationPeriods ?? defaults.evaluationPeriods,
+        datapointsToAlarm: userConfig?.datapointsToAlarm ?? defaults.datapointsToAlarm,
+        treatMissingData: userConfig?.treatMissingData ?? defaults.treatMissingData,
+    };
+}
+//# sourceMappingURL=function-alarms.js.map

package/dist/commonjs/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/commonjs/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/commonjs/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"}