From 0982415db802e030b8f6559db7f6376f2bc3fc26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrien=20LES=C3=89N=C3=89CHAL?= Date: Fri, 16 Feb 2024 13:57:02 +0100 Subject: [PATCH] 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 --- jquery/textSelection.d.ts | 22 ++++++++-------------- mw/ForeignApi.d.ts | 7 ++++++- mw/ForeignRest.d.ts | 5 +++++ mw/Map.d.ts | 12 ++++++------ mw/cookie.d.ts | 12 ++++++------ mw/hook.d.ts | 2 +- mw/language.d.ts | 16 ++++++++++------ mw/loader.d.ts | 2 +- mw/log.d.ts | 8 ++++---- mw/message.d.ts | 4 ++-- 10 files changed, 49 insertions(+), 41 deletions(-) diff --git a/jquery/textSelection.d.ts b/jquery/textSelection.d.ts index ecf808f..8af079b 100644 --- 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} [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 index 7d0a98a..afb5743 100644 --- 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 index c1ecaa7..1302232 100644 --- 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 index cd1bfd5..0475f5a 100644 --- a/mw/Map.d.ts +++ b/mw/Map.d.ts @@ -16,11 +16,11 @@ type PickOrDefault, TD, TX = unknown> = S ? { [P in K & PropertyKey]-?: GetOrDefault } : GetOrDefault; -// `ExtensibleMap` is an alternative to `Map` -// but unlike the latter, ExtensibleMap provides additional overloads to improve selection -// autocompletion and type checking. +// `ExtensibleMap` is an alternative to `Map>`, but unlike the latter +// ExtensibleMap provides additional overloads to improve selection autocompletion and type checking. -export interface ExtensibleMap, TX = unknown> extends mw.Map { +export interface ExtensibleMap, TX = unknown> + extends mw.Map> { /** * Check if a given key exists in the map. * @@ -49,7 +49,7 @@ export interface ExtensibleMap, TX = unknown> exte get, TD>(selection: S, fallback: TD): PickOrDefault; get>(selection: S): PickOrDefault; get>(selection: S): PickOrDefault; - get = V | Record>(): T; + get(): V & Record; /** * Set the value of one or more keys. @@ -103,7 +103,7 @@ declare global { fallback: TD ): PickOrDefault; get>(selection: S): PickOrDefault; - get(): T; + get(): V; /** * Set the value of one or more keys. diff --git a/mw/cookie.d.ts b/mw/cookie.d.ts index 3171d9d..e207505 100644 --- a/mw/cookie.d.ts +++ b/mw/cookie.d.ts @@ -13,8 +13,8 @@ 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( @@ -22,15 +22,15 @@ declare global { 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( @@ -38,7 +38,7 @@ declare global { 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 index b7348e6..5e1e15c 100644 --- a/mw/hook.d.ts +++ b/mw/hook.d.ts @@ -55,7 +55,7 @@ interface Hook { /** * 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 index 288a950..fba935e 100644 --- a/mw/language.d.ts +++ b/mw/language.d.ts @@ -1,5 +1,3 @@ -type FlipObject> = { [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(gender: string, forms: [T?, T?, T?]): T; + function gender(gender: string, forms: [T, T?, T?]): T; + function gender(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.} 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( + forms: T, + count: number + ): [...T, ...string[]]; } } } diff --git a/mw/loader.d.ts b/mw/loader.d.ts index a0dd49d..5b155f2 100644 --- 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(modules: U[]): T[]; + function resolve(modules: U[]): T[]; /** * Start loading of all queued module dependencies. diff --git a/mw/log.d.ts b/mw/log.d.ts index 6e7ca96..841bc75 100644 --- 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 index c3ec517..b37dfc0 100644 --- 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 */