Add missing, improve & fix types

- use shared interfaces for similar types (i.e. ClientNavigator, UserInfo) - add types to some "any" values (i.e. JQuery.client.test) - fix various type issues
Derugon · Jan 22, 2024 · e11977b · e11977b
1 parent d5b9588
commit e11977b
Show file tree

Hide file tree

Showing 18 changed files with 597 additions and 226 deletions.
diff --git a/jquery/client.d.ts b/jquery/client.d.ts
@@ -78,7 +78,7 @@ interface Client {
      *  Defaults to the global `navigator` object.
      * @return {Object} The client object
      */
-    profile(nav?: { userAgent: string; platform: string }): ClientProfile;
+    profile(nav?: ClientNavigator): ClientProfile;
 
     /**
      * Checks the current browser against a support map object.
@@ -122,23 +122,40 @@ interface Client {
      *  otherwise returns true if the browser is not found.
      * @return {boolean} The current browser is in the support map
      */
-    test(map: any, profile?: ClientProfile, exactMatchOnly?: boolean): boolean;
+    test(
+        map: ClientSupportMap | { ltr: ClientSupportMap; rtl: ClientSupportMap },
+        profile?: ClientProfile,
+        exactMatchOnly?: boolean
+    ): boolean;
 }
 
+export interface ClientNavigator {
+    userAgent: string;
+    platform: string;
+}
+
+type ClientProfileName =
+    | "android"
+    | "chrome"
+    | "crios"
+    | "edge"
+    | "firefox"
+    | "fxios"
+    | "konqueror"
+    | "msie"
+    | "opera"
+    | "rekong"
+    | "safari"
+    | "silk";
+
+type ClientSupportMap = Partial<Record<ClientProfileName, false | null | ClientSupportCondition[]>>;
+type ClientSupportCondition = [
+    "==" | "===" | "!=" | "!==" | "<" | "<=" | ">" | ">=",
+    string | number
+];
+
 interface ClientProfile {
-    name:
-        | "android"
-        | "chrome"
-        | "crios"
-        | "edge"
-        | "firefox"
-        | "fxios"
-        | "konqueror"
-        | "msie"
-        | "opera"
-        | "rekong"
-        | "safari"
-        | "silk";
+    name: ClientProfileName;
     layout: "edge" | "gecko" | "khtml" | "presto" | "trident" | "webkit";
     layoutVersion: number;
     platform: "ipad" | "iphone" | "linux" | "mac" | "solaris" | "win";

diff --git a/jquery/textSelection.d.ts b/jquery/textSelection.d.ts
@@ -16,7 +16,7 @@ declare global {
          * @return {JQuery}
          * @chainable
          */
-        textSelection(command: "setContents"): JQuery;
+        textSelection(command: "setContents", content: string): this;
 
         /**
          * Get the currently selected text in this textarea.
@@ -34,7 +34,7 @@ declare global {
          * @return {JQuery}
          * @chainable
          */
-        textSelection(command: "replaceSelection"): JQuery;
+        textSelection(command: "replaceSelection", value: string): this;
 
         /**
          * Insert text at the beginning and end of a text selection, optionally
@@ -49,18 +49,8 @@ declare global {
          */
         textSelection(
             command: "encapsulateSelection",
-            options: {
-                pre?: string;
-                peri?: string;
-                post?: string;
-                ownline?: boolean;
-                replace?: boolean;
-                selectPeri?: boolean;
-                splitlines?: boolean;
-                selectionStart?: number;
-                selectionEnd?: number;
-            }
-        ): JQuery;
+            options?: Partial<TextSelectionEncapsulateOptions>
+        ): this;
 
         /**
          * Get the current cursor position (in UTF-16 code units) in a textarea.
@@ -95,7 +85,7 @@ declare global {
          * @return {JQuery}
          * @chainable
          */
-        textSelection(command: "setSelection", options: { start?: number; end?: number }): JQuery;
+        textSelection(command: "setSelection", options: { start: number; end?: number }): this;
 
         /**
          * Scroll a textarea to the current cursor position. You can set the cursor
@@ -108,7 +98,7 @@ declare global {
          * @return {JQuery}
          * @chainable
          */
-        textSelection(command: "scrollToCaretPosition", options: { force?: boolean }): JQuery;
+        textSelection(command: "scrollToCaretPosition", options: { force?: boolean }): this;
 
         /**
          * Register an alternative textSelection API for this element.
@@ -120,7 +110,7 @@ declare global {
          */
         textSelection(
             command: "register",
-            functions: Record<string, (...commandOptions: any[]) => any>
+            functions: Record<string, (commandOptions: unknown) => any>
         ): void;
 
         /**
@@ -129,7 +119,55 @@ declare global {
          * @param {string} command Command to execute
          */
         textSelection(command: "unregister"): void;
+
+        /**
+         * 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
+         * @return {Mixed} Depending on the command
+         */
+        textSelection(command: string, commandOptions?: any): void;
     }
 }
 
