@knighted/duel 1.0.0-alpha.2 → 1.0.0-alpha.4

package/README.md

@@ -6,22 +6,23 @@
 
 Node.js tool for creating a TypeScript dual package.
 
-Early stages of development. Inspired by https://github.com/microsoft/TypeScript/issues/49462.
+Inspired by https://github.com/microsoft/TypeScript/issues/49462.
 
 ## Requirements
 
 * Node >= 16.19.0.
 * TypeScript, `npm i typescript`.
+* A `tsconfig.json` with `outDir` defined.
 
 ## Example
 
-First, install the package to create the `duel` executable inside your `node_modules/.bin` directory.
+First, install this package to create the `duel` executable inside your `node_modules/.bin` directory.
 
 ```console
 user@comp ~ $ npm i @knighted/duel
 ```
 
-Then, given a `package.json` that defines `"type": "module"` and  a `tsconfig.json` file that looks like the following:
+Then, given a `package.json` that defines `"type": "module"` and  a `tsconfig.json` file that looks something like the following:
 
 ```json
 {
@@ -51,9 +52,9 @@ And then running it:
 user@comp ~ $ npm run build
 ```
 
-If everything worked, you should have an ESM build inside of `dist` and a CJS build inside of `dist/cjs`. Now you can update your `exports` in package.json to match the build output.
+If everything worked, you should have an ESM build inside of `dist` and a CJS build inside of `dist/cjs`. Now you can update your [`exports`](https://nodejs.org/api/packages.html#exports) to match the build output.
 
-It should work similarly for a CJS first project. Except, your `tsconfig.json` would define `--module` and `--moduleResolution` differently, and you'd want to pass `-x .mjs`.
+It should work similarly for a CJS first project. Except, your `tsconfig.json` would define `--module` and `--moduleResolution` differently, and you'd want to pass `--target-extension .mjs`.
 
 See the available [options](#options).
 
@@ -71,13 +72,15 @@ You can run `duel --help` to get more info. Below is the output of that:
 Usage: duel [options]
 
 Options:
---project, -p 			 Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.
---target-extension, -x 		 Sets the file extension for the dual build. [.cjs,.mjs]
---help, -h 			 Print this message.
+--project, -p 		 Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.
+--target-extension, -x 	 Sets the file extension for the dual build. [.cjs,.mjs]
+--help, -h 		 Print this message.
 ```
 
 ## Gotchas
 
-* Unfortunately, TypeScript doesn't really understand dual packages very well. For instance, it will **always** create CJS exports when `--module commonjs` is used, even on files with an `.mts` extension. One reference issue is https://github.com/microsoft/TypeScript/issues/54573. If you use `.mts` extensions to enforce an ESM module system, this might break in the corresponding dual CJS build.
-* If targeting a dual CJS build, and you are using [top level `await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await), you will most likely encounter the compilation error `error TS1378: Top-level 'await' expressions are only allowed when the 'module' option is set to 'es2022', 'esnext', 'system', 'node16', or 'nodenext', and the 'target' option is set to 'es2017' or higher.` during the CJS build. This is because `duel` creates a temporary `tsconfig.json` from your original and overwrites the `--module` and `--moduleResolution` based on the provided `--target-ext`.
+These are definitely edge cases, and would only really come up if your project mixes file extensions. For example, if you have `.ts` files combined with `.mts`, and/or `.cts`. For most project, things should just work as expected.
+
+* 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_. In my opinion, the `tsc` compiler is fundamentally broken in this regard, and at best is enforcing usage patterns it shouldn't. If you want to see one of my extended rants on this, check out this [comment](https://github.com/microsoft/TypeScript/pull/50985#issuecomment-1656991606). This is only mentioned for transparency, `duel` will correct for this and produce files with the module system you would expect based on the files extension, so that it works with [how Node.js determines module systems](https://nodejs.org/api/packages.html#determining-module-system).
+
 * 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`.

package/dist/duel.cjs

@@ -15,7 +15,6 @@ var _glob = require("glob");
 var _specifier = require("@knighted/specifier");
 var _init = require("./init.cjs");
 var _util = require("./util.cjs");
-// TypeScript is defined as a peer dependency.
 const tsc = (0, _nodePath.join)((0, _nodeProcess.cwd)(), 'node_modules', '.bin', 'tsc');
 const runBuild = project => {
   const {
@@ -45,7 +44,8 @@ const duel = async args => {
       projectDir,
       tsconfig,
       targetExt,
-      configPath
+      configPath,
+      absoluteOutDir
     } = ctx;
     const startTime = _nodePerf_hooks.performance.now();
     (0, _util.log)('Starting primary build...\n');
@@ -58,13 +58,15 @@ const duel = async args => {
       } = tsconfig.compilerOptions;
       const dualConfigPath = (0, _nodePath.join)(projectDir, `tsconfig.${hex}.json`);
       const dualOutDir = isCjsBuild ? (0, _nodePath.join)(outDir, 'cjs') : (0, _nodePath.join)(outDir, 'mjs');
+      // Using structuredClone() would require node >= 17.0.0
       const tsconfigDual = {
         ...tsconfig,
         compilerOptions: {
           ...tsconfig.compilerOptions,
           outDir: dualOutDir,
-          module: isCjsBuild ? 'CommonJS' : 'NodeNext',
-          moduleResolution: isCjsBuild ? 'Node' : 'NodeNext'
+          module: isCjsBuild ? 'CommonJS' : 'ESNext',
+          // Best way to make this work given how tsc works
+          moduleResolution: 'Node'
         }
       };
       await (0, _promises.writeFile)(dualConfigPath, JSON.stringify(tsconfigDual, null, 2));
@@ -74,7 +76,8 @@ const duel = async args => {
         force: true
       });
       if (success) {
-        const filenames = await (0, _glob.glob)(`${(0, _nodePath.join)(projectDir, dualOutDir)}/**/*{.js,.d.ts}`, {
+        const absoluteDualOutDir = (0, _nodePath.join)(projectDir, dualOutDir);
+        const filenames = await (0, _glob.glob)(`${absoluteDualOutDir}/**/*{.js,.d.ts}`, {
           ignore: 'node_modules/**'
         });
         for (const filename of filenames) {
@@ -96,6 +99,49 @@ const duel = async args => {
             force: true
           });
         }
+
+        /**
+         * This is a fix for tsc compiler which doesn't seem to support
+         * converting an arbitrary `.ts` file, into another module system,
+         * while also preserving the module systems of `.mts` and `.cts` files.
+         *
+         * Hopefully it can be removed when TS updates their supported options,
+         * or at least how the combination of `--module` and `--moduleResolution`
+         * currently work.
+         *
+         * @see https://github.com/microsoft/TypeScript/pull/50985#issuecomment-1656991606
+         */
+        if (isCjsBuild) {
+          const mjsFiles = await (0, _glob.glob)(`${absoluteOutDir}/**/*.mjs`, {
+            ignore: ['node_modules/**', `${absoluteDualOutDir}/**`]
+          });
+          for (const filename of mjsFiles) {
+            const relativeFn = (0, _nodePath.relative)(absoluteOutDir, filename);
+            await (0, _promises.copyFile)(filename, (0, _nodePath.join)(absoluteDualOutDir, relativeFn));
+          }
+        } else {
+          const cjsFiles = await (0, _glob.glob)(`${absoluteOutDir}/**/*.cjs`, {
+            ignore: ['node_modules/**', `${absoluteDualOutDir}/**`]
+          });
+          for (const filename of cjsFiles) {
+            const relativeFn = (0, _nodePath.relative)(absoluteOutDir, filename);
+            await (0, _promises.copyFile)(filename, (0, _nodePath.join)(absoluteDualOutDir, relativeFn));
+          }
+
+          /**
+           * Now copy the good .mjs files from the dual out dir
+           * to the original out dir, but build the file path
+           * from the original out dir to distinguish from the
+           * dual build .mjs files.
+           */
+          const mjsFiles = await (0, _glob.glob)(`${absoluteOutDir}/**/*.mjs`, {
+            ignore: ['node_modules/**', `${absoluteDualOutDir}/**`]
+          });
+          for (const filename of mjsFiles) {
+            const relativeFn = (0, _nodePath.relative)(absoluteOutDir, filename);
+            await (0, _promises.copyFile)((0, _nodePath.join)(absoluteDualOutDir, relativeFn), filename);
+          }
+        }
         (0, _util.log)(`Successfully created a dual ${targetExt.replace('.', '').toUpperCase()} build in ${Math.round(_nodePerf_hooks.performance.now() - startTime)}ms.`);
       }
     }

