@knighted/duel 3.1.1 → 3.2.0

package/README.md

@@ -71,16 +71,14 @@ Assuming an `outDir` of `dist`, running the above will create `dist/esm` and `di
 
 ### 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.
+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 asymmetry. Prefer the single-switch `--mode` interface: `--mode globals` (equivalent to `--modules`) or `--mode full` (equivalent to `--modules --transform-syntax`) to have the [ESM vs CJS differences](https://nodejs.org/api/esm.html#differences-between-es-modules-and-commonjs) transformed by `duel` prior to running `tsc` so you avoid compilation or runtime errors. The legacy `--modules`/`--transform-syntax` flags remain supported.
 
 `duel` infers the primary vs dual build orientation from your `package.json` `type`:
 
 - `"type": "module"` → primary ESM, dual CJS
 - `"type": "commonjs"` → primary CJS, dual ESM
 
-The `--dirs` flag nests outputs under `outDir/esm` and `outDir/cjs` accordingly.
-
-Note, there is a slight performance penalty since your project needs to be copied first to run the transforms before compiling with `tsc`.
+The `--dirs` flag nests outputs under `outDir/esm` and `outDir/cjs` accordingly. There is a small performance cost because sources are copied to run the transform before `tsc`.
 
 ```json
 "scripts": {
@@ -88,11 +86,31 @@ Note, there is a slight performance penalty since your project needs to be copie
 }
 ```
 
-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)).
+For projects that need full syntax lowering, opt in explicitly:
+
+```json
+"scripts": {
+  "build": "duel --modules --transform-syntax"
+}
+```
+
+Using the single switch:
+
+```json
+"scripts": {
+  "build": "duel --mode globals"
+}
+```
+
+```json
+"scripts": {
+  "build": "duel --mode full"
+}
+```
 
 #### Pre-`tsc` transform (TypeScript 58658)
 
-When you pass `--modules`, `duel` copies your sources and runs [`@knighted/module`](https://github.com/knightedcodemonkey/module) **before** `tsc` so the transformed files no longer trigger TypeScript’s asymmetrical module-global errors (see [TypeScript#58658](https://github.com/microsoft/TypeScript/issues/58658)). No extra setup is needed: `--modules` is the pre-`tsc` mitigation.
+When you enable module transforms (`--mode globals`, `--mode full`, or `--modules`), `duel` copies your sources and runs [`@knighted/module`](https://github.com/knightedcodemonkey/module) **before** `tsc` so the transformed files no longer trigger TypeScript’s asymmetrical module-global errors (see [TypeScript#58658](https://github.com/microsoft/TypeScript/issues/58658)). No extra setup is needed: module transforms are the pre-`tsc` mitigation. If you also select full lowering (`--mode full` or `--transform-syntax`), that pre-`tsc` step performs full lowering instead of globals-only.
 
 ## Options
 
@@ -100,25 +118,16 @@ The available options are limited, because you should define most of them inside
 
 - `--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 `--project` dir.
+- `--mode` Optional shorthand for the module transform mode: `none` (default), `globals` (modules + globals-only), `full` (modules + full syntax lowering). Recommended.
 - `--modules, -m` Transform module globals for dual build target. Defaults to false.
+- `--transform-syntax, -s` Opt in to full syntax lowering via `@knighted/module` (default is globals-only). Implies `--modules`.
 - `--dirs, -d` Outputs both builds to directories inside of `outDir`. Defaults to `false`.
 - `--exports, -e` Generate `package.json` `exports` from build output. Values: `wildcard` | `dir` | `name`.
 
 > [!NOTE]
 > Exports keys are extensionless by design; the target `import`/`require`/`types` entries keep explicit file extensions so Node resolution remains deterministic.
 
-You can run `duel --help` to get the same info. Below is the output of that:
-
-```console
-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 --project directory.
---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.
-```
+You can run `duel --help` to get the same info.
 
 ## Gotchas
 

package/dist/cjs/duel.cjs

