feat: generate Typescript definitions (#7954)

package-lock.json

@@ -1670,9 +1670,9 @@
       "dev": true
     },
     "@types/node": {
-      "version": "15.0.1",
+      "version": "18.8.3",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-15.0.1.tgz",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-18.8.3.tgz",
-      "integrity": "sha512-TMkXt0Ck1y0KKsGr9gJtWGjttxlZnnvDtphxUOSd0bfaR6Q1jle+sPvrzNR1urqYTWMinoKvjKfXUGsumaO1PA==",
+      "integrity": "sha512-0os9vz6BpGwxGe9LOhgP/ncvYN5Tx1fNcd2TM3rD/aCGBkysb+ZWpXEocG24h6ZzOi13+VB8HndAQFezsSOw1w==",
       "dev": true
     },
     "@types/normalize-package-data": {
@@ -16113,6 +16113,15 @@
         }
       }
     },
+    "videojs-contrib-quality-levels": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/videojs-contrib-quality-levels/-/videojs-contrib-quality-levels-2.2.0.tgz",
+      "integrity": "sha512-r4LFNhjyeBmlGk4Ul43xl+f7sNJ9vFyM6p4NcZNbPlvs1IvykEXCqxvsvaR6KTBjHoHGJnr26grXWcJiLFP+cA==",
+      "requires": {
+        "global": "^4.3.2",
+        "video.js": "^6 || ^7"
+      }
+    },
     "videojs-font": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/videojs-font/-/videojs-font-3.2.0.tgz",

package.json

@@ -5,6 +5,7 @@
   "main": "./dist/video.cjs.js",
   "module": "./dist/video.es.js",
   "style": "./dist/video-js.css",
