Skip to content

ROADMAP.md

Latest commit

 

History

History
270 lines (201 loc) · 7.73 KB

ROADMAP.md

File metadata and controls

270 lines (201 loc) · 7.73 KB

Mochila Modernization Roadmap

Status: The codebase is in excellent condition with modern best practices. This roadmap identifies minor modernization opportunities.

Executive Summary

Overall Grade: A+ (Model Modern TypeScript Project)

The mochila-ts codebase follows 2025 best practices with:

  • Code Quality: Exceptional (no legacy patterns found)
  • Dependencies: Up-to-date and modern
  • Build Tools: Modern and efficient
  • Type Safety: Industry-leading (95%+ coverage)
  • Testing: Comprehensive (95%+ code coverage)

Current State Assessment

✅ Modern Practices Already Implemented

  • Zero var declarations - 100% using const/let
  • Modern arrow functions throughout
  • No any types (except 1 intentional ESLint-disabled case)
  • No TODO/FIXME comments - zero technical debt markers
  • TypeScript 5.6.3 with strict mode enabled
  • 95%+ type coverage enforced
  • Modern async/await patterns (no callback hell)
  • Functional programming with proper currying
  • No deprecated TypeScript features
  • ESLint 9 with flat config format
  • Modern build tooling: tsup, pnpm, semantic-release
  • GitHub Actions with latest versions

⚠️ Modernization Opportunities

The following items represent potential improvements, not critical issues:

1. CommonJS Configuration Files

Current State:

  • jest.config.js - uses module.exports
  • release.config.cjs - uses module.exports
  • .size-limit.js - uses module.exports
  • commitlint.config.cjs - uses .cjs extension

Impact: Low (tooling-dependent)

Action: Convert to ESM where tooling supports it

2. Jest vs Modern Test Runners

Current State: Jest 29.7.0 with ts-jest

Modern Alternative: Vitest

Benefits of Migration:

  • 2-10x faster execution
  • Native ESM support (no transpilation needed)
  • Better TypeScript integration
  • Compatible API migration path
  • Built-in coverage without additional packages

Impact: Medium (significant performance improvement)

3. ECMAScript Target

Current State:

  • target: "es2020" (tsconfig.json:16)
  • target: "es2020" (tsup.config.ts:10)

Node.js Requirement: 20.0.0+ (supports ES2022+)

Available Features in ES2022/ES2023:

  • Top-level await
  • Class fields and private methods
  • at() method for arrays
  • Object.hasOwn()
  • Error cause
  • Array .findLast() and .findLastIndex()

Impact: Low-Medium (enables newer language features)

Modernization Roadmap

Phase 1: Quick Wins (1-2 hours)

1.1 Update ECMAScript Target

Priority: High Effort: Low Impact: Medium

Tasks:

  • Update tsconfig.json target to "es2022"
  • Update tsconfig.json lib to ["es2022"]
  • Update tsup.config.ts target to "es2022"
  • Run full test suite to verify compatibility
  • Update documentation if needed

Files to modify:

  • tsconfig.json
  • tsup.config.ts

1.2 Convert Configuration Files to ESM

Priority: Medium Effort: Low Impact: Low

Tasks:

  • Research Jest 29 ESM support status
  • Convert .size-limit.js to .size-limit.mjs if supported
  • Update package.json scripts if needed
  • Test all npm scripts after conversion

Files to modify:

  • .size-limit.js → .size-limit.mjs
  • Potentially jest.config.js (check Jest ESM support)

Phase 2: Performance & Developer Experience (1-2 days)

2.1 Evaluate Vitest Migration

Priority: Medium Effort: Medium Impact: High

Research Tasks:

  • Create proof-of-concept branch
  • Install Vitest and related dependencies
  • Migrate 5-10 test files as pilot
  • Benchmark performance improvements
  • Evaluate coverage reporting
  • Check for API compatibility issues

