@knighted/module 1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 KCM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# [`@knighted/module`](https://www.npmjs.com/package/@knighted/module)
+
+![CI](https://github.com/knightedcodemonkey/module/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/knightedcodemonkey/module/graph/badge.svg?token=AjayQQxghy)](https://codecov.io/gh/knightedcodemonkey/module)
+[![NPM version](https://img.shields.io/npm/v/@knighted/module.svg)](https://www.npmjs.com/package/@knighted/module)
+
+Node.js utility for transforming JavaScript or TypeScript files from one module system to another.
+
+- ES module ➡️ CommonJS
+- CommonJS ➡️ ES module
+
+By default `@knighted/module` transforms globals from one module scope to another and returns the modified source, but it accepts options that allow
+
+- Module loading transforms, i.e, `import`/`export` converted to `require`/`exports`
+- Extensions to be updated in relative specifiers
+- Write transformed source code to a filename
+
+## Requirements
+
+- Node >= 20.11.0
+
+## Example
+
+Given an ES module
+
+**file.js**
+
+```js
+import { argv } from 'node:process'
+import { pathToFileURL } from 'node:url'
+import { realpath } from 'node:fs/promises'
+
+const detectCalledFromCli = async path => {
+  const realPath = await realpath(path)
+
+  if (import.meta.url === pathToFileURL(realPath).href) {
+    console.log('invoked directly by node')
+  }
+}
+
+detectCalledFromCli(argv[1])
+```
+
+You can use transform it to the equivalent CommonJS module
+
+```js
+import { transform } from '@knighted/module'
+
+await transform('./file.js', {
+  type: 'commonjs'
+  moduleLoading: true,
+  out: './file.cjs'
+})
+```
+
+Which produces
+
+**file.js**
+
+```js
+const { argv } = require('node:process')
+const { pathToFileURL } = require('node:url')
+const { realpath } = require('node:fs/promises')
+
+const detectCalledFromCli = async path => {
+  const realPath = await realpath(path)
+
+  if (require('node:url').pathToFileURL(__filename).toString() === pathToFileURL(realPath).href) {
+    console.log('invoked directly by node')
+  }
+}
+
+detectCalledFromCli(argv[1])
+```
+
+When executed from the CLI
+
+```console
+use@computer: $ node file.cjs
+invoked directly by node
+```
+
+## Options
+
+```ts
+type ModuleOptions = {
+  /* What module system to convert to. */
+  type?: 'module' | 'commonjs'
+  /* Whether import/export and require/exports should be transformed. */
+  moduleLoading?: boolean
+  /* Whether to change specifier extensions to the assigned value. If omitted they are left alone. */
+  specifiers?: '.js' | '.mjs' | '.cjs' | '.ts' | '.mts' | '.cts'
+  /* What filepath to write the transformed source to. If omitted the transformed source is returned. */
+  out?: string
+}
+```

package/dist/cjs/format.cjs

@@ -0,0 +1,89 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.format = void 0;
+var _magicString = _interopRequireDefault(require("magic-string"));
+var _traverse2 = _interopRequireDefault(require("@babel/traverse"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const traverse = _traverse2.default.default;
+const format = (code, ast, options) => {
+  const src = new _magicString.default(code);
+  const {
+    type = 'commonjs'
+  } = options;
+  traverse(ast, {
+    MetaProperty(metaPropertyPath) {
+      if (type === 'commonjs') {
+        const path = metaPropertyPath.findParent(path => path.isMemberExpression());
+        if (path) {
+          const {
+            node
+          } = path;
+          const {
+            start,
+            end
+          } = node;
+          if (node.type === 'MemberExpression' && node.property.type === 'Identifier' && typeof start == 'number' && typeof end === 'number') {
+            const name = node.property.name;
+            switch (name) {
+              case 'url':
+                src.update(start, end, 'require("node:url").pathToFileURL(__filename).toString()');
+                break;
+              case 'filename':
+                src.update(start, end, '__filename');
+                break;
+              case 'dirname':
+                src.update(start, end, '__dirname');
+                break;
+              case 'resolve':
+                src.update(start, end, 'require.resolve');
+                break;
+            }
+          }
+        }
+      }
+    },
+    ExpressionStatement(expressionStatementPath) {
+      if (type === 'module') {
+        const {
+          node
+        } = expressionStatementPath;
+        const {
+          start,
+          end
+        } = node;
+        if (node.expression.type === 'Identifier' && typeof start === 'number' && typeof end === 'number') {
+          const name = node.expression.name;
+          switch (name) {
+            case '__filename':
+              src.update(start, end, 'import.meta.filename');
+              break;
+            case '__dirname':
+              src.update(start, end, 'import.meta.dirname');
+              break;
+          }
+        }
+      }
+    },
+    MemberExpression(memberExpressionPath) {
+      if (type === 'module') {
+        const {
+          node
+        } = memberExpressionPath;
+        const {
+          start,
+          end
+        } = node;
+
+        // Update require.resolve to import.meta.resolve
+        if (node.object.type === 'Identifier' && node.object.name === 'require' && node.property.type === 'Identifier' && node.property.name == 'resolve' && typeof start === 'number' && typeof end === 'number') {
+          src.update(start, end, 'import.meta.resolve');
+        }
+      }
+    }
+  });
+  return src;
+};
+exports.format = format;

package/dist/cjs/format.d.cts

@@ -0,0 +1,7 @@
+import MagicString from 'magic-string';
+import type { ParseResult } from '@babel/parser';
+import type { File } from '@babel/types';
+import type { ModuleOptions } from './types.cjs';
+type FormatOptions = Omit<ModuleOptions, 'out'>;
+export declare const format: (code: string, ast: ParseResult<File>, options: FormatOptions) => MagicString;
+export {};

package/dist/cjs/module.cjs

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.transform = void 0;
+var _nodePath = require("node:path");
+var _promises = require("node:fs/promises");
+var _parse = require("./parse.cjs");
+var _format = require("./format.cjs");
+const defaultOptions = {
+  type: 'commonjs',
+  out: undefined,
+  moduleLoading: false,
+  specifiers: undefined
+};
+
+/**
+ * Transforms a file from one Node.js module system to another based on options.
+ * Module globals, for example import.meta, __dirname, __filename, etc. are always transformed.
+ * However, the CommonJS `module` object is not transformed, for instance `module.path`, `module.children`, etc.,
+ * with the exception of `module.exports` which is converted when `loading` is set to `true`.
+ */
+const transform = async (filename, options = defaultOptions) => {
+  const opts = {
+    ...defaultOptions,
+    ...options
+  };
+  const file = (0, _nodePath.resolve)(filename);
+  const code = (await (0, _promises.readFile)(file)).toString();
+  const ast = (0, _parse.parse)(code);
+  return (0, _format.format)(code, ast, opts).toString();
+};
+exports.transform = transform;

package/dist/cjs/module.d.cts

@@ -0,0 +1,9 @@
+import type { ModuleOptions } from './types.cjs';
+/**
+ * Transforms a file from one Node.js module system to another based on options.
+ * Module globals, for example import.meta, __dirname, __filename, etc. are always transformed.
+ * However, the CommonJS `module` object is not transformed, for instance `module.path`, `module.children`, etc.,
+ * with the exception of `module.exports` which is converted when `loading` is set to `true`.
+ */
+declare const transform: (filename: string, options?: ModuleOptions) => Promise<string>;
+export { transform };

package/dist/cjs/parse.cjs

@@ -0,0 +1,22 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.parse = void 0;
+var _parser = require("@babel/parser");
+const parse = (source, dts = false) => {
+  const ast = (0, _parser.parse)(source, {
+    sourceType: 'module',
+    allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true,
+    allowImportExportEverywhere: true,
+    plugins: ['jsx', ['importAttributes', {
+      deprecatedAssertSyntax: true
+    }], ['typescript', {
+      dts
+    }]]
+  });
+  return ast;
+};
+exports.parse = parse;

package/dist/cjs/parse.d.cts

@@ -0,0 +1,2 @@
+declare const parse: (source: string, dts?: boolean) => import("@babel/parser").ParseResult<import("@babel/types").File>;
+export { parse };

package/dist/cjs/types.cjs

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/dist/cjs/types.d.cts

@@ -0,0 +1,6 @@
+export type ModuleOptions = {
+    type?: 'module' | 'commonjs';
+    moduleLoading?: boolean;
+    specifiers?: '.js' | '.mjs' | '.cjs' | '.ts' | '.mts' | '.cts';
+    out?: string;
+};

package/dist/format.d.ts

@@ -0,0 +1,7 @@
+import MagicString from 'magic-string';
+import type { ParseResult } from '@babel/parser';
+import type { File } from '@babel/types';
+import type { ModuleOptions } from './types.js';
+type FormatOptions = Omit<ModuleOptions, 'out'>;
+export declare const format: (code: string, ast: ParseResult<File>, options: FormatOptions) => MagicString;
+export {};

package/dist/format.js

@@ -0,0 +1,81 @@
+import MagicString from 'magic-string';
+import _traverse from '@babel/traverse';
+const traverse = _traverse.default;
+export const format = (code, ast, options) => {
+  const src = new MagicString(code);
+  const {
+    type = 'commonjs'
+  } = options;
+  traverse(ast, {
+    MetaProperty(metaPropertyPath) {
+      if (type === 'commonjs') {
+        const path = metaPropertyPath.findParent(path => path.isMemberExpression());
+        if (path) {
+          const {
+            node
+          } = path;
+          const {
+            start,
+            end
+          } = node;
+          if (node.type === 'MemberExpression' && node.property.type === 'Identifier' && typeof start == 'number' && typeof end === 'number') {
+            const name = node.property.name;
+            switch (name) {
+              case 'url':
+                src.update(start, end, 'require("node:url").pathToFileURL(__filename).toString()');
+                break;
+              case 'filename':
+                src.update(start, end, '__filename');
+                break;
+              case 'dirname':
+                src.update(start, end, '__dirname');
+                break;
+              case 'resolve':
+                src.update(start, end, 'require.resolve');
+                break;
+            }
+          }
+        }
+      }
+    },
+    ExpressionStatement(expressionStatementPath) {
+      if (type === 'module') {
+        const {
+          node
+        } = expressionStatementPath;
+        const {
+          start,
+          end
+        } = node;
+        if (node.expression.type === 'Identifier' && typeof start === 'number' && typeof end === 'number') {
+          const name = node.expression.name;
+          switch (name) {
+            case '__filename':
+              src.update(start, end, 'import.meta.filename');
+              break;
+            case '__dirname':
+              src.update(start, end, 'import.meta.dirname');
+              break;
+          }
+        }
+      }
+    },
+    MemberExpression(memberExpressionPath) {
+      if (type === 'module') {
+        const {
+          node
+        } = memberExpressionPath;
+        const {
+          start,
+          end
+        } = node;
+
+        // Update require.resolve to import.meta.resolve
+        if (node.object.type === 'Identifier' && node.object.name === 'require' && node.property.type === 'Identifier' && node.property.name == 'resolve' && typeof start === 'number' && typeof end === 'number') {
+          src.update(start, end, 'import.meta.resolve');
+        }
+      }
+    }
+  });
+  return src;
+};

package/dist/module.d.ts

@@ -0,0 +1,9 @@
+import type { ModuleOptions } from './types.js';
+/**
+ * Transforms a file from one Node.js module system to another based on options.
+ * Module globals, for example import.meta, __dirname, __filename, etc. are always transformed.
+ * However, the CommonJS `module` object is not transformed, for instance `module.path`, `module.children`, etc.,
+ * with the exception of `module.exports` which is converted when `loading` is set to `true`.
+ */
+declare const transform: (filename: string, options?: ModuleOptions) => Promise<string>;
+export { transform };

package/dist/module.js

@@ -0,0 +1,28 @@
+import { resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { parse } from './parse.js';
+import { format } from './format.js';
+const defaultOptions = {
+  type: 'commonjs',
+  out: undefined,
+  moduleLoading: false,
+  specifiers: undefined
+};
+
+/**
+ * Transforms a file from one Node.js module system to another based on options.
+ * Module globals, for example import.meta, __dirname, __filename, etc. are always transformed.
+ * However, the CommonJS `module` object is not transformed, for instance `module.path`, `module.children`, etc.,
+ * with the exception of `module.exports` which is converted when `loading` is set to `true`.
+ */
+const transform = async (filename, options = defaultOptions) => {
+  const opts = {
+    ...defaultOptions,
+    ...options
+  };
+  const file = resolve(filename);
+  const code = (await readFile(file)).toString();
+  const ast = parse(code);
+  return format(code, ast, opts).toString();
+};
+export { transform };

package/dist/parse.d.ts

@@ -0,0 +1,2 @@
+declare const parse: (source: string, dts?: boolean) => import("@babel/parser").ParseResult<import("@babel/types").File>;
+export { parse };

package/dist/parse.js

@@ -0,0 +1,16 @@
+import { parse as babelParse } from '@babel/parser';
+const parse = (source, dts = false) => {
+  const ast = babelParse(source, {
+    sourceType: 'module',
+    allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true,
+    allowImportExportEverywhere: true,
+    plugins: ['jsx', ['importAttributes', {
+      deprecatedAssertSyntax: true
+    }], ['typescript', {
+      dts
+    }]]
+  });
+  return ast;
+};
+export { parse };

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+export type ModuleOptions = {
+    type?: 'module' | 'commonjs';
+    moduleLoading?: boolean;
+    specifiers?: '.js' | '.mjs' | '.cjs' | '.ts' | '.mts' | '.cts';
+    out?: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@knighted/module",
+  "version": "1.0.0-alpha.0",
+  "description": "Converts module differences in source files between ES and CommonJS.",
+  "type": "module",
+  "main": "dist/module.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types.d.ts",
+        "default": "./dist/module.js"
+      },
+      "require": {
+        "types": "./dist/cjs/types.d.cts",
+        "default": "./dist/cjs/module.cjs"
+      },
+      "default": "./dist/module.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "engineStrict": true,
+  "scripts": {
+    "prettier": "prettier -w .",
+    "lint": "eslint --ignore-pattern dist .",
+    "test": "c8 --reporter=text --reporter=text-summary --reporter=lcov tsx --test --test-reporter=spec test/*.ts",
+    "build:types": "tsc --emitDeclarationOnly",
+    "build:dual": "babel-dual-package src --extensions .ts",
+    "build": "npm run build:types && npm run build:dual",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "transform",
+    "es module",
+    "commonjs",
+    "module",
+    "require",
+    "import.meta",
+    "__dirname",
+    "__filename",
+    "conversion",
+    "tool",
+    "build"
+  ],
+  "files": [
+    "dist"
+  ],
+  "author": "KCM <knightedcodemonkey@gmail.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@babel/preset-env": "^7.24.6",
+    "@babel/preset-typescript": "^7.24.6",
+    "@babel/types": "^7.24.6",
+    "@eslint/js": "^9.3.0",
+    "@types/babel__traverse": "^7.20.6",
+    "@types/node": "^20.12.12",
+    "babel-dual-package": "^1.1.3",
+    "c8": "^9.1.0",
+    "eslint": "^9.3.0",
+    "eslint-plugin-n": "^17.7.0",
+    "prettier": "^3.2.5",
+    "tsx": "^4.11.0",
+    "typescript": "^5.4.5",
+    "typescript-eslint": "^8.0.0-alpha.16"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.24.6",
+    "@babel/traverse": "^7.24.6",
+    "magic-string": "^0.30.10"
+  },
+  "prettier": {
+    "arrowParens": "avoid",
+    "printWidth": 119,
+    "semi": false,
+    "singleQuote": true
+  }
+}