Add first-party Typescript support

[maxkfranz]

Cross-references to related issues. If there is no existing issue that describes your bug or feature request, then create an issue before making your pull request.

Associated issues:

• First-party Typescript support #3306
• Initial, experimental WebGL rendering support #3305

Notes re. the content of the pull request. Give context to reviewers or serve as a general record of the changes made. Add a screenshot or video to demonstrate your new feature, if possible.

• Adds the community Typescript definition file from DefinitelyTyped and improves it to cover API that the community definition file is currently missing.
• Updates the package.json file to point to the index.d.ts definition file so that Typescript projects that import cytoscape will use the latest definition file.
• This will make it easier for external contributors to make contributions to the definition file, as it has higher visibility in the main Cytoscape repo.
• When new API is introduced in the library, the Typescript definition file should be accordingly updated. The PR issue template has been updated with a reminder for this.
• This includes the provisional/experimental WebGL API (Initial, experimental WebGL rendering support #3305).
• Note: This doesn't cover extensions. Extensions will have to be covered separately.

Checklist

Author:

• The proper base branch has been selected. New features go on unstable. Bug-fix patches can go on either unstable or master.
• Automated tests have been included in this pull request, if possible, for the new feature(s) or bug fix. Check this box if tests are not pragmatically possible (e.g. rendering features could include screenshots or videos instead of automated tests).
• The associated GitHub issues are included (above).
• Notes have been included (above).

Reviewers:

• All automated checks are passing (green check next to latest commit).
• At least one reviewer has signed off on the pull request.
• For bug fixes: Just after this pull request is merged, it should be applied to both the master branch and the unstable branch. Normally, this just requires cherry-picking the corresponding merge commit from master to unstable -- or vice versa.

[maxkfranz]

@d2fong, since you have a lot of TS experience I've added you as a reviewer to this PR. Since this is an update of the already-working community definition file, I don't expect any major issues -- but please let us know if you notice any red flags or best practices that aren't being followed. Thanks

[maxkfranz]

@mikekucera, I've cleaned up the commits for this PR so your WebGL API is in a separate commit (3a9c3a1). Let me know if you notice any discrepancies, or if you plan to change the API before the release. Thanks

[mikekucera]

Hi Max, I'd love to give this a proper review, but that might take some time since its a big file and I'm new to TypeScript. Are you ok with waiting for a review from me?

[maxkfranz]

Sounds good

[d2fong]

@maxkfranz I reviewed the specific commits that include your additions to the community ts file. I don't see anything that looks out of place. How would you recommend that I test this out? If I install this branch in cytoscape-web, does this mean we shouldn't need to use the @types/cytoscape package anymore?

[mikekucera]

I skimmed the file and made some minor comments. The file is quite large and I'm new to TypeScript so I can't really comment on if the overall structure of all the type definitions are correct. My recommendation is to somehow mark the entire file as provisional so that we can fix any problems when the community finds them. We don't want to be locked into an API like we are with Cytoscape Java, at least until this file gets a decent amount of use from the community.

[maxkfranz]

@maxkfranz I reviewed the specific commits that include your additions to the community ts file. I don't see anything that looks out of place. How would you recommend that I test this out? If I install this branch in cytoscape-web, does this mean we shouldn't need to use the @types/cytoscape package anymore?

Yes, that's right.

You'd need to have package.json point to the branch:

"cytoscape": "https://github.com/cytoscape/cytoscape.js.git#feature/1st-party-ts"

Or if you want to point to a local dir, e.g.:

"cytoscape": "../cytoscape.js"

[maxkfranz]

My recommendation is to somehow mark the entire file as provisional so that we can fix any problems when the community finds them. We don't want to be locked into an API like we are with Cytoscape Java, at least until this file gets a decent amount of use from the community.

How about this?

• Add a comment block at the top of the file with the warning
• Add a warning in the top-level Cytoscape() constructor
• And as we discussed before: Add a warning/note in the release announcement blog post
• I'll double check that this is clear in the issue as well

[maxkfranz]

@mikekucera @d2fong

I've responded to the comments. Thanks for your thoughts.

Let me know what you think, and then I'll go ahead and make the planned changes.

[maxkfranz]

I'm going to resolve the comment threads for which we've decided what to do. I'll leave open the ones that may need more discussion.

[maxkfranz]

My recommendation is to somehow mark the entire file as provisional so that we can fix any problems when the community finds them. We don't want to be locked into an API like we are with Cytoscape Java, at least until this file gets a decent amount of use from the community.

How about this?

• Add a comment block at the top of the file with the warning
• Add a warning in the top-level Cytoscape() constructor
• And as we discussed before: Add a warning/note in the release announcement blog post
• I'll double check that this is clear in the issue as well

@mikekucera

Just bumping this in case you missed it. The thread is pretty long

[mikekucera]

My recommendation is to somehow mark the entire file as provisional so that we can fix any problems when the community finds them. We don't want to be locked into an API like we are with Cytoscape Java, at least until this file gets a decent amount of use from the community.

How about this?

• Add a comment block at the top of the file with the warning
• Add a warning in the top-level Cytoscape() constructor
• And as we discussed before: Add a warning/note in the release announcement blog post
• I'll double check that this is clear in the issue as well

@mikekucera

Just bumping this in case you missed it. The thread is pretty long

Sounds good.

[maxkfranz]

Great, thanks

[maxkfranz]

@mikekucera @d2fong

I've made all your suggested changes in the latest commits. I'll merge this in on Monday, and then I'll make the release.