Merge branch 'main' of https://github.com/Derugon/types-mediawiki

jquery/textSelection.d.ts

@@ -52,6 +52,10 @@ declare global {
                 force?: boolean;
             }
         ): JQuery;
+
+        textSelection(command: "unregister"): void;
+
+        textSelection(command: "register", commandOptions: Record<string, (...args: any[]) => any>): void;
     }
 }
 

mw/RegExp.d.ts

@@ -0,0 +1,26 @@
+declare global {
+    namespace mw {
+        /**
+         * @class mw.RegExp
+         * @see https://doc.wikimedia.org/mediawiki-core/REL1_29/js/source/mediawiki.RegExp.html
+         */
+        namespace RegExp {
+            /**
+             * Escape string for safe inclusion in regular expression
+             *
+             * The following characters are escaped:
+             *
+             *     \ { } ( ) | . ? * + - ^ $ [ ]
+             *
+             * @deprecated
+             * @since 1.26; deprecated since 1.34
+             * @param {string} str String to escape
+             * @return {string} Escaped string
+             * @see https://doc.wikimedia.org/mediawiki-core/REL1_29/js/source/mediawiki.RegExp.html#mw-RegExp-static-method-escape
+             */
+            function escape(str: string): string;
+        }
+    }
+}
+
+export {};

mw/Uri.d.ts

@@ -1,54 +1,259 @@
+type Options =
+    | {
+          strictMode?: boolean;
+          overrideKeys?: boolean;
+          arrayParams?: boolean;
+      }
+    | boolean;
+
 declare global {
     namespace mw {
+        /**
+         * A factory method to create an mw.Uri class with a default location to resolve relative URLs
+         * against (including protocol-relative URLs).
+         *
+         * @method
+         * @param {string|Function} documentLocation A full url, or function returning one.
+         *  If passed a function, the return value may change over time and this will be honoured. (T74334)
+         * @member mw
+         * @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;
+
         class Uri {
+            /**
+             * @property {string|undefined} fragment For example `top`
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-fragment
+             */
             fragment: string | undefined;
+            /**
+             * @property {string} host For example `www.example.com` (always present)
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-host
+             */
             host: string;
+            /**
+             * @property {string|undefined} password For example `pwd`
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-password
+             */
             password: string | undefined;
+            /**
+             * @property {string} path For example `/dir/dir.2/index.htm` (always present)
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-path
+             */
             path: string;
+            /**
+             * @property {string|undefined} port For example `81`
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-port
+             */
             port: string | undefined;
+            /**
+             * @property {string} protocol For example `http` (always present)
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-protocol
+             */
             protocol: string;
+            /**
+             * @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;
+            /**
+             * @property {string|undefined} user For example `usr`
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-user
+             */
             user: string | undefined;
 
+            /**
+             * Regular expressions to parse many common URIs.
+             *
+             * These are gnarly expressions. For improved readability, they have been moved to a separate
+             * file where they make use of named capture groups. That syntax isn't valid in JavaScript ES5,
+             * so the server-side strips these before delivering to the client.
+             *
+             * @private
+             * @static
+             * @property {Object} parser
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-static-property-parser
+             */
+            static parser: {
+                strict: RegExp;
+                loose: RegExp;
+            };
+
+            /**
+             * The order here matches the order of captured matches in the `parser` property regexes.
+             *
+             * @private
+             * @static
+             * @property {string[]} properties
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-static-property-properties
+             */
+            static properties: [
+                "protocol",
+                "user",
+                "password",
+                "host",
+                "port",
+                "path",
+                "query",
+                "fragment"
+            ];
+
+            /**
+             * Construct a new URI object. Throws error if arguments are illegal/impossible, or
+             * otherwise don't parse.
+             *
+             * @class mw.Uri
+             * @constructor
+             * @param {Object|string} [uri] URI string, or an Object with appropriate properties (especially
+             *  another URI object to clone). Object must have non-blank `protocol`, `host`, and `path`
+             *  properties. If omitted (or set to `undefined`, `null` or empty string), then an object
+             *  will be created for the default `uri` of this constructor (`location.href` for mw.Uri,
+             *  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
-                    | mw.Uri
-                    | {
-                          fragment?: string;
+                    | Uri
+                    | Partial<{
+                          fragment: string;
                           host: string;
-                          password?: string;
+                          password: string;
                           path: string;
-                          port?: string;
+                          port: string;
                           protocol: string;
-                          query?: any;
-                          user?: string;
-                      },
-                options?: {
-                    strictMode?: boolean;
-                    overrideKeys?: boolean;
-                    arrayParams?: boolean;
-                }
+                          query: any;
+                          user: string;
+                      }>,
+                options?: Options
             );
 
-            clone(): mw.Uri;
+            /**
+             * Clone this URI
+             *
+             * @return {Uri} New URI object with same properties
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-clone
+             */
+            clone(): Uri;
 
-            extend(parameters: any): mw.Uri;
+            /**
+             * Extend the query section of the URI with new parameters.
+             *
+             * @param {Object} parameters Query parameters to add to ours (or to override ours with) as an
+             *  object
+             * @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;
 
+            /**
+             * Get the userInfo, host and port section of the URI.
+             *
+             * In most real-world URLs this is simply the hostname, but the definition of 'authority' section is more general.
+             *
+             * @return {string}
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-getAuthority
+             */
             getAuthority(): string;
 
+            /**
+             * Get host and port section of a URI.
+             *
+             * @return {string}
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-getHostPort
+             */
             getHostPort(): string;
 
+            /**
+             * Get the query arguments of the URL, encoded into a string.
+             *
+             * Does not preserve the original order of arguments passed in the URI. Does handle escaping.
+             *
+             * @return {string}
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-getQueryString
+             */
             getQueryString(): string;
 
+            /**
+             * Get everything after the authority section of the URI.
+             *
+             * @return {string}
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-getRelativePath
+             */
             getRelativePath(): string;
 
+            /**
+             * Get user and password section of a URI.
+             *
+             * @return {string}
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-getUserInfo
+             */
             getUserInfo(): string;
 
+            /**
+             * Get the entire URI string.
+             *
+             * Note that the output may not be precisely the same as the constructor input,
+             * due to order of query arguments.
+             * Note also that the fragment is not always roundtripped as-is; some characters will
+             * become encoded, including the slash character, which can cause problems with e.g.
+             * mediawiki.router. It is recommended to use the native URL class (via
+             * web2017-polyfills, which loads a polyfill if needed) in contexts where the fragment
+             * is important.
+             *
+             * @return {string} The URI string
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-toString
+             */
             toString(): string;
 
+            /**
+             * Parse a string and set our properties accordingly.
+             *
+             * @private
+             * @param {string} str URI, see constructor.
+             * @param {Object} options See constructor.
+             * @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;
+
+            /**
+             * Decode a url encoded value.
+             *
+             * Reversed #encode. Standard decodeURIComponent, with addition of replacing
+             * `+` with a space.
+             *
+             * @static
+             * @param {string} s String to decode
+             * @return {string} Decoded string
+             * @throws {Error} when the string contains an unknown % sequence
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-static-method-decode
+             */
             static decode(s: string): string;
 
+            /**
+             * Encode a value for inclusion in a url.
+             *
+             * Standard encodeURIComponent, with extra stuff to make all browsers work similarly and more
+             * compliant with RFC 3986. Similar to rawurlencode from PHP and our JS library
+             * mw.util.rawurlencode, except this also replaces spaces with `+`.
+             *
+             * @static
+             * @param {string} s String to encode
+             * @return {string} Encoded string for URI
+             * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-static-method-encode
+             */
             static encode(s: string): string;
         }
     }

