dbis_core-lite/docs/deployment/package-update-guide.md

Package Update Recommendations

✅ Current Status

• 0 security vulnerabilities found
• All packages are at their "wanted" versions (within semver range)
• System is stable and secure

📋 Update Recommendations

⚠️ DO NOT UPDATE (Critical Dependencies)

1. prom-client (13.2.0 → 15.1.3)
   • Reason: Required for express-prometheus-middleware@1.2.0 compatibility
   • Status: Keep at 13.2.0 (peer dependency conflict would occur)

🔄 Major Version Updates (Require Testing & Code Review)

These major version updates have breaking changes and should be carefully evaluated:

2. express (4.22.1 → 5.2.1) - Major

   • Breaking changes in Express 5.x
   • Requires thorough testing of all routes and middleware
   • Recommendation: Defer until Express 5.x ecosystem is mature

3. helmet (7.2.0 → 8.1.0) - Major

   • Security middleware - needs careful testing
   • Recommendation: Update with testing (security-related)

4. jest (29.7.0 → 30.2.0) - Major

   • Testing framework - breaking changes possible
   • Recommendation: Update in test branch first

5. uuid (9.0.1 → 13.0.0) - Major

   • Multiple major versions jumped
   • Recommendation: Update carefully (API changes likely)

6. zod (3.25.76 → 4.2.1) - Major

   • Schema validation - used extensively
   • Recommendation: Update with testing (breaking changes in v4)

7. redis (4.7.1 → 5.10.0) - Major

   • Database client - critical dependency
   • Recommendation: Update with extensive testing

8. joi (17.13.3 → 18.0.2) - Major

   • Validation library - used in gateway
   • Recommendation: Update with testing (API may have changed)

9. dotenv (16.6.1 → 17.2.3) - Major

   • Environment variables - simple library
   • Recommendation: Safe to update (likely minimal breaking changes)

10. bcryptjs (2.4.3 → 3.0.3) - Major

    • Password hashing - security critical
    • Recommendation: Update with testing (verify hash compatibility)

🔧 Dev Dependencies (Safer to Update)

11. @types/node (20.19.27 → 25.0.3) - Major

    • Type definitions only
    • Recommendation: Update gradually (may need code changes)

12. @types/express (4.17.25 → 5.0.6) - Major

    • Type definitions for Express 5
    • Recommendation: Only update if Express is updated

13. @types/jest (29.5.14 → 30.0.0) - Major

    • Type definitions only
    • Recommendation: Update if Jest is updated

14. @types/uuid (9.0.8 → 10.0.0) - Major

    • Type definitions only
    • Recommendation: Update if uuid is updated

15. @typescript-eslint/* (6.21.0 → 8.50.1) - Major

    • ESLint plugins - dev tooling
    • Recommendation: Update with config review

16. eslint (8.57.1 → 9.39.2) - Major

    • Linting tool - dev dependency
    • Recommendation: Update with config migration (ESLint 9 has flat config)

17. supertest (6.3.4 → 7.1.4) - Major

    • Testing library
    • Recommendation: Update with test review

18. winston-daily-rotate-file (4.7.1 → 5.0.0) - Major

    • Logging utility
    • Recommendation: Update with testing

🎯 Recommended Update Strategy

Phase 1: Low-Risk Updates (Can do now)

• dotenv → 17.2.3 (simple env var loader)

Phase 2: Medium-Risk Updates (Test first)

• helmet → 8.1.0 (security middleware)
• winston-daily-rotate-file → 5.0.0 (logging)
• bcryptjs → 3.0.3 (with hash compatibility testing)

Phase 3: Higher-Risk Updates (Require extensive testing)

• zod → 4.2.1 (validation schema changes)
• joi → 18.0.2 (validation changes)
• redis → 5.10.0 (client API changes)
• uuid → 13.0.0 (API changes)

Phase 4: Framework Updates (Major refactoring)

• express → 5.2.1 (requires route/middleware review)
• jest → 30.2.0 (test framework changes)
• ESLint ecosystem → v9 (config migration needed)

📝 Update Process

1. Create feature branch for each update category
2. Update package.json with new version
3. Run npm install
4. Fix compilation errors (TypeScript/imports)
5. Run test suite (npm test)
6. Manual testing of affected functionality
7. Code review
8. Merge to main

⚡ Quick Update Script

To update specific packages safely:

# Update single package
npm install package@latest

# Update and test
npm install package@latest && npm test

# Check for breaking changes
npm outdated package

🔒 Security Priority

If security vulnerabilities are found:

1. Critical/High: Update immediately (even if major version)
2. Medium: Update in next maintenance window
3. Low: Update in regular cycle

---

Last Updated: 2025-12-28 Current Status: ✅ All packages secure, no vulnerabilities