fix(types): Adds track and track list types to typescript exports #8486
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
We love Video.js where I work and are currently using TypeScript. There are several areas where the TypeScript support for Video.js is lacking, even to the point of some of the guides on the website not being able to be compiled by TypeScript).
Currently, the guides around Tracks and Track list (like Audio Tracks for example: https://videojs.com/guides/audio-tracks/#listen-for-an-audio-track-becoming-enabled) can't be used out of the box with video.js and TypeScript. This PR doesn't fully address the issue of not being able to use the code verbatim, but it exposes the main types that will better unblock TypeScript developers on using these scenarios.
I kept the changes small to try to keep any conversation focused before moving on to other missing issues. This has come up in other issues: #8466.
Many of the issues I see are around either: types that weren't exported from the package (and hence, can't be referenced/used from TypeScript code), or from JSDoc comments that aren't attached to any specific variable or type (and hence, it's picked up by the TypeScript compiler when generating outgoing types).
Usable (and shown in code completion) by TypeScript in VSCode.
JSDocs on website still show correct types (some changes that TypeScript wanted resulted in a changing of the types displayed in the JSDoc website, so I explicitly did NOT do any of those changes in this PR without any further discussion).
The change exposes the types just like Player and others that were already exposed in video.js. This allows the specific list types to be referenced and used like this in TypeScript:
This would have failed before as the Player type didn't export
audioTracks
/textTracks
/videoTracks
, and video.js also didn't expose the matching*List
types either which made proper isolated testing in TypeScript much more difficult without jumping through hoops and creating our own types definitions.Hopefully these will be fairly non-controversial.
Specific Changes proposed
This first proposed change is based on a quick fix mentioned in the thread above: #8466.
The change resolves around these specific elements:
Add placeholder prototypes before the
videoTracks
/audioTracks
/textTracks
are added to the prototypeTypeScript compiler doesn't appear to pull JSDoc comments unless they are attached to something in the abstract syntax tree instead of floating in space.
Export specific track types from their files and reference those types via
import
of JSDocThis is so TypeScript pulls them in when generating types. Leaving it just
AudioTrackList
like before resulted in the TypeScript compiler just generating theaudioTracks
/videoTracks
/etc. properties as returningany
from their methods.There's a different way this can be done by importing the types, but it appears to then export them as well from the player.js file. That felt like a side-effect that wouldn't be appreciated, so I tried this less invasive way to keep the JavaScript interface as identical as possible from before.
I also ensured the above change doesn't break existing JSDoc documentation published to the website by generating the docs and exploring them locally.
Export those newly exported types via src/js/video.js so they are exported and usable from TypeScript
Other Notes
There are some other changes needed around the TrackList to let it work out of the box from TypeScript (as there are issues around it not being documented as ArrayLike for looping over returned tracks). Those changes were starting to be a bit more invasive though, so I saved those for later and focused on just exposing these core types.
Obviously, feedback is most welcome :).
Requirements Checklist