alchemy 2.0.0-beta.56 → 2.0.0-beta.57

package/lib/AWS/Lambda/EventSourceMapping.d.ts

@@ -154,6 +154,317 @@ export interface EventSourceMapping extends Resource<"AWS.Lambda.EventSourceMapp
     state: string;
 }, never, Providers> {
 }
+/**
+ * Connects an event source — an SQS queue, Kinesis stream, DynamoDB stream,
+ * Amazon MQ broker, or Kafka topic — to a Lambda function so that records are
+ * polled from the source and delivered to the function in batches.
+ *
+ * Most stacks create mappings indirectly through the higher-level event-source
+ * helpers (`SQS.messages(queue).subscribe(...)`,
+ * `Kinesis.events(stream).process(...)`, `DynamoDB.streams(table).process(...)`),
+ * which wire up the matching IAM permissions automatically. Use this resource
+ * directly when you need full control over batching, starting position, retry
+ * behavior, or filtering.
+ *
+ * @resource
+ * @section Polling an SQS Queue
+ * SQS is the simplest source: no `startingPosition` is needed because there is
+ * no stream cursor. Lambda long-polls the queue and invokes the function with
+ * up to `batchSize` messages, and `functionName` plus `eventSourceArn` are the
+ * only required props.
+ *
+ * @example Subscribe a function to a queue
+ * ```typescript
+ * import * as AWS from "alchemy/AWS";
+ *
+ * const queue = yield* AWS.SQS.Queue("Jobs", {});
+ * const worker = yield* AWS.Lambda.Function("Worker", {
+ *   main: "./src/worker.ts",
+ * });
+ *
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("JobsToWorker", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: queue.queueArn,
+ *   batchSize: 10,
+ *   maximumBatchingWindowInSeconds: 5,
+ * });
+ * ```
+ *
+ * This delivers up to 10 messages per invocation, waiting up to 5 seconds to
+ * fill a batch before invoking. Increasing the batching window trades latency
+ * for fewer, larger invocations — useful for amortizing cold starts or
+ * downstream write costs on bursty queues.
+ *
+ * @section Streaming from Kinesis & DynamoDB
+ * Stream sources (Kinesis and DynamoDB Streams) deliver records in shard order
+ * and therefore require a `startingPosition` that tells Lambda where in the
+ * shard to begin reading. These sources also unlock the stream-only tuning
+ * knobs covered in the next sections.
+ *
+ * @example Process a Kinesis stream from the latest records
+ * ```typescript
+ * import * as AWS from "alchemy/AWS";
+ *
+ * const stream = yield* AWS.Kinesis.Stream("Events", {});
+ * const consumer = yield* AWS.Lambda.Function("Consumer", {
+ *   main: "./src/consumer.ts",
+ * });
+ *
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("EventsToConsumer", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   startingPosition: "LATEST",
+ *   batchSize: 100,
+ * });
+ * ```
+ *
+ * `startingPosition: "LATEST"` skips any backlog and only processes records
+ * written after the mapping is created — the right choice for live event
+ * pipelines where replaying history would be wasteful or incorrect.
+ *
+ * @example Replay a DynamoDB stream from the beginning
+ * ```typescript
+ * import * as AWS from "alchemy/AWS";
+ *
+ * const table = yield* AWS.DynamoDB.Table("Orders", {
+ *   partitionKey: { name: "id", type: "S" },
+ * });
+ * const handler = yield* AWS.Lambda.Function("OrdersStream", {
+ *   main: "./src/orders.ts",
+ * });
+ *
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("OrdersToHandler", {
+ *   functionName: handler.functionName,
+ *   eventSourceArn: table.latestStreamArn!,
+ *   startingPosition: "TRIM_HORIZON",
+ * });
+ * ```
+ *
+ * `TRIM_HORIZON` starts at the oldest record still in the stream, so the
+ * function processes the full available history before catching up to new
+ * writes — use it when every change matters (e.g. building a projection).
+ *
+ * @example Start reading from a specific timestamp
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("EventsFromTime", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   startingPosition: "AT_TIMESTAMP",
+ *   startingPositionTimestamp: new Date("2026-01-01T00:00:00Z"),
+ * });
+ * ```
+ *
+ * `AT_TIMESTAMP` (Kinesis only) begins at the first record on or after
+ * `startingPositionTimestamp`, letting you reprocess a known time range without
+ * replaying the entire stream.
+ *
+ * @section Tuning Throughput
+ * For stream sources, throughput is governed by how records are batched and how
+ * many batches run in parallel per shard. These knobs let you balance
+ * end-to-end latency against invocation count and downstream load.
+ *
+ * @example Increase parallelism and use tumbling windows
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("HighThroughput", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   startingPosition: "LATEST",
+ *   batchSize: 500,
+ *   maximumBatchingWindowInSeconds: 10,
+ *   parallelizationFactor: 5,
+ *   tumblingWindowInSeconds: 30,
+ * });
+ * ```
+ *
+ * `parallelizationFactor` runs up to 5 concurrent batches per shard (records
+ * with the same partition key still stay in order), while
+ * `tumblingWindowInSeconds` aggregates results across sequential batches for
+ * windowed stream processing. Raising `batchSize`/`maximumBatchingWindowInSeconds`
+ * favors fewer, larger invocations.
+ *
+ * @section Error Handling & Retries
+ * For stream sources a single poison-pill record can block a shard forever.
+ * These props bound retries, split failing batches, expire stale records, and
+ * route failures elsewhere instead of stalling the stream.
+ *
+ * @example Bisect on error, cap retries, and expire old records
+ * ```typescript
+ * const dlq = yield* AWS.SQS.Queue("StreamFailures", {});
+ *
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("ResilientStream", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   startingPosition: "LATEST",
+ *   bisectBatchOnFunctionError: true,
+ *   maximumRetryAttempts: 3,
+ *   maximumRecordAgeInSeconds: 3600,
+ *   destinationConfig: {
+ *     OnFailure: { Destination: dlq.queueArn },
+ *   },
+ * });
+ * ```
+ *
+ * On a function error, `bisectBatchOnFunctionError` splits the batch in two and
+ * retries each half to isolate the bad record; after `maximumRetryAttempts` (or
+ * once a record is older than `maximumRecordAgeInSeconds`) the record is
+ * discarded and its metadata is sent to the `destinationConfig.OnFailure`
+ * target so it is never silently lost.
+ *
+ * @example Report partial batch failures
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("PartialFailures", {
+ *   functionName: handler.functionName,
+ *   eventSourceArn: table.latestStreamArn!,
+ *   startingPosition: "TRIM_HORIZON",
+ *   functionResponseTypes: ["ReportBatchItemFailures"],
+ * });
+ * ```
+ *
+ * `functionResponseTypes: ["ReportBatchItemFailures"]` lets the function return
+ * only the IDs of records it failed to process, so Lambda retries just those
+ * instead of the whole batch — avoiding redundant reprocessing of records that
+ * already succeeded.
+ *
+ * @section Filtering Records
+ * Attach `filterCriteria` so the function is only invoked for records matching
+ * an event pattern. Filtering happens before invocation, so it cuts both cost
+ * and unnecessary cold starts. Encrypt the patterns with `kmsKeyArn` when they
+ * contain sensitive values.
+ *
+ * @example Only deliver records where `type` is `"order"`
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("OrdersOnly", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: queue.queueArn,
+ *   filterCriteria: {
+ *     Filters: [{ Pattern: JSON.stringify({ body: { type: ["order"] } }) }],
+ *   },
+ *   kmsKeyArn:
+ *     "arn:aws:kms:us-east-1:111122223333:key/abcd1234-...",
+ * });
+ * ```
+ *
+ * Each `Pattern` is a JSON event-pattern string; messages that don't match are
+ * dropped without invoking the function. The optional `kmsKeyArn` encrypts the
+ * stored filter criteria with your own KMS key instead of an AWS-managed one.
+ *
+ * @section Enabling & Disabling
+ * The `enabled` flag controls whether Lambda actively polls the source without
+ * deleting the mapping, so you can pause and resume delivery in place.
+ *
+ * @example Create a paused mapping
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("PausedConsumer", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   startingPosition: "LATEST",
+ *   enabled: false,
+ * });
+ * ```
+ *
+ * With `enabled: false` the mapping exists but pulls no records — flip it back
+ * to `true` to resume. This is handy for maintenance windows or for staging a
+ * consumer before turning on traffic.
+ *
+ * @section Scaling & Provisioned Pollers
+ * Cap concurrency for SQS sources with `scalingConfig`, or reserve dedicated
+ * polling capacity (for Kafka/MSK and SQS) with `provisionedPollerConfig` to
+ * keep latency predictable under load.
+ *
+ * @example Limit SQS concurrency and provision pollers
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("BoundedConsumer", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: queue.queueArn,
+ *   scalingConfig: { MaximumConcurrency: 10 },
+ *   provisionedPollerConfig: {
+ *     MinimumPollers: 1,
+ *     MaximumPollers: 20,
+ *   },
+ * });
+ * ```
+ *
+ * `scalingConfig.MaximumConcurrency` caps how many function instances Lambda
+ * runs for this queue (protecting downstream systems), while
+ * `provisionedPollerConfig` keeps a pool of dedicated event pollers warm so
+ * throughput doesn't lag behind sudden spikes.
+ *
+ * @section Kafka, MQ & DocumentDB Sources
+ * Beyond AWS-native streams, an event source mapping can poll Amazon MSK,
+ * self-managed Apache Kafka, Amazon MQ brokers, and Amazon DocumentDB change
+ * streams. These sources use `topics`/`queues` to select what to consume,
+ * `sourceAccessConfigurations` for VPC and authentication wiring, and
+ * source-specific config props.
+ *
+ * @example Consume a self-managed Kafka topic
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("KafkaConsumer", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   topics: ["orders"],
+ *   selfManagedEventSource: {
+ *     Endpoints: { KAFKA_BOOTSTRAP_SERVERS: ["broker1:9092", "broker2:9092"] },
+ *   },
+ *   selfManagedKafkaEventSourceConfig: { ConsumerGroupId: "orders-consumer" },
+ *   sourceAccessConfigurations: [
+ *     { Type: "SASL_SCRAM_512_AUTH", URI: "arn:aws:secretsmanager:...:secret:kafka" },
+ *   ],
+ *   loggingConfig: { LogFormat: "JSON" },
+ * });
+ * ```
+ *
+ * `topics` names the Kafka topic(s) to read; `selfManagedEventSource.Endpoints`
+ * points at the brokers; `sourceAccessConfigurations` supplies the SASL/VPC
+ * credentials; and `selfManagedKafkaEventSourceConfig.ConsumerGroupId` pins the
+ * consumer group. For Amazon MSK use `amazonManagedKafkaEventSourceConfig`
+ * instead.
+ *
+ * @example Consume an Amazon MQ queue and a DocumentDB change stream
+ * ```typescript
+ * const mqMapping = yield* AWS.Lambda.EventSourceMapping("MqConsumer", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   queues: ["orders-queue"],
+ *   sourceAccessConfigurations: [
+ *     { Type: "BASIC_AUTH", URI: "arn:aws:secretsmanager:...:secret:mq" },
+ *   ],
+ * });
+ *
+ * const docDbMapping = yield* AWS.Lambda.EventSourceMapping("DocDbConsumer", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   documentDBEventSourceConfig: {
+ *     DatabaseName: "shop",
+ *     CollectionName: "orders",
+ *     FullDocument: "UpdateLookup",
+ *   },
+ * });
+ * ```
+ *
+ * For Amazon MQ, `queues` names the broker destination to consume and
+ * `sourceAccessConfigurations` carries the broker credentials; for DocumentDB,
+ * `documentDBEventSourceConfig` selects the database/collection and whether full
+ * documents are delivered on updates.
+ *
+ * @section Metrics & Tags
+ * Opt into per-mapping CloudWatch metrics with `metricsConfig` and brand the
+ * mapping with your own `tags` (Alchemy also applies its internal ownership
+ * tags automatically).
+ *
+ * @example Enable event metrics and add tags
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("ObservedConsumer", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: queue.queueArn,
+ *   metricsConfig: { Metrics: ["EventCount"] },
+ *   tags: { team: "payments", env: "prod" },
+ * });
+ * ```
+ *
+ * `metricsConfig.Metrics` turns on the named CloudWatch metrics (e.g.
+ * `EventCount`) for this mapping, and `tags` attaches arbitrary key/value pairs
+ * for cost allocation and discovery.
+ */
 export declare const EventSourceMapping: import("../../Resource.ts").ResourceClass<EventSourceMapping>;
 export declare const EventSourceMappingProvider: () => import("effect/Layer").Layer<Provider.Provider<EventSourceMapping>, never, AWSEnvironment | import("@distilled.cloud/aws/Credentials").Credentials | import("effect/unstable/http/HttpClient").HttpClient | import("@distilled.cloud/aws/Region").Region | import("../../Stack.ts").Stack | import("../../Stage.ts").Stage>;
 //# sourceMappingURL=EventSourceMapping.d.ts.map

