@knighted/module 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -9,6 +9,12 @@ Node.js utility for transforming a JavaScript or TypeScript file from an ES modu
 - ES module ➡️ CommonJS
 - CommonJS ➡️ ES module
 
+Highlights
+
+- Defaults to safe CommonJS output: strict live bindings, import.meta shims, and specifier preservation.
+- Opt into stricter/looser behaviors: live binding enforcement, import.meta.main gating, and top-level await strategies.
+- Can optionally rewrite relative specifiers and write transformed output to disk.
+
 > [!IMPORTANT]  
 > All parsing logic is applied under the assumption the code is in [strict mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) which [modules run under by default](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#other_differences_between_modules_and_classic_scripts).
 
@@ -18,9 +24,15 @@ By default `@knighted/module` transforms the one-to-one [differences between ES
 
 - Node >= 20.11.0
 
+## Install
+
+```bash
+npm install @knighted/module
+```
+
 ## Example
 
-Given an ES module
+Given an ES module:
 
 **file.js**
 
@@ -40,7 +52,7 @@ const detectCalledFromCli = async path => {
 detectCalledFromCli(argv[1])
 ```
 
-You can transform it to the equivalent CommonJS module
+Transform it to CommonJS:
 
 ```js
 import { transform } from '@knighted/module'
@@ -51,7 +63,7 @@ await transform('./file.js', {
 })
 ```
 
-Which produces
+Which produces:
 
 **file.cjs**
 
@@ -99,6 +111,7 @@ type ModuleOptions = {
     | ((value: string) => string | null | undefined)
   dirFilename?: 'inject' | 'preserve' | 'error'
   importMeta?: 'preserve' | 'shim' | 'error'
+  importMetaMain?: 'shim' | 'warn' | 'error'
   requireSource?: 'builtin' | 'create-require'
   cjsDefault?: 'module-exports' | 'auto' | 'none'
   topLevelAwait?: 'error' | 'wrap' | 'preserve'
@@ -107,7 +120,24 @@ type ModuleOptions = {
 }
 ```
 
+Behavior notes (defaults in parentheses)
+
+- `target` (`commonjs`): output module system.
+- `transformSyntax` (true): enable/disable the ESM↔CJS lowering pass.
+- `liveBindings` (`strict`): getter-based live bindings, or snapshot (`loose`/`off`).
+- `dirFilename` (`inject`): inject `__dirname`/`__filename`, preserve existing, or throw.
+- `importMeta` (`shim`): rewrite `import.meta.*` to CommonJS equivalents.
+- `importMetaMain` (`shim`): gate `import.meta.main` with shimming/warning/error when Node support is too old.
+- `topLevelAwait` (`error`): throw, wrap, or preserve when TLA appears in CommonJS output.
+- `rewriteSpecifier` (off): rewrite relative specifiers to a chosen extension or via a callback.
+- `requireSource` (`builtin`): whether `require` comes from Node or `createRequire`.
+- `cjsDefault` (`auto`): bundler-style default interop vs direct `module.exports`.
+- `out`/`inPlace`: write the transformed code to a file; otherwise the function returns the transformed string only.
+
+See [docs/esm-to-cjs.md](docs/esm-to-cjs.md) for deeper notes on live bindings, interop helpers, top-level await behavior, and `import.meta.main` handling.
+
 ## Roadmap
 
 - Remove `@knighted/specifier` and avoid double parsing.
-- Flesh out live-binding and top-level await handling.
+- Emit source maps and clearer diagnostics for transform choices.
+- Broaden fixtures covering live-binding and top-level await edge cases across Node versions.

package/dist/cjs/format.cjs

@@ -15,6 +15,240 @@ var _identifiers = require("#utils/identifiers.js");
 var _identifier2 = require("#helpers/identifier.js");
 var _walk = require("#walk");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const isValidIdent = name => /^[$A-Z_a-z][$\w]*$/.test(name);
+const exportAssignment = (name, expr, live) => {
+  const prop = isValidIdent(name) ? `.${name}` : `[${JSON.stringify(name)}]`;
+  if (live === 'strict') {
+    const key = JSON.stringify(name);
+    return `Object.defineProperty(exports, ${key}, { enumerable: true, get: () => ${expr} });`;
+  }
+  return `exports${prop} = ${expr};`;
+};
+const defaultInteropName = '__interopDefault';
+const interopHelper = `const ${defaultInteropName} = mod => (mod && mod.__esModule ? mod.default : mod);\n`;
+const hasTopLevelAwait = program => {
+  let found = false;
+  const walkNode = (node, inFunction) => {
+    if (found) return;
+    switch (node.type) {
+      case 'FunctionDeclaration':
+      case 'FunctionExpression':
+      case 'ArrowFunctionExpression':
+      case 'ClassDeclaration':
+      case 'ClassExpression':
+        inFunction = true;
+        break;
+    }
+    if (!inFunction && node.type === 'AwaitExpression') {
+      found = true;
+      return;
+    }
+    const keys = Object.keys(node);
+    for (const key of keys) {
+      const value = node[key];
+      if (!value) continue;
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (item && typeof item === 'object') {
+            walkNode(item, inFunction);
+            if (found) return;
+          }
+        }
+      } else if (value && typeof value === 'object') {
+        walkNode(value, inFunction);
+        if (found) return;
+      }
+    }
+  };
+  walkNode(program, false);
+  return found;
+};
+const lowerEsmToCjs = (program, code, opts, containsTopLevelAwait) => {
+  const live = opts.liveBindings ?? 'strict';
+  const importTransforms = [];
+  const exportTransforms = [];
+  let needsInterop = false;
+  let importIndex = 0;
+  for (const node of program.body) {
+    if (node.type === 'ImportDeclaration') {
+      const srcLiteral = code.slice(node.source.start, node.source.end);
+      const specifiers = node.specifiers ?? [];
+      const defaultSpec = specifiers.find(s => s.type === 'ImportDefaultSpecifier');
+      const namespaceSpec = specifiers.find(s => s.type === 'ImportNamespaceSpecifier');
+      const namedSpecs = specifiers.filter(s => s.type === 'ImportSpecifier');
+
+      // Side-effect import
+      if (!specifiers.length) {
+        importTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `require(${srcLiteral});\n`,
+          needsInterop: false
+        });
+        continue;
+      }
+      const modIdent = `__mod${importIndex++}`;
+      const lines = [];
+      lines.push(`const ${modIdent} = require(${srcLiteral});`);
+      if (namespaceSpec) {
+        lines.push(`const ${namespaceSpec.local.name} = ${modIdent};`);
+      }
+      if (defaultSpec) {
+        let init = modIdent;
+        switch (opts.cjsDefault) {
+          case 'module-exports':
+            init = modIdent;
+            break;
+          case 'none':
+            init = `${modIdent}.default`;
+            break;
+          case 'auto':
+          default:
+            init = `${defaultInteropName}(${modIdent})`;
+            needsInterop = true;
+            break;
+        }
+        lines.push(`const ${defaultSpec.local.name} = ${init};`);
+      }
+      if (namedSpecs.length) {
+        const pairs = namedSpecs.map(s => {
+          const imported = s.imported.name;
+          const local = s.local.name;
+          return imported === local ? imported : `${imported}: ${local}`;
+        });
+        lines.push(`const { ${pairs.join(', ')} } = ${modIdent};`);
+      }
+      importTransforms.push({
+        start: node.start,
+        end: node.end,
+        code: `${lines.join('\n')}\n`,
+        needsInterop
+      });
+    }
+    if (node.type === 'ExportNamedDeclaration') {
+      // Handle declaration exports
+      if (node.declaration) {
+        const decl = node.declaration;
+        const declSrc = code.slice(decl.start, decl.end);
+        const exportedNames = [];
+        if (decl.type === 'VariableDeclaration') {
+          for (const d of decl.declarations) {
+            if (d.id.type === 'Identifier') {
+              exportedNames.push(d.id.name);
+            }
+          }
+        } else if (decl.id?.type === 'Identifier') {
+          exportedNames.push(decl.id.name);
+        }
+        const exportLines = exportedNames.map(name => exportAssignment(name, name, live));
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${declSrc}\n${exportLines.join('\n')}\n`
+        });
+        continue;
+      }
+
+      // Handle re-export or local specifiers
+      if (node.specifiers?.length) {
+        if (node.source) {
+          const srcLiteral = code.slice(node.source.start, node.source.end);
+          const modIdent = `__mod${importIndex++}`;
+          const lines = [`const ${modIdent} = require(${srcLiteral});`];
+          for (const spec of node.specifiers) {
+            if (spec.type !== 'ExportSpecifier') continue;
+            const exported = spec.exported.name;
+            const imported = spec.local.name;
+            let rhs = `${modIdent}.${imported}`;
+            if (imported === 'default') {
+              rhs = `${defaultInteropName}(${modIdent})`;
+              needsInterop = true;
+            }
+            lines.push(exportAssignment(exported, rhs, live));
+          }
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${lines.join('\n')}\n`,
+            needsInterop
+          });
+        } else {
+          const lines = [];
+          for (const spec of node.specifiers) {
+            if (spec.type !== 'ExportSpecifier') continue;
+            const exported = spec.exported.name;
+            const local = spec.local.name;
+            lines.push(exportAssignment(exported, local, live));
+          }
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${lines.join('\n')}\n`
+          });
+        }
+      }
+    }
+    if (node.type === 'ExportDefaultDeclaration') {
+      const decl = node.declaration;
+      const useExportsObject = containsTopLevelAwait && opts.topLevelAwait !== 'error';
+      if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
+        if (decl.id?.name) {
+          const declSrc = code.slice(decl.start, decl.end);
+          const assign = useExportsObject ? `exports.default = ${decl.id.name};` : `module.exports = ${decl.id.name};`;
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${declSrc}\n${assign}\n`
+          });
+        } else {
+          const declSrc = code.slice(decl.start, decl.end);
+          const assign = useExportsObject ? `exports.default = ${declSrc};` : `module.exports = ${declSrc};`;
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${assign}\n`
+          });
+        }
+      } else {
+        const exprSrc = code.slice(decl.start, decl.end);
+        const assign = useExportsObject ? `exports.default = ${exprSrc};` : `module.exports = ${exprSrc};`;
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${assign}\n`
+        });
+      }
+    }
+    if (node.type === 'ExportAllDeclaration') {
+      const srcLiteral = code.slice(node.source.start, node.source.end);
+      if (node.exported) {
+        const exported = node.exported.name;
+        const modIdent = `__mod${importIndex++}`;
+        const lines = [`const ${modIdent} = require(${srcLiteral});`, exportAssignment(exported, modIdent, live)];
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${lines.join('\n')}\n`
+        });
+      } else {
+        const modIdent = `__mod${importIndex++}`;
+        const lines = [`const ${modIdent} = require(${srcLiteral});`];
+        const loop = `for (const k in ${modIdent}) {\n  if (k === 'default') continue;\n  if (!Object.prototype.hasOwnProperty.call(${modIdent}, k)) continue;\n  Object.defineProperty(exports, k, { enumerable: true, get: () => ${modIdent}[k] });\n}`;
+        lines.push(loop);
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${lines.join('\n')}\n`
+        });
+      }
+    }
+  }
+  return {
+    importTransforms,
+    exportTransforms,
+    needsInterop
+  };
+};
 /**
  * Node added support for import.meta.main.
  * Added in: v24.2.0, v22.18.0
@@ -30,6 +264,13 @@ const format = async (src, ast, opts) => {
   };
   const exportTable = opts.target === 'module' ? await (0, _exports.collectCjsExports)(ast.program) : null;
   await (0, _identifiers.collectModuleIdentifiers)(ast.program);
+  const shouldCheckTopLevelAwait = opts.target === 'commonjs' && opts.transformSyntax;
+  const containsTopLevelAwait = shouldCheckTopLevelAwait ? hasTopLevelAwait(ast.program) : false;
+  const shouldLowerCjs = opts.target === 'commonjs' && opts.transformSyntax;
+  let pendingCjsTransforms = null;
+  if (shouldLowerCjs && opts.topLevelAwait === 'error' && containsTopLevelAwait) {
+    throw new Error('Top-level await is not supported when targeting CommonJS (set topLevelAwait to "wrap" or "preserve" to override).');
+  }
   if (opts.target === 'module' && opts.transformSyntax) {
     /**
      * Prepare ESM output by renaming `exports` to `__exports` and seeding an
@@ -114,6 +355,25 @@ void import.meta.filename;
       }
     }
   });
+  if (shouldLowerCjs) {
+    const {
+      importTransforms,
+      exportTransforms,
+      needsInterop
+    } = lowerEsmToCjs(ast.program, code, opts, containsTopLevelAwait);
+    pendingCjsTransforms = {
+      transforms: [...importTransforms, ...exportTransforms].sort((a, b) => a.start - b.start),
+      needsInterop
+    };
+  }
+  if (pendingCjsTransforms) {
+    for (const t of pendingCjsTransforms.transforms) {
+      code.overwrite(t.start, t.end, t.code);
+    }
+    if (pendingCjsTransforms.needsInterop) {
+      code.prepend(`${interopHelper}exports.__esModule = true;\n`);
+    }
+  }
   if (opts.target === 'module' && opts.transformSyntax && exportTable) {
     const isValidExportName = name => /^[$A-Z_a-z][$\w]*$/.test(name);
     const asExportName = name => isValidExportName(name) ? name : JSON.stringify(name);
@@ -143,6 +403,16 @@ void import.meta.filename;
       code.append(`\n${lines.join('\n')}\n`);
     }
   }
+  if (opts.target === 'commonjs' && opts.transformSyntax && containsTopLevelAwait) {
+    const body = code.toString();
+    if (opts.topLevelAwait === 'wrap') {
+      const tlaPromise = `const __tla = (async () => {\n${body}\nreturn module.exports;\n})();\n`;
+      const setPromise = `const __setTla = target => {\n  if (!target) return;\n  const type = typeof target;\n  if (type !== 'object' && type !== 'function') return;\n  target.__tla = __tla;\n};\n`;
+      const attach = `__setTla(module.exports);\n__tla.then(resolved => __setTla(resolved), err => { throw err; });\n`;
+      return `${tlaPromise}${setPromise}${attach}`;
+    }
+    return `;(async () => {\n${body}\n})();\n`;
+  }
   return code.toString();
 };
 exports.format = format;

package/dist/cjs/formatters/metaProperty.cjs

@@ -4,6 +4,19 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.metaProperty = void 0;
+const importMetaMainSupport = '(() => { const [__nmaj, __nmin] = process.versions.node.split(".").map(n => parseInt(n, 10) || 0); return (__nmaj > 24 || (__nmaj === 24 && __nmin >= 2) || (__nmaj === 22 && __nmin >= 18)); })()';
+const importMetaMainShim = 'process.argv[1] === __filename';
+const importMetaMainExpr = mode => {
+  switch (mode) {
+    case 'warn':
+      return `(${importMetaMainSupport} ? ${importMetaMainShim} : (console.warn("import.meta.main is not supported before Node 22.18/24.2; falling back to shim."), ${importMetaMainShim}))`;
+    case 'error':
+      return `(${importMetaMainSupport} ? ${importMetaMainShim} : (() => { throw new Error("import.meta.main is not supported before Node 22.18/24.2"); })())`;
+    case 'shim':
+    default:
+      return importMetaMainShim;
+  }
+};
 const metaProperty = (node, parent, src, options) => {
   if (options.target === 'commonjs') {
     if (parent?.type !== 'MemberExpression') {
@@ -27,10 +40,15 @@ const metaProperty = (node, parent, src, options) => {
           break;
         case 'resolve':
           /**
-           * Should this be `require('node:url').pathToFileURL(require.resolve(<parsed specifier>)).href`?
+           * Map to require.resolve intentionally: matches CJS resolution semantics.
+           * Wrapping in pathToFileURL(...) would change the return shape (URL string)
+           * without truly emulating ESM import.meta.resolve rules.
            */
           src.update(parent.start, parent.end, 'require.resolve');
           break;
