@kensio/yulin 1.21.7 → 1.21.9

package/README.md

@@ -66,6 +66,7 @@ npm i -D @kensio/yulin
 - [Non-AWS dependencies](https://yulinsim.dev/non-aws-dependencies/ "Dependencies Yulin does not simulate docs")
 - [Serving on localhost](https://yulinsim.dev/serve/ "Serving simulated AWS on localhost docs")
 - [Simulated time](https://yulinsim.dev/time/ "Simulated time docs")
+- [Test suite setup](https://yulinsim.dev/testing/ "Sharing one Yulin environment across a test suite")
 - [Terraform](https://yulinsim.dev/terraform/ "Deploying Terraform into simulated AWS docs")
 
 Every page listed above also ships inside the package as markdown, documenting the version
@@ -74,6 +75,24 @@ reach can read them from there.
 
 ## Usage
 
+### Set up Yulin once for the test suite
+
+An application test suite should normally create one Yulin environment in its Vitest setup. Install
+SDK interception and deploy the application's simulated infrastructure there, then let every test
+use that state. Treat the environment like an AWS account or a LocalStack container that belongs to
+the suite.
+
+Keep tests independent by giving their records and resources unique names. A fresh `SimAws` or
+`SimSdk` for every test or test file is supported, but it is intended for cases that specifically
+need an empty simulated account.
+
+The simulated clock is shared too. Most tests should leave it alone and use the suite environment.
+Put tests that call `freeze()`, `setTo(...)`, `advanceBy(...)`, or `resume()` in a separate group with
+a fresh Yulin environment for each test.
+
+The [test suite setup guide](https://yulinsim.dev/testing/ "Sharing one Yulin environment across a test suite")
+shows the Vitest configuration, shared deployment, and SDK interception.
+
 ### Intercept AWS SDK clients
 
 If your code uses the AWS SDK, you can intercept its clients and route their Commands to simulated
@@ -166,8 +185,9 @@ const accountId = simAwsAccountId("111111111111");
 const someOtherAccountId = makeSimAwsAccountId();
 ```
 
-Each instance of `SimAws` is cheap and encapsulated. Make one wherever you need it, in every test
-case or in shared test setup, whichever suits.
+Each instance of `SimAws` is encapsulated. Application tests should usually share one instance from
+suite setup. Create another instance when a test needs a separate simulated account with no shared
+state.
 
 If you prefer, you can also instantiate simulated services individually:
 

package/dist/service/lambda/cfn/event-source-mapping/sim-cfn-lambda-event-source-mapping-properties.js

@@ -1,3 +1,4 @@
+import { simLambdaStreamDestinationConfig } from "../../event-source/sim-lambda-stream-destination-config.js";
 import { SimCfnLambdaPropertyParser } from "../function/sim-cfn-lambda-property-parser.js";
 import { assertSimulatedEventSourceMappingProperties } from "./sim-cfn-lambda-event-source-mapping-property-rules.js";
 import { simCfnLambdaTargetFunctionName } from "../function/sim-cfn-lambda-target-function.js";
@@ -34,6 +35,7 @@ export class SimCfnLambdaEventSourceMappingProperties {
         assertSimulatedEventSourceMappingProperties(this.resource, this.properties);
         return {
             EventSourceArn: eventSourceArn,
+            DestinationConfig: simLambdaStreamDestinationConfig(this.properties["DestinationConfig"]),
             FunctionName: simCfnLambdaTargetFunctionName(this.parser.requiredString(this.resource, this.properties["FunctionName"], "FunctionName")),
             BatchSize: this.parser.optionalNumber(this.resource, this.properties["BatchSize"], "BatchSize"),
             Enabled: this.parser.optionalBoolean(this.resource, this.properties["Enabled"], "Enabled"),

package/dist/service/lambda/cfn/event-source-mapping/sim-cfn-lambda-event-source-mapping-property-rules.js

@@ -18,6 +18,7 @@ const simulatedPropertyNames = new Set([
     "MaximumBatchingWindowInSeconds",
     "MaximumRecordAgeInSeconds",
     "MaximumRetryAttempts",
+    "DestinationConfig",
     "StartingPosition",
     "StartingPositionTimestamp",
 ]);
@@ -32,7 +33,6 @@ const simulatedPropertyNames = new Set([
 const unsimulatedPropertyNames = new Set([
     "AmazonManagedKafkaEventSourceConfig",
     "BisectBatchOnFunctionError",
-    "DestinationConfig",
     "DocumentDBEventSourceConfig",
     "FilterCriteria",
     "KmsKeyArn",

package/dist/service/lambda/command/event-source-mapping/create-event-source-mapping-input.d.ts

@@ -1,3 +1,4 @@
+import { type SimLambdaStreamDestinationConfiguration } from "../../event-source/sim-lambda-stream-destination-config.js";
 import type { SimAwsAccountRegionScope } from "../../../aws/sim-aws-account-region-scope.js";
 import { type SimLambdaEventSourceArn } from "../../event-source/sim-lambda-event-source-arn.js";
 import type { SimLambdaFunctionResponseType } from "../../event-source/sim-lambda-event-source-mapping.js";
@@ -29,6 +30,7 @@ export declare class SimLambdaEventSourceMappingInput {
     readonly start: SimLambdaEventSourceStart | undefined;
     readonly enabled: boolean;
     readonly functionResponseTypes: readonly SimLambdaFunctionResponseType[];
+    readonly destinationConfig: SimLambdaStreamDestinationConfiguration | undefined;
     /**
      * When a failed batch stops being delivered again, for a source that leaves
      * the counting to the mapping.

package/dist/service/lambda/command/event-source-mapping/create-event-source-mapping-input.js

@@ -1,3 +1,4 @@
+import { simLambdaStreamDestinationConfig, } from "../../event-source/sim-lambda-stream-destination-config.js";
 import { simLambdaEventSourceArnOf, } from "../../event-source/sim-lambda-event-source-arn.js";
 import { SimLambdaInvalidParameterValueException } from "../../error/sim-lambda.error.js";
 import { simLambdaFunctionReferenceOf } from "../../function/sim-lambda-function-reference.js";
@@ -28,6 +29,7 @@ export class SimLambdaEventSourceMappingInput {
     start;
     enabled;
     functionResponseTypes;
+    destinationConfig;
     /**
      * When a failed batch stops being delivered again, for a source that leaves
      * the counting to the mapping.
@@ -41,6 +43,7 @@ export class SimLambdaEventSourceMappingInput {
         this.start = properties.start;
         this.enabled = properties.enabled;
         this.functionResponseTypes = properties.functionResponseTypes;
+        this.destinationConfig = properties.destinationConfig;
         this.streamRetryLimits = properties.streamRetryLimits;
     }
     /**
@@ -53,6 +56,7 @@ export class SimLambdaEventSourceMappingInput {
         refuseUnsimulatedInput(input);
         return new this({
             eventSourceArn,
+            destinationConfig: simLambdaStreamDestinationConfig(input.DestinationConfig, eventSourceArn.kind),
             ...simLambdaFunctionReferenceOf(requiredString(input.FunctionName, "functionName")),
             batchSize: eventSourceArn.batchRules.sizeIn(input.BatchSize),
             start: eventSourceArn.startingPositionRules.startIn({

package/dist/service/lambda/command/event-source-mapping/create-event-source-mapping-refusals.js

@@ -12,11 +12,6 @@ const unsimulatedInputs = new Map([
     ["FilterCriteria", "event filtering is not simulated"],
     ["ScalingConfig", "polling concurrency is not simulated"],
     ["ProvisionedPollerConfig", "polling concurrency is not simulated"],
-    [
-        "DestinationConfig",
-        "failure destinations are not simulated, so a stream batch that runs out " +
-            "of attempts is discarded rather than sent anywhere",
-    ],
     [
         "BisectBatchOnFunctionError",
         "batch bisection is not simulated, so a failing stream batch is retried " +

package/dist/service/lambda/command/event-source-mapping/create-event-source-mapping.handler.d.ts

@@ -1,3 +1,4 @@
+import type { SimLambdaDestinationTargets } from "../../destination/sim-lambda-destination-targets.js";
 import type { CommandHandler } from "../../../../command/command-handler.js";
 import type { BackgroundScheduler } from "../../../../util/background/background.js";
 import type { SimAwsCaller } from "../../../aws/caller/sim-aws-caller.js";
@@ -19,6 +20,7 @@ interface CreateEventSourceMappingCommandHandlerProperties {
     readonly kinesisStreams: SimLambdaKinesisStreams;
     readonly functions: SimLambdaFunctionLookup;
     readonly iam: SimIamInterServiceAuthZ;
+    readonly destinations?: SimLambdaDestinationTargets;
     readonly background: BackgroundScheduler;
 }
 interface CreateEventSourceMappingCommandHandlerOptions {

package/dist/service/lambda/command/event-source-mapping/create-event-source-mapping.handler.js

@@ -81,6 +81,8 @@ export class CreateEventSourceMappingCommandHandler {
             enabled: input.enabled,
             functionResponseTypes: input.functionResponseTypes,
             streamRetryLimits: input.streamRetryLimits,
+            destinationConfig: input.destinationConfig,
+            destinations: this.properties.destinations,
             createdAt: this.properties.background.now(),
         });
         this.properties.mappings.add(mapping);

package/dist/service/lambda/command/event-source-mapping/sim-lambda-event-source-mapping-commands.d.ts

@@ -1,3 +1,4 @@
+import type { SimLambdaDestinationTargets } from "../../destination/sim-lambda-destination-targets.js";
 import type { BackgroundScheduler } from "../../../../util/background/background.js";
 import type { SimAwsCaller } from "../../../aws/caller/sim-aws-caller.js";
 import type { SimAwsAccountRegionScope } from "../../../aws/sim-aws-account-region-scope.js";
@@ -17,6 +18,7 @@ interface SimLambdaEventSourceMappingCommandsProperties {
     readonly kinesisStreams: SimLambdaKinesisStreams;
     readonly functions: SimLambdaFunctionLookup;
     readonly iam: SimIamInterServiceAuthZ;
+    readonly destinations?: SimLambdaDestinationTargets;
     readonly background: BackgroundScheduler;
 }
 interface SimLambdaEventSourceMappingCommandOptions {

package/dist/service/lambda/destination/sim-lambda-destination-targets.d.ts

@@ -1,3 +1,4 @@
+import type { SimLambdaStreamFailureRecord } from "../event-source/poll/sim-lambda-stream-failure-record.js";
 import type { SimLambdaDestinationArn } from "./sim-lambda-destination-arn.js";
 import type { SimLambdaDestinationRecord } from "./sim-lambda-destination-record.js";
 /**
@@ -5,7 +6,7 @@ import type { SimLambdaDestinationRecord } from "./sim-lambda-destination-record
  */
 export interface SimLambdaDestinationDeliveryRequest {
     readonly destinationArn: SimLambdaDestinationArn;
-    readonly record: SimLambdaDestinationRecord;
+    readonly record: SimLambdaDestinationRecord | SimLambdaStreamFailureRecord;
     /**
      * The function whose invocation produced this record, which is what the
      * delivery is attributed to.

package/dist/service/lambda/event-source/poll/kinesis/sim-lambda-kinesis-shard-poller.d.ts

@@ -49,9 +49,5 @@ export declare class SimLambdaKinesisShardPoller implements SimLambdaEventSource
      * reading the same records.
      */
     poll(): Promise<void>;
-    /**
-     * The function this mapping delivers to, while it should be delivering.
-     */
-    private pollingFunction;
 }
 export {};

package/dist/service/lambda/event-source/poll/kinesis/sim-lambda-kinesis-shard-poller.js

@@ -1,3 +1,5 @@
+import { processSimLambdaStreamBatch } from "../sim-lambda-stream-batch-processing.js";
+import { simLambdaKinesisStreamRecordTimes } from "../sim-lambda-stream-record-times.js";
 import { simLambdaEventSourceFunction } from "../sim-lambda-event-source-function.js";
 import { SimLambdaEventSourcePollTurn, } from "../sim-lambda-event-source-poll-turn.js";
 import { SimLambdaStreamProgress } from "../sim-lambda-stream-progress.js";
@@ -57,7 +59,7 @@ export class SimLambdaKinesisShardPoller {
      * reading the same records.
      */
     async poll() {
-        const simFunction = this.pollingFunction();
+        const simFunction = simLambdaEventSourceFunction(this.functions, this.mapping, this.stopped);
         if (simFunction === undefined) {
             return;
         }
@@ -65,19 +67,12 @@ export class SimLambdaKinesisShardPoller {
         // Reading is done as the function's execution role, as on real Lambda, so
         // simulated IAM decides whether this mapping may read its stream.
         const batch = await this.shard.read(progress.position, this.mapping.batchSize);
-        if (batch.records.length === 0) {
-            progress.caughtUp(batch);
-            return;
-        }
-        progress.after(await this.delivery.to(simFunction, batch.records), batch);
-    }
-    /**
-     * The function this mapping delivers to, while it should be delivering.
-     */
-    pollingFunction() {
-        if (this.stopped || !this.mapping.isPolling) {
-            return undefined;
-        }
-        return simLambdaEventSourceFunction(this.functions, this.mapping);
+        await processSimLambdaStreamBatch({
+            batch,
+            progress,
+            simFunction,
+            times: simLambdaKinesisStreamRecordTimes,
+            deliver: async (records) => await this.delivery.to(simFunction, records),
+        });
     }
 }

package/dist/service/lambda/event-source/poll/sim-lambda-dynamodb-stream-event-source-poller.d.ts

@@ -26,10 +26,9 @@ interface SimLambdaDynamoDbStreamEventSourcePollerProperties {
  * overlapping the first would hand the same records to the function twice.
  */
 export declare class SimLambdaDynamoDbStreamEventSourcePoller implements SimLambdaEventSourcePoller, SimLambdaEventSourcePolls {
-    private readonly mapping;
-    private readonly functions;
     private readonly stream;
     private readonly delivery;
+    private readonly polling;
     private readonly progress;
     private readonly turn;
     private stopped;
@@ -68,9 +67,5 @@ export declare class SimLambdaDynamoDbStreamEventSourcePoller implements SimLamb
      * reading the same records.
      */
     poll(): Promise<void>;
-    /**
-     * The function this mapping delivers to, while it should be delivering.
-     */
-    private pollingFunction;
 }
 export {};

package/dist/service/lambda/event-source/poll/sim-lambda-dynamodb-stream-event-source-poller.js

@@ -1,4 +1,4 @@
-import { simLambdaEventSourceFunction } from "./sim-lambda-event-source-function.js";
+import { SimLambdaDynamoDbStreamPolling } from "./sim-lambda-dynamodb-stream-polling.js";
 import { SimLambdaDynamoDbPolledStream } from "./sim-lambda-dynamodb-polled-stream.js";
 import { SimLambdaDynamoDbStreamDelivery } from "./sim-lambda-dynamodb-stream-delivery.js";
 import { SimLambdaEventSourcePollTurn, } from "./sim-lambda-event-source-poll-turn.js";
@@ -17,17 +17,14 @@ import { SimLambdaStreamProgress } from "./sim-lambda-stream-progress.js";
  * overlapping the first would hand the same records to the function twice.
  */
 export class SimLambdaDynamoDbStreamEventSourcePoller {
-    mapping;
-    functions;
     stream;
     delivery;
+    polling;
     progress;
     turn = new SimLambdaEventSourcePollTurn(this);
     stopped = false;
     constructor(properties) {
         const { eventSourceArn, mapping } = properties;
-        this.mapping = mapping;
-        this.functions = properties.functions;
         this.stream = new SimLambdaDynamoDbPolledStream(properties.streams, eventSourceArn.value);
         this.delivery = new SimLambdaDynamoDbStreamDelivery({
             mapping,
@@ -40,6 +37,12 @@ export class SimLambdaDynamoDbStreamEventSourcePoller {
                 await this.turn.take();
             },
         });
+        this.polling = new SimLambdaDynamoDbStreamPolling({
+            ...properties,
+            stream: this.stream,
+            progress: this.progress,
+            delivery: this.delivery,
+        });
     }
     /**
      * Watch the stream this mapping polls.
@@ -88,27 +91,6 @@ export class SimLambdaDynamoDbStreamEventSourcePoller {
      * reading the same records.
      */
     async poll() {
-        const simFunction = this.pollingFunction();
-        if (simFunction === undefined) {
-            return;
-        }
-        const { progress } = this;
-        // Reading is done as the function's execution role, as on real Lambda, so
-        // simulated IAM decides whether this mapping may read its stream.
-        const batch = await this.stream.read(simFunction.roleArn, progress.position, this.mapping.batchSize);
-        if (batch.records.length === 0) {
-            progress.caughtUp(batch);
-            return;
-        }
-        progress.after(await this.delivery.to(simFunction, batch.records), batch);
-    }
-    /**
-     * The function this mapping delivers to, while it should be delivering.
-     */
-    pollingFunction() {
-        if (this.stopped || !this.mapping.isPolling) {
-            return undefined;
-        }
-        return simLambdaEventSourceFunction(this.functions, this.mapping);
+        await this.polling.poll(this.stopped);
     }
 }

package/dist/service/lambda/event-source/poll/sim-lambda-dynamodb-stream-polling.d.ts

@@ -0,0 +1,19 @@
+import type { SimLambdaFunctionLookup } from "../../function/url/sim-lambda-function-lookup.js";
+import type { SimLambdaEventSourceMapping } from "../sim-lambda-event-source-mapping.js";
+import type { SimLambdaDynamoDbPolledStream } from "./sim-lambda-dynamodb-polled-stream.js";
+import type { SimLambdaDynamoDbStreamDelivery } from "./sim-lambda-dynamodb-stream-delivery.js";
+import type { SimLambdaStreamProgress } from "./sim-lambda-stream-progress.js";
+interface DynamoDbStreamPollingProperties {
+    readonly functions: SimLambdaFunctionLookup;
+    readonly mapping: SimLambdaEventSourceMapping;
+    readonly stream: SimLambdaDynamoDbPolledStream;
+    readonly delivery: SimLambdaDynamoDbStreamDelivery;
+    readonly progress: SimLambdaStreamProgress;
+}
+/** Read and process DynamoDB batches as the function execution role. */
+export declare class SimLambdaDynamoDbStreamPolling {
+    private readonly properties;
+    constructor(properties: DynamoDbStreamPollingProperties);
+    poll(stopped: boolean): Promise<void>;
+}
+export {};

package/dist/service/lambda/event-source/poll/sim-lambda-dynamodb-stream-polling.js

@@ -0,0 +1,27 @@
+import { simLambdaDynamoDbStreamRecordTimes } from "./sim-lambda-stream-record-times.js";
+import { processSimLambdaStreamBatch } from "./sim-lambda-stream-batch-processing.js";
+import { simLambdaEventSourceFunction } from "./sim-lambda-event-source-function.js";
+/** Read and process DynamoDB batches as the function execution role. */
+export class SimLambdaDynamoDbStreamPolling {
+    properties;
+    constructor(properties) {
+        this.properties = properties;
+    }
+    async poll(stopped) {
+        const simFunction = simLambdaEventSourceFunction(this.properties.functions, this.properties.mapping, stopped);
+        if (simFunction === undefined) {
+            return;
+        }
+        const { progress, stream, mapping, delivery } = this.properties;
+        // Reading is done as the function's execution role, as on real Lambda, so
+        // simulated IAM decides whether this mapping may read its stream.
+        const batch = await stream.read(simFunction.roleArn, progress.position, mapping.batchSize);
+        await processSimLambdaStreamBatch({
+            batch,
+            progress,
+            simFunction,
+            times: simLambdaDynamoDbStreamRecordTimes,
+            deliver: async (records) => await delivery.to(simFunction, records),
+        });
+    }
+}

package/dist/service/lambda/event-source/poll/sim-lambda-event-source-function.d.ts

@@ -9,4 +9,4 @@ import type { SimLambdaEventSourceMapping } from "../sim-lambda-event-source-map
  * delivers to. A function that has gone, and a qualifier that names nothing,
  * both answer with nothing, and the poll then does nothing.
  */
-export declare function simLambdaEventSourceFunction(functions: SimLambdaFunctionLookup, mapping: SimLambdaEventSourceMapping): SimLambdaFunction | undefined;
+export declare function simLambdaEventSourceFunction(functions: SimLambdaFunctionLookup, mapping: SimLambdaEventSourceMapping, stopped?: boolean): SimLambdaFunction | undefined;

package/dist/service/lambda/event-source/poll/sim-lambda-event-source-function.js

@@ -6,7 +6,9 @@
  * delivers to. A function that has gone, and a qualifier that names nothing,
  * both answer with nothing, and the poll then does nothing.
  */
-export function simLambdaEventSourceFunction(functions, mapping) {
+export function simLambdaEventSourceFunction(functions, mapping, stopped = false) {
+    if (stopped || !mapping.isPolling)
+        return undefined;
     return functions.findTarget(mapping.functionName, mapping.qualifier)
         ?.simFunction;
 }

package/dist/service/lambda/event-source/poll/sim-lambda-stream-batch-age.d.ts

@@ -0,0 +1,13 @@
+import type { SimClock } from "../../../../util/clock/sim-clock.js";
+import type { SimLambdaStreamRetryLimits } from "../sim-lambda-stream-retry-limits.js";
+import type { SimLambdaEventSourceStreamPosition } from "../stream/sim-lambda-event-source-streams.js";
+import type { SimLambdaStreamDiscard } from "./sim-lambda-stream-failure-record.js";
+import type { SimLambdaStreamRecordTime } from "./sim-lambda-stream-record-times.js";
+/** Identifies the expired prefix at the time a batch is polled. */
+export declare class SimLambdaStreamBatchAge {
+    private readonly limits;
+    private readonly clock;
+    constructor(limits: SimLambdaStreamRetryLimits, clock: SimClock);
+    discarded(records: readonly SimLambdaStreamRecordTime[]): SimLambdaStreamDiscard | undefined;
+    firstLivePosition(records: readonly SimLambdaStreamRecordTime[], count: number): SimLambdaEventSourceStreamPosition;
+}

package/dist/service/lambda/event-source/poll/sim-lambda-stream-batch-age.js

@@ -0,0 +1,27 @@
+import { assertDefined } from "../../../../util/type-guard/defined.js";
+/** Identifies the expired prefix at the time a batch is polled. */
+export class SimLambdaStreamBatchAge {
+    limits;
+    clock;
+    constructor(limits, clock) {
+        this.limits = limits;
+        this.clock = clock;
+    }
+    discarded(records) {
+        const at = this.clock.now();
+        const firstLive = records.findIndex((record) => !this.limits.hasAgedOut(record.at, at));
+        const count = firstLive === -1 ? records.length : firstLive;
+        if (count === 0)
+            return undefined;
+        return {
+            records: records.slice(0, count),
+            condition: "RecordAgeExceeded",
+            at,
+        };
+    }
+    firstLivePosition(records, count) {
+        const sequenceNumber = records.at(count)?.sequenceNumber;
+        assertDefined(sequenceNumber, "live stream record sequence number");
+        return { kind: "sequence", sequenceNumber };
+    }
+}

package/dist/service/lambda/event-source/poll/sim-lambda-stream-batch-info.d.ts

@@ -0,0 +1,15 @@
+import type { SimLambdaStreamFailureRecord } from "./sim-lambda-stream-failure-record.js";
+import type { SimLambdaStreamRecordTime } from "./sim-lambda-stream-record-times.js";
+export interface SimLambdaStreamBatchInfo {
+    readonly shardId: string;
+    readonly streamArn: string;
+    readonly startSequenceNumber: string;
+    readonly endSequenceNumber: string;
+    readonly approximateArrivalOfFirstRecord: string;
+    readonly approximateArrivalOfLastRecord: string;
+    readonly batchSize: number;
+}
+/** Identify the discarded records by shard and sequence-number bounds. */
+export declare function simLambdaStreamBatchInfo(records: readonly SimLambdaStreamRecordTime[], streamArn: string, shardId: string | undefined): SimLambdaStreamBatchInfo;
+/** Identify the discarded records by shard and sequence-number bounds. */
+export declare function streamFailureBatchInfo(arn: string, info: SimLambdaStreamBatchInfo): Pick<SimLambdaStreamFailureRecord, "DDBStreamBatchInfo" | "KinesisBatchInfo">;

package/dist/service/lambda/event-source/poll/sim-lambda-stream-batch-info.js

@@ -0,0 +1,26 @@
+import { assertDefined } from "../../../../util/type-guard/defined.js";
+/** Identify the discarded records by shard and sequence-number bounds. */
+export function simLambdaStreamBatchInfo(records, streamArn, shardId) {
+    const first = records.at(0);
+    const last = records.at(-1);
+    assertDefined(shardId, "discarded stream batch shard ID");
+    assertDefined(first?.sequenceNumber, "discarded batch start sequence number");
+    assertDefined(last?.sequenceNumber, "discarded batch end sequence number");
+    assertDefined(first.at, "discarded batch first arrival time");
+    assertDefined(last.at, "discarded batch last arrival time");
+    return {
+        shardId,
+        streamArn,
+        startSequenceNumber: first.sequenceNumber,
+        endSequenceNumber: last.sequenceNumber,
+        approximateArrivalOfFirstRecord: first.at.toISOString(),
+        approximateArrivalOfLastRecord: last.at.toISOString(),
+        batchSize: records.length,
+    };
+}
+/** Identify the discarded records by shard and sequence-number bounds. */
+export function streamFailureBatchInfo(arn, info) {
+    if (arn.startsWith("arn:aws:dynamodb:"))
+        return { DDBStreamBatchInfo: info };
+    return { KinesisBatchInfo: info };
+}

package/dist/service/lambda/event-source/poll/sim-lambda-stream-batch-outcome.d.ts

@@ -14,6 +14,7 @@ import type { SimLambdaStreamRecordTime } from "./sim-lambda-stream-record-times
  * to and the instants its records are aged from.
  */
 export declare class SimLambdaStreamBatchOutcome {
+    readonly functionError: boolean;
     readonly isHandled: boolean;
     /**
      * The records the batch carried, in stream order.

package/dist/service/lambda/event-source/poll/sim-lambda-stream-batch-outcome.js

@@ -12,6 +12,7 @@
  * to and the instants its records are aged from.
  */
 export class SimLambdaStreamBatchOutcome {
+    functionError;
     isHandled;
     /**
      * The records the batch carried, in stream order.
@@ -19,6 +20,7 @@ export class SimLambdaStreamBatchOutcome {
     records;
     rewindTo;
     constructor(properties) {
+        this.functionError = properties.functionError ?? false;
         this.isHandled = properties.isHandled;
         this.records = properties.records;
         this.rewindTo = properties.rewindTo;
@@ -33,7 +35,11 @@ export class SimLambdaStreamBatchOutcome {
      * A batch the function did not take, which is read again from where it was.
      */
     static failed(records) {
-        return new SimLambdaStreamBatchOutcome({ isHandled: false, records });
+        return new SimLambdaStreamBatchOutcome({
+            isHandled: false,
+            records,
+            functionError: true,
+        });
     }
     /**
      * A batch the function reported failing partway through, which is read again

package/dist/service/lambda/event-source/poll/sim-lambda-stream-batch-processing.d.ts

@@ -0,0 +1,17 @@
+import type { SimLambdaFunction } from "../../function/sim-lambda-function.js";
+import type { SimLambdaEventSourceStreamProgressBatch } from "../stream/sim-lambda-event-source-streams.js";
+import type { SimLambdaStreamBatchOutcome } from "./sim-lambda-stream-batch-outcome.js";
+import type { SimLambdaStreamProgress } from "./sim-lambda-stream-progress.js";
+import type { SimLambdaStreamRecordTime } from "./sim-lambda-stream-record-times.js";
+interface StreamBatchProcessing<RecordType> {
+    readonly batch: SimLambdaEventSourceStreamProgressBatch & {
+        readonly records: readonly RecordType[];
+    };
+    readonly simFunction: SimLambdaFunction;
+    readonly progress: SimLambdaStreamProgress;
+    readonly times: (records: readonly RecordType[]) => readonly SimLambdaStreamRecordTime[];
+    readonly deliver: (records: readonly RecordType[]) => Promise<SimLambdaStreamBatchOutcome>;
+}
+/** Check record age, invoke live records, and apply the batch outcome. */
+export declare function processSimLambdaStreamBatch<RecordType>(properties: StreamBatchProcessing<RecordType>): Promise<void>;
+export {};

package/dist/service/lambda/event-source/poll/sim-lambda-stream-batch-processing.js

@@ -0,0 +1,12 @@
+/** Check record age, invoke live records, and apply the batch outcome. */
+export async function processSimLambdaStreamBatch(properties) {
+    const { batch, progress, simFunction } = properties;
+    if (batch.records.length === 0) {
+        progress.caughtUp(batch);
+        return;
+    }
+    const firstLive = await progress.before(properties.times(batch.records), batch, simFunction);
+    if (firstLive === batch.records.length)
+        return;
+    await progress.after(await properties.deliver(batch.records.slice(firstLive)), batch, simFunction);
+}

package/dist/service/lambda/event-source/poll/sim-lambda-stream-cursor.d.ts

@@ -0,0 +1,15 @@
+import type { PollSchedule } from "../../../../util/background/poll-schedule.js";
+import type { SimLambdaEventSourceStart } from "../sim-lambda-event-source-starting-position.js";
+import type { SimLambdaEventSourceStreamPosition, SimLambdaEventSourceStreamProgressBatch } from "../stream/sim-lambda-event-source-streams.js";
+import type { SimLambdaStreamRetryAttempt } from "./sim-lambda-stream-retry.js";
+/** Keep the next read position and schedule consistent when a batch finishes or retries. */
+export declare class SimLambdaStreamCursor {
+    private readonly schedule;
+    private readonly checkpoint;
+    constructor(start: SimLambdaEventSourceStart, schedule: PollSchedule);
+    get position(): SimLambdaEventSourceStreamPosition;
+    advanceTo(position: SimLambdaEventSourceStreamPosition): void;
+    pollNow(): void;
+    handled(batch: SimLambdaEventSourceStreamProgressBatch): void;
+    resume(attempt: SimLambdaStreamRetryAttempt): void;
+}

package/dist/service/lambda/event-source/poll/sim-lambda-stream-cursor.js

@@ -0,0 +1,28 @@
+import { SimLambdaStreamCheckpoint } from "./sim-lambda-stream-checkpoint.js";
+/** Keep the next read position and schedule consistent when a batch finishes or retries. */
+export class SimLambdaStreamCursor {
+    schedule;
+    checkpoint;
+    constructor(start, schedule) {
+        this.schedule = schedule;
+        this.checkpoint = new SimLambdaStreamCheckpoint(start);
+    }
+    get position() {
+        return this.checkpoint.position;
+    }
+    advanceTo(position) {
+        this.checkpoint.advanceTo(position);
+    }
+    pollNow() {
+        this.schedule.now();
+    }
+    handled(batch) {
+        this.advanceTo(batch.next);
+        if (!batch.drained)
+            this.pollNow();
+    }
+    resume(attempt) {
+        this.advanceTo(attempt.position);
+        this.schedule.afterSeconds(attempt.afterSeconds);
+    }
+}

package/dist/service/lambda/event-source/poll/sim-lambda-stream-expiry.d.ts

@@ -0,0 +1,19 @@
+import type { SimLambdaStreamBatchAge } from "./sim-lambda-stream-batch-age.js";
+import type { SimLambdaStreamRecordTime } from "./sim-lambda-stream-record-times.js";
+import type { SimLambdaFunction } from "../../function/sim-lambda-function.js";
+import type { SimLambdaStreamFailureDestination } from "./sim-lambda-stream-failure-destination.js";
+import type { SimLambdaEventSourceStreamProgressBatch } from "../stream/sim-lambda-event-source-streams.js";
+import type { SimLambdaStreamCursor } from "./sim-lambda-stream-cursor.js";
+interface StreamExpiryProperties {
+    readonly age: SimLambdaStreamBatchAge;
+    readonly cursor: SimLambdaStreamCursor;
+    readonly failures: SimLambdaStreamFailureDestination;
+    readonly handled: (batch: SimLambdaEventSourceStreamProgressBatch) => void;
+}
+/** Advance past expired records and notify their destination before processing live records. */
+export declare class SimLambdaStreamExpiry {
+    private readonly properties;
+    constructor(properties: StreamExpiryProperties);
+    before(records: readonly SimLambdaStreamRecordTime[], batch: SimLambdaEventSourceStreamProgressBatch, simFunction: SimLambdaFunction): Promise<number>;
+}
+export {};

package/dist/service/lambda/event-source/poll/sim-lambda-stream-expiry.js

@@ -0,0 +1,23 @@
+/** Advance past expired records and notify their destination before processing live records. */
+export class SimLambdaStreamExpiry {
+    properties;
+    constructor(properties) {
+        this.properties = properties;
+    }
+    async before(records, batch, simFunction) {
+        const { age, cursor, failures, handled } = this.properties;
+        const discard = age.discarded(records);
+        if (discard === undefined)
+            return 0;
+        const discardedCount = discard.records.length;
+        const notification = failures.deliver(discard, batch, simFunction);
+        if (discardedCount === records.length) {
+            handled(batch);
+        }
+        else {
+            cursor.advanceTo(age.firstLivePosition(records, discardedCount));
+        }
+        await notification;
+        return discardedCount;
+    }
+}