feat: js-import generator

Author: pi0

docs/2.generators/js-import.md

@@ -0,0 +1,56 @@
+# js-import
+
+The `js-import` generator generates JavaScript usage example to be imported.
+
+<!-- automd:example cjs cdn generator=js-import name=pkg imports="foo,bar" -->
+
+## Example
+
+### Input
+
+    <!-- automd:js-import cjs=true cdn=true name=pkg imports=foo,bar -->
+    <!-- /automd -->
+
+### Output
+
+    <!-- automd:js-import cjs=true cdn=true name=pkg imports=foo,bar -->
+    
+    **ESM** (Node.js, Bun)
+    
+    ```js
+    import {
+      foo,
+      bar,
+    } from "pkg";
+    ```
+    
+    **CommonJS** (Legacy Node.js)
+    
+    ```js
+    const {
+      foo,
+      bar,
+    } = require("pkg");
+    ```
+    
+    **CDN** (Deno, Bun and Browsers)
+    
+    ```js
+    import {
+      foo,
+      bar,
+    } from "https://esm.sh/pkg";
+    ```
+    
+    <!-- /automd -->
+
+<!-- /automd -->
+
+## Arguments
+
+- `name`: The package name (by default tries to read from the `name` field in `package.json`).
+- `import`/`imports`: Array or comma seperated list of export names.
+- `no-esm`: Disable ESM instructions.
+- `cdn`: Generate CDN import usage.
+- `cjs`: Generate CommonJS require usage.
+- `src`: Auto scan export names from src using [unjs/mlly](https://mlly.unjs.io).

package.json

@@ -43,6 +43,7 @@
     "didyoumean2": "^6.0.1",
     "globby": "^14.0.1",
     "magic-string": "^0.30.7",
+    "mlly": "^1.5.0",
     "ofetch": "^1.3.3",
     "omark": "^0.1.0",
     "pathe": "^1.1.2",

pnpm-lock.yaml

@@ -3,12 +3,14 @@ import { jsdocs } from "./jsdocs";
 import { badges } from "./badges";
 import { pmX, pmInstall } from "./pm";
 import { fetch as _fetch } from "./fetch";
-
+import { jsimport } from "./jsimport";
 export default {
   jsdocs,
   badges,
   "pm-i": pmInstall,
   "pm-install": pmInstall,
   "pm-x": pmX,
   fetch: _fetch,
+  jsimport,
+  "js-import": jsimport,
 } as Record<string, Generator>;

src/generators/index.ts

@@ -0,0 +1,57 @@
+import { readFile } from "node:fs/promises";
+import { codeBlock } from "omark";
+import { findExportNames, resolvePath } from "mlly";
+import { getPkg } from "../_utils";
+import { defineGenerator } from "../generator";
+
+const DEFAULT_CDN = "https://esm.sh/";
+
+export const jsimport = defineGenerator({
+  name: "js-import",
+  async generate({ config, args }) {
+    const { name } = await getPkg(config.dir, args);
+
+    const importPath = name + (args.path || "");
+
+    const importNames: string[] = ([] as string[])
+      .concat(args.import, args.imports) // eslint-disable-line unicorn/prefer-spread
+      .filter(Boolean)
+      .flatMap((i) => i.split(/\s*,\s*/));
+
+    if (args.src) {
+      const resolved = await resolvePath(args.src, { url: config.dir });
+      const contents = await readFile(resolved, "utf8");
+      const exportNames = findExportNames(contents);
+      if (exportNames && exportNames.length > 0) {
+        importNames.push(...exportNames);
+      }
+    }
+
+    const lines: string[] = [];
+
+    const fmtImports =
+      importNames.length > 1
+        ? `\n${importNames.map((i) => "  " + i + ",").join("\n")}\n`
+        : (importNames[0] && ` ${importNames[0]} `) || "";
+
+    if (args.esm !== false) {
+      const code = `import {${fmtImports}} from "${importPath}";`;
+      lines.push("**ESM** (Node.js, Bun)", codeBlock(code, "js"));
+    }
+
+    if (args.cjs) {
+      const code = `const {${fmtImports}} = require("${importPath}");`;
+      lines.push("**CommonJS** (Legacy Node.js)", codeBlock(code, "js"));
+    }
+
+    if (args.cdn) {
+      const cdnBase = typeof args.cdn === "string" ? args.cdn : DEFAULT_CDN;
+      const code = `import {${fmtImports}} from "${cdnBase}${importPath}";`;
+      lines.push("**CDN** (Deno, Bun and Browsers)", codeBlock(code, "js"));
+    }
+
+    return {
+      contents: lines.join("\n\n"),
+    };
+  },
+});

src/generators/jsimport.ts

@@ -24,3 +24,8 @@
 
 <!-- automd:fetch url="https://gist.github.com/pi0/c176defbba5568b6d06ea619a75f6104/raw" -->
 <!-- /automd -->
+
+## `js-import`
+
+<!-- automd:js-import cjs=true cdn=true name=pkg imports=foo,bar -->
+<!-- /automd -->

test/fixture/INPUT.md

@@ -100,4 +100,37 @@ When your code doesn't work, don't blame yourself. It's clearly the compiler's f
 Why waste time solving problems when someone else has already done it for you? Stack Overflow is your best friend, your mentor, and your savior. Just make sure to upvote the answers that save your bacon.
 
 
+<!-- /automd -->
+
+## `js-import`
+
+<!-- automd:js-import cjs=true cdn=true name=pkg imports=foo,bar -->
+
+**ESM** (Node.js, Bun)
+
+```js
+import {
+  foo,
+  bar,
+} from "pkg";
+```
+
+**CommonJS** (Legacy Node.js)
+
+```js
+const {
+  foo,
+  bar,
+} = require("pkg");
+```
+
+**CDN** (Deno, Bun and Browsers)
+
+```js
+import {
+  foo,
+  bar,
+} from "https://esm.sh/pkg";
+```
+
 <!-- /automd -->