feat: better tla import.meta.main.

Author: knightedcodemonkey

docs/esm-to-cjs.md

@@ -5,6 +5,8 @@
 - Translates ESM syntax to CommonJS when `target: 'commonjs'` with `transformSyntax` enabled.
 - Assumes Node 20.11+ runtime with `__filename`/`__dirname` shims supplied by the host.
 - Keeps optional live-binding behavior via `liveBindings` (strict/loose/off).
+- Top-level await (TLA) handling is controlled by `topLevelAwait: 'error' | 'wrap' | 'preserve'` when lowering to CommonJS.
+- Optional import.meta.main gating via `importMetaMain: 'shim' | 'warn' | 'error'`.
 
 ## Imports and interop
 
@@ -14,20 +16,28 @@
 - Re-exporting a default (`export { default as x } from`) routes through the interop helper to match bundler behavior for CJS sources.
 - When the interop helper is emitted, `exports.__esModule = true` is also seeded for downstream consumers.
 
-## Exports
+## Exports and live bindings
 
-- Local named exports emit to `exports.<name>` (or bracket access) with `Object.defineProperty` getters when `liveBindings: 'strict'`.
-- `export default` writes to `module.exports = <expr>`; default functions/classes preserve their identifier before exporting.
+- Local named exports emit to `exports.<name>` (or bracket access) with `Object.defineProperty` getters when `liveBindings: 'strict'`; snapshot assignment is used for `loose`/`off`.
+- `export default` writes to `module.exports = <expr>` in the common case; when TLA is present and allowed (`wrap`/`preserve`), default exports write to `exports.default = <expr>` so the exports object stays stable for async wrapping.
 - `export * from` lowers to a `for...in` over the required module, skipping `default`, guarding on `hasOwnProperty`, and defining getters to mirror live bindings.
-- Named re-exports from another module (`export { foo as bar } from`) assign using either a direct property read or the interop helper for `default`.
+- Named re-exports from another module (`export { foo as bar } from`) use getters when `liveBindings: 'strict'`, otherwise snapshot assignment; `default` re-exports still use the interop helper.
+
+## Top-level await
+
+- `topLevelAwait: 'error'` (default) throws during transform when a TLA is found while targeting CommonJS.
+- `topLevelAwait: 'wrap'` wraps the entire CJS output in `const __tla = (async () => { ...; return module.exports; })();` and attaches `__tla` to both `module.exports` and the resolved value. Consumers can await `require('./file').__tla` for readiness.
+- `topLevelAwait: 'preserve'` runs the lowered code inside an immediately-invoked async function but does not attach a promise; consumers must rely on the natural scheduling of async effects.
+- In both allowed modes, default exports write to `exports.default` instead of replacing `module.exports` to keep the exports object consistent while async initialization completes.
+- Fixture: `test/fixtures/topLevelAwait.mjs` plus tests in `test/module.ts` cover both `wrap` and `preserve` behaviors.
 
 ## import.meta rewriting
 
 - `import.meta.url` → `require("node:url").pathToFileURL(__filename).href`
 - `import.meta.filename` → `__filename`
 - `import.meta.dirname` → `__dirname`
 - `import.meta.resolve` → `require.resolve`
-- `import.meta.main` → `process.argv[1] === __filename`
+- `import.meta.main` → configurable: default shim to `process.argv[1] === __filename`; with `importMetaMain: 'warn'` a warning is embedded for Node <22.18/24.2; with `importMetaMain: 'error'` the transform throws on those runtimes.
 - Bare `import.meta` becomes `module` so property accesses stay valid in CJS output.
 
 ## Fixtures for this phase
@@ -36,4 +46,5 @@
 - `test/fixtures/esmNamed.mjs`: named import and aliasing from the CJS provider, re-exported for assertions.
 - `test/fixtures/esmNamespace.mjs`: namespace import shape from the CJS provider, re-exported as `ns`.
 - `test/fixtures/esmReexport.mjs`: named + star re-exports from the CJS provider (includes live binding passthrough).
+- `test/fixtures/liveReexport.mjs`: re-export from a mutating CJS source; exercised when `liveBindings: 'strict'` to verify getter-based live bindings.
 - `test/fixtures/esmProvider.cjs`: CJS source exposing default/named exports plus a mutating `live` counter for binding checks (interval is `unref()`ed; tests wait ≥30ms to observe changes).

