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

package/README.md

@@ -8,36 +8,76 @@ Node.js tool for creating a TypeScript dual package.
 
 Early stages of development. Inspired by https://github.com/microsoft/TypeScript/issues/49462.
 
+## Requirements
+
+* Node >= 16.19.0.
+* TypeScript, `npm i typescript`.
+
 ## Example
 
-Consider a project that is ESM-first, i.e. `"type": "module"` in package.json, that also wants to create a separate CJS build. It might have a tsconfig.json file that looks like the following.
+First, install the package to create the `duel` executable inside your `node_modules/.bin` directory.
+
+```console
+user@comp ~ $ npm i @knighted/duel
+```
 
-**tsconfig.json**
+Then, given a `package.json` that defines `"type": "module"` and  a `tsconfig.json` file that looks like the following:
 
 ```json
 {
   "compilerOptions": {
-    "target": "ESNext",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "declaration": true,
+    "esModuleInterop": true,
+    "outDir": "dist",
     "strict": true,
-    "outDir": "dist"
   },
-  "include": ["src/*.ts"]
+  "include": ["src"]
+}
+```
+
+You can create a build for the project defined by the above configuration, **and also a separate dual CJS build** by defining the following npm run script in your `package.json`:
+
+```json
+"scripts": {
+  "build": "duel"
 }
 ```
 
-Running the following will use the tsconfig.json defined above and create a separate CJS build in `dist/cjs`.
+And then running it:
 
 ```console
-user@comp ~ $ duel -p tsconfig.json -x .cjs
+user@comp ~ $ npm run build
 ```
 
-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` in package.json to match the build output.
 
-It should work similarly for a CJS first project. Except, your tsconfig.json would be slightly different 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 `-x .mjs`.
+
+See the available [options](#options).
+
+
+## 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`.
+* `--target-extension, -x` The desired target extension which determines the type of dual build. Defaults to `.cjs`.
+
+You can run `duel --help` to get more info. Below is the output of that:
+
+```console
+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.
+```
 
 ## 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.
+* 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`.
+* 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

@@ -6,7 +6,6 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.duel = void 0;
 var _nodeProcess = require("node:process");
-var _nodeUrl = require("node:url");
 var _nodePath = require("node:path");
 var _nodeChild_process = require("node:child_process");
 var _promises = require("node:fs/promises");
@@ -16,10 +15,8 @@ var _glob = require("glob");
 var _specifier = require("@knighted/specifier");
 var _init = require("./init.cjs");
 var _util = require("./util.cjs");
-const _filename = (0, _nodeUrl.fileURLToPath)(import.meta.url);
-const _dirname = (0, _nodePath.dirname)(_filename);
-const root = (0, _nodePath.join)(_dirname, '..');
-const tsc = (0, _nodePath.join)(root, 'node_modules', '.bin', 'tsc');
+// TypeScript is defined as a peer dependency.
+const tsc = (0, _nodePath.join)((0, _nodeProcess.cwd)(), 'node_modules', '.bin', 'tsc');
 const runBuild = project => {
   const {
     status,

package/dist/duel.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
-import { argv } from 'node:process';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { argv, cwd } from 'node:process';
+import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { writeFile, rm } from 'node:fs/promises';
 import { randomBytes } from 'node:crypto';
@@ -10,10 +9,9 @@ import { glob } from 'glob';
 import { specifier } from '@knighted/specifier';
 import { init } from './init.js';
 import { getRealPathAsFileUrl, logError, log } from './util.js';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const root = join(__dirname, '..');
-const tsc = join(root, 'node_modules', '.bin', 'tsc');
+
+// TypeScript is defined as a peer dependency.
+const tsc = join(cwd(), 'node_modules', '.bin', 'tsc');
 const runBuild = project => {
   const {
     status,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/duel",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "description": "TypeScript dual packages.",
   "type": "module",
   "main": "dist",
@@ -56,8 +56,7 @@
   },
   "dependencies": {
     "@knighted/specifier": "^1.0.0-alpha.5",
-    "glob": "^10.3.3",
-    "magic-string": "^0.30.1"
+    "glob": "^10.3.3"
   },
   "prettier": {
     "arrowParens": "avoid",