[DOC] Document the lowest TypeScript version supported by bpmn-visualization

[tbouffard]

Current situation

bpmn-visualization follows the TypeScript evolution and the dependency is often updated to use the latest available version.
So in the code, we introduce the usage of new TS features. For instance

• override keyword for override methods (TS 4.3): https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-3.html#override-and-the---noimplicitoverride-flag in bpmn-visuailzation@0.17.1, see [REFACTOR] Make override methods explicit #1415
• type Modifiers on Import Names (TS 4.5): https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names in bpmn-visuailzation@0.21.0, see [REFACTOR] Explicit mxgraph type imports #1666

The new TS keywords or types can then be present in the type definition files that are included in the npm package which TS forces project integrating bpmn-visualization to use a compatible version of TS.
For instance, in bpmn-visualization@0.26.1, the BpmnVisualization class declare an import with both a type and a value

import { version, type Version } from './version';

The resulting import in the definition file looks like:

import { type Version } from './version';

This means that the minimum version of TS to use for integration is at least version 4.5 (a newest version may be needed, the analysis is not complete here).

We don't document this requirement and we don't even know what the minimal TS version is as we don't test it. We have example projects that use TS but they also use the latest available version, so they cannot be used to detect it.
That's why we discover that users are stuck like in #2221 and must use an old bpmn-visualization version.

What we know today

• bpmn-visualization@0.26.1 is built with typescript@4.8.2 https://github.com/process-analytics/bpmn-visualization-js/blob/v0.26.1/package.json#L150
• projects in examples using v0.26.1 works with typescript@4.7.4 https://github.com/process-analytics/bpmn-visualization-examples/blob/v0.26.1/projects/typescript-vanilla-with-vitejs/package.json#L15

Notice that these projects are not using all bpmn-visualization API so they may not detect some type issues.

Proposal

I propose that we detect what is the minimal TS needed to use bpmn-visualization and that we document it. Remember that bpmn-visualization also depends on typed-mxgraph that has its own TS requirement. Currently, bpmn-visualization@0.26.1 depends on typed-mxgraph@1.0.7 which depends on TypeScript 4.1.3.
By documenting, I mean this must be explicit and if possible, usage of an old version should produce an error in the projects integrating bpmn-visualization. Just documenting it in the README won't be enough.

We should also have clear policies about TS bump requirements and we should communicate at least about it in the release notes when it appears. This may not be related to the TypeScript version bump, just to the new TypeScript features we use.

Macro tasks

Detect the lowest TS version

[2022-09-16] It is TS 4.5 for bpmn-visualization@0.26.1

Declare the lowest TS version

• typesVersions field in package.json: https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html#version-selection-with-typesversions, starting from TS 3.1
• Specifying supported TypeScript versions microsoft/TypeScript#32166 for better error management (not implemented), the issue provides workarounds
• used workarounds
  • https://github.com/graphql/graphql-js/blob/743f42b6ef6006d35bf9e0b45e3b70d6e9100596/package.json#L7-L13
  • TypeScript <3.4 support sindresorhus/execa#336

Automatic tests
Once we know the version, we should add automatic tests that ensure that we don't need a more recent version. We could check DefinitivelyType for inspiration.

• https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dtslint
• https://github.com/SamVerschueren/tsd

We could create a TS project on the fly and check TS compilation (this was done like this in Jest prior v26) or with a static project within the bpmn-visualization repository:

• removed in https://github.com/facebook/jest/pull/9823/files
• See "verify-old-ts": "node ./scripts/verifyOldTs.js",https://github.com/SimenB/jest/blob/8313797aa661dabd035b65705fb4864ac94c06a5/scripts/verifyOldTs.js

We could run the automatic check in the workflow that produces the npm package: the project needs types stored in the npm package, so we could run the test after the package artifact upload.

Tasks

• Update the projects in the examples repository and make them use the lowest TypeScript version: [FEAT] Use the lowest possible version of TypeScript in projects bpmn-visualization-examples#385
• Update the README to explicit the lowest TS version to use for integration: [DOC] README indicates the lowest supported TypeScript version #2251
• Update package.json to explicit the lowest TS version: [FEAT] Explicit error message when using too old TypeScript versions #2272
• Add automatic tests: [FEAT] Simplify the integration in TypeScript project #2258
• clarify/document how we will change the lowest supported TS version: [FEAT] Explicit error message when using too old TypeScript versions #2272