@knighted/duel 2.0.0-rc.0 → 2.0.0-rc.2

package/README.md

@@ -10,8 +10,10 @@ Tool for building a Node.js [dual package](https://nodejs.org/api/packages.html#
 
 - Bidirectional ESM ↔️ CJS dual builds inferred from the package.json `type`.
 - Correctly preserves module systems for `.mts` and `.cts` file extensions.
-- Resolves the [differences between ES modules and CommonJS](https://nodejs.org/api/esm.html#differences-between-es-modules-and-commonjs).
-- Use only one package.json and tsconfig.json.
+- No extra configuration files needed, uses `package.json` and `tsconfig.json` files.
+- Transforms the [differences between ES modules and CommonJS](https://nodejs.org/api/esm.html#differences-between-es-modules-and-commonjs).
+- Works with monorepos.
+
 
 ## Requirements
 
@@ -68,12 +70,27 @@ If you prefer to have both builds in directories inside of your defined `outDir`
 
 Assuming an `outDir` of `dist`, running the above will create `dist/esm` and `dist/cjs` directories.
 
+### Module transforms
+
+TypeScript will throw compiler errors when using `import.meta` globals while targeting a CommonJS dual build, but _will not_ throw compiler errors when the inverse is true, i.e. using CommonJS globals (`__filename`, `__dirname`, etc.) while targeting an ES module dual build. There is an [open issue](https://github.com/microsoft/TypeScript/issues/58658) regarding this unexpected behavior. You can use the `--modules` option to have the [differences between ES modules and CommonJS](https://nodejs.org/api/esm.html#differences-between-es-modules-and-commonjs) transformed by `duel` prior to running compilation with `tsc` so that there are no compilation or runtime errors.
+
+Note, there is a slight performance penalty since your project needs to be copied first to run the transforms before compiling with `tsc`.
+
+```json
+"scripts": {
+  "build": "duel --modules"
+}
+```
+
+This feature is still a work in progress regarding transforming `exports` when targeting an ES module build (relies on [`@knighted/module`](https://github.com/knightedcodemonkey/module)).
+
 ## Options
 
 The available options are limited, because you should define most of them inside your project's `tsconfig.json` file.
 
 - `--project, -p` The path to the project's configuration file. Defaults to `tsconfig.json`.
 - `--pkg-dir, -k` The directory to start looking for a package.json file. Defaults to the cwd.
+- `--modules, -m` Transform module globals for dual build target. Defaults to false.
 - `--dirs, -d` Outputs both builds to directories inside of `outDir`. Defaults to `false`.
 
 You can run `duel --help` to get the same info. Below is the output of that:
@@ -84,6 +101,7 @@ Usage: duel [options]
 Options:
 --project, -p [path] 	 Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.
 --pkg-dir, -k [path] 	 The directory to start looking for a package.json file. Defaults to cwd.
+--modules, -m 		 Transform module globals for dual build target. Defaults to false.
 --dirs, -d 		 Output both builds to directories inside of outDir. [esm, cjs].
 --help, -h 		 Print this message.
 ```
@@ -94,7 +112,7 @@ These are definitely edge cases, and would only really come up if your project m
 
 - This is going to work best if your CJS-first project uses file extensions in _relative_ specifiers. This is completely acceptable in CJS projects, and [required in ESM projects](https://nodejs.org/api/esm.html#import-specifiers). This package makes no attempt to rewrite bare specifiers, or remap any relative specifiers to a directory index.
 
-- Unfortunately, TypeScript doesn't really build [dual packages](https://nodejs.org/api/packages.html#dual-commonjses-module-packages) very well in regards to preserving module system by file extension. For instance, there doesn't appear to be a way to convert an arbitrary `.ts` file into another module system, _while also preserving the module system of `.mts` and `.cts` files_, without requiring **multiple** package.json files. In my opinion, the `tsc` compiler is fundamentally broken in this regard, and at best is enforcing usage patterns it shouldn't. This is only mentioned for transparency, `duel` will correct for this and produce files with the module system you would expect based on the file's extension, so that it works with [how Node.js determines module systems](https://nodejs.org/api/packages.html#determining-module-system).
+- Unfortunately, TypeScript doesn't really build [dual packages](https://nodejs.org/api/packages.html#dual-commonjses-module-packages) very well. One instance of unexpected behavior is when the compiler throws errors for ES module globals when running a dual CJS build, but not for the inverse case, despite both causing runtime errors in Node.js. See the [open issue](https://github.com/microsoft/TypeScript/issues/58658). You can circumvent this with `duel` by using the `--modules` option if your project uses module globals such as `import.meta` properties or `__dirname`, `__filename`, etc. in a CommonJS project.
 
 - If doing an `import type` across module systems, i.e. from `.mts` into `.cts`, or vice versa, you might encounter the compilation error ``error TS1452: 'resolution-mode' assertions are only supported when `moduleResolution` is `node16` or `nodenext`.``. This is a [known issue](https://github.com/microsoft/TypeScript/issues/49055) and TypeScript currently suggests installing the nightly build, i.e. `npm i typescript@next`.
 
@@ -102,4 +120,6 @@ These are definitely edge cases, and would only really come up if your project m
 
 ## Notes
 
-As far as I can tell, `duel` is one (if not the only) way to get a correct dual package build using `tsc` with only **one package.json and tsconfig.json file**, _while also preserving module system by file extension_. Basically, how you expect things to work. The Microsoft backed TypeScript team [keep](https://github.com/microsoft/TypeScript/pull/54546) [talking](https://github.com/microsoft/TypeScript/issues/54593) about dual build support, but they continue to [refuse to rewrite specifiers](https://github.com/microsoft/TypeScript/issues/16577).
+As far as I can tell, `duel` is one (if not the only) way to get a correct dual package build using `tsc` without requiring multiple `tsconfig.json` files or extra configuration. The Microsoft backed TypeScript team [keep](https://github.com/microsoft/TypeScript/pull/54546) [talking](https://github.com/microsoft/TypeScript/issues/54593) about dual build support, but they continue to [refuse to rewrite specifiers](https://github.com/microsoft/TypeScript/issues/16577).
+
+Fortunately, Node.js has added `--experimental-require-module` so that you can [`require()` ES modules](https://nodejs.org/api/esm.html#require) if they don't use top level await, which sets the stage for possibly no longer requiring dual builds.

package/dist/cjs/duel.cjs

@@ -28,7 +28,7 @@ const handleErrorAndExit = message => {
 const duel = async (args) => {
     const ctx = await (0, init_js_1.init)(args);
     if (ctx) {
-        const { projectDir, tsconfig, configPath, dirs, pkg } = ctx;
+        const { projectDir, tsconfig, configPath, modules, dirs, pkg } = ctx;
         const tsc = await (0, find_up_1.findUp)(async (dir) => {
             const tscBin = (0, node_path_1.join)(dir, 'node_modules', '.bin', 'tsc');
             if (await (0, find_up_1.pathExists)(tscBin)) {
@@ -38,7 +38,7 @@ const duel = async (args) => {
         const runBuild = (project, outDir) => {
             return new Promise((resolve, reject) => {
                 const args = outDir ? ['-p', project, '--outDir', outDir] : ['-p', project];
-                const build = (0, node_child_process_1.spawn)(tsc, args, { stdio: 'inherit' });
+                const build = (0, node_child_process_1.spawn)(tsc, args, { stdio: 'inherit', shell: node_process_1.platform === 'win32' });
                 build.on('error', err => {
                     reject(new Error(`Failed to compile: ${err.message}`));
                 });
@@ -109,16 +109,36 @@ const duel = async (args) => {
             handleErrorAndExit(message);
         }
         if (success) {
-            const compileFiles = (0, util_js_1.getCompileFiles)(tsc, projectDir);
             const subDir = (0, node_path_1.join)(projectDir, `_${hex}_`);
-            const dualConfigPath = (0, node_path_1.join)(subDir, `tsconfig.${hex}.json`);
             const absoluteDualOutDir = (0, node_path_1.join)(projectDir, isCjsBuild ? (0, node_path_1.join)(outDir, 'cjs') : (0, node_path_1.join)(outDir, 'esm'));
             const tsconfigDual = getOverrideTsConfig();
             const pkgRename = 'package.json.bak';
+            let dualConfigPath = (0, node_path_1.join)(projectDir, `tsconfig.${hex}.json`);
             let errorMsg = '';
-            // Copy project directory as a subdirectory
-            await (0, promises_1.mkdir)(subDir);
-            await Promise.all(compileFiles.map(file => (0, promises_1.cp)(file, (0, node_path_1.resolve)(subDir, (0, node_path_1.relative)(projectDir, file)))));
+            if (modules) {
+                const compileFiles = (0, util_js_1.getCompileFiles)(tsc, projectDir);
+                dualConfigPath = (0, node_path_1.join)(subDir, `tsconfig.${hex}.json`);
+                await (0, promises_1.mkdir)(subDir);
+                await Promise.all(compileFiles.map(file => (0, promises_1.cp)(file, (0, node_path_1.join)(subDir, (0, node_path_1.relative)(projectDir, file).replace(/^(\.\.\/)*/, '')))));
+                /**
+                 * Transform ambiguous modules for the target dual build.
+                 * @see https://github.com/microsoft/TypeScript/issues/58658
+                 */
+                const toTransform = await (0, glob_1.glob)(`${subDir}/**/*{.js,.jsx,.ts,.tsx}`, {
+                    ignore: 'node_modules/**',
+                });
+                for (const file of toTransform) {
+                    /**
+                     * Maybe include the option to transform modules implicitly
+                     * (modules: true) so that `exports` are correctly converted
+                     * when targeting a CJS dual build. Depends on @knighted/module
+                     * supporting he `modules` option.
+                     *
+                     * @see https://github.com/microsoft/TypeScript/issues/58658
+                     */
+                    await (0, module_1.transform)(file, { out: file, type: isCjsBuild ? 'commonjs' : 'module' });
+                }
+            }
             /**
              * Create a new package.json with updated `type` field.
              * Create a new tsconfig.json.
@@ -128,16 +148,6 @@ const duel = async (args) => {
                 type: isCjsBuild ? 'commonjs' : 'module',
             }));
             await (0, promises_1.writeFile)(dualConfigPath, JSON.stringify(tsconfigDual));
-            /**
-             * Transform ambiguous modules for the target dual build.
-             * @see https://github.com/microsoft/TypeScript/issues/58658
-             */
-            const toTransform = await (0, glob_1.glob)(`${subDir}/**/*{.js,.jsx,.ts,.tsx}`, {
-                ignore: 'node_modules/**',
-            });
-            for (const file of toTransform) {
-                await (0, module_1.transform)(file, { out: file, type: isCjsBuild ? 'commonjs' : 'module' });
-            }
             // Build dual
             (0, util_js_1.log)('Starting dual build...');
             try {
@@ -169,6 +179,6 @@ const duel = async (args) => {
 };
 exports.duel = duel;
 const realFileUrlArgv1 = await (0, util_js_1.getRealPathAsFileUrl)(node_process_1.argv[1]);
-if (require("node:url").pathToFileURL(__filename).toString() === realFileUrlArgv1) {
+if (import.meta.url === realFileUrlArgv1) {
     await duel();
 }

package/dist/cjs/init.cjs

@@ -32,6 +32,11 @@ const init = async (args) => {
                     short: 'k',
                     default: (0, node_process_1.cwd)(),
                 },
+                modules: {
+                    type: 'boolean',
+                    short: 'm',
+                    default: false,
+                },
                 dirs: {
                     type: 'boolean',
                     short: 'd',
@@ -55,11 +60,12 @@ const init = async (args) => {
         (0, util_js_1.log)('Options:');
         (0, util_js_1.log)("--project, -p [path] \t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.");
         (0, util_js_1.log)('--pkg-dir, -k [path] \t The directory to start looking for a package.json file. Defaults to cwd.');
+        (0, util_js_1.log)('--modules, -m \t\t Transform module globals for dual build target. Defaults to false.');
         (0, util_js_1.log)('--dirs, -d \t\t Output both builds to directories inside of outDir. [esm, cjs].');
         (0, util_js_1.log)('--help, -h \t\t Print this message.');
     }
     else {
-        const { project, 'target-extension': targetExt, 'pkg-dir': pkgDir, dirs } = parsed;
+        const { project, 'target-extension': targetExt, 'pkg-dir': pkgDir, modules, dirs, } = parsed;
         let configPath = (0, node_path_1.resolve)(project);
         let stats = null;
         let pkg = null;
@@ -108,6 +114,7 @@ const init = async (args) => {
             return {
                 pkg,
                 dirs,
+                modules,
                 tsconfig,
                 projectDir,
                 configPath,

package/dist/cjs/init.d.cts

@@ -1,6 +1,7 @@
 export function init(args: any): Promise<false | {
     pkg: import("read-package-up", { with: { "resolution-mode": "import" } }).NormalizedReadResult;
-    dirs: boolean | undefined;
+    dirs: boolean;
+    modules: boolean;
     tsconfig: any;
     projectDir: string;
     configPath: string;

package/dist/cjs/util.cjs

@@ -5,6 +5,7 @@ const node_url_1 = require("node:url");
 const promises_1 = require("node:fs/promises");
 const node_child_process_1 = require("node:child_process");
 const node_process_1 = require("node:process");
+const node_os_1 = require("node:os");
 const log = (color = '\x1b[30m', msg = '') => {
     // eslint-disable-next-line no-console
     console.log(`${color}%s\x1b[0m`, msg);
@@ -19,11 +20,14 @@ const getRealPathAsFileUrl = async (path) => {
 };
 exports.getRealPathAsFileUrl = getRealPathAsFileUrl;
 const getCompileFiles = (tscBinPath, wd = (0, node_process_1.cwd)()) => {
-    const { stdout } = (0, node_child_process_1.spawnSync)(tscBinPath, ['--listFilesOnly'], { cwd: wd });
+    const { stdout } = (0, node_child_process_1.spawnSync)(tscBinPath, ['--listFilesOnly'], {
+        cwd: wd,
+        shell: node_process_1.platform === 'win32',
+    });
     // Exclude node_modules and empty strings.
     return stdout
         .toString()
-        .split('\n')
+        .split(node_os_1.EOL)
         .filter(path => !/node_modules|^$/.test(path));
 };
 exports.getCompileFiles = getCompileFiles;

package/dist/esm/duel.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { argv } from 'node:process';
+import { argv, platform } from 'node:process';
 import { join, dirname, resolve, relative } from 'node:path';
 import { spawn } from 'node:child_process';
-import { writeFile, rm, rename, cp, mkdir } from 'node:fs/promises';
+import { writeFile, rm, rename, mkdir, cp } from 'node:fs/promises';
 import { randomBytes } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
 import { glob } from 'glob';
@@ -25,7 +25,7 @@ const handleErrorAndExit = message => {
 const duel = async (args) => {
     const ctx = await init(args);
     if (ctx) {
-        const { projectDir, tsconfig, configPath, dirs, pkg } = ctx;
+        const { projectDir, tsconfig, configPath, modules, dirs, pkg } = ctx;
         const tsc = await findUp(async (dir) => {
             const tscBin = join(dir, 'node_modules', '.bin', 'tsc');
             if (await pathExists(tscBin)) {
@@ -35,7 +35,7 @@ const duel = async (args) => {
         const runBuild = (project, outDir) => {
             return new Promise((resolve, reject) => {
                 const args = outDir ? ['-p', project, '--outDir', outDir] : ['-p', project];
-                const build = spawn(tsc, args, { stdio: 'inherit' });
+                const build = spawn(tsc, args, { stdio: 'inherit', shell: platform === 'win32' });
                 build.on('error', err => {
                     reject(new Error(`Failed to compile: ${err.message}`));
                 });
@@ -106,16 +106,36 @@ const duel = async (args) => {
             handleErrorAndExit(message);
         }
         if (success) {
-            const compileFiles = getCompileFiles(tsc, projectDir);
             const subDir = join(projectDir, `_${hex}_`);
-            const dualConfigPath = join(subDir, `tsconfig.${hex}.json`);
             const absoluteDualOutDir = join(projectDir, isCjsBuild ? join(outDir, 'cjs') : join(outDir, 'esm'));
             const tsconfigDual = getOverrideTsConfig();
             const pkgRename = 'package.json.bak';
+            let dualConfigPath = join(projectDir, `tsconfig.${hex}.json`);
             let errorMsg = '';
-            // Copy project directory as a subdirectory
-            await mkdir(subDir);
-            await Promise.all(compileFiles.map(file => cp(file, resolve(subDir, relative(projectDir, file)))));
+            if (modules) {
+                const compileFiles = getCompileFiles(tsc, projectDir);
+                dualConfigPath = join(subDir, `tsconfig.${hex}.json`);
+                await mkdir(subDir);
+                await Promise.all(compileFiles.map(file => cp(file, join(subDir, relative(projectDir, file).replace(/^(\.\.\/)*/, '')))));
+                /**
+                 * Transform ambiguous modules for the target dual build.
+                 * @see https://github.com/microsoft/TypeScript/issues/58658
+                 */
+                const toTransform = await glob(`${subDir}/**/*{.js,.jsx,.ts,.tsx}`, {
+                    ignore: 'node_modules/**',
+                });
+                for (const file of toTransform) {
+                    /**
+                     * Maybe include the option to transform modules implicitly
+                     * (modules: true) so that `exports` are correctly converted
+                     * when targeting a CJS dual build. Depends on @knighted/module
+                     * supporting he `modules` option.
+                     *
+                     * @see https://github.com/microsoft/TypeScript/issues/58658
+                     */
+                    await transform(file, { out: file, type: isCjsBuild ? 'commonjs' : 'module' });
+                }
+            }
             /**
              * Create a new package.json with updated `type` field.
              * Create a new tsconfig.json.
@@ -125,16 +145,6 @@ const duel = async (args) => {
                 type: isCjsBuild ? 'commonjs' : 'module',
             }));
             await writeFile(dualConfigPath, JSON.stringify(tsconfigDual));
-            /**
-             * Transform ambiguous modules for the target dual build.
-             * @see https://github.com/microsoft/TypeScript/issues/58658
-             */
-            const toTransform = await glob(`${subDir}/**/*{.js,.jsx,.ts,.tsx}`, {
-                ignore: 'node_modules/**',
-            });
-            for (const file of toTransform) {
-                await transform(file, { out: file, type: isCjsBuild ? 'commonjs' : 'module' });
-            }
             // Build dual
             log('Starting dual build...');
             try {

package/dist/esm/init.d.ts

@@ -1,6 +1,7 @@
 export function init(args: any): Promise<false | {
     pkg: import("read-package-up").NormalizedReadResult;
-    dirs: boolean | undefined;
+    dirs: boolean;
+    modules: boolean;
     tsconfig: any;
     projectDir: string;
     configPath: string;

package/dist/esm/init.js

@@ -26,6 +26,11 @@ const init = async (args) => {
                     short: 'k',
                     default: cwd(),
                 },
+                modules: {
+                    type: 'boolean',
+                    short: 'm',
+                    default: false,
+                },
                 dirs: {
                     type: 'boolean',
                     short: 'd',
@@ -49,11 +54,12 @@ const init = async (args) => {
         log('Options:');
         log("--project, -p [path] \t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.");
         log('--pkg-dir, -k [path] \t The directory to start looking for a package.json file. Defaults to cwd.');
+        log('--modules, -m \t\t Transform module globals for dual build target. Defaults to false.');
         log('--dirs, -d \t\t Output both builds to directories inside of outDir. [esm, cjs].');
         log('--help, -h \t\t Print this message.');
     }
     else {
-        const { project, 'target-extension': targetExt, 'pkg-dir': pkgDir, dirs } = parsed;
+        const { project, 'target-extension': targetExt, 'pkg-dir': pkgDir, modules, dirs, } = parsed;
         let configPath = resolve(project);
         let stats = null;
         let pkg = null;
@@ -102,6 +108,7 @@ const init = async (args) => {
             return {
                 pkg,
                 dirs,
+                modules,
                 tsconfig,
                 projectDir,
                 configPath,

package/dist/esm/util.js

@@ -1,7 +1,8 @@
 import { pathToFileURL } from 'node:url';
 import { realpath } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
-import { cwd } from 'node:process';
+import { cwd, platform } from 'node:process';
+import { EOL } from 'node:os';
 const log = (color = '\x1b[30m', msg = '') => {
     // eslint-disable-next-line no-console
     console.log(`${color}%s\x1b[0m`, msg);
@@ -13,11 +14,14 @@ const getRealPathAsFileUrl = async (path) => {
     return asFileUrl;
 };
 const getCompileFiles = (tscBinPath, wd = cwd()) => {
-    const { stdout } = spawnSync(tscBinPath, ['--listFilesOnly'], { cwd: wd });
+    const { stdout } = spawnSync(tscBinPath, ['--listFilesOnly'], {
+        cwd: wd,
+        shell: platform === 'win32',
+    });
     // Exclude node_modules and empty strings.
     return stdout
         .toString()
-        .split('\n')
+        .split(EOL)
         .filter(path => !/node_modules|^$/.test(path));
 };
 export { log, logError, getRealPathAsFileUrl, getCompileFiles };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/duel",
-  "version": "2.0.0-rc.0",
+  "version": "2.0.0-rc.2",
   "description": "TypeScript dual packages.",
   "type": "module",
   "main": "dist/esm/duel.js",
@@ -18,9 +18,11 @@
   },
   "engineStrict": true,
   "scripts": {
-    "prettier": "prettier -w src/*.js test/*.js",
+    "prettier": "prettier -w *.js src/*.js test/*.js",
     "lint": "eslint src/*.js test/*.js",
-    "test": "c8 --reporter=text --reporter=text-summary --reporter=lcov node --test --test-reporter=spec test/*.js",
+    "test:integration": "node --test --test-reporter=spec test/integration.js",
+    "test:monorepos": "node --test --test-reporter=spec test/monorepos.js",
+    "test": "c8 --reporter=text --reporter=text-summary --reporter=lcov node --test --test-reporter=spec test/integration.js test/monorepos.js",
     "build": "node src/duel.js --dirs",
     "prepack": "npm run build"
   },
@@ -51,19 +53,22 @@
     "url": "https://github.com/knightedcodemonkey/duel/issues"
   },
   "peerDependencies": {
-    "typescript": ">=4.0.0 || >=4.9.0-dev || >=5.3.0-dev || >=5.4.0-dev || >=5.5.0-dev || next"
+    "typescript": ">=5.5.0-dev || >=5.6.0-dev || >=5.7.0-dev || next"
   },
   "devDependencies": {
-    "@types/node": "^20.11.0",
-    "c8": "^8.0.1",
-    "eslint": "^8.45.0",
-    "eslint-plugin-n": "^16.0.1",
+    "@eslint/js": "^9.6.0",
+    "@types/node": "^22.7.4",
+    "c8": "^10.1.2",
+    "eslint": "^9.5.0",
+    "eslint-plugin-n": "^17.9.0",
+    "globals": "^15.6.0",
     "prettier": "^3.2.4",
-    "typescript": "^5.5.0-dev.20240525",
-    "vite": "^5.2.8"
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.2",
+    "vite": "^5.4.8"
   },
   "dependencies": {
-    "@knighted/module": "^1.0.0-alpha.3",
+    "@knighted/module": "^1.0.0-alpha.4",
     "@knighted/specifier": "^2.0.0-rc.1",
     "find-up": "^6.3.0",
     "glob": "^10.3.3",