@middy/util 7.2.3 → 7.3.1

package/index.d.ts

@@ -184,3 +184,88 @@ declare function lambdaContext(
 ): unknown;
 
 declare const httpErrorCodes: Record<number, string>;
+
+export type JsonSchemaType =
+	| "string"
+	| "number"
+	| "integer"
+	| "boolean"
+	| "object"
+	| "array";
+
+export type StringRule = {
+	type: "string";
+	pattern?: string;
+	minLength?: number;
+	maxLength?: number;
+	enum?: readonly string[];
+	examples?: readonly string[];
+};
+
+export type NumberRule = {
+	type: "number" | "integer";
+	minimum?: number;
+	maximum?: number;
+	enum?: readonly number[];
+	examples?: readonly number[];
+};
+
+export type BooleanRule = {
+	type: "boolean";
+	enum?: readonly boolean[];
+	examples?: readonly boolean[];
+};
+
+export type ArrayRule = {
+	type: "array";
+	items?: OptionSchemaRule;
+	examples?: readonly unknown[];
+};
+
+export type ObjectRule = {
+	type: "object";
+	required?: readonly string[];
+	properties?: { [key: string]: OptionSchemaRule };
+	additionalProperties?: boolean | OptionSchemaRule;
+	examples?: readonly object[];
+};
+
+export type EnumRule = {
+	enum: readonly unknown[];
+	type?: JsonSchemaType;
+	examples?: readonly unknown[];
+};
+
+export type ConstRule = {
+	const: unknown;
+	examples?: readonly unknown[];
+};
+
+export type InstanceofRule = {
+	instanceof: string;
+	examples?: readonly unknown[];
+};
+
+export type OneOfRule = {
+	oneOf: readonly OptionSchemaRule[];
+	examples?: readonly unknown[];
+};
+
+export type OptionSchemaRule =
+	| StringRule
+	| NumberRule
+	| BooleanRule
+	| ArrayRule
+	| ObjectRule
+	| EnumRule
+	| ConstRule
+	| InstanceofRule
+	| OneOfRule;
+
+export type OptionSchema = ObjectRule;
+
+export declare function validateOptions(
+	packageName: string,
+	schema: OptionSchema,
+	options?: Record<string, unknown>,
+): void;

package/index.js

@@ -1,5 +1,248 @@
 // Copyright 2017 - 2026 will Farrell, Luciano Mammino, and Middy contributors.
 // SPDX-License-Identifier: MIT
