@63klabs/cache-data 1.3.6 → 1.3.8

package/src/lib/tools/index.js

@@ -44,19 +44,31 @@ const { Connections, Connection, ConnectionRequest, ConnectionAuthentication } =
  */
 
 /**
- * @typedef ConnectionObject
- * @property {object} connection A connection object
- * @property {string} connection.method GET or POST
- * @property {string} connection.uri the full uri (overrides protocol, host, path, and parameters) ex https://example.com/api/v1/1004/?key=asdf&y=4
- * @property {string} connection.protocol https
- * @property {string} connection.host host/domain: example.com
- * @property {string} connection.path path of the request: /api/v1/1004
- * @property {object} connection.parameters parameters for the query string as an object in key/value pairs
- * @property {object} connection.headers headers for the request as an object in key/value pairs
- * @property {string} connection.body for POST requests, the body
- * @property {string} connection.note a note for logging
- * @property {object} connection.options https_get options
- * @property {number} connection.options.timeout timeout in milliseconds
+ * @typedef {Object} ConnectionObject
+ * @property {string} method GET or POST
+ * @property {string} uri the full uri (overrides protocol, host, path, and parameters) ex https://example.com/api/v1/1004/?key=asdf&y=4
+ * @property {string} protocol https
+ * @property {string} host host/domain: example.com
+ * @property {string} path path of the request: /api/v1/1004
+ * @property {object} parameters parameters for the query string as an object in key/value pairs
+ * @property {object} headers headers for the request as an object in key/value pairs
+ * @property {string} body for POST requests, the body
+ * @property {string} note a note for logging
+ * @property {object} options https_get options
+ * @property {number} options.timeout timeout in milliseconds
+ * @property {CacheProfileObject[]} cache
+ */
+
+/**
+ * @typedef {Object} CacheProfileObject
+ * @property {string} profile The name of the cache profile
+ * @property {boolean} overrideOriginHeaderExpiration If true, the cache expiration will be overridden by the origin header expiration
+ * @property {number} defaultExpirationInSeconds The default expiration time in seconds
+ * @property {boolean} expirationIsOnInterval If true, the cache expiration will be on an interval
+ * @property {array<string>} headersToRetain
+ * @property {string} hostId The host ID to use for the cache key
+ * @property {string} pathId The path ID to use for the cache key
+ * @property {boolean} encrypt If true, the cache data will be encrypted
  */
 
 /* ****************************************************************************
@@ -69,7 +81,7 @@ const { Connections, Connection, ConnectionRequest, ConnectionAuthentication } =
  *************************************************************************** */
 
 /**
- * _ConfigSuperClass needs to be extended by your own Config class definition.
+ * AppConfig needs to be extended by your own Config class definition.
  * 
  * This super class holds common variables and methods that can be used by any 
  * application. However, each application requires it's own methods and logic 
@@ -80,36 +92,119 @@ const { Connections, Connection, ConnectionRequest, ConnectionAuthentication } =
  * initialized.
  * 
  * @example
- * class Config extends tools._ConfigSuperClass {
+ * class Config extends tools.AppConfig {
  * 		// your custom class definition including your implementation of .init()
  * }
  * 
  * Config.init();
  */
