refactor: Change return type to retain partial backwards compatibility.

docs/config/setup/interfaces/mermaidAPI.RenderResult.md

@@ -39,7 +39,7 @@ bindFunctions?.(div); // To call bindFunctions only if it's present.
 
 #### Defined in
 
-[mermaidAPI.ts:96](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L96)
+[mermaidAPI.ts:93](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L93)
 
 ---
 
@@ -51,7 +51,7 @@ The diagram type, e.g. 'flowchart', 'sequence', etc.
 
 #### Defined in
 
-[mermaidAPI.ts:86](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L86)
+[mermaidAPI.ts:83](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L83)
 
 ---
 
@@ -63,4 +63,4 @@ The svg code for the rendered graph.
 
 #### Defined in
 
-[mermaidAPI.ts:82](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L82)
+[mermaidAPI.ts:79](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L79)

docs/config/setup/modules/mermaidAPI.md

@@ -25,13 +25,13 @@ Renames and re-exports [mermaidAPI](mermaidAPI.md#mermaidapi)
 
 #### Defined in
 
-[mermaidAPI.ts:76](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L76)
+[mermaidAPI.ts:73](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L73)
 
 ---
 
 ### ParseResult
 
-Ƭ **ParseResult**: { `diagramType`: `string` ; `isValid`: `true` } | { `isValid`: `false` }
+Ƭ **ParseResult**: { `diagramType`: `string` } | `false`
 
 #### Defined in
 
@@ -106,7 +106,7 @@ mermaid.initialize(config);
 
 #### Defined in
 
-[mermaidAPI.ts:621](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L621)
+[mermaidAPI.ts:618](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L618)
 
 ## Functions
 
@@ -137,7 +137,7 @@ Return the last node appended
 
 #### Defined in
 
-[mermaidAPI.ts:275](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L275)
+[mermaidAPI.ts:272](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L272)
 
 ---
 
@@ -163,7 +163,7 @@ the cleaned up svgCode
 
 #### Defined in
 
-[mermaidAPI.ts:221](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L221)
+[mermaidAPI.ts:218](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L218)
 
 ---
 
@@ -188,7 +188,7 @@ the string with all the user styles
 
 #### Defined in
 
-[mermaidAPI.ts:151](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L151)
+[mermaidAPI.ts:148](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L148)
 
 ---
 
@@ -211,7 +211,7 @@ the string with all the user styles
 
 #### Defined in
 
-[mermaidAPI.ts:198](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L198)
+[mermaidAPI.ts:195](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L195)
 
 ---
 
@@ -238,7 +238,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:133](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L133)
 
 ---
 
@@ -264,7 +264,7 @@ Put the svgCode into an iFrame. Return the iFrame code
 
 #### Defined in
 
-[mermaidAPI.ts:252](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L252)
+[mermaidAPI.ts:249](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L249)
 
 ---
 
@@ -289,4 +289,4 @@ Remove any existing elements from the given document
 
 #### Defined in
 
-[mermaidAPI.ts:325](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L325)
+[mermaidAPI.ts:322](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L322)

docs/config/usage.md

@@ -331,15 +331,17 @@ module.exports = (options) ->
 
 ## Advanced usage
 
-**Syntax validation without rendering (Work in Progress)**
+### Syntax validation without rendering
 