+        case 'main':
+          src.update(parent.start, parent.end, importMetaMainExpr(options.importMetaMain));
+          break;
       }
     }
   }

package/dist/cjs/module.cjs

@@ -18,6 +18,7 @@ const defaultOptions = {
   rewriteSpecifier: undefined,
   dirFilename: 'inject',
   importMeta: 'shim',
+  importMetaMain: 'shim',
   requireSource: 'builtin',
   cjsDefault: 'auto',
   topLevelAwait: 'error',

package/dist/cjs/types.d.cts

@@ -8,6 +8,7 @@ export type ModuleOptions = {
     rewriteSpecifier?: RewriteSpecifier;
     dirFilename?: 'inject' | 'preserve' | 'error';
     importMeta?: 'preserve' | 'shim' | 'error';
+    importMetaMain?: 'shim' | 'warn' | 'error';
     requireSource?: 'builtin' | 'create-require';
     cjsDefault?: 'module-exports' | 'auto' | 'none';
     topLevelAwait?: 'error' | 'wrap' | 'preserve';

package/dist/format.js

@@ -8,7 +8,240 @@ import { exportsRename, collectCjsExports } from '#utils/exports.js';
 import { collectModuleIdentifiers } from '#utils/identifiers.js';
 import { isIdentifierName } from '#helpers/identifier.js';
 import { ancestorWalk } from '#walk';
+const isValidIdent = name => /^[$A-Z_a-z][$\w]*$/.test(name);
+const exportAssignment = (name, expr, live) => {
+  const prop = isValidIdent(name) ? `.${name}` : `[${JSON.stringify(name)}]`;
+  if (live === 'strict') {
+    const key = JSON.stringify(name);
+    return `Object.defineProperty(exports, ${key}, { enumerable: true, get: () => ${expr} });`;
+  }
+  return `exports${prop} = ${expr};`;
+};
+const defaultInteropName = '__interopDefault';
+const interopHelper = `const ${defaultInteropName} = mod => (mod && mod.__esModule ? mod.default : mod);\n`;
+const hasTopLevelAwait = program => {
+  let found = false;
+  const walkNode = (node, inFunction) => {
+    if (found) return;
+    switch (node.type) {
+      case 'FunctionDeclaration':
+      case 'FunctionExpression':
+      case 'ArrowFunctionExpression':
+      case 'ClassDeclaration':
+      case 'ClassExpression':
+        inFunction = true;
+        break;
+    }
+    if (!inFunction && node.type === 'AwaitExpression') {
+      found = true;
+      return;
+    }
+    const keys = Object.keys(node);
+    for (const key of keys) {
+      const value = node[key];
+      if (!value) continue;
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (item && typeof item === 'object') {
+            walkNode(item, inFunction);
+            if (found) return;
+          }
+        }
+      } else if (value && typeof value === 'object') {
+        walkNode(value, inFunction);
+        if (found) return;
+      }
+    }
+  };
+  walkNode(program, false);
+  return found;
+};
+const lowerEsmToCjs = (program, code, opts, containsTopLevelAwait) => {
+  const live = opts.liveBindings ?? 'strict';
+  const importTransforms = [];
+  const exportTransforms = [];
+  let needsInterop = false;
+  let importIndex = 0;
+  for (const node of program.body) {
+    if (node.type === 'ImportDeclaration') {
+      const srcLiteral = code.slice(node.source.start, node.source.end);
+      const specifiers = node.specifiers ?? [];
+      const defaultSpec = specifiers.find(s => s.type === 'ImportDefaultSpecifier');
+      const namespaceSpec = specifiers.find(s => s.type === 'ImportNamespaceSpecifier');
+      const namedSpecs = specifiers.filter(s => s.type === 'ImportSpecifier');
 
+      // Side-effect import
+      if (!specifiers.length) {
+        importTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `require(${srcLiteral});\n`,
+          needsInterop: false
+        });
+        continue;
+      }
+      const modIdent = `__mod${importIndex++}`;
+      const lines = [];
+      lines.push(`const ${modIdent} = require(${srcLiteral});`);
+      if (namespaceSpec) {
+        lines.push(`const ${namespaceSpec.local.name} = ${modIdent};`);
+      }
+      if (defaultSpec) {
+        let init = modIdent;
+        switch (opts.cjsDefault) {
+          case 'module-exports':
+            init = modIdent;
+            break;
+          case 'none':
+            init = `${modIdent}.default`;
+            break;
+          case 'auto':
+          default:
+            init = `${defaultInteropName}(${modIdent})`;
+            needsInterop = true;
+            break;
+        }
+        lines.push(`const ${defaultSpec.local.name} = ${init};`);
+      }
+      if (namedSpecs.length) {
+        const pairs = namedSpecs.map(s => {
+          const imported = s.imported.name;
+          const local = s.local.name;
+          return imported === local ? imported : `${imported}: ${local}`;
+        });
+        lines.push(`const { ${pairs.join(', ')} } = ${modIdent};`);
+      }
+      importTransforms.push({
+        start: node.start,
+        end: node.end,
+        code: `${lines.join('\n')}\n`,
+        needsInterop
+      });
+    }
+    if (node.type === 'ExportNamedDeclaration') {
+      // Handle declaration exports
+      if (node.declaration) {
+        const decl = node.declaration;
+        const declSrc = code.slice(decl.start, decl.end);
+        const exportedNames = [];
+        if (decl.type === 'VariableDeclaration') {
+          for (const d of decl.declarations) {
+            if (d.id.type === 'Identifier') {
+              exportedNames.push(d.id.name);
+            }
+          }
+        } else if (decl.id?.type === 'Identifier') {
+          exportedNames.push(decl.id.name);
+        }
+        const exportLines = exportedNames.map(name => exportAssignment(name, name, live));
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${declSrc}\n${exportLines.join('\n')}\n`
+        });
+        continue;
+      }
+
+      // Handle re-export or local specifiers
+      if (node.specifiers?.length) {
+        if (node.source) {
+          const srcLiteral = code.slice(node.source.start, node.source.end);
+          const modIdent = `__mod${importIndex++}`;
+          const lines = [`const ${modIdent} = require(${srcLiteral});`];
+          for (const spec of node.specifiers) {
+            if (spec.type !== 'ExportSpecifier') continue;
+            const exported = spec.exported.name;
+            const imported = spec.local.name;
+            let rhs = `${modIdent}.${imported}`;
+            if (imported === 'default') {
+              rhs = `${defaultInteropName}(${modIdent})`;
+              needsInterop = true;
+            }
+            lines.push(exportAssignment(exported, rhs, live));
+          }
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${lines.join('\n')}\n`,
+            needsInterop
+          });
+        } else {
+          const lines = [];
+          for (const spec of node.specifiers) {
+            if (spec.type !== 'ExportSpecifier') continue;
+            const exported = spec.exported.name;
+            const local = spec.local.name;
+            lines.push(exportAssignment(exported, local, live));
+          }
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${lines.join('\n')}\n`
+          });
+        }
+      }
+    }
+    if (node.type === 'ExportDefaultDeclaration') {
+      const decl = node.declaration;
+      const useExportsObject = containsTopLevelAwait && opts.topLevelAwait !== 'error';
+      if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
+        if (decl.id?.name) {
+          const declSrc = code.slice(decl.start, decl.end);
+          const assign = useExportsObject ? `exports.default = ${decl.id.name};` : `module.exports = ${decl.id.name};`;
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${declSrc}\n${assign}\n`
+          });
+        } else {
+          const declSrc = code.slice(decl.start, decl.end);
+          const assign = useExportsObject ? `exports.default = ${declSrc};` : `module.exports = ${declSrc};`;
+          exportTransforms.push({
+            start: node.start,
+            end: node.end,
+            code: `${assign}\n`
+          });
+        }
+      } else {
+        const exprSrc = code.slice(decl.start, decl.end);
+        const assign = useExportsObject ? `exports.default = ${exprSrc};` : `module.exports = ${exprSrc};`;
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${assign}\n`
+        });
+      }
+    }
+    if (node.type === 'ExportAllDeclaration') {
+      const srcLiteral = code.slice(node.source.start, node.source.end);
+      if (node.exported) {
+        const exported = node.exported.name;
+        const modIdent = `__mod${importIndex++}`;
+        const lines = [`const ${modIdent} = require(${srcLiteral});`, exportAssignment(exported, modIdent, live)];
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${lines.join('\n')}\n`
+        });
+      } else {
+        const modIdent = `__mod${importIndex++}`;
+        const lines = [`const ${modIdent} = require(${srcLiteral});`];
+        const loop = `for (const k in ${modIdent}) {\n  if (k === 'default') continue;\n  if (!Object.prototype.hasOwnProperty.call(${modIdent}, k)) continue;\n  Object.defineProperty(exports, k, { enumerable: true, get: () => ${modIdent}[k] });\n}`;
+        lines.push(loop);
+        exportTransforms.push({
+          start: node.start,
+          end: node.end,
+          code: `${lines.join('\n')}\n`
+        });
+      }
+    }
+  }
+  return {
+    importTransforms,
+    exportTransforms,
+    needsInterop
+  };
+};
 /**
  * Node added support for import.meta.main.
  * Added in: v24.2.0, v22.18.0
@@ -24,6 +257,13 @@ const format = async (src, ast, opts) => {
   };
   const exportTable = opts.target === 'module' ? await collectCjsExports(ast.program) : null;
   await collectModuleIdentifiers(ast.program);
+  const shouldCheckTopLevelAwait = opts.target === 'commonjs' && opts.transformSyntax;
+  const containsTopLevelAwait = shouldCheckTopLevelAwait ? hasTopLevelAwait(ast.program) : false;
+  const shouldLowerCjs = opts.target === 'commonjs' && opts.transformSyntax;
+  let pendingCjsTransforms = null;
+  if (shouldLowerCjs && opts.topLevelAwait === 'error' && containsTopLevelAwait) {
+    throw new Error('Top-level await is not supported when targeting CommonJS (set topLevelAwait to "wrap" or "preserve" to override).');
+  }
   if (opts.target === 'module' && opts.transformSyntax) {
     /**
      * Prepare ESM output by renaming `exports` to `__exports` and seeding an
@@ -108,6 +348,25 @@ void import.meta.filename;
       }
     }
   });
+  if (shouldLowerCjs) {
+    const {
+      importTransforms,
+      exportTransforms,
+      needsInterop
+    } = lowerEsmToCjs(ast.program, code, opts, containsTopLevelAwait);
+    pendingCjsTransforms = {
+      transforms: [...importTransforms, ...exportTransforms].sort((a, b) => a.start - b.start),
+      needsInterop
+    };
+  }
+  if (pendingCjsTransforms) {
+    for (const t of pendingCjsTransforms.transforms) {
+      code.overwrite(t.start, t.end, t.code);
+    }
+    if (pendingCjsTransforms.needsInterop) {
+      code.prepend(`${interopHelper}exports.__esModule = true;\n`);
+    }
+  }
   if (opts.target === 'module' && opts.transformSyntax && exportTable) {
     const isValidExportName = name => /^[$A-Z_a-z][$\w]*$/.test(name);
     const asExportName = name => isValidExportName(name) ? name : JSON.stringify(name);
@@ -137,6 +396,16 @@ void import.meta.filename;
       code.append(`\n${lines.join('\n')}\n`);
     }
   }
+  if (opts.target === 'commonjs' && opts.transformSyntax && containsTopLevelAwait) {
+    const body = code.toString();
+    if (opts.topLevelAwait === 'wrap') {
+      const tlaPromise = `const __tla = (async () => {\n${body}\nreturn module.exports;\n})();\n`;
+      const setPromise = `const __setTla = target => {\n  if (!target) return;\n  const type = typeof target;\n  if (type !== 'object' && type !== 'function') return;\n  target.__tla = __tla;\n};\n`;
+      const attach = `__setTla(module.exports);\n__tla.then(resolved => __setTla(resolved), err => { throw err; });\n`;
+      return `${tlaPromise}${setPromise}${attach}`;
+    }
+    return `;(async () => {\n${body}\n})();\n`;
+  }
   return code.toString();
 };
 export { format };

package/dist/formatters/metaProperty.js

@@ -1,3 +1,16 @@
+const importMetaMainSupport = '(() => { const [__nmaj, __nmin] = process.versions.node.split(".").map(n => parseInt(n, 10) || 0); return (__nmaj > 24 || (__nmaj === 24 && __nmin >= 2) || (__nmaj === 22 && __nmin >= 18)); })()';
+const importMetaMainShim = 'process.argv[1] === __filename';
+const importMetaMainExpr = mode => {
+  switch (mode) {
+    case 'warn':
+      return `(${importMetaMainSupport} ? ${importMetaMainShim} : (console.warn("import.meta.main is not supported before Node 22.18/24.2; falling back to shim."), ${importMetaMainShim}))`;
+    case 'error':
+      return `(${importMetaMainSupport} ? ${importMetaMainShim} : (() => { throw new Error("import.meta.main is not supported before Node 22.18/24.2"); })())`;
+    case 'shim':
+    default:
+      return importMetaMainShim;
+  }
+};
 export const metaProperty = (node, parent, src, options) => {
   if (options.target === 'commonjs') {
     if (parent?.type !== 'MemberExpression') {
@@ -21,10 +34,15 @@ export const metaProperty = (node, parent, src, options) => {
           break;
         case 'resolve':
           /**
-           * Should this be `require('node:url').pathToFileURL(require.resolve(<parsed specifier>)).href`?
+           * Map to require.resolve intentionally: matches CJS resolution semantics.
+           * Wrapping in pathToFileURL(...) would change the return shape (URL string)
+           * without truly emulating ESM import.meta.resolve rules.
            */
           src.update(parent.start, parent.end, 'require.resolve');
           break;