+interface TextSelectionEncapsulateOptions {
+    /**
+     * Text to insert before the cursor/selection.
+     */
+    pre: string;
+    /**
+     * Text to insert between pre and post and select afterwards.
+     */
+    peri: string;
+    /**
+     * Text to insert after the cursor/selection.
+     */
+    post: string;
+    /**
+     * Put the inserted text on a line of its own. Defaults to false.
+     */
+    ownline: boolean;
+    /**
+     * If there is a selection, replace it with peri instead of leaving it alone. Defaults to false.
+     */
+    replace: boolean;
+    /**
+     * Select the peri text if it was inserted (but not if there was a selection and replace==false, or if splitlines==true). Defaults to true.
+     */
+    selectPeri: boolean;
+    /**
+     * If multiple lines are selected, encapsulate each line individually. Defaults to false.
+     */
+    splitlines: boolean;
+    /**
+     * Position to start selection at.
+     */
+    selectionStart: number;
+    /**
+     * Position to end selection at. Defaults to the position to start setection at.
+     */
+    selectionEnd: number;
+}
+
 export {};
diff --git a/mw/Api.d.ts b/mw/Api.d.ts
@@ -5,6 +5,7 @@ import {
     ApiRollbackParams,
     ApiUploadParams,
 } from "../api_params";
+import { UserInfo } from "./user";
 
 type TitleLike = string | mw.Title;
 type TitleLikeArray = string[] | mw.Title[]; // TitleLike[] would be a mixed array