Migration Tasks (if approved after POC):

  • Install Vitest (pnpm add -D vitest @vitest/ui)
  • Create vitest.config.ts
  • Update test scripts in package.json
  • Migrate all test files (should be minimal changes)
  • Update CI workflows (.github/workflows/test.yml)
  • Update coverage configuration
  • Remove Jest dependencies

Benefits:

  • Faster test execution (2-10x improvement)
  • Better TypeScript integration
  • Native ESM support
  • Modern UI for test debugging

Risks:

  • Time investment for migration
  • Potential compatibility issues with existing tests
  • Team learning curve (minimal, API is similar)

Phase 3: Future Considerations (6-12 months)

3.1 Monitor TypeScript Updates

Priority: Low Effort: Ongoing Impact: Low-Medium

Tasks:

  • Monitor TypeScript 5.7+ releases
  • Evaluate new features for adoption
  • Update when stable releases are available

3.2 Node.js Native Test Runner

Priority: Low Effort: TBD Impact: Low

Tasks:

  • Monitor Node.js test runner maturity
  • Evaluate when it reaches feature parity
  • Consider migration if it becomes standard

Dependency Health

All dependencies are current and well-maintained:

Tool Current Version Status Notes
TypeScript 5.6.3 ✅ Latest Stable
ESLint 9.39.1 ✅ Modern Flat config
Jest 29.7.0 ✅ Current Consider Vitest
tsup 8.3.0 ✅ Modern Fast bundler
Prettier 3.6.2 ✅ Latest Stable
Node.js 22.21.0 ✅ LTS Production-ready
pnpm 10.19.0 ✅ Latest Fast, efficient

Build Tooling Stack

Current Stack (All Modern):

  • ✅ tsup - Modern, fast TypeScript bundler
  • ✅ pnpm - Efficient package manager
  • ✅ semantic-release - Automated releases
  • ✅ husky v9 - Modern git hooks
  • ✅ lint-staged - Pre-commit linting
  • ✅ GitHub Actions - Using latest action versions (v4)

Code Quality Metrics

Metric Current Target Status
Type Coverage 95%+ 95%+ ✅ Met
Test Coverage 95%+ 95%+ ✅ Met
ESLint Violations 0 0 ✅ Met
Legacy Patterns 0 0 ✅ Met
var Usage 0 0 ✅ Met
any Types 1 < 5 ✅ Met
Technical Debt None Low ✅ Excellent

Implementation Guidelines

Before Starting Any Phase

  1. Create a feature branch
  2. Run full test suite to establish baseline
  3. Document any breaking changes
  4. Update CHANGELOG.md

After Completing Each Task

  1. Run full test suite
  2. Run type checking (pnpm type-check)
  3. Run linting (pnpm lint)
  4. Run build (pnpm build)
  5. Verify bundle size (pnpm size)
  6. Update documentation
  7. Create PR with detailed description

Success Criteria

Each modernization task should:

  • ✅ Pass all existing tests
  • ✅ Maintain or improve type coverage
  • ✅ Not increase bundle size significantly
  • ✅ Maintain backward compatibility (where applicable)
  • ✅ Include updated documentation

Contributing to This Roadmap

This roadmap is a living document. To propose changes:

  1. Open an issue for discussion
  2. Provide research and rationale
  3. Consider impact on:
    • Developer experience
    • Build performance
    • Type safety
    • Bundle size
    • Breaking changes

Version History

  • 2025-11-05: Initial roadmap created based on codebase analysis
    • Identified 3 main modernization opportunities
    • All items are optional improvements, not critical issues
    • Project is already following modern best practices

Conclusion

This project is already a model modern TypeScript codebase. The roadmap items are optimizations rather than critical updates. The development team should be proud of the code quality and can approach these modernizations at their own pace without urgency.

Recommended Next Steps:

  1. Start with Phase 1.1 (Update ES target) - quick win with no risks
  2. Evaluate Phase 2.1 (Vitest) through a POC before committing
  3. Keep Phase 3 items on the radar but no immediate action needed