@63klabs/cache-data 1.3.6 → 1.3.7

package/CHANGELOG.md

@@ -2,13 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
-Proposed and upcoming changes may be found on [63Klabs/cache-data Issues](https://github.com/63Klabs/cache-data/issues).
+> **Note:** This project is still in beta. While every effort is made to prevent breaking changes, they may still occur. If after upgrading to a new version you experience any issue, please report the issue and go back to a previous version until a fix is released.
+
+To report an issue, or to see proposed and upcoming enhancements, check out [63Klabs/cache-data Issues](https://github.com/63Klabs/cache-data/issues) page on GitHub.
 
 Report all vulnerabilities under the [Security menu](https://github.com/63Klabs/cache-data/security/advisories) in the Cache-Data GitHub repository.
 
-## v1.3.7 (unreleased)
+## v1.3.8 (unreleased)
+
+- Nothing yet
+
+## v1.3.7 (2026-02-06)
+
+### Fixed
+- **Cache DAO Undefined Header Bug** [Spec: 1-3-7-cache-dao-fix](.kiro/specs/1-3-7-cache-dao-fix/) - Fixed production bug where undefined values were passed to HTTP headers, causing request failures with "Invalid value 'undefined' for header" errors
+  - Cache.getHeader() now normalizes undefined to null for consistent behavior
+  - Added defensive validation at header assignment points in CacheableDataAccess.getData()
+  - Added Cache._isValidHeaderValue() helper method for header validation
+  - **Most likely cause:** The move from over-use of JSON Stringify/parse cycles in favor of cloning in v1.3.6. JSON stringify/parse removed undefined values from objects, covering an underlying issue that is now fixed.
 
-- Next release
+### Added
+- **Jest Testing Framework** [Spec: 1-3-7-cache-dao-fix](.kiro/specs/1-3-7-cache-dao-fix/) - Set up Jest alongside Mocha for better AWS integration testing
+  - Configured Jest with ES module support
+  - Added npm scripts: `test:jest`, `test:all`, `test:cache:jest`
+  - Jest tests use `*.jest.mjs` pattern to avoid conflicts with Mocha tests
 
 ## v1.3.6 (2025-02-02)
 

package/CONTRIBUTING.md

@@ -12,6 +12,24 @@ Submit feature requests. To keep this project simple and maintainable we accept
 
 After you have successfully participated in the bug reporting and feature request process, fork the repository and make your changes in a separate branch. Once you're satisfied with your changes, submit a pull request for review. Please only submit small changes (a single feature) at first. Pull requests with major code updates or frequent pull requests will often get ignored. Changes should also have code and testing methods well documented.
 
+All code changes MUST start as an Issue (or security report) with a clear description of the problem or enhancement. No changes should be submitted to the repository without an attached, and approved, Issue.
+
+Code developed (by AI or Human) outside of Kiro (see below) must NOT be submitted directly to the repository. Instead submit a proof of concept for a new piece of code or method via the Issue tracker as an enhancement. Someone from the team will review, evaluate the usefulness, and then implement using the proper process.
+
+## Use of AI
+
+This project utilizes the Spec-Driven, AI-Assisted Engineering approach.
+
+Spec-Driven, AI-Assisted Engineering (SD-AI) is a software development methodology that prioritizes creating detailed, structured specifications before writing code. It priortizes context, requirements, and architectural constraints to generate accurate, non-hallucinated code. This approach shifts from ad-hoc, prompt-driven "vibe coding" to a structured, human-guided, AI-executed workflow, improving reliability in complex projects.
+
+> Contributors are responsible for every line of code--AI-generated or not.
+
+Code must be reviewed, understood, and tested by a human before being merged.
+
+Kiro is the required AI coding assistant for final integrations, documentation, and testing, as it is in the AWS Ecosystem and this project is deveoped to deploy on the AWS platform. Just like test suites, Kiro ensures the proper tests, documentation, and guardrails are in place. Kiro is as important as commit-hooks and tests as it is a tool that ensures quality checks and should not be bypassed.
+
+Ensure [AI Context](./AI_CONTEXT.md) and [Kiro steering documents](.kiro/steering/ai-context-reference.md) are reviewed, understood, and used by both humans and AI.
+
 ## Development Setup
 
 Tests and documentation are critical to this project.
@@ -138,18 +156,6 @@ All public APIs must have complete JSDoc documentation. See [Documentation Stand
  */
 ```
 
-## Use of AI
-
-This project utilizes the Spec-Driven, AI-Assisted Engineering approach.
-
-Spec-Driven, AI-Assisted Engineering (SD-AI) is a software development methodology that prioritizes creating detailed, structured specifications before writing code. It priortizes context, requirements, and architectural constraints to generate accurate, non-hallucinated code. This approach shifts from ad-hoc, prompt-driven "vibe coding" to a structured, human-guided, AI-executed workflow, improving reliability in complex projects.
-
-> Contributors are responsible for every line of code--AI-generated or not.
-
-Code must be reviewed, understood, and tested by a human before being merged.
-
-Kiro is the preferred AI coding assistant as it is in the AWS Ecosystem and this project is deveoped to deploy on the AWS platform. Ensure [AI Context](./AI_CONTEXT.md) and [Kiro steering documents](.kiro/steering/ai-context-reference.md) are reviewed, understood, and used by both humans and AI. 
-
 ## Current Contributors
 
 Thank you to the following people who have contributed to this project:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@63klabs/cache-data",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "description": "Cache data from an API endpoint or application process using AWS S3 and DynamoDb",
   "author": "Chad Leigh Kluck (https://chadkluck.me)",
   "license": "MIT",
@@ -28,6 +28,7 @@
     "chai": "^6.x",
     "chai-http": "^5.x",
     "fast-check": "^4.x",
+    "jest": "^30.2.0",
     "mocha": "^11.x",
     "sinon": "^21.x"
   },
@@ -36,7 +37,10 @@
   },
   "scripts": {
     "test": "mocha 'test/**/*-tests.mjs'",
+    "test:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:all": "npm test && npm run test:jest",
     "test:cache": "mocha 'test/cache/**/*-tests.mjs'",
+    "test:cache:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/cache",
     "test:config": "mocha 'test/config/**/*-tests.mjs'",
     "test:endpoint": "mocha 'test/endpoint/**/*-tests.mjs'",
     "test:logging": "mocha 'test/logging/**/*-tests.mjs'",

package/src/lib/dao-cache.js

@@ -1683,6 +1683,45 @@ class Cache {
 		// Boolean("false") is true so we need to code for it. As long as it is not "false", trust Boolean()
 		return  (( value !== "false") ? Boolean(value) : false ); 
 	};
+
+	/**
+	 * Validate that a header value is suitable for HTTP header assignment.
+	 * Returns true if the value is a non-empty string (except "undefined") or number, false otherwise.
+	 * 
+	 * This method is used internally to validate header values before assignment
+	 * to prevent undefined, null, or invalid types from being used in HTTP headers.
+	 * The string "undefined" is explicitly rejected because it causes HTTP errors
+	 * when used as a header value.
+	 * 
+	 * @param {*} value The value to validate
+	 * @returns {boolean} True if value is valid for HTTP header, false otherwise
+	 * @private
+	 * @example
+	 * Cache._isValidHeaderValue('text');        // true
+	 * Cache._isValidHeaderValue(123);           // true
+	 * Cache._isValidHeaderValue('');            // false
+	 * Cache._isValidHeaderValue('undefined');   // false (string "undefined" is invalid)
+	 * Cache._isValidHeaderValue(null);          // false
+	 * Cache._isValidHeaderValue(undefined);     // false
+	 * Cache._isValidHeaderValue(NaN);           // false
+	 * Cache._isValidHeaderValue(true);          // false
+	 * Cache._isValidHeaderValue({});            // false
+	 * Cache._isValidHeaderValue([]);            // false
+	 */
+	static _isValidHeaderValue(value) {
+		if (value === null || value === undefined) {
+			return false;
+		}
+		const type = typeof value;
+		if (type === 'string') {
+			// Filter out empty strings and the string "undefined"
+			return value.length > 0 && value !== 'undefined';
+		}
+		if (type === 'number') {
+			return !isNaN(value);
+		}
+		return false;
+	}
 	
 	/**
 	 * Generate an ETag hash for cache validation. Creates a unique hash by combining
@@ -2252,12 +2291,18 @@ class Cache {
 	 * Get the ETag header value from the cached data. The ETag is used for
 	 * cache validation and conditional requests.
 	 * 
-	 * @returns {string|null} The ETag value, or null if not present
+	 * Returns null if the ETag header is not present, is null, or is undefined.
+	 * This method uses getHeader() internally, which normalizes undefined values
+	 * to null for consistent behavior.
+	 * 
+	 * @returns {string|null} The ETag value, or null if not present, null, or undefined
 	 * @example
 	 * const cache = new Cache(connection, cacheProfile);
 	 * await cache.read();
 	 * const etag = cache.getETag();
-	 * console.log(`ETag: ${etag}`);
+	 * if (etag !== null) {
+	 *   console.log(`ETag: ${etag}`);
+	 * }
 	 */
 	getETag() {
 		return this.getHeader("etag");
@@ -2267,12 +2312,18 @@ class Cache {
 	 * Get the Last-Modified header value from the cached data. This timestamp
 	 * indicates when the cached content was last modified at the origin.
 	 * 
-	 * @returns {string|null} The Last-Modified header value in HTTP date format, or null if not present
+	 * Returns null if the Last-Modified header is not present, is null, or is undefined.
+	 * This method uses getHeader() internally, which normalizes undefined values
+	 * to null for consistent behavior.
+	 * 
+	 * @returns {string|null} The Last-Modified header value in HTTP date format, or null if not present, null, or undefined
 	 * @example
 	 * const cache = new Cache(connection, cacheProfile);
 	 * await cache.read();
 	 * const lastModified = cache.getLastModified();
-	 * console.log(`Last modified: ${lastModified}`);
+	 * if (lastModified !== null) {
+	 *   console.log(`Last modified: ${lastModified}`);
+	 * }
 	 */
 	getLastModified() {
 		return this.getHeader("last-modified");
@@ -2435,18 +2486,36 @@ class Cache {
 	 * Get a specific header value from the cached data by key. Header keys are
 	 * case-insensitive (stored as lowercase).
 	 * 
+	 * Returns null if the header doesn't exist, has a null value, or has an undefined value.
+	 * This normalization ensures consistent behavior for conditional checks and prevents
+	 * undefined values from being passed to HTTP headers.
+	 * 
+	 * Note: This method normalizes undefined to null. If a header key exists but has an
+	 * undefined value, this method returns null (never undefined). This ensures that
+	 * conditional checks like `!== null` work reliably.
+	 * 
 	 * @param {string} key The header key to retrieve (case-insensitive)
-	 * @returns {string|number|null} The header value, or null if the header doesn't exist
+	 * @returns {string|number|null} The header value, or null if the header doesn't exist, is null, or is undefined
 	 * @example
 	 * const cache = new Cache(connection, cacheProfile);
 	 * await cache.read();
 	 * const contentType = cache.getHeader('content-type');
 	 * const etag = cache.getHeader('ETag'); // Case-insensitive
 	 * console.log(`Content-Type: ${contentType}`);
+	 * 
+	 * @example
+	 * // Undefined values are normalized to null
+	 * const undefinedHeader = cache.getHeader('missing-header');
+	 * console.log(undefinedHeader === null); // true (never undefined)
 	 */
 	getHeader(key) {
 		let headers = this.getHeaders();
-		return ( headers !== null && key in headers) ? headers[key] : null
+		if (headers === null || !(key in headers)) {
+			return null;
+		}
+		// Normalize undefined to null for consistent behavior
+		const value = headers[key];
+		return (value === undefined || value === null) ? null : value;
 	};
 
 	/**
@@ -3047,11 +3116,23 @@ class CacheableDataAccess {
 
 					// add etag and last modified to connection
 					if ( !("headers" in connection)) { connection.headers = {}; }
-					if ( !("if-none-match" in connection.headers) && cache.getETag() !== null) { 
-						connection.headers['if-none-match'] = cache.getETag();
+					
+					// Sanitize existing headers to remove invalid values (including string "undefined")
+					for (const key in connection.headers) {
+						if (!Cache._isValidHeaderValue(connection.headers[key])) {
+							delete connection.headers[key];
+							tools.DebugAndLog.debug(`Removed invalid header value for "${key}": ${connection.headers[key]}`);
+						}
 					}
-					if (!("if-modified-since" in connection.headers) && cache.getLastModified() !== null) { 
-						connection.headers['if-modified-since'] = cache.getLastModified(); 
+					
+					const etag = cache.getETag();
+					if ( !("if-none-match" in connection.headers) && Cache._isValidHeaderValue(etag)) { 
+						connection.headers['if-none-match'] = etag;
+					}
+					
+					const lastModified = cache.getLastModified();
+					if (!("if-modified-since" in connection.headers) && Cache._isValidHeaderValue(lastModified)) { 
+						connection.headers['if-modified-since'] = lastModified; 
 					}
 
 					// request data from original source
@@ -3095,7 +3176,52 @@ class CacheableDataAccess {
 	};
 };
 
+/**
+ * TestHarness provides access to internal classes for testing purposes only.
+ * This class should NEVER be used in production code - it exists solely to
+ * enable proper testing of the cache-dao module without exposing internal
+ * implementation details to end users.
+ * 
+ * @private
+ * @example
+ * // In tests only - DO NOT use in production
+ * import { TestHarness } from '../../src/lib/dao-cache.js';
+ * const { CacheData } = TestHarness.getInternals();
+ * 
+ * // Mock CacheData.read for testing
+ * const originalRead = CacheData.read;
+ * CacheData.read = async () => ({ cache: { body: 'test', headers: {} } });
+ * // ... run tests ...
+ * CacheData.read = originalRead; // Restore
+ */
+class TestHarness {
+	/**
+	 * Get access to internal classes for testing purposes.
+	 * WARNING: This method is for testing only and should never be used in production.
+	 * 
+	 * @returns {{CacheData: typeof CacheData, S3Cache: typeof S3Cache, DynamoDbCache: typeof DynamoDbCache}} Object containing internal classes
+	 * @private
+	 * @example
+	 * // In tests only - DO NOT use in production
+	 * const { CacheData, S3Cache, DynamoDbCache } = TestHarness.getInternals();
+	 * 
+	 * // Mock CacheData.read for property-based testing
+	 * const originalRead = CacheData.read;
+	 * CacheData.read = async () => ({
+	 *   cache: { body: 'test', headers: { 'content-type': 'application/json' }, expires: 1234567890, statusCode: '200' }
+	 * });
+	 */
+	static getInternals() {
+		return {
+			CacheData,
+			S3Cache,
+			DynamoDbCache
+		};
+	}
+}
+
 module.exports = {
 	Cache,
-	CacheableDataAccess
+	CacheableDataAccess,
+	TestHarness
 };