|
| 1 | +# v4.0.0-alpha.0 (2025-10-27) |
| 2 | + |
| 3 | +Infrastructure modernization release. All changes are breaking and relate to runtime environment and module system. |
| 4 | + |
| 5 | +## Summary |
| 6 | + |
| 7 | +- Node.js 20+ required (dropped 16.x and 18.x) |
| 8 | +- All packages migrated to dual CJS/ESM builds |
| 9 | +- Manual type augmentation configuration required |
| 10 | +- InversifyJS v7 upgrade |
| 11 | +- Migrated from Yarn to pnpm |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Breaking Changes |
| 16 | + |
| 17 | +### Node.js Version |
| 18 | + |
| 19 | +Minimum version increased to Node.js 20.x. (#803) |
| 20 | + |
| 21 | +**Before**: Node.js 16.x, 18.x supported |
| 22 | +**After**: Node.js 20.x, 22.x, 24.x required |
| 23 | + |
| 24 | +```bash |
| 25 | +# Migration |
| 26 | +node --version # Must be >= 20.0.0 |
| 27 | +nvm install 20 |
| 28 | +nvm use 20 |
| 29 | +``` |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +### Module System |
| 34 | + |
| 35 | +All packages now output dual CJS/ESM builds to `dist/cjs/` and `dist/esm/`. |
| 36 | + |
| 37 | +**Before**: |
| 38 | +``` |
| 39 | +node_modules/@suites/unit/ |
| 40 | + dist/ |
| 41 | + index.js |
| 42 | + services/ |
| 43 | +``` |
| 44 | + |
| 45 | +**After**: |
| 46 | +``` |
| 47 | +node_modules/@suites/unit/ |
| 48 | + dist/ |
| 49 | + cjs/ |
| 50 | + index.js |
| 51 | + services/ |
| 52 | + esm/ |
| 53 | + index.js |
| 54 | + services/ |
| 55 | +``` |
| 56 | + |
| 57 | +**Impact**: Direct file imports must update paths (normal imports unchanged). |
| 58 | + |
| 59 | +```typescript |
| 60 | +// Normal imports work unchanged |
| 61 | +import { TestBed } from '@suites/unit'; // ✓ Still works |
| 62 | + |
| 63 | +// Direct imports need update |
| 64 | +import { something } from '@suites/unit/dist/services/builder'; // Old |
| 65 | +import { something } from '@suites/unit/dist/cjs/services/builder'; // New |
| 66 | +``` |
| 67 | + |
| 68 | +**Affected packages**: All 10 packages |
| 69 | +**Commits**: Multiple commits, one per package |
| 70 | + |
| 71 | +--- |
| 72 | + |
| 73 | +### Type Augmentation |
| 74 | + |
| 75 | +Postinstall scripts removed. Manual configuration required. |
| 76 | + |
| 77 | +**Before**: Types automatically injected via postinstall scripts |
| 78 | +**After**: Create `global.d.ts` manually |
| 79 | + |
| 80 | +**Migration**: |
| 81 | + |
| 82 | +1. Create `global.d.ts` in project root: |
| 83 | +```typescript |
| 84 | +/// <reference types="@suites/doubles.jest/unit" /> |
| 85 | +/// <reference types="@suites/di.nestjs/types" /> |
| 86 | +``` |
| 87 | + |
| 88 | +2. Add to `tsconfig.json`: |
| 89 | +```json |
| 90 | +{ |
| 91 | + "include": ["src", "global.d.ts"] |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +**Affected packages**: |
| 96 | +- `@suites/doubles.jest` |
| 97 | +- `@suites/doubles.vitest` |
| 98 | +- `@suites/doubles.sinon` |
| 99 | +- `@suites/di.inversify` |
| 100 | +- `@suites/di.nestjs` |
| 101 | + |
| 102 | +**Why**: Postinstall scripts caused CI/CD issues and violated npm best practices. |
| 103 | + |
| 104 | +--- |
| 105 | + |
| 106 | +### InversifyJS v7 |
| 107 | + |
| 108 | +`@suites/di.inversify` now requires InversifyJS v7.x. (#884) |
| 109 | + |
| 110 | +```bash |
| 111 | +npm install inversify@^7.0.0 reflect-metadata@^0.2.2 |
| 112 | +``` |
| 113 | + |
| 114 | +**What changed**: Uses InversifyJS v7 metadata API |
| 115 | + |
| 116 | +--- |
| 117 | + |
| 118 | +## Improvements |
| 119 | + |
| 120 | +### Package Manager |
| 121 | +- Migrated from Yarn to pnpm 10.14.0 (#799) |
| 122 | +- Faster installs, better workspace support |
| 123 | + |
| 124 | +### Dependencies |
| 125 | +- Removed lodash.isequal, using Node.js `util.isDeepStrictEqual()` |
| 126 | +- Lighter dependency footprint |
| 127 | + |
| 128 | +### License |
| 129 | +- Changed from MIT to Apache-2.0 |
| 130 | + |
| 131 | +--- |
| 132 | + |
| 133 | +## Bug Fixes |
| 134 | + |
| 135 | +- Fixed missing `@suites/types.doubles` dependency in core (#806) |
| 136 | +- Upgraded ts-mocha for Node 22/24 compatibility |
| 137 | + |
| 138 | +--- |
| 139 | + |
| 140 | +## Documentation |
| 141 | + |
| 142 | +Added comprehensive JSDoc to: |
| 143 | +- `@suites/unit` - TestBed API |
| 144 | +- `@suites/core.unit` - Core implementation |
| 145 | +- `@suites/doubles.jest` - Jest adapter |
| 146 | +- `@suites/doubles.vitest` - Vitest adapter |
| 147 | +- `@suites/doubles.sinon` - Sinon adapter |
| 148 | +- All type packages |
| 149 | + |
| 150 | +--- |
| 151 | + |
| 152 | +## Migration Checklist |
| 153 | + |
| 154 | +- [ ] Upgrade Node.js to 20+ |
| 155 | +- [ ] Install alpha: `npm install @suites/[email protected]` |
| 156 | +- [ ] Create `global.d.ts` with type references |
| 157 | +- [ ] Add `global.d.ts` to `tsconfig.json` include array |
| 158 | +- [ ] If using Inversify: `npm install inversify@^7.0.0` |
| 159 | +- [ ] Run tests |
| 160 | +- [ ] Update CI/CD Node.js version |
| 161 | + |
| 162 | +--- |
| 163 | + |
| 164 | +## Installation |
| 165 | + |
| 166 | +```bash |
| 167 | +npm install @suites/ [email protected] |
| 168 | +``` |
| 169 | + |
| 170 | +--- |
| 171 | + |
| 172 | +**Full Changelog**: https://github.com/suites-dev/suites/compare/v3.0.2...v4.0.0-alpha.0 |
0 commit comments