marcel/mermaid
1
0
Fork 0
mirror of https://github.com/mermaid-js/mermaid.git synced 2025-10-03 22:29:38 +02:00
Code Issues Packages Projects Releases Wiki Activity

refactor: Change return type to retain partial backwards compatibility.

Browse Source
This commit is contained in:
Sidharth Vinod
2023-12-06 22:23:37 +05:30
parent c3c7ccd78a
commit 479188bc40
6 changed files with 40 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/config/setup/interfaces/mermaidAPI.RenderResult.md
View File

@@ -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)

20
docs/config/setup/modules/mermaidAPI.md
View File

@@ -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)

63
docs/config/usage.md
View File

@@ -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
false if it does not. The parseError function will be called when the parse function returns false.
The function `mermaid.parse(text, parseOptions)`, takes a text string as an argument and returns `{ diagramType: string }` if the definition follows mermaid's syntax.
When the parser encounters invalid syntax the **mermaid.parseError** function is called. It is possible to override this
function in order to handle the error in an application-specific way.
If the definition is invalid, the function returns `false` if `parseOptions.supressError` is set to `true`. Otherwise, it throws an error.
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
setting the options in mermaid.
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.
You can pass the required configuration to the `mermaid.initialize` call. This is the preferred way of configuring mermaid.
The list of configuration objects are described [in the mermaidAPI documentation](./setup/README.md).
```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.

65
packages/mermaid/src/docs/config/usage.md
View File

@@ -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
false if it does not. The parseError function will be called when the parse function returns false.
The function `mermaid.parse(text, parseOptions)`, takes a text string as an argument and returns `{ diagramType: string }` if the definition follows mermaid's syntax.
When the parser encounters invalid syntax the **mermaid.parseError** function is called. It is possible to override this
function in order to handle the error in an application-specific way.
If the definition is invalid, the function returns `false` if `parseOptions.supressError` is set to `true`. Otherwise, it throws an error.
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
setting the options in mermaid.
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.
You can pass the required configuration to the `mermaid.initialize` call. This is the preferred way of configuring mermaid.
The list of configuration objects are described [in the mermaidAPI documentation](./setup/README.md).
```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.
```

4
packages/mermaid/src/mermaid.ts
View File

@@ -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.
* @throws Error if the diagram is invalid and parseOptions.suppressErrors is false.
* @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 or not set.
*/
const parse = async (text: string, parseOptions?: ParseOptions): Promise<ParseResult | void> => {
return new Promise((resolve, reject) => {

13
packages/mermaid/src/mermaidAPI.ts
View File

@@ -62,15 +62,12 @@ export interface ParseOptions {
export type ParseResult =
| {
isValid: true;
/**
* The diagram type, e.g. 'flowchart', 'sequence', etc.
*/
diagramType: string;
}
| {
isValid: false;
};
| 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.
* @throws Error if the diagram is invalid and parseOptions.suppressErrors is false.
* @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 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;
}