chore: Deprecate mermaidAPI

[sidharthv96]

📑 Summary

Deprecates the use of mermaidAPI.
Update docs to remove references to mermaidAPI.
Add docs for mermaid object.

mermaid.parse and mermaid.render should be used instead of mermaid.mermaidAPI.parse and mermaid.mermaidAPI.render.

📏 Design Decisions

Using MermaidAPI directly could cause issues, and making it internal lets us make changes easily.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🔖 targeted develop branch

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	c1052bd
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/667d5ca54810400008d54789
😎 Deploy Preview	https://deploy-preview-4821--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codecov]

Codecov Report

Attention: Patch coverage is 5.55556% with 17 lines in your changes missing coverage. Please review.

Project coverage is 5.74%. Comparing base (ba0d91d) to head (c1052bd).

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #4821   +/-   ##
=======================================
  Coverage     5.73%   5.74%           
=======================================
  Files          279     280    +1     
  Lines        42022   41932   -90     
  Branches       517     492   -25     
=======================================
- Hits          2409    2408    -1     
+ Misses       39613   39524   -89     

Flag	Coverage Δ
unit	5.74% <5.55%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
packages/mermaid/src/utils.ts	41.54% <100.00%> (-0.07%)	⬇️
packages/mermaid/src/accessibility.ts	0.00% <0.00%> (ø)
packages/mermaid/src/diagrams/mindmap/mindmapDb.ts	0.00% <0.00%> (ø)
...es/mermaid/src/diagrams/mindmap/mindmapRenderer.ts	0.00% <0.00%> (ø)
packages/mermaid/src/diagrams/mindmap/svgDraw.ts	0.00% <0.00%> (ø)
packages/mermaid/src/mermaidAPI.ts	0.00% <0.00%> (ø)
packages/mermaid/src/mermaid.ts	0.00% <0.00%> (ø)

... and 1 file with indirect coverage changes

[aloisklink]

Deprecating the init, mermaidAPI.render, mermaidAPI.initialize, mermaidAPI.parse functions make sense to me, although I'm uncertain if it makes sense to deprecate the entire mermaidAPI object. My comments:

• Instead of @deprecate-ing the entire mermaidAPI object, would it make more sense to just @deprecate mermaidAPI.render and mermaidAPI.initialize and mermaidAPI.parse? The other functions in mermaidAPI don't seem to have replacements (and if they do have replacements, it's probably easier to describe the replacements in a separate @deprecated Use <...> instead line).

• We shouldn't mark the mermaidAPI as @internal if it might be being used by third-parties. Using @internal might even hide the @deprecated warning for users.

• If we're @deprecate-ing functions that may be used by people (and I think it's likely that some people are using these functions), we might want to hold back on deprecating these functions until a v11 release.
  The eslint-plugin-deprecation has 350,000 weekly downloads, so it's quite possible that adding @deprecated will be a breaking change for some users.

  Although, SemVer just states we should make a MINOR release for deprecations, so 🤷, maybe it's overkill to wait until a MAJOR release.

• We probably should also make a Deprecation label for this PR, and add a Deprecated entry in https://github.com/mermaid-js/mermaid/blob/develop/.github/release-drafter.yml.

[sidharthv96]

Instead of @deprecate-ing the entire mermaidAPI object, would it make more sense to just @deprecate mermaidAPI.render and mermaidAPI.initialize and mermaidAPI.parse? The other functions in mermaidAPI don't seem to have replacements (and if they do have replacements, it's probably easier to describe the replacements in a separate @deprecated Use <...> instead line).

Only getDiagramFromText and globalReset seems like the candidate to expose (via mermaid.ts) in the rest of mermaidAPI.
Everything regarding setting config can be handled by initialize.

The intention is to provide mermaid.ts as the only "official" entrypoint into mermaid, so that we have more flexibility internally to change things, while keeping the public API stable (with low surface area).

[knsv]

Instead of @deprecate-ing the entire mermaidAPI object, would it make more sense to just @deprecate mermaidAPI.render and mermaidAPI.initialize and mermaidAPI.parse? The other functions in mermaidAPI don't seem to have replacements (and if they do have replacements, it's probably easier to describe the replacements in a separate @deprecated Use <...> instead line).

Only getDiagramFromText and globalReset seems like the candidate to expose (via mermaid.ts) in the rest of mermaidAPI. Everything regarding setting config can be handled by initialize.

The intention is to provide mermaid.ts as the only "official" entrypoint into mermaid, so that we have more flexibility internally to change things, while keeping the public API stable (with low surface area).

We turned it around then. The idea with the mermaidAPI was to have one entry point into Mermaid, which users using their own bootstraps/integrations could use. The mermaid.js was just one reference implementation.

I am little concerned by the potentially braking change though. This might be better in v11

[aloisklink]

Instead of @deprecate-ing the entire mermaidAPI object, would it make more sense to just @deprecate mermaidAPI.render and mermaidAPI.initialize and mermaidAPI.parse? The other functions in mermaidAPI don't seem to have replacements (and if they do have replacements, it's probably easier to describe the replacements in a separate @deprecated Use <...> instead line).

Only getDiagramFromText and globalReset seems like the candidate to expose (via mermaid.ts) in the rest of mermaidAPI. Everything regarding setting config can be handled by initialize.

The intention is to provide mermaid.ts as the only "official" entrypoint into mermaid, so that we have more flexibility internally to change things, while keeping the public API stable (with low surface area).

There doesn't seem to be any replacements for mermaid.mermaidAPI.getConfig, but I don't think we need one. Just in case, we should probably do something like:

/**
 * {@inheritDoc ./config.js:getConfig} // not sure if this syntax will work?
 * @deprecated This function may be removed in the future.
 *             Please comment in <GH discussion thread> if you use this feature.
 */
function getConfig() {
  return getConfig();
}

I could see mermaid.mermaidAPI.defaultConfig being useful? E.g. somebody might do something like the following, in order to add their own custom secure keys to the MermaidConfig:

mermaid.initialize({
  secure: [
    ...myCustomSecureFields,
    ...mermaid.mermaidAPI.defaultConfig.secure,
  ],
});

[sidharthv96]

@aloisklink we can add those if someone requests those, we are only deprecating mermaidAPI, not removing it completely. Otherwise, we're increasing our surface area, which will make future changes trickier.

[aloisklink]

@aloisklink we can add those if someone requests those, we are only deprecating mermaidAPI, not removing it completely. Otherwise, we're increasing our surface area, which will make future changes trickier.

In that case, I think we definitely need to at least improve the deprecation message, e.g. explaining that if parse() and render() doesn't cover somebody's use case, they should comment on a GitHub discussion.

A quick search of MermaidApi.getConfig on GitHub shows 152 matches, so I think there is a good chance people may request it.

My gut feeling is also to add a @deprecated message to each function in mermaidAPI as well, but I don't know enough about TypeScript tooling to know if a @deprecated message just on the mermaidAPI object is sufficient.

And we need to remove the @internal flag, otherwise they might not even see the deprecation message!

[knsv]

Ha from the beginning the mermaidAPI was intended to be the official API to use mermaid. The mermaid bootstrap was one reference implementation suing the API.

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Jun 27, 2024, 12:46 PM