fix: add ESM support and update documentation#25
Merged
Conversation
Changes:
- Added dual package support (CommonJS + ES Modules)
- Created tsconfig.esm.json for ES module compilation
- Updated package.json with proper 'module' and 'exports' fields
- Build now outputs both CJS (build/cjs/) and ESM (build/esm/)
- Added package.json marker in build/esm/ to indicate ES module type
- Updated all export paths to support both import and require
- Maintained backward compatibility with existing CommonJS consumers
Benefits:
- Better tree-shaking for modern bundlers (webpack, rollup, vite)
- Smaller bundle sizes for applications using ES modules
- Proper bundle size analysis on bundlephobia.com
- Package marked as side-effect free for optimal optimization
- Dual package hazard avoided with proper exports configuration
Technical details:
- CJS: module=commonjs, output=build/cjs/
- ESM: module=ES2020, output=build/esm/, with {"type":"module"}
- All tests passing (518 tests, 95.08% coverage)
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
🚀 Performance Benchmark Results📦 class-transformer Compatibility📊 Performance Comparison Summary📋 Full class-transformer Benchmark Output✅ class-validator Compatibility📋 Full class-validator Benchmark Output🎯 Core Performance⚡ Simple Mapping Benchmark🔧 Complex Transformations Benchmark💡 Note: These are absolute performance numbers from this PR. Benchmarked with Benchmark.js on Node.js 20 • View History |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting
…per ESM import specifiers This fixes the critical Node.js ESM compatibility issue where relative imports were missing .js file extensions, which would cause ERR_MODULE_NOT_FOUND errors in Node 18+ ESM contexts. Changes: - Updated tsconfig.esm.json to use module: ESNext with moduleResolution: bundler - Created scripts/fix-esm-imports.js post-build script to add .js extensions - Updated build:esm script to run the fix-esm-imports script after compilation - ESM output now has proper import specifiers (e.g., './core/Mapper.js') Technical details: - TypeScript's bundler resolution outputs clean ESM without extensions - Post-build script adds .js extensions to all relative imports/exports - This approach maintains source code compatibility with both CJS and ESM builds - All 518 tests passing, 95.08% coverage maintained Resolves the P1 issue identified in code review comment #2435728625
Isqanderm
commented
Oct 16, 2025
Enhanced the fix-esm-imports.js script to properly handle directory imports by checking if an import path points to a directory with an index.js file. Changes: - Updated fix-esm-imports.js to resolve directory imports to /index.js - Now correctly transforms './decorators' to './decorators/index.js' - Added test-esm-imports.mjs to verify all imports have proper extensions - Added test-esm-runtime.mjs to verify actual Node.js ESM runtime compatibility This fixes the issue where './decorators' was incorrectly transformed to './decorators.js' instead of './decorators/index.js', which caused ERR_MODULE_NOT_FOUND errors when importing the package in Node.js ESM context. Verification: - ✅ All 518 tests passing - ✅ 95.08% coverage maintained - ✅ ESM syntax validation passes (29 files scanned) - ✅ ESM runtime import test passes - ✅ All imports now resolve correctly in Node.js 18+ Addresses feedback from PR review comment #2435728625
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
…, function or class Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Add robust ESM integration testing suite to prevent ESM-related issues: Test Suite: - esm-integration.test.mjs: Comprehensive validation (8 tests) * Static import/export validation * Package structure verification * Runtime import resolution * Functionality testing * Export completeness checks - esm-runtime-simple.test.mjs: Quick smoke tests * Fast validation of core ESM functionality * Catches common import/export issues - esm-post-install-simulation.test.mjs: Real-world usage simulation * Tests 10 common usage scenarios * Validates post-npm-install experience * Tests legacy API compatibility CI/CD Integration: - Updated .github/workflows/ci.yml: * Added esm-validation job with Node.js 18, 20, 22 matrix * Runs after unit tests pass * Validates build artifacts and package structure * Includes smoke test for direct ESM imports * Posts PR comment with validation results - Updated .github/workflows/release.yml: * Added ESM integration tests before release * Verifies package integrity (CJS + ESM) * Prevents broken ESM builds from being published Package Scripts: - npm run test:esm - Run all ESM tests - npm run test:esm:integration - Comprehensive validation - npm run test:esm:simple - Quick smoke test - npm run test:esm:simulation - Post-install simulation - npm run test:all - Run unit + ESM tests Documentation: - Added test/ESM_TESTING.md with comprehensive guide: * Why ESM testing is critical * Test file descriptions * Running tests locally * CI/CD integration details * Common issues and debugging * Build process explanation Benefits: ✅ Catches missing .js extensions before merge ✅ Validates directory imports resolve correctly ✅ Ensures package.json type marker exists ✅ Tests on multiple Node.js versions (18, 20, 22) ✅ Prevents ERR_MODULE_NOT_FOUND errors in production ✅ Validates real-world usage scenarios ✅ Provides clear PR feedback on ESM compatibility This prevents the P1 ESM issues we just fixed from happening again.
✅ ESM Build ValidationStatus: All ESM validation checks passed! Test Matrix Results
Validation Steps
What This ValidatesThe ESM validation suite ensures:
✅ The package is ready for ESM consumption! This validation prevents issues like missing |
- Remove unused 'stat' import from test/esm-integration.test.mjs - Remove unused 'test' function from test/esm-post-install-simulation.test.mjs - Remove temporary test files (test-esm-imports.mjs, test-esm-runtime.mjs) Addresses GitHub Advanced Security code scanning alerts: - https://github.com/Isqanderm/data-mapper/security/code-scanning/40 - https://github.com/Isqanderm/data-mapper/security/code-scanning/41 All ESM tests still passing (22/22 tests)
- Remove benchmark-simple.txt (temporary benchmark results file) - Add benchmark-*.txt pattern to .gitignore to prevent future commits of benchmark result files
github-actions Bot
pushed a commit
that referenced
this pull request
Oct 16, 2025
## [4.1.3](v4.1.2...v4.1.3) (2025-10-16) ### Bug Fixes * add ESM support and update documentation ([#25](#25)) ([dba2fb7](dba2fb7))
|
🎉 This PR is included in version 4.1.3 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds ES Modules support for better tree-shaking and bundle analysis, removes an unused script, and updates the security policy.
Changes
1. ✨ Add ES Modules Support (feat)
Problem: The package was showing a warning on bundlephobia.com:
Solution:
tsconfig.esm.jsonfor ES module compilationpackage.jsonwith propermoduleandexportsfieldsbuild/cjs/) and ESM (build/esm/)package.jsonmarker inbuild/esm/to indicate ES module typeimportandrequireBenefits:
Technical details:
module=commonjs, output=build/cjs/module=ES2020, output=build/esm/, with{"type":"module"}2. 🧹 Remove Unused Script (chore)
translate-docs.jsfrom repository root3. 📝 Update Security Policy (docs)
SECURITY.mdto clearly state:Testing
"use strict", properexportstatements)Breaking Changes
None. This is a backward-compatible change:
importsyntaxChecklist
Ready for review! 🚀
Please verify that CI checks pass before merging.
Pull Request opened by Augment Code with guidance from the PR author