feat: add type declarations to distro

[MartyDashP]

Proposed Changes

Add type declarations to distribution package

Checklist

To ensure you provided everything we need to look at your PR:

• Brief textual description of the changes present
• Visual demo attached
• Steps to try out present, i.e. using the @bpmn-io/sr tool
• Related issue linked via Closes {LINK_TO_ISSUE} or Related to {LINK_TO_ISSUE}

[CLAassistant]

All committers have signed the CLA.

[MartyDashP]

I think this improvement will make it easier to work with moddle when developing extensions for bpmn-js.

[nikku]

@MartyDashP Thanks for your contribution 🚀

This PR fits well into our ongoing initiatives to offer types for our libraries.

---

As a matter of fact, exported types are a contract, an we need to ensure that we have tests for them; understand when they break accidentally, but also to show proposed use (example). Could you investigate a way how to add such tests for the generated types?

Some learnings from typing some of our core libraries (diagram-js, bpmn-js):

• A good pattern is to have a FileName.spec.ts file next to the actual JS file (example), and do a tsc --noEmit run to verify the declarations generated work as intended.
• To consider: What format do the type definitions have, are they clean? If not then bio-dts is a helpful tool to ensure the resulting type definitions are meaningful, and clean.

[nikku]

We need test coverage for any types that we generate. Added some thoughts.

[MartyDashP]

@nikku Thank for the feedback. I'll try to cover all exported types with tests. I can't promise that it will be done quickly, but I will do my best 😀

[nikku]

@MartyDashP I had a look at the PR, good bunch of TS magic! Find some adjustments pushed onto the branch, including proper integration into the overall library build + publishing.

I see that you heavily use expectType, which works, but in the end does not properly capture real world use. And these types, first and foremost have to be meaningful in the real world, hence we prefer that style of testing. Find one example here.

A few follow-ups we'd need if we wanted to incorporate it into the library:

• The actual library (moddle) is not type-tested at all, and so isn't more complex descriptors
• Optional vs. required properties: Right now every property is required (or always provided), which is not necessarily true (06a387d). We want to assess how that pans out in a real-world scenario, and if this is the right level of support we want to offer.

Probably next step is to get these real world examples incorporated (tests against moddle public API), or type some of our unit tests to verify current uses against the schema.

[MartyDashP]

@nikku I tried to cover all the public APIs with tests and hopefully took into account all the mentioned comments 🙂

[nikku]

Thanks for your updates. Hope to be able to look into this PR again, this week.

[MartyDashP]

@nikku 👋 Were you able to review my pull request? Do you have any comments or suggestions? 😀

[nikku]

@MartyDashP Sorry for leaving your PR hanging for so long.

Types are public API, and these types specifically are at the core of our tool stack. I need to put extra effort and attention to this before merging. Scheduled something after Easter 🤞, and rest assured, I want to see this merged, because it will super-power our users.

[nikku]

Need to get back to this PR 🙈, related to bpmn-io/dmn-moddle#31.