@middy/event-batch-response 7.5.0

package/README.md

@@ -0,0 +1,50 @@
+<div align="center">
+  <h1>Middy `event-batch-response` middleware</h1>
+  <img alt="Middy logo" src="https://raw.githubusercontent.com/middyjs/middy/main/docs/img/middy-logo.svg"/>
+  <p><strong>Batch response middleware for the middy framework, the stylish Node.js middleware engine for AWS Lambda. Shapes the response for SQS, Kinesis, DynamoDB Streams, Kafka, S3 Batch Operations, and Kinesis Firehose transform.</strong></p>
+  <p>
+    <a href="https://github.com/middyjs/middy/actions/workflows/test-unit.yml"><img src="https://github.com/middyjs/middy/actions/workflows/test-unit.yml/badge.svg" alt="GitHub Actions unit test status"></a>
+    <a href="https://github.com/middyjs/middy/actions/workflows/test-dast.yml"><img src="https://github.com/middyjs/middy/actions/workflows/test-dast.yml/badge.svg" alt="GitHub Actions dast test status"></a>
+    <a href="https://github.com/middyjs/middy/actions/workflows/test-perf.yml"><img src="https://github.com/middyjs/middy/actions/workflows/test-perf.yml/badge.svg" alt="GitHub Actions perf test status"></a>
+    <a href="https://github.com/middyjs/middy/actions/workflows/test-sast.yml"><img src="https://github.com/middyjs/middy/actions/workflows/test-sast.yml/badge.svg" alt="GitHub Actions SAST test status"></a>
+    <a href="https://github.com/middyjs/middy/actions/workflows/test-lint.yml"><img src="https://github.com/middyjs/middy/actions/workflows/test-lint.yml/badge.svg" alt="GitHub Actions lint test status"></a>
+    <br/>
+    <a href="https://www.npmjs.com/package/@middy/event-batch-response"><img alt="npm version" src="https://img.shields.io/npm/v/@middy/event-batch-response.svg"></a>
+    <a href="https://packagephobia.com/result?p=@middy/event-batch-response"><img src="https://packagephobia.com/badge?p=@middy/event-batch-response" alt="npm install size"></a>
+    <a href="https://www.npmjs.com/package/@middy/event-batch-response">
+    <img alt="npm weekly downloads" src="https://img.shields.io/npm/dw/@middy/event-batch-response.svg"></a>
+    <a href="https://www.npmjs.com/package/@middy/event-batch-response#provenance">
+    <img alt="npm provenance" src="https://img.shields.io/badge/provenance-Yes-brightgreen"></a>
+    <br/>
+    <a href="https://scorecard.dev/viewer/?uri=github.com/middyjs/middy"><img src="https://api.scorecard.dev/projects/github.com/middyjs/middy/badge" alt="Open Source Security Foundation (OpenSSF) Scorecard"></a>
+    <a href="https://slsa.dev"><img src="https://slsa.dev/images/gh-badge-level3.svg" alt="SLSA 3"></a>
+    <a href="https://github.com/middyjs/middy/blob/main/docs/CODE_OF_CONDUCT.md"><img src="https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg"></a>
+    <a href="https://biomejs.dev"><img alt="Checked with Biome" src="https://img.shields.io/badge/Checked_with-Biome-60a5fa?style=flat&logo=biome"></a>
+    <a href="https://conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white"></a>
+    <a href="https://github.com/middyjs/middy/blob/main/package.json#L32">
+    <img alt="code coverage" src="https://img.shields.io/badge/code%20coverage-100%25-brightgreen"></a>
+    <br/>
+  </p>
+<p>You can read the documentation at: <a href="https://middy.js.org/docs/middlewares/event-batch-response">https://middy.js.org/docs/middlewares/event-batch-response</a></p>
+</div>
+
+## Install
+
+```bash
+npm install --save @middy/event-batch-response
+```
+
+
+## Documentation and examples
+
+For documentation and examples, refer to the main [Middy monorepo on GitHub](https://github.com/middyjs/middy) or [Middy official website](https://middy.js.org/docs/middlewares/event-batch-response).
+
+
+## Contributing
+
+Everyone is very welcome to contribute to this repository. Feel free to [raise issues](https://github.com/middyjs/middy/issues) or to [submit Pull Requests](https://github.com/middyjs/middy/pulls).
+
+
+## License
+
+Licensed under [MIT License](https://github.com/middyjs/middy/blob/main/LICENSE). Copyright (c) 2017-2026 [will Farrell](https://github.com/willfarrell), [Luciano Mammino](https://github.com/lmammino), and [Middy contributors](https://github.com/middyjs/middy/graphs/contributors).

package/index.d.ts

@@ -0,0 +1,25 @@
+// Copyright 2017 - 2026 will Farrell, Luciano Mammino, and Middy contributors.
+// SPDX-License-Identifier: MIT
+import type middy from "@middy/core";
+
+declare function eventBatchResponse(): middy.MiddlewareObj<
+	unknown,
+	unknown,
+	Error
+>;
+
+/**
+ * Walk a Lambda batch event into a flat array of records, using the same
+ * detection precedence as the middleware. Shared with `@middy/event-batch-handler`
+ * so both packages iterate records in the same order.
+ *
+ * Supported sources: SQS, Kinesis Data Streams, DynamoDB Streams, MSK,
+ * self-managed Kafka, S3 Batch Operations, Kinesis Firehose transform.
+ *
+ * Returns `[]` for unrecognized event shapes or missing containers.
+ * Coerces non-array containers to `[]` rather than throwing — malformed
+ * events degrade silently.
+ */
+export declare function flattenBatchRecords(event: unknown): unknown[];
+
+export default eventBatchResponse;

package/index.js

@@ -0,0 +1,219 @@
+// Copyright 2017 - 2026 will Farrell, Luciano Mammino, and Middy contributors.
+// SPDX-License-Identifier: MIT
+import { isExecutionModeDurable } from "@middy/util";
+
+const name = "event-batch-response";
+const pkg = `@middy/${name}`;
+
+const buildBatchItemFailures = ({ items, settled }) => {
+	const batchItemFailures = [];
+	for (let idx = 0; idx < items.length; idx += 1) {
+		const entry = settled[idx] ?? {};
+		if (entry.status === "fulfilled") continue;
+		batchItemFailures.push({ itemIdentifier: items[idx].identifier });
+	}
+	return { batchItemFailures };
+};
+
+const toS3BatchResult = (taskId, value, defaultCode, reason) => {
+	if (value && typeof value === "object" && "resultCode" in value) {
+		return {
+			taskId,
+			resultCode: value.resultCode,
+			resultString: value.resultString ?? "",
+		};
+	}
+	if (typeof value === "string") {
+		return { taskId, resultCode: defaultCode, resultString: value };
+	}
+	const resultString =
+		reason instanceof Error ? reason.message : (reason ?? "");
+	return {
+		taskId,
+		resultCode: defaultCode,
+		resultString: String(resultString),
+	};
+};
+
+const buildS3BatchResponse = ({ items, settled, request }) => {
+	const results = items.map((item, idx) => {
+		const entry = settled[idx] ?? {};
+		if (entry.status === "fulfilled") {
+			return toS3BatchResult(item.identifier, entry.value, "Succeeded");
+		}
+		return toS3BatchResult(
+			item.identifier,
+			entry.value,
+			"TemporaryFailure",
+			entry.reason,
+		);
+	});
+	return {
+		invocationSchemaVersion: request.event.invocationSchemaVersion,
+		treatMissingKeysAs: "PermanentFailure",
+		invocationId: request.event.invocationId,
+		results,
+	};
+};
+
+const encodeFirehoseData = (value, fallback) => {
+	if (value === undefined || value === null) return fallback;
+	if (typeof value === "string") return Buffer.from(value).toString("base64");
+	if (Buffer.isBuffer(value)) return value.toString("base64");
+	if (value instanceof Uint8Array) return Buffer.from(value).toString("base64");
+	return Buffer.from(JSON.stringify(value)).toString("base64");
+};
+
+const toFirehoseRecord = (recordId, inputData, value, defaultResult) => {
+	if (value && typeof value === "object" && "result" in value) {
+		return {
+			recordId,
+			result: value.result,
+			data: encodeFirehoseData(value.data, inputData),
+		};
+	}
+	return {
+		recordId,
+		result: defaultResult,
+		data: encodeFirehoseData(value, inputData),
+	};
+};
+
+const buildFirehoseResponse = ({ items, settled }) => {
+	const records = items.map((item, idx) => {
+		const entry = settled[idx] ?? {};
+		const inputData = item.record?.data;
+		if (entry.status === "fulfilled") {
+			return toFirehoseRecord(item.identifier, inputData, entry.value, "Ok");
+		}
+		return {
+			recordId: item.identifier,
+			result: "ProcessingFailed",
+			data: inputData,
+		};
+	});
+	return { records };
+};
+
+const asArray = (value) => (Array.isArray(value) ? value : []);
+const sqsLikeRecords = (event) => asArray(event.Records);
+const kafkaRecords = (event) => {
+	const records = event.records;
+	if (!records || typeof records !== "object") return [];
+	const out = [];
+	for (const messages of Object.values(records)) {
+		if (!Array.isArray(messages)) continue;
+		for (const message of messages) out.push(message);
+	}
+	return out;
+};
+
+const sources = {
+	"aws:sqs": {
+		getRecords: sqsLikeRecords,
+		identify: (record) => record?.messageId,
+		buildResponse: buildBatchItemFailures,
+	},
+	"aws:kinesis": {
+		getRecords: sqsLikeRecords,
+		identify: (record) => record?.kinesis?.sequenceNumber,
+		buildResponse: buildBatchItemFailures,
+	},
+	"aws:dynamodb": {
+		getRecords: sqsLikeRecords,
+		identify: (record) => record?.dynamodb?.SequenceNumber,
+		buildResponse: buildBatchItemFailures,
+	},
+	"aws:kafka": {
+		getRecords: kafkaRecords,
+		identify: (message) =>
+			message && `${message.topic}-${message.partition}-${message.offset}`,
+		buildResponse: buildBatchItemFailures,
+	},
+	"aws:s3:batch": {
+		getRecords: (event) => asArray(event.tasks),
+		identify: (task) => task?.taskId,
+		buildResponse: buildS3BatchResponse,
+	},
+	"aws:lambda:events": {
+		getRecords: (event) => asArray(event.records),
+		identify: (record) => record?.recordId,
+		buildResponse: buildFirehoseResponse,
+	},
+};
+sources.SelfManagedKafka = sources["aws:kafka"];
+
+const detectEventSource = (event) => {
+	if (!event || typeof event !== "object") return undefined;
+	if (event.eventSource) return event.eventSource;
+	// Firehose transform: identified by deliveryStreamArn.
+	if (event.deliveryStreamArn) return "aws:lambda:events";
+	// S3 Batch Operations: no eventSource on event or task; identified by
+	// invocationSchemaVersion + tasks array.
+	if (event.invocationSchemaVersion && Array.isArray(event.tasks)) {
+		return "aws:s3:batch";
+	}
+	const records = event.Records ?? event.records ?? event.events ?? event.tasks;
+	if (Array.isArray(records) && records[0]) {
+		return records[0].eventSource ?? records[0].EventSource;
+	}
+	return undefined;
+};
+
+export const flattenBatchRecords = (event) => {
+	const source = sources[detectEventSource(event)];
+	if (!source) return [];
+	return source.getRecords(event);
+};
+
+const buildItems = (source, event) =>
+	source.getRecords(event).map((record) => ({
+		record,
+		identifier: source.identify(record),
+	}));
+
+const eventBatchResponseMiddleware = () => {
+	const eventBatchResponseMiddlewareBefore = (request) => {
+		const source = sources[detectEventSource(request.event)];
+		if (!source) return;
+		request.internal[pkg] = {
+			source,
+			items: buildItems(source, request.event),
+		};
+	};
+
+	const eventBatchResponseMiddlewareAfter = (request) => {
+		const cached = request.internal[pkg];
+		if (!cached) return;
+		if (!Array.isArray(request.response)) return;
+
+		request.response = cached.source.buildResponse({
+			items: cached.items,
+			settled: request.response,
+			request,
+		});
+	};
+
+	const eventBatchResponseMiddlewareOnError = (request) => {
+		// TODO remove in v8: core already skips the onError stack in durable mode.
+		if (isExecutionModeDurable(request.context)) throw request.error;
+		if (typeof request.response !== "undefined") return;
+		const cached = request.internal[pkg];
+		if (!cached) return;
+
+		request.response = Array.from({ length: cached.items.length }, () => ({
+			status: "rejected",
+			reason: request.error,
+		}));
+
+		eventBatchResponseMiddlewareAfter(request);
+	};
+
+	return {
+		before: eventBatchResponseMiddlewareBefore,
+		after: eventBatchResponseMiddlewareAfter,
+		onError: eventBatchResponseMiddlewareOnError,
+	};
+};
+
+export default eventBatchResponseMiddleware;

package/package.json

@@ -0,0 +1,77 @@
+{
+	"name": "@middy/event-batch-response",
+	"version": "7.5.0",
+	"description": "Batch response middleware for the middy framework (SQS, Kinesis, DynamoDB Streams, Kafka, S3 Batch, Firehose)",
+	"type": "module",
+	"engines": {
+		"node": ">=22"
+	},
+	"engineStrict": true,
+	"publishConfig": {
+		"access": "public"
+	},
+	"module": "./index.js",
+	"sideEffects": false,
+	"exports": {
+		".": {
+			"import": {
+				"types": "./index.d.ts",
+				"default": "./index.js"
+			}
+		}
+	},
+	"types": "index.d.ts",
+	"files": [
+		"index.js",
+		"index.d.ts"
+	],
+	"scripts": {
+		"test": "npm run test:unit && npm run test:fuzz",
+		"test:unit": "node --test",
+		"test:fuzz": "node --test index.fuzz.js",
+		"test:perf": "node --test index.perf.js"
+	},
+	"license": "MIT",
+	"keywords": [
+		"Lambda",
+		"Middleware",
+		"Serverless",
+		"Framework",
+		"AWS",
+		"AWS Lambda",
+		"Middy",
+		"SQS",
+		"Kinesis",
+		"DynamoDB",
+		"Kafka",
+		"S3 Batch",
+		"Firehose",
+		"Batch"
+	],
+	"author": {
+		"name": "Middy contributors",
+		"url": "https://github.com/middyjs/middy/graphs/contributors"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/middyjs/middy.git",
+		"directory": "packages/event-batch-response"
+	},
+	"bugs": {
+		"url": "https://github.com/middyjs/middy/issues"
+	},
+	"homepage": "https://middy.js.org",
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/willfarrell"
+	},
+	"dependencies": {
+		"@middy/util": "7.5.0"
+	},
+	"devDependencies": {
+		"@middy/core": "7.5.0",
+		"@serverless/event-mocks": "^1.0.0",
+		"@types/aws-lambda": "^8.0.0",
+		"@types/node": "^22.0.0"
+	}
+}