+        case 'main':
+          src.update(parent.start, parent.end, importMetaMainExpr(options.importMetaMain));
+          break;
       }
     }
   }

package/dist/module.js

@@ -12,6 +12,7 @@ const defaultOptions = {
   rewriteSpecifier: undefined,
   dirFilename: 'inject',
   importMeta: 'shim',
+  importMetaMain: 'shim',
   requireSource: 'builtin',
   cjsDefault: 'auto',
   topLevelAwait: 'error',

package/dist/src/types.d.ts

@@ -8,6 +8,7 @@ export type ModuleOptions = {
     rewriteSpecifier?: RewriteSpecifier;
     dirFilename?: 'inject' | 'preserve' | 'error';
     importMeta?: 'preserve' | 'shim' | 'error';
+    importMetaMain?: 'shim' | 'warn' | 'error';
     requireSource?: 'builtin' | 'create-require';
     cjsDefault?: 'module-exports' | 'auto' | 'none';
     topLevelAwait?: 'error' | 'wrap' | 'preserve';

package/dist/types.d.ts

@@ -8,6 +8,7 @@ export type ModuleOptions = {
     rewriteSpecifier?: RewriteSpecifier;
     dirFilename?: 'inject' | 'preserve' | 'error';
     importMeta?: 'preserve' | 'shim' | 'error';
+    importMetaMain?: 'shim' | 'warn' | 'error';
     requireSource?: 'builtin' | 'create-require';
     cjsDefault?: 'module-exports' | 'auto' | 'none';
     topLevelAwait?: 'error' | 'wrap' | 'preserve';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/module",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Transforms differences between ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",