package/lib/AWS/Lambda/EventSourceMapping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EventSourceMapping.d.ts","sourceRoot":"","sources":["../../../src/AWS/Lambda/EventSourceMapping.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EventSourceMapping.d.ts","sourceRoot":"","sources":["../../../src/AWS/Lambda/EventSourceMapping.ts"],"names":[],"mappings":"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"}

package/lib/AWS/Lambda/EventSourceMapping.js

@@ -8,6 +8,317 @@ import * as Provider from "../../Provider.js";
 import { Resource } from "../../Resource.js";
 import { createInternalTags, diffTags, hasTags } from "../../Tags.js";
 import { AWSEnvironment } from "../Environment.js";
+/**
+ * Connects an event source — an SQS queue, Kinesis stream, DynamoDB stream,
+ * Amazon MQ broker, or Kafka topic — to a Lambda function so that records are
+ * polled from the source and delivered to the function in batches.
+ *
+ * Most stacks create mappings indirectly through the higher-level event-source
+ * helpers (`SQS.messages(queue).subscribe(...)`,
+ * `Kinesis.events(stream).process(...)`, `DynamoDB.streams(table).process(...)`),
+ * which wire up the matching IAM permissions automatically. Use this resource
+ * directly when you need full control over batching, starting position, retry
+ * behavior, or filtering.
+ *
+ * @resource
+ * @section Polling an SQS Queue
+ * SQS is the simplest source: no `startingPosition` is needed because there is
+ * no stream cursor. Lambda long-polls the queue and invokes the function with
+ * up to `batchSize` messages, and `functionName` plus `eventSourceArn` are the
+ * only required props.
+ *
+ * @example Subscribe a function to a queue
+ * ```typescript
+ * import * as AWS from "alchemy/AWS";
+ *
+ * const queue = yield* AWS.SQS.Queue("Jobs", {});
+ * const worker = yield* AWS.Lambda.Function("Worker", {
+ *   main: "./src/worker.ts",
+ * });
+ *
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("JobsToWorker", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: queue.queueArn,
+ *   batchSize: 10,
+ *   maximumBatchingWindowInSeconds: 5,
+ * });
+ * ```
+ *
+ * This delivers up to 10 messages per invocation, waiting up to 5 seconds to
+ * fill a batch before invoking. Increasing the batching window trades latency
+ * for fewer, larger invocations — useful for amortizing cold starts or
+ * downstream write costs on bursty queues.
+ *
+ * @section Streaming from Kinesis & DynamoDB
+ * Stream sources (Kinesis and DynamoDB Streams) deliver records in shard order
+ * and therefore require a `startingPosition` that tells Lambda where in the
+ * shard to begin reading. These sources also unlock the stream-only tuning
+ * knobs covered in the next sections.
+ *
+ * @example Process a Kinesis stream from the latest records
+ * ```typescript
+ * import * as AWS from "alchemy/AWS";
+ *
+ * const stream = yield* AWS.Kinesis.Stream("Events", {});
+ * const consumer = yield* AWS.Lambda.Function("Consumer", {
+ *   main: "./src/consumer.ts",
+ * });
+ *
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("EventsToConsumer", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   startingPosition: "LATEST",
+ *   batchSize: 100,
+ * });
+ * ```
+ *
+ * `startingPosition: "LATEST"` skips any backlog and only processes records
+ * written after the mapping is created — the right choice for live event
+ * pipelines where replaying history would be wasteful or incorrect.
+ *
+ * @example Replay a DynamoDB stream from the beginning
+ * ```typescript
+ * import * as AWS from "alchemy/AWS";
+ *
+ * const table = yield* AWS.DynamoDB.Table("Orders", {
+ *   partitionKey: { name: "id", type: "S" },
+ * });
+ * const handler = yield* AWS.Lambda.Function("OrdersStream", {
+ *   main: "./src/orders.ts",
+ * });
+ *
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("OrdersToHandler", {
+ *   functionName: handler.functionName,
+ *   eventSourceArn: table.latestStreamArn!,
+ *   startingPosition: "TRIM_HORIZON",
+ * });
+ * ```
+ *
+ * `TRIM_HORIZON` starts at the oldest record still in the stream, so the
+ * function processes the full available history before catching up to new
+ * writes — use it when every change matters (e.g. building a projection).
+ *
+ * @example Start reading from a specific timestamp
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("EventsFromTime", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   startingPosition: "AT_TIMESTAMP",
+ *   startingPositionTimestamp: new Date("2026-01-01T00:00:00Z"),
+ * });
+ * ```
+ *
+ * `AT_TIMESTAMP` (Kinesis only) begins at the first record on or after
+ * `startingPositionTimestamp`, letting you reprocess a known time range without
+ * replaying the entire stream.
+ *
+ * @section Tuning Throughput
+ * For stream sources, throughput is governed by how records are batched and how
+ * many batches run in parallel per shard. These knobs let you balance
+ * end-to-end latency against invocation count and downstream load.
+ *
+ * @example Increase parallelism and use tumbling windows
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("HighThroughput", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   startingPosition: "LATEST",
+ *   batchSize: 500,
+ *   maximumBatchingWindowInSeconds: 10,
+ *   parallelizationFactor: 5,
+ *   tumblingWindowInSeconds: 30,
+ * });
+ * ```
+ *
+ * `parallelizationFactor` runs up to 5 concurrent batches per shard (records
+ * with the same partition key still stay in order), while
+ * `tumblingWindowInSeconds` aggregates results across sequential batches for
+ * windowed stream processing. Raising `batchSize`/`maximumBatchingWindowInSeconds`
+ * favors fewer, larger invocations.
+ *
+ * @section Error Handling & Retries
+ * For stream sources a single poison-pill record can block a shard forever.
+ * These props bound retries, split failing batches, expire stale records, and
+ * route failures elsewhere instead of stalling the stream.
+ *
+ * @example Bisect on error, cap retries, and expire old records
+ * ```typescript
+ * const dlq = yield* AWS.SQS.Queue("StreamFailures", {});
+ *
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("ResilientStream", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   startingPosition: "LATEST",
+ *   bisectBatchOnFunctionError: true,
+ *   maximumRetryAttempts: 3,
+ *   maximumRecordAgeInSeconds: 3600,
+ *   destinationConfig: {
+ *     OnFailure: { Destination: dlq.queueArn },
+ *   },
+ * });
+ * ```
+ *
+ * On a function error, `bisectBatchOnFunctionError` splits the batch in two and
+ * retries each half to isolate the bad record; after `maximumRetryAttempts` (or
+ * once a record is older than `maximumRecordAgeInSeconds`) the record is
+ * discarded and its metadata is sent to the `destinationConfig.OnFailure`
+ * target so it is never silently lost.
+ *
+ * @example Report partial batch failures
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("PartialFailures", {
+ *   functionName: handler.functionName,
+ *   eventSourceArn: table.latestStreamArn!,
+ *   startingPosition: "TRIM_HORIZON",
+ *   functionResponseTypes: ["ReportBatchItemFailures"],
+ * });
+ * ```
+ *
+ * `functionResponseTypes: ["ReportBatchItemFailures"]` lets the function return
+ * only the IDs of records it failed to process, so Lambda retries just those
+ * instead of the whole batch — avoiding redundant reprocessing of records that
+ * already succeeded.
+ *
+ * @section Filtering Records
+ * Attach `filterCriteria` so the function is only invoked for records matching
+ * an event pattern. Filtering happens before invocation, so it cuts both cost
+ * and unnecessary cold starts. Encrypt the patterns with `kmsKeyArn` when they
+ * contain sensitive values.
+ *
+ * @example Only deliver records where `type` is `"order"`
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("OrdersOnly", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: queue.queueArn,
+ *   filterCriteria: {
+ *     Filters: [{ Pattern: JSON.stringify({ body: { type: ["order"] } }) }],
+ *   },
+ *   kmsKeyArn:
+ *     "arn:aws:kms:us-east-1:111122223333:key/abcd1234-...",
+ * });
+ * ```
+ *
+ * Each `Pattern` is a JSON event-pattern string; messages that don't match are
+ * dropped without invoking the function. The optional `kmsKeyArn` encrypts the
+ * stored filter criteria with your own KMS key instead of an AWS-managed one.
+ *
+ * @section Enabling & Disabling
+ * The `enabled` flag controls whether Lambda actively polls the source without
+ * deleting the mapping, so you can pause and resume delivery in place.
+ *
+ * @example Create a paused mapping
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("PausedConsumer", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   startingPosition: "LATEST",
+ *   enabled: false,
+ * });
+ * ```
+ *
+ * With `enabled: false` the mapping exists but pulls no records — flip it back
+ * to `true` to resume. This is handy for maintenance windows or for staging a
+ * consumer before turning on traffic.
+ *
+ * @section Scaling & Provisioned Pollers
+ * Cap concurrency for SQS sources with `scalingConfig`, or reserve dedicated
+ * polling capacity (for Kafka/MSK and SQS) with `provisionedPollerConfig` to
+ * keep latency predictable under load.
+ *
+ * @example Limit SQS concurrency and provision pollers
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("BoundedConsumer", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: queue.queueArn,
+ *   scalingConfig: { MaximumConcurrency: 10 },
+ *   provisionedPollerConfig: {
+ *     MinimumPollers: 1,
+ *     MaximumPollers: 20,
+ *   },
+ * });
+ * ```
+ *
+ * `scalingConfig.MaximumConcurrency` caps how many function instances Lambda
+ * runs for this queue (protecting downstream systems), while
+ * `provisionedPollerConfig` keeps a pool of dedicated event pollers warm so
+ * throughput doesn't lag behind sudden spikes.
+ *
+ * @section Kafka, MQ & DocumentDB Sources
+ * Beyond AWS-native streams, an event source mapping can poll Amazon MSK,
+ * self-managed Apache Kafka, Amazon MQ brokers, and Amazon DocumentDB change
+ * streams. These sources use `topics`/`queues` to select what to consume,
+ * `sourceAccessConfigurations` for VPC and authentication wiring, and
+ * source-specific config props.
+ *
+ * @example Consume a self-managed Kafka topic
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("KafkaConsumer", {
+ *   functionName: consumer.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   topics: ["orders"],
+ *   selfManagedEventSource: {
+ *     Endpoints: { KAFKA_BOOTSTRAP_SERVERS: ["broker1:9092", "broker2:9092"] },
+ *   },
+ *   selfManagedKafkaEventSourceConfig: { ConsumerGroupId: "orders-consumer" },
+ *   sourceAccessConfigurations: [
+ *     { Type: "SASL_SCRAM_512_AUTH", URI: "arn:aws:secretsmanager:...:secret:kafka" },
+ *   ],
+ *   loggingConfig: { LogFormat: "JSON" },
+ * });
+ * ```
+ *
+ * `topics` names the Kafka topic(s) to read; `selfManagedEventSource.Endpoints`
+ * points at the brokers; `sourceAccessConfigurations` supplies the SASL/VPC
+ * credentials; and `selfManagedKafkaEventSourceConfig.ConsumerGroupId` pins the
+ * consumer group. For Amazon MSK use `amazonManagedKafkaEventSourceConfig`
+ * instead.
+ *
+ * @example Consume an Amazon MQ queue and a DocumentDB change stream
+ * ```typescript
+ * const mqMapping = yield* AWS.Lambda.EventSourceMapping("MqConsumer", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   queues: ["orders-queue"],
+ *   sourceAccessConfigurations: [
+ *     { Type: "BASIC_AUTH", URI: "arn:aws:secretsmanager:...:secret:mq" },
+ *   ],
+ * });
+ *
+ * const docDbMapping = yield* AWS.Lambda.EventSourceMapping("DocDbConsumer", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: stream.streamArn,
+ *   documentDBEventSourceConfig: {
+ *     DatabaseName: "shop",
+ *     CollectionName: "orders",
+ *     FullDocument: "UpdateLookup",
+ *   },
+ * });
+ * ```
+ *
+ * For Amazon MQ, `queues` names the broker destination to consume and
+ * `sourceAccessConfigurations` carries the broker credentials; for DocumentDB,
+ * `documentDBEventSourceConfig` selects the database/collection and whether full
+ * documents are delivered on updates.
+ *
+ * @section Metrics & Tags
+ * Opt into per-mapping CloudWatch metrics with `metricsConfig` and brand the
+ * mapping with your own `tags` (Alchemy also applies its internal ownership
+ * tags automatically).
+ *
+ * @example Enable event metrics and add tags
+ * ```typescript
+ * const mapping = yield* AWS.Lambda.EventSourceMapping("ObservedConsumer", {
+ *   functionName: worker.functionName,
+ *   eventSourceArn: queue.queueArn,
+ *   metricsConfig: { Metrics: ["EventCount"] },
+ *   tags: { team: "payments", env: "prod" },
+ * });
+ * ```
+ *
+ * `metricsConfig.Metrics` turns on the named CloudWatch metrics (e.g.
+ * `EventCount`) for this mapping, and `tags` attaches arbitrary key/value pairs
+ * for cost allocation and discovery.
+ */
 export const EventSourceMapping = Resource("AWS.Lambda.EventSourceMapping");
 export const EventSourceMappingProvider = () => Provider.effect(EventSourceMapping, Effect.gen(function* () {
     const createEventSourceMappingTags = Effect.fn(function* (id) {