@middy/cloudwatch-metrics 7.2.3 → 7.3.1

package/index.d.ts

@@ -7,7 +7,8 @@ export { MetricsLogger } from "aws-embedded-metrics";
 
 export interface Options {
 	namespace?: string;
-	dimensions?: Array<Record<string, string>>;
+	dimensions?: Record<string, string> | Array<Record<string, string>>;
+	onFlushError?: (error: Error) => void;
 }
 
 export type Context = LambdaContext & {
@@ -18,4 +19,8 @@ declare function cloudwatchMetrics(
 	options?: Options,
 ): middy.MiddlewareObj<unknown, unknown, Error>;
 
+export declare function cloudwatchMetricsValidateOptions(
+	options?: Record<string, unknown>,
+): void;
+
 export default cloudwatchMetrics;

package/index.js

@@ -1,11 +1,38 @@
 // Copyright 2017 - 2026 will Farrell, Luciano Mammino, and Middy contributors.
 // SPDX-License-Identifier: MIT
+
+import { validateOptions } from "@middy/util";
 import awsEmbeddedMetrics from "aws-embedded-metrics";
 
-const defaults = {};
+const defaults = {
+	onFlushError: undefined,
+};
+
+// `dimensions` accepts either a single dimension set (object of
+// string->string) or an array of dimension sets, matching the documented
+// API and aws-embedded-metrics' `setDimensions(dimensionSets)` signature.
+const dimensionSetSchema = {
+	type: "object",
+	additionalProperties: { type: "string", minLength: 1, maxLength: 1024 },
+};
+
+const optionSchema = {
+	type: "object",
+	properties: {
+		namespace: { type: "string", minLength: 1, maxLength: 256 },
+		dimensions: {
+			oneOf: [dimensionSetSchema, { type: "array", items: dimensionSetSchema }],
+		},
+		onFlushError: { instanceof: "Function" },
+	},
+	additionalProperties: false,
+};
+
+export const cloudwatchMetricsValidateOptions = (options) =>
+	validateOptions("@middy/cloudwatch-metrics", optionSchema, options);
 
 const cloudwatchMetricsMiddleware = (opts = {}) => {
-	const { namespace, dimensions } = { ...defaults, ...opts };
+	const { namespace, dimensions, onFlushError } = { ...defaults, ...opts };
 	const cloudwatchMetricsBefore = async (request) => {
 		const metrics = awsEmbeddedMetrics.createMetricsLogger();
 
@@ -24,8 +51,11 @@ const cloudwatchMetricsMiddleware = (opts = {}) => {
 	const flushMetrics = async (request) => {
 		try {
 			await request.context.metrics?.flush();
-		} catch {
-			// Swallow flush errors to prevent metrics from crashing the handler
+		} catch (err) {
+			// Flush errors are swallowed to prevent metrics from crashing the
+			// handler. Users who need visibility (e.g., to catch IAM or network
+			// misconfigurations) can pass `onFlushError` to observe them.
+			onFlushError?.(err);
 		}
 	};
 	const cloudwatchMetricsAfter = flushMetrics;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@middy/cloudwatch-metrics",
-	"version": "7.2.3",
+	"version": "7.3.1",
 	"description": "Embedded CloudWatch metrics middleware for the middy framework",
 	"type": "module",
 	"engines": {
@@ -17,9 +17,6 @@
 			"import": {
 				"types": "./index.d.ts",
 				"default": "./index.js"
-			},
-			"require": {
-				"default": "./index.js"
 			}
 		}
 	},
@@ -71,7 +68,7 @@
 		"aws-embedded-metrics": "4.2.1"
 	},
 	"devDependencies": {
-		"@middy/core": "7.2.3",
+		"@middy/core": "7.3.1",
 		"@types/aws-lambda": "^8.0.0",
 		"@types/node": "^22.0.0"
 	}