diff --git a/README.md b/README.md index 89895fc..f6e36fa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ [![NPM version](https://img.shields.io/npm/v/types-mediawiki.svg)](https://www.npmjs.com/package/types-mediawiki) ![Linter](https://github.com/wikimedia-gadgets/types-mediawiki/workflows/Lint/badge.svg) -[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) # types-mediawiki @@ -60,6 +59,8 @@ Since it is just a type import, it doesn't generate any JavaScript. Hence, such --- TODO: +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) -- Add doc comments for everything. Presently they are rarely there. +- Add doc comments for mw.Title, mw.Uri, mw.storage, mw.language and mw.loader. - Add types for more jQuery plugins. +- Add types for mw.experiments diff --git a/mw/Api.d.ts b/mw/Api.d.ts index 00de69c..6d436fb 100644 --- a/mw/Api.d.ts +++ b/mw/Api.d.ts @@ -67,10 +67,10 @@ declare global { */ constructor(options?: ApiOptions); - /** - * @private - */ - defaults: ApiOptions; + /** + * @private + */ + defaults: ApiOptions; /** * Abort all unfinished requests issued by this Api object. diff --git a/mw/config.d.ts b/mw/config.d.ts index eb05a44..8ba7e4d 100644 --- a/mw/config.d.ts +++ b/mw/config.d.ts @@ -1,72 +1,71 @@ declare global { - namespace mw { - - /** - * Map of configuration values. - * - * Check out [the complete list of configuration values](https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#mw.config) - * on mediawiki.org. - * - * If `$wgLegacyJavaScriptGlobals` is true, this Map will add its values to the - * global `window` object. - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-property-config - */ - const config: mw.Map<{ - debug: boolean; - skin: string; - stylepath: string; - wgArticlePath: string; - wgCaseSensitiveNamespaces: string[]; - wgContentLanguage: string; - wgContentNamespaces: number[]; - wgDBname: string; - wgEnableAPI: boolean; - wgEnableWriteAPI: boolean; - wgExtensionAssetsPath: string; - wgFormattedNamespaces: Record; - wgNamespaceIds: Record; - wgScript: string; - wgScriptPath: string; - wgServer: string; - wgSiteName: string; - wgVariantArticlePath: string | false; - wgVersion: string; - wgAction: string; - wgArticleId: number; - wgCanonicalNamespace: string; - wgCanonicalSpecialPageName: string | false; - wgCategories: string[]; - wgCurRevisionId: number; - wgIsArticle: boolean; - wgIsProbablyEditable: boolean; - wgNamespaceNumber: number; - wgPageContentLanguage: string; - wgPageContentModel: string; - wgPageName: string; - wgRedirectedFrom: string; - wgRelevantPageName: string; - wgRelevantUserName: string; - wgRelevantPageIsProbablyEditable: boolean; - wgRestrictionEdit: string[]; - wgRestrictionMove: string[]; - wgRevisionId: number; - wgSearchType: string; - wgTitle: string; - wgUserEditCount: number; - wgUserGroups: string[]; - wgUserId: number; - wgUserLanguage: string; - wgUserName: string; - wgUserRegistration: number; - wgIsMainPage: boolean; - wgUserVariant: string; - wgPostEdit: string; - wgDiffOldId: number | false; - wgDiffNewId: number; - wgWikibaseItemId: string; - [key: string]: unknown; // more config keys can be added by extensions - }>; - } + namespace mw { + /** + * Map of configuration values. + * + * Check out [the complete list of configuration values](https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#mw.config) + * on mediawiki.org. + * + * If `$wgLegacyJavaScriptGlobals` is true, this Map will add its values to the + * global `window` object. + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-property-config + */ + const config: mw.Map<{ + debug: boolean; + skin: string; + stylepath: string; + wgArticlePath: string; + wgCaseSensitiveNamespaces: string[]; + wgContentLanguage: string; + wgContentNamespaces: number[]; + wgDBname: string; + wgEnableAPI: boolean; + wgEnableWriteAPI: boolean; + wgExtensionAssetsPath: string; + wgFormattedNamespaces: Record; + wgNamespaceIds: Record; + wgScript: string; + wgScriptPath: string; + wgServer: string; + wgSiteName: string; + wgVariantArticlePath: string | false; + wgVersion: string; + wgAction: string; + wgArticleId: number; + wgCanonicalNamespace: string; + wgCanonicalSpecialPageName: string | false; + wgCategories: string[]; + wgCurRevisionId: number; + wgIsArticle: boolean; + wgIsProbablyEditable: boolean; + wgNamespaceNumber: number; + wgPageContentLanguage: string; + wgPageContentModel: string; + wgPageName: string; + wgRedirectedFrom: string; + wgRelevantPageName: string; + wgRelevantUserName: string; + wgRelevantPageIsProbablyEditable: boolean; + wgRestrictionEdit: string[]; + wgRestrictionMove: string[]; + wgRevisionId: number; + wgSearchType: string; + wgTitle: string; + wgUserEditCount: number; + wgUserGroups: string[]; + wgUserId: number; + wgUserLanguage: string; + wgUserName: string; + wgUserRegistration: number; + wgIsMainPage: boolean; + wgUserVariant: string; + wgPostEdit: string; + wgDiffOldId: number | false; + wgDiffNewId: number; + wgWikibaseItemId: string; + [key: string]: unknown; // more config keys can be added by extensions + }>; + } } -export {}; \ No newline at end of file +export {}; diff --git a/mw/index.d.ts b/mw/index.d.ts index d1317d3..1940cdf 100644 --- a/mw/index.d.ts +++ b/mw/index.d.ts @@ -25,114 +25,116 @@ declare global { * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw */ namespace mw { + /** + * Format a string. Replace $1, $2 ... $N with positional arguments. + * + * Used by Message#parser(). + * + * @since 1.25 + * @param {string} formatString Format string + * @param {...Mixed} parameters Values for $N replacements + * @return {string} Formatted string + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-format + */ + function format(formatString: string, ...parameters: unknown[]): string; - /** - * Format a string. Replace $1, $2 ... $N with positional arguments. - * - * Used by Message#parser(). - * - * @since 1.25 - * @param {string} formatString Format string - * @param {...Mixed} parameters Values for $N replacements - * @return {string} Formatted string - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-format - */ - function format(formatString: string, ...parameters: unknown[]): string; + /** + * Get the current time, measured in milliseconds since January 1, 1970 (UTC). + * + * On browsers that implement the Navigation Timing API, this function will produce + * floating-point values with microsecond precision that are guaranteed to be monotonic. + * On all other browsers, it will fall back to using `Date`. + * + * @return {number} Current time + */ + function now(): number; - /** - * Get the current time, measured in milliseconds since January 1, 1970 (UTC). - * - * On browsers that implement the Navigation Timing API, this function will produce - * floating-point values with microsecond precision that are guaranteed to be monotonic. - * On all other browsers, it will fall back to using `Date`. - * - * @return {number} Current time - */ - function now(): number; + /** + * Schedule a deferred task to run in the background. + * + * This allows code to perform tasks in the main thread without impacting + * time-critical operations such as animations and response to input events. + * + * Basic logic is as follows: + * + * - User input event should be acknowledged within 100ms per [RAIL]. + * - Idle work should be grouped in blocks of upto 50ms so that enough time + * remains for the event handler to execute and any rendering to take place. + * - Whenever a native event happens (e.g. user input), the deadline for any + * running idle callback drops to 0. + * - As long as the deadline is non-zero, other callbacks pending may be + * executed in the same idle period. + * + * See also: + * + * - + * - + * - + * [RAIL]: https://developers.google.com/web/fundamentals/performance/rail + * + * @member mw + * @param {Function} callback + * @param {Object} [options] + * @param {number} [options.timeout] If set, the callback will be scheduled for + * immediate execution after this amount of time (in milliseconds) if it didn't run + * by that time. + */ + function requestIdleCallback(callback: (...args: any[]) => any): void; - /** - * Schedule a deferred task to run in the background. - * - * This allows code to perform tasks in the main thread without impacting - * time-critical operations such as animations and response to input events. - * - * Basic logic is as follows: - * - * - User input event should be acknowledged within 100ms per [RAIL]. - * - Idle work should be grouped in blocks of upto 50ms so that enough time - * remains for the event handler to execute and any rendering to take place. - * - Whenever a native event happens (e.g. user input), the deadline for any - * running idle callback drops to 0. - * - As long as the deadline is non-zero, other callbacks pending may be - * executed in the same idle period. - * - * See also: - * - * - - * - - * - - * [RAIL]: https://developers.google.com/web/fundamentals/performance/rail - * - * @member mw - * @param {Function} callback - * @param {Object} [options] - * @param {number} [options.timeout] If set, the callback will be scheduled for - * immediate execution after this amount of time (in milliseconds) if it didn't run - * by that time. - */ - function requestIdleCallback(callback: ((...args: any[]) => any)): void; + /** + * Track an analytic event. + * + * This method provides a generic means for MediaWiki JavaScript code to capture state + * information for analysis. Each logged event specifies a string topic name that describes + * the kind of event that it is. Topic names consist of dot-separated path components, + * arranged from most general to most specific. Each path component should have a clear and + * well-defined purpose. + * + * Data handlers are registered via `mw.trackSubscribe`, and receive the full set of + * events that match their subscription, including those that fired before the handler was + * bound. + * + * @param {string} topic Topic name + * @param {Object|number|string} [data] Data describing the event. + */ + function track(topic: string, data?: object | number | string): void; - /** - * Track an analytic event. - * - * This method provides a generic means for MediaWiki JavaScript code to capture state - * information for analysis. Each logged event specifies a string topic name that describes - * the kind of event that it is. Topic names consist of dot-separated path components, - * arranged from most general to most specific. Each path component should have a clear and - * well-defined purpose. - * - * Data handlers are registered via `mw.trackSubscribe`, and receive the full set of - * events that match their subscription, including those that fired before the handler was - * bound. - * - * @param {string} topic Topic name - * @param {Object|number|string} [data] Data describing the event. - */ - function track(topic: string, data?: object | number | string): void; + /** + * Track an early error event via mw.track and send it to the window console. + * + * @private + * @param {string} topic Topic name + * @param {Object} data Data describing the event, encoded as an object; see mw#logError + */ + function trackError(topic: string, data: object): void; - /** - * Track an early error event via mw.track and send it to the window console. - * - * @private - * @param {string} topic Topic name - * @param {Object} data Data describing the event, encoded as an object; see mw#logError - */ - function trackError(topic: string, data: object): void; + /** + * Register a handler for subset of analytic events, specified by topic. + * + * Handlers will be called once for each tracked event, including any events that fired before the + * handler was registered; 'this' is set to a plain object with a topic' property naming the event, and a + * 'data' property which is an object of event-specific data. The event topic and event data are + * also passed to the callback as the first and second arguments, respectively. + * + * @param {string} topic Handle events whose name starts with this string prefix + * @param {Function} callback Handler to call for each matching tracked event + * @param {string} callback.topic + * @param {Object} [callback.data] + */ + function trackSubscribe( + topic: string, + callback: (topic: string, data: object) => any + ): void; - /** - * Register a handler for subset of analytic events, specified by topic. - * - * Handlers will be called once for each tracked event, including any events that fired before the - * handler was registered; 'this' is set to a plain object with a topic' property naming the event, and a - * 'data' property which is an object of event-specific data. The event topic and event data are - * also passed to the callback as the first and second arguments, respectively. - * - * @param {string} topic Handle events whose name starts with this string prefix - * @param {Function} callback Handler to call for each matching tracked event - * @param {string} callback.topic - * @param {Object} [callback.data] - */ - function trackSubscribe(topic: string, callback: ((topic: string, data: object) => any)): void; + /** + * Stop handling events for a particular handler + * + * @param {Function} callback + */ + function trackUnsubscribe(callback: (topic: string, data: object) => any): void; - /** - * Stop handling events for a particular handler - * - * @param {Function} callback - */ - function trackUnsubscribe(callback: Function): void; - - // types for mw.widgets are out of scope! - const widgets: any; + // types for mw.widgets are out of scope! + const widgets: any; } } diff --git a/mw/user.d.ts b/mw/user.d.ts index d48a6c2..e206207 100644 --- a/mw/user.d.ts +++ b/mw/user.d.ts @@ -4,7 +4,7 @@ declare global { * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.user */ namespace user { - // TODO: add types for items in the options map + // TODO: add types for items in the options map const options: mw.Map; const tokens: mw.Map<{ diff --git a/package-lock.json b/package-lock.json index 55ba5a1..ab19694 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,11 +1,11 @@ { "name": "types-mediawiki", - "version": "1.1.0", + "version": "1.2.0", "lockfileVersion": 2, "requires": true, "packages": { "": { - "version": "1.1.0", + "version": "1.2.0", "license": "GPL-3.0-or-later", "dependencies": { "@types/jquery": "^3.5.5" @@ -2066,7 +2066,6 @@ "graceful-fs": "^4.1.6", "normalize-package-data": "~1.0.1 || ^2.0.0", "npm-package-arg": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0", - "npmlog": "2 || ^3.1.0 || ^4.0.0", "once": "^1.3.3", "request": "^2.74.0", "retry": "^0.10.0", diff --git a/package.json b/package.json index 3b7af10..3b5ff37 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,11 @@ { "name": "types-mediawiki", - "version": "1.1.0", + "version": "1.2.0", "description": "TypeScript definitions for MediaWiki JS interface", "types": "index.d.ts", "scripts": { - "lint": "dtslint --localTs node_modules/typescript/lib . && prettier --write ." + "lint": "dtslint --localTs node_modules/typescript/lib .", + "format": "prettier --write ." }, "repository": { "type": "git", @@ -38,6 +39,6 @@ } }, "lint-staged": { - "*.ts(x)?": "npm run lint" + "*.ts(x)?": "prettier --write" } }