+
+// Option validation helper.
+// Schema values:
+//   'string' | 'number' | 'integer' | '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).
+//   { type: 'array' | 'array?', items: <itemSchema> }
+//     `items` is applied to each array element. It can be a type string,
+//     a predicate function, or a plain object treated as a per-element
+//     object schema (validated recursively with the same rules).
+//   { type: '<type>' | '<type>?', minimum?, maximum?, minLength?, maxLength?, pattern? }
+//     Numeric: `minimum`/`maximum` (number/integer).
+//     String: `minLength`/`maxLength` (string length), `pattern` (regex source).
+//   { type: 'object' | 'object?', properties?: {...}, additionalProperties?: <rule> }
+//     `properties` validates known keys with the flat-schema form.
+//     `additionalProperties` validates every other key's value against the
+//     given rule (string, predicate, or nested object schema). Without it,
+//     unknown keys throw.
+//   { enum: [...values], type?: '<type>' | '<type>?' }
+//     Value must strict-equal one of the listed values. Optional by default;
+//     combine with `type` to require a specific type and/or presence.
+// Keys in `options` (or nested objects) that are not in `schema` throw,
+// catching typos.
+const validateOptionsTypeCheckers = {
+	string: (v) => typeof v === "string",
+	number: (v) => typeof v === "number" && !Number.isNaN(v),
+	integer: (v) => Number.isInteger(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),
+};
+
+const isPlainObject = (v) =>
+	v !== null && typeof v === "object" && !Array.isArray(v);
+
+const checkSchemaObject = (schema, options, path, fail) => {
+	if (!isPlainObject(options)) {
+		fail(
+			path ? `Option '${path}' must be object` : "options must be an object",
+		);
+	}
+	for (const key of Object.keys(options)) {
+		if (!Object.hasOwn(schema, key)) {
+			fail(`Unknown option '${path ? `${path}.${key}` : key}'`);
+		}
+	}
+	for (const key of Object.keys(schema)) {
+		const childPath = path ? `${path}.${key}` : key;
+		checkRule(schema[key], options[key], childPath, fail);
+	}
+};
+
+// Returns true if type check passed (and value is defined), false if the
+// caller should stop validating (value was undefined and optional).
+const checkTypeSpec = (rawType, value, path, fail) => {
+	const optional = rawType.endsWith("?");
+	const type = optional ? rawType.slice(0, -1) : rawType;
+	const checker = validateOptionsTypeCheckers[type];
+	if (!checker) fail(`Unknown schema type '${type}' for option '${path}'`);
+	if (value === undefined) {
+		if (!optional) fail(`Missing required option '${path}' (${type})`);
+		return false;
+	}
+	if (!checker(value)) fail(`Option '${path}' must be ${type}`);
+	return true;
+};
+
+// Plain object with no rule-marker key (`type`, `enum`, `oneOf`, `const`,
+// `instanceof`) is a flat object schema; anything else is a rule. Used when
+// dispatching `items` and `additionalProperties`.
+const checkNestedRule = (rule, value, path, fail) => {
+	if (
+		isPlainObject(rule) &&
+		typeof rule.type !== "string" &&
+		!Array.isArray(rule.enum) &&
+		!Array.isArray(rule.oneOf) &&
+		!Object.hasOwn(rule, "const") &&
+		typeof rule.instanceof !== "string"
+	) {
+		checkSchemaObject(rule, value, path, fail);
+	} else {
+		checkRule(rule, value, path, fail);
+	}
+};
+
+const childPathOf = (path, key) => (path ? `${path}.${key}` : key);
+
+const resolveInstance = (name) => {
+	const ctor = globalThis[name];
+	if (typeof ctor !== "function") {
+		throw new Error(`Unknown 'instanceof' class '${name}'`);
+	}
+	return ctor;
+};
+
+const checkRule = (rule, value, path, fail) => {
+	if (typeof rule === "function") {
+		if (value !== undefined && !rule(value)) {
+			fail(`Invalid option '${path}'`);
+		}
+		return;
+	}
+	if (typeof rule === "string") {
+		checkTypeSpec(rule, value, path, fail);
+		return;
+	}
+	if (isPlainObject(rule) && Object.hasOwn(rule, "const")) {
+		if (value === undefined) return;
+		if (value !== rule.const) {
+			fail(`Option '${path}' must equal ${JSON.stringify(rule.const)}`);
+		}
+		return;
+	}
+	if (isPlainObject(rule) && Array.isArray(rule.oneOf)) {
+		if (value === undefined) return;
+		let matches = 0;
+		for (const sub of rule.oneOf) {
+			try {
+				checkRule(sub, value, path, (msg) => {
+					throw new TypeError(msg);
+				});
+				matches++;
+			} catch {}
+		}
+		if (matches !== 1) {
+			fail(`Option '${path}' must match exactly one schema in oneOf`);
+		}
+		return;
+	}
+	if (isPlainObject(rule) && typeof rule.instanceof === "string") {
+		if (value === undefined) return;
+		const ctor = resolveInstance(rule.instanceof);
+		if (!(value instanceof ctor)) {
+			fail(`Option '${path}' must be instanceof ${rule.instanceof}`);
+		}
+		return;
+	}
+	if (isPlainObject(rule) && Array.isArray(rule.enum)) {
+		if (typeof rule.type === "string") {
+			if (!checkTypeSpec(rule.type, value, path, fail)) return;
+		} else if (value === undefined) {
+			return;
+		}
+		if (!rule.enum.includes(value)) {
+			fail(`Option '${path}' must be one of ${JSON.stringify(rule.enum)}`);
+		}
+		return;
+	}
+	if (isPlainObject(rule) && typeof rule.type === "string") {
+		const {
+			type: rawType,
+			items,
+			properties,
+			required,
+			additionalProperties,
+			minimum,
+			maximum,
+			pattern,
+			minLength,
+			maxLength,
+		} = rule;
+		if (!checkTypeSpec(rawType, value, path, fail)) return;
+		const type = rawType.endsWith("?") ? rawType.slice(0, -1) : rawType;
+		if (minimum !== undefined && value < minimum) {
+			fail(`Option '${path}' must be >= ${minimum}`);
+		}
+		if (maximum !== undefined && value > maximum) {
+			fail(`Option '${path}' must be <= ${maximum}`);
+		}
+		if (pattern !== undefined && !new RegExp(pattern).test(value)) {
+			fail(`Option '${path}' must match pattern ${pattern}`);
+		}
+		if (minLength !== undefined && value.length < minLength) {
+			fail(`Option '${path}' must have length >= ${minLength}`);
+		}
+		if (maxLength !== undefined && value.length > maxLength) {
+			fail(`Option '${path}' must have length <= ${maxLength}`);
+		}
+		if (type === "array" && items !== undefined) {
+			for (let i = 0; i < value.length; i++) {
+				checkNestedRule(items, value[i], `${path}[${i}]`, fail);
+			}
+		}
+		if (type === "object" && Array.isArray(required)) {
+			for (const key of required) {
+				if (value[key] === undefined) {
+					fail(`Missing required option '${childPathOf(path, key)}'`);
+				}
+			}
+		}
+		if (
+			type === "object" &&
+			(properties || additionalProperties !== undefined)
+		) {
+			for (const key of Object.keys(value)) {
+				if (properties && Object.hasOwn(properties, key)) continue;
+				if (
+					additionalProperties === undefined ||
+					additionalProperties === false
+				) {
+					fail(`Unknown option '${childPathOf(path, key)}'`);
+				}
+				if (additionalProperties === true) continue;
+				checkNestedRule(
+					additionalProperties,
+					value[key],
+					childPathOf(path, key),
+					fail,
+				);
+			}
+			if (properties) {
+				for (const key of Object.keys(properties)) {
+					if (value[key] === undefined) continue;
+					checkRule(properties[key], value[key], childPathOf(path, key), fail);
+				}
+			}
+		}
+		return;
+	}
+	fail(`Invalid schema for option '${path}'`);
+};
+
+const isJsonSchemaForm = (schema) =>
+	isPlainObject(schema) &&
+	schema.type === "object" &&
+	(Object.hasOwn(schema, "properties") ||
+		Object.hasOwn(schema, "required") ||
+		Object.hasOwn(schema, "additionalProperties"));
+
+export const validateOptions = (packageName, schema, options = {}) => {
+	const fail = (message) => {
+		throw new TypeError(message, { cause: { package: packageName } });
+	};
+	if (isJsonSchemaForm(schema)) {
+		checkRule(schema, options, "", fail);
+	} else {
+		checkSchemaObject(schema, options, "", fail);
+	}
+	return options;
+};
+
 export const createPrefetchClient = (options) => {
 	const { awsClientOptions } = options;
 	const client = new options.AwsClient(awsClientOptions);
@@ -139,7 +382,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 +419,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 +436,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 +461,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 +474,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.1",
 	"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.1",
 		"@types/aws-lambda": "^8.0.0",
 		"@types/node": "^22.0.0",
 		"aws-xray-sdk": "^3.3.3"