mw/config.d.ts

@@ -64,6 +64,7 @@ declare global {
             wgDiffOldId: number | false;
             wgDiffNewId: number;
             wgWikibaseItemId: string;
+            wgUrlProtocols: string;
             [key: string]: unknown; // more config keys can be added by extensions
         }>;
     }

mw/experiments.d.ts

@@ -4,25 +4,54 @@ interface Experiment {
      */
     name: string;
     /**
-     * Whether the experiment is enabled
+     * Whether the experiment is enabled. If the experiment is disabled, then the user is always assigned to the control bucket
      */
     enabled: boolean;
     /**
-     * An object consisting of the experiment's buckets ("control" and at least one bucket) and their probabilities (a number < 1, eg 0.25)
+     * A map of bucket name to probability that the user will be assigned to that bucket
      */
     buckets: Record<string, number>;
 }
 
 declare global {
     namespace mw {
+        /**
+         * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.experiments
+         */
         namespace experiment {
             /**
-             * Get a bucket for a user for the given experiment
-             * @param {string} token A unique identifier for the user
-             * @param {Experiment} experiment The expermient to get a bucket from
-             * @returns {string} The name of the chosen bucket (for example, if the buckets were "control", "a" and "b", it could return "b")
+             * Gets the bucket for the experiment given the token.
+             *
+             * The name of the experiment and the token are hashed. The hash is converted
+             * to a number which is then used to get a bucket.
+             *
+             * @example
+             * // The experiment has three buckets: control, A, and B. The user has a 50% chance of
+             * // being assigned to the control bucket, and a 25% chance of being assigned to either
+             * // the A or B bucket. If the experiment were disabled, then the user would always be
+             * // assigned to the control bucket.
+             * {
+             *   name: 'My first experiment',
+             *   enabled: true,
+             *   buckets: {
+             *     control: 0.5
+             *     A: 0.25,
+             *     B: 0.25
+             *   }
+             * }
+             *
+             * @param {Object} experiment
+             * @param {string} experiment.name The name of the experiment
+             * @param {boolean} experiment.enabled Whether or not the experiment is
+             *  enabled. If the experiment is disabled, then the user is always assigned
+             *  to the control bucket
+             * @param {Object} experiment.buckets A map of bucket name to probability
+             *  that the user will be assigned to that bucket
+             * @param {string} token A token that uniquely identifies the user for the
+             *  duration of the experiment
+             * @return {string|undefined} The bucket
              */
-            function getBucket(experiment: Experiment, token: string): string;
+            function getBucket(experiment: Experiment, token: string): string | undefined;
         }
     }
 }