@knighted/module 1.0.0 → 1.1.0

package/README.md

@@ -130,7 +130,9 @@ type ModuleOptions = {
   requireMainStrategy?: 'import-meta-main' | 'realpath'
   detectCircularRequires?: 'off' | 'warn' | 'error'
   requireSource?: 'builtin' | 'create-require'
+  importMetaPrelude?: 'off' | 'auto' | 'on'
   cjsDefault?: 'module-exports' | 'auto' | 'none'
+  idiomaticExports?: 'off' | 'safe' | 'aggressive'
   topLevelAwait?: 'error' | 'wrap' | 'preserve'
   out?: string
   inPlace?: boolean
@@ -149,11 +151,13 @@ type ModuleOptions = {
 - `importMeta` (`shim`): rewrite `import.meta.*` to CommonJS equivalents.
 - `importMetaMain` (`shim`): gate `import.meta.main` with shimming/warning/error when Node support is too old.
 - `requireMainStrategy` (`import-meta-main`): use `import.meta.main` or the realpath-based `pathToFileURL(realpathSync(process.argv[1])).href` check.
+- `importMetaPrelude` (`auto`): emit a no-op `void import.meta.filename;` touch. `on` always emits; `off` never emits; `auto` emits only when helpers that reference `import.meta.*` are synthesized (e.g., `__dirname`/`__filename` in CJS→ESM, require-main shims, createRequire helpers). Useful for bundlers/transpilers that do usage-based `import.meta` polyfilling.
 - `detectCircularRequires` (`off`): optionally detect relative static require cycles and warn/throw.
 - `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. Precedence: the callback (if provided) runs first; if it returns a string, that wins. If it returns `undefined` or `null`, the appenders still apply.
 - `requireSource` (`builtin`): whether `require` comes from Node or `createRequire`.
 - `cjsDefault` (`auto`): bundler-style default interop vs direct `module.exports`.
+- `idiomaticExports` (`safe`): when raising CJS to ESM, attempt to synthesize `export` statements directly when it is safe. `off` always uses the helper bag; `aggressive` currently matches `safe` heuristics.
 - `out`/`inPlace`: write the transformed code to a file; otherwise the function returns the transformed string only.
 - CommonJS → ESM lowering will throw on `with` statements and unshadowed `eval` calls to avoid unsound rewrites.
 

package/dist/cjs/format.cjs

@@ -607,6 +607,8 @@ const format = async (src, ast, opts) => {
   let requireMainNeedsRealpath = false;
   let needsRequireResolveHelper = false;
   const nestedRequireStrategy = opts.nestedRequireStrategy ?? 'create-require';
+  const importMetaPreludeMode = opts.importMetaPrelude ?? 'auto';
+  let importMetaRef = false;
   const shouldLowerCjs = opts.target === 'commonjs' && fullTransform;
   const shouldRaiseEsm = opts.target === 'module' && fullTransform;
   let hoistedImports = [];
@@ -654,6 +656,10 @@ const format = async (src, ast, opts) => {
             const mainExpr = requireMainStrategy === 'import-meta-main' ? 'import.meta.main' : 'import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href';
             if (requireMainStrategy === 'realpath') {
               requireMainNeedsRealpath = true;
+              importMetaRef = true;
+            }
+            if (requireMainStrategy === 'import-meta-main') {
+              importMetaRef = true;
             }
             code.update(node.start, node.end, negate ? `!(${mainExpr})` : mainExpr);
             return;
@@ -772,6 +778,9 @@ const format = async (src, ast, opts) => {
         }
       }
       if ((0, _identifier2.isIdentifierName)(node)) {
+        if (shouldRaiseEsm && node.type === 'Identifier' && (node.name === '__dirname' || node.name === '__filename')) {
+          importMetaRef = true;
+        }
         (0, _identifier.identifier)({
           node,
           ancestors,
@@ -827,8 +836,14 @@ const format = async (src, ast, opts) => {
     const asExportName = name => isValidExportName(name) ? name : JSON.stringify(name);
     const accessProp = name => isValidExportName(name) ? `${_exports.exportsRename}.${name}` : `${_exports.exportsRename}[${JSON.stringify(name)}]`;
     const exportValueFor = name => {
-      if (name === '__dirname') return 'import.meta.dirname';
-      if (name === '__filename') return 'import.meta.filename';
+      if (name === '__dirname') {
+        importMetaRef = true;
+        return 'import.meta.dirname';
+      }
+      if (name === '__filename') {
+        importMetaRef = true;
+        return 'import.meta.filename';
+      }
       return name;
     };
     const tempNameFor = name => {
@@ -884,6 +899,9 @@ const format = async (src, ast, opts) => {
   }
   if (shouldRaiseEsm && fullTransform) {
     const importPrelude = [];
+    if (needsCreateRequire || needsRequireResolveHelper) {
+      importMetaRef = true;
+    }
     if (needsCreateRequire || needsRequireResolveHelper) {
       importPrelude.push('import { createRequire } from "node:module";\n');
     }
@@ -916,9 +934,13 @@ const format = async (src, ast, opts) => {
     const exportsBagInit = useExportsBag ? `let ${_exports.exportsRename} = {};
 ` : '';
     const modulePrelude = '';
-    const prelude = `${importPrelude.join('')}${importPrelude.length ? '\n' : ''}${setupPrelude.join('')}${setupPrelude.length ? '\n' : ''}${requireInit}${requireResolveInit}${exportsBagInit}${modulePrelude}void import.meta.filename;
-`;
-    code.prepend(prelude);
+    const prelude = `${importPrelude.join('')}${importPrelude.length ? '\n' : ''}${setupPrelude.join('')}${setupPrelude.length ? '\n' : ''}${requireInit}${requireResolveInit}${exportsBagInit}${modulePrelude}`;
+    const importMetaTouch = (() => {
+      if (importMetaPreludeMode === 'on') return 'void import.meta.filename;\n';
+      if (importMetaPreludeMode === 'off') return '';
+      return importMetaRef ? 'void import.meta.filename;\n' : '';
+    })();
+    code.prepend(`${prelude}${importMetaTouch}`);
   }
   if (opts.target === 'commonjs' && fullTransform && containsTopLevelAwait) {
     const body = code.toString();

package/dist/cjs/module.cjs

@@ -161,6 +161,7 @@ const defaultOptions = {
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
   idiomaticExports: 'safe',
+  importMetaPrelude: 'auto',
   topLevelAwait: 'error',
   out: undefined,
   inPlace: false

package/dist/cjs/types.d.cts

@@ -40,6 +40,8 @@ export type ModuleOptions = {
     cjsDefault?: 'module-exports' | 'auto' | 'none';
     /** Emit idiomatic exports when raising CJS to ESM. */
     idiomaticExports?: 'off' | 'safe' | 'aggressive';
+    /** Control whether a no-op import.meta prelude is emitted. */
+    importMetaPrelude?: 'off' | 'auto' | 'on';
     /** Handling for top-level await constructs. */
     topLevelAwait?: 'error' | 'wrap' | 'preserve';
     /** Optional diagnostics sink for warnings/errors emitted during transform. */

package/dist/format.js

@@ -600,6 +600,8 @@ const format = async (src, ast, opts) => {
   let requireMainNeedsRealpath = false;
   let needsRequireResolveHelper = false;
   const nestedRequireStrategy = opts.nestedRequireStrategy ?? 'create-require';
+  const importMetaPreludeMode = opts.importMetaPrelude ?? 'auto';
+  let importMetaRef = false;
   const shouldLowerCjs = opts.target === 'commonjs' && fullTransform;
   const shouldRaiseEsm = opts.target === 'module' && fullTransform;
   let hoistedImports = [];
@@ -647,6 +649,10 @@ const format = async (src, ast, opts) => {
             const mainExpr = requireMainStrategy === 'import-meta-main' ? 'import.meta.main' : 'import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href';
             if (requireMainStrategy === 'realpath') {
               requireMainNeedsRealpath = true;
+              importMetaRef = true;
+            }
+            if (requireMainStrategy === 'import-meta-main') {
+              importMetaRef = true;
             }
             code.update(node.start, node.end, negate ? `!(${mainExpr})` : mainExpr);
             return;
@@ -765,6 +771,9 @@ const format = async (src, ast, opts) => {
         }
       }
       if (isIdentifierName(node)) {
+        if (shouldRaiseEsm && node.type === 'Identifier' && (node.name === '__dirname' || node.name === '__filename')) {
+          importMetaRef = true;
+        }
         identifier({
           node,
           ancestors,
@@ -820,8 +829,14 @@ const format = async (src, ast, opts) => {
     const asExportName = name => isValidExportName(name) ? name : JSON.stringify(name);
     const accessProp = name => isValidExportName(name) ? `${exportsRename}.${name}` : `${exportsRename}[${JSON.stringify(name)}]`;
     const exportValueFor = name => {
-      if (name === '__dirname') return 'import.meta.dirname';
-      if (name === '__filename') return 'import.meta.filename';
+      if (name === '__dirname') {
+        importMetaRef = true;
+        return 'import.meta.dirname';
+      }
+      if (name === '__filename') {
+        importMetaRef = true;
+        return 'import.meta.filename';
+      }
       return name;
     };
     const tempNameFor = name => {
@@ -877,6 +892,9 @@ const format = async (src, ast, opts) => {
   }
   if (shouldRaiseEsm && fullTransform) {
     const importPrelude = [];
+    if (needsCreateRequire || needsRequireResolveHelper) {
+      importMetaRef = true;
+    }
     if (needsCreateRequire || needsRequireResolveHelper) {
       importPrelude.push('import { createRequire } from "node:module";\n');
     }
@@ -909,9 +927,13 @@ const format = async (src, ast, opts) => {
     const exportsBagInit = useExportsBag ? `let ${exportsRename} = {};
 ` : '';
     const modulePrelude = '';
-    const prelude = `${importPrelude.join('')}${importPrelude.length ? '\n' : ''}${setupPrelude.join('')}${setupPrelude.length ? '\n' : ''}${requireInit}${requireResolveInit}${exportsBagInit}${modulePrelude}void import.meta.filename;
-`;
-    code.prepend(prelude);
+    const prelude = `${importPrelude.join('')}${importPrelude.length ? '\n' : ''}${setupPrelude.join('')}${setupPrelude.length ? '\n' : ''}${requireInit}${requireResolveInit}${exportsBagInit}${modulePrelude}`;
+    const importMetaTouch = (() => {
+      if (importMetaPreludeMode === 'on') return 'void import.meta.filename;\n';
+      if (importMetaPreludeMode === 'off') return '';
+      return importMetaRef ? 'void import.meta.filename;\n' : '';
+    })();
+    code.prepend(`${prelude}${importMetaTouch}`);
   }
   if (opts.target === 'commonjs' && fullTransform && containsTopLevelAwait) {
     const body = code.toString();

package/dist/module.js

@@ -158,6 +158,7 @@ const defaultOptions = {
   nestedRequireStrategy: 'create-require',
   cjsDefault: 'auto',
   idiomaticExports: 'safe',
+  importMetaPrelude: 'auto',
   topLevelAwait: 'error',
   out: undefined,
   inPlace: false

package/dist/src/types.d.ts

@@ -40,6 +40,8 @@ export type ModuleOptions = {
     cjsDefault?: 'module-exports' | 'auto' | 'none';
     /** Emit idiomatic exports when raising CJS to ESM. */
     idiomaticExports?: 'off' | 'safe' | 'aggressive';
+    /** Control whether a no-op import.meta prelude is emitted. */
+    importMetaPrelude?: 'off' | 'auto' | 'on';
     /** Handling for top-level await constructs. */
     topLevelAwait?: 'error' | 'wrap' | 'preserve';
     /** Optional diagnostics sink for warnings/errors emitted during transform. */

package/dist/types.d.ts

@@ -40,6 +40,8 @@ export type ModuleOptions = {
     cjsDefault?: 'module-exports' | 'auto' | 'none';
     /** Emit idiomatic exports when raising CJS to ESM. */
     idiomaticExports?: 'off' | 'safe' | 'aggressive';
+    /** Control whether a no-op import.meta prelude is emitted. */
+    importMetaPrelude?: 'off' | 'auto' | 'on';
     /** Handling for top-level await constructs. */
     topLevelAwait?: 'error' | 'wrap' | 'preserve';
     /** Optional diagnostics sink for warnings/errors emitted during transform. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/module",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Bidirectional transform for ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",