feat: improved error interface (videojs#8564)

src/js/consts/errors.js

@@ -0,0 +1,13 @@
+export default {
+  UnsupportedSidxContainer: 'unsupported-sidx-container-error',
+  DashManifestSidxParsingError: 'dash-manifest-sidx-parsing-error',
+  HlsPlaylistRequestError: 'hls-playlist-request-error',
+  SegmentUnsupportedMediaFormat: 'segment-unsupported-media-format-error',
+  UnsupportedMediaInitialization: 'unsupported-media-initialization-error',
+  SegmentSwitchError: 'segment-switch-error',
+  SegmentExceedsSourceBufferQuota: 'segment-exceeds-source-buffer-quota-error',
+  SegmentAppendError: 'segment-append-error',
+  VttLoadError: 'vtt-load-error',
+  VttCueParsingError: 'vtt-cue-parsing-error',
+  EMEKeySessionCreationError: 'eme-key-session-creation-error'
+};

src/js/media-error.js

@@ -75,6 +75,21 @@ MediaError.prototype.message = '';
  */
 MediaError.prototype.status = null;
 
+/**
+ * An object containing an error type, as well as other information regarding the error.
+ *
+ * @typedef {{errorType: string, [key: string]: any}} ErrorMetadata
+ */
+
+/**
+ * An optional object to give more detail about the error. This can be used to give
+ * a higher level of specificity to an error versus the more generic MediaError codes.
+ * `metadata` expects an `errorType` string that should align with the values from videojs.Error.
+ *
+ * @type {ErrorMetadata}
+ */
+MediaError.prototype.metadata = null;
+
 /**
  * Errors indexed by the W3C standard. The order **CANNOT CHANGE**! See the
  * specification listed under {@link MediaError} for more information.
@@ -111,30 +126,23 @@ MediaError.defaultMessages = {
   5: 'The media is encrypted and we do not have the keys to decrypt it.'
 };
 
-// Add types as properties on MediaError
-// e.g. MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
-for (let errNum = 0; errNum < MediaError.errorTypes.length; errNum++) {
-  MediaError[MediaError.errorTypes[errNum]] = errNum;
-  // values should be accessible on both the class and instance
-  MediaError.prototype[MediaError.errorTypes[errNum]] = errNum;
-}
-
-// jsdocs for instance/static members added above
-// instance methods use `#` and static methods use `.`
 /**
  * W3C error code for any custom error.
  *
  * @member MediaError#MEDIA_ERR_CUSTOM
  * @constant {number}
  * @default 0
  */
+MediaError.MEDIA_ERR_CUSTOM = 0;
+
 /**
  * W3C error code for any custom error.
  *
  * @member MediaError.MEDIA_ERR_CUSTOM
  * @constant {number}
  * @default 0
  */
+MediaError.prototype.MEDIA_ERR_CUSTOM = 0;
 
 /**
  * W3C error code for media error aborted.
@@ -143,13 +151,16 @@ for (let errNum = 0; errNum < MediaError.errorTypes.length; errNum++) {
  * @constant {number}
  * @default 1
  */
+MediaError.MEDIA_ERR_ABORTED = 1;
+
 /**
  * W3C error code for media error aborted.
  *
  * @member MediaError.MEDIA_ERR_ABORTED
  * @constant {number}
  * @default 1
  */
+MediaError.prototype.MEDIA_ERR_ABORTED = 1;
 
 /**
  * W3C error code for any network error.
@@ -158,13 +169,16 @@ for (let errNum = 0; errNum < MediaError.errorTypes.length; errNum++) {
  * @constant {number}
  * @default 2
  */
+MediaError.MEDIA_ERR_NETWORK = 2;
+
 /**
  * W3C error code for any network error.
  *
  * @member MediaError.MEDIA_ERR_NETWORK
  * @constant {number}
  * @default 2
  */
+MediaError.prototype.MEDIA_ERR_NETWORK = 2;
 
 /**
  * W3C error code for any decoding error.
@@ -173,13 +187,16 @@ for (let errNum = 0; errNum < MediaError.errorTypes.length; errNum++) {
  * @constant {number}
  * @default 3
  */
+MediaError.MEDIA_ERR_DECODE = 3;
+
 /**
  * W3C error code for any decoding error.
  *
  * @member MediaError.MEDIA_ERR_DECODE
  * @constant {number}
  * @default 3
  */
+MediaError.prototype.MEDIA_ERR_DECODE = 3;
 
 /**
  * W3C error code for any time that a source is not supported.
@@ -188,13 +205,16 @@ for (let errNum = 0; errNum < MediaError.errorTypes.length; errNum++) {
  * @constant {number}
  * @default 4
  */
+MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
+
 /**
  * W3C error code for any time that a source is not supported.
  *
  * @member MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED
  * @constant {number}
  * @default 4
  */
+MediaError.prototype.MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
 
 /**
  * W3C error code for any time that a source is encrypted.
@@ -203,12 +223,15 @@ for (let errNum = 0; errNum < MediaError.errorTypes.length; errNum++) {
  * @constant {number}
  * @default 5
  */
+MediaError.MEDIA_ERR_ENCRYPTED = 5;
+
 /**
  * W3C error code for any time that a source is encrypted.
  *
  * @member MediaError.MEDIA_ERR_ENCRYPTED
  * @constant {number}
  * @default 5
  */
+MediaError.prototype.MEDIA_ERR_ENCRYPTED = 5;
 
 export default MediaError;

src/js/video.js

@@ -34,6 +34,7 @@ import * as Dom from './utils/dom.js';
 import * as browser from './utils/browser.js';
 import * as Url from './utils/url.js';
 import * as Obj from './utils/obj';
+import VjsErrors from './consts/errors';
 import xhr from '@videojs/xhr';
 
 // Include the built-in techs
@@ -617,4 +618,7 @@ videojs.str = Str;
  */
 videojs.url = Url;
 
+// The list of possible error types to occur in video.js
+videojs.Error = VjsErrors;
+
 export default videojs;

test/unit/media-error.test.js

@@ -41,12 +41,19 @@ QUnit.test('can be constructed from a string', function(assert) {
 
 QUnit.test('can be constructed from an object', function(assert) {
   const mediaError = new MediaError({code: 2});
-  const mediaErrorMsg = new MediaError({code: 2, message: 'hello, world'});
+  const mediaErrorMsg = new MediaError({
+    code: 2,
+    message: 'hello, world',
+    metadata: {
+      errorType: 'test-error'
+    }
+  });
 
   assert.strictEqual(mediaError.code, 2);
   assert.strictEqual(mediaError.message, MediaError.defaultMessages['2']);
   assert.strictEqual(mediaErrorMsg.code, 2);
   assert.strictEqual(mediaErrorMsg.message, 'hello, world');
+  assert.strictEqual(mediaErrorMsg.metadata.errorType, 'test-error');
 });
 
 if (isModernBrowser) {