@middy/util 7.2.2 → 7.3.0

package/index.d.ts

@@ -21,6 +21,7 @@ export interface Options<Client, ClientOptions> {
 	cacheKey?: string;
 	cacheExpiry?: number;
 	cacheKeyExpiry?: Record<string, number>;
+	cacheMaxSize?: number;
 	setToContext?: boolean;
 }
 
@@ -157,6 +158,8 @@ declare function jsonSafeStringify(
 	space?: string | number,
 ): string | unknown;
 
+declare const jsonContentTypePattern: RegExp;
+
 declare function decodeBody(event: {
 	body?: string | null;
 	isBase64Encoded?: boolean;
@@ -181,3 +184,28 @@ declare function lambdaContext(
 ): unknown;
 
 declare const httpErrorCodes: Record<number, string>;
+
+export type OptionSchemaRule =
+	| "string"
+	| "number"
+	| "boolean"
+	| "function"
+	| "object"
+	| "array"
+	| "string?"
+	| "number?"
+	| "boolean?"
+	| "function?"
+	| "object?"
+	| "array?"
+	| ((value: unknown) => boolean);
+
+export type OptionSchema = Record<string, OptionSchemaRule>;
+
+export declare function validateOptions(
+	packageName: string,
+	schema: OptionSchema,
+	options?: Record<string, unknown>,
+): void;
+
+export declare const awsClientOptionSchema: OptionSchema;

package/index.js

@@ -1,5 +1,75 @@
 // Copyright 2017 - 2026 will Farrell, Luciano Mammino, and Middy contributors.
 // SPDX-License-Identifier: MIT
+
+// Option validation helper.
+// Schema values:
+//   'string' | 'number' | 'boolean' | 'function' | 'object' | 'array'
+//     Trailing '?' marks the field as optional (may be undefined).
+//   (value) => boolean predicate — only called when value is not undefined
+//     (i.e. predicates treat the field as optional by design).
+// Keys in `options` that are not in `schema` throw, catching typos.
+const validateOptionsTypeCheckers = {
+	string: (v) => typeof v === "string",
+	number: (v) => typeof v === "number" && !Number.isNaN(v),
+	boolean: (v) => typeof v === "boolean",
+	function: (v) => typeof v === "function",
+	object: (v) => v !== null && typeof v === "object" && !Array.isArray(v),
+	array: (v) => Array.isArray(v),
+};
+
+// Shared schema for middlewares that wrap an AWS SDK client. Spread into
+// package-specific schemas: `{ ...awsClientOptionSchema, extraField: 'type?' }`.
+export const awsClientOptionSchema = {
+	AwsClient: "function?",
+	awsClientOptions: "object?",
+	awsClientAssumeRole: "string?",
+	awsClientCapture: "function?",
+	fetchData: "object?",
+	disablePrefetch: "boolean?",
+	cacheKey: "string?",
+	cacheKeyExpiry: "object?",
+	cacheExpiry: (v) => typeof v === "number" && v >= -1,
+	cacheMaxSize: (v) => Number.isInteger(v) && v >= 1,
+	setToContext: "boolean?",
+};
+
+export const validateOptions = (packageName, schema, options = {}) => {
+	const fail = (message) => {
+		throw new TypeError(message, { cause: { package: packageName } });
+	};
+	if (
+		options === null ||
+		typeof options !== "object" ||
+		Array.isArray(options)
+	) {
+		fail("options must be an object");
+	}
+	for (const key of Object.keys(options)) {
+		if (!Object.hasOwn(schema, key)) {
+			fail(`Unknown option '${key}'`);
+		}
+	}
+	for (const key of Object.keys(schema)) {
+		const rule = schema[key];
+		const value = options[key];
+		if (typeof rule === "function") {
+			if (value !== undefined && !rule(value)) {
+				fail(`Invalid option '${key}'`);
+			}
+			continue;
+		}
+		const optional = rule.endsWith("?");
+		const type = optional ? rule.slice(0, -1) : rule;
+		const checker = validateOptionsTypeCheckers[type];
+		if (!checker) fail(`Unknown schema type '${type}' for option '${key}'`);
+		if (value === undefined) {
+			if (!optional) fail(`Missing required option '${key}' (${type})`);
+			continue;
+		}
+		if (!checker(value)) fail(`Option '${key}' must be ${type}`);
+	}
+};
+
 export const createPrefetchClient = (options) => {
 	const { awsClientOptions } = options;
 	const client = new options.AwsClient(awsClientOptions);
@@ -139,14 +209,34 @@ export const sanitizeKey = (key) => {
 };
 
 // fetch Cache
-const cache = Object.create(null); // key: { value:{fetchKey:Promise}, expiry }
+// Map keyed by cacheKey; value shape: { value:{fetchKey:Promise}, expiry, refresh?, modified? }
+// Map chosen over plain object so deletion is O(1), frees the key slot, and
+// avoids the `delete` operator (biome's performance/noDelete rule).
+const cache = new Map();
+const defaultCacheMaxSize = 128;
+
+const validateCacheExpiry = (cacheExpiry) => {
+	if (
+		typeof cacheExpiry === "number" &&
+		cacheExpiry < -1 &&
+		!Number.isNaN(cacheExpiry)
+	) {
+		throw new Error(
+			`Invalid cacheExpiry value: ${cacheExpiry}. Must be -1 (infinite), 0 (disabled), or a positive number (ms duration or unix timestamp)`,
+			{ cause: { package: "@middy/util" } },
+		);
+	}
+};
+
 export const processCache = (
 	options,
 	middlewareFetch = () => undefined,
 	middlewareFetchRequest = {},
 ) => {
-	let { cacheKey, cacheKeyExpiry, cacheExpiry } = options;
+	let { cacheKey, cacheKeyExpiry, cacheExpiry, cacheMaxSize } = options;
+	cacheMaxSize ??= defaultCacheMaxSize;
 	cacheExpiry = cacheKeyExpiry?.[cacheKey] ?? cacheExpiry;
+	validateCacheExpiry(cacheExpiry);
 	const now = Date.now();
 	if (cacheExpiry) {
 		const cached = getCache(cacheKey);
@@ -156,27 +246,36 @@ export const processCache = (
 			if (cached.modified) {
 				const value = middlewareFetch(middlewareFetchRequest, cached.value);
 				Object.assign(cached.value, value);
-				cache[cacheKey] = { value: cached.value, expiry: cached.expiry };
-				return cache[cacheKey];
+				const entry = { value: cached.value, expiry: cached.expiry };
+				cache.set(cacheKey, entry);
+				return entry;
 			}
 			cached.cache = true;
 			return cached;
 		}
 	}
 	const value = middlewareFetch(middlewareFetchRequest);
-	// secrets-manager can override to unix timestamp
+	// cacheExpiry semantics:
+	//   >86400000 (24h): treated as unix timestamp (ms)
+	//   >0 && <=86400000: treated as duration (ms) from now
+	//   -1: infinite cache (never expires)
+	//   0/undefined/null: no caching
 	const expiry = cacheExpiry > 86400000 ? cacheExpiry : now + cacheExpiry;
 	const duration = cacheExpiry > 86400000 ? cacheExpiry - now : cacheExpiry;
 	if (cacheExpiry) {
+		clearTimeout(cache.get(cacheKey)?.refresh);
+		// .unref() so a pending refresh timer does not keep the Lambda event
+		// loop alive (relevant under `callbackWaitsForEmptyEventLoop: false`).
 		const refresh =
 			duration > 0
 				? setTimeout(
 						() =>
 							processCache(options, middlewareFetch, middlewareFetchRequest),
 						duration,
-					)
+					).unref()
 				: undefined;
-		cache[cacheKey] = { value, expiry, refresh };
+		cache.set(cacheKey, { value, expiry, refresh });
+		evictCache(cacheMaxSize);
 	}
 	return { value, expiry };
 };
@@ -189,27 +288,43 @@ export const catchInvalidSignatureException = (e, client, command) => {
 };
 
 export const getCache = (key) => {
-	if (!cache[key]) return {};
-	return cache[key];
+	return cache.get(key) ?? {};
 };
 
 // Used to remove parts of a cache
 export const modifyCache = (cacheKey, value) => {
-	if (!cache[cacheKey]) return;
-	clearTimeout(cache[cacheKey].refresh);
-	cache[cacheKey].value = value;
-	cache[cacheKey].modified = true;
+	const entry = cache.get(cacheKey);
+	if (!entry) return;
+	clearTimeout(entry.refresh);
+	entry.value = value;
+	entry.modified = true;
+};
+
+const evictCache = (maxSize) => {
+	if (cache.size <= maxSize) return;
+	let oldestKey = null;
+	let oldestExpiry = Infinity;
+	for (const [key, entry] of cache) {
+		if (entry && entry.expiry < oldestExpiry) {
+			oldestExpiry = entry.expiry;
+			oldestKey = key;
+		}
+	}
+	if (oldestKey !== null) {
+		clearTimeout(cache.get(oldestKey)?.refresh);
+		cache.delete(oldestKey);
+	}
 };
 
 export const clearCache = (inputKeys = null) => {
 	let keys = inputKeys;
-	keys ??= Object.keys(cache);
+	keys ??= [...cache.keys()];
 	if (!Array.isArray(keys)) {
 		keys = [keys];
 	}
 	for (const cacheKey of keys) {
-		clearTimeout(cache[cacheKey]?.refresh);
-		cache[cacheKey] = undefined;
+		clearTimeout(cache.get(cacheKey)?.refresh);
+		cache.delete(cacheKey);
 	}
 };
 
@@ -269,6 +384,9 @@ export const jsonSafeStringify = (value, replacer, space) => {
 	}
 };
 
+export const jsonContentTypePattern =
+	/^application\/([a-z0-9.+-]+\+)?json(;|$)/i;
+
 export const decodeBody = (event) => {
 	const { body, isBase64Encoded } = event;
 	if (typeof body === "undefined" || body === null) return body;
@@ -304,7 +422,10 @@ export class HttpError extends Error {
 		message ??= httpErrorCodes[code];
 		super(message, options);
 
-		const name = httpErrorCodes[code].replace(createErrorRegexp, "");
+		const name = (httpErrorCodes[code] ?? "Unknown").replace(
+			createErrorRegexp,
+			"",
+		);
 		this.name = !name.endsWith("Error") ? `${name}Error` : name;
 
 		this.status = this.statusCode = code; // setting `status` for backwards compatibility w/ `http-errors`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@middy/util",
-	"version": "7.2.2",
+	"version": "7.3.0",
 	"description": "🛵 The stylish Node.js middleware engine for AWS Lambda (util package)",
 	"type": "module",
 	"engines": {
@@ -17,9 +17,6 @@
 			"import": {
 				"types": "./index.d.ts",
 				"default": "./index.js"
-			},
-			"require": {
-				"default": "./index.js"
 			}
 		}
 	},
@@ -60,7 +57,7 @@
 	},
 	"devDependencies": {
 		"@aws-sdk/client-ssm": "^3.0.0",
-		"@middy/core": "7.2.2",
+		"@middy/core": "7.3.0",
 		"@types/aws-lambda": "^8.0.0",
 		"@types/node": "^22.0.0",
 		"aws-xray-sdk": "^3.3.3"