@63klabs/cache-data 1.3.9 → 1.3.10

package/src/lib/tools/ClientRequest.class.js

@@ -401,6 +401,7 @@ class ClientRequest extends RequestInfo {
 	
 	/* Validation system */
 	#validationMatchers = {};
+	#validationReason = { isValid: true, statusCode: 200, messages: [] };
 
 	/* The request data */
 	#props = {};
@@ -470,6 +471,10 @@ class ClientRequest extends RequestInfo {
 			bodyParameters: {},
 			bodyPayload: this.#event?.body || null, // from body
 			client: {
+				ip: this.getClientIp(),
+				userAgent: this.getClientUserAgent(),
+				origin: this.getClientOrigin(),
+				referrer: this.getClientReferrer(),
 				isAuthenticated: this.isAuthenticated(),
 				isGuest: this.isGuest(),
 				authorizations: this.getAuthorizations(),
@@ -698,7 +703,7 @@ class ClientRequest extends RequestInfo {
 	 * Parameter validations
 	 * @returns {{
 	 * 	pathParameters?: object,
-	 * 	queryParameters?: object,
+	 * 	queryStringParameters?: object,
 	 * 	headerParameters?: object,
 	 * 	cookieParameters?: object,
 	 * 	bodyParameters?: object
@@ -755,25 +760,129 @@ class ClientRequest extends RequestInfo {
 	 */
 	#validate() {
 	
-		let valid = false;
+		const reasons = [];
+		let statusCode = 200;
+
+		// Referrer check
+		const referrerValid = this.isAuthorizedReferrer();
+		if (!referrerValid) {
+			reasons.push("Forbidden");
+			statusCode = this.#upgradeStatusCode(statusCode, 403);
+		}
+
+		// Authentication check
+		const authFailed = this.hasNoAuthorization();
+		if (authFailed) {
+			reasons.push("Unauthorized");
+			statusCode = this.#upgradeStatusCode(statusCode, 401);
+		}
+
+		// Parameter checks - collect invalid parameter names from each
+		const pathResult = this.#hasValidPathParameters();
+		const queryResult = this.#hasValidQueryStringParameters();
+		const headerResult = this.#hasValidHeaderParameters();
+		const cookieResult = this.#hasValidCookieParameters();
+		const bodyResult = this.#hasValidBodyParameters();
+
+		// Collect invalid parameter messages
+		const paramResults = [pathResult, queryResult, headerResult, cookieResult, bodyResult];
+		for (const result of paramResults) {
+			if (result.invalidParams) {
+				for (const paramName of result.invalidParams) {
+					reasons.push(`Invalid parameter: ${paramName}`);
+					statusCode = this.#upgradeStatusCode(statusCode, 400);
+				}
+			}
+		}
 
-		// add your additional validations here
-		valid = this.isAuthorizedReferrer() && this.#hasValidPathParameters() && this.#hasValidQueryStringParameters() && this.#hasValidHeaderParameters() && this.#hasValidCookieParameters() && this.#hasValidBodyParameters();
+		// Handle invalid JSON body
+		if (bodyResult.invalidBody) {
+			reasons.push("Invalid request body");
+			statusCode = this.#upgradeStatusCode(statusCode, 400);
+		}
 
-		// set the variable
+		// Compute combined valid boolean from all check results
+		const valid = referrerValid && !authFailed
+			&& pathResult.isValid && queryResult.isValid && headerResult.isValid
+			&& cookieResult.isValid && bodyResult.isValid;
+
+		// Preserve backwards compatibility
 		super._isValid = valid;
 
+		// Populate validation reason
+		this.#validationReason = {
+			isValid: valid,
+			statusCode: valid ? 200 : statusCode,
+			messages: valid ? [] : reasons
+		};
+
 	};
 
+	/**
+	 * Returns the higher-priority HTTP status code between two candidates.
+	 * Priority order: 401 > 403 > 400 > 200.
+	 *
+	 * @private
+	 * @param {number} current - The current status code
+	 * @param {number} candidate - The candidate status code to compare
+	 * @returns {number} The status code with higher priority
+	 */
+	#upgradeStatusCode(current, candidate) {
+		const priority = { 401: 3, 403: 2, 400: 1, 200: 0 };
+		return (priority[candidate] || 0) > (priority[current] || 0) ? candidate : current;
+	};
+
+	/**
+	 * Returns a structured validation result object describing why the request
+	 * passed or failed validation. The object includes the validation status,
+	 * an appropriate HTTP status code, and descriptive messages identifying
+	 * each failure.
+	 * 
+	 * A new object is returned on each call to prevent external mutation of
+	 * internal state.
+	 * 
+	 * @returns {{ isValid: boolean, statusCode: number, messages: Array<string> }}
+	 *   A new object on each call containing:
+	 *   - isValid: whether the request passed all validation checks
+	 *   - statusCode: the appropriate HTTP status code (200, 400, 401, or 403)
+	 *   - messages: array of descriptive failure messages (empty when valid)
+	 * @example
+	 * // Valid request
+	 * const reason = clientRequest.getValidationReason();
+	 * // { isValid: true, statusCode: 200, messages: [] }
+	 *
+	 * @example
+	 * // Invalid request with bad parameters
+	 * const reason = clientRequest.getValidationReason();
+	 * // { isValid: false, statusCode: 400, messages: ["Invalid parameter: limit"] }
+	 */
+	getValidationReason() {
+		return {
+			isValid: this.#validationReason.isValid,
+			statusCode: this.#validationReason.statusCode,
+			messages: [...this.#validationReason.messages]
+		};
+	}
+
 	/**
 	 * Validate parameters using ValidationMatcher and ValidationExecutor.
 	 * 
 	 * This method implements the core parameter validation logic:
 	 * 1. Uses ValidationMatcher to find the best matching validation rule (4-tier priority)
 	 * 2. Uses ValidationExecutor to execute validation with appropriate interface (single or multi-parameter)
-	 * 3. Extracts validated parameters and returns them
+	 * 3. Extracts ALL validated parameters specified in the matching rule and returns them
 	 * 4. Respects excludeParamsWithNoValidationMatch flag (default: true)
 	 * 
+	 * When a validation rule matches and validation passes, ALL parameters specified in rule.params
+	 * are extracted from clientParameters and included in the returned params object. This ensures
+	 * that multi-parameter validation rules (e.g., validating query?param1,param2 together) correctly
+	 * extract all validated parameters, not just the one that triggered the rule match.
+	 * 
+	 * For single-parameter validation with multi-placeholder routes (e.g., users/{userId}/posts/{id}):
+	 * - ValidationMatcher returns validateParam field indicating which parameter to validate
+	 * - ValidationExecutor validates only that parameter with single-parameter interface
+	 * - This method extracts ALL parameters from rule.params array (e.g., both userId and id)
+	 * 
 	 * @private
 	 * @param {Object} paramValidations - Parameter validation configuration (may include BY_ROUTE, BY_METHOD, and global validations)
 	 * @param {Object} clientParameters - Parameters from the request (path, query, header, or cookie parameters)
@@ -791,12 +900,25 @@ class ClientRequest extends RequestInfo {
 
 		let rValue = {
 			isValid: true,
-			params: {}
+			params: {},
+			invalidParams: []
 		}
 	
-		if (clientParameters && paramValidations) {
+		if (clientParameters) {
 			// >! Check excludeParamsWithNoValidationMatch flag (default: true)
 			const excludeUnmatched = ClientRequest.#validations.parameters?.excludeParamsWithNoValidationMatch !== false;
+
+			// >! When no validation rules exist for this parameter type,
+			// >! pass through all parameters if excludeUnmatched is false
+			if (!paramValidations) {
+				if (!excludeUnmatched) {
+					rValue.params = { ...clientParameters };
+				}
+				return rValue;
+			}
+			
+			// >! Track which parameters have been validated to avoid duplicate validation
+			const validatedParams = new Set();
 			
 			// >! Create normalized parameter map for validation execution
 			// >! Include ALL parameter types so multi-parameter validations can access them
@@ -841,12 +963,20 @@ class ClientRequest extends RequestInfo {
 				normalizedParams[normalizedKey] = value;
 			}
 			
+			// >! Collect valid params separately so we can clear them if any fail
+			const collectedParams = {};
+
 			// Use a for...of loop instead of forEach for better control flow
 			for (const [key, value] of Object.entries(clientParameters)) {
 				// >! Preserve existing parameter key normalization
 				const paramKey = key.replace(/^\/|\/$/g, '');
 				const paramValue = value;
 				
+				// >! Skip parameters that have already been validated
+				if (validatedParams.has(paramKey)) {
+					continue;
+				}
+				
 				// >! Use ValidationMatcher to find the best matching validation rule
 				const rule = validationMatcher.findValidationRule(paramKey);
 				
@@ -856,22 +986,41 @@ class ClientRequest extends RequestInfo {
 					const isValid = ValidationExecutor.execute(rule.validate, rule.params, normalizedParams);
 					
 					if (isValid) {
-						rValue.params[paramKey] = paramValue;
+						// >! Extract ALL parameters specified in rule.params when validation passes
+						// >! This fixes the bug where only the current paramKey was added
+						for (const ruleParamName of rule.params) {
+							// >! Find the parameter value in clientParameters
+							// >! Use normalized key matching to handle case differences
+							const normalizedRuleParam = ruleParamName.replace(/^\/|\/$/g, '');
+							
+							// >! Search for matching parameter in clientParameters
+							for (const [clientKey, clientValue] of Object.entries(clientParameters)) {
+								const normalizedClientKey = clientKey.replace(/^\/|\/$/g, '');
+								
+								if (normalizedClientKey === normalizedRuleParam) {
+									collectedParams[clientKey] = clientValue;
+									// >! Mark this parameter as validated to avoid duplicate validation
+									validatedParams.add(normalizedClientKey);
+									break;
+								}
+							}
+						}
 					} else {
 						// >! Maintain existing logging for invalid parameters
 						DebugAndLog.warn(`Invalid parameter: ${paramKey} = ${paramValue}`);
 						rValue.isValid = false;
-						rValue.params = {};
-						// >! Ensure early exit on validation failure
-						return rValue;
+						rValue.invalidParams.push(paramKey);
 					}
 				} else if (!excludeUnmatched) {
 					// No validation rule found, but excludeUnmatched is false
 					// Include parameter without validation
-					rValue.params[paramKey] = paramValue;
+					collectedParams[paramKey] = paramValue;
 				}
 				// If excludeUnmatched is true and no rule found, skip parameter (existing behavior)
 			}
+
+			// >! If any parameter failed, clear params (preserves existing behavior)
+			rValue.params = rValue.isValid ? collectedParams : {};
 		}	
 		return rValue;
 	}
@@ -889,13 +1038,13 @@ class ClientRequest extends RequestInfo {
 	 * const isValid = #hasValidPathParameters();
 	 */
 	#hasValidPathParameters() {
-		const { isValid, params } = this.#hasValidParameters(
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
 			ClientRequest.getParameterValidations()?.pathParameters,
 			this.#event?.pathParameters,
 			this.#validationMatchers.pathParameters
 		);
 		this.#props.pathParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
 	/**
@@ -923,13 +1072,13 @@ class ClientRequest extends RequestInfo {
 		const paramValidations = ClientRequest.getParameterValidations();
 		const queryValidations = paramValidations?.queryStringParameters || paramValidations?.queryParameters;
 		
-		const { isValid, params } = this.#hasValidParameters(
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
 			queryValidations,
 			qs,
 			this.#validationMatchers.queryStringParameters
 		);
 		this.#props.queryStringParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
 	/**
@@ -977,23 +1126,23 @@ class ClientRequest extends RequestInfo {
 				const camelCaseKey = key.toLowerCase().replace(/-([a-z])/g, (g) => g[1].toUpperCase());
 				headers[camelCaseKey] = this.#event.headers[key];
 			}
-			const { isValid, params } = this.#hasValidParameters(
+			const { isValid, params, invalidParams } = this.#hasValidParameters(
 				ClientRequest.getParameterValidations()?.headerParameters,
 				headers,
 				this.#validationMatchers.headerParameters
 			);
 			this.#props.headerParameters = params;
-			return isValid;
+			return { isValid, invalidParams };
 		}
 
 	#hasValidCookieParameters() {
-		const { isValid, params } = this.#hasValidParameters(
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
 			ClientRequest.getParameterValidations()?.cookieParameters,
 			this.#event?.cookie,
 			this.#validationMatchers.cookieParameters
 		);
 		this.#props.cookieParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
 	/**
@@ -1028,12 +1177,12 @@ class ClientRequest extends RequestInfo {
 					error?.stack
 				);
 				this.#props.bodyParameters = {};
-				return false;
+				return { isValid: false, invalidParams: [], invalidBody: true };
 			}
 		}
 
 		// >! Use existing validation framework with body validation matcher
-		const { isValid, params } = this.#hasValidParameters(
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
 			ClientRequest.getParameterValidations()?.bodyParameters,
 			bodyObject,
 			this.#validationMatchers.bodyParameters
@@ -1041,7 +1190,7 @@ class ClientRequest extends RequestInfo {
 
 		// >! Store validated parameters
 		this.#props.bodyParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
 
@@ -1252,7 +1401,7 @@ class ClientRequest extends RequestInfo {
 	 * Get the _processed_ request properties. These are the properties that
 	 * the ClientRequest object took from the event sent to Lambda, validated,
 	 * supplemented, and makes available to controllers. 
-	 * @returns {{ method: string, path: string, pathArray: string[], resource: string, resourceArray[], pathParameters: {}, queryStringParameters: {}, headerParameters: {}, cookieParameters: {}, bodyPayload: string, client: {isAuthenticated: boolean, isGuest: boolean, authorizations: string[], roles: string[]}, deadline: number, calcMsToDeadline: number}
+	 * @returns {{ method: string, path: string, pathArray: string[], resource: string, resourceArray[], pathParameters: {}, queryStringParameters: {}, headerParameters: {}, cookieParameters: {}, bodyParameters: {}, bodyPayload: string, client: {ip: string, userAgent: string, origin: string, referrer: string, isAuthenticated: boolean, isGuest: boolean, authorizations: string[], roles: string[]}, deadline: number, calcMsToDeadline: number}
 	 */
 	getProps() {
 		return this.#props;

package/src/lib/tools/Connections.classes.js

@@ -32,7 +32,7 @@ const { safeClone } = require('./utils');
  * 
  * // Use with endpoint requests
  * const dbConn = connections.get('database');
- * const result = await endpoint.get(dbConn);
+ * const result = await endpoint.send(dbConn);
  */
 class Connections {
 	
@@ -132,7 +132,7 @@ class Connections {
  * The Connection object provides the base for requests but does not carry
  * the request. myConnection.get() will return an object (associative array) 
  * that can then be used to generate and submit a request to a DAO class or 
- * APIRequest object.
+ * ApiRequest object.
  * You can store and manage multiple connections using the Connections object.
  * @example
  * // Create a simple connection
@@ -145,7 +145,7 @@ class Connections {
  * 
  * // Get connection object for use with endpoint
  * const connObj = apiConnection.get();
- * const users = await endpoint.get(connObj);
+ * const users = await endpoint.send(connObj);
  * 
  * @example
  * // Create connection with authentication
@@ -581,7 +581,7 @@ class ConnectionAuthentication {
  * request.addParameter('page', 1);
  * 
  * // Make the request
- * const result = await endpoint.get(request);
+ * const result = await endpoint.send(request);
  * 
  * @example
  * // Build a request dynamically in a DAO
@@ -597,7 +597,7 @@ class ConnectionAuthentication {
  *       'Content-Type': 'application/json'
  *     });
  *     
- *     return await endpoint.get(request);
+ *     return await endpoint.send(request);
  *   }
  * }
  */

package/src/lib/tools/Response.class.js

@@ -525,6 +525,31 @@ class Response {
 		}
 	};
 
+	/**
+	 * Sets a message or messages property on the JSON response body.
+	 * If the body is not a JSON object, this method is a no-op.
+	 * Does not alter the status code or headers.
+	 *
+	 * @param {string|Array<string>} message - A single message string or array of message strings
+	 * @returns {void}
+	 * @example
+	 * // Single message
+	 * response.setMessage("Invalid parameter: limit");
+	 * // body becomes: { ...existingBody, message: "Invalid parameter: limit" }
+	 *
+	 * @example
+	 * // Multiple messages
+	 * response.setMessage(["Invalid parameter: limit", "Invalid parameter: offset"]);
+	 * // body becomes: { ...existingBody, messages: ["Invalid parameter: limit", "Invalid parameter: offset"] }
+	 */
+	setMessage = (message) => {
+		if (Array.isArray(message)) {
+			this.addToJsonBody({ messages: message });
+		} else {
+			this.addToJsonBody({ message: message });
+		}
+	};
+
 	/**
 	 * Converts the response to a plain object.
 	 * 

package/src/lib/tools/generic.response.html.js

@@ -1,121 +1,16 @@
-contentType = "text/html; charset=utf-8";
+const { createGenericResponseModule } = require("./generic.response");
 
-headers = {
-	"Content-Type": contentType
-};
-
-html = (title, body) => {
+const html = (title, body) => {
 	return `<html><head><title>${title}</title></head><body>${body}</body></html>`;
-}
-
-response200 = {
-	statusCode: 200,
-	headers: headers,
-	body: html("200 OK", "<p>Success</p>")
-};
-
-response400 = {
-	statusCode: 400,
-	headers: headers,
-	body: html("400 Bad Request", "<p>Bad Request</p>")
-};
-
-response401 = {
-	statusCode: 401,
-	headers: headers,
-	body: html("401 Unauthorized", "<p>Unauthorized</p>")
-};
-
-response403 = {
-	statusCode: 403,
-	headers: headers,
-	body: html("403 Forbidden", "<p>Forbidden</p>")
-};
-
-response404 = {
-	statusCode: 404,
-	headers: headers,
-	body: html("404 Not Found", "<p>Not Found</p>")
-};
-
-response405 = {
-	statusCode: 405,
-	headers: headers,
-	body: html("405 Method Not Allowed", "<p>Method Not Allowed</p>")
-};
-
-response408 = {
-	statusCode: 408,
-	headers: headers,
-	body: html("408 Request Timeout", "<p>Request Timeout</p>")
 };
 
-response418 = {
-	statusCode: 418,
-	headers: headers,
-	body: html("418 I'm a teapot", "<p>I'm a teapot</p>")
+const HTML_TITLE_MAP = {
+	200: "OK",
+	500: "Error"
 };
 
-response427 = {
-	statusCode: 427,
-	headers: headers,
-	body: html("427 Too Many Requests", "<p>Too Many Requests</p>")
-};
-
-response500 = {
-	statusCode: 500,
-	headers: headers,
-	body: html("500 Error", "<p>Internal Server Error</p>")
-};
+const htmlBodyFormatter = (statusCode, message) => html(statusCode + " " + (HTML_TITLE_MAP[statusCode] || message), "<p>" + message + "</p>");
 
-/**
- * 
- * @param {number|string} statusCode 
- * @returns {{statusCode: number, headers: object, body: Array|Object|string}}
- */
-response = function (statusCode) {
-	// convert to int
-	statusCode = parseInt(statusCode, 10);
-
-	switch (statusCode) {
-		case 200:
-			return this.response200;
-		case 400:
-			return this.response400;
-		case 401:
-			return this.response401;
-		case 403:
-			return this.response403;
-		case 404:
-			return this.response404;
-		case 405:
-			return this.response405;
-		case 408:
-			return this.response408;
-		case 418:
-			return this.response418;
-		case 427:
-			return this.response427;
-		case 500:
-			return this.response500;
-		default:
-			return this.response500;
-	}
-};
+const mod = createGenericResponseModule("text/html; charset=utf-8", htmlBodyFormatter);
 
-module.exports = {
-	contentType,
-	headers,
-	html,
-	response200,
-	response400,
-	response401,
-	response403,
-	response404,
-	response405,
-	response408,
-	response418,
-	response427,
-	response500,
-	response
-}
+module.exports = { ...mod, html };

package/src/lib/tools/generic.response.js

@@ -0,0 +1,73 @@
+/**
+ * Centralized generic response module factory.
+ *
+ * Encapsulates the shared STATUS_CODE_MAP, response object generation, and
+ * response() lookup function used by all five format-specific generic response
+ * files (HTML, JSON, RSS, Text, XML).
+ *
+ * @module generic.response
+ */
+
+/**
+ * Map of HTTP status codes to their default message strings.
+ *
+ * @type {Object.<number, string>}
+ */
+const STATUS_CODE_MAP = {
+	200: "Success",
+	400: "Bad Request",
+	401: "Unauthorized",
+	403: "Forbidden",
+	404: "Not Found",
+	405: "Method Not Allowed",
+	408: "Request Timeout",
+	418: "I'm a teapot",
+	427: "Too Many Requests",
+	500: "Internal Server Error"
+};
+
+/**
+ * Create a complete generic response module for a given content type and body formatter.
+ *
+ * Iterates over STATUS_CODE_MAP, calls bodyFormatter(statusCode, message) for each
+ * entry, and builds the response objects. Attaches a response() function that parses
+ * the status code to an integer and looks up the matching response object, falling
+ * back to response500 for unknown codes.
+ *
+ * @param {string} contentType - MIME content type string (e.g., "application/json")
+ * @param {function(number, string): *} bodyFormatter - Function that transforms (statusCode, message) into format-specific body
+ * @returns {{contentType: string, headers: Object, response200: Object, response400: Object, response401: Object, response403: Object, response404: Object, response405: Object, response408: Object, response418: Object, response427: Object, response500: Object, response: function(number|string): Object}}
+ * @example
+ * const { createGenericResponseModule } = require("./generic.response");
+ *
+ * const mod = createGenericResponseModule("application/json", (statusCode, message) => ({ message }));
+ * console.log(mod.response200.body); // { message: "Success" }
+ * console.log(mod.response(404).statusCode); // 404
+ */
+function createGenericResponseModule(contentType, bodyFormatter) {
+	const headers = { "Content-Type": contentType };
+
+	const mod = {
+		contentType: contentType,
+		headers: headers
+	};
+
+	for (const code in STATUS_CODE_MAP) {
+		const statusCode = parseInt(code, 10);
+		const message = STATUS_CODE_MAP[code];
+		mod["response" + statusCode] = {
+			statusCode: statusCode,
+			headers: headers,
+			body: bodyFormatter(statusCode, message)
+		};
+	}
+
+	mod.response = function (statusCode) {
+		statusCode = parseInt(statusCode, 10);
+		return this["response" + statusCode] || this.response500;
+	};
+
+	return mod;
+}
+
+module.exports = { createGenericResponseModule };