@63klabs/cache-data 1.3.9 → 1.3.10

package/CHANGELOG.md

@@ -8,9 +8,50 @@ To report an issue, or to see proposed and upcoming enhancements, check out [63K
 
 Report all vulnerabilities under the [Security menu](https://github.com/63Klabs/cache-data/security/advisories) in the Cache-Data GitHub repository.
 
-## v1.3.9 (unreleased)
+## v1.3.10 (2026-03-15)
+
+### Fixes
+
+- **Security Fixes** in tests and SSM Parameter Store legacy access [Spec: 1-3-10-security-fixes-for-tests](.kiro/specs/1-3-10-security-fixes-for-tests/)
+- **GitHub Workflow fix** for testing matrix. Node24 was failing while Node 20, 22 were passing [Spec: 1-3-10-github-workflow-test-fix](.kiro/specs/1-3-10-github-workflow-test-fix/)
+
+### Changes
+
+- **Complete Mocha to Jest Test Migration** [Spec: 1-3-10-test-migration-phase-6](.kiro/specs/1-3-10-test-migration-phase-6/)
+  - Migrated all 38 remaining Mocha test files to Jest, completing the full test suite migration
+  - Jest is now the sole test framework for the project
+  - All tests use the `.jest.mjs` file extension
+  - Updated `npm test` to run Jest directly
+  - Updated all module-specific test scripts (`test:cache`, `test:config`, `test:endpoint`) to use Jest
+  - Updated CI/CD configuration to run Jest only
+  - Updated documentation (README, CONTRIBUTING, AGENTS, steering documents) to reflect Jest-only testing
+- **ApiRequest** and **CachedSsmParameter** renaming to conform to naming conventions:
+  - `APIRequest` has been renamed to `ApiRequest`.
+  - `APIRequest` is now aliased to `ApiRequest` and will still work. 
+  - `CachedSSMParameter` has been renamed to `CachedSsmParameter`.
+  - `CachedSSMParameter` is now aliased to `CachedSsmParameter` and will still work. 
+  - While there is no timeframe to deprecate and remove the old naming, it will happen with a future **major** version update.
+  - New code should use the new conventions. Old code should be updated.
+- **tools.endpoint.get()** deprecated in favor of **tools.endpoint.send()**
+  - `tools.endpoint.send()` removes any confusion about it accepting more than just `GET` requests and that it will send immediately when called.
+- **Optimized Generic Response** for easier maintenance
+
+### Added
+
+- **Enhanced Invalid Request Messaging**
+- **New Response Formatting to ApiRequest**
+
+
+### Removed
+
+- **Mocha, Chai, and Sinon Dependencies** [Spec: 1-3-10-test-migration-phase-6](.kiro/specs/1-3-10-test-migration-phase-6/)
+  - Removed `mocha` from devDependencies
+  - Removed `chai` from devDependencies
+  - Removed `sinon` from devDependencies
+  - Removed `chai-http` from devDependencies
+  - Removed all legacy Mocha test files (`*-tests.mjs`)
+  - Removed `test:all` script (no longer needed with single test framework)
 
-- Unreleased
 
 ## v1.3.9 (2026-03-09)
 
@@ -92,14 +133,14 @@ Report all vulnerabilities under the [Security menu](https://github.com/63Klabs/
   - Production dependencies remain secure (0 vulnerabilities)
 
 ### Added
-- **APIRequest Pagination, Retry, and X-Ray Enhancements** [Spec: 1-3-8-api-request-pagination-retries-xray](.kiro/specs/1-3-8-api-request-pagination-retries-xray/) addresses [#171](https://github.com/63Klabs/cache-data/issues/171), [#172](https://github.com/63Klabs/cache-data/issues/172), [#173](https://github.com/63Klabs/cache-data/issues/173)
-  - **Automatic Pagination**: APIRequest now supports automatic pagination for APIs that return paginated results
+- **ApiRequest Pagination, Retry, and X-Ray Enhancements** [Spec: 1-3-8-api-request-pagination-retries-xray](.kiro/specs/1-3-8-api-request-pagination-retries-xray/) addresses [#171](https://github.com/63Klabs/cache-data/issues/171), [#172](https://github.com/63Klabs/cache-data/issues/172), [#173](https://github.com/63Klabs/cache-data/issues/173)
+  - **Automatic Pagination**: ApiRequest now supports automatic pagination for APIs that return paginated results
     - Configurable pagination labels for different API response structures
     - Batch processing for concurrent page requests
     - Support for both offset-based and token-based pagination
     - Automatic result combination into single response
     - Pagination metadata in response (total pages, total items, incomplete status)
-  - **Automatic Retry Logic**: APIRequest now includes built-in retry functionality for transient failures
+  - **Automatic Retry Logic**: ApiRequest now includes built-in retry functionality for transient failures
     - Configurable retry attempts (default: 1 retry after initial attempt)
     - Automatic retry on network errors, empty responses, parse errors, and 5xx status codes
     - Optional retry on 4xx status codes (disabled by default)
@@ -275,9 +316,9 @@ While `DebugAndLog` has also been optimized, there is no change to its results.
 
 ## 1.1.4 (2025-03-18) Added XRay sub-segment for API requests
 
-- Feature: Added XRay Segment for APIRequest class
+- Feature: Added XRay Segment for ApiRequest class
 
-When using the tools.APIRequest class, each remote request is now annotated and provided meta data.
+When using the tools.ApiRequest class, each remote request is now annotated and provided meta data.
 
 ## 1.1.3 (2025-02-17) Additional Options for Sending Parameters via Query String
 

package/CONTRIBUTING.md

@@ -120,10 +120,63 @@ Ensure all tests pass before submitting changes:
 npm test
 
 # Run specific test suites
-npm test -- test/documentation/
-npm test -- test/cache/
+npm test -- test/documentation
+npm test -- test/cache
 ```
 
+## Testing
+
+This project uses Jest as its test framework. All tests use the `.jest.mjs` file extension.
+
+### Test Framework
+
+- Test Runner: Jest
+- Assertions: Jest built-in (`expect`)
+- Property Testing: fast-check
+- Mocking: Jest built-in (`jest.spyOn`, `jest.fn`)
+- File Pattern: `*.jest.mjs`
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test suites
+npm test -- test/cache
+npm test -- test/endpoint
+npm test -- test/documentation
+```
+
+### Writing Tests
+
+All tests must use Jest. Example:
+
+```javascript
+import { describe, it, expect, jest, afterEach } from '@jest/globals';
+import { Cache } from '../src/lib/dao-cache.js';
+
+describe('Cache', () => {
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    it('should generate consistent hash for same input', () => {
+        const conn = { host: 'example.com', path: '/api' };
+        const hash1 = Cache.generateIdHash(conn);
+        const hash2 = Cache.generateIdHash(conn);
+        expect(hash1).toBe(hash2);
+    });
+});
+```
+
+### Test Naming Conventions
+
+- Test files: `*-tests.jest.mjs`
+- Property tests: `*-property-tests.jest.mjs`
+- Integration tests: `*-integration-tests.jest.mjs`
+- Unit tests: `*-unit-tests.jest.mjs`
+
 ## Documentation Standards
 
 All public APIs must have complete JSDoc documentation. See [JSDoc Documentation Standards](.kiro/steering/documentation-standards-jsdoc.md) for detailed requirements.
@@ -149,7 +202,7 @@ All public APIs must have complete JSDoc documentation. See [JSDoc Documentation
  * @example
  * const result = await CacheableDataAccess.getData(
  *   cacheProfile,
- *   endpoint.get,
+ *   endpoint.send,
  *   connection
  * );
  * console.log(result.data);

package/README.md

@@ -116,7 +116,7 @@ cache.Cache.init({
 // Retrieve cached data
 const conn = { host: "api.example.com", path: "api/users"};
 const cacheProfile = {/* cache parameters */};
-const cachedData = await CacheableDataAccess.getData(cacheProfile, endpoint.get, conn);
+const cachedData = await CacheableDataAccess.getData(cacheProfile, endpoint.send, conn);
 const data = cachedData.getBody(true);
 ```
 
@@ -126,7 +126,7 @@ const data = cachedData.getBody(true);
 const { endpoint } = require("@63klabs/cache-data");
 
 // Make a simple GET request to an API
-const response = await endpoint.get(
+const response = await endpoint.send(
   { host: "api.example.com", path: "/data", parameters: { q: "search-term" } }
 );
 
@@ -134,13 +134,13 @@ console.log("API Response:", response.body);
 console.log("Status Code:", response.statusCode);
 ```
 
-### Using APIRequest with Pagination and Retry
+### Using ApiRequest with Pagination and Retry
 
 ```javascript
-const { tools: {APIRequest} } = require("@63klabs/cache-data");
+const { tools: {ApiRequest} } = require("@63klabs/cache-data");
 
 // Make a request with automatic pagination and retry
-const request = new tools.APIRequest({
+const request = new tools.ApiRequest({
   host: "api.example.com",
   path: "/users",
   parameters: {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@63klabs/cache-data",
-  "version": "1.3.9",
-  "description": "Cache data from an API endpoint or application process using AWS S3 and DynamoDb",
-  "author": "Chad Leigh Kluck (https://chadkluck.me)",
+  "version": "1.3.10",
+  "description": "A package for AWS Lambda Node.js applications to access and cache data from remote API endpoints (or other sources) utilizing AWS S3 and DynamoDb for the cache storage. Also provides a simple request handling, routing, and response logging framework for running a web service with minimal dependencies.",
+  "author": "Chad Kluck (https://chadkluck.me)",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,36 +26,24 @@
     "@aws-sdk/client-ssm": "^3.995.0",
     "@aws-sdk/lib-dynamodb": "^3.995.0",
     "@eslint/js": "^10.0.1",
-    "chai": "^6.2.2",
-    "chai-http": "^5.1.2",
     "eslint": "^10.0.1",
     "fast-check": "^4.5.3",
-    "jest": "^30.2.0",
-    "mocha": "^11.7.5",
-    "sinon": "^21.0.1"
-  },
+    "jest": "^30.2.0"  },
   "overrides": {
-    "diff": ">=8.0.3",
     "fast-xml-parser": ">=5.3.4",
     "glob": ">=13.0.6",
-    "minimatch": ">=10.2.2",
-    "serialize-javascript": ">=7.0.3"
+    "minimatch": ">=10.2.2"
   },
   "scripts": {
-    "test": "mocha 'test/**/*-tests.mjs' --exclude 'test/migration/property/test-execution-equivalence-property-tests.mjs'",
-    "test:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "test:all": "npm test && npm run test:jest",
-    "test:migration:validation": "mocha test/migration/property/test-execution-equivalence-property-tests.mjs",
-    "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:endpoint:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/endpoint",
-    "test:tools:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/tools",
-    "test:logging": "mocha 'test/logging/**/*-tests.mjs'",
-    "test:request": "mocha 'test/request/**/*-tests.mjs'",
-    "test:response": "mocha 'test/response/**/*-tests.mjs'",
-    "test:utils": "mocha 'test/utils/**/*-tests.mjs'",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:cache": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/cache",
+    "test:config": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/config",
+    "test:endpoint": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/endpoint",
+    "test:tools": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/tools",
+    "test:logging": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/logging",
+    "test:request": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/request",
+    "test:response": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/response",
+    "test:utils": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/utils",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "lint:ci": "eslint . --max-warnings 0"

package/src/lib/dao-cache.js

@@ -38,9 +38,10 @@ const moment = require('moment-timezone');
  * and retrieval operations - cache expiration logic and data management are
  * handled by the CacheData class.
  * 
- * Use this class when you need direct access to S3 cache storage operations.
- * For most use cases, use the Cache or CacheableDataAccess classes instead.
+ * Used by Cache object to write and retrieve data that is larger than what
+ * we want to store in DynamoDB
  * 
+ * @private
  * @example
  * // Initialize S3Cache with bucket name
  * S3Cache.init('my-cache-bucket');
@@ -57,8 +58,13 @@ class S3Cache {
 	static #bucket = null;
 	static #objPath = "cache/";
 
-	constructor () {
-	};
+	/**
+	 * Create a new S3Cache instance.
+	 * Private constructor - instances should be created through static methods.
+	 *
+	 * @private
+	 */
+	constructor () {};
 
 	/**
 	 * Get the S3 bucket name configured for cache storage.
@@ -106,7 +112,6 @@ class S3Cache {
 	 * process.env.CACHE_DATA_S3_BUCKET = 'my-cache-bucket';
 	 * S3Cache.init();
 	 */
-
 	static init(bucket = null) {
 		if ( S3Cache.getBucket() === null ) {
 			bucket = (bucket === null) ? process.env?.CACHE_DATA_S3_BUCKET || null : bucket;
@@ -272,14 +277,14 @@ class S3Cache {
 };
 
 /**
- * Basic DynamoDb read/write for cache data. Provides low-level storage operations
+ * Basic DynamoDB read/write for cache data. Provides low-level storage operations
  * for cached data in Amazon DynamoDB. This class handles only the storage format
  * and retrieval operations - cache expiration logic and data management are
  * handled by the CacheData class.
  * 
- * Use this class when you need direct access to DynamoDB cache storage operations.
- * For most use cases, use the Cache or CacheableDataAccess classes instead.
+ * Used by Cache object to write and retrieve data in DynamoDB
  * 
+ * @private
  * @example
  * // Initialize DynamoDbCache with table name
  * DynamoDbCache.init('my-cache-table');
@@ -455,8 +460,8 @@ class DynamoDbCache {
  * coordinates storage between DynamoDB (for small items) and S3 (for large items).
  * 
  * This class is used internally by the publicly exposed Cache class and should
- * not be used directly in most cases. Use the Cache or CacheableDataAccess
- * classes instead for application-level caching.
+ * not be used directly. Use the CacheableDataAccess to access data for
+ * application-level caching.
  * 
  * Key responsibilities:
  * - Expiration time calculations and interval-based caching
@@ -464,6 +469,7 @@ class DynamoDbCache {
  * - Automatic routing between DynamoDB and S3 based on size
  * - ETag and Last-Modified header generation
  * 
+ * @private
  * @example
  * // Initialize CacheData (typically done through Cache.init())
  * CacheData.init({
@@ -508,7 +514,7 @@ class CacheData {
 	 * @param {string} [parameters.dynamoDbTable] DynamoDB table name (or use CACHE_DATA_DYNAMO_DB_TABLE env var)
 	 * @param {string} [parameters.s3Bucket] S3 bucket name (or use CACHE_DATA_S3_BUCKET env var)
 	 * @param {string} [parameters.secureDataAlgorithm='aes-256-cbc'] Encryption algorithm (or use CACHE_DATA_SECURE_DATA_ALGORITHM env var)
-	 * @param {string|Buffer|tools.Secret|tools.CachedSSMParameter|tools.CachedSecret} parameters.secureDataKey Encryption key (required, no env var for security)
+	 * @param {string|Buffer|tools.Secret|tools.CachedSsmParameter|tools.CachedSecret} parameters.secureDataKey Encryption key (required, no env var for security)
 	 * @param {number} [parameters.DynamoDbMaxCacheSize_kb=10] Max size in KB for DynamoDB storage (or use CACHE_DATA_DYNAMO_DB_MAX_CACHE_SIZE_KB env var)
 	 * @param {number} [parameters.purgeExpiredCacheEntriesAfterXHours=24] Hours after expiration to purge entries (or use CACHE_DATA_PURGE_EXPIRED_CACHE_ENTRIES_AFTER_X_HRS env var)
 	 * @param {string} [parameters.timeZoneForInterval='Etc/UTC'] Timezone for interval calculations (or use CACHE_DATA_TIME_ZONE_FOR_INTERVAL env var)
@@ -1373,26 +1379,18 @@ class CacheData {
 };
 
 /**
- * The Cache object handles the settings for the cache system
+ * The Cache object handles the settings for the cache system and is only
+ * accessed by the application during init.
  * 
- * Before using it must be initialized. 
+ * Reading of the cache is done through CacheableDataAccess.getData()
+ * 
+ * Before using the Cache, it must be initialized. 
  * 
  * Many settings can be set through Environment variables or by
  * passing parameters to Cache.init():
  * 
  * Cache.init({parameters});
  * 
- * Then you can then make a request, sending it through CacheableDataAccess:
- * 
- *  const { cache } = require("@63klabs/cache-data");
- * 
- *	const cacheObj = await cache.CacheableDataAccess.getData(
- *		cacheCfg, 
- *		yourFetchFunction,
- *		conn, 
- *		daoQuery
- *	);
- * 
  * @example
  * // Initialize the cache system
  * Cache.init({
@@ -1401,13 +1399,6 @@ class CacheData {
  *   idHashAlgorithm: 'sha256'
  * });
  * 
- * // Create a cache instance with connection and profile
- * const connection = { host: 'api.example.com', path: '/data' };
- * const cacheProfile = { 
- *   defaultExpirationInSeconds: 300,
- *   encrypt: true 
- * };
- * const cacheInstance = new Cache(connection, cacheProfile);
  */
 class Cache {
 
@@ -1526,7 +1517,7 @@ class Cache {
 	 * @param {string} parameters.dynamoDbTable Can also be set with environment variable CACHE_DATA_DYNAMO_DB_TABLE
 	 * @param {string} parameters.s3Bucket Can also be set with environment variable CACHE_DATA_S3_BUCKET
 	 * @param {string} parameters.secureDataAlgorithm Can also be set with environment variable CACHE_DATA_SECURE_DATA_ALGORITHM
-	 * @param {string|Buffer|tools.Secret|tools.CachedSSMParameter|tools.CachedSecret} parameters.secureDataKey Must be passed, will not accept an environment variable for security reasons.
+	 * @param {string|Buffer|tools.Secret|tools.CachedSsmParameter|tools.CachedSecret} parameters.secureDataKey Must be passed, will not accept an environment variable for security reasons.
 	 * @param {number} parameters.DynamoDbMaxCacheSize_kb Can also be set with environment variable CACHE_DATA_DYNAMO_DB_MAX_CACHE_SIZE_KB
 	 * @param {number} parameters.purgeExpiredCacheEntriesAfterXHours Can also be set with environment variable CACHE_DATA_PURGE_EXPIRED_CACHE_ENTRIES_AFTER_X_HRS
 	 * @param {string} parameters.timeZoneForInterval Can also be set with environment variable CACHE_DATA_TIME_ZONE_FOR_INTERVAL
@@ -3012,7 +3003,7 @@ class Cache {
 /**
  * The CacheableDataAccess object provides an interface to 
  * the cache. It is responsible for reading from and writing to cache.
- * All requests to data go through the cache
+ * All requests to data go through CacheableDataAccess.getData
  * 
  * Before using CacheableDataAccess, the Cache must be initialized. 
  * 
@@ -3099,7 +3090,7 @@ class CacheableDataAccess {
 	 *
 	 * const cache = await CacheableDataAccess.getData(
 	 *   cachePolicy,
-	 *   endpoint.get,
+	 *   endpoint.send,
 	 *   connection,
 	 *   null,
 	 *   {path: 'users', id: '123'}