feat: add Flowtype

BREAKING CHANGE:

Some internal and deprecated methods have been removed from the abstraction. By the looks of it, it doesn’t break anything. Making the breaking change just in case (as it is a risky change).

Author: gajus

.babelrc

@@ -2,7 +2,7 @@
   "plugins": [
     "lodash",
     "transform-object-rest-spread",
-    "transform-flow-comments",
+    "transform-flow-strip-types",
     "transform-runtime",
     "add-module-exports"
   ],

.flowconfig

@@ -0,0 +1,7 @@
+[ignore]
+.*/node_modules/.*/test/.*
+.*/node_modules/babel-plugin-flow-runtime/.*
+.*/node_modules/config-chain/.*
+.*/node_modules/conventional-changelog-core/.*
+.*/node_modules/flow-runtime/.*
+.*/node_modules/npmconf/.*

package.json

@@ -22,14 +22,16 @@
     "babel-cli": "^6.24.1",
     "babel-plugin-add-module-exports": "^0.2.1",
     "babel-plugin-lodash": "^3.2.11",
-    "babel-plugin-transform-flow-comments": "^6.22.0",
+    "babel-plugin-transform-flow-strip-types": "^6.22.0",
     "babel-plugin-transform-object-rest-spread": "^6.23.0",
     "babel-plugin-transform-runtime": "^6.23.0",
     "babel-preset-env": "1.4.0",
     "babel-register": "^6.24.1",
     "chai": "^3.5.0",
     "eslint": "^3.19.0",
     "eslint-config-canonical": "^8.2.0",
+    "flow-bin": "^0.45.0",
+    "flow-copy-source": "^1.1.0",
     "husky": "^0.13.3",
     "npm-watch": "^0.1.9",
     "semantic-release": "^6.3.2"
