@63klabs/cache-data 1.3.5 → 1.3.7

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

@@ -1,33 +1,27 @@
-
-/* ****************************************************************************
- * Response Data Model
- * ----------------------------------------------------------------------------
- * 
- * Provides a class that can be used to store and complie data to send back
- * as a response.
- * 
- *************************************************************************** */
+const { safeClone } = require('./utils');
 
 /**
- * A response object that can be used to collect data to be sent back as a response.
- * A structured skeleton may be created during construction to create an order of
- * presenting various keys. As the program executes, additional data may be added.
- * Other response objects may be added with keys to fill out the object. If there are
- * key collisions then new items matching that key are added as an element in an array.
+ * ResponseDataModel class for collecting and structuring response data.
+ * Provides methods to build complex response objects by adding items with keys or as array elements.
+ * Supports creating structured skeletons during construction and filling them during execution.
+ * Handles key collisions by converting single values to arrays when duplicate keys are added.
  * 
- * Extends ResponseDataModel, can be used to extend as an interface.
+ * @class ResponseDataModel
+ * @example
+ * // Create response with skeleton
+ * const response = new ResponseDataModel({ users: [], metadata: {} }, 'data');
+ * response.addItemByKey({ id: 1, name: 'John' }, 'users');
+ * response.addItemByKey({ id: 2, name: 'Jane' }, 'users');
+ * console.log(response.toString());
+ * // Output: {"data":{"users":[{"id":1,"name":"John"},{"id":2,"name":"Jane"}],"metadata":{}}}
  * 
  * @example
- * let obj = new Response(); // you can pass a skeleton that you will add to, or the full object to the constructor
- * obj.addItem(newItem); // where newItem is another response object or regular structured object which will be added as a node
- * obj.addItemByKey(newItem2,"employees");// where newItem2 is another response object or regular structured object which will be added as a node. Note that you can override a label by passing a new one. For example pluralizing a label
- * obj.removeEmpty(); // optional, it will remove empty keys
- * 	response = {
- * 		statusCode: 200,
- * 		body: dataResponse.toString(),
- * 		headers: {'content-type': 'application/json'}
- * 	};
- *
+ * // Add items to array
+ * const list = new ResponseDataModel(null, 'items');
+ * list.addItem({ id: 1 });
+ * list.addItem({ id: 2 });
+ * console.log(list.toString());
+ * // Output: {"items":[{"id":1},{"id":2}]}
  */
 class ResponseDataModel {
 
@@ -35,10 +29,18 @@ class ResponseDataModel {
 	_label = "";
 
 	/**
-	 * Used for collecting parts of a response. A data skeleton may be passed in as an object.
+	 * Creates a new ResponseDataModel instance for collecting response data.
+	 * A data skeleton may be passed in with various fields set to {}, [], "", null, or default values.
 	 * 
-	 * @param {*} data Can be a skeleton with various fields set to {}, [], "", null or defaults.
-	 * @param {*} label 
+	 * @param {*} [data=null] - Initial data structure (can be a skeleton or complete object)
+	 * @param {string} [label=""] - Label to use as a key when this object is added to another ResponseDataModel
+	 * @example
+	 * // Create with skeleton
+	 * const response = new ResponseDataModel({ users: [], count: 0 }, 'data');
+	 * 
+	 * @example
+	 * // Create empty
+	 * const response = new ResponseDataModel();
 	 */
 	constructor(data = null, label = "") {
 		if (data !== null) {
@@ -51,28 +53,48 @@ class ResponseDataModel {
 	};
 	
 	/**
-	 * Get the label that will be used when this object is added to another 
-	 * ResponseDataModel or returned as a response
-	 * @returns {string} a label to use as a key for the object
+	 * Gets the label that will be used when this object is added to another ResponseDataModel.
+	 * 
+	 * @returns {string} The label to use as a key for the object
+	 * @example
+	 * const response = new ResponseDataModel({ id: 1 }, 'user');
+	 * console.log(response.getLabel()); // 'user'
 	 */
 	getLabel() {
 		return this._label;
 	};
 
 	/**
-	 * Get the data object
-	 * @returns {*} A copy of the data object
+	 * Gets a copy of the response data object.
+	 * 
+	 * @returns {*} A cloned copy of the data object
+	 * @example
+	 * const data = response.getResponseData();
+	 * console.log(data);
 	 */
 	getResponseData() {
-		return JSON.parse(JSON.stringify(this._responseData));
+		return safeClone(this._responseData);
 	};
 
 	/**
-	 * Add an item as part of an array.
-	 * If the responseObject is null, it will be transformed into an array and the item will be added at index 0
-	 * If the responseObject is an array, the item will be added as the next index
-	 * If the responseObject is an object, the item will be added as an array element under the label (or 'items' if label is "")
-	 * @param {ResponseDataModel|*} item 
+	 * Adds an item as part of an array or under a labeled key.
+	 * - If responseData is null, transforms it into an array and adds item at index 0
+	 * - If responseData is an array, adds item as the next element
+	 * - If responseData is an object, adds item as an array element under the label (or 'items' if no label)
+	 * 
+	 * @param {ResponseDataModel|*} item - Item to add (can be ResponseDataModel or any value)
+	 * @returns {void}
+	 * @example
+	 * const response = new ResponseDataModel();
+	 * response.addItem({ id: 1, name: 'John' });
+	 * response.addItem({ id: 2, name: 'Jane' });
+	 * // Result: [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
+	 * 
+	 * @example
+	 * // Add with label
+	 * const item = new ResponseDataModel({ id: 1 }, 'user');
+	 * response.addItem(item);
+	 * // Result: { user: [{ id: 1 }] }
 	 */
 	addItem(item) {
 
@@ -83,7 +105,18 @@ class ResponseDataModel {
 			data = item.getResponseData();
 			label = item.getLabel(); // see if there is an override key/label
 		} else {
-			data = item;
+			// Clone plain objects to prevent external mutation
+			// If cloning fails (e.g., functions, symbols), use the original value
+			if (typeof item === 'object' && item !== null) {
+				try {
+					data = safeClone(item);
+				} catch (e) {
+					// If safeClone fails, fall back to original value
+					data = item;
+				}
+			} else {
+				data = item;
+			}
 		}
 
 		if ( label === "" ) {
@@ -114,9 +147,23 @@ class ResponseDataModel {
 	};
 	
 	/**
-	 * Add an item by key
-	 * @param {ResponseDataModel|*} item 
-	 * @param {string} key 
+	 * Adds an item by a specific key.
+	 * If the key exists and contains non-empty data, converts to array and appends new item.
+	 * If the key doesn't exist or contains placeholder data, replaces with new item.
+	 * 
+	 * @param {ResponseDataModel|*} item - Item to add (can be ResponseDataModel or any value)
+	 * @param {string} [key=""] - Key to use for the item (overrides item's label if provided)
+	 * @returns {void}
+	 * @example
+	 * const response = new ResponseDataModel({});
+	 * response.addItemByKey({ id: 1, name: 'John' }, 'user');
+	 * response.addItemByKey({ id: 2, name: 'Jane' }, 'user');
+	 * // Result: { user: [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }] }
+	 * 
+	 * @example
+	 * // Override label
+	 * const item = new ResponseDataModel({ id: 1 }, 'employee');
+	 * response.addItemByKey(item, 'employees'); // Pluralize the label
 	 */
 	addItemByKey(item, key = "") {
 
@@ -131,7 +178,18 @@ class ResponseDataModel {
 			data = item.getResponseData();
 			label = (key !== "" ? key : item.getLabel() ); // see if there is an override key/label
 		} else {
-			data = item;
+			// Clone plain objects to prevent external mutation
+			// If cloning fails (e.g., functions, symbols), use the original value
+			if (typeof item === 'object' && item !== null) {
+				try {
+					data = safeClone(item);
+				} catch (e) {
+					// If safeClone fails, fall back to original value
+					data = item;
+				}
+			} else {
+				data = item;
+			}
 			label = key;
 		}
 
@@ -144,7 +202,7 @@ class ResponseDataModel {
 			) {
 			// if it is not yet an array, convert to array and move existing data to index 0
 			if ( !Array.isArray(this._responseData[label]) ) {
-				let temp = JSON.parse(JSON.stringify(this._responseData[label])); // no pointers, create copy
+				let temp = safeClone(this._responseData[label]); // no pointers, create copy
 				this._responseData[label] = []; // reassign to array
 				this._responseData[label].push(temp); // move original element to array
 			}
@@ -156,8 +214,20 @@ class ResponseDataModel {
 	};
 	
 	/**
+	 * Converts the response data to an object.
+	 * If there's a label, returns the data as a key-value pair with the label as the key.
+	 * If no label, returns the data directly.
+	 * 
+	 * @returns {*} The data object, optionally wrapped with label as key
+	 * @example
+	 * const response = new ResponseDataModel({ id: 1 }, 'user');
+	 * console.log(response.toObject());
+	 * // Output: { user: { id: 1 } }
 	 * 
-	 * @returns {*} The data object. If there is a label then it is returned as a key value pair where the label is the key
+	 * @example
+	 * const response = new ResponseDataModel({ id: 1 });
+	 * console.log(response.toObject());
+	 * // Output: { id: 1 }
 	 */
 	toObject() {
 		let obj = {};
@@ -171,8 +241,14 @@ class ResponseDataModel {
 	};
 
 	/**
+	 * Converts the response data to a JSON string.
+	 * Uses toObject() to get the object representation, then stringifies it.
 	 * 
-	 * @returns {string} A stringified JSON object (using .toObject() ) for use as a response
+	 * @returns {string} JSON string representation of the response data
+	 * @example
+	 * const response = new ResponseDataModel({ users: [{ id: 1 }] }, 'data');
+	 * console.log(response.toString());
+	 * // Output: '{"data":{"users":[{"id":1}]}}'
 	 */
 	toString() {
 		return JSON.stringify(this.toObject());

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

@@ -1,7 +1,40 @@
 /* */
 const DebugAndLog = require("./DebugAndLog.class");
 
+/**
+ * Timer class for measuring execution time and tracking performance metrics.
+ * Provides methods to start, stop, and query elapsed time with diagnostic logging.
+ * 
+ * @class Timer
+ * @example
+ * // Create and start a timer
+ * const timer = new Timer('myOperation', true);
+ * // ... perform operation ...
+ * const elapsed = timer.stop();
+ * console.log(`Operation took ${elapsed}ms`);
+ * 
+ * @example
+ * // Create timer without auto-start
+ * const timer = new Timer('delayedOperation');
+ * await timer.start();
+ * // ... perform operation ...
+ * timer.stop();
+ */
 class Timer {
+	/**
+	 * Creates a new Timer instance.
+	 * 
+	 * @param {string} name - The name of the timer for identification in logs
+	 * @param {boolean} [start=false] - Whether to automatically start the timer upon creation
+	 * @example
+	 * // Create timer with auto-start
+	 * const timer = new Timer('apiCall', true);
+	 * 
+	 * @example
+	 * // Create timer without auto-start
+	 * const timer = new Timer('batchProcess');
+	 * await timer.start();
+	 */
 	constructor(name, start = false) {
 		this.name = name;
 		this.startTime = -1;
@@ -15,13 +48,29 @@ class Timer {
 		}
 	};
 
+	/**
+	 * Updates the timer's internal message and logs it for diagnostics.
+	 * 
+	 * @param {string} message - The message to set and log
+	 * @returns {Promise<void>}
+	 * @example
+	 * await timer.updateMessage('Processing batch 1 of 10');
+	 */
 	async updateMessage(message) {
 		this.latestMessage = message;
 		DebugAndLog.diag(this.latestMessage);
 	};
 
 	/**
-	 * Start the timer
+	 * Starts the timer if it hasn't been started already.
+	 * Records the start time and logs a diagnostic message.
+	 * 
+	 * @returns {Promise<void>}
+	 * @example
+	 * const timer = new Timer('operation');
+	 * await timer.start();
+	 * // ... perform operation ...
+	 * timer.stop();
 	 */
 	async start() {
 		if ( this.startTime === -1 ) {
@@ -31,9 +80,15 @@ class Timer {
 	};
 
 	/**
-	 * Stop the timer
+	 * Stops the timer if it hasn't been stopped already.
+	 * Records the stop time, logs elapsed time, and returns the elapsed duration.
 	 * 
-	 * @returns {number} The time elapsed in milliseconds
+	 * @returns {number} The time elapsed in milliseconds between start and stop
+	 * @example
+	 * const timer = new Timer('dataProcessing', true);
+	 * // ... process data ...
+	 * const duration = timer.stop();
+	 * console.log(`Processing completed in ${duration}ms`);
 	 */
 	stop() {
 		if ( this.stopTime === -1 ) {
@@ -44,85 +99,137 @@ class Timer {
 	};
 
 	/**
-	 * The amount of time elapsed between the start and stop of the timer.
-	 * If the timer is still running it will be the amount of time between
-	 * start and now(). If the timer is stopped it will be the amount of
-	 * time between the start and stop.
+	 * Gets the amount of time elapsed between the start and stop of the timer.
+	 * If the timer is still running, returns the time between start and now().
+	 * If the timer is stopped, returns the time between start and stop.
 	 * 
-	 * @returns {number}
+	 * @returns {number} Elapsed time in milliseconds
+	 * @example
+	 * const timer = new Timer('operation', true);
+	 * // ... perform operation ...
+	 * console.log(`Current elapsed: ${timer.elapsed()}ms`);
+	 * timer.stop();
+	 * console.log(`Final elapsed: ${timer.elapsed()}ms`);
 	 */
 	elapsed() {
 		return ((this.isRunning()) ? this.now() : this.stopTime ) - this.startTime;
 	};
 
 	/**
-	 * The amount of time elapsed between the start of the timer and now()
-	 * Even if the timer is stopped, it will use now() and this value will
-	 * continue to increase during execution.
-	 * 
+	 * Gets the amount of time elapsed between the start of the timer and now().
+	 * Even if the timer is stopped, this value will continue to increase during execution.
 	 * Use elapsed() to get the amount of time between start and stop.
 	 * 
-	 * @returns {number}
+	 * @returns {number} Time in milliseconds since the timer was started
+	 * @example
+	 * const timer = new Timer('longOperation', true);
+	 * // ... perform operation ...
+	 * timer.stop();
+	 * console.log(`Time since start: ${timer.elapsedSinceStart()}ms`);
 	 */
 	elapsedSinceStart() {
 		return (this.now() - this.startTime);
 	};
 
 	/**
-	 * The amount of time elapsed since the timer was stopped and will increase
-	 * during execution. If the timer has not been stopped, it will 
-	 * return -1 (negative one)
+	 * Gets the amount of time elapsed since the timer was stopped.
+	 * This value will increase during execution after the timer is stopped.
+	 * If the timer has not been stopped, returns -1.
 	 * 
-	 * @returns {number}
+	 * @returns {number} Time in milliseconds since the timer was stopped, or -1 if still running
+	 * @example
+	 * const timer = new Timer('operation', true);
+	 * timer.stop();
+	 * setTimeout(() => {
+	 *   console.log(`Time since stop: ${timer.elapsedSinceStop()}ms`);
+	 * }, 1000);
 	 */
 	elapsedSinceStop() {
 		return (this.isRunning() ? -1 : this.now() - this.stopTime);
 	};
 
 	/**
-	 * The time now. Same as Date.now()
+	 * Gets the current time in milliseconds since the Unix epoch.
+	 * Equivalent to Date.now().
 	 * 
-	 * @returns {number}
+	 * @returns {number} Current timestamp in milliseconds
+	 * @example
+	 * const timer = new Timer('test');
+	 * const timestamp = timer.now();
+	 * console.log(`Current time: ${timestamp}`);
 	 */
 	now() {
 		return Date.now();
 	};
 
 	/**
-	 * Was the timer started
-	 * @returns {boolean}
+	 * Checks whether the timer has been started.
+	 * 
+	 * @returns {boolean} True if the timer was started, false otherwise
+	 * @example
+	 * const timer = new Timer('operation');
+	 * console.log(timer.wasStarted()); // false
+	 * await timer.start();
+	 * console.log(timer.wasStarted()); // true
 	 */
 	wasStarted() {
 		return (this.startTime > 0);
 	};
 
 	/**
+	 * Checks whether the timer has not been started yet.
 	 * 
-	 * @returns {boolean} Returns true if timer has not yet been started
+	 * @returns {boolean} True if timer has not yet been started, false otherwise
+	 * @example
+	 * const timer = new Timer('operation');
+	 * console.log(timer.notStarted()); // true
+	 * await timer.start();
+	 * console.log(timer.notStarted()); // false
 	 */
 	notStarted() {
 		return !(this.wasStarted());
 	};
 
 	/**
+	 * Checks whether the timer is currently running.
+	 * A timer is running if it has been started but not yet stopped.
 	 * 
-	 * @returns {boolean} True if the timer is currently running. False if not running
+	 * @returns {boolean} True if the timer is currently running, false if not running
+	 * @example
+	 * const timer = new Timer('operation', true);
+	 * console.log(timer.isRunning()); // true
+	 * timer.stop();
+	 * console.log(timer.isRunning()); // false
 	 */
 	isRunning() {
 		return (this.wasStarted() && this.stopTime < 0);
 	};
 
 	/**
+	 * Checks whether the timer has been stopped.
 	 * 
-	 * @returns {boolean} True if the timer was stopped. False if not stopped
+	 * @returns {boolean} True if the timer was stopped, false if not stopped
+	 * @example
+	 * const timer = new Timer('operation', true);
+	 * console.log(timer.wasStopped()); // false
+	 * timer.stop();
+	 * console.log(timer.wasStopped()); // true
 	 */
 	wasStopped() {
 		return (this.wasStarted() && this.stopTime > 0);
 	};
 
 	/**
+	 * Gets the current status of the timer as a string.
 	 * 
-	 * @returns {string} Text string denoting stating. 'NOT_STARTED', 'IS_RUNNING', 'IS_STOPPED'
+	 * @returns {string} Status string: 'NOT_STARTED', 'IS_RUNNING', or 'IS_STOPPED'
+	 * @example
+	 * const timer = new Timer('operation');
+	 * console.log(timer.status()); // 'NOT_STARTED'
+	 * await timer.start();
+	 * console.log(timer.status()); // 'IS_RUNNING'
+	 * timer.stop();
+	 * console.log(timer.status()); // 'IS_STOPPED'
 	 */
 	status() {
 		var s = "NOT_STARTED";
@@ -133,8 +240,13 @@ class Timer {
 	};
 
 	/**
-	 * Messages are internal updates about the status
+	 * Gets the latest internal message from the timer.
+	 * Messages are internal updates about the timer's status.
+	 * 
 	 * @returns {string} The latest message from the timer
+	 * @example
+	 * const timer = new Timer('operation', true);
+	 * console.log(timer.message()); // "Timer 'operation' started at ..."
 	 */
 	message() {
 		return (this.latestMessage);

package/src/lib/tools/index.js

@@ -92,6 +92,22 @@ class _ConfigSuperClass {
 	static _connections = null;
 	static _settings = null;
 
+	/**
+	 * Get the application settings object
+	 * 
+	 * Returns the settings object that was initialized during Config.init(). 
+	 * This typically contains application-specific configuration values loaded 
+	 * from parameter store, environment variables, or other sources.
+	 * 
+	 * @returns {object|null} Settings object containing application configuration, or null if not initialized
+	 * @example
+	 * // Access application settings
+	 * const settings = Config.settings();
+	 * if (settings) {
+	 *   console.log('App version:', settings.version);
+	 *   console.log('Environment:', settings.environment);
+	 * }
+	 */
 	static settings() {
 		return _ConfigSuperClass._settings;
 	};
@@ -105,14 +121,85 @@ class _ConfigSuperClass {
 	};
 
 	/**
+	 * Get a connection by name and return the Connection instance
 	 * 
-	 * @param {string} name 
-	 * @returns {Connection}
+	 * @param {string} name The name of the connection to retrieve
+	 * @returns {Connection|null} Connection instance or null if not found
 	 */
 	static getConnection(name) {
+		if (_ConfigSuperClass._connections === null) {
+			return null;
+		}
 		return _ConfigSuperClass._connections.get(name);
 	}
 
+	/**
+	 * Get a connection by name and return it as a plain object
+	 * 
+	 * @param {string} name The name of the connection to retrieve
+	 * @returns {{method: string, uri: string, protocol: string, host: string, path: string, headers: object, parameters: object, body: string, options: object, note: string, authentication: object}|null} Connection object with properties or null if not found
+	 * @example
+	 * const conn = Config.getConn('myConnection');
+	 * const cacheObj = await CacheableDataAccess.getData(
+	 *    cacheProfile,
+	 *    endpoint.get
+	 *    conn
+	 * )
+	 * */
+	static getConn(name) {
+		if (_ConfigSuperClass._connections === null) {
+			return null;
+		}
+		
+		const connection = _ConfigSuperClass._connections.get(name);
+		
+		if (connection === null) {
+			return null;
+		}
+		
+		return connection.toObject();
+	}
+
+	/**
+	 * Get a connection AND one of its Cache Profiles by name and return as plain objects
+	 * @param {string} connectionName The name of the connection to retrieve
+	 * @param {string} cacheProfileName The name of the cache profile to retrieve from the connection
+	 * @returns {{conn: {method: string, uri: string, protocol: string, host: string, path: string, headers: object, parameters: object, body: string, options: object, note: string, authentication: object}|null, cacheProfile: {profile: string, overrideOriginHeaderExpiration: boolean, defaultExpirationInSeconds: number, expirationIsOnInterval: boolean, hostId: string, pathId: string, encrypt: boolean, defaultExpirationExtensionOnErrorInSeconds: number}|null}} Connection and Cache Profile objects or null if not found
+	 * @example
+	 * const { conn, cacheProfile } = Config.getConnCacheProfile('myConnection', 'myCacheProfile');
+	 * const cacheObj = await CacheableDataAccess.getData(
+	 *    cacheProfile,
+	 *    endpoint.get
+	 *    conn
+	 * )
+	 */
+	static getConnCacheProfile(connectionName, cacheProfileName) {
+
+		if (_ConfigSuperClass._connections === null) {
+			return { conn: null, cacheProfile: null };
+		}
+
+		const connection = _ConfigSuperClass._connections.get(connectionName);
+
+		if (connection === null) {
+			return { conn: null, cacheProfile: null };
+		}
+
+		let cacheProfile = null;
+		try {
+			const profile = connection.getCacheProfile(cacheProfileName);
+			cacheProfile = (profile === undefined) ? null : profile;
+		} catch (error) {
+			// getCacheProfile throws if _cacheProfiles is null
+			cacheProfile = null;
+		}
+
+		return {
+			conn: connection.toObject(),
+			cacheProfile: cacheProfile
+		};
+	}
+
 	/**
 	 * 
 	 * @returns {Promise} A promise that resolves when the Config class has finished initializing