-class _ConfigSuperClass {
+class AppConfig {
 
 	static _promise = null;
+	static _promises = [];
 	static _connections = null;
 	static _settings = null;
+	static _ssmParameters = null;
+
+	/**
+	 * Initialize the Config class
+	 *
+	 * @param {object} options Configuration options
+	 * @param {object} options.settings Application settings retrieved by Config.settings()
+	 * @param {ConnectionObject[]} options.connections Application connections that can then be retrieved by Config.getConn() or Config.getConnCacheProfile()
+	 * @param {object} options.validations ClientRequest.init() options
+	 * @param {object} options.responses Response.init() options
+	 * @param {object} options.responses.settings
+	 * @param {number} options.responses.settings.errorExpirationInSeconds
+	 * @param {number} options.responses.settings.routeExpirationInSeconds
+	 * @param {number} options.responses.settings.externalRequestHeadroomInMs
+	 * @param {object} options.responses.jsonResponses
+	 * @param {object} options.responses.htmlResponses
+	 * @param {object} options.responses.xmlResponses
+	 * @param {object} options.responses.rssResponses
+	 * @param {object} options.responses.textResponses
+	 * @param {object} options.ssmParameters Parameter Store
+	 * @returns {Promise<void>}
+	 * @example
+	 * const { Config } = require("./config");
+	 * Config.init({
+	 *   settings: {
+	 *     dataLimit: 1000,
+	 *     cacheTTL: 300
+	 *   },
+	 *   connections: {
+	 *     myConnection: {
+	 *       method: "GET",
+	 *       host: "example.com",
+	 *       path: "/api/v1/data",
+	 *       parameters: {
+	 *         limit: 100
+	 *       }
+	 *     }
+	 *   }
+	 * });
+	 */
+	static init(options = {}) {
+
+		try {
+
+			const debug = (options?.debug === true);
+			if (debug) {
+				DebugAndLog.debug("Config Init in debug mode");
+			}
+
+			if (options.settings) {
+				AppConfig._settings = options.settings;
+				if (debug) { DebugAndLog.debug("Settings initialized", AppConfig._settings); }
+			}
+
+			if (options.connections) {
+				AppConfig._connections = new Connections(options.connections);
+				if (debug) { DebugAndLog.debug("Connections initialized", AppConfig._connections.info()); }
+			}
+
+			if (options.validations) {
+				ClientRequest.init(options.validations);
+				if (debug) { DebugAndLog.debug("ClientRequest initialized", ClientRequest.info()); }
+			}
+
+			if (options.responses) {
+				Response.init(options.responses);
+				if (debug) { DebugAndLog.debug("Response initialized", Response.info()); }
+			}
+
+			if (options.ssmParameters) {
+				AppConfig._ssmParameters = AppConfig._initParameters(options.ssmParameters);
+				AppConfig.add(AppConfig._ssmParameters);
+			}
+
+			return true;
+
+		} catch (error) {
+			DebugAndLog.error(`Could not initialize Config ${error.message}`, error.stack);
+			return false;
+		}
+	};
+
+	/**
+	 * Add a promise to AppConfig. Use AppConfig.promise() to ensure all are resolved.
+	 * @param {Promise} promise 
+	 */
+	static add(promise) {
+		AppConfig._promises.push(promise);
+	}
 
 	/**
 	 * 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);
-	 * }
+	 * // Config extends AppConfig
+	 * const { Config } = require("./config");
+	 * const limit = Config.settings().dataLimit;
 	 */
 	static settings() {
-		return _ConfigSuperClass._settings;
+		return AppConfig._settings;
 	};
 
 	/**
@@ -117,7 +212,7 @@ class _ConfigSuperClass {
 	 * @returns {Connections}
 	 */
 	static connections() {
-		return _ConfigSuperClass._connections;
+		return AppConfig._connections;
 	};
 
 	/**
@@ -127,10 +222,10 @@ class _ConfigSuperClass {
 	 * @returns {Connection|null} Connection instance or null if not found
 	 */
 	static getConnection(name) {
-		if (_ConfigSuperClass._connections === null) {
+		if (AppConfig._connections === null) {
 			return null;
 		}
-		return _ConfigSuperClass._connections.get(name);
+		return AppConfig._connections.get(name);
 	}
 
 	/**
@@ -147,11 +242,11 @@ class _ConfigSuperClass {
 	 * )
 	 * */
 	static getConn(name) {
-		if (_ConfigSuperClass._connections === null) {
+		if (AppConfig._connections === null) {
 			return null;
 		}
 		
-		const connection = _ConfigSuperClass._connections.get(name);
+		const connection = AppConfig._connections.get(name);
 		
 		if (connection === null) {
 			return null;
@@ -175,29 +270,31 @@ class _ConfigSuperClass {
 	 */
 	static getConnCacheProfile(connectionName, cacheProfileName) {
 
-		if (_ConfigSuperClass._connections === null) {
+		if (AppConfig._connections === null) {
 			return { conn: null, cacheProfile: null };
 		}
 
-		const connection = _ConfigSuperClass._connections.get(connectionName);
+		const connection = AppConfig._connections.get(connectionName);
 
 		if (connection === null) {
 			return { conn: null, cacheProfile: null };
 		}
 
-		let cacheProfile = null;
+		let cacheProfile;
+		
 		try {
 			const profile = connection.getCacheProfile(cacheProfileName);
 			cacheProfile = (profile === undefined) ? null : profile;
-		} catch (error) {
+		} catch {
 			// getCacheProfile throws if _cacheProfiles is null
 			cacheProfile = null;
 		}
 
 		return {
 			conn: connection.toObject(),
-			cacheProfile: cacheProfile
-		};
+			cacheProfile
+		};	
+
 	}
 
 	/**
@@ -205,7 +302,10 @@ class _ConfigSuperClass {
 	 * @returns {Promise} A promise that resolves when the Config class has finished initializing
 	 */
 	static promise() {
-		return _ConfigSuperClass._promise;
+		if (AppConfig._promise !== null ) { // Backwards compatibility
+			AppConfig._promises.push(AppConfig._promise);
+		}
+		return Promise.all[AppConfig._promises];
 	};
 
 	
@@ -246,8 +346,6 @@ class _ConfigSuperClass {
 			return { names: names, paths: paths};
 		};
 
-		let request = [];
-
 		let pNames = paramNames();
 
 		if (pNames.names.length > 0 || pNames.paths.length > 0 ) {
@@ -352,20 +450,20 @@ class _ConfigSuperClass {
 	 *  ]
 	 * );
 	 * @param {array} parameters An array of parameter locations
-	 * @returns {object} Parameters from the parameter store
+	 * @returns {Promise<object>} Parameters from the parameter store
 	 */
 	static async _initParameters(parameters) {
 		// make the call to get the parameters and wait before proceeding to the return
 		return await this._getParameters(parameters);        
 	};
 
-	static async _initS3File(paths) {
-		return {};
-	};
+	// static async _initS3File(paths) {
+	// 	return {};
+	// };
 
-	static async _initDynamoDbRecord(query) {
-		return {};
-	};
+	// static async _initDynamoDbRecord(query) {
+	// 	return {};
+	// };
 	
 };
 
@@ -388,7 +486,8 @@ module.exports = {
 	ClientRequest,
 	ResponseDataModel,
 	Response,
-	_ConfigSuperClass,
+	AppConfig,
+	_ConfigSuperClass: AppConfig, // Alias
 	CachedSSMParameter,
 	CachedSecret,
 	CachedParameterSecret,

package/scripts/README.md

@@ -1,175 +0,0 @@
-# Documentation Validation Scripts
-
-This directory contains scripts for validating and auditing documentation in the @63klabs/cache-data package.
-
-## Scripts
-
-### audit-documentation.mjs
-
-Comprehensive documentation audit and validation script that checks:
-
-- **JSDoc Completeness**: Ensures all exported functions have complete JSDoc with required tags (@param, @returns, @example)
-- **JSDoc Accuracy**: Verifies that documented parameters match actual function signatures
-- **Link Validation**: Checks all links in documentation files to ensure they point to existing files
-- **Example Code Validation**: Validates that JavaScript code examples have correct syntax
-
-#### Usage
-
-```bash
-node scripts/audit-documentation.mjs
-```
-
-#### Output
-
-The script generates a detailed report at:
-```
-.kiro/specs/1-3-6-documentation-enhancement/audit-report.json
-```
-
-The report includes:
-- Summary statistics (coverage percentages, error counts)
-- List of functions missing JSDoc
-- List of functions with incomplete JSDoc
-- List of functions with inaccurate JSDoc (hallucinated parameters)
-- List of broken links in documentation
-- List of invalid code examples
-
-#### Exit Codes
-
-- `0`: All validation checks passed
-- `1`: Critical errors found (missing JSDoc, inaccurate JSDoc, broken links, or invalid examples)
-
-### Pre-Commit Hook
-
-A Git pre-commit hook is installed at `.git/hooks/pre-commit` that automatically runs documentation validation before each commit.
-
-#### How It Works
-
-1. When you run `git commit`, the hook automatically executes
-2. It runs `audit-documentation.mjs` to validate all documentation
-3. If critical errors are found, the commit is blocked
-4. You must fix the errors before committing
-
-#### Bypassing the Hook
-
-If you need to commit despite validation errors (not recommended):
-
-```bash
-git commit --no-verify
-```
-
-#### Installing the Hook
-
-The hook is automatically created when task 16.3 is completed. If you need to reinstall it:
-
-```bash
-chmod +x .git/hooks/pre-commit
-```
-
-## Validation Requirements
-
-### JSDoc Requirements
-
-All exported functions, methods, and classes must have:
-
-1. **Description**: Clear explanation of what the function does
-2. **@param tags**: For each parameter, with type and description
-3. **@returns tag**: With detailed type information and description
-4. **@example tag**: Demonstrating typical usage
-5. **@throws tag**: If the function can throw errors (optional but recommended)
-
-### Type Annotation Standards
-
-- Promises: `{Promise<ResolvedType>}`
-- Arrays: `{Array.<ElementType>}`
-- Objects: `{Object.<string, Type>}` or detailed property list
-- Complex returns: `{Promise<{prop1: Type1, prop2: Type2}>}`
-- Optional parameters: `{Type} [paramName=default]`
-- Union types: `{Type1|Type2}`
-
-### Example Code Standards
-
-All JavaScript code examples in documentation must:
-
-- Have valid syntax (pass Node.js syntax check)
-- Include necessary imports if using package functionality
-- Not use deprecated APIs
-- Be executable or clearly marked as snippets
-
-### Link Standards
-
-All links in documentation must:
-
-- Point to existing files for internal links
-- Be valid URLs for external links
-- Use relative paths for internal documentation
-
-## Common Issues and Fixes
-
-### Missing JSDoc
-
-**Issue**: Function has no JSDoc comment
-
-**Fix**: Add a JSDoc comment block above the function:
-
-```javascript
-/**
- * Description of what the function does
- * 
- * @param {Type} paramName - Description of parameter
- * @returns {ReturnType} Description of return value
- * @example
- * // Example usage
- * const result = functionName(param);
- */
-function functionName(paramName) {
-  // ...
-}
-```
-
-### Incomplete JSDoc
-
-**Issue**: JSDoc is missing required tags
-
-**Fix**: Add the missing tags (@param, @returns, @example)
-
-### Inaccurate JSDoc
-
-**Issue**: JSDoc documents parameters that don't exist in the function signature
-
-**Fix**: Update JSDoc to match the actual function signature, or update the function signature if JSDoc is correct
-
-### Broken Links
-
-**Issue**: Documentation contains links to non-existent files
-
-**Fix**: Update the link to point to the correct file, or create the missing file
-
-### Invalid Code Examples
-
-**Issue**: Code example has syntax errors
-
-**Fix**: Correct the syntax error, or mark the code as a snippet if it's intentionally incomplete
-
-## Integration with CI/CD
-
-To integrate documentation validation into your CI/CD pipeline:
-
-```yaml
-# Example GitHub Actions workflow
-- name: Validate Documentation
-  run: node scripts/audit-documentation.mjs
-```
-
-The script will exit with code 1 if validation fails, causing the CI/CD pipeline to fail.
-
-## Maintenance
-
-The validation script should be updated when:
-
-- New JSDoc requirements are added
-- New documentation standards are established
-- New types of validation checks are needed
-- Deprecated APIs change
-
-See `.kiro/specs/1-3-6-documentation-enhancement/STEERING.md` for documentation standards and maintenance procedures.