@@ -54,7 +56,7 @@
     "test": "{src,test}/*.js"
   },
   "scripts": {
-    "build": "NODE_ENV=production babel ./src --out-dir ./dist --copy-files",
+    "build": "NODE_ENV=production babel ./src --out-dir ./dist --copy-files && flow-copy-source src dist",
     "lint": "eslint ./src ./test",
     "watch": "npm-watch",
     "precommit": "npm run lint && npm run test",

src/FunctionStateMap.js

@@ -1,3 +1,5 @@
+// @flow
+
 import PlayerStates from './constants/PlayerStates';
 
 export default {

src/YouTubePlayer.js

@@ -1,29 +1,37 @@
+// @flow
+
 import _ from 'lodash';
 import functionNames from './functionNames';
 import eventNames from './eventNames';
 import FunctionStateMap from './FunctionStateMap';
+import type {
+  EmitterType,
+  YouTubePlayerType
+} from './types';
 
 const YouTubePlayer = {};
 
+type EventHandlerMapType = {
+  [key: string]: (event: Object) => void
+};
+
 /**
  * Construct an object that defines an event handler for all of the YouTube
  * player events. Proxy captured events through an event emitter.
  *
  * @todo Capture event parameters.
  * @see https://developers.google.com/youtube/iframe_api_reference#Events
- * @param {Sister} emitter
- * @returns {Object}
  */
-YouTubePlayer.proxyEvents = (emitter) => {
+YouTubePlayer.proxyEvents = (emitter: EmitterType): EventHandlerMapType => {
   const events = {};
 
-  _.forEach(eventNames, (eventName) => {
+  for (const eventName of eventNames) {
     const onEventName = 'on' + _.upperFirst(eventName);
 
     events[onEventName] = (event) => {
       emitter.trigger(eventName, event);
     };
-  });
+  }
 
   return events;
 };
@@ -33,16 +41,16 @@ YouTubePlayer.proxyEvents = (emitter) => {
  *
  * @todo Proxy all of the methods using Object.keys.
  * @todo See TRICKY below.
- * @param {Promise} playerAPIReady Promise that resolves when player is ready.
- * @param {boolean} strictState A flag designating whether or not to wait for
- * an acceptable state when calling supported functions. Default: `false`.
+ * @param playerAPIReady Promise that resolves when player is ready.
+ * @param strictState A flag designating whether or not to wait for
+ * an acceptable state when calling supported functions.
  * @returns {Object}
  */
-YouTubePlayer.promisifyPlayer = (playerAPIReady, strictState = false) => {
+YouTubePlayer.promisifyPlayer = (playerAPIReady: Promise<YouTubePlayerType>, strictState: boolean = false) => {
   const functions = {};
 
-  _.forEach(functionNames, (functionName) => {
-    if (strictState && FunctionStateMap[functionName] instanceof Object) {
+  for (const functionName of functionNames) {
+    if (strictState && FunctionStateMap[functionName]) {
       functions[functionName] = async (...args) => {
         const stateInfo = FunctionStateMap[functionName];
         const player = await playerAPIReady;
@@ -110,7 +118,7 @@ YouTubePlayer.promisifyPlayer = (playerAPIReady, strictState = false) => {
         return player[functionName].apply(player, args);
       };
     }
-  });
+  }
 
   return functions;
 };

src/constants/PlayerStates.js

@@ -1,3 +1,5 @@
+// @flow
+
 export default {
   BUFFERING: 3,
   ENDED: 0,

src/eventNames.js

@@ -1,3 +1,5 @@
+// @flow
+
 /**
  * @see https://developers.google.com/youtube/iframe_api_reference#Events
  */

src/functionNames.js

@@ -1,3 +1,5 @@
+// @flow
+
 /**
  * @see https://developers.google.com/youtube/iframe_api_reference#Functions
  */
@@ -9,11 +11,7 @@ export default [
   'playVideo',
   'pauseVideo',
   'stopVideo',
-  'clearVideo',
-  'getVideoBytesLoaded',
-  'getVideoBytesTotal',
   'getVideoLoadedFraction',
-  'getVideoStartBytes',
   'cuePlaylist',
   'loadPlaylist',
   'nextVideo',
@@ -23,9 +21,6 @@ export default [
   'setLoop',
   'getPlaylist',
   'getPlaylistIndex',
-  'getPlaylistId',
-  'loadModule',
-  'unloadModule',
   'setOption',
   'mute',
   'unMute',
@@ -44,29 +39,11 @@ export default [
   'getDuration',
   'removeEventListener',
   'getVideoUrl',
-  'getDebugText',
-  'getVideoData',
-  'addCueRange',
-  'removeCueRange',
-  'getApiInterface',
-  'showVideoInfo',
-  'hideVideoInfo',
-  'G',
-  'C',
-  'R',
-  'aa',
-  '$',
-  'Z',
   'getVideoEmbedCode',
   'getOptions',
   'getOption',
-  'Y',
-  'X',
   'addEventListener',
   'destroy',
-  'A',
-  'P',
-  'J',
   'setSize',
   'getIframe'
 ];

src/index.js

@@ -1,17 +1,22 @@
-import _ from 'lodash';
+// @flow
+
 import Sister from 'sister';
 import loadYouTubeIframeApi from './loadYouTubeIframeApi';
 import YouTubePlayer from './YouTubePlayer';
+import type {
+  YouTubePlayerType
+} from './types';
 
 /**
- * @typedef options
  * @see https://developers.google.com/youtube/iframe_api_reference#Loading_a_Video_Player
- * @param {Number} width
- * @param {Number} height
- * @param {String} videoId
- * @param {Object} playerVars
- * @param {Object} events
  */
+type OptionsType = {
+  events?: Object,
+  height?: number,
+  playerVars?: Object,
+  videoId?: string,
+  width?: number
+};
 
 /**
  * @typedef YT.Player
@@ -23,15 +28,14 @@ let youtubeIframeAPI;
 /**
  * A factory function used to produce an instance of YT.Player and queue function calls and proxy events of the resulting object.
  *
- * @param {YT.Player|HTMLElement|String} elementId Either An existing YT.Player instance,
+ * @param elementId Either An existing YT.Player instance,
  * the DOM element or the id of the HTML element where the API will insert an <iframe>.
- * @param {YouTubePlayer~options} options See `options` (Ignored when using an existing YT.Player instance).
- * @param {boolean} strictState A flag designating whether or not to wait for
+ * @param options See `options` (Ignored when using an existing YT.Player instance).
+ * @param strictState A flag designating whether or not to wait for
  * an acceptable state when calling supported functions. Default: `false`.
  * See `FunctionStateMap.js` for supported functions and acceptable states.
- * @returns {Object}
  */
-export default (elementId, options = {}, strictState = false) => {
+export default (maybeElementId: YouTubePlayerType | HTMLElement | string, options: OptionsType = {}, strictState: boolean = false) => {
   const emitter = Sister();
 
   if (!youtubeIframeAPI) {
@@ -42,37 +46,34 @@ export default (elementId, options = {}, strictState = false) => {
     throw new Error('Event handlers cannot be overwritten.');
   }
 
-  if (_.isString(elementId) && !document.getElementById(elementId)) {
-    throw new Error('Element "' + elementId + '" does not exist.');
+  if (typeof maybeElementId === 'string' && !document.getElementById(maybeElementId)) {
+    throw new Error('Element "' + maybeElementId + '" does not exist.');
   }
 
   options.events = YouTubePlayer.proxyEvents(emitter);
 
-  const playerAPIReady = new Promise(async (resolve) => {
-    let player;
-
-    if (
-      elementId instanceof Object &&
-      elementId.playVideo instanceof Function
-    ) {
-      player = elementId;
-
-      resolve(player);
-    } else {
+  const playerAPIReady = new Promise(async (resolve: (result: YouTubePlayerType) => void) => {
+    if (typeof maybeElementId === 'string' || maybeElementId instanceof HTMLElement) {
       const YT = await youtubeIframeAPI;
 
-      player = new YT.Player(elementId, options);
+      const player: YouTubePlayerType = new YT.Player(maybeElementId, options);
 
       emitter.on('ready', () => {
         resolve(player);
       });
+    } else if (typeof maybeElementId === 'object' && maybeElementId.playVideo instanceof Function) {
+      const player: YouTubePlayerType = maybeElementId;
+
+      resolve(player);
+    } else {
+      throw new TypeError('Unexpected state.');
     }
   });
 
-  const playerAPI = YouTubePlayer.promisifyPlayer(playerAPIReady, strictState);
+  const playerApi = YouTubePlayer.promisifyPlayer(playerAPIReady, strictState);
 
-  playerAPI.on = emitter.on;
-  playerAPI.off = emitter.off;
+  playerApi.on = emitter.on;
+  playerApi.off = emitter.off;
 
-  return playerAPI;
+  return playerApi;
 };

src/loadYouTubeIframeApi.js

@@ -1,12 +1,14 @@
+// @flow
+
 import load from 'load-script';
+import type {
+  IframeApiType
+} from './types';
 
-export default () => {
+export default (): Promise<IframeApiType> => {
   /**
    * A promise that is resolved when window.onYouTubeIframeAPIReady is called.
    * The promise is resolved with a reference to window.YT object.
-   *
-   * @param {Function} resolve
-   * @member {Object} iframeAPIReady
    */
   const iframeAPIReady = new Promise((resolve) => {
     if (window.YT && window.YT.Player && window.YT.Player instanceof Function) {
@@ -27,6 +29,7 @@ export default () => {
       resolve(window.YT);
     };
   });
+
   const protocol = window.location.protocol === 'http:' ? 'http:' : 'https:';
 
   load(protocol + '//www.youtube.com/iframe_api');