Merge pull request #39 from Derugon/mw

Add more MediaWiki modules

mw/Api.d.ts

@@ -17,7 +17,8 @@ type TypeOrArray<T> = T extends any ? T | T[] : never; // T[] would be a mixed a
 type ReplaceValue<T extends U | U[], U, V> = T extends U[] ? V[] : V;
 
 type UnknownApiParams = Record<string, string | string[] | boolean | number | number[]>;
-type ApiResponse = Record<string, any>; // it will always be a JSON object, the rest is uncertain ...
+
+export type ApiResponse = Record<string, any>; // it will always be a JSON object, the rest is uncertain ...
 
 interface Revision {
     content: string;

mw/ForeignApi.d.ts

@@ -1,6 +1,6 @@
 import { ApiOptions } from "./Api";
 
-interface ForeignApiOptions extends ApiOptions {
+export interface ForeignApiOptions extends ApiOptions {
     /**
      * Whether to perform all requests anonymously. Use this option if the target wiki may otherwise not accept cross-origin requests, or if you don't need to perform write actions or read restricted information and want to avoid the overhead.
      */

mw/ForeignUpload.d.ts

@@ -0,0 +1,59 @@
+import { ApiOptions } from "./Api";
+import { ForeignApiOptions } from "./ForeignApi";
+
+declare global {
+    namespace mw {
+        /**
+         * Used to represent an upload in progress on the frontend.
+         *
+         * Subclassed to upload to a foreign API, with no other goodies. Use
+         * this for a generic foreign image repository on your wiki farm.
+         *
+         * Note you can provide the {@link target} or not - if the first argument is
+         * an object, we assume you want the default, and treat it as apiconfig
+         * instead.
+         */
+        class ForeignUpload extends Upload {
+            static static: {};
+            static super: typeof Upload;
+            /** @deprecated Use `super` instead */
+            static parent: typeof Upload;
+
+            /**
+             * Used to specify the target repository of the upload.
+             *
+             * If you set this to something that isn't 'local', you must be sure to
+             * add that target to $wgForeignUploadTargets in LocalSettings, and the
+             * repository must be set up to use CORS and CentralAuth.
+             *
+             * Most wikis use "shared" to refer to Wikimedia Commons, we assume that
+             * in this class and in the messages linked to it.
+             *
+             * Defaults to the first available foreign upload target,
+             * or to local uploads if no foreign target is configured.
+             */
+            target: string;
+
+            /**
+             * Used to represent an upload in progress on the frontend.
+             *
+             * Subclassed to upload to a foreign API, with no other goodies. Use
+             * this for a generic foreign image repository on your wiki farm.
+             *
+             * Note you can provide the {@link target} or not - if the first argument is
+             * an object, we assume you want the default, and treat it as apiconfig
+             * instead.
+             *
+             * @param {string} [target] Used to set up the target
+             *     wiki. If not remote, this class behaves identically to mw.Upload (unless further subclassed)
+             *     Use the same names as set in $wgForeignFileRepos for this. Also,
+             *     make sure there is an entry in the $wgForeignUploadTargets array for this name.
+             * @param {Partial<ApiOptions>} [apiconfig] Passed to the constructor of mw.ForeignApi or mw.Api, as needed.
+             */
+            constructor(target: string, apiconfig?: Partial<ForeignApiOptions>);
+            constructor(apiconfig?: Partial<ApiOptions>);
+        }
+    }
+}
+
+export {};

mw/Upload.d.ts

@@ -0,0 +1,288 @@
+import { ApiOptions, ApiResponse } from "./Api";
+
+declare global {
+    namespace mw {
+        /**
+         * Used to represent an upload in progress on the frontend.
+         * Most of the functionality is implemented in mw.Api.plugin.upload,
+         * but this model class will tie it together as well as let you perform
+         * actions in a logical way.
+         *
+         * A simple example:
+         *
+         * ```js
+         * var file = new OO.ui.SelectFileWidget(),
+         *     button = new OO.ui.ButtonWidget( { label: 'Save' } ),
+         *     upload = new mw.Upload;
+         *
+         * button.on( 'click', function () {
+         *     upload.setFile( file.getValue() );
+         *     upload.setFilename( file.getValue().name );
+         *     upload.upload();
+         * } );
+         *
+         * $( document.body ).append( file.$element, button.$element );
+         * ```
+         *
+         * You can also choose to {@link uploadToStash stash the upload} and
+         * {@link finishStashUpload finalize} it later:
+         *
+         * ```js
+         * var file, // Some file object
+         *     upload = new mw.Upload,
+         *     stashPromise = $.Deferred();
+         *
+         * upload.setFile( file );
+         * upload.uploadToStash().then( function () {
+         *     stashPromise.resolve();
+         * } );
+         *
+         * stashPromise.then( function () {
+         *     upload.setFilename( 'foo' );
+         *     upload.setText( 'bar' );
+         *     upload.finishStashUpload().then( function () {
+         *         console.log( 'Done!' );
+         *     } );
+         * } );
+         * ```
+         */
+        class Upload {
+            /**
+             * Used to represent an upload in progress on the frontend.
+             * Most of the functionality is implemented in mw.Api.plugin.upload,
+             * but this model class will tie it together as well as let you perform
+             * actions in a logical way.
+             *
+             * A simple example:
+             *
+             * ```js
+             * var file = new OO.ui.SelectFileWidget(),
+             *     button = new OO.ui.ButtonWidget( { label: 'Save' } ),
+             *     upload = new mw.Upload;
+             *
+             * button.on( 'click', function () {
+             *     upload.setFile( file.getValue() );
+             *     upload.setFilename( file.getValue().name );
+             *     upload.upload();
+             * } );
+             *
+             * $( document.body ).append( file.$element, button.$element );
+             * ```
+             *
+             * You can also choose to {@link uploadToStash stash the upload} and
+             * {@link finishStashUpload finalize} it later:
+             *
+             * ```js
+             * var file, // Some file object
+             *     upload = new mw.Upload,
+             *     stashPromise = $.Deferred();
+             *
+             * upload.setFile( file );
+             * upload.uploadToStash().then( function () {
+             *     stashPromise.resolve();
+             * } );
+             *
+             * stashPromise.then( function () {
+             *     upload.setFilename( 'foo' );
+             *     upload.setText( 'bar' );
+             *     upload.finishStashUpload().then( function () {
+             *         console.log( 'Done!' );
+             *     } );
+             * } );
+             * ```
+             *
+             * @param {Api|Partial<ApiOptions>} [apiconfig] A mw.Api object (or subclass), or configuration
+             *     to pass to the constructor of mw.Api.
+             */
+            constructor(apiconfig?: Api | Partial<ApiOptions>);
+
+            /**
+             * Finish a stash upload.
+             *
+             * @returns {JQuery.Promise<ApiResponse>}
+             */
+            finishStashUpload(): JQuery.Promise<ApiResponse>;
+
+            /**
+             * Get the mw.Api instance used by this Upload object.
+             *
+             * @returns {JQuery.Promise<Api>}
+             */
+            getApi(): JQuery.Promise<Api>;
+
+            /**
+             * Gets the base filename from a path name.
+             *
+             * @param {string} path
+             * @returns {string}
+             */
+            getBasename(path: string): string;
+
+            /**
+             * Get the current value of the edit comment for the upload.
+             *
+             * @returns {string}
+             */
+            getComment(): string;
+
+            /**
+             * Get the file being uploaded.
+             *
+             * @returns {HTMLInputElement|File|Blob}
+             */
+            getFile(): HTMLInputElement | File | Blob;
+
+            /**
+             * Get the filename, to be finalized on upload.
+             *
+             * @returns {string}
+             */
+            getFilename(): string;
+
+            /**
+             * Get the imageinfo object for the finished upload.
+             * Only available once the upload is finished! Don't try to get it
+             * beforehand.
+             *
+             * @returns {ApiResponse|undefined}
+             */
+            getImageInfo(): ApiResponse | undefined;
+
+            /**
+             * Gets the state of the upload.
+             *
+             * @returns {Upload.State}
+             */
+            getState(): Upload.State;
+
+            /**
+             * Gets details of the current state.
+             *
+             * @returns {any}
+             */
+            getStateDetails(): any;
+
+            /**
+             * Get the text of the file page, to be created on file upload.
+             *
+             * @returns {string}
+             */
+            getText(): string;
+
+            /**
+             * Get the boolean for whether the file will be watchlisted after upload.
+             *
+             * @returns {boolean}
+             */
+            getWatchlist(): boolean;
+
+            /**
+             * Set the edit comment for the upload.
+             *
+             * @param {string} comment
+             */
+            setComment(comment: string): void;
+
+            /**
+             * Set the file to be uploaded.
+             *
+             * @param {HTMLInputElement|File|Blob} file
+             */
+            setFile(file: HTMLInputElement | File | Blob): void;
+
+            /**
+             * Set the stashed file to finish uploading.
+             *
+             * @param {string} filekey
+             */
+            setFilekey(filekey: string): void;
+
+            /**
+             * Set the filename, to be finalized on upload.
+             *
+             * @param {string} filename
+             */
+            setFilename(filename: string): void;
+
+            /**
+             * Sets the filename based on the filename as it was on the upload.
+             */
+            setFilenameFromFile(): void;
+
+            /**
+             * Sets the state and state details (if any) of the upload.
+             *
+             * @param {Upload.State} state
+             * @param {any} stateDetails
+             */
+            setState(state: Upload.State, stateDetails: any): void;
+
+            /**
+             * Set the text of the file page, to be created on file upload.
+             *
+             * @param {string} text
+             */
+            setText(text: string): void;
+
+            /**
+             * Set whether the file should be watchlisted after upload.
+             *
+             * @param {boolean} watchlist
+             */
+            setWatchlist(watchlist: boolean): void;
+
+            /**
+             * Upload the file directly.
+             *
+             * @returns {JQuery.Promise<ApiResponse>}
+             */
+            upload(): JQuery.Promise<ApiResponse>;
+
+            /**
+             * Upload the file to the stash to be completed later.
+             *
+             * @returns {JQuery.Promise<ApiResponse>}
+             */
+            uploadToStash(): JQuery.Promise<ApiResponse>;
+        }
+
+        namespace Upload {
+            /**
+             * State of uploads represented in simple terms.
+             */
+            enum State {
+                /**
+                 * Upload not yet started
+                 */
+                NEW,
+
+                /**
+                 * Upload finished, but there was a warning
+                 */
+                WARNING,
+
+                /**
+                 * Upload finished, but there was an error
+                 */
+                ERROR,
+
+                /**
+                 * Upload in progress
+                 */
+                UPLOADING,
+
+                /**
+                 * Upload finished, but not published, call #finishStashUpload
+                 */
+                STASHED,
+
+                /**
+                 * Upload finished and published
+                 */
+                UPLOADED,
+            }
+        }
+    }
+}
+
+export {};

mw/cldr.d.ts

@@ -0,0 +1,22 @@
+declare global {
+    namespace mw {
+        /**
+         * Namespace for CLDR-related utility methods.
+         */
+        namespace cldr {
+            /**
+             * Get the plural form index for the number.
+             *
+             * In case none of the rules passed, we return `pluralRules.length` -
+             * that means it is the "other" form.
+             *
+             * @param {number} number
+             * @param {string[]} pluralRules
+             * @returns {number} plural form index
+             */
+            function getPluralForm(number: number, pluralRules: string[]): number;
+        }
+    }
+}
+
+export {};