@63klabs/cache-data 1.3.4 → 1.3.6

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

@@ -1,11 +1,48 @@
 const RequestInfo = require('./RequestInfo.class');
 const Timer = require('./Timer.class');
 const DebugAndLog = require('./DebugAndLog.class');
+const { safeClone } = require('./utils');
 
 
 /**
  * Extends RequestInfo
  * Can be used to create a custom ClientRequest object
+ * @example
+ * // Initialize ClientRequest with validations
+ * ClientRequest.init({
+ *   validations: {
+ *     referrers: ['example.com', 'myapp.com'],
+ *     parameters: {
+ *       queryStringParameters: {
+ *         limit: (value) => !isNaN(value) && value > 0 && value <= 100,
+ *         page: (value) => !isNaN(value) && value > 0
+ *       },
+ *       pathParameters: {
+ *         id: (value) => /^[a-zA-Z0-9-]+$/.test(value)
+ *       }
+ *     }
+ *   }
+ * });
+ * 
+ * @example
+ * // Use in Lambda handler
+ * exports.handler = async (event, context) => {
+ *   const clientRequest = new ClientRequest(event, context);
+ *   
+ *   if (!clientRequest.isValid()) {
+ *     return { statusCode: 400, body: 'Invalid request' };
+ *   }
+ *   
+ *   const userId = clientRequest.getPathAt(1);
+ *   const queryParams = clientRequest.getQueryStringParameters();
+ *   
+ *   // Add logging for monitoring
+ *   clientRequest.addPathLog(`users/${userId}`);
+ *   clientRequest.addQueryLog(`limit=${queryParams.limit}`);
+ *   
+ *   // Process request...
+ *   return { statusCode: 200, body: 'Success' };
+ * };
  */
 class ClientRequest extends RequestInfo { 
 
@@ -22,7 +59,7 @@ class ClientRequest extends RequestInfo {
 	/* What and who of the request */
 	#event = null;
 	#context = null;
-	#authorizations = JSON.parse(JSON.stringify(ClientRequest.#unauthenticatedAuthorizations));
+	#authorizations = safeClone(ClientRequest.#unauthenticatedAuthorizations);
 	#roles = [];
 
 	/* The request data */
@@ -83,8 +120,8 @@ class ClientRequest extends RequestInfo {
 	 * This is used to initialize the ClientRequest class for all requests.
 	 * Add ClientRequest.init(options) to the Config.init process or at the
 	 * top of the main index.js file outside of the handler.
-	 * @param {Array<string>} options.validations.referrers An array of accepted referrers. String matching goes from right to left, so ['example.com'] will allow example.com and subdomain.example.com
-	 * @param {object} options.validations.parameters An object containing functions for validating request parameters (path, querystring, headers, cookies, etc).
+	 * @param {object} options - Configuration options with validations property containing referrers and parameters
+	 * @throws {Error} If options is not an object
 	 */
 	static init(options) {
 		if (typeof options === 'object') {
@@ -193,12 +230,8 @@ class ClientRequest extends RequestInfo {
 	}
 
 
-	/**
-	 * Utility function for getPathArray and getResourceArray
-	 * @param {array<string>} arr array to slice
-	 * @param {number} n number of elements to return
-	 * @returns {array<string>} array of elements
-	 */
+	// Utility function for getPathArray and getResourceArray
+	// Returns array slice based on n parameter
 	#getArray(arr, n = 0) {
 		if (n === 0 || arr.length <= n || (n < 0 && arr.length <= (n*-1))) {
 			return arr;
@@ -352,7 +385,7 @@ class ClientRequest extends RequestInfo {
 		if (this.isAuthenticated()) {
 			return this.#authorizations;
 		} else {
-			return JSON.parse(JSON.stringify(ClientRequest.#unauthenticatedAuthorizations));
+			return safeClone(ClientRequest.#unauthenticatedAuthorizations);
 		}
 	};
 

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

@@ -1,4 +1,5 @@
 const DebugAndLog = require('./DebugAndLog.class');
+const { safeClone } = require('./utils');
 
 
 /* ****************************************************************************
@@ -9,6 +10,30 @@ const DebugAndLog = require('./DebugAndLog.class');
  * 
  *************************************************************************** */
 
+/**
+ * @class Connections
+ * @property {object} _connections An object containing Connection objects
+ * @example
+ * // Create a Connections container with multiple connections
+ * const connections = new Connections([
+ *   { name: 'api', host: 'api.example.com', path: '/v1/users' },
+ *   { name: 'auth', host: 'auth.example.com', path: '/oauth/token' }
+ * ]);
+ * 
+ * // Get a specific connection
+ * const apiConnection = connections.get('api');
+ * const connectionObj = apiConnection.get();
+ * 
+ * @example
+ * // Add connections dynamically
+ * const connections = new Connections();
+ * connections.add({ name: 'database', host: 'db.example.com', path: '/query' });
+ * connections.add({ name: 'cache', host: 'cache.example.com', path: '/get' });
+ * 
+ * // Use with endpoint requests
+ * const dbConn = connections.get('database');
+ * const result = await endpoint.get(dbConn);
+ */
 class Connections {
 	
 	_connections = {};
@@ -84,6 +109,41 @@ class Connections {
  * that can then be used to generate and submit a request to a DAO class or 
  * APIRequest object.
  * You can store and manage multiple connections using the Connections object.
+ * @example
+ * // Create a simple connection
+ * const apiConnection = new Connection({
+ *   name: 'userAPI',
+ *   host: 'api.example.com',
+ *   path: '/v1/users',
+ *   method: 'GET'
+ * });
+ * 
+ * // Get connection object for use with endpoint
+ * const connObj = apiConnection.get();
+ * const users = await endpoint.get(connObj);
+ * 
+ * @example
+ * // Create connection with authentication
+ * const authConn = new Connection({
+ *   name: 'secureAPI',
+ *   host: 'secure.example.com',
+ *   path: '/api/data',
+ *   authentication: {
+ *     headers: { 'x-api-key': 'your-api-key' }
+ *   }
+ * });
+ * 
+ * @example
+ * // Create connection with cache configuration
+ * const cachedConn = new Connection({
+ *   name: 'cachedAPI',
+ *   host: 'api.example.com',
+ *   path: '/data',
+ *   cache: {
+ *     profile: 'default',
+ *     expirationInSeconds: 300
+ *   }
+ * });
  */
 class Connection {
 
@@ -150,7 +210,7 @@ class Connection {
 	 * @returns {Object}
 	 */
 	getParameters() {
-		let params = (this._parameters !== null) ? JSON.parse(JSON.stringify(this._parameters)) : null;
+		let params = (this._parameters !== null) ? safeClone(this._parameters) : null;
 
 		if ("parameters" in this._getAuthenticationObject()) {
 			if (params === null) { params = {}; }
@@ -166,7 +226,7 @@ class Connection {
 	 * @returns {Object}
 	 */
 	getHeaders() {
-		let headers = (this._headers !== null) ? JSON.parse(JSON.stringify(this._headers)) : null;
+		let headers = (this._headers !== null) ? safeClone(this._headers) : null;
 
 		if ("headers" in this._getAuthenticationObject()) {
 			if (headers === null) { headers = {}; }
@@ -204,11 +264,16 @@ class Connection {
 	 */
 	getCacheProfile( profileName ) {
 
+		if (this._cacheProfiles === null) {
+			return undefined;
+		}
+
 		function isProfile(item) {
 			return item.profile === profileName;
 		};
 
-		return JSON.parse(JSON.stringify(this._cacheProfiles.find(isProfile)));
+		const profile = this._cacheProfiles.find(isProfile);
+		return profile ? safeClone(profile) : undefined;
 	};
 
 	_setAuthentication(authentication) {
@@ -248,7 +313,10 @@ class Connection {
 		if ( parameters !== null ) { obj.parameters = parameters; }
 		if ( body !== null ) { obj.body = body; }
 
-		if ( this._authentication !== null ) { obj.authentication = this._authentication.toObject(); }
+		const authObj = this._getAuthenticationObject();
+		if ( Object.keys(authObj).length > 0 ) { obj.authentication = authObj; }
+
+		if ( this._cacheProfiles !== null ) { obj.cache = this._cacheProfiles; }
 
 		return obj;
 	};
@@ -288,14 +356,43 @@ class Connection {
  * Header, parameter, and/or Basic auth key/value pairs can be passed in. 
  * Additional methods could be added in the future.
  * 
- * new ConnectionAuthentication(
- * {
- *  headers: { x-key: "bsomeKeyForAHeaderField", x-user: "myUserID" },
- *  parameters: { apikey: "myExampleApiKeyForResource1234" },
- *  body: { key: "myExampleApiKeyForResource1283" },
- *  basic: { username: "myUsername", password: "myPassword" }
- * }
- * );
+ * @example
+ * // Create authentication with API key in header
+ * const auth = new ConnectionAuthentication({
+ *   headers: { 
+ *     'x-api-key': 'your-api-key-here',
+ *     'x-user-id': 'user123'
+ *   }
+ * });
+ * 
+ * @example
+ * // Create authentication with query parameters
+ * const auth = new ConnectionAuthentication({
+ *   parameters: { 
+ *     apikey: 'your-api-key',
+ *     token: 'auth-token'
+ *   }
+ * });
+ * 
+ * @example
+ * // Create authentication with Basic auth
+ * const auth = new ConnectionAuthentication({
+ *   basic: { 
+ *     username: 'myUsername',
+ *     password: 'myPassword'
+ *   }
+ * });
+ * 
+ * @example
+ * // Use with Connection
+ * const connection = new Connection({
+ *   name: 'secureAPI',
+ *   host: 'api.example.com',
+ *   path: '/secure/data',
+ *   authentication: new ConnectionAuthentication({
+ *     headers: { 'Authorization': 'Bearer token123' }
+ *   })
+ * });
  */
 class ConnectionAuthentication {
 
@@ -414,7 +511,7 @@ class ConnectionAuthentication {
 		let body = this._getBody();
 		if ( Object.keys(body).length ) { obj.body = body; }
 
-		return JSON.parse(JSON.stringify(obj));
+		return safeClone(obj);
 	};
 
 	// Static methods that could perform authentication could go here
@@ -428,6 +525,44 @@ class ConnectionAuthentication {
  * Connection by adding request specific parameters. While a Connection 
  * cannot be modified after creation (it is a config), a ClientRequest can be 
  * modified as the application or DAO assembles the request.
+ * @example
+ * // Create a connection request from a base connection
+ * const baseConnection = new Connection({
+ *   name: 'api',
+ *   host: 'api.example.com',
+ *   path: '/users'
+ * });
+ * 
+ * const request = new ConnectionRequest(baseConnection.get());
+ * 
+ * // Add dynamic headers
+ * request.addHeader('Authorization', `Bearer ${token}`);
+ * request.addHeader('X-Request-ID', requestId);
+ * 
+ * // Add query parameters
+ * request.addParameter('limit', 10);
+ * request.addParameter('page', 1);
+ * 
+ * // Make the request
+ * const result = await endpoint.get(request);
+ * 
+ * @example
+ * // Build a request dynamically in a DAO
+ * class UsersDAO {
+ *   static async getUser(userId, authToken) {
+ *     const request = new ConnectionRequest({
+ *       host: 'api.example.com',
+ *       path: `/users/${userId}`
+ *     });
+ *     
+ *     request.addHeaders({
+ *       'Authorization': `Bearer ${authToken}`,
+ *       'Content-Type': 'application/json'
+ *     });
+ *     
+ *     return await endpoint.get(request);
+ *   }
+ * }
  */
 class ConnectionRequest extends Connection {