Type fixes

- add OOJS static properties to `mw.ForeignApi`/`mw.ForeignRest` - replace `Mixed` with `any` in JSdoc for consistency, as it can't be used in some places, so currently both `any` & `Mixed` are used - be more specific with `mw.ForeignApi.getOrigin`/`mw.language.preConvertPlural` return types for autocompletion - add additional signatures to `mw.language.convertNumber` to better infer return type - remove `mw.Map.get()` type parameter, as it allowed to completely bypass type checking - fix `mw.cookie.get`/`mw.cookie.getCrossSite`/`mw.language.gender` not specifying that `null`/`undefined` may be returned - fix `$.textSelection` not allowing `boolean` as argument - fix `ExtensibleMap.values` not allowing unknown properties
wikimedia-gadgets · Feb 16, 2024 · 0982415 · 0982415
1 parent dec4928
commit 0982415
Show file tree

Hide file tree

Showing 10 changed files with 49 additions and 41 deletions.
diff --git a/jquery/textSelection.d.ts b/jquery/textSelection.d.ts
@@ -45,7 +45,7 @@ declare global {
          * Also focusses the textarea.
          *
          * @param {string} command Command to execute
-         * @param {TextSelectionEncapsulateOptions} [options]
+         * @param {Partial<TextSelectionEncapsulateOptions>} [options]
          * @returns {JQuery}
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
          */
@@ -60,24 +60,18 @@ declare global {
          * @param {string} command Command to execute
          * @param {Object} [options]
          * @param {boolean} [options.startAndEnd=false] Return range of the selection rather than just start
-         * @returns {number[]} Array with two numbers, for start and end of selection
+         * @returns {number|number[]} Array with two numbers, for start and end of selection
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
          */
         textSelection(
             command: "getCaretPosition",
             options: { startAndEnd: true }
         ): [number, number];
-
-        /**
-         * Get the current cursor position (in UTF-16 code units) in a textarea.
-         *
-         * @param {string} command Command to execute
-         * @param {Object} [options]
-         * @param {boolean} [options.startAndEnd=false] Return range of the selection rather than just start
-         * @returns {number}
-         * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
-         */
         textSelection(command: "getCaretPosition", options?: { startAndEnd?: false }): number;
+        textSelection(
+            command: "getCaretPosition",
+            options?: { startAndEnd: boolean }
+        ): number | [number, number];
 
         /**
          * Set the current cursor position (in UTF-16 code units) in a textarea.
@@ -130,8 +124,8 @@ declare global {
          * Do things to the selection in the textarea, using a command from the alternative textSelection API for this element.
          *
          * @param {string} command Command to execute
-         * @param {Mixed} [commandOptions] Options to pass to the command
-         * @returns {Mixed} Depending on the command
+         * @param {any} [commandOptions] Options to pass to the command
+         * @returns {any} Depending on the command
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection
          */
         textSelection(command: string, commandOptions?: unknown): any;

diff --git a/mw/ForeignApi.d.ts b/mw/ForeignApi.d.ts
@@ -13,6 +13,11 @@ declare global {
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi
          */
         class ForeignApi extends Api {
+            static static: {};
+            static super: typeof Api;
+            /** @deprecated Use `super` instead */
+            static parent: typeof Api;
+
             /**
              * Create an object like {@link mw.Api}, but automatically handling everything required to communicate with another MediaWiki wiki via cross-origin requests (CORS).
              *
@@ -51,7 +56,7 @@ declare global {
              * @returns {string|undefined}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-getOrigin
              */
-            protected getOrigin(): string | undefined;
+            protected getOrigin(): "*" | `${string}//${string}` | undefined;
         }
     }
 }

diff --git a/mw/ForeignRest.d.ts b/mw/ForeignRest.d.ts
@@ -15,6 +15,11 @@ declare global {
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignRest
          */
         class ForeignRest extends Rest {
+            static static: {};
+            static super: typeof Rest;
+            /** @deprecated Use `super` instead */
+            static parent: typeof Rest;
+
             /**
              * Create an object like {@link mw.Rest}, but automatically handling everything required
              * to communicate with another MediaWiki wiki via cross-origin requests (CORS).

diff --git a/mw/Map.d.ts b/mw/Map.d.ts
@@ -16,11 +16,11 @@ type PickOrDefault<V, S extends TypeOrArray<PropertyKey>, TD, TX = unknown> = S
     ? { [P in K & PropertyKey]-?: GetOrDefault<V, P, TD, TX> }
     : GetOrDefault<V, S & PropertyKey, TD, TX>;
 
-// `ExtensibleMap<V, TX>` is an alternative to `Map<V & { [k: string]: TX; }>`
-// but unlike the latter, ExtensibleMap provides additional overloads to improve selection
-// autocompletion and type checking.
+// `ExtensibleMap<V, TX>` is an alternative to `Map<V & Record<string, TX>>`, but unlike the latter
+// ExtensibleMap provides additional overloads to improve selection autocompletion and type checking.
 
-export interface ExtensibleMap<V extends Record<string, any>, TX = unknown> extends mw.Map<V> {
+export interface ExtensibleMap<V extends Record<string, any>, TX = unknown>
+    extends mw.Map<V & Record<string, TX>> {
     /**
      * Check if a given key exists in the map.
      *
@@ -49,7 +49,7 @@ export interface ExtensibleMap<V extends Record<string, any>, TX = unknown> exte
     get<S extends TypeOrArray<string>, TD>(selection: S, fallback: TD): PickOrDefault<V, S, TD, TX>;
     get<S extends TypeOrArray<keyof V>>(selection: S): PickOrDefault<V, S, null, TX>;
     get<S extends TypeOrArray<string>>(selection: S): PickOrDefault<V, S, null, TX>;
-    get<T extends Record<string, any> = V | Record<string, TX>>(): T;
+    get(): V & Record<string, TX>;
 
     /**
      * Set the value of one or more keys.
@@ -103,7 +103,7 @@ declare global {
                 fallback: TD
             ): PickOrDefault<V, S, TD>;
             get<S extends TypeOrArray<keyof V>>(selection: S): PickOrDefault<V, S, null>;
-            get<T extends V = V>(): T;
+            get(): V;
 
             /**
              * Set the value of one or more keys.

diff --git a/mw/cookie.d.ts b/mw/cookie.d.ts
@@ -13,32 +13,32 @@ declare global {
              *
              * @param {string} key The key for the cookie
              * @param {string} [prefix] The prefix of the key. If undefined or null, `$wgCookiePrefix` is used
-             * @param {Mixed} [defaultValue] A value to return if the cookie does not exist
-             * @returns {Mixed} If the cookie exists, the value of the cookie, otherwise `defaultValue`
+             * @param {any} [defaultValue] A value to return if the cookie does not exist
+             * @returns {any} If the cookie exists, the value of the cookie, otherwise `defaultValue`
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.cookie-method-get
              */
             function get<D>(
                 key: string,
                 prefix: string | undefined | null,
                 defaultValue: D
             ): string | D;
-            function get(key: string, prefix?: string | null): string;
+            function get(key: string, prefix?: string | null): string | null;
 
             /**
              * Get the value of a `SameSite` = `None` cookie, using the legacy `ss0-` prefix if needed.
              *
              * @param {string} key The key for the cookie
              * @param {string} [prefix] The prefix of the key. If undefined or null, `$wgCookiePrefix` is used
-             * @param {Mixed} [defaultValue] A value to return if the cookie does not exist
-             * @returns {Mixed} If the cookie exists, the value of the cookie, otherwise `defaultValue`
+             * @param {any} [defaultValue] A value to return if the cookie does not exist
+             * @returns {any} If the cookie exists, the value of the cookie, otherwise `defaultValue`
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.cookie-method-getCrossSite
              */
             function getCrossSite<D>(
                 key: string,
                 prefix: string | undefined | null,
                 defaultValue: D
             ): string | D;
-            function getCrossSite(key: string, prefix?: string | null): string;
+            function getCrossSite(key: string, prefix?: string | null): string | undefined;
 
             /**
              * Set or delete a cookie.

diff --git a/mw/hook.d.ts b/mw/hook.d.ts
@@ -55,7 +55,7 @@ interface Hook<T extends any[] = any[]> {
     /**
      * Call hook handlers with data.
      *
-     * @param {Mixed} data
+     * @param {any} data
      * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.hook-method-fire
      */
     fire(...data: T): this;

diff --git a/mw/language.d.ts b/mw/language.d.ts
@@ -1,5 +1,3 @@
-type FlipObject<T extends Record<PropertyKey, PropertyKey>> = { [K in keyof T as T[K]]: K };
-
 declare global {
     namespace mw {
         /**
@@ -112,6 +110,8 @@ declare global {
              * @returns {number|string} Formatted number
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-convertNumber
              */
+            function convertNumber(num: number, integer: true): number;
+            function convertNumber(num: number, integer?: false): string;
             function convertNumber(num: number, integer?: boolean): number | string;
 
             /**
@@ -142,7 +142,8 @@ declare global {
              * @returns {string}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-gender
              */
-            function gender<T extends string>(gender: string, forms: [T?, T?, T?]): T;
+            function gender<T extends string>(gender: string, forms: [T, T?, T?]): T;
+            function gender<T extends string = never>(gender: string, forms: [T?, T?, T?]): T | "";
 
             /**
              * Convenience method for retrieving language data.
@@ -152,7 +153,7 @@ declare global {
              *
              * @param {string} langCode
              * @param {string} dataKey
-             * @returns {Mixed} Value stored in the mw.Map (or `undefined` if there is no map for the
+             * @returns {any} Value stored in the mw.Map (or `undefined` if there is no map for the
              *  specified langCode)
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-getData
              */
@@ -208,7 +209,7 @@ declare global {
              *
              * @param {string} langCode
              * @param {string|Object.<string, any>} dataKey Key or object of key/values
-             * @param {Mixed} [value] Value for dataKey, omit if dataKey is an object
+             * @param {any} [value] Value for dataKey, omit if dataKey is an object
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-setData
              */
             function setData(langCode: string, dataKey: string, value: any): void;
@@ -223,7 +224,10 @@ declare global {
              * @returns {string[]} Padded array of forms
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-preConvertPlural
              */
-            function preConvertPlural(forms: string[], count: number): string[];
+            function preConvertPlural<T extends string[]>(
+                forms: T,
+                count: number
+            ): [...T, ...string[]];
         }
     }
 }

diff --git a/mw/loader.d.ts b/mw/loader.d.ts
@@ -433,7 +433,7 @@ declare global {
              * @throws {Error} If an unregistered module or a dependency loop is encountered
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader-method-resolve
              */
-            function resolve<T extends string, U extends T>(modules: U[]): T[];
+            function resolve<T extends string, U extends T = T>(modules: U[]): T[];
 
             /**
              * Start loading of all queued module dependencies.

diff --git a/mw/log.d.ts b/mw/log.d.ts
@@ -23,7 +23,7 @@ declare global {
          *
          * See {@link mw.log} for other logging methods.
          *
-         * @param {...Mixed} msg Messages to output to console.
+         * @param {...any} msg Messages to output to console.
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-log
          */
         function log(...msg: any[]): void;
@@ -48,7 +48,7 @@ declare global {
              *
              * @param {Object} obj Host object of deprecated property
              * @param {string} key Name of property to create in `obj`
-             * @param {Mixed} val The value this property should return when accessed
+             * @param {any} val The value this property should return when accessed
              * @param {string} [msg] Optional extra text to add to the deprecation warning
              * @param {string} [logName] Name of the feature for deprecation tracker.
              *  Tracking is disabled by default, except for global variables on `window`.
@@ -69,7 +69,7 @@ declare global {
              * argument is an Error object.
              *
              * @since 1.26
-             * @param {...Mixed} msg Messages to output to console
+             * @param {...any} msg Messages to output to console
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-error
              */
             function error(...msg: any[]): void;
@@ -105,7 +105,7 @@ declare global {
             /**
              * Write a message to the browser console's warning channel.
              *
-             * @param {...Mixed} msg Messages to output to console
+             * @param {...any} msg Messages to output to console
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.log-method-warn
              */
             function warn(...msg: any[]): void;

diff --git a/mw/message.d.ts b/mw/message.d.ts
@@ -6,7 +6,7 @@ declare global {
          * Shortcut for `new mw.Message( mw.messages, key, parameters )`.
          *
          * @param {string} key Key of message to get
-         * @param {...Mixed} parameters Values for $N replacements
+         * @param {...any} parameters Values for $N replacements
          * @returns {Message}
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-message
          */
@@ -232,7 +232,7 @@ declare global {
          * Shortcut for `mw.message( key, parameters... ).text()`.
          *
          * @param {string} key Key of message to get
-         * @param {...Mixed} parameters Values for $N replacements
+         * @param {...any} parameters Values for $N replacements
          * @returns {string}
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-msg
          */