src/format.ts

@@ -74,7 +74,12 @@ const hasTopLevelAwait = (program: any) => {
   return found
 }
 
-const lowerEsmToCjs = (program: any, code: MagicString, opts: FormatterOptions) => {
+const lowerEsmToCjs = (
+  program: any,
+  code: MagicString,
+  opts: FormatterOptions,
+  containsTopLevelAwait: boolean,
+) => {
   const live = opts.liveBindings ?? 'strict'
   const importTransforms: ImportTransform[] = []
   const exportTransforms: ExportTransform[] = []
@@ -221,28 +226,38 @@ const lowerEsmToCjs = (program: any, code: MagicString, opts: FormatterOptions)
 
     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}\nmodule.exports = ${decl.id.name};\n`,
+            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: `module.exports = ${declSrc};\n`,
+            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: `module.exports = ${exprSrc};\n`,
+          code: `${assign}\n`,
         })
       }
     }
@@ -308,32 +323,21 @@ const format = async (src: string, ast: ParseResult, opts: FormatterOptions) =>
   const exportTable =
     opts.target === 'module' ? await collectCjsExports(ast.program) : null
   await collectModuleIdentifiers(ast.program)
-
-  if (opts.target === 'commonjs' && opts.transformSyntax) {
-    if (opts.topLevelAwait === 'error' && hasTopLevelAwait(ast.program)) {
-      throw new Error(
-        'Top-level await is not supported when targeting CommonJS (set topLevelAwait to "wrap" or "preserve" to override).',
-      )
-    }
-
-    const { importTransforms, exportTransforms, needsInterop } = lowerEsmToCjs(
-      ast.program,
-      code,
-      opts,
+  const shouldCheckTopLevelAwait = opts.target === 'commonjs' && opts.transformSyntax
+  const containsTopLevelAwait = shouldCheckTopLevelAwait
+    ? hasTopLevelAwait(ast.program)
+    : false
+
+  const shouldLowerCjs = opts.target === 'commonjs' && opts.transformSyntax
+  let pendingCjsTransforms: {
+    transforms: Array<ImportTransform | ExportTransform>
+    needsInterop: boolean
+  } | null = 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).',
     )
-
-    // Apply transforms in source order
-    const allTransforms = [...importTransforms, ...exportTransforms].sort(
-      (a, b) => a.start - b.start,
-    )
-
-    for (const t of allTransforms) {
-      code.overwrite(t.start, t.end, t.code)
-    }
-
-    if (needsInterop) {
-      code.prepend(`${interopHelper}exports.__esModule = true;\n`)
-    }
   }
 
   if (opts.target === 'module' && opts.transformSyntax) {
@@ -456,6 +460,32 @@ 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: string) => /^[$A-Z_a-z][$\w]*$/.test(name)
     const asExportName = (name: string) =>
@@ -495,6 +525,19 @@ void import.meta.filename;
     }
   }
 
+  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()
 }
 

src/formatters/metaProperty.ts

@@ -3,6 +3,22 @@ import type { Node, MetaProperty } from 'oxc-parser'
 
 import type { FormatterOptions } from '../types.js'
 
+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: FormatterOptions['importMetaMain']) => {
+  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: MetaProperty,
   parent: Node | null,
@@ -34,12 +50,14 @@ export const metaProperty = (
           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, 'process.argv[1] === __filename')
+          src.update(parent.start, parent.end, importMetaMainExpr(options.importMetaMain))
           break
       }
     }

src/module.ts

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

src/types.ts

@@ -25,6 +25,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'

test/fixtures/import.meta.main.mjs

@@ -0,0 +1 @@
+export const isMain = import.meta.main

test/fixtures/liveReexport.mjs

@@ -0,0 +1 @@
+export { counter, bump } from './liveSource.cjs'

test/fixtures/liveSource.cjs

@@ -0,0 +1,16 @@
+let counter = 0
+
+const bump = () => {
+  counter += 1
+}
+
+setTimeout(() => {
+  counter += 1
+}, 20)
+
+module.exports = {
+  get counter() {
+    return counter
+  },
+  bump,
+}

test/fixtures/topLevelAwait.mjs

@@ -0,0 +1,5 @@
+const first = await Promise.resolve(2)
+const second = await new Promise(resolve => setTimeout(() => resolve(3), 5))
+
+export const value = first + second
+export default second