+  "types": "./dist/types/video.d.ts",
   "copyright": "Copyright Brightcove, Inc. <https://www.brightcove.com/>",
   "license": "Apache-2.0",
   "keywords": [
@@ -25,7 +26,7 @@
     "postclean": "shx mkdir -p ./dist/lang ./test/dist",
     "changelog": "conventional-changelog -p videojs -i CHANGELOG.md -s",
     "build": "npm-run-all build-dev minify copy zip",
-    "build-dev": "npm-run-all clean lint-errors build:js build:css build:lang build:test",
+    "build-dev": "npm-run-all clean lint-errors build:js build:css build:lang build:test build:types",
     "build:test": "npm-run-all build:test:*",
     "build:test:a11y": "shx cp sandbox/descriptions.html.example sandbox/descriptions.test-a11y.html",
     "build:test:browserify": "browserify test/require/browserify.js -o test/dist/browserify.js",
@@ -36,6 +37,7 @@
     "build:js": "rollup -c",
     "build:css": "npm-run-all build:css:*",
     "build:css:cdn": "sass --load-path='./' --load-path='./node_modules/' --no-source-map src/css/vjs-cdn.scss dist/alt/video-js-cdn.css",
+    "build:types": "tsc",
     "postbuild:css:cdn": "postcss --verbose --config postcss.config.js -d dist/alt dist/alt/video-js-cdn.css",
     "build:css:default": "sass --load-path='./' --load-path='./node_modules/' --no-source-map src/css/vjs.scss dist/video-js.css",
     "postbuild:css:default": "postcss --verbose --config postcss.config.js -d dist/ dist/video-js.css",
@@ -52,6 +54,7 @@
     "watch": "npm-run-all -p watch:*",
     "watch:lang": "chokidar --initial 'lang/**/!(zh-Hans|zh-Hant)*.json' -c 'npm run build:lang'",
     "watch:rollup": "rollup -c -w --no-progress",
+    "watch:types": "tsc -w",
     "watch:css": "npm-run-all -p build:css:default build:css:cdn watch:css:*",
     "watch:css:default": "npm run build:css:default -- --watch",
     "watch:css:cdn": "npm run build:css:cdn -- --watch",
@@ -103,6 +106,7 @@
     "@babel/plugin-transform-runtime": "^7.9.0",
     "@babel/preset-env": "^7.9.0",
     "@rollup/plugin-replace": "^2.4.1",
+    "@types/node": "^18.8.3",
     "access-sniff": "^3.2.0",
     "autoprefixer": "^10.2.5",
     "bestzip": "^2.2.0",
@@ -156,6 +160,7 @@
     "shx": "^0.3.2",
     "sinon": "^11.1.1",
     "tui-jsdoc-template": "^1.2.2",
+    "typescript": "^4.8.4",
     "uglify-js": "^3.6.0",
     "unified": "^7.0.2",
     "videojs-generate-karma-config": "^8.0.1",

src/js/component.js

@@ -25,7 +25,7 @@ class Component {
 
   /**
    * A callback that is called when a component is ready. Does not have any
-   * paramters and any callback value will be ignored.
+   * parameters and any callback value will be ignored.
    *
    * @callback Component~ReadyCallback
    * @this Component
@@ -700,6 +700,9 @@ class Component {
    * Different from event listeners in that if the ready event has already happened
    * it will trigger the function immediately.
    *
+   * @param {Component~ReadyCallback} fn
+   *        Function that gets called when the `Component` is ready.
+   *
    * @return {Component}
    *         Returns itself; method can be chained.
    */

src/js/event-target.js

@@ -4,6 +4,8 @@
 import * as Events from './utils/events.js';
 import window from 'global/window';
 
+let EVENT_MAP;
+
 /**
  * `EventTarget` is a class that can have the same API as the DOM `EventTarget`. It
  * adds shorthand functions that wrap around lengthy functions. For example:
@@ -12,39 +14,7 @@ import window from 'global/window';
  * @see [EventTarget Spec]{@link https://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-EventTarget}
  * @class EventTarget
  */
-const EventTarget = function() {};
+class EventTarget {
-
-/**
- * A Custom DOM event.
- *
- * @typedef {Object} EventTarget~Event
- * @see [Properties]{@link https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent}
- */
-
-/**
- * All event listeners should follow the following format.
- *
- * @callback EventTarget~EventListener
- * @this {EventTarget}
- *
- * @param {EventTarget~Event} event
- *        the event that triggered this function
- *
- * @param {Object} [hash]
- *        hash of data sent during the event
- */
-
-/**
- * An object containing event names as keys and booleans as values.
- *
- * > NOTE: If an event name is set to a true value here {@link EventTarget#trigger}
- *         will have extra functionality. See that function for more information.
- *
- * @property EventTarget.prototype.allowedEvents_
- * @private
- */
-EventTarget.prototype.allowedEvents_ = {};
-
   /**
    * Adds an `event listener` to an instance of an `EventTarget`. An `event listener` is a
    * function that will get called when an event with a certain name gets triggered.
@@ -55,7 +25,7 @@ EventTarget.prototype.allowedEvents_ = {};
    * @param {EventTarget~EventListener} fn
    *        The function to call with `EventTarget`s
    */
-EventTarget.prototype.on = function(type, fn) {
+  on(type, fn) {
     // Remove the addEventListener alias before calling Events.on
     // so we don't get into an infinite type loop
     const ael = this.addEventListener;
@@ -63,17 +33,7 @@ EventTarget.prototype.on = function(type, fn) {
     this.addEventListener = () => { };
     Events.on(this, type, fn);
     this.addEventListener = ael;
-};
+  }
-
-/**
- * An alias of {@link EventTarget#on}. Allows `EventTarget` to mimic
- * the standard DOM API.
- *
- * @function
- * @see {@link EventTarget#on}
- */
-EventTarget.prototype.addEventListener = EventTarget.prototype.on;
-
   /**
    * Removes an `event listener` for a specific event from an instance of `EventTarget`.
    * This makes it so that the `event listener` will no longer get called when the
@@ -85,19 +45,9 @@ EventTarget.prototype.addEventListener = EventTarget.prototype.on;
    * @param {EventTarget~EventListener} fn
    *        The function to remove.
    */
-EventTarget.prototype.off = function(type, fn) {
+  off(type, fn) {
     Events.off(this, type, fn);
-};
+  }
-
-/**
- * An alias of {@link EventTarget#off}. Allows `EventTarget` to mimic
- * the standard DOM API.
- *
- * @function
- * @see {@link EventTarget#off}
- */
-EventTarget.prototype.removeEventListener = EventTarget.prototype.off;
-
   /**
    * This function will add an `event listener` that gets triggered only once. After the
    * first trigger it will get removed. This is like adding an `event listener`
@@ -109,7 +59,7 @@ EventTarget.prototype.removeEventListener = EventTarget.prototype.off;
    * @param {EventTarget~EventListener} fn
    *        The function to be called once for each event name.
    */
-EventTarget.prototype.one = function(type, fn) {
+  one(type, fn) {
     // Remove the addEventListener aliasing Events.on
     // so we don't get into an infinite type loop
     const ael = this.addEventListener;
@@ -117,9 +67,8 @@ EventTarget.prototype.one = function(type, fn) {
     this.addEventListener = () => { };
     Events.one(this, type, fn);
     this.addEventListener = ael;
-};
+  }
-
+  any(type, fn) {
-EventTarget.prototype.any = function(type, fn) {
     // Remove the addEventListener aliasing Events.on
     // so we don't get into an infinite type loop
     const ael = this.addEventListener;
@@ -127,8 +76,7 @@ EventTarget.prototype.any = function(type, fn) {
     this.addEventListener = () => { };
     Events.any(this, type, fn);
     this.addEventListener = ael;
-};
+  }
-
   /**
    * This function causes an event to happen. This will then cause any `event listeners`
    * that are waiting for that event, to get called. If there are no `event listeners`
@@ -145,7 +93,7 @@ EventTarget.prototype.any = function(type, fn) {
    *        The name of the event, an `Event`, or an object with a key of type set to
    *        an event name.
    */
-EventTarget.prototype.trigger = function(event) {
+  trigger(event) {
     const type = event.type || event;
 
     // deprecation
@@ -163,20 +111,8 @@ EventTarget.prototype.trigger = function(event) {
     }
 
     Events.trigger(this, event);
-};
+  }
-
+  queueTrigger(event) {
-/**
- * An alias of {@link EventTarget#trigger}. Allows `EventTarget` to mimic
- * the standard DOM API.
- *
- * @function
- * @see {@link EventTarget#trigger}
- */
-EventTarget.prototype.dispatchEvent = EventTarget.prototype.trigger;
-
-let EVENT_MAP;
-
-EventTarget.prototype.queueTrigger = function(event) {
     // only set up EVENT_MAP if it'll be used
     if (!EVENT_MAP) {
       EVENT_MAP = new Map();
@@ -207,6 +143,65 @@ EventTarget.prototype.queueTrigger = function(event) {
     }, 0);
 
     map.set(type, timeout);
-};
+  }
+}
+
+/**
+ * A Custom DOM event.
+ *
+ * @typedef {EventTarget} Event
+ * @see [Properties]{@link https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent}
+ */
+
+/**
+ * All event listeners should follow the following format.
+ *
+ * @callback EventTarget~EventListener
+ * @this {EventTarget}
+ *
+ * @param {EventTarget~Event} event
+ *        the event that triggered this function
+ *
+ * @param {Object} [hash]
+ *        hash of data sent during the event
+ */
+
+/**
+ * An object containing event names as keys and booleans as values.
+ *
+ * > NOTE: If an event name is set to a true value here {@link EventTarget#trigger}
+ *         will have extra functionality. See that function for more information.
+ *
+ * @property EventTarget.prototype.allowedEvents_
+ * @private
+ */
+EventTarget.prototype.allowedEvents_ = {};
+
+/**
+ * An alias of {@link EventTarget#on}. Allows `EventTarget` to mimic
+ * the standard DOM API.
+ *
+ * @function
+ * @see {@link EventTarget#on}
+ */
+EventTarget.prototype.addEventListener = EventTarget.prototype.on;
+
+/**
+ * An alias of {@link EventTarget#off}. Allows `EventTarget` to mimic
+ * the standard DOM API.
+ *
+ * @function
+ * @see {@link EventTarget#off}
+ */
+EventTarget.prototype.removeEventListener = EventTarget.prototype.off;
+
+/**
+ * An alias of {@link EventTarget#trigger}. Allows `EventTarget` to mimic
+ * the standard DOM API.
+ *
+ * @function
+ * @see {@link EventTarget#trigger}
+ */
+EventTarget.prototype.dispatchEvent = EventTarget.prototype.trigger;
 
 export default EventTarget;

src/js/fullscreen-api.js

@@ -1,7 +1,6 @@
 /**
  * @file fullscreen-api.js
  * @module fullscreen-api
- * @private
  */
 import document from 'global/document';
 

src/js/menu/menu-keys.js

@@ -6,6 +6,7 @@
   * All keys used for operation of a menu (`MenuButton`, `Menu`, and `MenuItem`)
   * Note that 'Enter' and 'Space' are not included here (otherwise they would
   * prevent the `MenuButton` and `MenuItem` from being keyboard-clickable)
+ *
   * @typedef MenuKeys
   * @array
   */

src/js/resize-manager.js

@@ -14,6 +14,7 @@ import Component from './component.js';
  *
  * If the ResizeObserver is available natively, it will be used. A polyfill can be passed in as an option.
  * If a `playerresize` event is not needed, the ResizeManager component can be removed from the player, see the example below.
+ *
  * @example <caption>How to disable the resize manager</caption>
  * const player = videojs('#vid', {
  *   resizeManager: false

src/js/tech/html5.js

@@ -28,7 +28,7 @@ class Html5 extends Tech {
   * @param {Object} [options]
   *        The key/value store of player options.
   *
-  * @param {Component~ReadyCallback} ready
+  * @param {Component~ReadyCallback} [ready]
   *        Callback function to call when the `HTML5` Tech is ready.
   */
   constructor(options, ready) {

src/js/tech/tech.js

@@ -88,7 +88,7 @@ class Tech extends Component {
   * @param {Object} [options]
   *        The key/value store of player options.
   *
-  * @param {Component~ReadyCallback} ready
+  * @param {Component~ReadyCallback} [ready]
   *        Callback function to call when the `HTML5` Tech is ready.
   */
   constructor(options = {}, ready = function() {}) {

src/js/tracks/html-track-element.js

@@ -5,16 +5,6 @@
 import EventTarget from '../event-target';
 import TextTrack from '../tracks/text-track';
 
-/**
- * @memberof HTMLTrackElement
- * @typedef {HTMLTrackElement~ReadyState}
- * @enum {number}
- */
-const NONE = 0;
-const LOADING = 1;
-const LOADED = 2;
-const ERROR = 3;
-
 /**
  * A single track represented in the DOM.
  *
@@ -98,14 +88,14 @@ class HTMLTrackElement extends EventTarget {
       }
     });
 
-    readyState = NONE;
+    readyState = HTMLTrackElement.NONE;
 
     /**
      * @listens TextTrack#loadeddata
      * @fires HTMLTrackElement#load
      */
     track.addEventListener('loadeddata', () => {
-      readyState = LOADED;
+      readyState = HTMLTrackElement.LOADED;
 
       this.trigger({
         type: 'load',
@@ -119,9 +109,36 @@ HTMLTrackElement.prototype.allowedEvents_ = {
   load: 'load'
 };
 
-HTMLTrackElement.NONE = NONE;
+/**
-HTMLTrackElement.LOADING = LOADING;
+ * The text track not loaded state.
-HTMLTrackElement.LOADED = LOADED;
+ *
-HTMLTrackElement.ERROR = ERROR;
+ * @type {number}
+ * @static
+ */
+HTMLTrackElement.NONE = 0;
+
+/**
+ * The text track loading state.
+ *
+ * @type {number}
+ * @static
+ */
+HTMLTrackElement.LOADING = 1;
+
+/**
+ * The text track loaded state.
+ *
+ * @type {number}
+ * @static
+ */
+HTMLTrackElement.LOADED = 2;
+
+/**
+ * The text track failed to load state.
+ *
+ * @type {number}
+ * @static
+ */
+HTMLTrackElement.ERROR = 3;
 
 export default HTMLTrackElement;

src/js/video.js

@@ -49,6 +49,13 @@ import { use as middlewareUse, TERMINATOR } from './tech/middleware.js';
  */
 const normalizeId = (id) => id.indexOf('#') === 0 ? id.slice(1) : id;
 
+/**
+ * A callback that is called when a component is ready. Does not have any
+ * parameters and any callback value will be ignored. See: {@link Component~ReadyCallback}
+ *
+ * @callback ReadyCallback
+ */
+
 /**
  * The `videojs()` function doubles as the main function for users to create a
  * {@link Player} instance as well as the main library namespace.
@@ -110,7 +117,7 @@ const normalizeId = (id) => id.indexOf('#') === 0 ? id.slice(1) : id;
  *         Options object for providing settings.
  *         See: [Options Guide](https://docs.videojs.com/tutorial-options.html).
  *
- * @param  {Component~ReadyCallback} [ready]
+ * @param  {ReadyCallback} [ready]
  *         A function to be called when the {@link Player} and {@link Tech} are
  *         ready.
  *

tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "include": ["src/js/**/*"],
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "dist/types",
+    "declarationMap": true,
+    "skipLibCheck": true,
+    "checkJs": false,
+    "preserveWatchOutput": true
+  }
+}