@@ -184,7 +184,7 @@ const generateExports = async (options) => {
 const duel = async (args) => {
     const ctx = await (0, init_js_1.init)(args);
     if (ctx) {
-        const { projectDir, tsconfig, configPath, modules, dirs, pkg, exports: exportsOpt, } = ctx;
+        const { projectDir, tsconfig, configPath, modules, dirs, transformSyntax, pkg, exports: exportsOpt, } = ctx;
         const tsc = await (0, find_up_1.findUp)(async (dir) => {
             const tscBin = (0, node_path_1.join)(dir, 'node_modules', '.bin', 'tsc');
             try {
@@ -233,6 +233,7 @@ const duel = async (args) => {
         const runPrimaryBuild = () => {
             return runBuild(configPath, primaryOutDir);
         };
+        const syntaxMode = transformSyntax ? true : 'globals-only';
         const updateSpecifiersAndFileExtensions = async (filenames, target, ext) => {
             for (const filename of filenames) {
                 const dts = /(\.d\.ts)$/;
@@ -258,7 +259,7 @@ const duel = async (args) => {
                 const writeOptions = {
                     target,
                     rewriteSpecifier,
-                    transformSyntax: 'globals-only',
+                    transformSyntax: syntaxMode,
                     ...(outFilename === filename ? { inPlace: true } : { out: outFilename }),
                 };
                 await (0, module_1.transform)(filename, writeOptions);
@@ -304,18 +305,12 @@ const duel = async (args) => {
                     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
-                     */
+                    const isTsLike = /\.[cm]?tsx?$/.test(file);
+                    const transformSyntaxMode = syntaxMode === true && isTsLike ? 'globals-only' : syntaxMode;
                     await (0, module_1.transform)(file, {
                         out: file,
                         target: isCjsBuild ? 'commonjs' : 'module',
-                        transformSyntax: 'globals-only',
+                        transformSyntax: transformSyntaxMode,
                     });
                 }
             }

package/dist/cjs/init.cjs

@@ -41,6 +41,14 @@ const init = async (args) => {
                     type: 'string',
                     short: 'e',
                 },
+                'transform-syntax': {
+                    type: 'boolean',
+                    short: 's',
+                    default: false,
+                },
+                mode: {
+                    type: 'string',
+                },
                 help: {
                     type: 'boolean',
                     short: 'h',
@@ -58,18 +66,24 @@ const init = async (args) => {
         const bare = { bare: true };
         (0, util_js_1.log)('Usage: duel [options]\n', 'info', bare);
         (0, util_js_1.log)('Options:', 'info', bare);
-        (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'.", 'info', bare);
-        (0, util_js_1.log)('--pkg-dir, -k [path] \t The directory to start looking for a package.json file. Defaults to --project directory.', 'info', bare);
-        (0, util_js_1.log)('--modules, -m \t\t Transform module globals for dual build target. Defaults to false.', 'info', bare);
-        (0, util_js_1.log)('--dirs, -d \t\t Output both builds to directories inside of outDir. [esm, cjs].', 'info', bare);
-        (0, util_js_1.log)('--exports, -e \t Generate package.json exports. Values: wildcard | dir | name.', 'info', bare);
-        (0, util_js_1.log)('--help, -h \t\t Print this message.', 'info', bare);
+        (0, util_js_1.log)("--project, -p [path] \t\t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.", 'info', bare);
+        (0, util_js_1.log)('--pkg-dir, -k [path] \t\t The directory to start looking for a package.json file. Defaults to --project directory.', 'info', bare);
+        (0, util_js_1.log)('--modules, -m \t\t\t Transform module globals for dual build target. Defaults to false.', 'info', bare);
+        (0, util_js_1.log)('--dirs, -d \t\t\t Output both builds to directories inside of outDir. [esm, cjs].', 'info', bare);
+        (0, util_js_1.log)('--exports, -e \t\t\t Generate package.json exports. Values: wildcard | dir | name.', 'info', bare);
+        (0, util_js_1.log)('--transform-syntax, -s \t\t Opt in to full syntax lowering via @knighted/module (default is globals-only).', 'info', bare);
+        (0, util_js_1.log)('--mode [none|globals|full] \t Optional shorthand for module transforms and syntax lowering.', 'info', bare);
+        (0, util_js_1.log)('--help, -h \t\t\t Print this message.', 'info', bare);
     }
     else {
-        const { project, 'target-extension': targetExt, 'pkg-dir': pkgDir, modules, dirs, exports: exportsOpt, } = parsed;
+        const { project, 'target-extension': targetExt, 'pkg-dir': pkgDir, modules, dirs, exports: exportsOpt, 'transform-syntax': transformSyntax, mode, } = parsed;
         let configPath = (0, node_path_1.resolve)(project);
         let stats = null;
         let pkg = null;
+        if (mode && !['none', 'globals', 'full'].includes(mode)) {
+            (0, util_js_1.logError)('--mode expects one of: none | globals | full');
+            return false;
+        }
         if (targetExt) {
             (0, util_js_1.logError)('--target-extension is deprecated. Define "type" in your package.json instead and the dual build will be inferred from that.');
             return false;
@@ -106,10 +120,30 @@ const init = async (args) => {
                 (0, util_js_1.logError)('--exports expects one of: wildcard | dir | name');
                 return false;
             }
+            let modulesFinal = modules;
+            let transformSyntaxFinal = transformSyntax;
+            if (mode) {
+                if (mode === 'none') {
+                    modulesFinal = false;
+                    transformSyntaxFinal = false;
+                }
+                else if (mode === 'globals') {
+                    modulesFinal = true;
+                    transformSyntaxFinal = false;
+                }
+                else if (mode === 'full') {
+                    modulesFinal = true;
+                    transformSyntaxFinal = true;
+                }
+            }
+            else if (transformSyntax && !modules) {
+                modulesFinal = true;
+            }
             return {
                 pkg,
                 dirs,
-                modules,
+                modules: modulesFinal,
+                transformSyntax: transformSyntaxFinal,
                 exports: exportsOpt,
                 tsconfig,
                 projectDir,

package/dist/cjs/init.d.cts

@@ -2,6 +2,7 @@ export function init(args: any): Promise<false | {
     pkg: import("read-package-up", { with: { "resolution-mode": "import" } }).NormalizedReadResult;
     dirs: boolean;
     modules: boolean;
+    transformSyntax: boolean;
     exports: string | undefined;
     tsconfig: {
         compilerOptions?: import("get-tsconfig").TsConfigJson.CompilerOptions | undefined;

package/dist/esm/duel.js

@@ -181,7 +181,7 @@ const generateExports = async (options) => {
 const duel = async (args) => {
     const ctx = await init(args);
     if (ctx) {
-        const { projectDir, tsconfig, configPath, modules, dirs, pkg, exports: exportsOpt, } = ctx;
+        const { projectDir, tsconfig, configPath, modules, dirs, transformSyntax, pkg, exports: exportsOpt, } = ctx;
         const tsc = await findUp(async (dir) => {
             const tscBin = join(dir, 'node_modules', '.bin', 'tsc');
             try {
@@ -230,6 +230,7 @@ const duel = async (args) => {
         const runPrimaryBuild = () => {
             return runBuild(configPath, primaryOutDir);
         };
+        const syntaxMode = transformSyntax ? true : 'globals-only';
         const updateSpecifiersAndFileExtensions = async (filenames, target, ext) => {
             for (const filename of filenames) {
                 const dts = /(\.d\.ts)$/;
@@ -255,7 +256,7 @@ const duel = async (args) => {
                 const writeOptions = {
                     target,
                     rewriteSpecifier,
-                    transformSyntax: 'globals-only',
+                    transformSyntax: syntaxMode,
                     ...(outFilename === filename ? { inPlace: true } : { out: outFilename }),
                 };
                 await transform(filename, writeOptions);
@@ -301,18 +302,12 @@ const duel = async (args) => {
                     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
-                     */
+                    const isTsLike = /\.[cm]?tsx?$/.test(file);
+                    const transformSyntaxMode = syntaxMode === true && isTsLike ? 'globals-only' : syntaxMode;
                     await transform(file, {
                         out: file,
                         target: isCjsBuild ? 'commonjs' : 'module',
-                        transformSyntax: 'globals-only',
+                        transformSyntax: transformSyntaxMode,
                     });
                 }
             }

package/dist/esm/init.d.ts

@@ -2,6 +2,7 @@ export function init(args: any): Promise<false | {
     pkg: import("read-package-up").NormalizedReadResult;
     dirs: boolean;
     modules: boolean;
+    transformSyntax: boolean;
     exports: string | undefined;
     tsconfig: {
         compilerOptions?: import("get-tsconfig").TsConfigJson.CompilerOptions | undefined;

package/dist/esm/init.js

@@ -38,6 +38,14 @@ const init = async (args) => {
                     type: 'string',
                     short: 'e',
                 },
+                'transform-syntax': {
+                    type: 'boolean',
+                    short: 's',
+                    default: false,
+                },
+                mode: {
+                    type: 'string',
+                },
                 help: {
                     type: 'boolean',
                     short: 'h',
@@ -55,18 +63,24 @@ const init = async (args) => {
         const bare = { bare: true };
         log('Usage: duel [options]\n', 'info', bare);
         log('Options:', 'info', bare);
-        log("--project, -p [path] \t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.", 'info', bare);
-        log('--pkg-dir, -k [path] \t The directory to start looking for a package.json file. Defaults to --project directory.', 'info', bare);
-        log('--modules, -m \t\t Transform module globals for dual build target. Defaults to false.', 'info', bare);
-        log('--dirs, -d \t\t Output both builds to directories inside of outDir. [esm, cjs].', 'info', bare);
-        log('--exports, -e \t Generate package.json exports. Values: wildcard | dir | name.', 'info', bare);
-        log('--help, -h \t\t Print this message.', 'info', bare);
+        log("--project, -p [path] \t\t Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.", 'info', bare);
+        log('--pkg-dir, -k [path] \t\t The directory to start looking for a package.json file. Defaults to --project directory.', 'info', bare);
+        log('--modules, -m \t\t\t Transform module globals for dual build target. Defaults to false.', 'info', bare);
+        log('--dirs, -d \t\t\t Output both builds to directories inside of outDir. [esm, cjs].', 'info', bare);
+        log('--exports, -e \t\t\t Generate package.json exports. Values: wildcard | dir | name.', 'info', bare);
+        log('--transform-syntax, -s \t\t Opt in to full syntax lowering via @knighted/module (default is globals-only).', 'info', bare);
+        log('--mode [none|globals|full] \t Optional shorthand for module transforms and syntax lowering.', 'info', bare);
+        log('--help, -h \t\t\t Print this message.', 'info', bare);
     }
     else {
-        const { project, 'target-extension': targetExt, 'pkg-dir': pkgDir, modules, dirs, exports: exportsOpt, } = parsed;
+        const { project, 'target-extension': targetExt, 'pkg-dir': pkgDir, modules, dirs, exports: exportsOpt, 'transform-syntax': transformSyntax, mode, } = parsed;
         let configPath = resolve(project);
         let stats = null;
         let pkg = null;
+        if (mode && !['none', 'globals', 'full'].includes(mode)) {
+            logError('--mode expects one of: none | globals | full');
+            return false;
+        }
         if (targetExt) {
             logError('--target-extension is deprecated. Define "type" in your package.json instead and the dual build will be inferred from that.');
             return false;
@@ -103,10 +117,30 @@ const init = async (args) => {
                 logError('--exports expects one of: wildcard | dir | name');
                 return false;
             }
+            let modulesFinal = modules;
+            let transformSyntaxFinal = transformSyntax;
+            if (mode) {
+                if (mode === 'none') {
+                    modulesFinal = false;
+                    transformSyntaxFinal = false;
+                }
+                else if (mode === 'globals') {
+                    modulesFinal = true;
+                    transformSyntaxFinal = false;
+                }
+                else if (mode === 'full') {
+                    modulesFinal = true;
+                    transformSyntaxFinal = true;
+                }
+            }
+            else if (transformSyntax && !modules) {
+                modulesFinal = true;
+            }
             return {
                 pkg,
                 dirs,
-                modules,
+                modules: modulesFinal,
+                transformSyntax: transformSyntaxFinal,
                 exports: exportsOpt,
                 tsconfig,
                 projectDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/duel",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "TypeScript dual packages.",
   "type": "module",
   "main": "dist/esm/duel.js",