npm - @mermaid-js/mermaid-cli - Versions diffs - 11.12.0 → 11.15.0 - Mend

@mermaid-js/mermaid-cli 11.12.0 → 11.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/dist/index.html CHANGED Viewed

@@ -1,7 +1,5 @@
 <!doctype html>
 <html>
-  <script charset="utf-8" src="./assets/index-Bv5aVo5X.js"></script>
   <body>
     <div id="container"></div>
   </body>

package/dist-types/src/index.d.ts CHANGED Viewed

@@ -56,6 +56,16 @@ export type MarkdownImageProps = {
      */
     title?: string | null | undefined;
 };
+/**
+ * - Adapted from `p-limit` package.
+ */
+export type Limiter = <Arguments extends unknown[], ReturnType>(function_: (...arguments_: Arguments) => Promise<ReturnType>, ...arguments_: Arguments) => Promise<ReturnType>;
+/**
+ * @typedef {<Arguments extends unknown[], ReturnType>(
+ *  function_: (...arguments_: Arguments) => Promise<ReturnType>,
+ *    ...arguments_: Arguments
+ * ) => Promise<ReturnType>} Limiter - Adapted from `p-limit` package.
+ */
 /**
  * Renders a mermaid diagram or mermaid markdown file.
  *
@@ -70,13 +80,18 @@ export type MarkdownImageProps = {
  * @param {"svg" | "png" | "pdf"} [opts.outputFormat] - Mermaid output format.
  * @param {string} [opts.artefacts] - Path to the artefacts directory.
  * Defaults to `output` extension. Overrides `output` extension if set.
+ * @param {import("puppeteer").Browser} [opts.browser] - If set, reuses the given puppeteer browser instance instead of creating a new one.
+ * This may leak cookies/cache between runs.
+ * @param {Limiter} [opts.limiter] - If set, limiter function to avoid rendering too many diagrams in parallel.
  * @param {ParseMDDOptions} [opts.parseMMDOptions] - Options to pass to {@link parseMMDOptions}.
  */