package/dist/duel.js

@@ -1,16 +1,14 @@
 #!/usr/bin/env node
 import { argv, cwd } from 'node:process';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { writeFile, rm } from 'node:fs/promises';
+import { writeFile, copyFile, rm } from 'node:fs/promises';
 import { randomBytes } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
 import { glob } from 'glob';
 import { specifier } from '@knighted/specifier';
 import { init } from './init.js';
 import { getRealPathAsFileUrl, logError, log } from './util.js';
-
-// TypeScript is defined as a peer dependency.
 const tsc = join(cwd(), 'node_modules', '.bin', 'tsc');
 const runBuild = project => {
   const {
@@ -40,7 +38,8 @@ const duel = async args => {
       projectDir,
       tsconfig,
       targetExt,
-      configPath
+      configPath,
+      absoluteOutDir
     } = ctx;
     const startTime = performance.now();
     log('Starting primary build...\n');
@@ -53,13 +52,15 @@ const duel = async args => {
       } = tsconfig.compilerOptions;
       const dualConfigPath = join(projectDir, `tsconfig.${hex}.json`);
       const dualOutDir = isCjsBuild ? join(outDir, 'cjs') : join(outDir, 'mjs');
+      // Using structuredClone() would require node >= 17.0.0
       const tsconfigDual = {
         ...tsconfig,
         compilerOptions: {
           ...tsconfig.compilerOptions,
           outDir: dualOutDir,
-          module: isCjsBuild ? 'CommonJS' : 'NodeNext',
-          moduleResolution: isCjsBuild ? 'Node' : 'NodeNext'
+          module: isCjsBuild ? 'CommonJS' : 'ESNext',
+          // Best way to make this work given how tsc works
+          moduleResolution: 'Node'
         }
       };
       await writeFile(dualConfigPath, JSON.stringify(tsconfigDual, null, 2));
@@ -69,7 +70,8 @@ const duel = async args => {
         force: true
       });
       if (success) {
-        const filenames = await glob(`${join(projectDir, dualOutDir)}/**/*{.js,.d.ts}`, {
+        const absoluteDualOutDir = join(projectDir, dualOutDir);
+        const filenames = await glob(`${absoluteDualOutDir}/**/*{.js,.d.ts}`, {
           ignore: 'node_modules/**'
         });
         for (const filename of filenames) {
@@ -91,6 +93,49 @@ const duel = async args => {
             force: true
           });
         }
+
+        /**
+         * This is a fix for tsc compiler which doesn't seem to support
+         * converting an arbitrary `.ts` file, into another module system,
+         * while also preserving the module systems of `.mts` and `.cts` files.
+         *
+         * Hopefully it can be removed when TS updates their supported options,
+         * or at least how the combination of `--module` and `--moduleResolution`
+         * currently work.
+         *
+         * @see https://github.com/microsoft/TypeScript/pull/50985#issuecomment-1656991606
+         */
+        if (isCjsBuild) {
+          const mjsFiles = await glob(`${absoluteOutDir}/**/*.mjs`, {
+            ignore: ['node_modules/**', `${absoluteDualOutDir}/**`]
+          });
+          for (const filename of mjsFiles) {
+            const relativeFn = relative(absoluteOutDir, filename);
+            await copyFile(filename, join(absoluteDualOutDir, relativeFn));
+          }
+        } else {
+          const cjsFiles = await glob(`${absoluteOutDir}/**/*.cjs`, {
+            ignore: ['node_modules/**', `${absoluteDualOutDir}/**`]
+          });
+          for (const filename of cjsFiles) {
+            const relativeFn = relative(absoluteOutDir, filename);
+            await copyFile(filename, join(absoluteDualOutDir, relativeFn));
+          }
+
+          /**
+           * Now copy the good .mjs files from the dual out dir
+           * to the original out dir, but build the file path
+           * from the original out dir to distinguish from the
+           * dual build .mjs files.
+           */
+          const mjsFiles = await glob(`${absoluteOutDir}/**/*.mjs`, {
+            ignore: ['node_modules/**', `${absoluteDualOutDir}/**`]
+          });
+          for (const filename of mjsFiles) {
+            const relativeFn = relative(absoluteOutDir, filename);
+            await copyFile(join(absoluteDualOutDir, relativeFn), filename);
+          }
+        }
         log(`Successfully created a dual ${targetExt.replace('.', '').toUpperCase()} build in ${Math.round(performance.now() - startTime)}ms.`);
       }
     }

package/dist/init.cjs

@@ -42,9 +42,9 @@ const init = async args => {
   if (parsed.help) {
     (0, _util.log)('Usage: duel [options]\n');
     (0, _util.log)('Options:');
-    (0, _util.log)("--project, -p \t\t\t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.");
-    (0, _util.log)('--target-extension, -x \t\t Sets the file extension for the dual build. [.cjs,.mjs]');
-    (0, _util.log)('--help, -h \t\t\t Print this message.');
+    (0, _util.log)("--project, -p \t\t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.");
+    (0, _util.log)('--target-extension, -x \t Sets the file extension for the dual build. [.cjs,.mjs]');
+    (0, _util.log)('--help, -h \t\t Print this message.');
   } else {
     const {
       project,

package/dist/init.js

@@ -36,9 +36,9 @@ const init = async args => {
   if (parsed.help) {
     log('Usage: duel [options]\n');
     log('Options:');
-    log("--project, -p \t\t\t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.");
-    log('--target-extension, -x \t\t Sets the file extension for the dual build. [.cjs,.mjs]');
-    log('--help, -h \t\t\t Print this message.');
+    log("--project, -p \t\t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.");
+    log('--target-extension, -x \t Sets the file extension for the dual build. [.cjs,.mjs]');
+    log('--help, -h \t\t Print this message.');
   } else {
     const {
       project,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/duel",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "description": "TypeScript dual packages.",
   "type": "module",
   "main": "dist",
@@ -44,7 +44,7 @@
     "url": "https://github.com/knightedcodemonkey/duel/issues"
   },
   "peerDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": ">=4.0.0"
   },
   "devDependencies": {
     "babel-dual-package": "^1.0.0-rc.5",