indexeddbshim 11.0.0 → 12.0.0-pre.0

package/src/DOMException.js

@@ -8,6 +8,7 @@ import CFG from './CFG.js';
  * @returns {DOMException}
  */
 function createNativeDOMException (name, message) {
+    // @ts-expect-error It's ok
     return new DOMException.prototype.constructor(
         message,
         name || 'DOMException'
@@ -15,6 +16,20 @@ function createNativeDOMException (name, message) {
 }
 
 // From web-platform-tests testharness.js name_code_map (though not in new spec)
+
+/**
+ * @typedef {"IndexSizeError"|"HierarchyRequestError"|"WrongDocumentError"|
+ * "InvalidCharacterError"|"NoModificationAllowedError"|"NotFoundError"|
+ * "NotSupportedError"|"InUseAttributeError"|"InvalidStateError"|
+ * "SyntaxError"|"InvalidModificationError"|"NamespaceError"|
+ * "InvalidAccessError"|"TypeMismatchError"|"SecurityError"|
+ * "NetworkError"|"AbortError"|"URLMismatchError"|"QuotaExceededError"|
+ * "TimeoutError"|"InvalidNodeTypeError"|"DataCloneError"|"EncodingError"|
+ * "NotReadableError"|"UnknownError"|"ConstraintError"|"DataError"|
+ * "TransactionInactiveError"|"ReadOnlyError"|"VersionError"|
+ * "OperationError"|"NotAllowedError"} Code
+ */
+
 const codes = {
     IndexSizeError: 1,
     HierarchyRequestError: 3,
@@ -51,6 +66,17 @@ const codes = {
     NotAllowedError: 0
 };
 
+/**
+ * @typedef {"INDEX_SIZE_ERR"|"DOMSTRING_SIZE_ERR"|"HIERARCHY_REQUEST_ERR"|
+ * "WRONG_DOCUMENT_ERR"|"INVALID_CHARACTER_ERR"|"NO_DATA_ALLOWED_ERR"|
+ * "NO_MODIFICATION_ALLOWED_ERR"|"NOT_FOUND_ERR"|"NOT_SUPPORTED_ERR"|
+ * "INUSE_ATTRIBUTE_ERR"|"INVALID_STATE_ERR"|"SYNTAX_ERR"|
+ * "INVALID_MODIFICATION_ERR"|"NAMESPACE_ERR"|"INVALID_ACCESS_ERR"|
+ * "VALIDATION_ERR"|"TYPE_MISMATCH_ERR"|"SECURITY_ERR"|"NETWORK_ERR"|
+ * "ABORT_ERR"|"URL_MISMATCH_ERR"|"QUOTA_EXCEEDED_ERR"|"TIMEOUT_ERR"|
+ * "INVALID_NODE_TYPE_ERR"|"DATA_CLONE_ERR"} LegacyCode
+ */
+
 const legacyCodes = {
     INDEX_SIZE_ERR: 1,
     DOMSTRING_SIZE_ERR: 2,
@@ -81,13 +107,20 @@ const legacyCodes = {
 
 /**
  *
- * @returns {DOMException}
+ * @returns {typeof DOMException}
  */
 function createNonNativeDOMExceptionClass () {
+    /**
+     * @param {string|undefined} message
+     * @param {Code|LegacyCode} name
+     * @returns {void}
+     */
     function DOMException (message, name) {
         // const err = Error.prototype.constructor.call(this, message); // Any use to this? Won't set this.message
         this[Symbol.toStringTag] = 'DOMException';
-        this._code = name in codes ? codes[name] : (legacyCodes[name] || 0);
+        this._code = name in codes
+            ? codes[/** @type {Code} */ (name)]
+            : (legacyCodes[/** @type {LegacyCode} */ (name)] || 0);
         this._name = name || 'Error';
         // We avoid `String()` in this next line as it converts Symbols
         this._message = message === undefined ? '' : ('' + message); // eslint-disable-line no-implicit-coercion
@@ -118,19 +151,29 @@ function createNonNativeDOMExceptionClass () {
     // Necessary for W3C tests which complains if `DOMException` has properties on its "own" prototype
 
     // class DummyDOMException extends Error {}; // Sometimes causing problems in Node
-    // eslint-disable-next-line func-name-matching
+    /* eslint-disable func-name-matching */
+    /**
+     * @class
+     */
     const DummyDOMException = function DOMException () { /* */ };
+    /* eslint-enable func-name-matching */
     DummyDOMException.prototype = Object.create(Error.prototype); // Intended for subclassing
-    ['name', 'message'].forEach((prop) => {
+    /** @type {const} */ (['name', 'message']).forEach((prop) => {
         Object.defineProperty(DummyDOMException.prototype, prop, {
             enumerable: true,
+            /**
+             * @this {DOMException}
+             * @returns {string}
+             */
             get () {
                 if (!(this instanceof DOMException ||
+                    // @ts-expect-error Just checking
                     this instanceof DummyDOMException ||
+                    // @ts-expect-error Just checking
                     this instanceof Error)) {
                     throw new TypeError('Illegal invocation');
                 }
-                return this['_' + prop];
+                return this[prop === 'name' ? '_name' : '_message'];
             }
         });
     });
@@ -142,6 +185,7 @@ function createNonNativeDOMExceptionClass () {
             throw new TypeError('Illegal invocation');
         }
     });
+    // @ts-expect-error It's ok
     DOMException.prototype = new DummyDOMException();
 
     DOMException.prototype[Symbol.toStringTag] = 'DOMExceptionPrototype';
@@ -149,19 +193,25 @@ function createNonNativeDOMExceptionClass () {
         writable: false
     });
 
-    Object.keys(codes).forEach((codeName) => {
-        Object.defineProperty(DOMException.prototype, codeName, {
-            enumerable: true,
-            configurable: false,
-            value: codes[codeName]
-        });
-        Object.defineProperty(DOMException, codeName, {
-            enumerable: true,
-            configurable: false,
-            value: codes[codeName]
-        });
-    });
-    Object.keys(legacyCodes).forEach((codeName) => {
+    const keys = Object.keys(codes);
+
+    /** @type {(keyof codes)[]} */ (keys).forEach(
+        (codeName) => {
+            Object.defineProperty(DOMException.prototype, codeName, {
+                enumerable: true,
+                configurable: false,
+                value: codes[codeName]
+            });
+            Object.defineProperty(DOMException, codeName, {
+                enumerable: true,
+                configurable: false,
+                value: codes[codeName]
+            });
+        }
+    );
+    /** @type {(keyof legacyCodes)[]} */ (Object.keys(legacyCodes)).forEach((
+        codeName
+    ) => {
         Object.defineProperty(DOMException.prototype, codeName, {
             enumerable: true,
             configurable: false,
@@ -180,6 +230,7 @@ function createNonNativeDOMExceptionClass () {
         value: DOMException
     });
 
+    // @ts-expect-error We don't need all its properties
     return DOMException;
 }
 
@@ -195,25 +246,39 @@ function createNonNativeDOMException (name, message) {
     return new ShimNonNativeDOMException(message, name);
 }
 
+/**
+ * @typedef {{
+ *   message: string|DOMString
+ * }} ErrorLike
+ */
+
 /**
  * Logs detailed error information to the console.
  * @param {string} name
  * @param {string} message
- * @param {string|Error|null} error
+ * @param {string|ErrorLike|boolean|null} [error]
  * @returns {void}
  */
 function logError (name, message, error) {
     if (CFG.DEBUG) {
-        if (error && error.message) {
-            error = error.message;
-        }
+        const msg = error && typeof error === 'object' && error.message
+            ? error.message
+            : /** @type {string} */ (error);
 
         const method = typeof (console.error) === 'function' ? 'error' : 'log';
-        console[method](name + ': ' + message + '. ' + (error || ''));
+        console[method](name + ': ' + message + '. ' + (msg || ''));
         console.trace && console.trace();
     }
 }
 
+/**
+ * @typedef {any} ArbitraryValue
+ */
+
+/**
+ * @param {ArbitraryValue} obj
+ * @returns {boolean}
+ */
 function isErrorOrDOMErrorOrDOMException (obj) {
     return obj && typeof obj === 'object' && // We don't use util.isObj here as mutual dependency causing problems in Babel with browser
         typeof obj.name === 'string';
@@ -223,7 +288,7 @@ function isErrorOrDOMErrorOrDOMException (obj) {
  * Finds the error argument.  This is useful because some WebSQL callbacks
  * pass the error as the first argument, and some pass it as the second
  * argument.
- * @param {Array} args
+ * @param {(Error|{message?: string, name?: string}|any)[]} args
  * @returns {Error|DOMException|undefined}
  */
 function findError (args) {
@@ -246,8 +311,10 @@ function findError (args) {
 
 /**
  *
- * @param {external:WebSQLError} webSQLErr
- * @returns {DOMException}
+ * @param {SQLError} webSQLErr
+ * @returns {(DOMException|Error) & {
+ *   sqlError: SQLError
+ * }}
  */
 function webSQLErrback (webSQLErr) {
     let name, message;
@@ -275,7 +342,13 @@ function webSQLErrback (webSQLErr) {
     }
     }
     message += ' (' + webSQLErr.message + ')--(' + webSQLErr.code + ')';
-    const err = createDOMException(name, message);
+    const err =
+        /**
+         * @type {(Error | DOMException) & {
+         *   sqlError: SQLError
+         * }}
+         */
+        (createDOMException(name, message));
     err.sqlError = webSQLErr;
     return err;
 }
@@ -292,11 +365,25 @@ try {
 } catch (e) {}
 
 const createDOMException = useNativeDOMException
-    ? function (name, message, error) {
+    // eslint-disable-next-line operator-linebreak -- Need JSDoc
+    ? /**
+     * @param {string} name
+     * @param {string} message
+     * @param {ErrorLike} [error]
+     * @returns {DOMException}
+     */
+    function (name, message, error) {
         logError(name, message, error);
         return createNativeDOMException(name, message);
     }
-    : function (name, message, error) {
+    // eslint-disable-next-line operator-linebreak -- Need JSDoc
+    : /**
+    * @param {string} name
+    * @param {string} message
+    * @param {ErrorLike} [error]
+    * @returns {Error}
+    */
+    function (name, message, error) {
         logError(name, message, error);
         return createNonNativeDOMException(name, message);
     };

package/src/DOMStringList.js

@@ -1,3 +1,23 @@
+/**
+ * @typedef {number} Integer
+ */
+
+/**
+ * @typedef {{
+ *   _items: string[],
+ *   _length: Integer,
+ *   [key: number]: string,
+ *   addIndexes: () => void,
+ *   sortList: () => string[],
+ *   push: (item: string) => void,
+ *   clone: () => DOMStringListFull,
+ *   contains: (str: string) => boolean,
+ *   indexOf: (str: string) => Integer,
+ *   splice: (index: Integer, howmany: Integer, ...args: any) => void
+ *   length: Integer
+ * }} DOMStringListFull
+ */
+
 let cleanInterface = false;
 
 const testObject = {test: true};
@@ -19,17 +39,33 @@ if (Object.defineProperty) {
  * @class
  */
 const DOMStringList = function () {
+    /** @type {string[]} */
+    this._items = [];
+    /** @type {Integer} */
+    this._length = 0;
     throw new TypeError('Illegal constructor');
 };
+
+// @ts-expect-error It's ok
 DOMStringList.prototype = {
     constructor: DOMStringList,
     // Interface.
+
+    /**
+     * @param {string} str
+     * @returns {boolean}
+     */
     contains (str) {
         if (!arguments.length) {
             throw new TypeError('DOMStringList.contains must be supplied a value');
         }
         return this._items.includes(str);
     },
+
+    /**
+     * @param {number} key
+     * @returns {string|null}
+     */
     item (key) {
         if (!arguments.length) {
             throw new TypeError('DOMStringList.item must be supplied a value');
@@ -41,6 +77,9 @@ DOMStringList.prototype = {
     },
 
     // Helpers. Should only be used internally.
+    /**
+     * @returns {DOMStringListFull}
+     */
     clone () {
         const stringList = DOMStringList.__createInstance();
         stringList._items = this._items.slice();
@@ -48,11 +87,19 @@ DOMStringList.prototype = {
         stringList.addIndexes();
         return stringList;
     },
+    /**
+     * @this {DOMStringListFull}
+     * @returns {void}
+     */
     addIndexes () {
         for (let i = 0; i < this._items.length; i++) {
             this[i] = this._items[i];
         }
     },
+    /**
+     * @this {DOMStringListFull}
+     * @returns {string[]}
+     */
     sortList () {
         // http://w3c.github.io/IndexedDB/#sorted-list
         // https://tc39.github.io/ecma262/#sec-abstract-relational-comparison
@@ -60,22 +107,49 @@ DOMStringList.prototype = {
         this.addIndexes();
         return this._items;
     },
+    /**
+     * @param {(value: string, i: Integer, arr: string[]) => void} cb
+     * @param {object} thisArg
+     * @returns {void}
+     */
     forEach (cb, thisArg) {
         // eslint-disable-next-line unicorn/no-array-callback-reference, unicorn/no-array-method-this-argument
         this._items.forEach(cb, thisArg);
     },
+    /**
+     * @param {(value: string, i: Integer, arr: string[]) => any[]} cb
+     * @param {object} thisArg
+     * @returns {any[]}
+     */
     map (cb, thisArg) {
         // eslint-disable-next-line unicorn/no-array-callback-reference, unicorn/no-array-method-this-argument
         return this._items.map(cb, thisArg);
     },
+    /**
+     * @param {string} str
+     * @returns {Integer}
+     */
     indexOf (str) {
         return this._items.indexOf(str);
     },
+    /**
+     * @param {string} item
+     * @this {DOMStringListFull}
+     * @returns {void}
+     */
     push (item) {
         this._items.push(item);
         this._length++;
         this.sortList();
     },
+    /**
+     * @typedef {any} AnyArgs
+     */
+    /**
+     * @param {[index: Integer, howmany: Integer, ...args: any]} args
+     * @this {DOMStringListFull}
+     * @returns {void}
+     */
     splice (...args /* index, howmany, item1, ..., itemX */) {
         this._items.splice(...args);
         this._length = this._items.length;
@@ -99,14 +173,29 @@ DOMStringList.prototype = {
         }
     }
 };
+
+/**
+ * @typedef {any} AnyValue
+ */
 Object.defineProperty(DOMStringList, Symbol.hasInstance, {
+    /**
+     * @param {AnyValue} obj
+     * @returns {boolean}
+     */
     value (obj) {
         return Object.prototype.toString.call(obj) === 'DOMStringListPrototype';
     }
 });
 const DOMStringListAlias = DOMStringList;
 Object.defineProperty(DOMStringList, '__createInstance', {
+    /**
+     * @returns {DOMStringListFull}
+     */
     value () {
+        /**
+         * @class
+         * @this {DOMStringList}
+         */
         const DOMStringList = function DOMStringList () {
             this.toString = function () {
                 return '[object DOMStringList]';
@@ -118,11 +207,11 @@ Object.defineProperty(DOMStringList, '__createInstance', {
                     return this._length;
                 }
             });
-            this._items = [];
+            this._items = /** @type {string[]} */ ([]);
             this._length = 0;
         };
         DOMStringList.prototype = DOMStringListAlias.prototype;
-        return new DOMStringList();
+        return /** @type {DOMStringListFull} */ (new DOMStringList());
     }
 });
 
@@ -139,6 +228,7 @@ if (cleanInterface) {
     });
 
     // Illegal invocations
+    // @ts-expect-error No return value
     Object.defineProperty(DOMStringList.prototype, 'length', {
         configurable: true,
         enumerable: true,

package/src/Event.js

@@ -1,14 +1,21 @@
 import {ShimEventTarget, ShimEvent, ShimCustomEvent} from 'eventtargeter';
 import * as util from './util.js';
 
+/**
+ * @typedef {Error} DebuggingError
+ */
+
 /**
  *
  * @param {string} type
- * @param {Any} debug
- * @param {EventInit} evInit
- * @returns {Event}
+ * @param {DebuggingError|null} [debug]
+ * @param {EventInit} [evInit]
+ * @returns {Event & {
+ *   __legacyOutputDidListenersThrowError?: boolean
+ * }}
  */
 function createEvent (type, debug, evInit) {
+    // @ts-expect-error It's ok
     const ev = new ShimEvent(type, evInit);
     ev.debug = debug;
     return ev;
@@ -16,7 +23,15 @@ function createEvent (type, debug, evInit) {
 
 // We don't add within polyfill repo as might not always be the desired implementation
 Object.defineProperty(ShimEvent, Symbol.hasInstance, {
-    value: (obj) => util.isObj(obj) && 'target' in obj && typeof obj.bubbles === 'boolean'
+    /**
+     * @typedef {any} AnyValue
+     */
+    value:
+        /**
+         * @param {AnyValue} obj
+         * @returns {boolean}
+         */
+        (obj) => util.isObj(obj) && 'target' in obj && 'bubbles' in obj && typeof obj.bubbles === 'boolean'
 });
 
 export {createEvent, ShimEvent, ShimCustomEvent, ShimEventTarget};