@middy/util 7.2.3 → 7.3.0

package/index.d.ts

@@ -184,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,7 +209,10 @@ 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) => {
@@ -173,8 +246,9 @@ 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;
@@ -189,16 +263,18 @@ export const processCache = (
 	const expiry = cacheExpiry > 86400000 ? cacheExpiry : now + cacheExpiry;
 	const duration = cacheExpiry > 86400000 ? cacheExpiry - now : cacheExpiry;
 	if (cacheExpiry) {
-		clearTimeout(cache[cacheKey]?.refresh);
+		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 };
@@ -212,13 +288,12 @@ 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) => {
-	const entry = cache[cacheKey];
+	const entry = cache.get(cacheKey);
 	if (!entry) return;
 	clearTimeout(entry.refresh);
 	entry.value = value;
@@ -226,32 +301,30 @@ export const modifyCache = (cacheKey, value) => {
 };
 
 const evictCache = (maxSize) => {
-	const cacheKeys = Object.keys(cache);
-	if (cacheKeys.length <= maxSize) return;
+	if (cache.size <= maxSize) return;
 	let oldestKey = null;
 	let oldestExpiry = Infinity;
-	for (const key of cacheKeys) {
-		const entry = cache[key];
+	for (const [key, entry] of cache) {
 		if (entry && entry.expiry < oldestExpiry) {
 			oldestExpiry = entry.expiry;
 			oldestKey = key;
 		}
 	}
-	if (oldestKey) {
-		clearTimeout(cache[oldestKey]?.refresh);
-		cache[oldestKey] = undefined;
+	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);
 	}
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@middy/util",
-	"version": "7.2.3",
+	"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.3",
+		"@middy/core": "7.3.0",
 		"@types/aws-lambda": "^8.0.0",
 		"@types/node": "^22.0.0",
 		"aws-xray-sdk": "^3.3.3"