@@ -355,13 +356,10 @@ declare global {
             /**
              * Get the current user's groups and rights.
              *
-             * @returns {JQuery.Promise<{ groups: string[], rights: string[] }>}
+             * @returns {JQuery.Promise<UserInfo>}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.user-method-getUserInfo
              */
-            getUserInfo(): JQuery.Promise<{
-                groups: string[];
-                rights: string[];
-            }>;
+            getUserInfo(): JQuery.Promise<UserInfo>;
 
             /**
              * Extend an API parameter object with an assertion that the user won't change.

diff --git a/mw/Map.d.ts b/mw/Map.d.ts
@@ -24,10 +24,7 @@ declare global {
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-get
              */
             get(): V;
-            get<S extends Array<keyof V>>(
-                selection: S,
-                fallback?: any
-            ): Pick<V, S extends Array<infer SS> ? SS : never>;
+            get<S extends keyof V>(selection: S[], fallback?: any): Pick<V, S>;
             get<S extends keyof V>(selection: S, fallback?: V[S]): V[S];
 
             /**

diff --git a/mw/Rest.d.ts b/mw/Rest.d.ts
@@ -38,12 +38,12 @@ declare global {
              * @param {RestOptions} [options]
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-constructor
              */
-            constructor(options?: RestOptions);
+            constructor(options?: Partial<RestOptions>);
 
             /**
              * @private
              */
-            defaultOptions: RestOptions;
+            defaults: RestOptions;
 
             /**
              * Abort all unfinished requests issued by this Api object.

diff --git a/mw/Title.d.ts b/mw/Title.d.ts
@@ -1,3 +1,5 @@
+import { QueryParams } from "./Uri";
+
 type title = string | mw.Title;
 
 declare global {
@@ -260,7 +262,7 @@ declare global {
              * @return {string}
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getUrl
              */
-            getUrl(params?: any): string;
+            getUrl(params?: QueryParams): string;
 
             /**
              * Check if the title is in a talk namespace
@@ -337,7 +339,7 @@ declare global {
              * @return {Title|null} A valid Title object or null if the title is invalid
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-static-method-newFromFileName
              */
-            static newFromFileName(uncleanName: string): Title;
+            static newFromFileName(uncleanName: string): Title | null;
 
             /**
              * Get the file title from an image element
@@ -385,7 +387,7 @@ declare global {
                 title: string,
                 defaultNamespace?: number,
                 options?: { forUploading: boolean }
-            ): Title;
+            ): Title | null;
 
             /**
              * Normalize a file extension to the common form, making it lowercase and checking some synonyms,

diff --git a/mw/Uri.d.ts b/mw/Uri.d.ts
@@ -1,10 +1,21 @@
-type Options =
-    | {
-          strictMode?: boolean;
-          overrideKeys?: boolean;
-          arrayParams?: boolean;
-      }
-    | boolean;
+export type QueryParams = Record<string, any>;
+
+interface UriOptions {
+    /**
+     * Trigger strict mode parsing of the url.
+     */
+    strictMode: boolean;
+    /**
+     * Whether to let duplicate query parameters override each other (`true`) or automagically convert them to an array (`false`).
+     */
+    overrideKeys: boolean;
+    /**
+     * Whether to parse array query parameters (e.g. `&foo[0]=a&foo[1]=b` or `&foo[]=a&foo[]=b`) or leave them alone.
+     * Currently this does not handle associative or multi-dimensional arrays, but that may be improved in the future.
+     * Implies `overrideKeys: true` (query parameters without `[...]` are not parsed as arrays).
+     */
+    arrayParams: boolean;
+}
 
 declare global {
     namespace mw {
@@ -19,7 +30,7 @@ declare global {
          * @return {Function} An mw.Uri class constructor
          * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-UriRelative
          */
-        function UriRelative(documentLocation: string | ((...args: any[]) => string)): Uri;
+        function UriRelative(documentLocation: string | (() => string)): typeof Uri;
 
         /**
          * Library for simple URI parsing and manipulation.
@@ -111,7 +122,7 @@ declare global {
              * @property {Object} query For example `{ a: '0', b: '', c: 'value' }` (always present)
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-query
              */
-            query: any;
+            query: QueryParams;
             /**
              * @property {string|undefined} user For example `usr`
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-user
@@ -163,31 +174,12 @@ declare global {
              *  other values for other instances -- see mw.UriRelative for details).
              * @param {Object|boolean} [options] Object with options, or (backwards compatibility) a boolean
              *  for strictMode
-             * @param {boolean} [options.strictMode=false] Trigger strict mode parsing of the url.
-             * @param {boolean} [options.overrideKeys=false] Whether to let duplicate query parameters
-             *  override each other (`true`) or automagically convert them to an array (`false`).
-             * @param {boolean} [options.arrayParams=false] Whether to parse array query parameters (e.g.
-             *  `&foo[0]=a&foo[1]=b` or `&foo[]=a&foo[]=b`) or leave them alone. Currently this does not
-             *  handle associative or multi-dimensional arrays, but that may be improved in the future.
-             *  Implies `overrideKeys: true` (query parameters without `[...]` are not parsed as arrays).
              * @throws {Error} when the query string or fragment contains an unknown % sequence
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-constructor
              */
             constructor(
-                uri?:
-                    | string
-                    | Uri
-                    | Partial<{
-                          fragment: string;
-                          host: string;
-                          password: string;
-                          path: string;
-                          port: string;
-                          protocol: string;
-                          query: any;
-                          user: string;
-                      }>,
-                options?: Options
+                uri?: string | Uri | Partial<Record<typeof Uri.properties[number], string>>,
+                options?: Partial<UriOptions> | boolean
             );
 
             /**
@@ -206,7 +198,7 @@ declare global {
              * @return {Uri} This URI object
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-extend
              */
-            extend(parameters: Record<string, any>): Uri;
+            extend(parameters: QueryParams): Uri;
 
             /**
              * Get the userInfo, host and port section of the URI.
@@ -266,7 +258,7 @@ declare global {
              * @return {string} The URI string
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-toString
              */
-            toString(): string;
+            toString(): `${string}://${string}`;
 
             /**
              * Parse a string and set our properties accordingly.
@@ -277,7 +269,7 @@ declare global {
              * @throws {Error} when the query string or fragment contains an unknown % sequence
              * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-parse
              */
-            parse(str: string, options: Options): void;
+            parse(str: string, options: Partial<UriOptions>): void;
 
             /**
              * Decode a url encoded value.