From 4ea7294eeb2aa71a48c984562750958dd92900de Mon Sep 17 00:00:00 2001
From: Sidharth Vinod <sidharthv96@gmail.com>
Date: Sun, 19 Feb 2023 16:10:08 +0530
Subject: [PATCH] fix(#3406, #3394): Remove init & initThrowsErrors

New run function added as replacement.
---
 V10-BreakingChanges.md                        |  35 ++-
 .../external-diagrams-example-diagram.html    |   2 +-
 cypress/platform/render-after-error.html      |   3 +-
 cypress/platform/rerender.html                |   2 +-
 .../interfaces/mermaidAPI.ParseOptions.md     |  19 ++
 .../interfaces/mermaidAPI.RenderResult.md     |   4 +-
 docs/config/setup/modules/mermaidAPI.md       |  25 +--
 packages/mermaid/src/mermaid.spec.ts          |  28 ++-
 packages/mermaid/src/mermaid.ts               | 202 ++++++++++--------
 packages/mermaid/src/mermaidAPI.spec.ts       |   4 +-
 packages/mermaid/src/mermaidAPI.ts            |  17 +-
 11 files changed, 215 insertions(+), 126 deletions(-)
 create mode 100644 docs/config/setup/interfaces/mermaidAPI.ParseOptions.md

diff --git a/V10-BreakingChanges.md b/V10-BreakingChanges.md
index e3322a3a1..121fdd596 100644
--- a/V10-BreakingChanges.md
+++ b/V10-BreakingChanges.md
@@ -2,7 +2,7 @@
 
 ## Async
 
-`init`, `parse`, `render` are now async.
+`parse`, `render` are now async.
 
 ## Lazy loading and asynchronisity
 
@@ -23,3 +23,36 @@ try {
   parseError(err);
 }
 ```
+
+## Init deprecated and InitThrowsErrors removed
+
+The config passed to `init` was not being used eariler.
+It will now be used.
+The `init` function is deprecated and will be removed in the next major release.
+init currently works as a wrapper to `initialize` and `run`.
+
+```js
+//< v10.0.0
+mermaid.init(config, selector, cb);
+
+//>= v10.0.0
+mermaid.initialize(config);
+mermaid.run({
+  querySelector: selector,
+  postRenderCallback: cb,
+  suppressErrors: true,
+});
+```
+
+```js
+//< v10.0.0
+mermaid.initThrowsErrors(config, selector, cb);
+
+//>= v10.0.0
+mermaid.initialize(config);
+mermaid.run({
+  querySelector: selector,
+  postRenderCallback: cb,
+  suppressErrors: false,
+});
+```
diff --git a/cypress/platform/external-diagrams-example-diagram.html b/cypress/platform/external-diagrams-example-diagram.html
index a1339d4e6..b5b716ff8 100644
--- a/cypress/platform/external-diagrams-example-diagram.html
+++ b/cypress/platform/external-diagrams-example-diagram.html
@@ -17,7 +17,7 @@ example-diagram
 
       await mermaid.registerExternalDiagrams([exampleDiagram]);
       await mermaid.initialize({ logLevel: 0 });
-      await mermaid.initThrowsErrors();
+      await mermaid.run();
       if (window.Cypress) {
         window.rendered = true;
       }
diff --git a/cypress/platform/render-after-error.html b/cypress/platform/render-after-error.html
index 72ccac34c..2334158c2 100644
--- a/cypress/platform/render-after-error.html
+++ b/cypress/platform/render-after-error.html
@@ -11,7 +11,8 @@
 
     <script type="module">
       import mermaid from './mermaid.esm.mjs';
-      await mermaid.init({ startOnLoad: false });
+      await mermaid.initialize({ startOnLoad: false });
+      await mermaid.run();
 
       await mermaid.mermaidAPI.initialize({ securityLevel: 'strict' });
       try {
diff --git a/cypress/platform/rerender.html b/cypress/platform/rerender.html
index 44ffd8fa8..d9dbc4a5e 100644
--- a/cypress/platform/rerender.html
+++ b/cypress/platform/rerender.html
@@ -11,7 +11,7 @@
 
     <script type="module">
       import mermaid from './mermaid.esm.mjs';
-      mermaid.init({ startOnLoad: false });
+      mermaid.initialize({ startOnLoad: false });
       mermaid.mermaidAPI.initialize();
 
       async function rerender(text) {
diff --git a/docs/config/setup/interfaces/mermaidAPI.ParseOptions.md b/docs/config/setup/interfaces/mermaidAPI.ParseOptions.md
new file mode 100644
index 000000000..93708863c
--- /dev/null
+++ b/docs/config/setup/interfaces/mermaidAPI.ParseOptions.md
@@ -0,0 +1,19 @@
+> **Warning**
+>
+> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
+>
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/setup/interfaces/mermaidAPI.ParseOptions.md](../../../../packages/mermaid/src/docs/config/setup/interfaces/mermaidAPI.ParseOptions.md).
+
+# Interface: ParseOptions
+
+[mermaidAPI](../modules/mermaidAPI.md).ParseOptions
+
+## Properties
+
+### suppressErrors
+
+• `Optional` **suppressErrors**: `boolean`
+
+#### Defined in
+
+[mermaidAPI.ts:70](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L70)
diff --git a/docs/config/setup/interfaces/mermaidAPI.RenderResult.md b/docs/config/setup/interfaces/mermaidAPI.RenderResult.md
index 89a8d70b2..e93359e39 100644
--- a/docs/config/setup/interfaces/mermaidAPI.RenderResult.md
+++ b/docs/config/setup/interfaces/mermaidAPI.RenderResult.md
@@ -65,7 +65,7 @@ element will be removed when rendering is completed.
 
 #### Defined in
 
-[mermaidAPI.ts:385](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L385)
+[mermaidAPI.ts:387](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L387)
 
 ---
 
@@ -75,4 +75,4 @@ element will be removed when rendering is completed.
 
 #### Defined in
 
-[mermaidAPI.ts:384](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L384)
+[mermaidAPI.ts:386](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L386)
diff --git a/docs/config/setup/modules/mermaidAPI.md b/docs/config/setup/modules/mermaidAPI.md
index 7d45a5a13..3be7530dc 100644
--- a/docs/config/setup/modules/mermaidAPI.md
+++ b/docs/config/setup/modules/mermaidAPI.md
@@ -8,6 +8,7 @@
 
 ## Interfaces
 
+- [ParseOptions](../interfaces/mermaidAPI.ParseOptions.md)
 - [RenderResult](../interfaces/mermaidAPI.RenderResult.md)
 
 ## References
@@ -24,13 +25,13 @@ Renames and re-exports [mermaidAPI](mermaidAPI.md#mermaidapi)
 
 #### Defined in
 
-[mermaidAPI.ts:71](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L71)
+[mermaidAPI.ts:75](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L75)
 
 ## Variables
 
 ### mermaidAPI
 
-• `Const` **mermaidAPI**: `Readonly`<{ `defaultConfig`: `MermaidConfig` = configApi.defaultConfig; `getConfig`: () => `MermaidConfig` = configApi.getConfig; `getSiteConfig`: () => `MermaidConfig` = configApi.getSiteConfig; `globalReset`: () => `void` ; `initialize`: (`options`: `MermaidConfig`) => `void` ; `parse`: (`text`: `string`, `parseOptions?`: { `silent?`: `boolean` }) => `Promise`<`boolean` | `void`> ; `parseDirective`: (`p`: `any`, `statement`: `string`, `context`: `string`, `type`: `string`) => `void` ; `render`: (`id`: `string`, `text`: `string`, `svgContainingElement?`: `Element`) => `Promise`<[`RenderResult`](../interfaces/mermaidAPI.RenderResult.md)> ; `reset`: () => `void` ; `setConfig`: (`conf`: `MermaidConfig`) => `MermaidConfig` = configApi.setConfig; `updateSiteConfig`: (`conf`: `MermaidConfig`) => `MermaidConfig` = configApi.updateSiteConfig }>
+• `Const` **mermaidAPI**: `Readonly`<{ `defaultConfig`: `MermaidConfig` = configApi.defaultConfig; `getConfig`: () => `MermaidConfig` = configApi.getConfig; `getSiteConfig`: () => `MermaidConfig` = configApi.getSiteConfig; `globalReset`: () => `void` ; `initialize`: (`options`: `MermaidConfig`) => `void` ; `parse`: (`text`: `string`, `parseOptions?`: [`ParseOptions`](../interfaces/mermaidAPI.ParseOptions.md)) => `Promise`<`boolean` | `void`> ; `parseDirective`: (`p`: `any`, `statement`: `string`, `context`: `string`, `type`: `string`) => `void` ; `render`: (`id`: `string`, `text`: `string`, `svgContainingElement?`: `Element`) => `Promise`<[`RenderResult`](../interfaces/mermaidAPI.RenderResult.md)> ; `reset`: () => `void` ; `setConfig`: (`conf`: `MermaidConfig`) => `MermaidConfig` = configApi.setConfig; `updateSiteConfig`: (`conf`: `MermaidConfig`) => `MermaidConfig` = configApi.updateSiteConfig }>
 
 ## mermaidAPI configuration defaults
 
@@ -94,7 +95,7 @@ mermaid.initialize(config);
 
 #### Defined in
 
-[mermaidAPI.ts:669](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L669)
+[mermaidAPI.ts:671](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L671)
 
 ## Functions
 
@@ -125,7 +126,7 @@ Return the last node appended
 
 #### Defined in
 
-[mermaidAPI.ts:292](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L292)
+[mermaidAPI.ts:294](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L294)
 
 ---
 
@@ -151,7 +152,7 @@ the cleaned up svgCode
 
 #### Defined in
 
-[mermaidAPI.ts:243](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L243)
+[mermaidAPI.ts:245](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L245)
 
 ---
 
@@ -177,7 +178,7 @@ the string with all the user styles
 
 #### Defined in
 
-[mermaidAPI.ts:172](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L172)
+[mermaidAPI.ts:174](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L174)
 
 ---
 
@@ -200,7 +201,7 @@ the string with all the user styles
 
 #### Defined in
 
-[mermaidAPI.ts:220](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L220)
+[mermaidAPI.ts:222](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L222)
 
 ---
 
@@ -227,7 +228,7 @@ with an enclosing block that has each of the cssClasses followed by !important;
 
 #### Defined in
 
-[mermaidAPI.ts:156](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L156)
+[mermaidAPI.ts:158](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L158)
 
 ---
 
@@ -247,7 +248,7 @@ with an enclosing block that has each of the cssClasses followed by !important;
 
 #### Defined in
 
-[mermaidAPI.ts:136](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L136)
+[mermaidAPI.ts:138](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L138)
 
 ---
 
@@ -267,7 +268,7 @@ with an enclosing block that has each of the cssClasses followed by !important;
 
 #### Defined in
 
-[mermaidAPI.ts:107](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L107)
+[mermaidAPI.ts:109](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L109)
 
 ---
 
@@ -293,7 +294,7 @@ Put the svgCode into an iFrame. Return the iFrame code
 
 #### Defined in
 
-[mermaidAPI.ts:271](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L271)
+[mermaidAPI.ts:273](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L273)
 
 ---
 
@@ -318,4 +319,4 @@ Remove any existing elements from the given document
 
 #### Defined in
 
-[mermaidAPI.ts:342](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L342)
+[mermaidAPI.ts:344](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L344)
diff --git a/packages/mermaid/src/mermaid.spec.ts b/packages/mermaid/src/mermaid.spec.ts
index f50661dcf..75cafcdf3 100644
--- a/packages/mermaid/src/mermaid.spec.ts
+++ b/packages/mermaid/src/mermaid.spec.ts
@@ -14,41 +14,43 @@ describe('when using mermaid and ', () => {
     it('should not start rendering with mermaid.startOnLoad set to false', async () => {
       mermaid.startOnLoad = false;
       document.body.innerHTML = '<div class="mermaid">graph TD;\na;</div>';
-      spyOn(mermaid, 'init');
+      spyOn(mermaid, 'run');
       mermaid.contentLoaded();
-      expect(mermaid.init).not.toHaveBeenCalled();
+      expect(mermaid.run).not.toHaveBeenCalled();
     });
 
     it('should start rendering with both startOnLoad set', async () => {
       mermaid.startOnLoad = true;
       document.body.innerHTML = '<div class="mermaid">graph TD;\na;</div>';
-      spyOn(mermaid, 'init');
+      spyOn(mermaid, 'run');
       mermaid.contentLoaded();
-      expect(mermaid.init).toHaveBeenCalled();
+      expect(mermaid.run).toHaveBeenCalled();
     });
 
     it('should start rendering with mermaid.startOnLoad', async () => {
       mermaid.startOnLoad = true;
       document.body.innerHTML = '<div class="mermaid">graph TD;\na;</div>';
-      spyOn(mermaid, 'init');
+      spyOn(mermaid, 'run');
       mermaid.contentLoaded();
-      expect(mermaid.init).toHaveBeenCalled();
+      expect(mermaid.run).toHaveBeenCalled();
     });
 
     it('should start rendering as a default with no changes performed', async () => {
       document.body.innerHTML = '<div class="mermaid">graph TD;\na;</div>';
-      spyOn(mermaid, 'init');
+      spyOn(mermaid, 'run');
       mermaid.contentLoaded();
-      expect(mermaid.init).toHaveBeenCalled();
+      expect(mermaid.run).toHaveBeenCalled();
     });
   });
 
-  describe('when using #initThrowsErrors', () => {
+  describe('when using #run', () => {
     it('should accept single node', async () => {
       const node = document.createElement('div');
       node.appendChild(document.createTextNode('graph TD;\na;'));
 
-      await mermaid.initThrowsErrors(undefined, node);
+      await mermaid.run({
+        nodes: [node],
+      });
       // mermaidAPI.render function has been mocked, since it doesn't yet work
       // in Node.JS (only works in browser)
       expect(mermaidAPI.render).toHaveBeenCalled();
@@ -73,7 +75,11 @@ describe('when using mermaid and ', () => {
         )
       ).rejects.toThrow('Failed to load 1 external diagrams');
 
-      expect(() => mermaid.initThrowsErrors(undefined, node)).not.toThrow();
+      await expect(
+        mermaid.run({
+          nodes: [node],
+        })
+      ).resolves.not.toThrow();
       // should still render, even if lazyLoadedDiagrams fails
       expect(mermaidAPI.render).toHaveBeenCalled();
     });
diff --git a/packages/mermaid/src/mermaid.ts b/packages/mermaid/src/mermaid.ts
index c4499bbc3..18e0b3429 100644
--- a/packages/mermaid/src/mermaid.ts
+++ b/packages/mermaid/src/mermaid.ts
@@ -7,7 +7,7 @@ import dedent from 'ts-dedent';
 import { MermaidConfig } from './config.type';
 import { log } from './logger';
 import utils from './utils';
-import { mermaidAPI, RenderResult } from './mermaidAPI';
+import { mermaidAPI, ParseOptions, RenderResult } from './mermaidAPI';
 import { registerLazyLoadedDiagrams } from './diagram-api/detectType';
 import type { ParseErrorFunction } from './Diagram';
 import { isDetailedError } from './utils';
@@ -18,47 +18,20 @@ import { ExternalDiagramDefinition } from './diagram-api/types';
 export type { MermaidConfig, DetailedError, ExternalDiagramDefinition, ParseErrorFunction };
 
 /**
- * ## init
+ * The options used when running mermaid.
  *
- * Function that goes through the document to find the chart definitions in there and render them.
- *
- * The function tags the processed attributes with the attribute data-processed and ignores found
- * elements with the attribute already set. This way the init function can be triggered several
- * times.
- *
- * ```mermaid
- * graph LR;
- *  a(Find elements)-->b{Processed}
- *  b-->|Yes|c(Leave element)
- *  b-->|No |d(Transform)
- * ```
- *
- * Renders the mermaid diagrams
- *
- * @param config - **Deprecated**, please set configuration in {@link initialize}.
- * @param nodes - **Default**: `.mermaid`. One of the following:
- * - A DOM Node
- * - An array of DOM nodes (as would come from a jQuery selector)
- * - A W3C selector, a la `.mermaid`
- * @param callback - Called once for each rendered diagram's id.
+ * @param querySelector - The query selector to use when finding elements to render. Default: .mermaid
+ * @param nodes - The nodes to render. If this is set, querySelector will be ignored.
+ * @param postRenderCallback - A callback to call after each diagram is rendered.
+ * @param suppressErrors - If true, errors will be logged to the console, but not thrown. Default: false
  */
-const init = async function (
-  config?: MermaidConfig,
-  nodes?: string | HTMLElement | NodeListOf<HTMLElement>,
-  callback?: (id: string) => unknown
-) {
-  try {
-    await initThrowsErrors(config, nodes, callback);
-  } catch (e) {
-    log.warn('Syntax Error rendering');
-    if (isDetailedError(e)) {
-      log.warn(e.str);
-    }
-    if (mermaid.parseError) {
-      mermaid.parseError(e as string);
-    }
-  }
-};
+export interface RunOptions {
+  // Default: .mermaid
+  querySelector?: string;
+  nodes?: ArrayLike<HTMLElement>;
+  postRenderCallback?: (id: string) => unknown;
+  suppressErrors?: boolean;
+}
 
 const handleError = (error: unknown, errors: DetailedError[], parseError?: ParseErrorFunction) => {
   log.warn(error);
@@ -110,48 +83,68 @@ const loadExternalDiagrams = async (...diagrams: ExternalDiagramDefinition[]) =>
 };
 
 /**
- * Equivalent to {@link init}, except an error will be thrown on error.
+ * ## run
  *
- * @param config - **Deprecated** Mermaid sequenceConfig.
- * @param nodes - One of:
- * - A DOM Node
- * - An array of DOM nodes (as would come from a jQuery selector)
- * - A W3C selector, a la `.mermaid` (default)
- * @param callback - Function that is called with the id of each generated mermaid diagram.
- * @returns Resolves on success, otherwise the {@link Promise} will be rejected.
+ * Function that goes through the document to find the chart definitions in there and render them.
+ *
+ * The function tags the processed attributes with the attribute data-processed and ignores found
+ * elements with the attribute already set. This way the init function can be triggered several
+ * times.
+ *
+ * ```mermaid
+ * graph LR;
+ *  a(Find elements)-->b{Processed}
+ *  b-->|Yes|c(Leave element)
+ *  b-->|No |d(Transform)
+ * ```
+ *
+ * Renders the mermaid diagrams
+ *
+ * @param options - Optional runtime configs
  */
-const initThrowsErrors = async function (
-  config?: MermaidConfig,
-  nodes?: string | HTMLElement | NodeListOf<HTMLElement>,
-  callback?: (id: string) => unknown
+const run = async function (
+  options: RunOptions = {
+    querySelector: '.mermaid',
+  }
+) {
+  try {
+    await runThrowsErrors(options);
+  } catch (e) {
+    if (isDetailedError(e)) {
+      log.error(e.str);
+    }
+    if (mermaid.parseError) {
+      mermaid.parseError(e as string);
+    }
+    if (!options.suppressErrors) {
+      log.error('Use the suppressErrors option to suppress these errors');
+      throw e;
+    }
+  }
+};
+
+const runThrowsErrors = async function (
+  { postRenderCallback, querySelector, nodes }: Omit<RunOptions, 'suppressErrors'> = {
+    querySelector: '.mermaid',
+  }
 ) {
   const conf = mermaidAPI.getConfig();
 
-  if (config) {
-    // This is a legacy way of setting config. It is not documented and should be removed in the future.
-    // @ts-ignore: TODO Fix ts errors
-    mermaid.sequenceConfig = config;
-  }
+  log.debug(`${!postRenderCallback ? 'No ' : ''}Callback function found`);
 
-  // if last argument is a function this is the callback function
-  log.debug(`${!callback ? 'No ' : ''}Callback function found`);
   let nodesToProcess: ArrayLike<HTMLElement>;
-  if (nodes === undefined) {
-    nodesToProcess = document.querySelectorAll('.mermaid');
-  } else if (typeof nodes === 'string') {
-    nodesToProcess = document.querySelectorAll(nodes);
-  } else if (nodes instanceof HTMLElement) {
-    nodesToProcess = [nodes];
-  } else if (nodes instanceof NodeList) {
+  if (nodes) {
     nodesToProcess = nodes;
+  } else if (querySelector) {
+    nodesToProcess = document.querySelectorAll(querySelector);
   } else {
-    throw new Error('Invalid argument nodes for mermaid.init');
+    throw new Error('Nodes and querySelector are both undefined');
   }
 
   log.debug(`Found ${nodesToProcess.length} diagrams`);
-  if (config?.startOnLoad !== undefined) {
-    log.debug('Start On Load: ' + config?.startOnLoad);
-    mermaidAPI.updateSiteConfig({ startOnLoad: config?.startOnLoad });
+  if (conf?.startOnLoad !== undefined) {
+    log.debug('Start On Load: ' + conf?.startOnLoad);
+    mermaidAPI.updateSiteConfig({ startOnLoad: conf?.startOnLoad });
   }
 
   // generate the id of the diagram
@@ -187,8 +180,8 @@ const initThrowsErrors = async function (
     try {
       const { svg, bindFunctions } = await mermaidAPI.render(id, txt, element);
       element.innerHTML = svg;
-      if (callback) {
-        callback(id);
+      if (postRenderCallback) {
+        await postRenderCallback(id);
       }
       if (bindFunctions) {
         bindFunctions(element);
@@ -203,10 +196,52 @@ const initThrowsErrors = async function (
   }
 };
 
+/**
+ * Used to set configurations for mermaid.
+ * This function should be called before the run function.
+ * @param config - Configuration object for mermaid.
+ */
+
 const initialize = function (config: MermaidConfig) {
   mermaidAPI.initialize(config);
 };
 
+/**
+ * ## init
+ *
+ * @deprecated Use {@link initialize} and {@link run} instead.
+ *
+ * Renders the mermaid diagrams
+ *
+ * @param config - **Deprecated**, please set configuration in {@link initialize}.
+ * @param nodes - **Default**: `.mermaid`. One of the following:
+ * - A DOM Node
+ * - An array of DOM nodes (as would come from a jQuery selector)
+ * - A W3C selector, a la `.mermaid`
+ * @param callback - Called once for each rendered diagram's id.
+ */
+const init = async function (
+  config?: MermaidConfig,
+  nodes?: string | HTMLElement | NodeListOf<HTMLElement>,
+  callback?: (id: string) => unknown
+) {
+  log.warn('mermaid.init is deprecated. Please use run instead.');
+  if (config) {
+    initialize(config);
+  }
+  const runOptions: RunOptions = { postRenderCallback: callback, querySelector: '.mermaid' };
+  if (typeof nodes === 'string') {
+    runOptions.querySelector = nodes;
+  } else if (nodes) {
+    if (nodes instanceof HTMLElement) {
+      runOptions.nodes = [nodes];
+    } else {
+      runOptions.nodes = nodes;
+    }
+  }
+  await run(runOptions);
+};
+
 /**
  * Used to register external diagram types.
  * @param diagrams - Array of {@link ExternalDiagramDefinition}.
@@ -236,7 +271,7 @@ const contentLoaded = function () {
   if (mermaid.startOnLoad) {
     const { startOnLoad } = mermaidAPI.getConfig();
     if (startOnLoad) {
-      mermaid.init().catch((err) => log.error('Mermaid failed to initialize', err));
+      mermaid.run().catch((err) => log.error('Mermaid failed to initialize', err));
     }
   }
 };
@@ -260,10 +295,10 @@ if (typeof document !== 'undefined') {
  * This is provided for environments where the mermaid object can't directly have a new member added
  * to it (eg. dart interop wrapper). (Initially there is no parseError member of mermaid).
  *
- * @param newParseErrorHandler - New parseError() callback.
+ * @param parseErrorHandler - New parseError() callback.
  */
-const setParseErrorHandler = function (newParseErrorHandler: (err: any, hash: any) => void) {
-  mermaid.parseError = newParseErrorHandler;
+const setParseErrorHandler = function (parseErrorHandler: (err: any, hash: any) => void) {
+  mermaid.parseError = parseErrorHandler;
 };
 
 const executionQueue: (() => Promise<unknown>)[] = [];
@@ -290,15 +325,10 @@ const executeQueue = async () => {
  * Parse the text and validate the syntax.
  * @param text - The mermaid diagram definition.
  * @param parseOptions - Options for parsing.
- * @returns true if the diagram is valid, false otherwise if parseOptions.silent is true.
- * @throws Error if the diagram is invalid and parseOptions.silent is false.
+ * @returns true if the diagram is valid, false otherwise if parseOptions.suppressErrors is true.
+ * @throws Error if the diagram is invalid and parseOptions.suppressErrors is false.
  */
-const parse = async (
-  text: string,
-  parseOptions?: {
-    silent?: boolean;
-  }
-): Promise<boolean | void> => {
+const parse = async (text: string, parseOptions?: ParseOptions): Promise<boolean | void> => {
   return new Promise((resolve, reject) => {
     // This promise will resolve when the mermaidAPI.render call is done.
     // It will be queued first and will be executed when it is first in line
@@ -357,7 +387,7 @@ const mermaid: {
   parse: typeof parse;
   render: typeof render;
   init: typeof init;
-  initThrowsErrors: typeof initThrowsErrors;
+  run: typeof run;
   registerExternalDiagrams: typeof registerExternalDiagrams;
   initialize: typeof initialize;
   contentLoaded: typeof contentLoaded;
@@ -368,7 +398,7 @@ const mermaid: {
   parse,
   render,
   init,
-  initThrowsErrors,
+  run,
   registerExternalDiagrams,
   initialize,
   parseError: undefined,
diff --git a/packages/mermaid/src/mermaidAPI.spec.ts b/packages/mermaid/src/mermaidAPI.spec.ts
index b16237866..cf858b58e 100644
--- a/packages/mermaid/src/mermaidAPI.spec.ts
+++ b/packages/mermaid/src/mermaidAPI.spec.ts
@@ -683,7 +683,7 @@ describe('mermaidAPI', () => {
     });
     it('returns false for invalid definition with silent option', async () => {
       await expect(
-        mermaidAPI.parse('this is not a mermaid diagram definition', { silent: true })
+        mermaidAPI.parse('this is not a mermaid diagram definition', { suppressErrors: true })
       ).resolves.toBe(false);
     });
     it('resolves for valid definition', async () => {
@@ -693,7 +693,7 @@ describe('mermaidAPI', () => {
     });
     it('returns true for valid definition with silent option', async () => {
       await expect(
-        mermaidAPI.parse('graph TD;A--x|text including URL space|B;', { silent: true })
+        mermaidAPI.parse('graph TD;A--x|text including URL space|B;', { suppressErrors: true })
       ).resolves.toBe(true);
     });
   });
diff --git a/packages/mermaid/src/mermaidAPI.ts b/packages/mermaid/src/mermaidAPI.ts
index 5a71bb08e..999db5088 100644
--- a/packages/mermaid/src/mermaidAPI.ts
+++ b/packages/mermaid/src/mermaidAPI.ts
@@ -66,6 +66,10 @@ interface DiagramStyleClassDef {
   textStyles?: string[];
 }
 
+export interface ParseOptions {
+  suppressErrors?: boolean;
+}
+
 // This makes it clear that we're working with a d3 selected element of some kind, even though it's hard to specify the exact type.
 // @ts-ignore Could replicate the type definition in d3. This also makes it possible to use the untyped info from the js diagram files.
 export type D3Element = any;
@@ -74,16 +78,11 @@ export type D3Element = any;
  * Parse the text and validate the syntax.
  * @param text - The mermaid diagram definition.
  * @param parseOptions - Options for parsing.
- * @returns true if the diagram is valid, false otherwise if parseOptions.silent is true.
- * @throws Error if the diagram is invalid and parseOptions.silent is false.
+ * @returns true if the diagram is valid, false otherwise if parseOptions.suppressErrors is true.
+ * @throws Error if the diagram is invalid and parseOptions.suppressErrors is false.
  */
 
-async function parse(
-  text: string,
-  parseOptions?: {
-    silent?: boolean;
-  }
-): Promise<boolean | void> {
+async function parse(text: string, parseOptions?: ParseOptions): Promise<boolean | void> {
   addDiagrams();
   let error;
   try {
@@ -92,7 +91,7 @@ async function parse(
   } catch (err) {
     error = err;
   }
-  if (parseOptions?.silent) {
+  if (parseOptions?.suppressErrors) {
     return error === undefined;
   }
   if (error) {