From 18079a44bedb09eda7831aaacc5c3b263c97c227 Mon Sep 17 00:00:00 2001 From: Sidharth Vinod Date: Wed, 6 Sep 2023 22:06:05 +0530 Subject: [PATCH] chore: Add deprecation notices, improve types Co-authored-by: Alois Klink --- docs/config/setup/modules/mermaidAPI.md | 2 +- packages/mermaid/src/Diagram.ts | 7 ++++--- packages/mermaid/src/diagram-api/diagramAPI.ts | 3 ++- packages/mermaid/src/diagram-api/types.ts | 7 +++++++ packages/mermaid/src/mermaidAPI.ts | 2 +- packages/mermaid/src/preprocess.ts | 11 +++++++++-- 6 files changed, 24 insertions(+), 8 deletions(-) diff --git a/docs/config/setup/modules/mermaidAPI.md b/docs/config/setup/modules/mermaidAPI.md index 3c2b5bb84..1ea19fac4 100644 --- a/docs/config/setup/modules/mermaidAPI.md +++ b/docs/config/setup/modules/mermaidAPI.md @@ -31,7 +31,7 @@ Renames and re-exports [mermaidAPI](mermaidAPI.md#mermaidapi) ### mermaidAPI -• `Const` **mermaidAPI**: `Readonly`<{ `defaultConfig`: `MermaidConfig` = configApi.defaultConfig; `getConfig`: () => `MermaidConfig` = configApi.getConfig; `getDiagramFromText`: (`text`: `string`, `metadata`: { `title?`: `string` }) => `Promise`<`Diagram`> ; `getSiteConfig`: () => `MermaidConfig` = configApi.getSiteConfig; `globalReset`: () => `void` ; `initialize`: (`options`: `MermaidConfig`) => `void` ; `parse`: (`text`: `string`, `parseOptions?`: [`ParseOptions`](../interfaces/mermaidAPI.ParseOptions.md)) => `Promise`<`boolean`> ; `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; `getDiagramFromText`: (`text`: `string`, `metadata`: `Pick`<`DiagramMetadata`, `"title"`>) => `Promise`<`Diagram`> ; `getSiteConfig`: () => `MermaidConfig` = configApi.getSiteConfig; `globalReset`: () => `void` ; `initialize`: (`options`: `MermaidConfig`) => `void` ; `parse`: (`text`: `string`, `parseOptions?`: [`ParseOptions`](../interfaces/mermaidAPI.ParseOptions.md)) => `Promise`<`boolean`> ; `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 diff --git a/packages/mermaid/src/Diagram.ts b/packages/mermaid/src/Diagram.ts index 3dc973804..b77091f28 100644 --- a/packages/mermaid/src/Diagram.ts +++ b/packages/mermaid/src/Diagram.ts @@ -4,7 +4,7 @@ import { getDiagram, registerDiagram } from './diagram-api/diagramAPI.js'; import { detectType, getDiagramLoader } from './diagram-api/detectType.js'; import { UnknownDiagramError } from './errors.js'; import type { DetailedError } from './utils.js'; -import type { DiagramDefinition } from './diagram-api/types.js'; +import type { DiagramDefinition, DiagramMetadata } from './diagram-api/types.js'; export type ParseErrorFunction = (err: string | DetailedError | unknown, hash?: any) => void; @@ -20,7 +20,7 @@ export class Diagram { private init?: DiagramDefinition['init']; private detectError?: UnknownDiagramError; - constructor(public text: string, public metadata: { title?: string } = {}) { + constructor(public text: string, public metadata: Pick = {}) { this.text += '\n'; const cnf = configApi.getConfig(); try { @@ -72,13 +72,14 @@ export class Diagram { * **Warning:** This function may be changed in the future. * @alpha * @param text - The mermaid diagram definition. + * @param metadata - Diagram metadata, defined in YAML. * @returns A the Promise of a Diagram object. * @throws {@link UnknownDiagramError} if the diagram type can not be found. * @privateRemarks This is exported as part of the public mermaidAPI. */ export const getDiagramFromText = async ( text: string, - metadata: { title?: string } = {} + metadata: Pick = {} ): Promise => { const type = detectType(text, configApi.getConfig()); try { diff --git a/packages/mermaid/src/diagram-api/diagramAPI.ts b/packages/mermaid/src/diagram-api/diagramAPI.ts index 9a4af2585..ea3c10159 100644 --- a/packages/mermaid/src/diagram-api/diagramAPI.ts +++ b/packages/mermaid/src/diagram-api/diagramAPI.ts @@ -57,7 +57,8 @@ export const registerDiagram = ( setupGraphViewbox, getCommonDb(), () => { - // parseDirective is removed. This is a no-op for legacy support. + // parseDirective is removed in https://github.com/mermaid-js/mermaid/pull/4759. + // This is a no-op for legacy support. } ); }; diff --git a/packages/mermaid/src/diagram-api/types.ts b/packages/mermaid/src/diagram-api/types.ts index 4e73d109f..15aa4b033 100644 --- a/packages/mermaid/src/diagram-api/types.ts +++ b/packages/mermaid/src/diagram-api/types.ts @@ -3,6 +3,11 @@ import type { Diagram } from '../Diagram.js'; import type { BaseDiagramConfig, MermaidConfig } from '../config.type.js'; import type * as d3 from 'd3'; +export interface DiagramMetadata { + title?: string; + config?: MermaidConfig; +} + export interface InjectUtils { _log: any; _setLogLevel: any; @@ -10,6 +15,7 @@ export interface InjectUtils { _sanitizeText: any; _setupGraphViewbox: any; _commonDb: any; + /** @deprecated as directives will be pre-processed since https://github.com/mermaid-js/mermaid/pull/4759 */ _parseDirective: any; } @@ -46,6 +52,7 @@ export interface DiagramDefinition { _sanitizeText: InjectUtils['_sanitizeText'], _setupGraphViewbox: InjectUtils['_setupGraphViewbox'], _commonDb: InjectUtils['_commonDb'], + /** @deprecated as directives will be pre-processed since https://github.com/mermaid-js/mermaid/pull/4759 */ _parseDirective: InjectUtils['_parseDirective'] ) => void; } diff --git a/packages/mermaid/src/mermaidAPI.ts b/packages/mermaid/src/mermaidAPI.ts index f71fe27a7..3649b50f5 100644 --- a/packages/mermaid/src/mermaidAPI.ts +++ b/packages/mermaid/src/mermaidAPI.ts @@ -99,7 +99,7 @@ export interface RenderResult { function processAndSetConfigs(text: string) { const processed = preprocessDiagram(text); configApi.reset(); - configApi.addDirective(processed.config); + configApi.addDirective(processed.config ?? {}); return processed; } diff --git a/packages/mermaid/src/preprocess.ts b/packages/mermaid/src/preprocess.ts index 3c33ce30f..6e386e744 100644 --- a/packages/mermaid/src/preprocess.ts +++ b/packages/mermaid/src/preprocess.ts @@ -1,5 +1,6 @@ import { cleanupComments } from './diagram-api/comments.js'; import { extractFrontMatter } from './diagram-api/frontmatter.js'; +import type { DiagramMetadata } from './diagram-api/types.js'; import utils, { cleanAndMerge, removeDirectives } from './utils.js'; const cleanupText = (code: string) => { @@ -44,7 +45,13 @@ const processDirectives = (code: string) => { }; }; -export const preprocessDiagram = (code: string) => { +/** + * Preprocess the given code by cleaning it up, extracting front matter and directives, + * cleaning and merging configuration, and removing comments. + * @param code - The code to preprocess. + * @returns The object containing the preprocessed code, title, and configuration. + */ +export function preprocessDiagram(code: string): DiagramMetadata & { code: string } { const cleanedCode = cleanupText(code); const frontMatterResult = processFrontmatter(cleanedCode); const directiveResult = processDirectives(frontMatterResult.text); @@ -55,4 +62,4 @@ export const preprocessDiagram = (code: string) => { title: frontMatterResult.title, config, }; -}; +}