-export function run(input: `${string}.${"md" | "markdown"}` | string | undefined, output: `${string}.${"md" | "markdown" | "svg" | "png" | "pdf"}` | "/dev/stdout", { puppeteerConfig, quiet, outputFormat, parseMMDOptions, artefacts }?: {
+export function run(input: `${string}.${"md" | "markdown"}` | string | undefined, output: `${string}.${"md" | "markdown" | "svg" | "png" | "pdf"}` | "/dev/stdout", { browser: userPassedBrowser, puppeteerConfig, quiet, outputFormat, parseMMDOptions, limiter, artefacts }?: {
     puppeteerConfig?: puppeteer.LaunchOptions | undefined;
     quiet?: boolean | undefined;
     outputFormat?: "svg" | "png" | "pdf" | undefined;
     artefacts?: string | undefined;
+    browser?: puppeteer.Browser | undefined;
+    limiter?: Limiter | undefined;
     parseMMDOptions?: ParseMDDOptions | undefined;
 }): Promise<void>;
 /**

package/dist-types/src/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;~~SAsZc~~,MAAM;;;;SACN,MAAM~~;;;;;;AAqBpB;;;;;;;;;;;;;;;GAeG~~;AACH,~~2BAbW~~,GAAG,MAAM,IAAI,IAAI,GAAG,UAAU,EAAE,GAAG,MAAM,GAAG,SAAS,UAIrD,GAAG,MAAM,IAAI,IAAI,GAAG,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,EAAE,GAAG,aAAa,~~yEAEhF~~;IAAiD,eAAe;IACzC,KAAK;IACS,YAAY;IAC3B,SAAS;~~IAEA~~,eAAe;CAChD,~~iBAoHA~~;~~AA7UD~~;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uCAPW,OAAO,WAAW,EAAE,OAAO,GAAG,OAAO,WAAW,EAAE,cAAc,cAChE,MAAM,gBACN,KAAK,GAAG,KAAK,GAAG,KAAK,yGACrB,eAAe,GACb,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAC,CAAC,~~CA6JlF~~;~~AAzSD~~,~~qCAwHC~~;~~AA5MD~~;;;;;GAKG;AACH,+BAHW,MAAM,GACJ,KAAK,CAKjB;~~sBAxBqB~~,WAAW"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAodc,MAAM;;;;SACN,MAAM;;;;;;;;;sBAsBP,CAAC,SAAS,SAAS,OAAO,EAAE,EAAE,UAAU,EACjD,SAAS,EAAE,CAAC,GAAG,UAAU,EAAE,SAAS,KAAK,OAAO,CAAC,UAAU,CAAC,EAC/D,GAAQ,UAAU,EAAE,SAAS,KACtB,OAAO,CAAC,UAAU,CAAC;AAJ3B;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,2BAhBW,GAAG,MAAM,IAAI,IAAI,GAAG,UAAU,EAAE,GAAG,MAAM,GAAG,SAAS,UAIrD,GAAG,MAAM,IAAI,IAAI,GAAG,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,EAAE,GAAG,aAAa,8GAEhF;IAAiD,eAAe;IACzC,KAAK;IACS,YAAY;IAC3B,SAAS;IAEY,OAAO;IAE3B,OAAO;IACC,eAAe;CAChD,iBAyHA;AA3WD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uCAPW,OAAO,WAAW,EAAE,OAAO,GAAG,OAAO,WAAW,EAAE,cAAc,cAChE,MAAM,gBACN,KAAK,GAAG,KAAK,GAAG,KAAK,yGACrB,eAAe,GACb,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAC,CAAC,CA4KlF;AA5TD,qCA4HC;AAhOD;;;;;GAKG;AACH,+BAHW,MAAM,GACJ,KAAK,CAKjB;sBAjDqB,WAAW"}

package/dist-types/src/puppeteerIntercept.d.ts ADDED Viewed

@@ -0,0 +1,32 @@
+/**
+ * Puppeteer doesn't allow importing ESM modules from `file://` URLs.
+ * We don't want to create a dummy http server to serve ESM modules
+ * (since that would cause issues with ports/firewalls), so this module
+ * instead intercepts dummy `https://mermaid-cli-intercept.invalid` requests.
+ */
+export class Interceptor {
+    /**
+     * @param {URL | `file://${string}`} fileUrl - File URL
+     * @param {Object} [options] - Optional options.
+     * @param {number} [options.allowParentDirectoryLevel] - Number of parent directory levels to allow access to.
+     */
+    fileUrlToInterceptUrl(fileUrl: URL | `file://${string}`, { allowParentDirectoryLevel }?: {
+        allowParentDirectoryLevel?: number | undefined;
+    }): Promise<string>;
+    /**
+       *
+       * @param {URL | string} interceptUrl
+       * @throws {Error} If the URL is not a valid intercept URL
+       */
+    interceptUrlToFileUrl(interceptUrl: URL | string): Promise<URL>;
+    /**
+       * Intercepts requests to `https://mermaid-cli-intercept.invalid`
+       * and serves the corresponding file content.
+       *
+       * @return {puppeteer.Handler<puppeteer.HTTPRequest>}
+       */
+    get interceptRequestHandler(): puppeteer.Handler<puppeteer.HTTPRequest>;
+    #private;
+}
+import type puppeteer from 'puppeteer';
+//# sourceMappingURL=puppeteerIntercept.d.ts.map

package/dist-types/src/puppeteerIntercept.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"puppeteerIntercept.d.ts","sourceRoot":"","sources":["../../src/puppeteerIntercept.js"],"names":[],"mappings":"AA+BA;;;;;GAKG;AACH;IAcE;;;;OAIG;IACH,+BAJW,GAAG,GAAG,UAAU,MAAM,EAAE,kCAEhC;QAAyB,yBAAyB;KACpD,mBAcA;IAED;;;;SAIK;IACL,oCAHa,GAAG,GAAG,MAAM,gBAcxB;IAyBD;;;;;SAKK;IACL,+BAFc,kBAAkB,qBAAqB,CAAC,CAIrD;;CACF;2BAxHyB,WAAW"}

package/dist-types/src/version.d.ts CHANGED Viewed

@@ -1,2 +1,2 @@
-export const version: "11.12.0";
+export const version: "11.15.0";
 //# sourceMappingURL=version.d.ts.map

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mermaid-js/mermaid-cli",
-  "version": "11.12.0",
+  "version": "11.15.0",
   "description": "Command-line interface for mermaid",
   "license": "MIT",
   "repository": "git@github.com:mermaid-js/mermaid-cli.git",
@@ -14,43 +14,47 @@
   },
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist-types/src/index.d.ts",
-        "default": "./src/index.js"
-      }
+      "types": "./dist-types/src/index.d.ts",
+      "default": "./src/index.js"
     }
   },
   "types": "./dist-types/src/index.d.ts",
   "scripts": {
     "prepare": "tsc && vite build",
     "prepack": "tsc && vite build",
-    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" npx jest",
+    "test": "cross-env-shell NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" npx jest",
     "test:cli": "bash run-tests.sh test-positive",
     "version": "node scripts/version.js",
     "lint": "standard",
     "lint-fix": "standard --fix"
   },
   "dependencies": {
+    "@fortawesome/fontawesome-free": "^6.0.0 || ^7.0.1",
+    "@mermaid-js/layout-elk": "^0.1.5 || ^0.2.0",
     "@mermaid-js/mermaid-zenuml": "^0.2.0",
     "chalk": "^5.0.1",
-    "commander": "^14.0.0",
+    "commander": "^13.1.0",
     "import-meta-resolve": "^4.1.0",
-    "mermaid": "^11.0.2"
+    "katex": "^0.16.25",
+    "mermaid": "^11.14.0",
+    "p-limit": "^6.2.0"
+  },
+  "optionalDependencies": {
+    "@mermaid-js/layout-tidy-tree": "^0.2.1"
   },
   "peerDependencies": {
-    "puppeteer": "^23"
+    "puppeteer": "^23 || ^24"
   },
   "devDependencies": {
-    "@fortawesome/fontawesome-free": "^6.5.2",
-    "@mermaid-js/layout-elk": "^0.1.2",
     "@tsconfig/node18": "^18.2.4",
     "@types/node": "~18.19.31",
+    "cross-env": "^7.0.3",
     "jest": "^30.0.5",
-    "puppeteer": "^23.1.1",
+    "puppeteer": "^24.0.0",
     "standard": "^17.0.0",
-    "typescript": "^5.0.1-rc",
+    "typescript": "^6.0.3",
     "vite": "^6.0.2",
-    "yarn-upgrade-all": "^0.7.0"
+    "yarn-upgrade-all": "^0.8.1"
   },
   "files": [
     "src/",

package/src/index.js CHANGED Viewed

@@ -2,21 +2,48 @@ import { Command, Option, InvalidArgumentError } from 'commander'
 import chalk from 'chalk'
 import fs from 'fs'
 import { resolve } from 'import-meta-resolve'
+import os from 'node:os'
 import path from 'path'
+import pLimit from 'p-limit'
 import puppeteer from 'puppeteer'
 import url from 'url'
+import { promisify } from 'node:util'
 import { version } from './version.js'
+import { Interceptor } from './puppeteerIntercept.js'
 // __dirname is not available in ESM modules by default
 const __dirname = url.fileURLToPath(new url.URL('.', import.meta.url))
 /**
- * Mermaid.js IFFE path.
- *
- * Importing this in a browser adds a global `mermaid` object.
+ * CSS paths to embed in the page.
+ */
+const cssImports = /** @type {const} */ ({
+  '@fortawesome/fontawesome-free/css/brands.css': { level: 2 },
+  '@fortawesome/fontawesome-free/css/regular.css': { level: 2 },
+  '@fortawesome/fontawesome-free/css/solid.css': { level: 2 },
+  '@fortawesome/fontawesome-free/css/fontawesome.css': { level: 2 },
+  'katex/dist/katex.css': { level: 2 }
+})
+/**
+ * ESM bundles. Our interceptor doesn't support loading ESM modules that load
+ * other modules using relative paths, so these have to no `dependencies`.
  */
-const mermaidIIFEPath = path.resolve(path.dirname(url.fileURLToPath(resolve('mermaid', import.meta.url))), 'mermaid.js')
-const zenumlIIFEPath = path.resolve(path.dirname(url.fileURLToPath(resolve('@mermaid-js/mermaid-zenuml', import.meta.url))), 'mermaid-zenuml.js')
+const mermaidESMPath = path.resolve(path.dirname(url.fileURLToPath(resolve('mermaid', import.meta.url))), 'mermaid.esm.mjs')
+const elkESMPath = path.resolve(path.dirname(url.fileURLToPath(resolve('@mermaid-js/layout-elk', import.meta.url))), 'mermaid-layout-elk.esm.mjs')
+const zenumlESMPath = path.resolve(path.dirname(url.fileURLToPath(resolve('@mermaid-js/mermaid-zenuml', import.meta.url))), 'mermaid-zenuml.esm.mjs')
+/** @type {string | undefined} Path to `@mermaid-js/layout-tidy-tree`, if it is installed */
+let tidyTreeESMPath
+try {
+  tidyTreeESMPath = path.resolve(path.dirname(url.fileURLToPath(resolve('@mermaid-js/layout-tidy-tree', import.meta.url))), 'mermaid-layout-tidy-tree.esm.mjs')
+} catch (error) {
+  if (error instanceof Error && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') {
+    // optional dependency, this is normal
+  } else {
+    throw error
+  }
+}
 /**
  * Prints an error to stderr, then closes with exit code 1
@@ -102,6 +129,22 @@ function parseCommanderInt (value, _unused) {
   return parsedValue
 }
+/**
+ * Commander parser that converts a string to a float.
+ *
+ * @param {string} value - The value from commander.
+ * @param {*} _unused - Unused.
+ * @returns {number} The value parsed as a number.
+ * @see https://github.com/tj/commander.js/wiki/Class:-Option#argparserfn
+ */
+function parseCommanderFloat (value, _unused) {
+  const parsedValue = parseFloat(value)
+  if (isNaN(parsedValue) || parsedValue <= 0) {
+    throw new InvalidArgumentError('Not a positive number.')
+  }
+  return parsedValue
+}
 async function cli () {
   const commander = new Command()
   commander
@@ -112,12 +155,15 @@ async function cli () {
     .option('-i, --input <input>', 'Input mermaid file. Files ending in .md will be treated as Markdown and all charts (e.g. ```mermaid (...)``` or :::mermaid (...):::) will be extracted and generated. Use `-` to read from stdin.')
     .option('-o, --output [output]', 'Output file. It should be either md, svg, png, pdf or use `-` to output to stdout. Optional. Default: input + ".svg"')
     .option('-a, --artefacts [artefacts]', 'Output artefacts path. Only used with Markdown input file. Optional. Default: output directory')
+    .addOption(new Option('-j, --jobs <jobs>', 'Number of parallel jobs to run when rendering multiple diagrams. Defaults to half the available CPUs.').argParser(parseCommanderInt).default(
+      Math.floor(os.availableParallelism() / 2) || 1
+    ))
     .addOption(new Option('-e, --outputFormat [format]', 'Output format for the generated image.').choices(['svg', 'png', 'pdf']).default(null, 'Loaded from the output file extension'))
     .addOption(new Option('-b, --backgroundColor [backgroundColor]', 'Background color for pngs/svgs (not pdfs). Example: transparent, red, \'#F0F0F0\'.').default('white'))
     .option('-c, --configFile [configFile]', 'JSON configuration file for mermaid.')
     .option('-C, --cssFile [cssFile]', 'CSS file for the page.')
     .option('-I, --svgId [svgId]', 'The id attribute for the SVG element to be rendered.')
-    .addOption(new Option('-s, --scale [scale]', 'Puppeteer scale factor').argParser(parseCommanderInt).default(1))
+    .addOption(new Option('-s, --scale [scale]', 'Puppeteer scale factor').argParser(parseCommanderFloat).default(1))
     .option('-f, --pdfFit', 'Scale PDF to fit chart')
     .option('-q, --quiet', 'Suppress log output')
     .option('-p --puppeteerConfigFile [puppeteerConfigFile]', 'JSON configuration file for puppeteer.')
@@ -127,7 +173,7 @@ async function cli () {
   const options = commander.opts()
-  let { theme, width, height, input, output, outputFormat, backgroundColor, configFile, cssFile, svgId, puppeteerConfigFile, scale, pdfFit, quiet, iconPacks, iconPacksNamesAndUrls, artefacts } = options
+  let { theme, width, height, input, output, outputFormat, backgroundColor, configFile, cssFile, svgId, puppeteerConfigFile, scale, pdfFit, quiet, iconPacks, iconPacksNamesAndUrls, artefacts, jobs } = options
   // check input file
   if (!input) {
@@ -189,7 +235,7 @@ async function cli () {
     mermaidConfig = Object.assign(mermaidConfig, JSON.parse(fs.readFileSync(configFile, 'utf-8')))
   }
-  let puppeteerConfig = /** @type {import('puppeteer').PuppeteerLaunchOptions} */ ({
+  let puppeteerConfig = /** @type {import('puppeteer').LaunchOptions} */ ({
     /*
      * `headless: 'shell'` is not officially supported in Puppeteer v19, v20, v21,
      * but still works. In Puppeteer v22, it uses the `chrome-headless-shell` package,
@@ -216,6 +262,7 @@ async function cli () {
       puppeteerConfig,
       quiet,
       outputFormat,
+      limiter: pLimit(jobs),
       parseMMDOptions: {
         mermaidConfig, backgroundColor, myCSS, pdfFit, viewport: { width, height, deviceScaleFactor: scale }, svgId, iconPacks, iconPacksNamesAndUrls
       },
@@ -259,25 +306,41 @@ async function renderMermaid (browser, definition, outputFormat, { viewport, bac
     await page.$eval('body', (body, backgroundColor) => {
       body.style.background = backgroundColor
     }, backgroundColor)
-    await Promise.all([
-      page.addScriptTag({ path: mermaidIIFEPath }),
-      page.addScriptTag({ path: zenumlIIFEPath })
-    ])
-    const metadata = await page.$eval('#container', async (container, definition, mermaidConfig, myCSS, backgroundColor, svgId, iconPacks, iconPacksNamesAndUrls) => {
-      await Promise.all(Array.from(document.fonts, (font) => font.load()))
-      /**
-       * @typedef {Object} GlobalThisWithMermaid
-       * We've already imported these modules in our `index.html` file (or by running `page.addScriptTag`),
-       * so that they get correctly bundled.
-       * @property {import("mermaid")["default"]} mermaid Already imported mermaid instance
-       * @property {import("@mermaid-js/mermaid-zenuml")["default"]} mermaid-zenuml Already imported mermaid-zenuml instance
-       * @property {import("@mermaid-js/layout-elk")["default"]} elkLayouts Already imported mermaid-elkLayouts instance
-       */
-      const { mermaid, 'mermaid-zenuml': zenuml, elkLayouts } = /** @type {GlobalThisWithMermaid & typeof globalThis} */ (globalThis)
+    const interceptor = new Interceptor()
+    const mermaidUrl = await interceptor.fileUrlToInterceptUrl(url.pathToFileURL(mermaidESMPath))
+    const elkUrl = await interceptor.fileUrlToInterceptUrl(url.pathToFileURL(elkESMPath))
+    const zenumlUrl = await interceptor.fileUrlToInterceptUrl(url.pathToFileURL(zenumlESMPath))
+    const tidyTreeESMUrl = tidyTreeESMPath ? await interceptor.fileUrlToInterceptUrl(url.pathToFileURL(tidyTreeESMPath)) : undefined
+    page.on('request', interceptor.interceptRequestHandler)
+    await page.setRequestInterception(true)
+    await Promise.all(Object.entries(cssImports).map(async ([cssImport, { level }]) => {
+      const interceptUrl = await interceptor.fileUrlToInterceptUrl(new URL(resolve(cssImport, import.meta.url)), {
+        allowParentDirectoryLevel: level
+      })
+      await page.addStyleTag({
+        url: interceptUrl
+      })
+    }))
+    const metadata = await page.$eval('#container', async (container, { definition, mermaidConfig, myCSS, backgroundColor, svgId, iconPacks, iconPacksNamesAndUrls, elkUrl, mermaidUrl, zenumlUrl, tidyTreeESMUrl }) => {
+      const { default: mermaid } = await import(mermaidUrl)
+      /** @type {typeof import('@mermaid-js/layout-elk')} */
+      const { default: elkLayouts } = await import(elkUrl)
+      /** @type {typeof import('@mermaid-js/mermaid-zenuml')} */
+      const { default: zenuml } = await import(zenumlUrl)
+      // @ts-ignore -- @mermaid-js/layout-tidy-tree is an optionalDependency and might not be installed
+      /** @type {typeof import('@mermaid-js/layout-tidy-tree') | {default: undefined}} */
+      const { default: tidyTree } = tidyTreeESMUrl ? await import(tidyTreeESMUrl) : { default: undefined }
+      await Promise.all(Array.from(document.fonts, (font) => font.load()))
       await mermaid.registerExternalDiagrams([zenuml])
-      mermaid.registerLayoutLoaders(elkLayouts)
+      mermaid.registerLayoutLoaders([
+        ...elkLayouts,
+        ...(tidyTree ?? [])
+      ])
       // lazy load icon packs
       mermaid.registerIconPacks(
@@ -291,22 +354,21 @@ async function renderMermaid (browser, definition, outputFormat, { viewport, bac
       )
       mermaid.registerIconPacks(
-        iconPacksNamesAndUrls.map((iconPackInfo) =>
-          {
-            var packName = iconPackInfo.split('#')[0];
-            var packUrl = iconPackInfo.split('#')[1];
-            return ({
-              name: packName,
-              loader: () =>
-                fetch(packUrl)
-                  .then((res) => res.json())
-                  .catch(() => {
-                    error(`Failed to fetch icon: ${iconPackInfo}`);
-                  })
-              }
-            )
+        iconPacksNamesAndUrls.map((iconPackInfo) => {
+          const packName = iconPackInfo.split('#')[0]
+          const packUrl = iconPackInfo.split('#')[1]
+          return ({
+            name: packName,
+            loader: () =>
+              fetch(packUrl)
+                .then((res) => res.json())
+                .catch(() => {
+                  error(`Failed to fetch icon: ${iconPackInfo}`)
+                })
           }
+          )
+        }
         )
       )
       mermaid.initialize({ startOnLoad: false, ...mermaidConfig })
@@ -347,7 +409,7 @@ async function renderMermaid (browser, definition, outputFormat, { viewport, bac
       return {
         title, desc
       }
-    }, definition, mermaidConfig, myCSS, backgroundColor, svgId, iconPacks, iconPacksNamesAndUrls)
+    }, { definition, mermaidConfig, myCSS, backgroundColor, svgId, iconPacks, iconPacksNamesAndUrls, elkUrl, mermaidUrl, zenumlUrl, tidyTreeESMUrl })
     if (outputFormat === 'svg') {
       const svgXML = await page.$eval('svg', (svg) => {
@@ -426,6 +488,13 @@ function markdownImage ({ url, title, alt }) {
   }
 }
+/**
+ * @typedef {<Arguments extends unknown[], ReturnType>(
+ *  function_: (...arguments_: Arguments) => Promise<ReturnType>,
+ *    ...arguments_: Arguments
+ * ) => Promise<ReturnType>} Limiter - Adapted from `p-limit` package.
+ */
 /**
  * Renders a mermaid diagram or mermaid markdown file.
  *
@@ -440,9 +509,12 @@ function markdownImage ({ url, title, alt }) {
  * @param {"svg" | "png" | "pdf"} [opts.outputFormat] - Mermaid output format.
  * @param {string} [opts.artefacts] - Path to the artefacts directory.
  * Defaults to `output` extension. Overrides `output` extension if set.
+ * @param {import("puppeteer").Browser} [opts.browser] - If set, reuses the given puppeteer browser instance instead of creating a new one.
+ * This may leak cookies/cache between runs.
+ * @param {Limiter} [opts.limiter] - If set, limiter function to avoid rendering too many diagrams in parallel.
  * @param {ParseMDDOptions} [opts.parseMMDOptions] - Options to pass to {@link parseMMDOptions}.
  */
-async function run (input, output, { puppeteerConfig = {}, quiet = false, outputFormat, parseMMDOptions, artefacts } = {}) {
+async function run (input, output, { browser: userPassedBrowser, puppeteerConfig = {}, quiet = false, outputFormat, parseMMDOptions, limiter = (x, ...args) => x(...args), artefacts } = {}) {
   /**
    * Logs the given message to stdout, unless `quiet` is set to `true`.
    *
@@ -461,7 +533,7 @@ async function run (input, output, { puppeteerConfig = {}, quiet = false, output
    * @type {puppeteer.Browser | undefined}
    * Lazy-loaded browser instance, only created when needed.
    */
-  let browser
+  let browser = userPassedBrowser
   try {
     if (!outputFormat) {
       const outputFormatFromFilename =
@@ -510,7 +582,7 @@ async function run (input, output, { puppeteerConfig = {}, quiet = false, output
         const outputFileRelative = `./${path.relative(path.dirname(path.resolve(output)), path.resolve(outputFile))}`
-        const imagePromise = (async () => {
+        const imagePromise = limiter(async (browser, outputFormat) => {
           const { title, desc, data } = await renderMermaid(browser, mermaidDefinition, outputFormat, parseMMDOptions)
           await fs.promises.writeFile(outputFile, data)
           info(` ✅ ${outputFileRelative}`)
@@ -520,7 +592,7 @@ async function run (input, output, { puppeteerConfig = {}, quiet = false, output
             title,
             alt: desc
           }
-        })()
+        }, browser, outputFormat)
         imagePromises.push(imagePromise)
       }
@@ -548,14 +620,19 @@ async function run (input, output, { puppeteerConfig = {}, quiet = false, output
       }
     } else {
       info('Generating single mermaid chart')
-      browser = await puppeteer.launch(puppeteerConfig)
+      browser ??= await puppeteer.launch(puppeteerConfig)
       const { data } = await renderMermaid(browser, definition, outputFormat, parseMMDOptions)
-      await output !== '/dev/stdout'
-        ? fs.promises.writeFile(output, data)
-        : process.stdout.write(data)
+      if (output === '/dev/stdout') {
+        await promisify(process.stdout.write).call(process.stdout, data)
+      } else {
+        await fs.promises.writeFile(output, data)
+      }
     }
   } finally {
-    await browser?.close?.()
+    // Don't close the browser if it was passed in by the user
+    if (browser !== userPassedBrowser) {
+      await browser?.close?.()
+    }
   }
 }

package/src/puppeteerIntercept.js ADDED Viewed

@@ -0,0 +1,122 @@
+/**
+ * @import puppeteer from 'puppeteer';
+ */
+import { readFile, realpath } from 'node:fs/promises'
+import path from 'node:path'
+import url from 'node:url'
+/**
+ * Guesses the MIME-type of a file based on its extension.
+ *
+ * I've hardcoded the bare minimum number of MIME-types to support for security reasons.
+ *
+ * @param {string} filePath - The file path to guess the MIME-type for.
+ */
+function getContentTypeFromFileExtension (filePath) {
+  const ext = path.extname(filePath).toLowerCase()
+  switch (ext) {
+    case '.css':
+      // Make sure to set UTF-8, since sometimes Puppeteer can parse it as Latin-1.
+      return 'text/css;charset=UTF-8'
+    case '.js':
+    case '.mjs':
+      return 'application/javascript'
+    case '.woff2':
+      return 'font/woff2'
+    default:
+      throw new Error(`Unsupported file extension for intercept: ${ext}`)
+  }
+}
+/**
+ * Puppeteer doesn't allow importing ESM modules from `file://` URLs.
+ * We don't want to create a dummy http server to serve ESM modules
+ * (since that would cause issues with ports/firewalls), so this module
+ * instead intercepts dummy `https://mermaid-cli-intercept.invalid` requests.
+ */
+export class Interceptor {
+  #INTERCEPT_ORIGIN = 'https://mermaid-cli-intercept.invalid'
+  /**
+     * Set of allowed file directories that can be intercepted.
+     *
+     * This is used to prevent arbitrary file access through the intercept mechanism.
+     *
+     * Make sure to use `realpath` to resolve any symlinks.
+     *
+     * @type {Set<string>}
+     */
+  #allowedDirs = new Set()
+  /**
+   * @param {URL | `file://${string}`} fileUrl - File URL
+   * @param {Object} [options] - Optional options.
+   * @param {number} [options.allowParentDirectoryLevel] - Number of parent directory levels to allow access to.
+   */
+  async fileUrlToInterceptUrl (fileUrl, {
+    allowParentDirectoryLevel = 1
+  } = {}) {
+    fileUrl = new URL(fileUrl)
+    if (fileUrl.protocol !== 'file:') {
+      throw new Error(`Invalid file URL: ${fileUrl}`)
+    }
+    let parentDirectory = await realpath(url.fileURLToPath(fileUrl))
+    while (allowParentDirectoryLevel-- >= 0) {
+      parentDirectory = path.dirname(parentDirectory)
+    }
+    this.#allowedDirs.add(parentDirectory)
+    return `${this.#INTERCEPT_ORIGIN}${fileUrl.pathname}`
+  }
+  /**
+     *
+     * @param {URL | string} interceptUrl
+     * @throws {Error} If the URL is not a valid intercept URL
+     */
+  async interceptUrlToFileUrl (interceptUrl) {
+    interceptUrl = new URL(interceptUrl)
+    if (interceptUrl.origin !== this.#INTERCEPT_ORIGIN) {
+      throw new Error(`Invalid intercept URL: ${interceptUrl}`)
+    }
+    const fileUrl = new URL(interceptUrl.href.slice(this.#INTERCEPT_ORIGIN.length), 'file://')
+    const filePath = await realpath(url.fileURLToPath(fileUrl))
+    if (![...this.#allowedDirs].some(dir => path.relative(filePath, dir).startsWith('..'))) {
+      throw new Error(`Intercept URL is not in an allowed directory: ${interceptUrl}`)
+    }
+    return fileUrl
+  }
+  /**
+     * @param {puppeteer.HTTPRequest} request - The intercepted request
+     */
+  async #interceptRequestHandler (request) {
+    try {
+      if (request.url().startsWith(this.#INTERCEPT_ORIGIN)) {
+        const fileUrl = await this.interceptUrlToFileUrl(request.url())
+        return request.respond({
+          status: 200,
+          headers: {
+            'Access-Control-Allow-Origin': '*'
+          },
+          contentType: getContentTypeFromFileExtension(url.fileURLToPath(fileUrl)),
+          body: await readFile(fileUrl)
+        })
+      }
+    } catch (error) {
+      console.error(`Error handling intercept request for ${request.url()}:`, error)
+      request.abort()
+    }
+    request.continue()
+  }
+  /**
+     * Intercepts requests to `https://mermaid-cli-intercept.invalid`
+     * and serves the corresponding file content.
+     *
+     * @return {puppeteer.Handler<puppeteer.HTTPRequest>}
+     */
+  get interceptRequestHandler () {
+    return this.#interceptRequestHandler.bind(this)
+  }
+}