-The **mermaid.parse(txt)** function validates graph definitions without rendering a graph. **[This function is still a work in progress](https://github.com/mermaid-js/mermaid/issues/1066), find alternatives below.**
+The `mermaid.parse(text, parseOptions)` function validates graph definitions without rendering a graph.
 
-The function **mermaid.parse(txt)**, takes a text string as an argument and returns true if the definition follows mermaid's syntax and
+The function `mermaid.parse(text, parseOptions)`, takes a text string as an argument and returns `{ diagramType: string }` if the definition follows mermaid's syntax.
-false if it does not. The parseError function will be called when the parse function returns false.
 
-When the parser encounters invalid syntax the **mermaid.parseError** function is called. It is possible to override this
+If the definition is invalid, the function returns `false` if `parseOptions.supressError` is set to `true`. Otherwise, it throws an error.
-function in order to handle the error in an application-specific way.
+
+The parseError function will be called when the parse function throws an error. It will not be called if `parseOptions.supressError` is set to `true`.
+
+It is possible to override this function in order to handle the error in an application-specific way.
 
 The code-example below in meta code illustrates how this could work:
 
@@ -359,26 +361,10 @@ const textFieldUpdated = async function () {
 bindEventHandler('change', 'code', textFieldUpdated);
 ```
 
-**Alternative to mermaid.parse():**
-One effective and more future-proof method of validating your graph definitions, is to paste and render them via the [Mermaid Live Editor](https://mermaid.live/). This will ensure that your code is compliant with the syntax of Mermaid's most recent version.
-
 ## Configuration
 
-Mermaid takes a number of options which lets you tweak the rendering of the diagrams. Currently there are three ways of
+You can pass the required configuration to the `mermaid.initialize` call. This is the preferred way of configuring mermaid.
-setting the options in mermaid.
+The list of configuration objects are described [in the mermaidAPI documentation](./setup/README.md).
-
-1.  Instantiation of the configuration using the initialize call
-2.  _Using the global mermaid object_ - **Deprecated**
-3.  _using the global mermaid_config object_ - **Deprecated**
-4.  Instantiation of the configuration using the **mermaid.init** call- **Deprecated**
-
-The list above has two ways too many of doing this. Three are deprecated and will eventually be removed. The list of
-configuration objects are described [in the mermaidAPI documentation](./setup/README.md).
-
-## Using the `mermaidAPI.initialize`/`mermaid.initialize` call
-
-The future proof way of setting the configuration is by using the initialization call to mermaid or mermaidAPI depending
-on what kind of integration you use.
 
 ```html
 <script type="module">
@@ -407,32 +393,3 @@ mermaid.startOnLoad = true;
 
 > **Warning**
 > This way of setting the configuration is deprecated. Instead the preferred way is to use the initialize method. This functionality is only kept for backwards compatibility.
-
-## Using the mermaid_config
-
-It is possible to set some configuration via the mermaid object. The two parameters that are supported using this
-approach are:
-
-- mermaid_config.startOnLoad
-- mermaid_config.htmlLabels
-
-```javascript
-mermaid_config.startOnLoad = true;
-```
-
-> **Warning**
-> This way of setting the configuration is deprecated. Instead the preferred way is to use the initialize method. This functionality is only kept for backwards compatibility.
-
-## Using the mermaid.init call
-
-To set some configuration via the mermaid object. The two parameters that are supported using this approach are:
-
-- mermaid_config.startOnLoad
-- mermaid_config.htmlLabels
-
-```javascript
-mermaid_config.startOnLoad = true;
-```
-
-> **Warning**
-> This way of setting the configuration is deprecated. Instead the preferred way is to use the initialize method. This functionality is only kept for backwards compatibility.

packages/mermaid/src/docs/config/usage.md

@@ -328,15 +328,17 @@ module.exports = (options) ->
 
 ## Advanced usage
 
-**Syntax validation without rendering (Work in Progress)**
+### Syntax validation without rendering
 
-The **mermaid.parse(txt)** function validates graph definitions without rendering a graph. **[This function is still a work in progress](https://github.com/mermaid-js/mermaid/issues/1066), find alternatives below.**
+The `mermaid.parse(text, parseOptions)` function validates graph definitions without rendering a graph.
 
-The function **mermaid.parse(txt)**, takes a text string as an argument and returns true if the definition follows mermaid's syntax and
+The function `mermaid.parse(text, parseOptions)`, takes a text string as an argument and returns `{ diagramType: string }` if the definition follows mermaid's syntax.
-false if it does not. The parseError function will be called when the parse function returns false.
 
-When the parser encounters invalid syntax the **mermaid.parseError** function is called. It is possible to override this
+If the definition is invalid, the function returns `false` if `parseOptions.supressError` is set to `true`. Otherwise, it throws an error.
-function in order to handle the error in an application-specific way.
+
+The parseError function will be called when the parse function throws an error. It will not be called if `parseOptions.supressError` is set to `true`.
+
+It is possible to override this function in order to handle the error in an application-specific way.
 
 The code-example below in meta code illustrates how this could work:
 
@@ -356,26 +358,10 @@ const textFieldUpdated = async function () {
 bindEventHandler('change', 'code', textFieldUpdated);
 ```
 
-**Alternative to mermaid.parse():**
-One effective and more future-proof method of validating your graph definitions, is to paste and render them via the [Mermaid Live Editor](https://mermaid.live/). This will ensure that your code is compliant with the syntax of Mermaid's most recent version.
-
 ## Configuration
 
-Mermaid takes a number of options which lets you tweak the rendering of the diagrams. Currently there are three ways of
+You can pass the required configuration to the `mermaid.initialize` call. This is the preferred way of configuring mermaid.
-setting the options in mermaid.
+The list of configuration objects are described [in the mermaidAPI documentation](./setup/README.md).
-
-1. Instantiation of the configuration using the initialize call
-2. _Using the global mermaid object_ - **Deprecated**
-3. _using the global mermaid_config object_ - **Deprecated**
-4. Instantiation of the configuration using the **mermaid.init** call- **Deprecated**
-
-The list above has two ways too many of doing this. Three are deprecated and will eventually be removed. The list of
-configuration objects are described [in the mermaidAPI documentation](./setup/README.md).
-
-## Using the `mermaidAPI.initialize`/`mermaid.initialize` call
-
-The future proof way of setting the configuration is by using the initialization call to mermaid or mermaidAPI depending
-on what kind of integration you use.
 
 ```html
 <script type="module">
@@ -406,34 +392,3 @@ mermaid.startOnLoad = true;
 ```warning
 This way of setting the configuration is deprecated. Instead the preferred way is to use the initialize method. This functionality is only kept for backwards compatibility.
 ```
-
-## Using the mermaid_config
-
-It is possible to set some configuration via the mermaid object. The two parameters that are supported using this
-approach are:
-
-- mermaid_config.startOnLoad
-- mermaid_config.htmlLabels
-
-```javascript
-mermaid_config.startOnLoad = true;
-```
-
-```warning
-This way of setting the configuration is deprecated. Instead the preferred way is to use the initialize method. This functionality is only kept for backwards compatibility.
-```
-
-## Using the mermaid.init call
-
-To set some configuration via the mermaid object. The two parameters that are supported using this approach are:
-
-- mermaid_config.startOnLoad
-- mermaid_config.htmlLabels
-
-```javascript
-mermaid_config.startOnLoad = true;
-```
-
-```warning
-This way of setting the configuration is deprecated. Instead the preferred way is to use the initialize method. This functionality is only kept for backwards compatibility.
-```

packages/mermaid/src/mermaid.ts

@@ -315,8 +315,8 @@ const executeQueue = async () => {
  * Parse the text and validate the syntax.
  * @param text - The mermaid diagram definition.
  * @param parseOptions - Options for parsing.
- * @returns - If the diagram is valid, returns an object with isValid set to true and the diagramType set to type of the diagram.
+ * @returns An object with the diagramType set to type of the diagram if valid. Otherwise false if parseOptions.suppressErrors is true.
- * @throws Error if the diagram is invalid and parseOptions.suppressErrors is false.
+ * @throws Error if the diagram is invalid and parseOptions.suppressErrors is false or not set.
  */
 const parse = async (text: string, parseOptions?: ParseOptions): Promise<ParseResult | void> => {
   return new Promise((resolve, reject) => {

packages/mermaid/src/mermaidAPI.ts

@@ -62,15 +62,12 @@ export interface ParseOptions {
 
 export type ParseResult =
   | {
-      isValid: true;
       /**
        * The diagram type, e.g. 'flowchart', 'sequence', etc.
        */
       diagramType: string;
     }
-  | {
+  | false;
-      isValid: false;
-    };
 
 // 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.
 export type D3Element = any;
@@ -107,8 +104,8 @@ function processAndSetConfigs(text: string) {
  * Parse the text and validate the syntax.
  * @param text - The mermaid diagram definition.
  * @param parseOptions - Options for parsing.
- * @returns - If the diagram is valid, returns an object with isValid set to true and the diagramType set to type of the diagram.
+ * @returns An object with the diagramType set to type of the diagram if valid. Otherwise false if parseOptions.suppressErrors is true.
- * @throws Error if the diagram is invalid and parseOptions.suppressErrors is false.
+ * @throws Error if the diagram is invalid and parseOptions.suppressErrors is false or not set.
  */
 
 async function parse(text: string, parseOptions?: ParseOptions): Promise<ParseResult> {
@@ -116,10 +113,10 @@ async function parse(text: string, parseOptions?: ParseOptions): Promise<ParseRe
   try {
     const { code } = processAndSetConfigs(text);
     const diagram = await getDiagramFromText(code);
-    return { isValid: true, diagramType: diagram.type };
+    return { diagramType: diagram.type };
   } catch (error) {
     if (parseOptions?.suppressErrors) {
-      return { isValid: false };
+      return false;
     }
     throw error;
   }