@63klabs/cache-data 1.3.6 → 1.3.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/{AI_CONTEXT.md → AGENTS.md} +164 -15
- package/CHANGELOG.md +76 -3
- package/CONTRIBUTING.md +19 -14
- package/README.md +42 -3
- package/eslint.config.js +53 -0
- package/package.json +28 -13
- package/src/lib/dao-cache.js +136 -11
- package/src/lib/tools/APIRequest.class.js +948 -91
- package/src/lib/tools/ClientRequest.class.js +34 -1
- package/src/lib/tools/Connections.classes.js +40 -3
- package/src/lib/tools/Response.class.js +11 -0
- package/src/lib/tools/generic.response.html.js +33 -0
- package/src/lib/tools/generic.response.json.js +40 -1
- package/src/lib/tools/generic.response.rss.js +33 -0
- package/src/lib/tools/generic.response.text.js +34 -1
- package/src/lib/tools/generic.response.xml.js +39 -0
- package/src/lib/tools/index.js +148 -49
- package/scripts/README.md +0 -175
- package/scripts/audit-documentation.mjs +0 -856
- package/scripts/review-documentation-files.mjs +0 -406
- package/scripts/setup-dev-environment.sh +0 -59
- package/scripts/verify-example-files.mjs +0 -194
|
@@ -391,14 +391,91 @@ This package is used in high-traffic Lambda functions. Performance matters.
|
|
|
391
391
|
|
|
392
392
|
## 5. Testing Strategy
|
|
393
393
|
|
|
394
|
-
### 5.1 Test
|
|
394
|
+
### 5.1 Test Framework Migration
|
|
395
|
+
|
|
396
|
+
**CRITICAL: Mocha to Jest Migration in Progress**
|
|
397
|
+
|
|
398
|
+
This project is actively migrating from Mocha to Jest. During this transition period:
|
|
399
|
+
|
|
400
|
+
**Migration Status:**
|
|
401
|
+
- **Phase**: Active migration - both frameworks supported
|
|
402
|
+
- **Legacy**: Mocha tests (`*-tests.mjs`) - maintain but don't create new
|
|
403
|
+
- **Current**: Jest tests (`*.jest.mjs`) - all new tests must use this
|
|
404
|
+
- **Goal**: Complete migration to Jest, remove Mocha dependency
|
|
405
|
+
|
|
406
|
+
**File Naming Conventions:**
|
|
407
|
+
- Mocha (legacy): `cache-tests.mjs`, `endpoint-tests.mjs`, `*-property-tests.mjs`
|
|
408
|
+
- Jest (current): `cache-tests.jest.mjs`, `endpoint-tests.jest.mjs`, `*-property-tests.jest.mjs`
|
|
409
|
+
|
|
410
|
+
**Test Execution Commands:**
|
|
411
|
+
```bash
|
|
412
|
+
# Run Mocha tests only (legacy)
|
|
413
|
+
npm test
|
|
414
|
+
|
|
415
|
+
# Run Jest tests only (current)
|
|
416
|
+
npm run test:jest
|
|
417
|
+
|
|
418
|
+
# Run both test suites (REQUIRED for CI/CD)
|
|
419
|
+
npm run test:all
|
|
420
|
+
|
|
421
|
+
# Run specific test suites
|
|
422
|
+
npm run test:cache # Mocha cache tests
|
|
423
|
+
npm run test:cache:jest # Jest cache tests
|
|
424
|
+
npm run test:endpoint # Mocha endpoint tests
|
|
425
|
+
npm run test:endpoint:jest # Jest endpoint tests
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
**Migration Guidelines:**
|
|
429
|
+
|
|
430
|
+
1. **Creating New Tests:**
|
|
431
|
+
- ALWAYS use Jest (`*.jest.mjs` files)
|
|
432
|
+
- Follow Jest patterns and assertions
|
|
433
|
+
- Use Jest mocking (not Sinon)
|
|
434
|
+
- Place in same directory as Mocha tests
|
|
435
|
+
|
|
436
|
+
2. **Modifying Existing Tests:**
|
|
437
|
+
- If minor change: Update Mocha test
|
|
438
|
+
- If major change: Consider migrating to Jest
|
|
439
|
+
- If time permits: Migrate to Jest and delete Mocha version
|
|
440
|
+
|
|
441
|
+
3. **Test Coverage:**
|
|
442
|
+
- Both test suites must pass in CI/CD
|
|
443
|
+
- Jest coverage: `coverage-jest/` directory
|
|
444
|
+
- Mocha coverage: `coverage/` directory (if generated)
|
|
445
|
+
|
|
446
|
+
4. **Property-Based Tests:**
|
|
447
|
+
- Use fast-check in both Mocha and Jest
|
|
448
|
+
- Same property definitions work in both frameworks
|
|
449
|
+
- Migrate property tests to Jest when possible
|
|
450
|
+
|
|
451
|
+
**Why Jest?**
|
|
452
|
+
- Better ESM support
|
|
453
|
+
- Built-in mocking (no Sinon needed)
|
|
454
|
+
- Better async/await handling
|
|
455
|
+
- More modern and actively maintained
|
|
456
|
+
- Better IDE integration
|
|
457
|
+
- Simpler configuration
|
|
458
|
+
|
|
459
|
+
**Migration Checklist for Converting Tests:**
|
|
460
|
+
- [ ] Create new `*.jest.mjs` file
|
|
461
|
+
- [ ] Import from `@jest/globals` instead of `chai`
|
|
462
|
+
- [ ] Change `expect().to.equal()` to `expect().toBe()`
|
|
463
|
+
- [ ] Change `expect().to.not.equal()` to `expect().not.toBe()`
|
|
464
|
+
- [ ] Replace Sinon mocks with Jest mocks
|
|
465
|
+
- [ ] Update async test patterns if needed
|
|
466
|
+
- [ ] Run Jest tests to verify: `npm run test:jest`
|
|
467
|
+
- [ ] Delete old Mocha test file
|
|
468
|
+
- [ ] Update any references in documentation
|
|
469
|
+
|
|
470
|
+
### 5.2 Test Organization
|
|
395
471
|
|
|
396
472
|
Tests mirror source structure:
|
|
397
473
|
|
|
398
474
|
```
|
|
399
475
|
test/
|
|
400
476
|
├── cache/ # Cache module tests
|
|
401
|
-
│ ├── cache-tests.mjs
|
|
477
|
+
│ ├── cache-tests.mjs (Mocha - legacy)
|
|
478
|
+
│ ├── cache-tests.jest.mjs (Jest - new)
|
|
402
479
|
│ ├── in-memory-cache/
|
|
403
480
|
│ │ ├── unit/
|
|
404
481
|
│ │ ├── integration/
|
|
@@ -407,6 +484,8 @@ test/
|
|
|
407
484
|
├── documentation/ # Documentation validation
|
|
408
485
|
│ └── property/
|
|
409
486
|
├── endpoint/ # Endpoint module tests
|
|
487
|
+
│ ├── endpoint-tests.mjs (Mocha - legacy)
|
|
488
|
+
│ ├── endpoint-tests.jest.mjs (Jest - new)
|
|
410
489
|
├── logging/ # Logging tests
|
|
411
490
|
├── request/ # Request handling tests
|
|
412
491
|
├── response/ # Response tests
|
|
@@ -414,22 +493,72 @@ test/
|
|
|
414
493
|
└── helpers/ # Test utilities
|
|
415
494
|
```
|
|
416
495
|
|
|
417
|
-
|
|
496
|
+
**Note**: During migration, both `.mjs` (Mocha) and `.jest.mjs` (Jest) files coexist in the same directories.
|
|
497
|
+
|
|
498
|
+
### 5.3 Test Naming Conventions
|
|
418
499
|
|
|
500
|
+
**Mocha (Legacy):**
|
|
419
501
|
- Test files: `*-tests.mjs`
|
|
420
502
|
- Property tests: `*-property-tests.mjs`
|
|
421
503
|
- Integration tests: `*-integration-tests.mjs`
|
|
422
504
|
- Unit tests: `*-unit-tests.mjs` or `*-tests.mjs`
|
|
423
505
|
|
|
424
|
-
|
|
506
|
+
**Jest (Current - Use for All New Tests):**
|
|
507
|
+
- Test files: `*.jest.mjs`
|
|
508
|
+
- Property tests: `*-property-tests.jest.mjs`
|
|
509
|
+
- Integration tests: `*-integration-tests.jest.mjs`
|
|
510
|
+
- Unit tests: `*-unit-tests.jest.mjs` or `*.jest.mjs`
|
|
511
|
+
|
|
512
|
+
### 5.4 Test Framework
|
|
513
|
+
|
|
514
|
+
**CRITICAL: Test Framework Migration in Progress**
|
|
515
|
+
|
|
516
|
+
This project is currently migrating from Mocha to Jest. Both frameworks are supported during the transition period.
|
|
517
|
+
|
|
518
|
+
**Current Status:**
|
|
519
|
+
- **Legacy Tests**: Mocha tests (files ending in `-tests.mjs`)
|
|
520
|
+
- **New Tests**: Jest tests (files ending in `.jest.mjs`)
|
|
521
|
+
- **Migration Goal**: All tests will eventually be in Jest
|
|
425
522
|
|
|
426
|
-
|
|
427
|
-
- **Assertions**: Chai (expect style)
|
|
428
|
-
- **Property Testing**: fast-check
|
|
429
|
-
- **Mocking**: Sinon (when necessary)
|
|
430
|
-
- **HTTP Testing**: chai-http
|
|
523
|
+
**Test Framework by Type:**
|
|
431
524
|
|
|
432
|
-
|
|
525
|
+
**Mocha (Legacy - Being Phased Out):**
|
|
526
|
+
- Test Runner: Mocha
|
|
527
|
+
- Assertions: Chai (expect style)
|
|
528
|
+
- Property Testing: fast-check
|
|
529
|
+
- Mocking: Sinon
|
|
530
|
+
- HTTP Testing: chai-http
|
|
531
|
+
- File Pattern: `*-tests.mjs`
|
|
532
|
+
|
|
533
|
+
**Jest (Current - All New Tests):**
|
|
534
|
+
- Test Runner: Jest
|
|
535
|
+
- Assertions: Jest built-in (expect)
|
|
536
|
+
- Property Testing: fast-check (same as Mocha)
|
|
537
|
+
- Mocking: Jest built-in
|
|
538
|
+
- HTTP Testing: Jest with mocks
|
|
539
|
+
- File Pattern: `*.jest.mjs`
|
|
540
|
+
|
|
541
|
+
**Rules for Test Development:**
|
|
542
|
+
|
|
543
|
+
1. **ALL NEW TESTS MUST BE WRITTEN IN JEST** using the `*.jest.mjs` file pattern
|
|
544
|
+
2. **DO NOT create new Mocha tests** - only maintain existing ones
|
|
545
|
+
3. **When modifying existing tests**, consider migrating to Jest if time permits
|
|
546
|
+
4. **Both test suites must pass** before merging (`npm run test:all`)
|
|
547
|
+
5. **Jest tests coexist with Mocha tests** in the same directories
|
|
548
|
+
|
|
549
|
+
**Test Execution:**
|
|
550
|
+
```bash
|
|
551
|
+
# Run Mocha tests (legacy)
|
|
552
|
+
npm test
|
|
553
|
+
|
|
554
|
+
# Run Jest tests (new)
|
|
555
|
+
npm run test:jest
|
|
556
|
+
|
|
557
|
+
# Run both test suites (required for CI/CD)
|
|
558
|
+
npm run test:all
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
### 5.5 Writing Good Tests
|
|
433
562
|
|
|
434
563
|
**DO**:
|
|
435
564
|
- Test one thing per test
|
|
@@ -438,6 +567,7 @@ test/
|
|
|
438
567
|
- Make tests deterministic
|
|
439
568
|
- Keep tests fast
|
|
440
569
|
- Use property-based testing for core logic
|
|
570
|
+
- **Write all new tests in Jest** (not Mocha)
|
|
441
571
|
|
|
442
572
|
**DON'T**:
|
|
443
573
|
- Test implementation details
|
|
@@ -445,11 +575,12 @@ test/
|
|
|
445
575
|
- Use real AWS services (mock them)
|
|
446
576
|
- Make tests dependent on each other
|
|
447
577
|
- Skip tests without good reason
|
|
578
|
+
- **Create new Mocha tests** (migration in progress)
|
|
448
579
|
|
|
449
|
-
**Example Test Structure:**
|
|
580
|
+
**Example Test Structure (Jest - Use This for New Tests):**
|
|
450
581
|
|
|
451
582
|
```javascript
|
|
452
|
-
import { expect } from '
|
|
583
|
+
import { describe, it, expect } from '@jest/globals';
|
|
453
584
|
import { Cache } from '../src/lib/dao-cache.js';
|
|
454
585
|
|
|
455
586
|
describe('Cache', () => {
|
|
@@ -458,7 +589,7 @@ describe('Cache', () => {
|
|
|
458
589
|
const conn = { host: 'example.com', path: '/api' };
|
|
459
590
|
const hash1 = Cache.generateIdHash(conn);
|
|
460
591
|
const hash2 = Cache.generateIdHash(conn);
|
|
461
|
-
expect(hash1).
|
|
592
|
+
expect(hash1).toBe(hash2);
|
|
462
593
|
});
|
|
463
594
|
|
|
464
595
|
it('should generate different hashes for different inputs', () => {
|
|
@@ -466,11 +597,29 @@ describe('Cache', () => {
|
|
|
466
597
|
const conn2 = { host: 'example.com', path: '/api2' };
|
|
467
598
|
const hash1 = Cache.generateIdHash(conn1);
|
|
468
599
|
const hash2 = Cache.generateIdHash(conn2);
|
|
469
|
-
expect(hash1).
|
|
600
|
+
expect(hash1).not.toBe(hash2);
|
|
470
601
|
});
|
|
471
602
|
|
|
472
603
|
it('should handle null input gracefully', () => {
|
|
473
|
-
expect(() => Cache.generateIdHash(null)).
|
|
604
|
+
expect(() => Cache.generateIdHash(null)).not.toThrow();
|
|
605
|
+
});
|
|
606
|
+
});
|
|
607
|
+
});
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
**Legacy Test Structure (Mocha - Maintain Only, Don't Create New):**
|
|
611
|
+
|
|
612
|
+
```javascript
|
|
613
|
+
import { expect } from 'chai';
|
|
614
|
+
import { Cache } from '../src/lib/dao-cache.js';
|
|
615
|
+
|
|
616
|
+
describe('Cache', () => {
|
|
617
|
+
describe('generateIdHash()', () => {
|
|
618
|
+
it('should generate consistent hash for same input', () => {
|
|
619
|
+
const conn = { host: 'example.com', path: '/api' };
|
|
620
|
+
const hash1 = Cache.generateIdHash(conn);
|
|
621
|
+
const hash2 = Cache.generateIdHash(conn);
|
|
622
|
+
expect(hash1).to.equal(hash2);
|
|
474
623
|
});
|
|
475
624
|
});
|
|
476
625
|
});
|
package/CHANGELOG.md
CHANGED
|
@@ -2,13 +2,86 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> **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.
|
|
6
|
+
|
|
7
|
+
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.
|
|
6
8
|
|
|
7
9
|
Report all vulnerabilities under the [Security menu](https://github.com/63Klabs/cache-data/security/advisories) in the Cache-Data GitHub repository.
|
|
8
10
|
|
|
9
|
-
## v1.3.
|
|
11
|
+
## v1.3.8 (2026-03-02)
|
|
12
|
+
|
|
13
|
+
### Security
|
|
14
|
+
- **Updated the way dependencies are listed reduce npm Security Vulnerabilities** [Spec: 1-3-8-npm-security-vulnerabilities-fix](.kiro/specs/1-3-8-npm-security-vulnerabilities-fix/)
|
|
15
|
+
- Fixed 1 low, 20 high, and 1 critical severity vulnerabilities in development dependencies
|
|
16
|
+
- Updated devDependencies to specific secure versions:
|
|
17
|
+
- `@aws-sdk/client-dynamodb`, `@aws-sdk/client-s3`, `@aws-sdk/client-ssm`, `@aws-sdk/lib-dynamodb`: Updated from `3.x` to `^3.995.0`
|
|
18
|
+
- `mocha`: Updated from `^11.x` to `^11.7.5`
|
|
19
|
+
- `chai`: Updated from `^6.x` to `^6.2.2`
|
|
20
|
+
- `chai-http`: Updated from `^5.x` to `^5.1.2`
|
|
21
|
+
- `sinon`: Updated from `^21.x` to `^21.0.1`
|
|
22
|
+
- `fast-check`: Updated from `^4.x` to `^4.5.3`
|
|
23
|
+
- Added npm overrides for transitive dependencies:
|
|
24
|
+
- `diff`: `>=8.0.3` (fixes low severity DoS vulnerability)
|
|
25
|
+
- `minimatch`: `>=10.2.2` (fixes high severity ReDoS vulnerability)
|
|
26
|
+
- `glob`: `>=13.0.6` (fixes transitive vulnerabilities)
|
|
27
|
+
- No breaking changes to public APIs
|
|
28
|
+
- All existing tests pass
|
|
29
|
+
- Production dependencies remain secure (0 vulnerabilities)
|
|
30
|
+
|
|
31
|
+
### Added
|
|
32
|
+
- **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)
|
|
33
|
+
- **Automatic Pagination**: APIRequest now supports automatic pagination for APIs that return paginated results
|
|
34
|
+
- Configurable pagination labels for different API response structures
|
|
35
|
+
- Batch processing for concurrent page requests
|
|
36
|
+
- Support for both offset-based and token-based pagination
|
|
37
|
+
- Automatic result combination into single response
|
|
38
|
+
- Pagination metadata in response (total pages, total items, incomplete status)
|
|
39
|
+
- **Automatic Retry Logic**: APIRequest now includes built-in retry functionality for transient failures
|
|
40
|
+
- Configurable retry attempts (default: 1 retry after initial attempt)
|
|
41
|
+
- Automatic retry on network errors, empty responses, parse errors, and 5xx status codes
|
|
42
|
+
- Optional retry on 4xx status codes (disabled by default)
|
|
43
|
+
- Retry metadata in response (attempts made, final attempt number)
|
|
44
|
+
- **Enhanced X-Ray Subsegments**: Improved AWS X-Ray tracing for better observability
|
|
45
|
+
- Unique subsegment names for each request using timestamps
|
|
46
|
+
- Retry and pagination metadata included in X-Ray traces
|
|
47
|
+
- Separate subsegments for each paginated request
|
|
48
|
+
- Detailed annotations and metadata for debugging
|
|
49
|
+
- **Response Metadata**: New optional metadata field in responses
|
|
50
|
+
- Retry information (occurred, attempts, final attempt)
|
|
51
|
+
- Pagination information (occurred, total pages, total items, incomplete status)
|
|
52
|
+
- Only present when retries or pagination occur
|
|
53
|
+
- **Backwards Compatibility Maintained**: All new features are opt-in via configuration
|
|
54
|
+
- Existing code continues to work without modification
|
|
55
|
+
- No breaking changes to public API
|
|
56
|
+
- Default behavior unchanged when new features not configured
|
|
57
|
+
- See documentation: [Pagination Guide](docs/features/tools/api-request-pagination.md), [Retry Guide](docs/features/tools/api-request-retry.md), [X-Ray Guide](docs/features/tools/api-request-xray.md)
|
|
58
|
+
- **tools.AppConfig** replaces `tools._ConfigSuperClass` and receives an `.init()` to simplify initialization
|
|
59
|
+
- Updated documentation to reflect how `Config` can be implemented to extend `tools._ConfigSuperClass`
|
|
60
|
+
- Instead of separate `Response.init()`, `ClientRequest.init()` and `Connections.init()` a single `AppConfig.init()` can be used within the `Config.init()`
|
|
61
|
+
|
|
62
|
+
### Enhancement
|
|
10
63
|
|
|
11
|
-
-
|
|
64
|
+
- **Expanded Generic Responses** - Additional responses for status codes
|
|
65
|
+
- Added responses for 408, 418, and 427
|
|
66
|
+
- Ensured all generic responses have the same statuses
|
|
67
|
+
- **Revised Documentation** - Clarified and revised documentation
|
|
68
|
+
- Reviewed all code examples
|
|
69
|
+
- Reviewed implementation instructions
|
|
70
|
+
|
|
71
|
+
## v1.3.7 (2026-02-06)
|
|
72
|
+
|
|
73
|
+
### Fixed
|
|
74
|
+
- **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
|
|
75
|
+
- Cache.getHeader() now normalizes undefined to null for consistent behavior
|
|
76
|
+
- Added defensive validation at header assignment points in CacheableDataAccess.getData()
|
|
77
|
+
- Added Cache._isValidHeaderValue() helper method for header validation
|
|
78
|
+
- **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.
|
|
79
|
+
|
|
80
|
+
### Added
|
|
81
|
+
- **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
|
|
82
|
+
- Configured Jest with ES module support
|
|
83
|
+
- Added npm scripts: `test:jest`, `test:all`, `test:cache:jest`
|
|
84
|
+
- Jest tests use `*.jest.mjs` pattern to avoid conflicts with Mocha tests
|
|
12
85
|
|
|
13
86
|
## v1.3.6 (2025-02-02)
|
|
14
87
|
|
package/CONTRIBUTING.md
CHANGED
|
@@ -12,6 +12,24 @@ Submit feature requests. To keep this project simple and maintainable we accept
|
|
|
12
12
|
|
|
13
13
|
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.
|
|
14
14
|
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
## Use of AI
|
|
20
|
+
|
|
21
|
+
This project utilizes the Spec-Driven, AI-Assisted Engineering approach.
|
|
22
|
+
|
|
23
|
+
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.
|
|
24
|
+
|
|
25
|
+
> Contributors are responsible for every line of code--AI-generated or not.
|
|
26
|
+
|
|
27
|
+
Code must be reviewed, understood, and tested by a human before being merged.
|
|
28
|
+
|
|
29
|
+
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.
|
|
30
|
+
|
|
31
|
+
Ensure [AGENTS](./AGENTS.md) and Kiro steering documents are reviewed, understood, and used by both humans and AI.
|
|
32
|
+
|
|
15
33
|
## Development Setup
|
|
16
34
|
|
|
17
35
|
Tests and documentation are critical to this project.
|
|
@@ -138,24 +156,11 @@ All public APIs must have complete JSDoc documentation. See [Documentation Stand
|
|
|
138
156
|
*/
|
|
139
157
|
```
|
|
140
158
|
|
|
141
|
-
## Use of AI
|
|
142
|
-
|
|
143
|
-
This project utilizes the Spec-Driven, AI-Assisted Engineering approach.
|
|
144
|
-
|
|
145
|
-
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.
|
|
146
|
-
|
|
147
|
-
> Contributors are responsible for every line of code--AI-generated or not.
|
|
148
|
-
|
|
149
|
-
Code must be reviewed, understood, and tested by a human before being merged.
|
|
150
|
-
|
|
151
|
-
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.
|
|
152
|
-
|
|
153
159
|
## Current Contributors
|
|
154
160
|
|
|
155
161
|
Thank you to the following people who have contributed to this project:
|
|
156
162
|
|
|
157
163
|
Chad Kluck\
|
|
158
164
|
DevOps & Developer Experience Engineer\
|
|
159
|
-
AWS Certified
|
|
160
|
-
Certified Solutions Architect - Associate\
|
|
165
|
+
AWS Certified Developer and Solutions Architect\
|
|
161
166
|
[Website](https://chadkluck.me)
|
package/README.md
CHANGED
|
@@ -29,7 +29,10 @@ The @63klabs/cache-data package provides three main modules:
|
|
|
29
29
|
- **Cache Profiles**: Configure multiple cache profiles with different expiration policies
|
|
30
30
|
|
|
31
31
|
### Endpoint Module
|
|
32
|
-
- **HTTP/HTTPS Requests**: Make requests to external APIs and endpoints with
|
|
32
|
+
- **HTTP/HTTPS Requests**: Make requests to external APIs and endpoints with automatic pagination, retry logic, and X-Ray tracing
|
|
33
|
+
- **Automatic Pagination**: Fetch all pages from paginated APIs automatically with configurable batch processing
|
|
34
|
+
- **Automatic Retry**: Retry failed requests with configurable conditions (network errors, server errors, empty responses)
|
|
35
|
+
- **Enhanced X-Ray Tracing**: Detailed monitoring and debugging with AWS X-Ray subsegments
|
|
33
36
|
- **Connection Management**: Define and manage multiple endpoint connections with authentication
|
|
34
37
|
- **Request Caching**: Automatically cache endpoint responses to reduce API calls and improve performance
|
|
35
38
|
- **Flexible Configuration**: Support for custom headers, query parameters, request bodies, and timeouts
|
|
@@ -136,6 +139,42 @@ console.log("API Response:", response.body);
|
|
|
136
139
|
console.log("Status Code:", response.statusCode);
|
|
137
140
|
```
|
|
138
141
|
|
|
142
|
+
### Using APIRequest with Pagination and Retry
|
|
143
|
+
|
|
144
|
+
```javascript
|
|
145
|
+
const { tools } = require("@63klabs/cache-data");
|
|
146
|
+
|
|
147
|
+
// Make a request with automatic pagination and retry
|
|
148
|
+
const request = new tools.APIRequest({
|
|
149
|
+
host: "api.example.com",
|
|
150
|
+
path: "/users",
|
|
151
|
+
parameters: {
|
|
152
|
+
limit: 100 // Items per page
|
|
153
|
+
},
|
|
154
|
+
pagination: {
|
|
155
|
+
enabled: true // Automatically fetch all pages
|
|
156
|
+
},
|
|
157
|
+
retry: {
|
|
158
|
+
enabled: true,
|
|
159
|
+
maxRetries: 2 // Retry failed requests up to 2 times
|
|
160
|
+
}
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
const response = await request.send();
|
|
164
|
+
|
|
165
|
+
// Response contains all users from all pages
|
|
166
|
+
const allUsers = JSON.parse(response.body).items;
|
|
167
|
+
console.log(`Retrieved ${allUsers.length} total users`);
|
|
168
|
+
|
|
169
|
+
// Check metadata
|
|
170
|
+
if (response.metadata?.pagination?.occurred) {
|
|
171
|
+
console.log(`Fetched ${response.metadata.pagination.totalPages} pages`);
|
|
172
|
+
}
|
|
173
|
+
if (response.metadata?.retries?.occurred) {
|
|
174
|
+
console.log(`Succeeded after ${response.metadata.retries.attempts} attempts`);
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
139
178
|
### Using Utility Tools
|
|
140
179
|
|
|
141
180
|
```javascript
|
|
@@ -198,8 +237,8 @@ This will install dependencies, configure the pre-commit hook for documentation
|
|
|
198
237
|
|
|
199
238
|
## AI Context
|
|
200
239
|
|
|
201
|
-
See [
|
|
240
|
+
See [AGENTS.md](AGENTS.md) for important context and guidelines for AI-generated code in this repository.
|
|
202
241
|
|
|
203
242
|
The context file is also helpful (and perhaps essential) for HUMANS developing within the application's structured platform as well.
|
|
204
243
|
|
|
205
|
-
AI Assisted Engineering of this solution was provided by [Kiro](https://kiro.dev/). Steering documents are provided in the repository's
|
|
244
|
+
AI Assisted Engineering of this solution was provided by [Kiro](https://kiro.dev/). Steering documents are provided in the repository's `.kiro/steering/` directory. Because testing is tightly coupled with the implementation, it is suggested all documents, code, and tests are thoroughly reviewed before, and updated after, any changes.
|
package/eslint.config.js
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import js from '@eslint/js';
|
|
2
|
+
|
|
3
|
+
export default [
|
|
4
|
+
js.configs.recommended,
|
|
5
|
+
{
|
|
6
|
+
languageOptions: {
|
|
7
|
+
ecmaVersion: 'latest',
|
|
8
|
+
sourceType: 'module',
|
|
9
|
+
globals: {
|
|
10
|
+
// Node.js globals
|
|
11
|
+
console: 'readonly',
|
|
12
|
+
process: 'readonly',
|
|
13
|
+
Buffer: 'readonly',
|
|
14
|
+
__dirname: 'readonly',
|
|
15
|
+
__filename: 'readonly',
|
|
16
|
+
exports: 'writable',
|
|
17
|
+
module: 'writable',
|
|
18
|
+
require: 'readonly',
|
|
19
|
+
global: 'readonly',
|
|
20
|
+
// Mocha globals
|
|
21
|
+
describe: 'readonly',
|
|
22
|
+
it: 'readonly',
|
|
23
|
+
before: 'readonly',
|
|
24
|
+
after: 'readonly',
|
|
25
|
+
beforeEach: 'readonly',
|
|
26
|
+
afterEach: 'readonly',
|
|
27
|
+
// ES2021 globals
|
|
28
|
+
globalThis: 'readonly'
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
rules: {
|
|
32
|
+
'no-template-curly-in-string': 'error',
|
|
33
|
+
'no-eval': 'error',
|
|
34
|
+
'no-implied-eval': 'error',
|
|
35
|
+
'no-new-func': 'error'
|
|
36
|
+
}
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
files: ['test/**/*.mjs', 'test/**/*.js', 'scripts/**/*.mjs', 'scripts/**/*.js', 'src/**/*.js'],
|
|
40
|
+
rules: {
|
|
41
|
+
'no-restricted-imports': ['error', {
|
|
42
|
+
patterns: [{
|
|
43
|
+
group: ['child_process'],
|
|
44
|
+
importNames: ['exec', 'execSync'],
|
|
45
|
+
message: 'Use execFile or execFileSync instead of exec/execSync to prevent shell injection. See .kiro/steering/secure-coding-practices.md'
|
|
46
|
+
}]
|
|
47
|
+
}]
|
|
48
|
+
}
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
ignores: ['node_modules/**', 'coverage/**', 'coverage-jest/**', '.git/**']
|
|
52
|
+
}
|
|
53
|
+
];
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@63klabs/cache-data",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.8",
|
|
4
4
|
"description": "Cache data from an API endpoint or application process using AWS S3 and DynamoDb",
|
|
5
5
|
"author": "Chad Leigh Kluck (https://chadkluck.me)",
|
|
6
6
|
"license": "MIT",
|
|
@@ -21,28 +21,43 @@
|
|
|
21
21
|
"object-hash": "^3.0.0"
|
|
22
22
|
},
|
|
23
23
|
"devDependencies": {
|
|
24
|
-
"@aws-sdk/client-dynamodb": "3.
|
|
25
|
-
"@aws-sdk/client-s3": "3.
|
|
26
|
-
"@aws-sdk/client-ssm": "3.
|
|
27
|
-
"@aws-sdk/lib-dynamodb": "3.
|
|
28
|
-
"
|
|
29
|
-
"chai
|
|
30
|
-
"
|
|
31
|
-
"
|
|
32
|
-
"
|
|
24
|
+
"@aws-sdk/client-dynamodb": "^3.995.0",
|
|
25
|
+
"@aws-sdk/client-s3": "^3.995.0",
|
|
26
|
+
"@aws-sdk/client-ssm": "^3.995.0",
|
|
27
|
+
"@aws-sdk/lib-dynamodb": "^3.995.0",
|
|
28
|
+
"@eslint/js": "^10.0.1",
|
|
29
|
+
"chai": "^6.2.2",
|
|
30
|
+
"chai-http": "^5.1.2",
|
|
31
|
+
"eslint": "^10.0.1",
|
|
32
|
+
"fast-check": "^4.5.3",
|
|
33
|
+
"jest": "^30.2.0",
|
|
34
|
+
"mocha": "^11.7.5",
|
|
35
|
+
"sinon": "^21.0.1"
|
|
33
36
|
},
|
|
34
37
|
"overrides": {
|
|
35
|
-
"fast-xml-parser": ">=5.3.4"
|
|
38
|
+
"fast-xml-parser": ">=5.3.4",
|
|
39
|
+
"diff": ">=8.0.3",
|
|
40
|
+
"minimatch": ">=10.2.2",
|
|
41
|
+
"glob": ">=13.0.6"
|
|
36
42
|
},
|
|
37
43
|
"scripts": {
|
|
38
|
-
"test": "mocha 'test/**/*-tests.mjs'",
|
|
44
|
+
"test": "mocha 'test/**/*-tests.mjs' --exclude 'test/migration/property/test-execution-equivalence-property-tests.mjs'",
|
|
45
|
+
"test:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
|
|
46
|
+
"test:all": "npm test && npm run test:jest",
|
|
47
|
+
"test:migration:validation": "mocha test/migration/property/test-execution-equivalence-property-tests.mjs",
|
|
39
48
|
"test:cache": "mocha 'test/cache/**/*-tests.mjs'",
|
|
49
|
+
"test:cache:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/cache",
|
|
40
50
|
"test:config": "mocha 'test/config/**/*-tests.mjs'",
|
|
41
51
|
"test:endpoint": "mocha 'test/endpoint/**/*-tests.mjs'",
|
|
52
|
+
"test:endpoint:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/endpoint",
|
|
53
|
+
"test:tools:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/tools",
|
|
42
54
|
"test:logging": "mocha 'test/logging/**/*-tests.mjs'",
|
|
43
55
|
"test:request": "mocha 'test/request/**/*-tests.mjs'",
|
|
44
56
|
"test:response": "mocha 'test/response/**/*-tests.mjs'",
|
|
45
|
-
"test:utils": "mocha 'test/utils/**/*-tests.mjs'"
|
|
57
|
+
"test:utils": "mocha 'test/utils/**/*-tests.mjs'",
|
|
58
|
+
"lint": "eslint .",
|
|
59
|
+
"lint:fix": "eslint . --fix",
|
|
60
|
+
"lint:ci": "eslint . --max-warnings 0"
|
|
46
61
|
},
|
|
47
62
|
"keywords": [
|
|
48
63
|
"api",
|