diff --git a/README.md b/README.md index e429444..f059ec8 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Edit your project's `tsconfig.json` file so that it includes ] ``` -You should be all set! `mw` will be available in the global scope. There is no need to put any import statements in the TypeScript source files. +You should be all set! `mw` will be available in the global scope. There is no need to put any import statements in the TypeScript source files. **If you find any errors or have suggestions for more specific typings, please open a PR or file an issue.** @@ -58,4 +58,3 @@ import type { ApiEditPageParams, ApiParseParams } from "types-mediawiki/api_para ``` Since it is just a type import, it doesn't generate any JavaScript. Hence, such imports can also be used in non-modular applications. - diff --git a/api_params/index.d.ts b/api_params/index.d.ts index 17a57ce..287a89d 100644 --- a/api_params/index.d.ts +++ b/api_params/index.d.ts @@ -1,3 +1,5 @@ +// tslint:disable:no-empty-interface + type timestamp = string; type expiry = string; type namespace = number; @@ -6,6 +8,30 @@ type password = string; type upload = File; // XXX type OneOrMore = T | T[]; +export type ApiAssert = "anon" | "bot" | "user"; + +export type ApiTokenType = + | "createaccount" + | "csrf" + | "deleteglobalaccount" + | "login" + | "patrol" + | "rollback" + | "setglobalaccountstatus" + | "userrights" + | "watch"; + +export type ApiLegacyTokenType = + | "block" + | "delete" + | "edit" + | "email" + | "import" + | "move" + | "options" + | "protect" + | "unblock"; + export interface ApiParams { action?: string; format?: "json" | "jsonfm" | "xml" | "xmlfm" | "php" | "none"; @@ -32,6 +58,8 @@ export interface ApiParams { formatversion?: "1" | "2" | "latest"; } +export {}; + // AUTOMATICALLY GENERATED FROM HERE: export interface AbuseFilterApiCheckMatchParams extends ApiParams { @@ -61,7 +89,9 @@ export interface AbuseFilterApiAbuseLogPrivateDetailsParams extends ApiParams { token?: string; } -export interface ApiAntiSpoofParams extends ApiParams { +export interface ApiAcquireTempUserNameParams extends ApiParams {} + +export interface AntiSpoofApiAntiSpoofParams extends ApiParams { username?: string; } @@ -86,16 +116,16 @@ export interface ApiBlockParams extends ApiParams { token?: string; } -export interface ApiBounceHandlerParams extends ApiParams { +export interface BounceHandlerApiBounceHandlerParams extends ApiParams { email?: string; } -export interface ApiCategoryTreeParams extends ApiParams { +export interface CategoryTreeApiCategoryTreeParams extends ApiParams { category?: string; options?: string; } -export interface ApiCentralAuthTokenParams extends ApiParams {} +export interface CentralAuthApiCentralAuthTokenParams extends ApiParams {} export interface ApiCentralNoticeCdnCacheUpdateBannerParams extends ApiParams { banner?: string; @@ -113,8 +143,8 @@ export interface ApiCentralNoticeQueryCampaignParams extends ApiParams { } export interface ApiChangeAuthenticationDataParams extends ApiParams { - request?: string; - token?: string; + changeauthrequest?: string; + changeauthtoken?: string; } export interface ApiChangeContentModelParams extends ApiParams { @@ -153,7 +183,9 @@ export interface ApiCheckTokenParams extends ApiParams { maxtokenage?: number; } -export interface CirrusSearchApiConfigDumpParams extends ApiParams {} +export interface CirrusSearchApiConfigDumpParams extends ApiParams { + prop?: OneOrMore<"globals" | "namespacemap" | "profiles" | "replicagroup" | "usertesting">; +} export interface CirrusSearchApiMappingDumpParams extends ApiParams {} @@ -166,13 +198,33 @@ export interface CirrusSearchApiSettingsDumpParams extends ApiParams {} export interface ApiClearHasMsgParams extends ApiParams {} export interface ApiClientLoginParams extends ApiParams { - requests?: string | string[]; - messageformat?: "html" | "none" | "raw" | "wikitext"; - mergerequestfields?: boolean; - preservestate?: boolean; - returnurl?: string; - continue?: boolean; - token?: string; + loginrequests?: string | string[]; + loginmessageformat?: "html" | "none" | "raw" | "wikitext"; + loginmergerequestfields?: boolean; + loginpreservestate?: boolean; + loginreturnurl?: string; + logincontinue?: boolean; + logintoken?: string; +} + +export interface CollectionApiCollectionParams extends ApiParams { + submodule?: + | "addarticle" + | "addcategory" + | "addchapter" + | "clearcollection" + | "getbookcreatorboxcontent" + | "getcollection" + | "getpopupdata" + | "postcollection" + | "removearticle" + | "removeitem" + | "renamechapter" + | "setsorting" + | "settitles" + | "sortitems" + | "suggestarticleaction" + | "suggestundoarticleaction"; } export interface ApiComparePagesParams extends ApiParams { @@ -252,19 +304,20 @@ export interface ApiComparePagesParams extends ApiParams { | "user" >; slots?: OneOrMore<"main">; + difftype?: "inline" | "table" | "unified"; } export interface ApiAMCreateAccountParams extends ApiParams { - requests?: string | string[]; - messageformat?: "html" | "none" | "raw" | "wikitext"; - mergerequestfields?: boolean; - preservestate?: boolean; - returnurl?: string; - continue?: boolean; - token?: string; + createrequests?: string | string[]; + createmessageformat?: "html" | "none" | "raw" | "wikitext"; + createmergerequestfields?: boolean; + createpreservestate?: boolean; + createreturnurl?: string; + createcontinue?: boolean; + createtoken?: string; } -export interface ApiCreateLocalAccountParams extends ApiParams { +export interface CentralAuthApiCreateLocalAccountParams extends ApiParams { username?: string; reason?: string; token?: string; @@ -275,19 +328,14 @@ export interface ApiCSPReportParams extends ApiParams { source?: string; } -export interface ApiContentTranslationConfigurationParams extends ApiParams { - from?: string; - to?: string; -} - -export interface ApiContentTranslationDeleteParams extends ApiParams { +export interface ContentTranslationActionApiContentTranslationDeleteParams extends ApiParams { from?: string; to?: string; sourcetitle?: string; token?: string; } -export interface ApiContentTranslationPublishParams extends ApiParams { +export interface ContentTranslationActionApiContentTranslationPublishParams extends ApiParams { title?: string; html?: string; from?: string; @@ -310,13 +358,14 @@ export interface ContentTranslationActionApiSectionTranslationPublishParams exte sourcerevid?: string; sourcesectiontitle?: string; targetsectiontitle?: string; - sectionnumber?: string; + sectiontranslationid?: number; + issandbox?: boolean; captchaid?: string; captchaword?: string; token?: string; } -export interface ApiContentTranslationSaveParams extends ApiParams { +export interface ContentTranslationActionApiContentTranslationSaveParams extends ApiParams { from?: string; to?: string; sourcetitle?: string; @@ -330,7 +379,8 @@ export interface ApiContentTranslationSaveParams extends ApiParams { token?: string; } -export interface ApiContentTranslationSuggestionListParams extends ApiParams { +export interface ContentTranslationActionApiContentTranslationSuggestionListParams + extends ApiParams { listname?: string; listaction?: "add" | "remove" | "view"; titles?: string | string[]; @@ -339,7 +389,7 @@ export interface ApiContentTranslationSuggestionListParams extends ApiParams { token?: string; } -export interface ApiContentTranslationTokenParams extends ApiParams { +export interface ContentTranslationActionApiContentTranslationTokenParams extends ApiParams { token?: string; } @@ -348,6 +398,7 @@ export interface ApiDeleteParams extends ApiParams { pageid?: number; reason?: string; tags?: string | string[]; + deletetalk?: boolean; watch?: boolean; watchlist?: "nochange" | "preferences" | "unwatch" | "watch"; watchlistexpiry?: expiry; @@ -356,33 +407,98 @@ export interface ApiDeleteParams extends ApiParams { token?: string; } -export interface ApiDeleteGlobalAccountParams extends ApiParams { +export interface CentralAuthApiDeleteGlobalAccountParams extends ApiParams { user?: string; reason?: string; token?: string; } -export interface DiscussionToolsApiDiscussionToolsParams extends ApiParams { - paction?: "transcludedfrom"; - page?: string; - oldid?: string; +export interface DiscussionToolsApiDiscussionToolsCompareParams extends ApiParams { + fromtitle?: string; + fromrev?: number; + totitle?: string; + torev?: number; } export interface DiscussionToolsApiDiscussionToolsEditParams extends ApiParams { paction?: "addcomment" | "addtopic"; + autosubscribe?: "default" | "no" | "yes"; page?: string; token?: string; + formtoken?: string; + commentname?: string; commentid?: string; wikitext?: string; html?: string; summary?: string; sectiontitle?: string; + allownosectiontitle?: boolean; + useskin?: + | "apioutput" + | "cologneblue" + | "contenttranslation" + | "fallback" + | "minerva" + | "modern" + | "monobook" + | "timeless" + | "vector" + | "vector-2022"; watchlist?: string; captchaid?: string; captchaword?: string; + nocontent?: string; + tags?: string | string[]; + returnto?: string; + returntoquery?: string; + returntoanchor?: string; + mobileformat?: boolean; +} + +export interface DiscussionToolsApiDiscussionToolsFindCommentParams extends ApiParams { + idorname?: string; + heading?: string; + page?: string; +} + +export interface DiscussionToolsApiDiscussionToolsGetSubscriptionsParams extends ApiParams { + commentname?: string | string[]; +} + +export interface DiscussionToolsApiDiscussionToolsPageInfoParams extends ApiParams { + page?: string; + oldid?: number; + prop?: OneOrMore<"threaditemshtml" | "transcludedfrom">; + excludesignatures?: boolean; +} + +export interface DiscussionToolsApiDiscussionToolsPreviewParams extends ApiParams { + type?: "reply" | "topic"; + page?: string; + wikitext?: string; + sectiontitle?: string; + useskin?: + | "apioutput" + | "cologneblue" + | "contenttranslation" + | "fallback" + | "minerva" + | "modern" + | "monobook" + | "timeless" + | "vector" + | "vector-2022"; + mobileformat?: boolean; +} + +export interface DiscussionToolsApiDiscussionToolsSubscribeParams extends ApiParams { + page?: string; + token?: string; + commentname?: string; + subscribe?: boolean; } -export interface ApiEchoMarkReadParams extends ApiParams { +export interface NotificationsApiEchoMarkReadParams extends ApiParams { wikis?: string | string[]; list?: string | string[]; unreadlist?: string | string[]; @@ -391,19 +507,19 @@ export interface ApiEchoMarkReadParams extends ApiParams { token?: string; } -export interface ApiEchoMarkSeenParams extends ApiParams { +export interface NotificationsApiEchoMarkSeenParams extends ApiParams { type?: "alert" | "all" | "message"; timestampFormat?: "ISO_8601" | "MW"; } -export interface ApiEchoMuteParams extends ApiParams { +export interface NotificationsApiEchoMuteParams extends ApiParams { type?: "page-linked-title" | "user"; mute?: string | string[]; unmute?: string | string[]; token?: string; } -export interface EchoPushApiEchoPushSubscriptionsParams extends ApiParams { +export interface NotificationsPushApiEchoPushSubscriptionsParams extends ApiParams { command?: "create" | "delete"; token?: string; } @@ -460,6 +576,9 @@ export interface ApiEditPageParams extends ApiParams { | "unknown" | "wikitext"; token?: string; + returnto?: string; + returntoquery?: string; + returntoanchor?: string; captchaword?: string; captchaid?: string; } @@ -469,6 +588,8 @@ export interface MediaWikiMassMessageApiEditMassMessageListParams extends ApiPar description?: string; add?: string | string[]; remove?: string | string[]; + minor?: boolean; + watchlist?: "nochange" | "preferences" | "unwatch" | "watch"; token?: string; } @@ -496,6 +617,7 @@ export interface ApiExpandTemplatesParams extends ApiParams { | "wikitext" >; includecomments?: boolean; + showstrategykeys?: boolean; generatexml?: boolean; templatesandboxprefix?: string | string[]; templatesandboxtitle?: string; @@ -526,9 +648,9 @@ export interface ApiExpandTemplatesParams extends ApiParams { | "unknown/unknown"; } -export interface ApiFancyCaptchaReloadParams extends ApiParams {} +export interface ConfirmEditFancyCaptchaApiFancyCaptchaReloadParams extends ApiParams {} -export interface ApiFeaturedFeedsParams extends ApiParams { +export interface FeaturedFeedsApiFeaturedFeedsParams extends ApiParams { feedformat?: "atom" | "rss"; feed?: "featured" | "onthisday" | "potd"; language?: string; @@ -564,6 +686,7 @@ export interface ApiFeedRecentChangesParams extends ApiParams { hidemyself?: boolean; hidecategorization?: boolean; tagfilter?: string | string[]; + inverttags?: boolean; target?: string; showlinkedto?: boolean; } @@ -602,15 +725,17 @@ export interface ApiFileRevertParams extends ApiParams { export interface ApiFlagConfigParams extends ApiParams {} -export interface ApiGlobalBlockParams extends ApiParams { +export interface GlobalBlockingApiGlobalBlockParams extends ApiParams { target?: string; - expiry?: string; + expiry?: expiry; unblock?: boolean; reason?: string; anononly?: boolean; modify?: boolean; alsolocal?: boolean; localblockstalk?: boolean; + localblocksemail?: boolean; + localanononly?: boolean; token?: string; } @@ -648,7 +773,7 @@ export interface GlobalPreferencesApiGlobalPreferencesParams extends ApiParams { token?: string; } -export interface ApiGlobalUserRightsParams extends ApiParams { +export interface CentralAuthApiGlobalUserRightsParams extends ApiParams { user?: string; userid?: number; add?: OneOrMore< @@ -667,14 +792,15 @@ export interface ApiGlobalUserRightsParams extends ApiParams { | "new-wikis-importer" | "oathauth-tester" | "ombuds" - | "otrs-member" | "recursive-export" | "staff" | "steward" | "sysadmin" - | "wmf-ops-monitoring" + | "vrt-permissions" + | "wmf-email-block-override" | "wmf-researcher" >; + expiry?: string | string[]; remove?: OneOrMore< | "abusefilter-helper" | "abusefilter-maintainer" @@ -691,12 +817,12 @@ export interface ApiGlobalUserRightsParams extends ApiParams { | "new-wikis-importer" | "oathauth-tester" | "ombuds" - | "otrs-member" | "recursive-export" | "staff" | "steward" | "sysadmin" - | "wmf-ops-monitoring" + | "vrt-permissions" + | "wmf-email-block-override" | "wmf-researcher" >; reason?: string; @@ -704,11 +830,54 @@ export interface ApiGlobalUserRightsParams extends ApiParams { tags?: string | string[]; } -export interface GraphApiGraphParams extends ApiParams { - hash?: string; +export interface GrowthExperimentsApiInvalidateImageRecommendationParams extends ApiParams { + tasktype?: "image-recommendation" | "section-image-recommendation"; title?: string; - text?: string; - oldid?: number; + filename?: string; + sectiontitle?: string; + sectionnumber?: number; + token?: string; +} + +export interface GrowthExperimentsApiInvalidatePersonalizedPraiseSuggestionParams + extends ApiParams { + mentee?: string; + reason?: "praised" | "skipped"; + skipreason?: "already-praised" | "not-now" | "not-praiseworthy" | "other"; + token?: string; +} + +export interface GrowthExperimentsApiManageMentorListParams extends ApiParams { + geaction?: "add" | "change" | "remove"; + message?: string; + weight?: "0" | "1" | "2" | "4"; + isaway?: boolean; + awaytimestamp?: timestamp; + summary?: string; + username?: string; + token?: string; +} + +export interface GrowthExperimentsApiMentorDashboardUpdateDataParams extends ApiParams { + token?: string; +} + +export interface GrowthExperimentsApiSetMenteeStatusParams extends ApiParams { + state?: "disabled" | "enabled" | "optout"; + token?: string; +} + +export interface GrowthExperimentsApiSetMentorParams extends ApiParams { + mentee?: string; + mentor?: string; + reason?: string; + token?: string; +} + +export interface GrowthExperimentsApiStarMenteeParams extends ApiParams { + gesaction?: "star" | "unstar"; + gesmentee?: string; + token?: string; } export interface ApiHelpParams extends ApiParams { @@ -719,6 +888,22 @@ export interface ApiHelpParams extends ApiParams { toc?: boolean; } +export interface GrowthExperimentsApiHelpPanelPostQuestionParams extends ApiParams { + body?: string; + source?: + | "helpdesk" + | "helppanel" + | "homepage-mentorship" + | "mentor-helppanel" + | "mentor-homepage"; + relevanttitle?: string; + token?: string; +} + +export interface GrowthExperimentsApiQuestionStoreParams extends ApiParams { + storage?: "growthexperiments-helppanel-questions" | "growthexperiments-mentor-questions"; +} + export interface ApiDisabledParams extends ApiParams {} export interface ApiImportParams extends ApiParams { @@ -772,25 +957,25 @@ export interface ApiFormatJsonParams extends ApiParams { formatversion?: "1" | "2" | "latest"; } -export interface ApiLanguageSearchParams extends ApiParams { +export interface UniversalLanguageSelectorApiLanguageSearchParams extends ApiParams { search?: string; typos?: number; } export interface ApiLinkAccountParams extends ApiParams { - requests?: string | string[]; - messageformat?: "html" | "none" | "raw" | "wikitext"; - mergerequestfields?: boolean; - returnurl?: string; - continue?: boolean; - token?: string; + linkrequests?: string | string[]; + linkmessageformat?: "html" | "none" | "raw" | "wikitext"; + linkmergerequestfields?: boolean; + linkreturnurl?: string; + linkcontinue?: boolean; + linktoken?: string; } export interface ApiLoginParams extends ApiParams { - name?: string; - password?: password; - domain?: string; - token?: string; + lgname?: string; + lgpassword?: password; + lgdomain?: string; + lgtoken?: string; } export interface ApiLogoutParams extends ApiParams { @@ -824,46 +1009,6 @@ export interface ApiMergeHistoryParams extends ApiParams { token?: string; } -export interface MobileFrontendApiMobileViewParams extends ApiParams { - page?: string; - redirect?: "no" | "yes"; - sections?: string; - prop?: OneOrMore< - | "contentmodel" - | "description" - | "displaytitle" - | "editable" - | "hasvariants" - | "id" - | "image" - | "languagecount" - | "lastmodified" - | "lastmodifiedby" - | "namespace" - | "normalizedtitle" - | "pageprops" - | "protection" - | "revision" - | "sections" - | "text" - | "thumb" - >; - sectionprop?: OneOrMore< - "anchor" | "fromtitle" | "index" | "level" | "line" | "number" | "toclevel" - >; - pageprops?: string; - variant?: string; - noheadings?: boolean; - notransform?: boolean; - onlyrequestedsections?: boolean; - offset?: number; - maxlen?: number; - revision?: number; - thumbheight?: number; - thumbwidth?: number; - thumbsize?: number; -} - export interface ApiMoveParams extends ApiParams { from?: string; fromid?: number; @@ -883,7 +1028,6 @@ export interface ApiFormatNoneParams extends ApiParams {} export interface OATHAuthApiModuleApiOATHValidateParams extends ApiParams { user?: string; - totp?: string; data?: string; token?: string; } @@ -923,6 +1067,7 @@ export interface PageTriageApiPageTriageActionParams extends ApiParams { token?: string; note?: string; skipnotif?: boolean; + tags?: string | string[]; } export interface PageTriageApiPageTriageListParams extends ApiParams { @@ -938,6 +1083,7 @@ export interface PageTriageApiPageTriageListParams extends ApiParams { show_predicted_issues_none?: boolean; show_predicted_issues_copyvio?: boolean; showbots?: boolean; + showautopatrolled?: boolean; showredirs?: boolean; showothers?: boolean; showreviewed?: boolean; @@ -975,6 +1121,7 @@ export interface PageTriageApiPageTriageStatsParams extends ApiParams { show_predicted_issues_none?: boolean; show_predicted_issues_copyvio?: boolean; showbots?: boolean; + showautopatrolled?: boolean; showredirs?: boolean; showothers?: boolean; showreviewed?: boolean; @@ -992,19 +1139,18 @@ export interface PageTriageApiPageTriageStatsParams extends ApiParams { username?: string; date_range_from?: timestamp; date_range_to?: timestamp; - topreviewers?: string; } export interface PageTriageApiPageTriageTagCopyvioParams extends ApiParams { revid?: number; + untag?: boolean; token?: string; } export interface PageTriageApiPageTriageTaggingParams extends ApiParams { pageid?: number; token?: string; - top?: string; - bottom?: string; + wikitext?: string; deletion?: boolean; note?: string; taglist?: string | string[]; @@ -1068,7 +1214,6 @@ export interface ApiParamInfoParams extends ApiParams { | "gadgetcategories" | "gadgets" | "geosearch" - | "gettingstartedgetpages" | "globalallusers" | "globalblocks" | "globalgroups" @@ -1076,10 +1221,19 @@ export interface ApiParamInfoParams extends ApiParams { | "globalrenamestatus" | "globalusage" | "globaluserinfo" + | "growthimagesuggestiondata" + | "growthmenteestatus" + | "growthmentorlist" + | "growthmentormentee" + | "growthmentorstatus" + | "growthnextsuggestedtasktype" + | "growthstarredmentees" + | "growthtasks" | "imageinfo" | "images" | "imageusage" | "info" + | "isreviewed" | "iwbacklinks" | "iwlinks" | "langbacklinks" @@ -1092,7 +1246,7 @@ export interface ApiParamInfoParams extends ApiParams { | "linterstats" | "logevents" | "mapdata" - | "mmsites" + | "mmcontent" | "mostviewed" | "mystashedfiles" | "notifications" @@ -1183,6 +1337,7 @@ export interface ApiParseParams extends ApiParams { | "headitems" >; wrapoutputclass?: string; + parsoid?: boolean; pst?: boolean; onlypst?: boolean; effectivelanglinks?: boolean; @@ -1192,11 +1347,22 @@ export interface ApiParseParams extends ApiParams { disablelimitreport?: boolean; disableeditsection?: boolean; disablestylededuplication?: boolean; + showstrategykeys?: boolean; generatexml?: boolean; preview?: boolean; sectionpreview?: boolean; disabletoc?: boolean; - useskin?: "minerva" | "modern" | "monobook" | "timeless" | "vector"; + useskin?: + | "apioutput" + | "cologneblue" + | "contenttranslation" + | "fallback" + | "minerva" + | "modern" + | "monobook" + | "timeless" + | "vector" + | "vector-2022"; contentformat?: | "application/json" | "application/octet-stream" @@ -1222,7 +1388,6 @@ export interface ApiParseParams extends ApiParams { | "unknown" | "wikitext"; mobileformat?: boolean; - mainpage?: boolean; templatesandboxprefix?: string | string[]; templatesandboxtitle?: string; templatesandboxtext?: string; @@ -1252,6 +1417,12 @@ export interface ApiParseParams extends ApiParams { | "unknown/unknown"; } +export interface ParserMigrationApiParserMigrationParams extends ApiParams { + title?: string; + config?: OneOrMore<"new" | "old">; + redirect?: string; +} + export interface ApiPatrolParams extends ApiParams { rcid?: number; revid?: number; @@ -1310,7 +1481,6 @@ export interface ApiPurgeParams extends ApiParams { | "exturlusage" | "fileusage" | "geosearch" - | "gettingstartedgetpages" | "images" | "imageusage" | "iwbacklinks" @@ -1334,6 +1504,7 @@ export interface ApiPurgeParams extends ApiParams { | "watchlist" | "watchlistraw" | "wblistentityusage" + | "growthtasks" | "readinglistentries"; redirects?: boolean; converttitles?: boolean; @@ -1355,14 +1526,17 @@ export interface ApiQueryParams extends ApiParams { | "fileusage" | "flagged" | "globalusage" + | "growthimagesuggestiondata" | "imageinfo" | "images" | "info" + | "isreviewed" | "iwlinks" | "langlinks" | "langlinkscount" | "links" | "linkshere" + | "mmcontent" | "pageassessments" | "pageimages" | "pageprops" @@ -1413,10 +1587,12 @@ export interface ApiQueryParams extends ApiParams { | "gadgetcategories" | "gadgets" | "geosearch" - | "gettingstartedgetpages" | "globalallusers" | "globalblocks" | "globalgroups" + | "growthmentorlist" + | "growthmentormentee" + | "growthstarredmentees" | "imageusage" | "iwbacklinks" | "langbacklinks" @@ -1443,7 +1619,7 @@ export interface ApiQueryParams extends ApiParams { | "wblistentityusage" | "wikisets" | "deletedrevs" - | "mmsites" + | "growthtasks" | "readinglistentries" >; meta?: OneOrMore< @@ -1455,6 +1631,8 @@ export interface ApiQueryParams extends ApiParams { | "globalpreferences" | "globalrenamestatus" | "globaluserinfo" + | "growthmenteestatus" + | "growthmentorstatus" | "languageinfo" | "linterstats" | "notifications" @@ -1466,6 +1644,7 @@ export interface ApiQueryParams extends ApiParams { | "userinfo" | "wikibase" | "cxdeletedtranslations" + | "growthnextsuggestedtasktype" | "oath" | "readinglists" >; @@ -1500,7 +1679,6 @@ export interface ApiQueryParams extends ApiParams { | "exturlusage" | "fileusage" | "geosearch" - | "gettingstartedgetpages" | "images" | "imageusage" | "iwbacklinks" @@ -1524,6 +1702,7 @@ export interface ApiQueryParams extends ApiParams { | "watchlist" | "watchlistraw" | "wblistentityusage" + | "growthtasks" | "readinglistentries"; redirects?: boolean; converttitles?: boolean; @@ -1538,12 +1717,6 @@ export interface ReadingListsApiReadingListsParams extends ApiParams { token?: string; } -export interface MediaWikiLinterApiRecordLintParams extends ApiParams { - data?: string; - page?: string; - revision?: number; -} - export interface ApiRemoveAuthenticationDataParams extends ApiParams { request?: string; token?: string; @@ -1562,13 +1735,6 @@ export interface ApiReviewParams extends ApiParams { token?: string; } -export interface ApiReviewActivityParams extends ApiParams { - previd?: string; - oldid?: string; - reviewing?: "0" | "1"; - token?: string; -} - export interface ApiRevisionDeleteParams extends ApiParams { type?: "archive" | "filearchive" | "logging" | "oldimage" | "revision"; target?: string; @@ -1600,15 +1766,21 @@ export interface KartographerApiSanitizeMapDataParams extends ApiParams { text?: string; } -export interface ApiScribuntoConsoleParams extends ApiParams { +export interface ScribuntoApiScribuntoConsoleParams extends ApiParams { title?: string; content?: string; session?: number; question?: string; clear?: boolean; + token?: string; +} + +export interface SecurePollApiSecurePollAuthParams extends ApiParams { + token?: string; + id?: number; } -export interface ApiSetGlobalAccountStatusParams extends ApiParams { +export interface CentralAuthApiSetGlobalAccountStatusParams extends ApiParams { user?: string; locked?: "" | "lock" | "unlock"; hidden?: "" | "lists" | "suppressed"; @@ -1647,7 +1819,6 @@ export interface ApiSetNotificationTimestampParams extends ApiParams { | "exturlusage" | "fileusage" | "geosearch" - | "gettingstartedgetpages" | "images" | "imageusage" | "iwbacklinks" @@ -1671,6 +1842,7 @@ export interface ApiSetNotificationTimestampParams extends ApiParams { | "watchlist" | "watchlistraw" | "wblistentityusage" + | "growthtasks" | "readinglistentries"; redirects?: boolean; converttitles?: boolean; @@ -1681,22 +1853,24 @@ export interface ApiSetPageLanguageParams extends ApiParams { title?: string; pageid?: number; lang?: + | "aae" | "ab" | "abs" | "ace" + | "acm" | "ady" | "ady-cyrl" | "aeb" | "aeb-arab" | "aeb-latn" | "af" - | "ak" | "aln" | "alt" | "am" | "ami" | "an" | "ang" + | "ann" | "anp" | "ar" | "arc" @@ -1721,15 +1895,19 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "bbc" | "bbc-latn" | "bcc" + | "bci" | "bcl" + | "bdr" | "be" | "be-tarask" + | "bew" | "bg" | "bgn" | "bh" | "bho" | "bi" | "bjn" + | "blk" | "bm" | "bn" | "bo" @@ -1753,21 +1931,27 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "ckb" | "co" | "cps" + | "cpx" + | "cpx-hans" + | "cpx-hant" | "cr" | "crh" | "crh-cyrl" | "crh-latn" + | "crh-ro" | "cs" | "csb" | "cu" | "cv" | "cy" | "da" + | "dag" | "de" | "de-at" | "de-ch" | "de-formal" | "default" + | "dga" | "din" | "diq" | "dsb" @@ -1776,6 +1960,7 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "dv" | "dz" | "ee" + | "efi" | "egl" | "el" | "eml" @@ -1789,11 +1974,13 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "eu" | "ext" | "fa" + | "fat" | "ff" | "fi" | "fit" | "fj" | "fo" + | "fon" | "fr" | "frc" | "frp" @@ -1801,13 +1988,16 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "fur" | "fy" | "ga" + | "gaa" | "gag" | "gan" | "gan-hans" | "gan-hant" + | "gcf" | "gcr" | "gd" | "gl" + | "gld" | "glk" | "gn" | "gom" @@ -1815,10 +2005,13 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "gom-latn" | "gor" | "got" + | "gpe" | "grc" | "gsw" | "gu" | "guc" + | "gur" + | "guw" | "gv" | "ha" | "hak" @@ -1828,9 +2021,11 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "hif" | "hif-latn" | "hil" + | "hno" | "hr" | "hrx" | "hsb" + | "hsn" | "ht" | "hu" | "hu-formal" @@ -1840,6 +2035,7 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "id" | "ie" | "ig" + | "igl" | "ii" | "ik" | "ike-cans" @@ -1858,14 +2054,18 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "ka" | "kaa" | "kab" + | "kai" | "kbd" | "kbd-cyrl" | "kbp" | "kcg" + | "kea" | "kg" + | "kge" | "khw" | "ki" | "kiu" + | "kjh" | "kjp" | "kk" | "kk-arab" @@ -1880,6 +2080,7 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "ko" | "ko-kp" | "koi" + | "kr" | "krc" | "kri" | "krj" @@ -1888,10 +2089,12 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "ks-arab" | "ks-deva" | "ksh" + | "ksw" | "ku" | "ku-arab" | "ku-latn" | "kum" + | "kus" | "kv" | "kw" | "ky" @@ -1920,6 +2123,7 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "lzh" | "lzz" | "mad" + | "mag" | "mai" | "map-bms" | "mdf" @@ -1930,13 +2134,17 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "mk" | "ml" | "mn" + | "mnc" + | "mnc-mong" | "mni" | "mnw" | "mo" + | "mos" | "mr" | "mrh" | "mrj" | "ms" + | "ms-arab" | "mt" | "mwl" | "my" @@ -1952,18 +2160,25 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "ne" | "new" | "nia" + | "nit" | "niu" | "nl" | "nl-informal" + | "nmz" | "nn" + | "nod" + | "nog" | "nov" | "nqo" | "nrm" | "nso" | "nv" | "ny" + | "nyn" + | "nyo" | "nys" | "oc" + | "ojb" | "olo" | "om" | "or" @@ -1973,6 +2188,7 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "pam" | "pap" | "pcd" + | "pcm" | "pdc" | "pdt" | "pfl" @@ -1986,21 +2202,28 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "ps" | "pt" | "pt-br" + | "pwn" | "qu" | "qug" | "rgn" | "rif" + | "rki" | "rm" + | "rmc" | "rmy" + | "rn" | "ro" | "roa-tara" + | "rsk" | "ru" | "rue" | "rup" | "ruq" | "ruq-cyrl" | "ruq-latn" + | "rut" | "rw" + | "ryu" | "sa" | "sah" | "sat" @@ -2011,16 +2234,23 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "sdc" | "sdh" | "se" + | "se-fi" + | "se-no" + | "se-se" | "sei" | "ses" | "sg" | "sgs" | "sh" + | "sh-cyrl" + | "sh-latn" | "shi" | "shn" | "shy" | "shy-latn" | "si" + | "sjd" + | "sje" | "sk" | "skr" | "skr-arab" @@ -2029,6 +2259,7 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "sm" | "sma" | "smn" + | "sms" | "sn" | "so" | "sq" @@ -2036,6 +2267,7 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "sr-ec" | "sr-el" | "srn" + | "sro" | "ss" | "st" | "stq" @@ -2043,11 +2275,13 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "su" | "sv" | "sw" + | "syl" | "szl" | "szy" | "ta" | "tay" | "tcy" + | "tdd" | "te" | "tet" | "tg" @@ -2060,6 +2294,7 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "tly" | "tn" | "to" + | "tok" | "tpi" | "tr" | "tru" @@ -2068,6 +2303,8 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "tt" | "tt-cyrl" | "tt-latn" + | "ttj" + | "tum" | "tw" | "ty" | "tyv" @@ -2085,20 +2322,28 @@ export interface ApiSetPageLanguageParams extends ApiParams { | "vi" | "vls" | "vmf" + | "vmw" | "vo" | "vot" | "vro" | "wa" + | "wal" | "war" + | "wls" | "wo" | "wuu" + | "wuu-hans" + | "wuu-hant" | "xal" | "xh" | "xmf" | "xsy" | "yi" | "yo" + | "yrl" | "yue" + | "yue-hans" + | "yue-hant" | "za" | "zea" | "zgh" @@ -2117,20 +2362,21 @@ export interface ApiSetPageLanguageParams extends ApiParams { token?: string; } -export interface ApiShortenUrlParams extends ApiParams { +export interface UrlShortenerApiShortenUrlParams extends ApiParams { url?: string; + qrcode?: boolean; } export interface SiteMatrixApiSiteMatrixParams extends ApiParams { - type?: OneOrMore<"language" | "special">; - state?: OneOrMore<"all" | "closed" | "fishbowl" | "nonglobal" | "private">; - langprop?: OneOrMore<"code" | "dir" | "localname" | "name" | "site">; - siteprop?: OneOrMore<"code" | "dbname" | "lang" | "sitename" | "url">; - limit?: limit; - continue?: string; + smtype?: OneOrMore<"language" | "special">; + smstate?: OneOrMore<"all" | "closed" | "fishbowl" | "nonglobal" | "private">; + smlangprop?: OneOrMore<"code" | "dir" | "localname" | "name" | "site">; + smsiteprop?: OneOrMore<"code" | "dbname" | "lang" | "sitename" | "url">; + smlimit?: limit; + smcontinue?: string; } -export interface ApiSpamBlacklistParams extends ApiParams { +export interface SpamBlacklistApiSpamBlacklistParams extends ApiParams { url?: string | string[]; } @@ -2138,8 +2384,6 @@ export interface ApiStabilizeProtectParams extends ApiParams { protectlevel?: "autoconfirmed" | "none"; expiry?: string; reason?: string; - watch?: string; - watchlist?: "nochange" | "preferences" | "unwatch" | "watch"; title?: string; token?: string; } @@ -2192,27 +2436,58 @@ export interface SecurePollApiStrikeVoteParams extends ApiParams { token?: string; } +export interface ContentTranslationActionApiSectionTranslationDeleteParams extends ApiParams { + sectiontranslationid?: number; + translationid?: number; + sectionid?: string; + token?: string; +} + +export interface ContentTranslationActionApiSectionTranslationSaveParams extends ApiParams { + sourcelanguage?: string; + targetlanguage?: string; + sourcetitle?: string; + targettitle?: string; + content?: string; + sourcerevision?: number; + sourcesectiontitle?: string; + targetsectiontitle?: string; + sectionid?: string; + issandbox?: boolean; + progress?: string; + token?: string; +} + export interface ApiTagParams extends ApiParams { rcid?: number | number[]; revid?: number | number[]; logid?: number | number[]; add?: OneOrMore< | "AWB" - | "Image up for deletion on Commons" - | "Manual revert" + | "AntiVandal script" + | "Deputy" + | "Newcomer task" | "ProveIt edit" | "RedWarn" | "STiki" + | "Single use" + | "Ultraviolet" | "WPCleaner" | "WikiLoop Battlefield" | "bot trial" - | "discretionary" + | "convenient-discussions" | "editProtectedHelper" + | "fixed lint errors" | "huggle" | "large non-free file" + | "moveToDraft" + | "new user moving page out of userspace" | "possible birth or death date change" + | "pronoun-change" | "self-published-blog" | "self-published source" + | "shortdesc helper" + | "talk banner shell conversion" | "twinkle" >; remove?: string | string[]; @@ -2221,7 +2496,7 @@ export interface ApiTagParams extends ApiParams { token?: string; } -export interface ApiTemplateDataParams extends ApiParams { +export interface TemplateDataApiTemplateDataParams extends ApiParams { includeMissingTitles?: boolean; doNotIgnoreMissingTitles?: boolean; lang?: string; @@ -2249,7 +2524,6 @@ export interface ApiTemplateDataParams extends ApiParams { | "exturlusage" | "fileusage" | "geosearch" - | "gettingstartedgetpages" | "images" | "imageusage" | "iwbacklinks" @@ -2273,65 +2547,47 @@ export interface ApiTemplateDataParams extends ApiParams { | "watchlist" | "watchlistraw" | "wblistentityusage" + | "growthtasks" | "readinglistentries"; redirects?: boolean; converttitles?: boolean; } -export interface ApiCoreThankParams extends ApiParams { +export interface ThanksApiCoreThankParams extends ApiParams { rev?: number; log?: number; token?: string; source?: string; } -export interface ApiTimedTextParams extends ApiParams { +export interface MediaWikiTimedMediaHandlerApiTimedTextParams extends ApiParams { title?: string; pageid?: number; trackformat?: "srt" | "vtt"; lang?: string; } -export interface ApiQueryTitleBlacklistParams extends ApiParams { - title?: string; - action?: "create" | "createpage" | "createtalk" | "edit" | "move" | "new-account" | "upload"; - nooverride?: boolean; +export interface TitleBlacklistApiTitleBlacklistParams extends ApiParams { + tbtitle?: string; + tbaction?: "create" | "createpage" | "createtalk" | "edit" | "move" | "new-account" | "upload"; + tbnooverride?: boolean; } -export interface ApiTokensParams extends ApiParams { - type?: OneOrMore< - | "block" - | "createaccount" - | "csrf" - | "delete" - | "deleteglobalaccount" - | "edit" - | "email" - | "import" - | "login" - | "move" - | "options" - | "patrol" - | "protect" - | "rollback" - | "setglobalaccountstatus" - | "unblock" - | "userrights" - | "watch" - >; +export interface TorBlockApiTorBlockParams extends ApiParams { + ip?: string; } -export interface ApiTranscodeResetParams extends ApiParams { +export interface MediaWikiTimedMediaHandlerApiTranscodeResetParams extends ApiParams { title?: string; transcodekey?: string; token?: string; } -export interface ApiULSLocalizationParams extends ApiParams { +export interface UniversalLanguageSelectorApiULSLocalizationParams extends ApiParams { language?: string; } -export interface ApiULSSetLanguageParams extends ApiParams { +export interface UniversalLanguageSelectorApiULSSetLanguageParams extends ApiParams { languagecode?: string; token?: string; } @@ -2342,6 +2598,8 @@ export interface ApiUnblockParams extends ApiParams { userid?: number; reason?: string; tags?: string | string[]; + watchuser?: boolean; + watchlistexpiry?: expiry; token?: string; } @@ -2351,6 +2609,7 @@ export interface ApiUndeleteParams extends ApiParams { tags?: string | string[]; timestamps?: timestamp | timestamp[]; fileids?: number | number[]; + undeletetalk?: boolean; watchlist?: "nochange" | "preferences" | "unwatch" | "watch"; watchlistexpiry?: expiry; token?: string; @@ -2405,12 +2664,14 @@ export interface ApiUserrightsParams extends ApiParams { | "interface-admin" | "ipblock-exempt" | "massmessage-sender" - | "oversight" + | "no-ipinfo" | "patroller" + | "push-subscription-manager" | "researcher" | "reviewer" | "rollbacker" | "steward" + | "suppress" | "sysop" | "templateeditor" | "transwiki" @@ -2435,12 +2696,14 @@ export interface ApiUserrightsParams extends ApiParams { | "interface-admin" | "ipblock-exempt" | "massmessage-sender" - | "oversight" + | "no-ipinfo" | "patroller" + | "push-subscription-manager" | "researcher" | "reviewer" | "rollbacker" | "steward" + | "suppress" | "sysop" | "templateeditor" | "transwiki" @@ -2448,6 +2711,8 @@ export interface ApiUserrightsParams extends ApiParams { reason?: string; token?: string; tags?: string | string[]; + watchuser?: boolean; + watchlistexpiry?: expiry; } export interface ApiValidatePasswordParams extends ApiParams { @@ -2457,31 +2722,31 @@ export interface ApiValidatePasswordParams extends ApiParams { realname?: string; } -export interface ApiVisualEditorParams extends ApiParams { +export interface VisualEditorApiVisualEditorParams extends ApiParams { page?: string; badetag?: string; format?: "json" | "jsonfm"; - paction?: "metadata" | "parse" | "parsedoc" | "parsefragment" | "templatesused" | "wikitext"; + paction?: "metadata" | "parse" | "parsefragment" | "templatesused" | "wikitext"; wikitext?: string; section?: string; - stash?: string; - oldid?: string; + stash?: boolean; + oldid?: number; editintro?: string; pst?: boolean; preload?: string; preloadparams?: string | string[]; } -export interface ApiVisualEditorEditParams extends ApiParams { +export interface VisualEditorApiVisualEditorEditParams extends ApiParams { paction?: "diff" | "save" | "serialize" | "serializeforcache"; page?: string; token?: string; wikitext?: string; section?: string; sectiontitle?: string; - basetimestamp?: string; - starttimestamp?: string; - oldid?: string; + basetimestamp?: timestamp; + starttimestamp?: timestamp; + oldid?: number; minor?: string; watchlist?: string; html?: string; @@ -2490,7 +2755,24 @@ export interface ApiVisualEditorEditParams extends ApiParams { captchaid?: string; captchaword?: string; cachekey?: string; + nocontent?: boolean; + returnto?: string; + returntoquery?: string; + returntoanchor?: string; + useskin?: + | "apioutput" + | "cologneblue" + | "contenttranslation" + | "fallback" + | "minerva" + | "modern" + | "monobook" + | "timeless" + | "vector" + | "vector-2022"; tags?: string | string[]; + plugins?: string | string[]; + mobileformat?: boolean; } export interface ApiWatchParams extends ApiParams { @@ -2522,7 +2804,6 @@ export interface ApiWatchParams extends ApiParams { | "exturlusage" | "fileusage" | "geosearch" - | "gettingstartedgetpages" | "images" | "imageusage" | "iwbacklinks" @@ -2546,6 +2827,7 @@ export interface ApiWatchParams extends ApiParams { | "watchlist" | "watchlistraw" | "wblistentityusage" + | "growthtasks" | "readinglistentries"; redirects?: boolean; converttitles?: boolean; @@ -2555,8 +2837,7 @@ export interface ApiWatchParams extends ApiParams { export interface MobileFrontendApiWebappManifestParams extends ApiParams {} export interface WebAuthnApiWebAuthnParams extends ApiParams { - func?: string; - data?: string; + func?: "getAuthInfo" | "getRegisterInfo"; } export interface WikiLoveApiWikiLoveParams extends ApiParams { @@ -2570,6 +2851,12 @@ export interface WikiLoveApiWikiLoveParams extends ApiParams { tags?: string | string[]; } +export interface WikimediaEventsApiWikimediaEventsBlockedEditParams extends ApiParams { + page?: string; + interface?: "discussiontools" | "mobilefrontend" | "other" | "visualeditor" | "wikieditor"; + platform?: "desktop" | "mobile"; +} + export interface ApiFormatXmlParams extends ApiParams { xslt?: string; includexmlnamespace?: boolean; @@ -2773,15 +3060,15 @@ export interface ApiQueryAllPagesParams extends ApiQueryParams { apprefix?: string; apnamespace?: namespace; apfilterredir?: "all" | "nonredirects" | "redirects"; + apfilterlanglinks?: "all" | "withlanglinks" | "withoutlanglinks"; apminsize?: number; apmaxsize?: number; apprtype?: OneOrMore<"edit" | "move" | "upload">; apprlevel?: OneOrMore<"" | "autoconfirmed" | "extendedconfirmed" | "sysop" | "templateeditor">; apprfiltercascade?: "all" | "cascading" | "noncascading"; + apprexpiry?: "all" | "definite" | "indefinite"; aplimit?: limit; apdir?: "ascending" | "descending"; - apfilterlanglinks?: "all" | "withlanglinks" | "withoutlanglinks"; - apprexpiry?: "all" | "definite" | "indefinite"; } export interface ApiQueryAllLinksParams extends ApiQueryParams { @@ -2882,12 +3169,14 @@ export interface ApiQueryAllUsersParams extends ApiQueryParams { | "interface-admin" | "ipblock-exempt" | "massmessage-sender" - | "oversight" + | "no-ipinfo" | "patroller" + | "push-subscription-manager" | "researcher" | "reviewer" | "rollbacker" | "steward" + | "suppress" | "sysop" | "templateeditor" | "transwiki" @@ -2911,23 +3200,27 @@ export interface ApiQueryAllUsersParams extends ApiQueryParams { | "interface-admin" | "ipblock-exempt" | "massmessage-sender" - | "oversight" + | "no-ipinfo" | "patroller" + | "push-subscription-manager" | "researcher" | "reviewer" | "rollbacker" | "steward" + | "suppress" | "sysop" | "templateeditor" | "transwiki" >; aurights?: OneOrMore< + | "abusefilter-bypass-blocked-external-domains" | "abusefilter-hidden-log" | "abusefilter-hide-log" | "abusefilter-log" | "abusefilter-log-detail" | "abusefilter-log-private" | "abusefilter-modify" + | "abusefilter-modify-blocked-external-domains" | "abusefilter-modify-global" | "abusefilter-modify-restricted" | "abusefilter-privatedetails" @@ -2942,6 +3235,8 @@ export interface ApiQueryAllUsersParams extends ApiQueryParams { | "autopatrol" | "autoreview" | "autoreviewrestore" + | "badcaptcha" + | "badoath" | "bigdelete" | "block" | "blockemail" @@ -2950,15 +3245,19 @@ export interface ApiQueryAllUsersParams extends ApiQueryParams { | "centralauth-createlocal" | "centralauth-lock" | "centralauth-merge" - | "centralauth-oversight" | "centralauth-rename" + | "centralauth-suppress" | "centralauth-unmerge" - | "centralauth-usermerge" + | "changeemail" | "changetags" | "checkuser" | "checkuser-log" + | "checkuser-temporary-account" + | "checkuser-temporary-account-log" + | "checkuser-temporary-account-no-preference" | "collectionsaveascommunitypage" | "collectionsaveasuserpage" + | "confirmemail" | "createaccount" | "createpage" | "createpagemainns" @@ -2971,6 +3270,7 @@ export interface ApiQueryAllUsersParams extends ApiQueryParams { | "deletelogentry" | "deleterevision" | "edit" + | "editautopatrolprotected" | "editautoreviewprotected" | "editcontentmodel" | "editeditorprotected" @@ -2988,9 +3288,11 @@ export interface ApiQueryAllUsersParams extends ApiQueryParams { | "editsitecss" | "editsitejs" | "editsitejson" + | "edittrustedprotected" | "editusercss" | "edituserjs" | "edituserjson" + | "enrollasmentor" | "extendedconfirmed" | "flow-create-board" | "flow-delete" @@ -2998,19 +3300,27 @@ export interface ApiQueryAllUsersParams extends ApiQueryParams { | "flow-hide" | "flow-suppress" | "gadgets-definition-edit" - | "gadgets-edit" | "globalblock" | "globalblock-exempt" | "globalblock-whitelist" | "globalgroupmembership" | "globalgrouppermissions" - | "gwtoolset" + | "growthexperiments-apiqueryimagesuggestiondata" + | "growthexperimentsuserimpacthandler" + | "growthmentordashboardupdatedata" | "hideuser" | "import" | "importupload" | "ipblock-exempt" + | "ipinfo" + | "ipinfo-view-basic" + | "ipinfo-view-full" + | "ipinfo-view-log" + | "linkpurge" + | "mailpassword" | "manage-all-push-subscriptions" | "managechangetags" + | "managementors" | "markbotedits" | "massmessage" | "mergehistory" @@ -3044,30 +3354,40 @@ export interface ApiQueryAllUsersParams extends ApiQueryParams { | "override-export-depth" | "pagelang" | "pagetriage-copyvio" + | "pagetriage-mark-action" + | "pagetriage-tagging-action" | "patrol" | "patrolmarks" | "protect" | "purge" | "read" | "renameuser" + | "renderfile" + | "renderfile-nonstandard" | "reupload" | "reupload-own" | "reupload-shared" | "review" | "rollback" + | "sboverride" | "securepoll-create-poll" + | "securepoll-view-voter-pii" | "sendemail" | "setmentor" + | "sfsblock-bypass" | "siteadmin" | "skipcaptcha" | "spamblacklistlog" | "stablesettings" + | "stashbasehtml" + | "stashedit" | "suppressionlog" | "suppressredirect" | "suppressrevision" | "tboverride" | "tboverride-account" | "templateeditor" + | "thanks-notification" | "titleblacklistlog" | "torunblocked" | "transcode-reset" @@ -3078,10 +3398,10 @@ export interface ApiQueryAllUsersParams extends ApiQueryParams { | "unwatchedpages" | "upload" | "upload_by_url" + | "urlshortcode" | "urlshortener-create-url" | "urlshortener-manage-url" | "urlshortener-view-log" - | "usermerge" | "userrights" | "userrights-interwiki" | "validate" @@ -3138,7 +3458,7 @@ export interface ApiQueryBacklinksParams extends ApiQueryParams { blredirect?: boolean; } -export interface ApiQueryBetaFeaturesParams extends ApiQueryParams { +export interface BetaFeaturesApiQueryBetaFeaturesParams extends ApiQueryParams { bfcounts?: string; } @@ -3216,7 +3536,7 @@ export interface ApiCentralNoticeLogsParams extends ApiQueryParams { } export interface MediaWikiCheckUserApiQueryCheckUserParams extends ApiQueryParams { - curequest?: "edits" | "ipusers" | "userips"; + curequest?: "actions" | "ipusers" | "userips" | "edits"; cutarget?: string; cureason?: string; culimit?: limit; @@ -3228,6 +3548,7 @@ export interface MediaWikiCheckUserApiQueryCheckUserParams extends ApiQueryParam export interface MediaWikiCheckUserApiQueryCheckUserLogParams extends ApiQueryParams { culuser?: string; cultarget?: string; + culreason?: string; cullimit?: limit; culdir?: "newer" | "older"; culfrom?: timestamp; @@ -3235,39 +3556,50 @@ export interface MediaWikiCheckUserApiQueryCheckUserLogParams extends ApiQueryPa culcontinue?: string; } -export interface CirrusSearchApiQueryBuildDocumentParams extends ApiQueryParams {} +export interface CirrusSearchApiQueryBuildDocumentParams extends ApiQueryParams { + cbbuilders?: OneOrMore<"content" | "links">; + cblimiterprofile?: string; +} export interface CirrusSearchApiQueryCompSuggestBuildDocParams extends ApiQueryParams { csbmethod?: string; } -export interface CirrusSearchApiQueryCirrusDocParams extends ApiQueryParams {} +export interface CirrusSearchApiQueryCirrusDocParams extends ApiQueryParams { + cdincludes?: string | string[]; +} -export interface ApiQueryContentTranslationParams extends ApiQueryParams { +export interface ContentTranslationActionApiQueryContentTranslationParams extends ApiQueryParams { translationid?: string; from?: string; to?: string; sourcetitle?: string; + sourcesectiontitle?: string; limit?: limit; offset?: string; type?: "draft" | "published"; + usecase?: "desktop-editor-draft" | "translation-corpora-units" | "unified-dashboard"; } -export interface ApiQueryContentTranslationCorporaParams extends ApiQueryParams { +export interface ContentTranslationActionApiQueryContentTranslationCorporaParams + extends ApiQueryParams { translationid?: number; striphtml?: boolean; types?: OneOrMore<"mt" | "source" | "user">; } -export interface ApiQueryContentTranslationLanguageTrendParams extends ApiQueryParams { +export interface ContentTranslationActionApiQueryContentTranslationLanguageTrendParams + extends ApiQueryParams { source?: string; target?: string; interval?: "month" | "week"; } -export interface ApiQueryContentTranslationStatsParams extends ApiQueryParams {} +export interface ContentTranslationActionApiQueryContentTranslationStatsParams + extends ApiQueryParams {} -export interface ApiQueryContentTranslationSuggestionsParams extends ApiQueryParams { +export interface ContentTranslationActionApiQueryContentTranslationSuggestionsParams + extends ApiQueryParams { from?: string; to?: string; listid?: string; @@ -3296,12 +3628,14 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "interface-admin" | "ipblock-exempt" | "massmessage-sender" - | "oversight" + | "no-ipinfo" | "patroller" + | "push-subscription-manager" | "researcher" | "reviewer" | "rollbacker" | "steward" + | "suppress" | "sysop" | "templateeditor" | "transwiki" @@ -3325,23 +3659,27 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "interface-admin" | "ipblock-exempt" | "massmessage-sender" - | "oversight" + | "no-ipinfo" | "patroller" + | "push-subscription-manager" | "researcher" | "reviewer" | "rollbacker" | "steward" + | "suppress" | "sysop" | "templateeditor" | "transwiki" >; pcrights?: OneOrMore< + | "abusefilter-bypass-blocked-external-domains" | "abusefilter-hidden-log" | "abusefilter-hide-log" | "abusefilter-log" | "abusefilter-log-detail" | "abusefilter-log-private" | "abusefilter-modify" + | "abusefilter-modify-blocked-external-domains" | "abusefilter-modify-global" | "abusefilter-modify-restricted" | "abusefilter-privatedetails" @@ -3364,13 +3702,15 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "centralauth-createlocal" | "centralauth-lock" | "centralauth-merge" - | "centralauth-oversight" | "centralauth-rename" + | "centralauth-suppress" | "centralauth-unmerge" - | "centralauth-usermerge" | "changetags" | "checkuser" | "checkuser-log" + | "checkuser-temporary-account" + | "checkuser-temporary-account-log" + | "checkuser-temporary-account-no-preference" | "collectionsaveascommunitypage" | "collectionsaveasuserpage" | "createaccount" @@ -3385,6 +3725,7 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "deletelogentry" | "deleterevision" | "edit" + | "editautopatrolprotected" | "editautoreviewprotected" | "editcontentmodel" | "editeditorprotected" @@ -3402,9 +3743,11 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "editsitecss" | "editsitejs" | "editsitejson" + | "edittrustedprotected" | "editusercss" | "edituserjs" | "edituserjson" + | "enrollasmentor" | "extendedconfirmed" | "flow-create-board" | "flow-delete" @@ -3412,19 +3755,22 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "flow-hide" | "flow-suppress" | "gadgets-definition-edit" - | "gadgets-edit" | "globalblock" | "globalblock-exempt" | "globalblock-whitelist" | "globalgroupmembership" | "globalgrouppermissions" - | "gwtoolset" | "hideuser" | "import" | "importupload" | "ipblock-exempt" + | "ipinfo" + | "ipinfo-view-basic" + | "ipinfo-view-full" + | "ipinfo-view-log" | "manage-all-push-subscriptions" | "managechangetags" + | "managementors" | "markbotedits" | "massmessage" | "mergehistory" @@ -3461,7 +3807,6 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "patrol" | "patrolmarks" | "protect" - | "purge" | "read" | "renameuser" | "reupload" @@ -3469,9 +3814,12 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "reupload-shared" | "review" | "rollback" + | "sboverride" | "securepoll-create-poll" + | "securepoll-view-voter-pii" | "sendemail" | "setmentor" + | "sfsblock-bypass" | "siteadmin" | "skipcaptcha" | "spamblacklistlog" @@ -3495,7 +3843,6 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "urlshortener-create-url" | "urlshortener-manage-url" | "urlshortener-view-log" - | "usermerge" | "userrights" | "userrights-interwiki" | "validate" @@ -3507,12 +3854,14 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "writeapi" >; pcexcluderights?: OneOrMore< + | "abusefilter-bypass-blocked-external-domains" | "abusefilter-hidden-log" | "abusefilter-hide-log" | "abusefilter-log" | "abusefilter-log-detail" | "abusefilter-log-private" | "abusefilter-modify" + | "abusefilter-modify-blocked-external-domains" | "abusefilter-modify-global" | "abusefilter-modify-restricted" | "abusefilter-privatedetails" @@ -3535,13 +3884,15 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "centralauth-createlocal" | "centralauth-lock" | "centralauth-merge" - | "centralauth-oversight" | "centralauth-rename" + | "centralauth-suppress" | "centralauth-unmerge" - | "centralauth-usermerge" | "changetags" | "checkuser" | "checkuser-log" + | "checkuser-temporary-account" + | "checkuser-temporary-account-log" + | "checkuser-temporary-account-no-preference" | "collectionsaveascommunitypage" | "collectionsaveasuserpage" | "createaccount" @@ -3556,6 +3907,7 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "deletelogentry" | "deleterevision" | "edit" + | "editautopatrolprotected" | "editautoreviewprotected" | "editcontentmodel" | "editeditorprotected" @@ -3573,9 +3925,11 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "editsitecss" | "editsitejs" | "editsitejson" + | "edittrustedprotected" | "editusercss" | "edituserjs" | "edituserjson" + | "enrollasmentor" | "extendedconfirmed" | "flow-create-board" | "flow-delete" @@ -3583,19 +3937,22 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "flow-hide" | "flow-suppress" | "gadgets-definition-edit" - | "gadgets-edit" | "globalblock" | "globalblock-exempt" | "globalblock-whitelist" | "globalgroupmembership" | "globalgrouppermissions" - | "gwtoolset" | "hideuser" | "import" | "importupload" | "ipblock-exempt" + | "ipinfo" + | "ipinfo-view-basic" + | "ipinfo-view-full" + | "ipinfo-view-log" | "manage-all-push-subscriptions" | "managechangetags" + | "managementors" | "markbotedits" | "massmessage" | "mergehistory" @@ -3632,7 +3989,6 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "patrol" | "patrolmarks" | "protect" - | "purge" | "read" | "renameuser" | "reupload" @@ -3640,9 +3996,12 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "reupload-shared" | "review" | "rollback" + | "sboverride" | "securepoll-create-poll" + | "securepoll-view-voter-pii" | "sendemail" | "setmentor" + | "sfsblock-bypass" | "siteadmin" | "skipcaptcha" | "spamblacklistlog" @@ -3666,7 +4025,6 @@ export interface ApiQueryContributorsParams extends ApiQueryParams { | "urlshortener-create-url" | "urlshortener-manage-url" | "urlshortener-view-log" - | "usermerge" | "userrights" | "userrights-interwiki" | "validate" @@ -3690,19 +4048,20 @@ export interface GeoDataApiQueryCoordinatesParams extends ApiQueryParams { codistancefrompage?: string; } -export interface ApiQueryDeletedTranslationsParams extends ApiQueryParams { +export interface ContentTranslationActionApiQueryDeletedTranslationsParams extends ApiQueryParams { dtafter?: timestamp; dtnamespace?: namespace; } -export interface ApiQueryPublishedTranslationsParams extends ApiQueryParams { +export interface ContentTranslationActionApiQueryPublishedTranslationsParams + extends ApiQueryParams { from?: string; to?: string; limit?: limit; offset?: string; } -export interface ApiQueryTranslatorStatsParams extends ApiQueryParams { +export interface ContentTranslationActionApiQueryTranslatorStatsParams extends ApiQueryParams { translator?: string; } @@ -3776,9 +4135,9 @@ export interface ApiQueryDeletedrevsParams extends ApiQueryParams { | "revid" | "sha1" | "tags" - | "token" | "user" | "userid" + | "token" >; drlimit?: limit; drcontinue?: string; @@ -3823,6 +4182,7 @@ export interface ApiQueryExternalLinksParams extends ApiQueryParams { | "ircs" | "magnet" | "mailto" + | "matrix" | "mms" | "news" | "nntp" @@ -3869,6 +4229,7 @@ export interface ApiQueryExtLinksUsageParams extends ApiQueryParams { | "ircs" | "magnet" | "mailto" + | "matrix" | "mms" | "news" | "nntp" @@ -3890,7 +4251,7 @@ export interface ApiQueryExtLinksUsageParams extends ApiQueryParams { euexpandurl?: boolean; } -export interface ApiQueryFeatureUsageParams extends ApiQueryParams { +export interface ApiFeatureUsageApiQueryFeatureUsageParams extends ApiQueryParams { afustart?: timestamp; afuend?: timestamp; afuagent?: string; @@ -3950,12 +4311,12 @@ export interface ApiQueryBacklinkspropParams extends ApiQueryParams { export interface ApiQueryFlaggedParams extends ApiQueryParams {} -export interface ApiQueryGadgetCategoriesParams extends ApiQueryParams { +export interface GadgetsApiQueryGadgetCategoriesParams extends ApiQueryParams { gcprop?: OneOrMore<"members" | "name" | "title">; gcnames?: string | string[]; } -export interface ApiQueryGadgetsParams extends ApiQueryParams { +export interface GadgetsApiQueryGadgetsParams extends ApiQueryParams { gaprop?: OneOrMore<"desc" | "id" | "metadata">; gacategories?: string | string[]; gaids?: string | string[]; @@ -3969,6 +4330,7 @@ export interface GeoDataApiQueryGeoSearchElasticParams extends ApiQueryParams { gsbbox?: string; gsradius?: number; gsmaxdim?: number; + gssort?: "distance" | "relevance"; gslimit?: limit; gsglobe?: "earth"; gsnamespace?: namespace | namespace[]; @@ -3977,13 +4339,7 @@ export interface GeoDataApiQueryGeoSearchElasticParams extends ApiQueryParams { gsdebug?: boolean; } -export interface GettingStartedApiGettingStartedGetPagesParams extends ApiQueryParams { - gsgptaskname?: string; - gsgpexcludedtitle?: string; - gsgpcount?: number; -} - -export interface ApiQueryGlobalAllUsersParams extends ApiQueryParams { +export interface CentralAuthApiQueryGlobalAllUsersParams extends ApiQueryParams { agufrom?: string; aguto?: string; aguprefix?: string; @@ -4004,12 +4360,12 @@ export interface ApiQueryGlobalAllUsersParams extends ApiQueryParams { | "new-wikis-importer" | "oathauth-tester" | "ombuds" - | "otrs-member" | "recursive-export" | "staff" | "steward" | "sysadmin" - | "wmf-ops-monitoring" + | "vrt-permissions" + | "wmf-email-block-override" | "wmf-researcher" >; aguexcludegroup?: OneOrMore< @@ -4028,19 +4384,19 @@ export interface ApiQueryGlobalAllUsersParams extends ApiQueryParams { | "new-wikis-importer" | "oathauth-tester" | "ombuds" - | "otrs-member" | "recursive-export" | "staff" | "steward" | "sysadmin" - | "wmf-ops-monitoring" + | "vrt-permissions" + | "wmf-email-block-override" | "wmf-researcher" >; aguprop?: OneOrMore<"existslocally" | "groups" | "lockinfo">; agulimit?: limit; } -export interface ApiQueryGlobalBlocksParams extends ApiQueryParams { +export interface GlobalBlockingApiQueryGlobalBlocksParams extends ApiQueryParams { bgstart?: timestamp; bgend?: timestamp; bgdir?: "newer" | "older"; @@ -4051,7 +4407,7 @@ export interface ApiQueryGlobalBlocksParams extends ApiQueryParams { bgprop?: OneOrMore<"address" | "by" | "expiry" | "id" | "range" | "reason" | "timestamp">; } -export interface ApiQueryGlobalGroupsParams extends ApiQueryParams { +export interface CentralAuthApiQueryGlobalGroupsParams extends ApiQueryParams { ggpprop?: OneOrMore<"rights">; } @@ -4059,11 +4415,11 @@ export interface GlobalPreferencesApiQueryGlobalPreferencesParams extends ApiQue gprprop?: OneOrMore<"localoverrides" | "preferences">; } -export interface ApiQueryGlobalRenameStatusParams extends ApiQueryParams { +export interface CentralAuthApiQueryGlobalRenameStatusParams extends ApiQueryParams { grsuser?: string; } -export interface ApiQueryGlobalUsageParams extends ApiQueryParams { +export interface GlobalUsageApiQueryGlobalUsageParams extends ApiQueryParams { guprop?: OneOrMore<"namespace" | "pageid" | "url">; gulimit?: limit; gunamespace?: namespace | namespace[]; @@ -4072,12 +4428,83 @@ export interface ApiQueryGlobalUsageParams extends ApiQueryParams { gufilterlocal?: boolean; } -export interface ApiQueryGlobalUserInfoParams extends ApiQueryParams { +export interface CentralAuthApiQueryGlobalUserInfoParams extends ApiQueryParams { guiuser?: string; guiid?: number; guiprop?: OneOrMore<"editcount" | "groups" | "merged" | "rights" | "unattached">; } +export interface GrowthExperimentsApiQueryImageSuggestionDataParams extends ApiQueryParams { + gisdtasktype?: "image-recommendation" | "section-image-recommendation"; + gisdcontinue?: string; +} + +export interface GrowthExperimentsApiQueryMenteeStatusParams extends ApiQueryParams {} + +export interface GrowthExperimentsApiQueryMentorListParams extends ApiQueryParams {} + +export interface GrowthExperimentsApiQueryMentorMenteeParams extends ApiQueryParams { + gemmmentor?: string; +} + +export interface GrowthExperimentsApiQueryMentorStatusParams extends ApiQueryParams {} + +export interface GrowthExperimentsApiQueryNextSuggestedTaskTypeParams extends ApiQueryParams { + gnsttactivetasktype?: "copyedit" | "expand" | "links" | "references" | "update"; +} + +export interface GrowthExperimentsApiQueryStarredMenteesParams extends ApiQueryParams {} + +export interface GrowthExperimentsApiQueryGrowthTasksParams extends ApiQueryParams { + gttasktypes?: OneOrMore<"copyedit" | "expand" | "links" | "references" | "update">; + gttopics?: OneOrMore< + | "africa" + | "architecture" + | "art" + | "asia" + | "biography" + | "biology" + | "business-and-economics" + | "central-america" + | "chemistry" + | "comics-and-anime" + | "computers-and-internet" + | "earth-and-environment" + | "education" + | "engineering" + | "entertainment" + | "europe" + | "fashion" + | "food-and-drink" + | "general-science" + | "history" + | "literature" + | "mathematics" + | "medicine-and-health" + | "military-and-warfare" + | "music" + | "north-america" + | "oceania" + | "performing-arts" + | "philosophy-and-religion" + | "physics" + | "politics-and-government" + | "society" + | "south-america" + | "sports" + | "technology" + | "transportation" + | "tv-and-film" + | "video-games" + | "women" + >; + gttopicsmode?: "AND" | "OR"; + gtlimit?: limit; + gtoffset?: number; + gtdebug?: boolean; + gtexcludepageids?: number | number[]; +} + export interface ApiQueryImageInfoParams extends ApiQueryParams { iiprop?: OneOrMore< | "archivename" @@ -4136,10 +4563,12 @@ export interface ApiQueryBacklinksParams extends ApiQueryParams { export interface ApiQueryInfoParams extends ApiQueryParams { inprop?: OneOrMore< + | "associatedpage" | "displaytitle" + | "editintro" | "linkclasses" | "notificationtimestamp" - | "preload" + | "preloadcontent" | "protection" | "subjectid" | "talkid" @@ -4148,17 +4577,24 @@ export interface ApiQueryInfoParams extends ApiQueryParams { | "visitingwatchers" | "watched" | "watchers" + | "preload" | "readable" >; inlinkcontext?: string; intestactions?: string | string[]; intestactionsdetail?: "boolean" | "full" | "quick"; - intoken?: OneOrMore< - "block" | "delete" | "edit" | "email" | "import" | "move" | "protect" | "unblock" | "watch" - >; + intestactionsautocreate?: boolean; + inpreloadcustom?: string; + inpreloadparams?: string | string[]; + inpreloadnewsection?: boolean; + ineditintrostyle?: "lessframes" | "moreframes"; + ineditintroskip?: string | string[]; + ineditintrocustom?: string; incontinue?: string; } +export interface PageTriageApiIsReviewedParams extends ApiQueryParams {} + export interface ApiQueryIWBacklinksParams extends ApiQueryParams { iwblprefix?: string; iwbltitle?: string; @@ -4198,10 +4634,12 @@ export interface ApiQueryLangLinksParams extends ApiQueryParams { llurl?: boolean; } -export interface ApiQueryLangLinksCountParams extends ApiQueryParams {} +export interface ContentTranslationActionApiQueryLangLinksCountParams extends ApiQueryParams {} export interface ApiQueryLanguageinfoParams extends ApiQueryParams { - liprop?: OneOrMore<"autonym" | "bcp47" | "code" | "dir" | "fallbacks" | "name" | "variants">; + liprop?: OneOrMore< + "autonym" | "bcp47" | "code" | "dir" | "fallbacks" | "name" | "variantnames" | "variants" + >; licode?: string | string[]; licontinue?: string; } @@ -4223,7 +4661,7 @@ export interface ApiQueryBacklinkspropParams extends ApiQueryParams { } export interface MediaWikiLinterApiQueryLintErrorsParams extends ApiQueryParams { - lntcategories?: OneOrMore< + "lntcategories"?: OneOrMore< | "bogus-image-options" | "deletable-table-tag" | "fostered" @@ -4231,6 +4669,7 @@ export interface MediaWikiLinterApiQueryLintErrorsParams extends ApiQueryParams | "misc-tidy-replacement-issues" | "misnested-tag" | "missing-end-tag" + | "missing-end-tag-in-heading" | "multi-colon-escape" | "multiline-html-table-in-list" | "multiple-unclosed-formatting-tags" @@ -4243,11 +4682,12 @@ export interface MediaWikiLinterApiQueryLintErrorsParams extends ApiQueryParams | "unclosed-quotes-in-heading" | "wikilink-in-extlink" >; - lntlimit?: limit; - lntnamespace?: namespace | namespace[]; - lntpageid?: number | number[]; - lnttitle?: string; - lntfrom?: number; + "lntinvisible-categories"?: OneOrMore<"large-tables">; + "lntlimit"?: limit; + "lntnamespace"?: namespace | namespace[]; + "lntpageid"?: number | number[]; + "lnttitle"?: string; + "lntfrom"?: number; } export interface MediaWikiLinterApiQueryLinterStatsParams extends ApiQueryParams {} @@ -4268,8 +4708,10 @@ export interface ApiQueryLogEventsParams extends ApiQueryParams { letype?: | "" | "abusefilter" + | "abusefilterblockeddomainhit" | "abusefilterprivatedetails" | "block" + | "checkuser-temporary-account" | "contentmodel" | "create" | "delete" @@ -4277,7 +4719,9 @@ export interface ApiQueryLogEventsParams extends ApiQueryParams { | "gblrename" | "gblrights" | "globalauth" + | "growthexperiments" | "import" + | "ipinfo" | "managetags" | "massmessage" | "merge" @@ -4286,7 +4730,6 @@ export interface ApiQueryLogEventsParams extends ApiQueryParams { | "oath" | "pagetriage-copyvio" | "pagetriage-curation" - | "pagetriage-deletion" | "patrol" | "protect" | "renameuser" @@ -4306,10 +4749,13 @@ export interface ApiQueryLogEventsParams extends ApiQueryParams { | "abusefilter/create" | "abusefilter/hit" | "abusefilter/modify" + | "abusefilterblockeddomainhit/*" | "abusefilterprivatedetails/access" | "block/block" | "block/reblock" | "block/unblock" + | "checkuser-private-event/*" + | "checkuser-temporary-account/*" | "contentmodel/change" | "contentmodel/new" | "create/create" @@ -4345,9 +4791,17 @@ export interface ApiQueryLogEventsParams extends ApiQueryParams { | "globalauth/setstatus" | "globalauth/unhide" | "globalauth/unlock" + | "growthexperiments/addimage" + | "growthexperiments/addlink" + | "growthexperiments/addsectionimage" + | "growthexperiments/claimmentee" + | "growthexperiments/claimmentee-no-previous-mentor" + | "growthexperiments/setmentor" + | "growthexperiments/setmentor-no-previous-mentor" | "import/interwiki" | "import/upload" | "interwiki/*" + | "ipinfo/*" | "managetags/activate" | "managetags/create" | "managetags/deactivate" @@ -4368,13 +4822,17 @@ export interface ApiQueryLogEventsParams extends ApiQueryParams { | "newusers/forcecreatelocal" | "newusers/newusers" | "oath/*" + | "pagetriage-copyvio/delete" | "pagetriage-copyvio/insert" | "pagetriage-curation/delete" | "pagetriage-curation/enqueue" | "pagetriage-curation/reviewed" + | "pagetriage-curation/reviewed-article" + | "pagetriage-curation/reviewed-redirect" | "pagetriage-curation/tag" | "pagetriage-curation/unreviewed" - | "pagetriage-deletion/delete" + | "pagetriage-curation/unreviewed-article" + | "pagetriage-curation/unreviewed-redirect" | "patrol/autopatrol" | "patrol/patrol" | "protect/modify" @@ -4438,9 +4896,7 @@ export interface KartographerApiQueryMapDataParams extends ApiQueryParams { mpdcontinue?: number; } -export interface MediaWikiMassMessageApiQueryMMSitesParams extends ApiQueryParams { - term?: string; -} +export interface MediaWikiMassMessageApiQueryMMContentParams extends ApiQueryParams {} export interface PageViewInfoApiQueryMostViewedParams extends ApiQueryParams { pvimmetric?: "pageviews"; @@ -4454,7 +4910,7 @@ export interface ApiQueryMyStashedFilesParams extends ApiQueryParams { msfcontinue?: string; } -export interface ApiEchoNotificationsParams extends ApiQueryParams { +export interface NotificationsApiEchoNotificationsParams extends ApiQueryParams { notwikis?: string | string[]; notfilter?: OneOrMore<"!read" | "read">; notprop?: OneOrMore<"count" | "list" | "seenTime">; @@ -4466,6 +4922,7 @@ export interface ApiEchoNotificationsParams extends ApiQueryParams { notunreadfirst?: boolean; nottitles?: string | string[]; notbundle?: boolean; + notnotifiertypes?: OneOrMore<"email" | "push" | "web">; notalertcontinue?: string; notalertunreadfirst?: boolean; notmessagecontinue?: string; @@ -4527,71 +4984,657 @@ export interface ApiQueryPagesWithPropParams extends ApiQueryParams { export interface WikibaseClientApiPageTermsParams extends ApiQueryParams { wbptcontinue?: number; - wbptterms?: OneOrMore<"alias" | "description" | "label">; -} - -export interface PageViewInfoApiQueryPageViewsParams extends ApiQueryParams { - pvipmetric?: "pageviews"; - pvipdays?: number; - pvipcontinue?: string; -} - -export interface ApiQueryPrefixSearchParams extends ApiQueryParams { - pssearch?: string; - psnamespace?: namespace | namespace[]; - pslimit?: limit; - psoffset?: number; - psprofile?: "classic" | "engine_autoselect" | "fast-fuzzy" | "fuzzy" | "normal" | "strict"; -} - -export interface PageAssessmentsApiQueryProjectPagesParams extends ApiQueryParams { - wppassessments?: boolean; - wppprojects?: string | string[]; - wpplimit?: limit; - wppcontinue?: string; -} - -export interface PageAssessmentsApiQueryProjectsParams extends ApiQueryParams { - pjsubprojects?: boolean; -} - -export interface ApiQueryProtectedTitlesParams extends ApiQueryParams { - ptnamespace?: namespace | namespace[]; - ptlevel?: OneOrMore<"autoconfirmed" | "extendedconfirmed" | "sysop" | "templateeditor">; - ptlimit?: limit; - ptdir?: "newer" | "older"; - ptstart?: timestamp; - ptend?: timestamp; - ptprop?: OneOrMore< - "comment" | "expiry" | "level" | "parsedcomment" | "timestamp" | "user" | "userid" - >; - ptcontinue?: string; -} - -export interface ApiQueryQueryPageParams extends ApiQueryParams { - qppage?: - | "Ancientpages" - | "BrokenRedirects" - | "Deadendpages" - | "DisambiguationPageLinks" - | "DisambiguationPages" - | "DoubleRedirects" - | "Fewestrevisions" - | "GadgetUsage" - | "GloballyWantedFiles" - | "ListDuplicatedFiles" - | "Listredirects" - | "Lonelypages" - | "Longpages" - | "MediaStatistics" - | "MostGloballyLinkedFiles" - | "Mostcategories" - | "Mostimages" + wbptlanguage?: + | "aa" + | "aae" + | "ab" + | "abs" + | "ace" + | "acm" + | "ady" + | "ady-cyrl" + | "aeb" + | "aeb-arab" + | "aeb-latn" + | "af" + | "agq" + | "aln" + | "als" + | "alt" + | "am" + | "ami" + | "an" + | "ang" + | "ann" + | "anp" + | "ar" + | "arc" + | "arn" + | "arq" + | "ary" + | "arz" + | "as" + | "ase" + | "ast" + | "atj" + | "av" + | "avk" + | "awa" + | "ay" + | "az" + | "azb" + | "ba" + | "bag" + | "ban" + | "ban-bali" + | "bar" + | "bas" + | "bat-smg" + | "bax" + | "bbc" + | "bbc-latn" + | "bbj" + | "bcc" + | "bci" + | "bcl" + | "bdr" + | "be" + | "be-tarask" + | "be-x-old" + | "bew" + | "bfd" + | "bg" + | "bgn" + | "bh" + | "bho" + | "bi" + | "bjn" + | "bkc" + | "bkh" + | "bkm" + | "blk" + | "bm" + | "bn" + | "bo" + | "bpy" + | "bqi" + | "bqz" + | "br" + | "brh" + | "bs" + | "btm" + | "bto" + | "bug" + | "bxr" + | "byv" + | "ca" + | "cak" + | "cal" + | "cbk-zam" + | "cdo" + | "ce" + | "ceb" + | "ch" + | "cho" + | "chr" + | "chy" + | "ckb" + | "cnh" + | "co" + | "cps" + | "cpx" + | "cpx-hans" + | "cpx-hant" + | "cpx-latn" + | "cr" + | "crh" + | "crh-cyrl" + | "crh-latn" + | "crh-ro" + | "cs" + | "csb" + | "cu" + | "cv" + | "cy" + | "da" + | "dag" + | "de" + | "de-at" + | "de-ch" + | "de-formal" + | "dga" + | "din" + | "diq" + | "dsb" + | "dtp" + | "dty" + | "dua" + | "dv" + | "dz" + | "ee" + | "efi" + | "egl" + | "el" + | "eml" + | "en" + | "en-ca" + | "en-gb" + | "en-us" + | "eo" + | "es" + | "es-419" + | "es-formal" + | "et" + | "eto" + | "etu" + | "eu" + | "ewo" + | "ext" + | "fa" + | "fat" + | "ff" + | "fi" + | "fit" + | "fiu-vro" + | "fj" + | "fkv" + | "fmp" + | "fo" + | "fon" + | "fr" + | "frc" + | "frp" + | "frr" + | "fur" + | "fy" + | "ga" + | "gaa" + | "gag" + | "gan" + | "gan-hans" + | "gan-hant" + | "gcf" + | "gcr" + | "gd" + | "gl" + | "gld" + | "glk" + | "gn" + | "gom" + | "gom-deva" + | "gom-latn" + | "gor" + | "got" + | "gpe" + | "grc" + | "gsw" + | "gu" + | "guc" + | "gur" + | "guw" + | "gv" + | "gya" + | "ha" + | "hak" + | "haw" + | "he" + | "hi" + | "hif" + | "hif-latn" + | "hil" + | "hno" + | "ho" + | "hr" + | "hrx" + | "hsb" + | "hsn" + | "ht" + | "hu" + | "hu-formal" + | "hy" + | "hyw" + | "hz" + | "ia" + | "id" + | "ie" + | "ig" + | "igl" + | "ii" + | "ik" + | "ike-cans" + | "ike-latn" + | "ilo" + | "inh" + | "io" + | "is" + | "isu" + | "it" + | "iu" + | "ja" + | "jam" + | "jbo" + | "jut" + | "jv" + | "ka" + | "kaa" + | "kab" + | "kai" + | "kbd" + | "kbd-cyrl" + | "kbp" + | "kcg" + | "kea" + | "ker" + | "kg" + | "kge" + | "khw" + | "ki" + | "kiu" + | "kj" + | "kjh" + | "kjp" + | "kk" + | "kk-arab" + | "kk-cn" + | "kk-cyrl" + | "kk-kz" + | "kk-latn" + | "kk-tr" + | "kl" + | "km" + | "kn" + | "ko" + | "ko-kp" + | "koi" + | "kr" + | "krc" + | "kri" + | "krj" + | "krl" + | "ks" + | "ks-arab" + | "ks-deva" + | "ksf" + | "ksh" + | "ksw" + | "ku" + | "ku-arab" + | "ku-latn" + | "kum" + | "kus" + | "kv" + | "kw" + | "ky" + | "la" + | "lad" + | "lb" + | "lbe" + | "lem" + | "lez" + | "lfn" + | "lg" + | "li" + | "lij" + | "liv" + | "lki" + | "lld" + | "lmo" + | "ln" + | "lns" + | "lo" + | "loz" + | "lrc" + | "lt" + | "ltg" + | "lus" + | "luz" + | "lv" + | "lzh" + | "lzz" + | "mad" + | "mag" + | "mai" + | "map-bms" + | "mcn" + | "mcp" + | "mdf" + | "mg" + | "mh" + | "mhr" + | "mi" + | "min" + | "mk" + | "ml" + | "mn" + | "mnc" + | "mnc-latn" + | "mnc-mong" + | "mni" + | "mnw" + | "mo" + | "mos" + | "mr" + | "mrh" + | "mrj" + | "ms" + | "ms-arab" + | "mt" + | "mua" + | "mus" + | "mwl" + | "my" + | "myv" + | "mzn" + | "na" + | "nah" + | "nan" + | "nan-hani" + | "nap" + | "nb" + | "nds" + | "nds-nl" + | "ne" + | "new" + | "ng" + | "nge" + | "nia" + | "nit" + | "niu" + | "nl" + | "nl-informal" + | "nla" + | "nmg" + | "nmz" + | "nn" + | "nnh" + | "nnz" + | "no" + | "nod" + | "nog" + | "nov" + | "nqo" + | "nrm" + | "nso" + | "nv" + | "ny" + | "nyn" + | "nyo" + | "nys" + | "oc" + | "ojb" + | "olo" + | "om" + | "or" + | "os" + | "osa-latn" + | "ota" + | "pa" + | "pag" + | "pam" + | "pap" + | "pap-aw" + | "pcd" + | "pcm" + | "pdc" + | "pdt" + | "pfl" + | "pi" + | "pih" + | "pl" + | "pms" + | "pnb" + | "pnt" + | "prg" + | "ps" + | "pt" + | "pt-br" + | "pwn" + | "qu" + | "quc" + | "qug" + | "rgn" + | "rif" + | "rki" + | "rm" + | "rmc" + | "rmf" + | "rmy" + | "rn" + | "ro" + | "roa-rup" + | "roa-tara" + | "rsk" + | "ru" + | "rue" + | "rup" + | "ruq" + | "ruq-cyrl" + | "ruq-latn" + | "rut" + | "rw" + | "rwr" + | "ryu" + | "sa" + | "sah" + | "sat" + | "sc" + | "scn" + | "sco" + | "sd" + | "sdc" + | "sdh" + | "se" + | "se-fi" + | "se-no" + | "se-se" + | "sei" + | "ses" + | "sg" + | "sgs" + | "sh" + | "sh-cyrl" + | "sh-latn" + | "shi" + | "shi-latn" + | "shi-tfng" + | "shn" + | "shy" + | "shy-latn" + | "si" + | "simple" + | "sjd" + | "sje" + | "sju" + | "sk" + | "skr" + | "skr-arab" + | "sl" + | "sli" + | "sm" + | "sma" + | "smj" + | "smn" + | "sms" + | "sn" + | "so" + | "sq" + | "sr" + | "sr-ec" + | "sr-el" + | "srn" + | "sro" + | "srq" + | "ss" + | "st" + | "stq" + | "sty" + | "su" + | "sv" + | "sw" + | "syl" + | "szl" + | "szy" + | "ta" + | "tay" + | "tcy" + | "tdd" + | "te" + | "tet" + | "tg" + | "tg-cyrl" + | "tg-latn" + | "th" + | "ti" + | "tk" + | "tl" + | "tly" + | "tly-cyrl" + | "tn" + | "to" + | "tok" + | "tpi" + | "tpv" + | "tr" + | "tru" + | "trv" + | "ts" + | "tt" + | "tt-cyrl" + | "tt-latn" + | "ttj" + | "tum" + | "tvu" + | "tw" + | "ty" + | "tyv" + | "tzm" + | "udm" + | "ug" + | "ug-arab" + | "ug-latn" + | "uk" + | "ur" + | "uselang" + | "uz" + | "uz-cyrl" + | "uz-latn" + | "ve" + | "vec" + | "vep" + | "vi" + | "vls" + | "vmf" + | "vmw" + | "vo" + | "vot" + | "vro" + | "vut" + | "wa" + | "wal" + | "war" + | "wes" + | "wls" + | "wo" + | "wuu" + | "wuu-hans" + | "wuu-hant" + | "wya" + | "xal" + | "xh" + | "xmf" + | "xsy" + | "yas" + | "yat" + | "yav" + | "ybb" + | "yi" + | "yo" + | "yrl" + | "yue" + | "yue-hans" + | "yue-hant" + | "za" + | "zea" + | "zgh" + | "zh" + | "zh-classical" + | "zh-cn" + | "zh-hans" + | "zh-hant" + | "zh-hk" + | "zh-min-nan" + | "zh-mo" + | "zh-my" + | "zh-sg" + | "zh-tw" + | "zh-yue" + | "zu"; + wbptterms?: OneOrMore<"alias" | "description" | "label">; +} + +export interface PageViewInfoApiQueryPageViewsParams extends ApiQueryParams { + pvipmetric?: "pageviews"; + pvipdays?: number; + pvipcontinue?: string; +} + +export interface ApiQueryPrefixSearchParams extends ApiQueryParams { + pssearch?: string; + psnamespace?: namespace | namespace[]; + pslimit?: limit; + psoffset?: number; + psprofile?: "classic" | "engine_autoselect" | "fast-fuzzy" | "fuzzy" | "normal" | "strict"; +} + +export interface PageAssessmentsApiQueryProjectPagesParams extends ApiQueryParams { + wppassessments?: boolean; + wppprojects?: string | string[]; + wpplimit?: limit; + wppcontinue?: string; +} + +export interface PageAssessmentsApiQueryProjectsParams extends ApiQueryParams { + pjsubprojects?: boolean; +} + +export interface ApiQueryProtectedTitlesParams extends ApiQueryParams { + ptnamespace?: namespace | namespace[]; + ptlevel?: OneOrMore<"autoconfirmed" | "extendedconfirmed" | "sysop" | "templateeditor">; + ptlimit?: limit; + ptdir?: "newer" | "older"; + ptstart?: timestamp; + ptend?: timestamp; + ptprop?: OneOrMore< + "comment" | "expiry" | "level" | "parsedcomment" | "timestamp" | "user" | "userid" + >; + ptcontinue?: string; +} + +export interface ApiQueryQueryPageParams extends ApiQueryParams { + qppage?: + | "Ancientpages" + | "BrokenRedirects" + | "Deadendpages" + | "DisambiguationPageLinks" + | "DisambiguationPages" + | "DoubleRedirects" + | "Fewestrevisions" + | "GadgetUsage" + | "GloballyWantedFiles" + | "ListDuplicatedFiles" + | "Listredirects" + | "Lonelypages" + | "Longpages" + | "MediaStatistics" + | "MostGloballyLinkedFiles" + | "Mostcategories" + | "Mostimages" | "Mostinterwikis" | "Mostlinked" | "Mostlinkedcategories" | "Mostlinkedtemplates" | "Mostrevisions" + | "OrphanedTimedText" | "Shortpages" | "Uncategorizedcategories" | "Uncategorizedimages" @@ -4664,7 +5707,6 @@ export interface ApiQueryRecentChangesParams extends ApiQueryParams { | "user" | "userid" >; - rctoken?: OneOrMore<"patrol">; rcshow?: OneOrMore< | "!anon" | "!autopatrolled" @@ -4748,7 +5790,6 @@ export interface ApiQueryRevisionsParams extends ApiQueryParams { rvuser?: string; rvexcludeuser?: string; rvtag?: string; - rvtoken?: OneOrMore<"rollback">; rvcontinue?: string; } @@ -4762,6 +5803,7 @@ export interface ApiQuerySearchParams extends ApiQueryParams { | "classic_noboostlinks" | "empty" | "engine_autoselect" + | "growth_underlinked" | "mlr-1024rs" | "popular_inclinks" | "popular_inclinks_pv" @@ -4797,11 +5839,16 @@ export interface ApiQuerySearchParams extends ApiQueryParams { | "last_edit_desc" | "none" | "random" - | "relevance"; + | "relevance" + | "user_random"; } export interface ApiQuerySiteinfoParams extends ApiQueryParams { siprop?: OneOrMore< + | "autocreatetempuser" + | "autopromote" + | "autopromoteonce" + | "clientlibraries" | "dbrepllag" | "defaultoptions" | "extensions" @@ -4899,9 +5946,9 @@ export interface ApiQueryBacklinkspropParams extends ApiQueryParams { ticontinue?: string; } -export interface ApiTranscodeStatusParams extends ApiQueryParams {} +export interface MediaWikiTimedMediaHandlerApiTranscodeStatusParams extends ApiQueryParams {} -export interface ApiEchoUnreadNotificationPagesParams extends ApiQueryParams { +export interface NotificationsApiEchoUnreadNotificationPagesParams extends ApiQueryParams { unpwikis?: string | string[]; unpgrouppages?: boolean; unplimit?: limit; @@ -4915,6 +5962,7 @@ export interface ApiQueryUserContribsParams extends ApiQueryParams { ucuser?: string | string[]; ucuserids?: number | number[]; ucuserprefix?: string; + uciprange?: string; ucdir?: "newer" | "older"; ucnamespace?: namespace | namespace[]; ucprop?: OneOrMore< @@ -4952,6 +6000,7 @@ export interface ApiQueryUserInfoParams extends ApiQueryParams { uiprop?: OneOrMore< | "acceptlang" | "blockinfo" + | "cancreateaccount" | "centralids" | "changeablegroups" | "editcount" @@ -4968,7 +6017,6 @@ export interface ApiQueryUserInfoParams extends ApiQueryParams { | "rights" | "theoreticalratelimits" | "unreadcount" - | "preferencestoken" >; uiattachedwiki?: string; } @@ -4990,10 +6038,9 @@ export interface ApiQueryUsersParams extends ApiQueryParams { usattachedwiki?: string; ususers?: string | string[]; ususerids?: number | number[]; - ustoken?: OneOrMore<"userrights">; } -export interface ApiQueryVideoInfoParams extends ApiQueryParams { +export interface MediaWikiTimedMediaHandlerApiQueryVideoInfoParams extends ApiQueryParams { viprop?: OneOrMore< | "archivename" | "badfile" @@ -5030,7 +6077,7 @@ export interface ApiQueryVideoInfoParams extends ApiQueryParams { viurlparam?: string; vibadfilecontexttitle?: string; vicontinue?: string; - vilocalonly?: string; + vilocalonly?: boolean; } export interface ApiQueryWatchlistParams extends ApiQueryParams { @@ -5103,18 +6150,18 @@ export interface WikibaseClientApiPropsEntityUsageParams extends ApiQueryParams } export interface WikibaseClientApiListEntityUsageParams extends ApiQueryParams { - wbeuprop?: OneOrMore<"url">; - wbeuaspect?: OneOrMore<"C" | "D" | "L" | "O" | "S" | "T" | "X">; - wbeuentities?: string | string[]; - wbeulimit?: limit; - wbeucontinue?: string; + wbleuprop?: OneOrMore<"url">; + wbleuaspect?: OneOrMore<"C" | "D" | "L" | "O" | "S" | "T" | "X">; + wbleuentities?: string | string[]; + wbleulimit?: limit; + wbleucontinue?: string; } export interface WikibaseClientApiClientInfoParams extends ApiQueryParams { wbprop?: OneOrMore<"siteid" | "url">; } -export interface ApiQueryWikiSetsParams extends ApiQueryParams { +export interface CentralAuthApiQueryWikiSetsParams extends ApiQueryParams { wsfrom?: string; wsprop?: OneOrMore<"type" | "wikisincluded" | "wikisnotincluded">; wslimit?: limit; diff --git a/jquery/client.d.ts b/jquery/client.d.ts index 0b82e40..152e6e6 100644 --- a/jquery/client.d.ts +++ b/jquery/client.d.ts @@ -1,5 +1,10 @@ declare global { interface JQueryStatic { + /** + * User-agent detection + * + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.client + */ client: Client; } } @@ -10,26 +15,30 @@ interface Client { * * The resulting client object will be in the following format: * - * { - * 'name': 'firefox', - * 'layout': 'gecko', - * 'layoutVersion': 20101026, - * 'platform': 'linux' - * 'version': '3.5.1', - * 'versionBase': '3', - * 'versionNumber': 3.5, - * } + * ```js + * { + * 'name': 'firefox', + * 'layout': 'gecko', + * 'layoutVersion': 20101026, + * 'platform': 'linux' + * 'version': '3.5.1', + * 'versionBase': '3', + * 'versionNumber': 3.5, + * } + * ``` * * Example: * - * if ( $.client.profile().layout == 'gecko' ) { - * // This will only run in Gecko browsers, such as Mozilla Firefox. - * } + * ```js + * if ( $.client.profile().layout == 'gecko' ) { + * // This will only run in Gecko browsers, such as Mozilla Firefox. + * } * - * var profile = $.client.profile(); - * if ( profile.layout == 'gecko' && profile.platform == 'linux' ) { - * // This will only run in Gecko browsers on Linux. - * } + * var profile = $.client.profile(); + * if ( profile.layout == 'gecko' && profile.platform == 'linux' ) { + * // This will only run in Gecko browsers on Linux. + * } + * ``` * * Recognised browser names: * @@ -67,11 +76,12 @@ interface Client { * - `solaris` (untested) * - `win` * - * @param {Object} [nav] An object with a 'userAgent' and 'platform' property. + * @param {ClientNavigator} [nav] An object with a 'userAgent' and 'platform' property. * Defaults to the global `navigator` object. - * @return {Object} The client object + * @returns {ClientProfile} The client object + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.client-method-profile */ - profile(nav?: { userAgent: string; platform: string }): ClientProfile; + profile(nav?: ClientNavigator): ClientProfile; /** * Checks the current browser against a support map object. @@ -82,53 +92,74 @@ interface Client { * * A browser map is in the following format: * - * { - * // Multiple rules with configurable operators - * 'msie': [['>=', 7], ['!=', 9]], - * // Match no versions - * 'iphone': false, - * // Match any version - * 'android': null - * } + * ```js + * { + * // Multiple rules with configurable operators + * 'msie': [['>=', 7], ['!=', 9]], + * // Match no versions + * 'iphone': false, + * // Match any version + * 'android': null + * } + * ``` * * It can optionally be split into ltr/rtl sections: * - * { - * 'ltr': { - * 'android': null, - * 'iphone': false - * }, - * 'rtl': { - * 'android': false, - * // rules are not inherited from ltr - * 'iphone': false - * } + * ```js + * { + * 'ltr': { + * 'android': null, + * 'iphone': false + * }, + * 'rtl': { + * 'android': false, + * // rules are not inherited from ltr + * 'iphone': false * } + * } + * ``` * - * @param {Object} map Browser support map - * @param {Object} [profile] A client-profile object + * @param {ClientSupportMap} map Browser support map + * @param {ClientProfile} [profile] A client-profile object * @param {boolean} [exactMatchOnly=false] Only return true if the browser is matched, * otherwise returns true if the browser is not found. - * - * @return {boolean} The current browser is in the support map + * @returns {boolean} The current browser is in the support map + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.client-method-test */ - test(map: any, profile?: ClientProfile, exactMatchOnly?: boolean): boolean; + test(map: 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 ComparisonOperator = "==" | "===" | "!=" | "!==" | "<" | "<=" | ">" | ">="; +type ClientSupportCondition = [ComparisonOperator, string | number]; + +type UndirectedClientSupportMap = Partial< + Record +>; +type ClientSupportMap = + | UndirectedClientSupportMap + | Record<"ltr" | "rtl", UndirectedClientSupportMap>; + 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/collapsibleTabs.d.ts b/jquery/collapsibleTabs.d.ts index accb571..b218fdf 100644 --- a/jquery/collapsibleTabs.d.ts +++ b/jquery/collapsibleTabs.d.ts @@ -13,13 +13,21 @@ declare global { } } -/** A jQuery plugin that makes collapsible tabs for the Vector skin. */ +/** + * A jQuery plugin that makes collapsible tabs for the Vector skin. + */ interface CollapsibleTabsOptions { - /** Optional tab selector. Defaults to `#p-views ul`. */ + /** + * Optional tab selector. Defaults to `#p-views ul`. + */ expandedContainer: string; - /** Optional menu item selector. Defaults to `#p-cactions ul`. */ + /** + * Optional menu item selector. Defaults to `#p-cactions ul`. + */ collapsedContainer: string; - /** Optional selector for tabs that are collapsible. Defaults to `li.collapsible`. */ + /** + * Optional selector for tabs that are collapsible. Defaults to `li.collapsible`. + */ collapsible: string; shifting: boolean; expandedWidth: number; diff --git a/jquery/colorUtil.d.ts b/jquery/colorUtil.d.ts index 3332e89..c71783a 100644 --- a/jquery/colorUtil.d.ts +++ b/jquery/colorUtil.d.ts @@ -4,6 +4,8 @@ declare global { } } +type Color = [number, number, number]; + interface ColorUtil { /** * Parse CSS color strings looking for color tuples @@ -11,20 +13,18 @@ interface ColorUtil { * Based on highlightFade by Blair Mitchelmore * * - * @param {Array|string} color - * @return {Array} + * @param {Color|string} color + * @returns {Color} */ - getRGB(color: string | number[]): number[]; + getRGB(color: string | T): T; /** * Named color map * * Based on Interface by Stefan Petre * - * - * @property {Object} */ - colors: Record; + colors: Record; /** * Convert an RGB color value to HSL. @@ -40,9 +40,9 @@ interface ColorUtil { * @param {number} r The red color value * @param {number} g The green color value * @param {number} b The blue color value - * @return {number[]} The HSL representation + * @returns {Color} The HSL representation */ - rgbToHsl(r: number, g: number, b: number): number[]; + rgbToHsl(r: number, g: number, b: number): Color; /** * Convert an HSL color value to RGB. @@ -58,25 +58,30 @@ interface ColorUtil { * @param {number} h The hue * @param {number} s The saturation * @param {number} l The lightness - * @return {number[]} The RGB representation + * @returns {Color} The RGB representation */ - hslToRgb(h: number, s: number, l: number): number[]; + hslToRgb(h: number, s: number, l: number): Color; /** * Get a brighter or darker rgb() value string. * * Usage: * - * $.colorUtil.getColorBrightness( 'red', +0.1 ); - * // > "rgb(255,50,50)" - * $.colorUtil.getColorBrightness( 'rgb(200,50,50)', -0.2 ); - * // > "rgb(118,29,29)" + * ```js + * $.colorUtil.getColorBrightness( 'red', +0.1 ); + * // > "rgb(255,50,50)" + * $.colorUtil.getColorBrightness( 'rgb(200,50,50)', -0.2 ); + * // > "rgb(118,29,29)" + * ``` * - * @param {Mixed} currentColor Current value in css + * @param {Color|string} currentColor Current value in css * @param {number} mod Wanted brightness modification between -1 and 1 - * @return {string} Like `'rgb(r,g,b)'` + * @returns {string} Like `'rgb(r,g,b)'` */ - getColorBrightness(currentColor: any, mod: number): `rgb(${number},${number},${number})`; + getColorBrightness( + currentColor: string | Color, + mod: number + ): `rgb(${number},${number},${number})`; } export {}; diff --git a/jquery/index.d.ts b/jquery/index.d.ts index cf11390..14b9c18 100644 --- a/jquery/index.d.ts +++ b/jquery/index.d.ts @@ -1,6 +1,6 @@ import "jquery"; -import "./textSelection"; -import "./collapsibleTabs"; import "./client"; +import "./collapsibleTabs"; import "./colorUtil"; +import "./textSelection"; diff --git a/jquery/textSelection.d.ts b/jquery/textSelection.d.ts index 0a85786..8af079b 100644 --- a/jquery/textSelection.d.ts +++ b/jquery/textSelection.d.ts @@ -1,62 +1,174 @@ declare global { interface JQuery { - // one overload for each command + /** + * Get the contents of the textarea. + * + * @param {string} command Command to execute + * @returns {string} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection + */ textSelection(command: "getContents"): string; - textSelection(command: "setContents"): JQuery; + /** + * Set the contents of the textarea, replacing anything that was there before. + * + * @param {string} command Command to execute + * @param {string} content + * @returns {JQuery} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection + */ + textSelection(command: "setContents", content: string): this; + /** + * Get the currently selected text in this textarea. + * + * @param {string} command Command to execute + * @returns {string} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection + */ textSelection(command: "getSelection"): string; - textSelection(command: "replaceSelection"): JQuery; + /** + * Replace the selected text in the textarea with the given text, or insert it at the cursor. + * + * @param {string} command Command to execute + * @param {string} value + * @returns {JQuery} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection + */ + textSelection(command: "replaceSelection", value: string): this; + /** + * Insert text at the beginning and end of a text selection, optionally + * inserting text at the caret when selection is empty. + * + * Also focusses the textarea. + * + * @param {string} command Command to execute + * @param {Partial} [options] + * @returns {JQuery} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection + */ textSelection( command: "encapsulateSelection", - commandOptions: { - pre?: string; - peri?: string; - post?: string; - ownline?: boolean; - replace?: boolean; - selectPeri?: boolean; - splitlines?: boolean; - selectionStart?: number; - selectionEnd?: number; - } - ): JQuery; + options?: Partial + ): this; + /** + * 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|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", - commandOptions?: { - startAndEnd?: false; - } - ): number; - + options: { startAndEnd: true } + ): [number, number]; + textSelection(command: "getCaretPosition", options?: { startAndEnd?: false }): number; textSelection( command: "getCaretPosition", - commandOptions: { - startAndEnd: true; - } - ): [number, number]; + options?: { startAndEnd: boolean } + ): number | [number, number]; - textSelection( - command: "setSelection", - commandOptions: { - start?: number; - end?: number; - } - ): JQuery; + /** + * Set the current cursor position (in UTF-16 code units) in a textarea. + * + * @param {string} command Command to execute + * @param {Object} options + * @param {number} options.start + * @param {number} [options.end=options.start] + * @returns {JQuery} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection + */ + textSelection(command: "setSelection", options: { start: number; end?: number }): this; + /** + * Scroll a textarea to the current cursor position. You can set the cursor + * position with 'setSelection'. + * + * @param {string} command Command to execute + * @param {Object} [options] + * @param {boolean} [options.force=false] Whether to force a scroll even if the caret position + * is already visible. + * @returns {JQuery} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection + */ + textSelection(command: "scrollToCaretPosition", options: { force?: boolean }): this; + + /** + * Register an alternative textSelection API for this element. + * + * @param {string} command Command to execute + * @param {Object.} functions Functions to replace. Keys are command names (as in {@link textSelection}, + * except 'register' and 'unregister'). Values are functions to execute when a given command is + * called. + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection + */ textSelection( - command: "scrollToCaretPosition", - commandOptions: { - force?: boolean; - } - ): JQuery; + command: "register", + functions: Record any> + ): void; + /** + * Unregister the alternative textSelection API for this element (see 'register'). + * + * @param {string} command Command to execute + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/jQuery.plugin.textSelection-method-textSelection + */ textSelection(command: "unregister"): void; - textSelection(command: "register", commandOptions: Record any>): 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 {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; } } +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 index 4665ba8..a391580 100644 --- a/mw/Api.d.ts +++ b/mw/Api.d.ts @@ -1,18 +1,94 @@ import { + ApiParams, ApiEditPageParams, + ApiLegacyTokenType, ApiParseParams, ApiQueryAllMessagesParams, ApiRollbackParams, + ApiTokenType, ApiUploadParams, + ApiAssert, + ApiQueryTokensParams, } from "../api_params"; +import { TitleLike } from "./Title"; +import { UserInfo } from "./user"; -type TitleLike = string | mw.Title; -type TitleLikeArray = string[] | mw.Title[]; // TitleLike[] would be a mixed array -type ApiParams = Record; +type TypeOrArray = T extends any ? T | T[] : never; // T[] would be a mixed array +type ReplaceValue = T extends U[] ? V[] : V; + +type UnknownApiParams = Record; type ApiResponse = Record; // it will always be a JSON object, the rest is uncertain ... +interface Revision { + content: string; + timestamp: string; +} + +type EditResult = EditFailureResult | EditNoChangeResult | EditChangedResult; + +interface EditFailureResult { + result: "Failure"; +} + +interface EditSuccessResult { + contentmodel: string | false; + pageid: number; + result: "Success"; + tempusercreated?: true; + tempusercreatedredirect?: string; + title: string; + watched?: true; + watchlistexpiry?: string; +} + +interface EditNoChangeResult extends EditSuccessResult { + nochange: true; +} + +interface EditChangedResult extends EditSuccessResult { + oldrevid: number; + newrevid: number; + newtimestamp: string; +} + +interface AssertUser { + assert: "anon" | "user"; + assertUser: string; +} + +interface WatchStatus { + ns: number; + title: string; + watched: boolean; +} + +interface RollbackInfo { + /** + * The revision being restored (the last revision before revision(s) by the reverted user). + */ + last_revid: number; + /** + * The revision being reverted (previously the current revision of the page). + */ + old_revid: number; + pageid: number; + revid: number; + summary: string; + title: string; +} + +interface FinishUpload { + /** + * Call this function to finish the upload. + * + * @param {ApiUploadParams} data Additional data for the upload. + * @returns {JQuery.Promise} API promise for the final upload. + */ + (data?: ApiUploadParams): JQuery.Promise; +} + /** - * Default options for jQuery#ajax calls. Can be overridden by passing + * Default options for {@link jQuery.ajax} calls. Can be overridden by passing * `options` to {@link mw.Api} constructor. * * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-property-defaultOptions @@ -21,11 +97,11 @@ export interface ApiOptions { /** * Default query parameters for API requests */ - parameters?: ApiParams; + parameters: UnknownApiParams; /** - * Default options for jQuery#ajax + * Default options for {@link jQuery.ajax} */ - ajax?: JQuery.AjaxSettings; + ajax: JQuery.AjaxSettings; /** * Whether to use U+001F when joining multi-valued parameters (since 1.28). * Default is true if ajax.url is not set, false otherwise for compatibility. @@ -41,6 +117,7 @@ declare global { class Api { /** * Constructor to create an object to interact with the API of a particular MediaWiki server. mw.Api objects represent the API of a particular MediaWiki server. + * * ```js * var api = new mw.Api(); * api.get( { @@ -50,7 +127,9 @@ declare global { * console.log( data ); * } ); * ``` + * * Since MW 1.25, multiple values for a parameter can be specified using an array: + * * ```js * var api = new mw.Api(); * api.get( { @@ -60,79 +139,97 @@ declare global { * console.log( data ); * } ); * ``` + * * Since MW 1.26, boolean values for a parameter can be specified directly. If the value is false or undefined, the parameter will be omitted from the request, as required by the API. * - * @param {ApiOptions} options + * @param {ApiOptions} [options] * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-constructor */ - constructor(options?: ApiOptions); + constructor(options?: Partial); - /** - * @private - */ - defaults: ApiOptions; + private defaults: ApiOptions; /** * Abort all unfinished requests issued by this Api object. * - * @returns {void} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-abort */ abort(): void; /** - * Perform API get request. + * Perform API get request. See {@link ajax()} for details. * - * @param {ApiParams} parameters - * @param {JQuery.AjaxSettings?} ajaxOptions + * @param {UnknownApiParams} parameters + * @param {JQuery.AjaxSettings} [ajaxOptions] * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-get */ get( - parameters: ApiParams, + parameters: UnknownApiParams, ajaxOptions?: JQuery.AjaxSettings ): JQuery.Promise; /** - * Perform API post request. + * Perform API post request. See {@link ajax()} for details. * - * @param {ApiParams} parameters - * @param {JQuery.AjaxSettings?} ajaxOptions + * @param {UnknownApiParams} parameters + * @param {JQuery.AjaxSettings} [ajaxOptions] * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-post */ post( - parameters: ApiParams, + parameters: UnknownApiParams, ajaxOptions?: JQuery.AjaxSettings ): JQuery.Promise; /** * Massage parameters from the nice format we accept into a format suitable for the API. * - * @private - * @param {ApiParams} parameters (modified in-place) + * @param {UnknownApiParams} parameters (modified in-place) * @param {boolean} useUS Whether to use U+001F when joining multi-valued parameters. - * @returns {void} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-preprocessParameters */ - private preprocessParameters(parameters: ApiParams, useUS: boolean): void; + private preprocessParameters(parameters: UnknownApiParams, useUS: boolean): void; /** * Perform the API call. * - * @param {ApiParams} parameters - * @param {JQuery.AjaxSettings?} ajaxOptions - * @returns {JQuery.Promise} API response data and the jqXHR object + * @param {UnknownApiParams} parameters Parameters to the API. See also {@link ApiOptions.parameters} + * @param {JQuery.AjaxSettings} [ajaxOptions] Parameters to pass to jQuery.ajax. See also {@link ApiOptions.ajax} + * @returns {JQuery.Promise} A promise that settles when the API response is processed. + * Has an 'abort' method which can be used to abort the request. + * + * - On success, resolves to `( result, jqXHR )` where `result` is the parsed API response. + * - On an API error, rejects with `( code, result, result, jqXHR )` where `code` is the + * [API error code](https://www.mediawiki.org/wiki/API:Errors_and_warnings), and `result` + * is as above. When there are multiple errors, the code from the first one will be used. + * If there is no error code, "unknown" is used. + * - On other types of errors, rejects with `( 'http', details )` where `details` is an object + * with three fields: `xhr` (the jqXHR object), `textStatus`, and `exception`. + * The meaning of the last two fields is as follows: + * - When the request is aborted (the abort method of the promise is called), textStatus + * and exception are both set to "abort". + * - On a network timeout, textStatus and exception are both set to "timeout". + * - On a network error, textStatus is "error" and exception is the empty string. + * - When the HTTP response code is anything other than 2xx or 304 (the API does not + * use such response codes but some intermediate layer might), textStatus is "error" + * and exception is the HTTP status text (the text following the status code in the + * first line of the server response). For HTTP/2, `exception` is always an empty string. + * - When the response is not valid JSON but the previous error conditions aren't met, + * textStatus is "parsererror" and exception is the exception object thrown by + * `JSON.parse`. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-ajax */ ajax( - parameters: ApiParams, + parameters: UnknownApiParams, ajaxOptions?: JQuery.AjaxSettings ): JQuery.Promise; /** - * Post to API with specified type of token. If we have no token, get one and try to post. - * If we have a cached token try using that, and if it fails, blank out the - * cached token and start over. For example to change an user option you could do: + * Post to API with the specified type of token. If we have no token, get one and try to post. + * If we already have a cached token, try using that, and if the request fails using the cached token, + * blank it out and start over. For example, to change a user option, you could do: + * * ```js * new mw.Api().postWithToken( 'csrf', { * action: 'options', @@ -141,29 +238,52 @@ declare global { * } ); * ``` * - * @param {string} tokenType The name of the token, like `options` or `edit` - * @param {ApiParams} params API parameters - * @param {JQuery.AjaxSettings?} ajaxOptions - * @returns {JQuery.Promise} * @since 1.22 + * @param {string} tokenType The name of the token, like `options` or `edit`. + * @param {UnknownApiParams} params API parameters + * @param {JQuery.AjaxSettings} [ajaxOptions] + * @returns {JQuery.Promise} See {@link post} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-postWithToken */ + postWithToken( + tokenType: ApiTokenType, + params: UnknownApiParams, + ajaxOptions?: JQuery.AjaxSettings + ): JQuery.Promise; + /** @deprecated Use "csrf" instead */ + postWithToken( + tokenType: ApiLegacyTokenType, + params: UnknownApiParams, + ajaxOptions?: JQuery.AjaxSettings + ): JQuery.Promise; postWithToken( tokenType: string, - params: ApiParams, + params: UnknownApiParams, ajaxOptions?: JQuery.AjaxSettings ): JQuery.Promise; /** * Get a token for a certain action from the API. * + * @since 1.22 * @param {string} type Token type - * @param {(ApiParams | string)?} additionalParams Additional parameters for the API (since 1.35). When given a string, it's treated as the `assert` parameter (since 1.25) + * @param {ApiQueryTokensParams|ApiAssert} [additionalParams] Additional parameters for the API (since 1.35). When given a string, it's treated as the `assert` parameter (since 1.25) * @returns {JQuery.Promise} Received token - * @since 1.22 * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-getToken */ - getToken(type: string, additionalParams?: ApiParams | string): JQuery.Promise; + getToken( + type: ApiTokenType, + additionalParams?: ApiQueryTokensParams | ApiAssert + ): JQuery.Promise; + /** @deprecated Use "csrf" instead */ + getToken( + type: ApiLegacyTokenType, + additionalParams?: ApiQueryTokensParams | ApiAssert + ): JQuery.Promise; + getToken( + type: string, + additionalParams?: ApiQueryTokensParams | ApiAssert + ): JQuery.Promise; /** * Indicate that the cached token for a certain action of the API is bad. @@ -172,11 +292,13 @@ declare global { * You may also want to use `postWithToken()` instead, which invalidates bad cached tokens * automatically. * - * @param {string} type Token type - * @returns {void} * @since 1.26 + * @param {string} type Token type * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-badToken */ + badToken(type: ApiTokenType): void; + /** @deprecated Use "csrf" instead */ + badToken(type: ApiLegacyTokenType): void; badToken(type: string): void; /** @@ -211,7 +333,7 @@ declare global { * } ); * ``` * - * @param {Object} data API response indicating an error + * @param {ApiResponse} data API response indicating an error * @returns {JQuery} Error messages, each wrapped in a `
` * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-getErrorMessage */ @@ -220,20 +342,20 @@ declare global { /** * Post to API with csrf token. If we have no token, get one and try to post. If we have a cached token try using that, and if it fails, blank out the cached token and start over. * - * @param {APIParams} params API parameters - * @param {JQuery.AjaxSettings?} ajaxOptions + * @param {UnknownApiParams} params API parameters + * @param {JQuery.AjaxSettings} [ajaxOptions] See {@link post} * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.edit-method-postWithEditToken */ postWithEditToken( - params: ApiParams, + params: UnknownApiParams, ajaxOptions?: JQuery.AjaxSettings ): JQuery.Promise; /** * API helper to grab a csrf token. * - * @returns {JQuery.Promise} + * @returns {JQuery.Promise} Received token. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.edit-method-getEditToken */ getEditToken(): JQuery.Promise; @@ -242,6 +364,7 @@ declare global { * Create a new page. * * Example: + * * ```js * new mw.Api().create( 'Sandbox', * { summary: 'Load sand particles.' }, @@ -249,17 +372,18 @@ declare global { * ); * ``` * + * @since 1.28 * @param {TitleLike} title Page title * @param {ApiEditPageParams} params Edit API parameters * @param {string} content Page content - * @returns {} + * @returns {JQuery.Promise} API response * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.edit-method-create */ create( title: TitleLike, params: ApiEditPageParams, content: string - ): JQuery.Promise; + ): JQuery.Promise; /** * Edit an existing page. @@ -267,6 +391,7 @@ declare global { * To create a new page, use create() instead. * * Simple transformation: + * * ```js * new mw.Api() * .edit( 'Sandbox', function ( revision ) { @@ -276,7 +401,9 @@ declare global { * console.log( 'Saved!' ); * } ); * ``` + * * Set save parameters by returning an object instead of a string: + * * ```js * new mw.Api().edit( * 'Sandbox', @@ -293,7 +420,9 @@ declare global { * console.log( 'Saved!' ); * } ); * ``` + * * Transform asynchronously by returning a promise. + * * ```js * new mw.Api() * .edit( 'Sandbox', function ( revision ) { @@ -311,18 +440,16 @@ declare global { * } ); * ``` * + * @since 1.28 * @param {TitleLike} title Page title - * @param {(data: { timestamp: string, content: string }) => string | ApiEditPageParams} transform Callback that prepares the edit - * @returns {JQuery.Promise} + * @param {function(Revision):string|ApiEditPageParams} transform Callback that prepares the edit + * @returns {JQuery.Promise} Edit API response * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.edit-method-edit */ edit( title: TitleLike, - transform: (data: { - timestamp: string; - content: string; - }) => string | ApiEditPageParams - ): JQuery.Promise; + transform: (revision: Revision) => string | ApiEditPageParams + ): JQuery.Promise; /** * Post a new section to the page. @@ -344,13 +471,11 @@ declare global { /** * Get the current user's groups and rights. * - * @returns {JQuery.Promise<{ groups: string[], rights: string[] }>} + * @since 1.27 + * @returns {JQuery.Promise} * @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; /** * Extend an API parameter object with an assertion that the user won't change. @@ -362,16 +487,14 @@ declare global { * * `apierror-assertuserfailed`: when the client-side logic thinks the user is logged in but the server thinks it is anonymous * * `apierror-assertnameduserfailed`: when both the client-side logic and the server thinks the user is logged in but they see it logged in under a different username. * - * @param {ApiParams} query Query parameters. The object will not be changed - * @returns {JQuery.Promise<{ assert: "anon" | "user", assertUser: string }>} + * @since 1.27 + * @param {UnknownApiParams} query Query parameters. The object will not be changed + * @returns {AssertUser} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.user-method-assertCurrentUser */ - assertCurrentUser( - query: ApiParams - ): JQuery.Promise<{ - assert: "anon" | "user"; - assertUser: string; - }>; + assertCurrentUser( + query: T + ): Omit & AssertUser; /** * Asynchronously save the value of a single user option using the API. See `saveOptions()`. @@ -384,7 +507,7 @@ declare global { saveOption(name: string, value: string | null): JQuery.Promise; /** - * Asynchronously save the values of user options using the API. + * Asynchronously save the values of user options using the [Options API](https://www.mediawiki.org/wiki/API:Options). * * If a value of `null` is provided, the given option will be reset to the default value. * @@ -394,7 +517,7 @@ declare global { * * If a request from a previous `saveOptions()` call is still pending, this will wait for it to be completed, otherwise MediaWiki gets sad. No requests are sent for anonymous users, as they would fail anyway. See T214963. * - * @param {Object} options + * @param {Object.} options Options as a `{ name: value, … }` object * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.options-method-saveOptions */ @@ -403,87 +526,79 @@ declare global { /** * Convenience method for `action=watch`. * - * @param {TitleLike | TitleLikeArray} pages - * @param {string?} expiry - * @returns {JQuery.Promise<{ watch: { title: string, watched: boolean } | Array<{ title: string, watched: boolean }> }>} - * @since 1.35: expiry parameter can be passed when watchlist expiry is enabled + * @since 1.35 - expiry parameter can be passed when Watchlist Expiry is enabled + * @param {TypeOrArray} pages + * @param {string} [expiry] + * @returns {JQuery.Promise>} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.watch-method-watch */ - watch

( + watch

>( pages: P, expiry?: string - ): JQuery.Promise<{ - watch: P extends TitleLikeArray - ? Array<{ title: string; watched: boolean }> - : { title: string; watched: boolean }; - }>; + ): JQuery.Promise>; /** * Convenience method for `action=watch&unwatch=1`. * - * @param {TitleLike | TitleLikeArray} pages - * @returns {JQuery.Promise<{ watch: { title: string, watched: boolean } | Array<{ title: string, watched: boolean }> }>} + * @param {TypeOrArray} pages + * @returns {JQuery.Promise>} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.watch-method-unwatch */ - unwatch

( + unwatch

>( pages: P - ): JQuery.Promise<{ - watch: P extends TitleLikeArray - ? Array<{ title: string; watched: boolean }> - : { title: string; watched: boolean }; - }>; + ): JQuery.Promise>; /** * Convenience method for `action=parse`. * - * @param {string | mw.Title} content Content to parse, either as a wikitext string or a mw.Title - * @param {ApiParseParams} additionalParams - * @returns {JQuery.Promise} + * @param {TitleLike} content Content to parse, either as a wikitext string or a mw.Title + * @param {ApiParseParams} [additionalParams] Parameters object to set custom settings, e.g. + * redirects, sectionpreview. prop should not be overridden. + * @returns {JQuery.Promise} Parsed HTML of `wikitext`. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.parse-method-parse */ - parse( - content: string | mw.Title, - additionalParams?: ApiParseParams - ): JQuery.Promise; + parse(content: TitleLike, additionalParams?: ApiParseParams): JQuery.Promise; /** * Get a set of messages. * - * @param {string[]} messages Messages to retrieve - * @param {ApiQueryAllMessagesParams?} options Additional parameters for the API call - * @returns {JQuery.Promise} + * @since 1.27 + * @param {string|string[]} messages Messages to retrieve + * @param {ApiQueryAllMessagesParams} [options] Additional parameters for the API call + * @returns {JQuery.Promise>} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.messages-method-getMessages */ - getMessages( - messages: string[], + getMessages( + messages: T | T[], options?: ApiQueryAllMessagesParams - ): JQuery.Promise; + ): JQuery.Promise>>; /** * Load a set of messages and add them to `mw.messages`. * - * @param {string[]} messages Messages to retrieve - * @param {ApiQueryAllMessagesParams?} options Additional parameters for the API call - * @returns {JQuery.Promise} + * @param {string|string[]} messages Messages to retrieve + * @param {ApiQueryAllMessagesParams} [options] Additional parameters for the API call + * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.messages-method-loadMessages */ loadMessages( - messages: string[], + messages: string | string[], options?: ApiQueryAllMessagesParams - ): JQuery.Promise; + ): JQuery.Promise; /** * Load a set of messages and add them to `mw.messages`. Only messages that are not already known are loaded. If all messages are known, the returned promise is resolved immediately. * + * @since 1.27 * @param {string[]} messages Messages to retrieve - * @param {ApiQueryAllMessagesParams?} options Additional parameters for the API call - * @returns {JQuery.Promise} + * @param {ApiQueryAllMessagesParams} [options] Additional parameters for the API call + * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.messages-method-loadMessagesIfMissing */ loadMessagesIfMissing( messages: string[], options?: ApiQueryAllMessagesParams - ): JQuery.Promise; + ): JQuery.Promise; /** * Determine if a category exists. @@ -509,32 +624,34 @@ declare global { * Get the categories that a particular page on the wiki belongs to. * * @param {TitleLike} title - * @returns {JQuery.Promise} List of category titles or false if title was not found + * @returns {JQuery.Promise} List of category titles or false if title was not found * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.category-method-getCategories */ - getCategories(title: TitleLike): JQuery.Promise; + getCategories(title: TitleLike): JQuery.Promise; /** * Convenience method for `action=rollback`. * + * @since 1.28 * @param {TitleLike} page * @param {string} user - * @param {ApiRollbackParams?} params Additional parameters + * @param {ApiRollbackParams} [params] Additional parameters + * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.rollback-method-rollback */ rollback( page: TitleLike, user: string, params?: ApiRollbackParams - ): JQuery.Promise; + ): JQuery.Promise; /** * Upload a file in several chunks. * * @param {File} file * @param {ApiUploadParams} data Other upload options, see `action=upload` API docs for more - * @param {number?} chunkSize Size (in bytes) per chunk (default: 5MB) - * @param {number?} chunkRetries Amount of times to retry a failed chunk (default: 1) + * @param {number} [chunkSize] Size (in bytes) per chunk (default: 5MB) + * @param {number} [chunkRetries] Amount of times to retry a failed chunk (default: 1) * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.upload-method-chunkedUpload */ @@ -550,28 +667,28 @@ declare global { * * This function will return a promise that will resolve with a function to finish the stash upload. * - * @param {File | HTMLInputElement} file - * @param {ApiUploadParams?} data - * @param {number?} chunkSize Size (in bytes) per chunk (default: 5MB) - * @param {number?} chunkRetries Amount of times to retry a failed chunk (default: 1) - * @returns {JQuery.Promise<(data?: ApiUploadParams) => JQuery.Promise>} Call this function to finish the upload + * @param {File|HTMLInputElement} file + * @param {ApiUploadParams} [data] + * @param {number} [chunkSize] Size (in bytes) per chunk (default: 5MB) + * @param {number} [chunkRetries] Amount of times to retry a failed chunk (default: 1) + * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.upload-method-chunkedUploadToStash */ chunkedUploadToStash( - file: File, + file: File | HTMLInputElement, data?: ApiUploadParams, chunkSize?: number, chunkRetries?: number - ): JQuery.Promise<(data?: ApiUploadParams) => JQuery.Promise>; + ): JQuery.Promise; /** * Upload a file to MediaWiki. * * The file will be uploaded using AJAX and FormData. * - * @param {HTMLInputElement | File | Blob} file HTML `input type=file` element with a file already inside of it, or a File object. + * @param {File|Blob|HTMLInputElement} file HTML `input type=file` element with a file already inside of it, or a File object. * @param {ApiUploadParams} data Other upload options, see `action=upload` API docs for more - * @return {JQuery.Promise} + * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.upload-method-upload */ upload( @@ -593,6 +710,7 @@ declare global { * Upload a file to the stash. * * This function will return a promise that will resolve with a function to finish the stash upload. You can call that function with an argument containing more, or conflicting, data to pass to the server. For example: + * * ```js * // upload a file to the stash with a placeholder filename * api.uploadToStash( file, { filename: 'testing.png' } ).done( function ( finish ) { @@ -604,21 +722,20 @@ declare global { * } ); * ``` * - * @param {File | HTMLInputElement} file - * @param {ApiUploadParams?} data - * @return {JQuery.Promise} - * @returns {JQuery.Promise<(data?: ApiUploadParams) => JQuery.Promise>} Call this function to finish the upload + * @param {File|HTMLInputElement} file + * @param {ApiUploadParams} [data] + * @returns {JQuery.Promise} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.upload-method-uploadToStash */ uploadToStash( file: File | HTMLInputElement, data?: ApiUploadParams - ): JQuery.Promise<(data?: ApiUploadParams) => JQuery.Promise>; + ): JQuery.Promise; /** * @param {string} username * @param {string} password - * @returns {JQuery.Promise} + * @returns {JQuery.Promise} See {@link post()} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api.plugin.login-method-login */ login(username: string, password: string): JQuery.Promise; diff --git a/mw/ForeignApi.d.ts b/mw/ForeignApi.d.ts index 4959efe..afb5743 100644 --- a/mw/ForeignApi.d.ts +++ b/mw/ForeignApi.d.ts @@ -4,7 +4,7 @@ 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. */ - anonymous?: boolean; + anonymous: boolean; } declare global { @@ -12,11 +12,17 @@ declare global { /** * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi */ - class ForeignApi extends mw.Api { + class ForeignApi extends Api { + static static: {}; + static super: typeof Api; + /** @deprecated Use `super` instead */ + static parent: typeof Api; + /** - * Create an object like `mw.Api`, but automatically handling everything required to communicate with another MediaWiki wiki via cross-origin requests (CORS). + * Create an object like {@link mw.Api}, but automatically handling everything required to communicate with another MediaWiki wiki via cross-origin requests (CORS). * * The foreign wiki must be configured to accept requests from the current wiki. See for details. + * * ```js * var api = new mw.ForeignApi( 'https://commons.wikimedia.org/w/api.php' ); * api.get( { @@ -30,26 +36,27 @@ declare global { * To ensure that the user at the foreign wiki is logged in, pass the `assert: 'user'` parameter to `get()`/`post()` (since MW 1.23): if they are not, the API request will fail. (Note that this doesn't guarantee that it's the same user.) * * Authentication-related MediaWiki extensions may extend this class to ensure that the user authenticated on the current wiki will be automatically authenticated on the foreign one. These extension modules should be registered using the ResourceLoaderForeignApiModules hook. See CentralAuth for a practical example. The general pattern to extend and override the name is: + * * ```js * function MyForeignApi() {}; * OO.inheritClass( MyForeignApi, mw.ForeignApi ); * mw.ForeignApi = MyForeignApi; * ``` * - * @param {string | mw.Uri} url URL pointing to another wiki's `api.php` endpoint. - * @param {ForeignApiOptions?} options * @since 1.26 + * @param {string|Uri} url URL pointing to another wiki's `api.php` endpoint. + * @param {Partial} [options] * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-constructor */ - constructor(url: string | mw.Uri, options?: ForeignApiOptions); + constructor(url: string | Uri, options?: Partial); /** * Return the origin to use for API requests, in the required format (protocol, host and port, if any). * - * @protected - * @return {string | undefined} + * @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 631fd66..1302232 100644 --- a/mw/ForeignRest.d.ts +++ b/mw/ForeignRest.d.ts @@ -6,7 +6,7 @@ interface ForeignRestOptions extends RestOptions { * accept cross-origin requests, or if you don't need to perform write actions or read * restricted information and want to avoid the overhead. */ - anonymous?: boolean; + anonymous: boolean; } declare global { @@ -14,9 +14,14 @@ declare global { /** * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignRest */ - class ForeignRest extends mw.Rest { + class ForeignRest extends Rest { + static static: {}; + static super: typeof Rest; + /** @deprecated Use `super` instead */ + static parent: typeof Rest; + /** - * Create an object like `mw.Rest`, but automatically handling everything required + * Create an object like {@link mw.Rest}, but automatically handling everything required * to communicate with another MediaWiki wiki via cross-origin requests (CORS). * * The foreign wiki must be configured to accept requests from the current wiki. See https://www.mediawiki.org/wiki/Manual:$wgCrossSiteAJAXdomains for details. @@ -41,16 +46,16 @@ declare global { * mw.ForeignRest = MyForeignRest; * ``` * - * @param {string | mw.Uri} url URL pointing to another wiki's rest.php endpoint. - * @param {mw.ForeignApi} foreignActionApi - * @param {ForeignRestOptions?} options - * @since 1.26 - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignApi-method-constructor + * @since 1.36 + * @param {string} url URL pointing to another wiki's `rest.php` endpoint. + * @param {ForeignApi} foreignActionApi + * @param {Partial} [options] + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.ForeignRest-method-constructor */ constructor( - url: string | mw.Uri, - foreignActionApi: mw.ForeignApi, - options?: ForeignRestOptions + url: string, + foreignActionApi: ForeignApi, + options?: Partial ); } } diff --git a/mw/Map.d.ts b/mw/Map.d.ts index 6d42de8..0475f5a 100644 --- a/mw/Map.d.ts +++ b/mw/Map.d.ts @@ -1,3 +1,69 @@ +type TypeOrArray = T | T[]; + +// Get/PickOrDefault extracts values from V using key selection S +// - TD is the value type of missing properties +// - TX is the value type of unknown properties + +type GetOrDefault = K extends keyof V + ? V extends Required> + ? V[K] + : Required[K] | TD + : TX | TD; + +type PickOrDefault, TD, TX = unknown> = S extends Array< + infer K +> + ? { [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. + +export interface ExtensibleMap, TX = unknown> + extends mw.Map> { + /** + * Check if a given key exists in the map. + * + * @param selection Key to check + * @returns True if the key exists + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-exists + */ + exists(selection: S): selection is S; + exists(selection: S): selection is S; + + /** + * Get the value of one or more keys. + * + * If called with no arguments, all values are returned. + * + * @param selection Key or array of keys to retrieve values for. + * @param fallback Value for keys that don't exist. + * @returns If selection was a string, returns the value. If selection was an array, returns + * an object of key/values. If no selection is passed, a new object with all key/values is returned. + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-get + */ + get, TD>( + selection: S, + fallback: TD + ): PickOrDefault; + get, TD>(selection: S, fallback: TD): PickOrDefault; + get>(selection: S): PickOrDefault; + get>(selection: S): PickOrDefault; + get(): V & Record; + + /** + * Set the value of one or more keys. + * + * @param selection Key to set value for, or object mapping keys to values + * @param value Value to set (optional, only in use when key is a string) + * @returns True on success, false on failure + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-set + */ + set(selection: S, value: V[S]): boolean; + set(selection: S, value: TX): boolean; + set & Record>(selection: S): boolean; +} + declare global { namespace mw { /** @@ -6,27 +72,38 @@ declare global { * * **NOTE**: This is a private utility class for internal use by the framework. * Don't rely on its existence. + * * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map */ class Map = any> { private values: V; + /** + * Check if a given key exists in the map. + * + * @param selection Key to check + * @returns True if the key exists + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-exists + */ + exists(selection: S): selection is S; + /** * Get the value of one or more keys. * * If called with no arguments, all values are returned. + * * @param selection Key or array of keys to retrieve values for. * @param fallback Value for keys that don't exist. * @returns If selection was a string, returns the value. If selection was an array, returns * an object of key/values. If no selection is passed, a new object with all key/values is returned. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-get */ - get(): V; - get>( + get, TD>( selection: S, - fallback?: any - ): Pick ? SS : never>; - get(selection: S, fallback?: V[S]): V[S]; + fallback: TD + ): PickOrDefault; + get>(selection: S): PickOrDefault; + get(): V; /** * Set the value of one or more keys. @@ -37,15 +114,7 @@ declare global { * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-set */ set(selection: S, value: V[S]): boolean; - set(selection: Partial): boolean; - - /** - * Check if a given key exists in the map. - * @param selection Key to check - * @returns True if the key exists - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-exists - */ - exists(selection: keyof V): boolean; + set>(selection: S): boolean; } } } diff --git a/mw/RegExp.d.ts b/mw/RegExp.d.ts index 238a077..b66cc1a 100644 --- a/mw/RegExp.d.ts +++ b/mw/RegExp.d.ts @@ -1,7 +1,6 @@ declare global { namespace mw { /** - * @class mw.RegExp * @see https://doc.wikimedia.org/mediawiki-core/REL1_29/js/source/mediawiki.RegExp.html */ namespace RegExp { @@ -12,10 +11,10 @@ declare global { * * \ { } ( ) | . ? * + - ^ $ [ ] * - * @deprecated - * @since 1.26; deprecated since 1.34 + * @deprecated since 1.34 + * @since 1.26 * @param {string} str String to escape - * @return {string} Escaped string + * @returns {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; diff --git a/mw/Rest.d.ts b/mw/Rest.d.ts index f2b1021..d412830 100644 --- a/mw/Rest.d.ts +++ b/mw/Rest.d.ts @@ -1,11 +1,3 @@ -import { - ApiEditPageParams, - ApiParseParams, - ApiQueryAllMessagesParams, - ApiRollbackParams, - ApiUploadParams, -} from "../api_params"; - export interface RestOptions { ajax: JQuery.AjaxSettings; } @@ -43,20 +35,16 @@ declare global { * } ); * ``` * - * @param {RestOptions} options + * @param {Partial} [options] * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-constructor */ - constructor(options?: RestOptions); + constructor(options?: Partial); - /** - * @private - */ - defaultOptions: RestOptions; + private defaults: RestOptions; /** * Abort all unfinished requests issued by this Api object. * - * @returns {void} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Rest-method-abort */ abort(): void; @@ -131,8 +119,8 @@ declare global { * Perform the API call. * * @param {string} path - * @param {JQuery.AjaxSettings?} ajaxOptions - * @returns {JQuery.Promise} API response data and the jqXHR object + * @param {JQuery.AjaxSettings} [ajaxOptions] + * @returns {JQuery.Promise} Done: API response data and the jqXHR object. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Api-method-ajax */ ajax(path: string, ajaxOptions?: JQuery.AjaxSettings): JQuery.Promise; diff --git a/mw/Title.d.ts b/mw/Title.d.ts index 8130a37..b03910d 100644 --- a/mw/Title.d.ts +++ b/mw/Title.d.ts @@ -1,61 +1,70 @@ -type title = string | mw.Title; +import { QueryParams } from "./Uri"; + +export type TitleLike = string | mw.Title; declare global { namespace mw { /** * Parse titles into an object structure. Note that when using the constructor - * directly, passing invalid titles will result in an exception. Use #newFromText to use the + * directly, passing invalid titles will result in an exception. Use {@link newFromText} to use the * logic directly and get null for invalid titles which is easier to work with. * - * Note that in the constructor and #newFromText method, `namespace` is the **default** namespace + * Note that in the constructor and {@link newFromText} method, `namespace` is the **default** namespace * only, and can be overridden by a namespace prefix in `title`. If you do not want this behavior, - * use #makeTitle. Compare: + * use {@link makeTitle}. Compare: * - * new mw.Title( 'Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' - * mw.Title.newFromText( 'Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' - * mw.Title.makeTitle( NS_TEMPLATE, 'Foo' ).getPrefixedText(); // => 'Template:Foo' + * ```js + * new mw.Title( 'Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' + * mw.Title.newFromText( 'Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' + * mw.Title.makeTitle( NS_TEMPLATE, 'Foo' ).getPrefixedText(); // => 'Template:Foo' * - * new mw.Title( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo' - * mw.Title.newFromText( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo' - * mw.Title.makeTitle( NS_TEMPLATE, 'Category:Foo' ).getPrefixedText(); // => 'Template:Category:Foo' + * new mw.Title( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo' + * mw.Title.newFromText( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo' + * mw.Title.makeTitle( NS_TEMPLATE, 'Category:Foo' ).getPrefixedText(); // => 'Template:Category:Foo' * - * new mw.Title( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' - * mw.Title.newFromText( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' - * mw.Title.makeTitle( NS_TEMPLATE, 'Template:Foo' ).getPrefixedText(); // => 'Template:Template:Foo' + * new mw.Title( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' + * mw.Title.newFromText( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo' + * mw.Title.makeTitle( NS_TEMPLATE, 'Template:Foo' ).getPrefixedText(); // => 'Template:Template:Foo' + * ``` * - * @class mw.Title + * @since 1.18 * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title */ class Title { /** * Store page existence * - * @static - * @property {Object} exist - * @property {Object} exist.pages Keyed by title. Boolean true value indicates page does exist. - * - * @property {Function} exist.set The setter function. - * - * Example to declare existing titles: - * - * Title.exist.set( ['User:John_Doe', ...] ); - * - * Example to declare titles nonexistent: - * - * Title.exist.set( ['File:Foo_bar.jpg', ...], false ); - * - * @property {string|Array} exist.set.titles Title(s) in strict prefixedDb title form - * @property {boolean} [exist.set.state=true] State of the given titles - * @return {boolean} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-static-property-exist */ static exist: { + /** + * Keyed by title. Boolean true value indicates page does exist. + */ pages: { [title: string]: boolean }; - set: (titles: string | string[], state?: boolean) => boolean; + + /** + * The setter function. + * + * Example to declare existing titles: + * + * ```js + * Title.exist.set( ['User:John_Doe', ...] ); + * ``` + * + * Example to declare titles nonexistent: + * + * ```js + * Title.exist.set( ['File:Foo_bar.jpg', ...], false ); + * ``` + * + * @param {string|string[]} titles Title(s) in strict prefixedDb title form + * @param {boolean} [state=true] State of the given titles + * @returns {boolean} + */ + set(titles: string | string[], state?: boolean): boolean; }; /** - * @method constructor * @param {string} title Title of the page. If no second argument given, * this will be searched for a namespace * @param {number} [namespace=NS_MAIN] If given, will used as default namespace for the given title @@ -67,7 +76,7 @@ declare global { /** * Check the title can have an associated talk page * - * @return {boolean} The title can have an associated talk page + * @returns {boolean} The title can have an associated talk page * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-canHaveTalkPage */ canHaveTalkPage(): boolean; @@ -75,7 +84,7 @@ declare global { /** * Whether this title exists on the wiki. * - * @return {boolean|null} Boolean if the information is available, otherwise null + * @returns {boolean|null} Boolean if the information is available, otherwise null * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-exists */ exists(): boolean | null; @@ -83,7 +92,7 @@ declare global { /** * Get the extension of the page name (if any) * - * @return {string|null} Name extension or null if there is none + * @returns {string|null} Name extension or null if there is none * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getExtension */ getExtension(): string | null; @@ -94,9 +103,9 @@ declare global { * "File:Example_image.svg" will be returned as "Example image". * * Note that this method will work for non-file titles but probably give nonsensical results. - * A title like "User:Dr._J._Fail" will be returned as "Dr. J"! Use #getMainText instead. + * A title like "User:Dr._J._Fail" will be returned as "Dr. J"! Use {@link getMainText} instead. * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getFileNameTextWithoutExtension */ getFileNameTextWithoutExtension(): string; @@ -107,9 +116,9 @@ declare global { * "File:Example_image.svg" will be returned as "Example_image". * * Note that this method will work for non-file titles but probably give nonsensical results. - * A title like "User:Dr._J._Fail" will be returned as "Dr._J"! Use #getMain instead. + * A title like "User:Dr._J._Fail" will be returned as "Dr._J"! Use {@link getMain} instead. * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getFileNameWithoutExtension */ getFileNameWithoutExtension(): string; @@ -120,7 +129,7 @@ declare global { * Note that this method (by design) does not include the hash character and * the value is not url encoded. * - * @return {string|null} + * @returns {string|null} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getFragment */ getFragment(): string | null; @@ -130,7 +139,7 @@ declare global { * * Example: "Example_image.svg" for "File:Example_image.svg". * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getMain */ getMain(): string; @@ -140,17 +149,30 @@ declare global { * * Example: "Example image.svg" for "File:Example_image.svg". * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getMainText */ getMainText(): string; + /** + * Get the page name as if it is a file name, without extension or namespace prefix. Warning, + * this is usually not what you want! A title like "User:Dr._J._Fail" will be returned as + * "Dr. J"! Use {@link getMain} or {@link getMainText} for the actual page name. + * + * @deprecated since 1.40, use {@link getFileNameWithoutExtension} instead + * @returns {string} File name without file extension, in the canonical form with underscores + * instead of spaces. For example, the title "File:Example_image.svg" will be returned as + * "Example_image". + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getName + */ + getName(): string; + /** * Get the namespace number * * Example: 6 for "File:Example_image.svg". * - * @return {number} + * @returns {number} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getNamespaceId */ getNamespaceId(): number; @@ -161,18 +183,31 @@ declare global { * Example: "File:" for "File:Example_image.svg". * In #NS_MAIN this is '', otherwise namespace name plus ':' * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getNamespacePrefix */ getNamespacePrefix(): string; + /** + * Get the page name as if it is a file name, without extension or namespace prefix. Warning, + * this is usually not what you want! A title like "User:Dr._J._Fail" will be returned as + * "Dr. J"! Use {@link getMainText} for the actual page name. + * + * @deprecated since 1.40, use {@link getFileNameTextWithoutExtension} instead + * @returns {string} File name without file extension, formatted with spaces instead of + * underscores. For example, the title "File:Example_image.svg" will be returned as + * "Example image". + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getNameText + */ + getNameText(): string; + /** * Get the full page name * * Example: "File:Example_image.svg". * Most useful for API calls, anything that must identify the "title". * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getPrefixedDb */ getPrefixedDb(): string; @@ -182,7 +217,7 @@ declare global { * * Example: "File:Example image.svg" for "File:Example_image.svg". * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getPrefixedText */ getPrefixedText(): string; @@ -197,7 +232,7 @@ declare global { * - "Foo:Bar" relative to any namespace other than Foo stays "Foo:Bar". * * @param {number} namespace The namespace to be relative to - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getRelativeText */ getRelativeText(namespace: number): string; @@ -205,7 +240,7 @@ declare global { /** * Get the title for the subject page of a talk page * - * @return {mw.Title|null} The title for the subject page of a talk page, null if not available + * @returns {Title|null} The title for the subject page of a talk page, null if not available * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getSubjectPage */ getSubjectPage(): Title | null; @@ -213,7 +248,7 @@ declare global { /** * Get the title for the associated talk page * - * @return {mw.Title|null} The title for the associated talk page, null if not available + * @returns {Title|null} The title for the associated talk page, null if not available * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getTalkPage */ getTalkPage(): Title | null; @@ -221,133 +256,68 @@ declare global { /** * Get the URL to this title * - * @param {Object} [params] A mapping of query parameter names to values, + * @param {QueryParams} [params] A mapping of query parameter names to values, * e.g. `{ action: 'edit' }`. - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getUrl */ - getUrl(params?: any): string; - - /** - * Check if a given namespace is a talk namespace - * - * See NamespaceInfo::isTalk in PHP - * - * @param {number} namespaceId Namespace ID - * @return {boolean} Namespace is a talk namespace - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-isTalkNamespace - */ - isTalkNamespace(namespaceId: number): boolean; + getUrl(params?: QueryParams): string; /** * Check if the title is in a talk namespace * - * @return {boolean} The title is in a talk namespace + * @returns {boolean} The title is in a talk namespace * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-isTalkPage */ isTalkPage(): boolean; /** - * Normalize a file extension to the common form, making it lowercase and checking some synonyms, - * and ensure it's clean. Extensions with non-alphanumeric characters will be discarded. - * Keep in sync with File::normalizeExtension() in PHP. - * - * @param {string} extension File extension (without the leading dot) - * @return {string} File extension in canonical form - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-normalizeExtension - */ - normalizeExtension(extension: string): string; - - /** - * PHP's strtoupper differs from String.toUpperCase in a number of cases (T147646). - * - * @param {string} chr Unicode character - * @return {string} Unicode character, in upper case, according to the same rules as in PHP - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-phpCharToUpper - */ - phpCharToUpper(chr: string): string; - - /** - * Alias of mw.Title#getPrefixedDb - * - * TODO: Use @-alias when we switch to JSDoc + * Alias of {@link getPrefixedDb} * - * @method * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-toString */ toString(): string; /** - * Alias of mw.Title#getPrefixedText + * Alias of {@link getPrefixedText} * - * TODO: Use @-alias when we switch to JSDoc - * - * @method * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-toText */ toText(): string; /** - * Check if signature buttons should be shown in a given namespace - * - * See NamespaceInfo::wantSignatures in PHP - * - * @param {number} namespaceId Namespace ID - * @return {boolean} Namespace is a signature namespace - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-wantSignaturesNamespace - */ - wantSignatureNamespace(namespaceId: number): boolean; - - /** - * Get the page name as if it is a file name, without extension or namespace prefix. Warning, - * this is usually not what you want! A title like "User:Dr._J._Fail" will be returned as - * "Dr. J"! Use #getMain or #getMainText for the actual page name. + * Whether this title exists on the wiki. * - * @deprecated since 1.40, use #getFileNameWithoutExtension instead - * @return {string} File name without file extension, in the canonical form with underscores - * instead of spaces. For example, the title "File:Example_image.svg" will be returned as - * "Example_image". - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getName + * @param {string|Title} title prefixed db-key name (string) or instance of Title + * @returns {boolean|null} Boolean if the information is available, otherwise null + * @throws {Error} If title is not a string or mw.Title + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-static-method-exists */ - getName(): string; + static exists(title: TitleLike): boolean | null; /** - * Get the page name as if it is a file name, without extension or namespace prefix. Warning, - * this is usually not what you want! A title like "User:Dr._J._Fail" will be returned as - * "Dr. J"! Use #getMainText for the actual page name. + * Check if a given namespace is a talk namespace * - * @deprecated since 1.40, use #getFileNameTextWithoutExtension instead - * @return {string} File name without file extension, formatted with spaces instead of - * underscores. For example, the title "File:Example_image.svg" will be returned as - * "Example image". - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-getNameText - */ - getNameText(): string; - - /** - * Whether this title exists on the wiki. + * See NamespaceInfo::isTalk in PHP * - * @static - * @param {string|mw.Title} title prefixed db-key name (string) or instance of Title - * @return {boolean|null} Boolean if the information is available, otherwise null - * @throws {Error} If title is not a string or mw.Title - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-static-method-exists + * @param {number} namespaceId Namespace ID + * @returns {boolean} Namespace is a talk namespace + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-isTalkNamespace */ - static exists(title: title): boolean | null; + static isTalkNamespace(namespaceId: number): boolean; /** * Constructor for Title objects with predefined namespace. * - * Unlike #newFromText or #constructor, this function doesn't allow the given `namespace` to be - * overridden by a namespace prefix in `title`. See #constructor for details about this behavior. + * Unlike {@link newFromText} or {@link constructor}, this function doesn't allow the given `namespace` to be + * overridden by a namespace prefix in `title`. See {@link constructor} for details about this behavior. * * The single exception to this is when `namespace` is 0, indicating the main namespace. The - * function behaves like #newFromText in that case. + * function behaves like {@link newFromText} in that case. * - * @static * @param {number} namespace Namespace to use for the title * @param {string} title - * @return {Title|null} A valid Title object or null if the title is invalid + * @returns {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-makeTitle */ static makeTitle(namespace: number, title: string): Title | null; @@ -357,37 +327,36 @@ declare global { * so it is most likely a valid MediaWiki title and file name after processing. * Returns null on fatal errors. * - * @static * @param {string} uncleanName The unclean file name including file extension but * without namespace - * @return {Title|null} A valid Title object or null if the title is invalid + * @returns {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 * - * var title = mw.Title.newFromImg( imageNode ); + * ```js + * var title = mw.Title.newFromImg( imageNode ); + * ``` * - * @static * @param {HTMLElement|JQuery} img The image to use as a base - * @return {Title|null} The file title or null if unsuccessful + * @returns {Title|null} The file title or null if unsuccessful * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-static-method-newFromImg */ - static newFromImg(img: HTMLElement | JQuery): Title; + static newFromImg(img: HTMLElement | JQuery): Title | null; /** * Constructor for Title objects with a null return instead of an exception for invalid titles. * * Note that `namespace` is the **default** namespace only, and can be overridden by a namespace - * prefix in `title`. If you do not want this behavior, use #makeTitle. See #constructor for + * prefix in `title`. If you do not want this behavior, use {@link makeTitle}. See {@link constructor} for * details. * - * @static * @param {string} title * @param {number} [namespace=NS_MAIN] Default namespace - * @return {Title|null} A valid Title object or null if the title is invalid + * @returns {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-newFromText */ static newFromText(title: string, namespace?: number): Title | null; @@ -396,7 +365,6 @@ declare global { * Constructor for Title objects from user input altering that input to * produce a title that MediaWiki will accept as legal * - * @static * @param {string} title * @param {number} [defaultNamespace=NS_MAIN] * If given, will used as default namespace for the given title. @@ -405,14 +373,45 @@ declare global { * Makes sure that a file is uploadable under the title returned. * There are pages in the file namespace under which file upload is impossible. * Automatically assumed if the title is created in the Media namespace. - * @return {Title|null} A valid Title object or null if the input cannot be turned into a valid title + * @returns {Title|null} A valid Title object or null if the input cannot be turned into a valid title * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-static-method-newFromUserInput */ static newFromUserInput( title: string, defaultNamespace?: number, - options?: { forUploading: boolean } - ): Title; + options?: { forUploading?: boolean } + ): Title | null; + + /** + * Normalize a file extension to the common form, making it lowercase and checking some synonyms, + * and ensure it's clean. Extensions with non-alphanumeric characters will be discarded. + * Keep in sync with File::normalizeExtension() in PHP. + * + * @param {string} extension File extension (without the leading dot) + * @returns {string} File extension in canonical form + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-normalizeExtension + */ + static normalizeExtension(extension: string): string; + + /** + * PHP's strtoupper differs from {@link String.toUpperCase} in a number of cases (T147646). + * + * @param {string} chr Unicode character + * @returns {string} Unicode character, in upper case, according to the same rules as in PHP + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-phpCharToUpper + */ + static phpCharToUpper(chr: string): string; + + /** + * Check if signature buttons should be shown in a given namespace + * + * See NamespaceInfo::wantSignatures in PHP + * + * @param {number} namespaceId Namespace ID + * @returns {boolean} Namespace is a signature namespace + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title-method-wantSignaturesNamespace + */ + static wantSignatureNamespace(namespaceId: number): boolean; } } } diff --git a/mw/Uri.d.ts b/mw/Uri.d.ts index f7e3173..f748e3b 100644 --- a/mw/Uri.d.ts +++ b/mw/Uri.d.ts @@ -1,10 +1,26 @@ -type Options = - | { - strictMode?: boolean; - overrideKeys?: boolean; - arrayParams?: boolean; - } - | boolean; +export type QueryParams = Record; + +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; +} + +interface UriParser { + strict: RegExp; + loose: RegExp; +} declare global { namespace mw { @@ -12,53 +28,114 @@ declare global { * 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 + * @returns {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. + * + * Intended to be minimal, but featureful; do not expect full RFC 3986 compliance. The use cases we + * have in mind are constructing 'next page' or 'previous page' URLs, detecting whether we need to + * use cross-domain proxies for an API, constructing simple URL-based API calls, etc. Parsing here + * is regex-based, so may not work on all URIs, but is good enough for most. + * + * You can modify the properties directly, then use the {@link toString} method to extract the full URI + * string again. Example: + * + * ```js + * var uri = new mw.Uri( 'http://example.com/mysite/mypage.php?quux=2' ); + * + * if ( uri.host == 'example.com' ) { + * uri.host = 'foo.example.com'; + * uri.extend( { bar: 1 } ); + * + * $( 'a#id1' ).attr( 'href', uri ); + * // anchor with id 'id1' now links to http://foo.example.com/mysite/mypage.php?bar=1&quux=2 + * + * $( 'a#id2' ).attr( 'href', uri.clone().extend( { bar: 3, pif: 'paf' } ) ); + * // anchor with id 'id2' now links to http://foo.example.com/mysite/mypage.php?bar=3&quux=2&pif=paf + * } + * ``` + * + * Given a URI like + * `http://usr:pwd@www.example.com:81/dir/dir.2/index.htm?q1=0&&test1&test2=&test3=value+%28escaped%29&r=1&r=2#top` + * the returned object will have the following properties: + * + * ```js + * protocol 'http' + * user 'usr' + * password 'pwd' + * host 'www.example.com' + * port '81' + * path '/dir/dir.2/index.htm' + * query { + * q1: '0', + * test1: null, + * test2: '', + * test3: 'value (escaped)' + * r: ['1', '2'] + * } + * fragment 'top' + * ``` + * + * (N.b., 'password' is technically not allowed for HTTP URIs, but it is possible with other kinds + * of URIs.) + * + * Parsing based on parseUri 1.2.2 (c) Steven Levithan , MIT License. + * + * + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri + */ class Uri { /** - * @property {string|undefined} fragment For example `top` + * 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) + * 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` + * 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) + * 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` + * 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) + * 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) + * 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` + * For example `usr` + * * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-property-user */ user: string | undefined; @@ -70,25 +147,16 @@ declare global { * 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; - }; + private static parser: UriParser; /** * 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: [ + private static properties: [ "protocol", "user", "password", @@ -103,46 +171,25 @@ declare global { * 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 + * @param {Partial|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>, + options?: Partial | boolean ); /** * Clone this URI * - * @return {Uri} New URI object with same properties + * @returns {Uri} New URI object with same properties * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-clone */ clone(): Uri; @@ -150,19 +197,19 @@ declare global { /** * 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 + * @param {QueryParams} parameters Query parameters to add to ours (or to override ours with) as an * object - * @return {Uri} This URI object + * @returns {Uri} This URI object * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-extend */ - extend(parameters: Record): Uri; + extend(parameters: QueryParams): 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} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-getAuthority */ getAuthority(): string; @@ -170,7 +217,7 @@ declare global { /** * Get host and port section of a URI. * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-getHostPort */ getHostPort(): string; @@ -180,7 +227,7 @@ declare global { * * Does not preserve the original order of arguments passed in the URI. Does handle escaping. * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-getQueryString */ getQueryString(): string; @@ -188,7 +235,7 @@ declare global { /** * Get everything after the authority section of the URI. * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-getRelativePath */ getRelativePath(): string; @@ -196,7 +243,7 @@ declare global { /** * Get user and password section of a URI. * - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Uri-method-getUserInfo */ getUserInfo(): string; @@ -212,31 +259,29 @@ declare global { * web2017-polyfills, which loads a polyfill if needed) in contexts where the fragment * is important. * - * @return {string} The URI string + * @returns {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. * - * @private * @param {string} str URI, see constructor. - * @param {Object} options See constructor. + * @param {Partial} 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; + private parse(str: string, options: Partial): void; /** * Decode a url encoded value. * - * Reversed #encode. Standard decodeURIComponent, with addition of replacing + * Reversed {@link encode}. Standard decodeURIComponent, with addition of replacing * `+` with a space. * - * @static * @param {string} s String to decode - * @return {string} Decoded string + * @returns {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 */ @@ -249,9 +294,8 @@ declare global { * 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 + * @returns {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; diff --git a/mw/config.d.ts b/mw/config.d.ts index 557515d..ba74e7f 100644 --- a/mw/config.d.ts +++ b/mw/config.d.ts @@ -1,73 +1,395 @@ +import { ExtensibleMap } from "./Map"; + 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) + * Check out {@link https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#mw.config the complete list of configuration values} * 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; + const config: ExtensibleMap<{ + /** + * Since MediaWiki 1.36+, 0 means debug mode is off, and a positive non-zero number means debug mode is on (e.g. 1 or 2). + * + * In MediaWiki 1.35 and earlier, false and true were used (phab:T85805). + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#debug + */ + debug: boolean | number; + /** + * The internal name of the currently used skin. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#skin + */ skin: string; + /** + * Full URL to the root directory for skins, containing stylesheets and skin-specific scripts. The path does not contain the skin subdirectory, and is not terminated by a "/". + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#stylepath + */ stylepath: string; + wgActionPaths: Record; + /** + * Local path, starting at the root, to reference articles, containing a "$1" placeholder that may be replaced by a page title to get a valid URL to that page. Given a valid page title title, a valid URL may be constructed using wgArticlePath.replace('$1', title). See also $wgArticlePath. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgArticlePath + */ wgArticlePath: string; - wgCaseSensitiveNamespaces: string[]; + /** + * The IDs of the namespaces treated as case-sensitive by MediaWiki. Determined by the values of them $wgCapitalLinks and $wgCapitalLinksOverrides configuration variables. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgCaseSensitiveNamespaces + */ + wgCaseSensitiveNamespaces: number[]; + wgCommentCodePointLimit: number; + /** + * The language code for the default content language of the wiki. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgContentLanguage + */ wgContentLanguage: string; + /** + * The IDs of the namespaces considered "content namespaces" by MediaWiki. Equivalent to the value of the $wgContentNamespaces configuration variable, with 0 included if it is not already. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgContentNamespaces + */ wgContentNamespaces: number[]; + /** + * The name of the wiki's database. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgDBname + */ wgDBname: string; - wgEnableAPI: boolean; - wgEnableWriteAPI: boolean; + /** + * Root path used for extension static assets (e.g. images). Append '/' then the name of the extension to get the root path for a given extension. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgExtensionAssetsPath + */ wgExtensionAssetsPath: string; + wgExtraSignatureNamespaces: number[]; + /** + * Gives a mapping from namespace IDs to localized namespace names. For each namespace, the object has one entry that has the stringified namespace number as the key and the namespace name as its value. Aliases or canonical names are not included. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgFormattedNamespaces + */ wgFormattedNamespaces: Record; + wgIllegalFileChars: string; + wgLegalTitleChars: string; + /** + * Gives a mapping from namespace names to namespace IDs. For each namespace name, including localized and canonical names as well as aliases, the object has one entry that has namespace name as the key and the namespace ID as its integer value. The keys are all lowercase, with spaces replaced by underscores. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgNamespaceIds + */ wgNamespaceIds: Record; + /** + * Full path to the main access point script, starting at the root, including the full script name with extension. On WMF wikis, normally "/w/index.php". See also $wgScript. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgScript + */ wgScript: string; + /** + * The path part of wgScript, without trailing "/". This is the path to use for direct calls to the php access points such as index.php or api.php. See also $wgScriptPath. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgScriptPath + */ wgScriptPath: string; + /** + * The server URL, not terminated by "/". The combination wgServer + wgScriptPath + "/api.php", for instance, results in a valid URL to the API access point script. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgServer + */ wgServer: string; + /** + * The name of the server, without the protocol or trailing slash (e.g. "en.wikipedia.org"). + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgServerName + */ wgServerName: string; + /** + * The name of the site, as defined by $wgSitename. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgSiteName + */ wgSiteName: string; + wgTranslateNumerals: boolean; + wgUrlProtocols: string; + /** + * If a wiki has language variants (such as the Chinese and the Serbian Wikipedias), set to a path beginning at the root for language variants other than wgContentLanguage. The path contains two placeholders: "$1" is to be replaced by the page title, and "$2" is to be replaced by the language code of the language variant (e.g. "zh-tw"). If the wiki does not have language variants, set to false. See also $wgVariantArticlePath. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgVariantArticlePath + */ wgVariantArticlePath: string | false; + /** + * Identifies the version of MediaWiki that served the page. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgVersion + */ wgVersion: string; + /** + * The wiki identifier. Should be preferred over wgDBname. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgWikiID + */ + wgWikiID: string; + /** + * The action performed, e.g. "edit" for edit pages, or "view" for page views. See Manual:Parameters to index.php#Actions. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgAction + */ wgAction: string; + /** + * The internal ID (page ID) of the page. For non-existent pages and special pages, it is zero. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgArticleId + */ wgArticleId: number; + /** + * The canonical (i.e., not localized or aliased) namespace name of the page. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgCanonicalNamespace + */ wgCanonicalNamespace: string; + /** + * On special pages, the canonical (i.e., not localized or aliased) name of the special page; otherwise it is not defined at all (up to and including MW 1.15) or is set to false (since MW 1.16). + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgCanonicalSpecialPageName + */ wgCanonicalSpecialPageName: string | false; + /** + * The list of all the categories a page belongs to. This is essentially a JavaScript version of the category box shown on the page (grey box at bottom of page, in Monobook/Vector). If the category box is not shown on the current page (as is the case when editing/viewing history), wgCategories will be an empty array. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgCategories + */ wgCategories: string[]; + /** + * The top revision ID of the currently viewed page at the time the page was served. Also set on diff and history pages; zero for special pages. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgCurRevisionId + */ wgCurRevisionId: number; + /** + * true if the page displays the content of a wiki page, e.g. when viewing a page (regardless of namespace), or when viewing an old revision or diff with rendered content below it. It is false for anything else (edit form, history page, special pages, most generated pages, etc.). + * + * This variable is badly named – it is not related to a page being a main namespace "article". + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgIsArticle + */ wgIsArticle: boolean; + /** + * True if the page is probably editable (based on Title::quickUserCan) by the current user. The 'probably' is necessary for performance reasons. An exact editability check is too costly here, due to cascading protection and hook-based extensions like TitleBlacklist that may be enabled. If this is true, it is likely to be editable. If it is false, it is definitely not editable. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgIsProbablyEditable + */ wgIsProbablyEditable: boolean; + /** + * true if the page is a redirect to a wiki page using #REDIRECT [[Target page name]]. It is false for anything else (normal pages, special pages, most generated pages, etc.). + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgIsRedirect + */ + wgIsRedirect: boolean; + /** + * The number of the namespace the page is in. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgNamespaceNumber + */ wgNamespaceNumber: number; + /** + * Language code of the page content language (according to $context->getTitle()->getPageLanguage()) + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgPageContentLanguage + */ wgPageContentLanguage: string; + /** + * 'wikitext' on typical wiki pages, 'javascript' on pages interpreted as JavaScript, 'css' on pages interpreted as CSS, 'Scribunto' on pages interpreted as Scribunto (Lua). + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgPageContentModel + */ wgPageContentModel: string; + /** + * The full name of the page, including the localized namespace name, if the namespace has a name (the main namespace (number 0) doesn't), and with spaces replaced by underscores. To get only the title without the namespace, use wgTitle. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgPageName + */ wgPageName: string; - wgRedirectedFrom: string; + /** + * Parser limit report for the page when parser data is available. Includes data about parset limits, Lua statistics when Scribunto extension is enabled and parser cache information. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgPageParseReport + */ + wgPageParseReport: PageParseReport; + /** + * When redirected contains the title of the page we were redirected from. If the page was not redirected, the value is omitted entirely (absent in mw.config). Uses the same format as wgPageName + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgRedirectedFrom + */ + wgRedirectedFrom?: string; + /** + * The full name of the page to which content actions and navigation links (e.g. a skin's tabs) apply. The AJAX watch function uses this to work correctly on special pages such as Special:MovePage and Special:WhatLinksHere. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgRelevantPageName + */ wgRelevantPageName: string; - wgRelevantUserName: string; + /** + * The relevant name of the user to which content actions and some extra navigation links (e.g. link to user rights or user contributions) apply. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgRelevantUserName + */ + wgRelevantUserName?: string; + /** + * Like wgIsProbablyEditable, but applied to the contextually relevant page name from wgRelevantPageName instead of strictly the current page being viewed. For example, when viewing a page "Special:MovePage/Example" this will indicate whether the subject page is editable. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgRelevantPageIsProbablyEditable + */ wgRelevantPageIsProbablyEditable: boolean; - wgRestrictionEdit: string[]; + /** + * If the page is editable at all (and is not a special page) and editing of the page is restricted to some user groups, the array contains the minimum user group a user must be in in order to edit the page. For semi-protected pages, it'd contain ["autoconfirmed"]; for fully protected pages ["sysop"]. If there are no explicit restrictions, the value is [] (an array with no elements). + * + * This array contains only explicit protections. Namespace-wide protections (e.g. MediaWiki namespace, $wgNamespaceProtection), cascading protections, or "protections" brought about by the TitleBlacklist extension's "noedit" attribute, are ignored by this array. On such pages, the value is normally [], unless additional protections have been applied specifically to that page. + * + * If the page does not exist, the variable is not set. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgRestrictionEdit + */ + wgRestrictionEdit?: string[]; + /** + * If the page is movable at all (and is not a special page) and moving of the page is restricted to some user groups, the array contains the minimum user group a user must be in in order to move the page. For semi-moveprotected pages, it'd contain ["autoconfirmed"]; for fully moveprotected pages ["sysop"]. If there are no explicit restrictions, the value is [] (an array with no elements). + * + * This array contains only explicit protections. Namespace-wide protections (e.g. MediaWiki namespace, $wgNamespaceProtection), cascading protections, or "protections" brought about by the TitleBlacklist extension's "moveonly" attribute, are ignored by this array. On such pages, the value is normally [], unless additional protections have been applied specifically to that page. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgRestrictionMove + */ wgRestrictionMove: string[]; + /** + * The revision ID of the currently viewed revision, or the right revision for diff views (But 0 when diffonly=yes, task T231744). Also set on diff pages; zero for special pages, history pages, or anywhere else inapplicable. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgRevisionId + */ wgRevisionId: number; - wgSearchType: string; + /** + * The name of the search backend used to execute search requests. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgSearchType + */ + wgSearchType: string | null; + /** + * The page title, without the namespace. May contain spaces – does not contain underscores. To get the title including the namespace, use wgPageName. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgTitle + */ wgTitle: string; - wgUserEditCount: number; - wgUserGroups: string[]; - wgUserId: number; + /** + * The number of edits the current user made (null if not logged in). + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgUserEditCount + */ + wgUserEditCount?: number; + /** + * An array containing all the (local) user groups the current user is a member of, or null for non-logged-in users. User groups are identified by the internal user group names, e.g. "sysop", "autoconfirmed", "bureaucrat", and so on. The default user group is named "*". + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgUserGroups + */ + wgUserGroups: string[] | null; + /** + * The numeric ID of the current user (null if not logged in). + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgUserId + */ + wgUserId?: number; + /** + * The language code for the user's interface language, as set in Special→Preferences (which may be overridden by a uselang= parameter in the URL). + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgUserLanguage + */ wgUserLanguage: string; - wgUserName: string; - wgUserRegistration: number; - wgIsMainPage: boolean; - wgUserVariant: string; - wgPostEdit: string; - wgDiffOldId: number | false; - wgDiffNewId: number; - wgWikibaseItemId: string; - wgUrlProtocols: string; - [key: string]: unknown; // more config keys can be added by extensions + /** + * The user name of the user currently viewing the page, if it's a logged-in user. For non-logged-in users, it is null (not the user's IP address, unlike PHP $wgUser->getName() on the server). + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgUserName + */ + wgUserName: string | null; + /** + * The time and date on which the current user registered, represented as milliseconds since epoch. Null if not logged in. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgUserRegistration + */ + wgUserRegistration?: number; + /** + * true if the current page is the main page of the wiki. Omitted entirely otherwise (defaulting to null in mw.config). + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgIsMainPage + */ + wgIsMainPage?: true; + /** + * If the wiki has language variants, the language code of the user's preferred variant. If the wiki does not have variants, the variable is not configured (does not exist), i.e.: + * + * ```js + * mw.config.exists( 'wgUserVariant' ); // false + * mw.config.get( 'wgUserVariant' ); // null. + * ``` + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgUserVariant + */ + wgUserVariant?: string; + /** + * "saved" if the user just saved this page. "created" if the user just created this page. "restored" if the user just restored this page by going to the history page, clicked on a timestamp link for an old revision, clicked on edit and then saved. null otherwise. Note that: + * + * On null edits, this is null, not "saved" + * + * When using "undo", this is "saved" + * + * On rollback, this is null + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgPostEdit + */ + wgPostEdit?: "created" | "restored" | "saved"; + /** + * Revision ID of the "old" revision when viewing a diff. Only available when viewing a revision comparison. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgDiffOldId + */ + wgDiffOldId?: number; + /** + * Revision ID of the "new" revision when viewing a diff. Only available when viewing a revision comparison. + * + * @see https://www.mediawiki.org/wiki/Manual:Interface/JavaScript#wgDiffNewId + */ + wgDiffNewId?: number; }>; } } +interface PageParseReport { + cachereport: CacheReport; + limitreport: LimitReport; +} + +interface CacheReport { + timestamp: `${number}`; + transientcontent: boolean; + ttl: number; +} + +interface LimitReport { + "cputime": `${number}`; + "expansiondepth": LimitReportValue; + "expensivefunctioncount": LimitReportValue; + "postexpandincludesize": LimitReportValue; + "ppvisitednodes": LimitReportValue; + "templateargumentsize": LimitReportValue; + "timingprofile": string[]; + "unstrip-depth": LimitReportValue; + "unstrip-size": LimitReportValue; +} + +interface LimitReportValue { + value: number; + limit: number; +} + export {}; diff --git a/mw/cookie.d.ts b/mw/cookie.d.ts index 7b98476..e207505 100644 --- a/mw/cookie.d.ts +++ b/mw/cookie.d.ts @@ -8,6 +8,38 @@ declare global { * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.cookie */ namespace cookie { + /** + * Get the value of a cookie. + * + * @param {string} key The key for the cookie + * @param {string} [prefix] The prefix of the key. If undefined or null, `$wgCookiePrefix` is used + * @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( + key: string, + prefix: string | undefined | null, + defaultValue: D + ): string | D; + 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 {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( + key: string, + prefix: string | undefined | null, + defaultValue: D + ): string | D; + function getCrossSite(key: string, prefix?: string | null): string | undefined; + /** * Set or delete a cookie. * @@ -19,62 +51,33 @@ declare global { * * @param {string} key * @param {string | null} value Value of cookie. If `value` is `null` then this method will instead remove a cookie by name of `key` - * @param {(Object | Date | number)?} options Options object, or expiry date - * @param {(Date | number | null)?} options.expires The expiry date of the cookie or lifetime in seconds. If `options.expires` is null or 0, then a session cookie is set - * @param {string?} options.prefix The prefix of the key - * @param {string?} options.domain The domain attribute of the cookie - * @param {string?} options.path The path attribute of the cookie - * @param {boolean?} options.secure Whether or not to include the secure attribute (Does **not** use the wgCookieSecure configuration variable) - * @param {string?} options.sameSite The `SameSite` flag of the cookie (case-insensitive; default is to omit the flag, which results in `Lax` on modern browsers). Set to `None` *and* set `secure` to `true` if the cookie needs to be visible on cross-domain requests - * @param {boolean?} options.sameSiteLegacy If true, `SameSite` = `None` cookies will also be sent as non-`SameSite` cookies with an "ss0-" prefix, to work around old browsers interpreting the standard differently - * @returns {void} + * @param {Object | Date | number} [options] Options object, or expiry date + * @param {Date | number | null} [options.expires] The expiry date of the cookie or lifetime in seconds. If `options.expires` is null or 0, then a session cookie is set + * @param {string} [options.prefix] The prefix of the key + * @param {string} [options.domain] The domain attribute of the cookie + * @param {string} [options.path] The path attribute of the cookie + * @param {boolean} [options.secure] Whether or not to include the secure attribute (Does **not** use the wgCookieSecure configuration variable) + * @param {string} [options.sameSite] The `SameSite` flag of the cookie (case-insensitive; default is to omit the flag, which results in `Lax` on modern browsers). Set to `None` *and* set `secure` to `true` if the cookie needs to be visible on cross-domain requests + * @param {boolean} [options.sameSiteLegacy] If true, `SameSite` = `None` cookies will also be sent as non-`SameSite` cookies with an "ss0-" prefix, to work around old browsers interpreting the standard differently + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.cookie-method-set */ // see https://stackoverflow.com/a/64932909 for function set( key: string, - value: any, + value: string | null, options?: | Date | number | Partial<{ - expires: Date | number; - prefix: string; domain: string; + expires: Date | number | null; path: string; - secure: boolean; + prefix: string; sameSite: Lowercase extends SameSite ? SS : SameSite; + sameSiteLegacy: boolean; + secure: boolean; }> ): void; - - /** - * Get the value of a cookie. - * - * @param {string} key The key for the cookie - * @param {string?} prefix The prefix of the key. If undefined or null, `$wgCookiePrefix` is used - * @param {*} defaultValue A value to return if the cookie does not exist - * @returns {*} If the cookie exists, the value of the cookie, otherwise `defaultValue` - */ - function get( - key: string, - prefix: string | undefined | null, - defaultValue: D - ): string | D; - function get(key: string, prefix?: string): string; - - /** - * 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 {*} defaultValue A value to return if the cookie does not exist - * @returns {*} If the cookie exists, the value of the cookie, otherwise `defaultValue` - */ - function getCrossSite( - key: string, - prefix: string | undefined | null, - defaultValue: D - ): string | D; - function getCrossSite(key: string, prefix?: string): string; } } } diff --git a/mw/experiments.d.ts b/mw/experiments.d.ts index 09a96e3..2d09da8 100644 --- a/mw/experiments.d.ts +++ b/mw/experiments.d.ts @@ -18,7 +18,7 @@ declare global { /** * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.experiments */ - namespace experiment { + namespace experiments { /** * Gets the bucket for the experiment given the token. * @@ -26,30 +26,33 @@ declare global { * to a number which is then used to get a bucket. * * @example + * ```js * // 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 - * } + * name: 'My first experiment', + * enabled: true, + * buckets: { + * control: 0.5 + * A: 0.25, + * B: 0.25 + * } * } + * ``` * - * @param {Object} experiment + * @param {Experiment} 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 + * @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 + * @returns {string|undefined} The bucket + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.experiments-method-getBucket */ function getBucket(experiment: Experiment, token: string): string | undefined; } diff --git a/mw/global.d.ts b/mw/global.d.ts index 4c20dc8..f4d3f94 100644 --- a/mw/global.d.ts +++ b/mw/global.d.ts @@ -9,11 +9,10 @@ declare global { * Schedule a function to run once the page is ready (DOM loaded). * * @since 1.5.8 - * @member global * @param {Function} fn * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/global-method-addOnloadHook */ - function addOnloadHook(fn: (...args: any[]) => any): void; + function addOnloadHook(fn: () => void): void; /** * Import a local JS content page, for use by user scripts and site-wide scripts. @@ -22,19 +21,16 @@ declare global { * be loaded and executed once. * * @since 1.12.2 - * @member global * @param {string} title - * @return {HTMLScriptElement|null} Script tag, or null if it was already imported before + * @returns {HTMLScriptElement|null} Script tag, or null if it was already imported before * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/global-method-importScript */ function importScript(title: string): HTMLScriptElement | null; /** * @since 1.12.2 - * @method importScriptURI - * @member global * @param {string} url - * @return {HTMLScriptElement|null} Script tag, or null if it was already imported before + * @returns {HTMLScriptElement|null} Script tag, or null if it was already imported before * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/global-method-importScriptURI */ function importScriptURI(url: string): HTMLScriptElement | null; @@ -43,22 +39,20 @@ declare global { * Import a local CSS content page, for use by user scripts and site-wide scripts. * * @since 1.12.2 - * @member global * @param {string} title - * @return {HTMLLinkElement} Link tag + * @returns {HTMLLinkElement} Link tag * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/global-method-importStylesheet */ - function importStylesheet(title: string): HTMLLinkElement | null; + function importStylesheet(title: string): HTMLLinkElement; /** * @since 1.12.2 - * @member global * @param {string} url * @param {string} media - * @return {HTMLLinkElement} Link tag + * @returns {HTMLLinkElement} Link tag * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/global-method-importStylesheetURI */ - function importStylesheetURI(url: string, media: string): HTMLLinkElement | null; + function importStylesheetURI(url: string, media: string): HTMLLinkElement; } export {}; diff --git a/mw/hook.d.ts b/mw/hook.d.ts index f420465..5e1e15c 100644 --- a/mw/hook.d.ts +++ b/mw/hook.d.ts @@ -17,7 +17,7 @@ import { User } from "./user"; * * Example usage: * - * ``` + * ```js * mw.hook( 'wikipage.content' ).add( fn ).remove( fn ); * mw.hook( 'wikipage.content' ).fire( $content ); * ``` @@ -33,7 +33,7 @@ import { User } from "./user"; * You can pass around the `add` and/or `fire` method to another piece of code * without it having to know the event name (or `mw.hook` for that matter). * - * ``` + * ```js * var h = mw.hook( 'bar.ready' ); * new mw.Foo( .. ).fetch( { callback: h.fire } ); * ``` @@ -48,15 +48,15 @@ interface Hook { * Register a hook handler. * * @param {...Function} handler Function to bind. - * @chainable + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.hook-method-add */ add(...handler: Array<(...data: T) => any>): this; /** * Call hook handlers with data. * - * @param {*} data - * @chainable + * @param {any} data + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.hook-method-fire */ fire(...data: T): this; @@ -64,7 +64,7 @@ interface Hook { * Unregister a hook handler. * * @param {...Function} handler Function to unbind. - * @chainable + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.hook-method-remove */ remove(...handler: Array<(...data: T) => any>): this; } @@ -140,7 +140,7 @@ declare global { * * Code that fires the postEdit hook should first set `wgRevisionId` and `wgCurRevisionId` to the revision associated with the edit that triggered the postEdit hook, then fire the postEdit hook, e.g.: * - * ``` + * ```js * mw.config.set( { * wgCurRevisionId: data.newrevid, * wgRevisionId: data.newrevid @@ -300,7 +300,8 @@ declare global { * Create an instance of mw.hook, fired when the page watch status has changed. * * Example usage: - * ``` + * + * ```js * mw.hook( 'wikipage.watchlistChange' ).add( ( isWatched, expiry, expirySelected ) => { * // Do things * } ); @@ -315,9 +316,9 @@ declare global { /** * Create an instance of mw.hook. * - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.hook + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-hook */ - function hook(name: string): Hook; + function hook(event: string): Hook; } } diff --git a/mw/html.d.ts b/mw/html.d.ts index 75ca4cd..2ec8b5c 100644 --- a/mw/html.d.ts +++ b/mw/html.d.ts @@ -1,6 +1,19 @@ declare global { namespace mw { /** + * HTML construction helper functions + * + * @example + * ```js + * var Html, output; + * + * Html = mw.html; + * output = Html.element( 'div', {}, new Html.Raw( + * Html.element( 'img', { src: '<' } ) + * ) ); + * mw.log( output ); //

+ * ``` + * * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.html */ namespace html { @@ -8,18 +21,18 @@ declare global { * Create an HTML element string, with safe escaping. * * @param {string} name The tag name. - * @param {Object} [attrs] An object with members mapping element names to values + * @param {Object.} [attrs] An object with members mapping element names to values * @param {string|Raw|null} [contents=null] The contents of the element. * * - string: Text to be escaped. * - null: The element is treated as void with short closing form, e.g. `
`. * - this.Raw: The raw value is directly included. - * @return {string} HTML + * @returns {string} HTML * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.html-method-element */ function element( name: string, - attrs?: Record, + attrs?: Record, contents?: string | Raw | null ): string; @@ -28,20 +41,20 @@ declare global { * * Converts special characters to HTML entities. * - * mw.html.escape( '< > \' & "' ); - * // Returns < > ' & " + * ```js + * mw.html.escape( '< > \' & "' ); + * // Returns < > ' & " + * ``` * * @param {string} s The string to escape - * @return {string} HTML + * @returns {string} HTML * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.html-method-escape */ function escape(s: string): string; /** - * Wrapper object for raw HTML passed to mw.html.element(). + * Wrapper object for raw HTML passed to {@link mw.html.element()}. * - * @class mw.html.Raw - * @constructor * @param {string} value * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.html.Raw-method-constructor */ diff --git a/mw/index.d.ts b/mw/index.d.ts index ffe3d7d..f7b395b 100644 --- a/mw/index.d.ts +++ b/mw/index.d.ts @@ -21,26 +21,72 @@ import "./Uri"; import "./user"; import "./util"; +type ObjectAnalyticEventData = Record; +type AnalyticEventData = ObjectAnalyticEventData | number | string | undefined; + +interface ErrorAnalyticEventData extends ObjectAnalyticEventData { + exception?: any; + module?: string; + source: string; +} + +interface AnalyticEvent { + topic: string; + data: AnalyticEventData; +} + +interface AnalyticEventCallback { + (topic: string, data: AnalyticEventData): void; +} + declare global { /** * Base library for MediaWiki. * * Exposed globally as `mw`, with `mediaWiki` as alias. + * + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw + */ + const mediaWiki: typeof mw; + + /** + * Base library for MediaWiki. + * + * Exposed globally as `mw`, with `mediaWiki` as alias. + * * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw */ namespace mw { + /** + * Empty object for third-party libraries, for cases where you don't + * want to add a new global, or the global is bad and needs containment + * or wrapping. + * + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-property-libs + */ + const libs: Record; + + /** + * OOUI widgets specific to MediaWiki + * + * types for mw.widgets are out of scope! + * + * @see https://doc.wikimedia.org/mediawiki-core/master/js/source/mediawiki.base.html#mw-property-libs + */ + const widgets: any; + /** * Format a string. Replace $1, $2 ... $N with positional arguments. * - * Used by Message#parser(). + * Used by {@link Message.parser()}. * * @since 1.25 * @param {string} formatString Format string - * @param {...Mixed} parameters Values for $N replacements - * @return {string} Formatted string + * @param {...string} parameters Values for $N replacements + * @returns {string} Formatted string * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-format */ - function format(formatString: string, ...parameters: unknown[]): string; + function format(formatString: string, ...parameters: string[]): string; /** * Get the current time, measured in milliseconds since January 1, 1970 (UTC). @@ -49,7 +95,8 @@ declare global { * 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 + * @returns {number} Current time + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-now */ function now(): number; @@ -76,14 +123,17 @@ declare global { * - * [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. + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-requestIdleCallback */ - function requestIdleCallback(callback: (...args: any[]) => any): void; + function requestIdleCallback( + callback: (...args: any[]) => any, + options?: { timeout?: number } + ): void; /** * Track an analytic event. @@ -94,51 +144,69 @@ declare global { * 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. + * Data handlers are registered via {@link mw.trackSubscribe}, and receive the full set of + * events that match their subscription, including buffered events that fired before the handler + * was subscribed. * * @param {string} topic Topic name - * @param {Object|number|string} [data] Data describing the event. + * @param {AnalyticEventData} [data] Data describing the event. + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-track */ - function track(topic: string, data?: object | number | string): void; + function track(topic: string, data?: AnalyticEventData): 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 + * @param {ErrorAnalyticEventData} data Data describing the event, encoded as an object; see {@link errorLogger.logError} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-trackError */ - function trackError(topic: string, data: object): void; + function trackError(topic: string, data: ErrorAnalyticEventData): 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. + * Handlers will be called once for each tracked event, including for any buffered events that + * fired before the handler was subscribed. The callback is passed a `topic` string, and optional + * `data` event object. The `this` value for the callback is a plain object with `topic` and + * `data` properties set to those same values. + * + * Example to monitor all topics for debugging: + * + * ```js + * mw.trackSubscribe( '', console.log ); + * ``` + * + * Example to subscribe to any of `foo.*`, e.g. both `foo.bar` and `foo.quux`: + * + * ```js + * mw.trackSubscribe( 'foo.', console.log ); + * ``` * * @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] + * @param {function(string, AnalyticEventData): void} callback Handler to call for each matching tracked event + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-trackSubscribe */ - function trackSubscribe( - topic: string, - callback: (topic: string, data: object) => any - ): void; + function trackSubscribe(topic: string, callback: AnalyticEventCallback): void; /** * Stop handling events for a particular handler * - * @param {Function} callback + * @param {function(string, AnalyticEventData): void} callback + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-method-trackUnsubscribe */ - function trackUnsubscribe(callback: (topic: string, data: object) => any): void; + function trackUnsubscribe(callback: AnalyticEventCallback): void; - // types for mw.widgets are out of scope! - const widgets: any; + /** + * List of all analytic events emitted so far. + * + * Exposed only for use by mediawiki.base. + * + * @private + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw-property-trackQueue + */ + const trackQueue: AnalyticEvent[]; } } diff --git a/mw/language.d.ts b/mw/language.d.ts index 44568e2..26784c6 100644 --- a/mw/language.d.ts +++ b/mw/language.d.ts @@ -4,12 +4,10 @@ declare global { * Base language object with methods related to language support, attempting to mirror some of the * functionality of the Language class in MediaWiki: * - * - storing and retrieving language data - * - transforming message syntax (`{{PLURAL:}}`, `{{GRAMMAR:}}`, `{{GENDER:}}`) - * - formatting numbers + * - storing and retrieving language data + * - transforming message syntax (`{{PLURAL:}}`, `{{GRAMMAR:}}`, `{{GENDER:}}`) + * - formatting numbers * - * @class - * @singleton * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language */ namespace language { @@ -20,57 +18,42 @@ declare global { * * To set data: * - * // Override, extend or create the language data object of 'nl' - * mw.language.setData( 'nl', 'myKey', 'My value' ); + * ```js + * // Override, extend or create the language data object of 'nl' + * mw.language.setData( 'nl', 'myKey', 'My value' ); * - * // Set multiple key/values pairs at once - * mw.language.setData( 'nl', { foo: 'X', bar: 'Y' } ); + * // Set multiple key/values pairs at once + * mw.language.setData( 'nl', { foo: 'X', bar: 'Y' } ); + * ``` * * To get GrammarForms data for language 'nl': * - * var grammarForms = mw.language.getData( 'nl', 'grammarForms' ); + * ```js + * var grammarForms = mw.language.getData( 'nl', 'grammarForms' ); + * ``` * * Possible data keys: * - * - `digitTransformTable` - * - `separatorTransformTable` - * - `minimumGroupingDigits` - * - `grammarForms` - * - `pluralRules` - * - `digitGroupingPattern` - * - `fallbackLanguages` - * - `bcp47Map` - * - `languageNames` + * - `digitTransformTable` + * - `separatorTransformTable` + * - `minimumGroupingDigits` + * - `grammarForms` + * - `pluralRules` + * - `digitGroupingPattern` + * - `fallbackLanguages` + * - `bcp47Map` + * - `languageNames` * - * @property {Object} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-property-data */ - const data: Record; - - /** - * Information about month names in current UI language. - * - * Object keys: - * - * - `names`: array of month names (in nominative case in languages which have the distinction), - * zero-indexed - * - `genitive`: array of month names in genitive case, zero-indexed - * - `abbrev`: array of three-letter-long abbreviated month names, zero-indexed - * - `keys`: object with three keys like the above, containing zero-indexed arrays of message keys - * for appropriate messages which can be passed to mw.msg. - * - * @property {Object} - * @member mw.language - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-property-months - */ - const months: Record; + const data: Record; /** * Formats language tags according the BCP 47 standard. * See LanguageCode::bcp47 for the PHP implementation. * * @param {string} languageTag Well-formed language tag - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-bcp47 */ function bcp47(languageTag: string): string; @@ -84,47 +67,38 @@ declare global { * * @param {string} word * @param {string} form - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-convertGrammar */ function convertGrammar(word: string, form: string): string; /** - * Converts a number using #getDigitTransformTable. + * Converts a number using {@link getDigitTransformTable}. * * @param {number} num Value to be converted * @param {boolean} [integer=false] Whether to convert the return value to an integer - * @return {number|string} Formatted number + * @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; /** * Plural form transformations, needed for some languages. * * @param {number} count Non-localized quantifier - * @param {Array} forms List of plural forms - * @param {Object} [explicitPluralForms] List of explicit plural forms - * @return {string} Correct form for quantifier in this language + * @param {string[]} forms List of plural forms + * @param {Object.} [explicitPluralForms] List of explicit plural forms + * @returns {string} Correct form for quantifier in this language * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-convertPlural */ function convertPlural( count: number, forms: string[], - explicitPluralForms?: Record + explicitPluralForms?: Record ): string; - /** - * Helper function to flip transformation tables. - * - * @param {...Object} Transformation tables - * @return {Object} - * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-flipTransform - */ - function flipTransform( - ...Transformation: Array> - ): Record; - /** * Provides an alternative text depending on specified gender. * @@ -134,11 +108,12 @@ declare global { * These details may be overridden per language. * * @param {string} gender 'male', 'female', or anything else for neutral. - * @param {Array} forms List of gender forms - * @return {string} + * @param {string[]} forms List of gender forms + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-gender */ - function gender(gender: string, forms: string[]): string; + function gender(gender: string, forms: [T, T?, T?]): T; + function gender(gender: string, forms: [T?, T?, T?]): T | ""; /** * Convenience method for retrieving language data. @@ -148,7 +123,7 @@ declare global { * * @param {string} langCode * @param {string} dataKey - * @return {any} 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 */ @@ -157,15 +132,15 @@ declare global { /** * Get the digit transform table for current UI language. * - * @return {Object|Array} + * @returns {Object.|string[]} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-getDigitTransformTable */ - function getDigitTransformTable(): any; + function getDigitTransformTable(): string[] | Record; /** * Get the language fallback chain for current UI language, including the language itself. * - * @return {string[]} List of language keys, e.g. `['pfl', de', 'en']` + * @returns {string[]} List of language keys, e.g. `['pfl', de', 'en']` * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-getFallbackLanguageChain */ function getFallbackLanguageChain(): string[]; @@ -173,7 +148,7 @@ declare global { /** * Get the language fallback chain for current UI language (not including the language itself). * - * @return {string[]} List of language keys, e.g. `['de', 'en']` + * @returns {string[]} List of language keys, e.g. `['de', 'en']` * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-getFallbackLanguages */ function getFallbackLanguages(): string[]; @@ -181,10 +156,10 @@ declare global { /** * Get the separator transform table for current UI language. * - * @return {Object|Array} + * @returns {Object.|string[]} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-getSeparatorTransformTable */ - function getSeparatorTransformTable(): any; + function getSeparatorTransformTable(): string[] | Record; /** * Turn a list of string into a simple list using commas and 'and'. @@ -192,7 +167,7 @@ declare global { * See Language::listToText in languages/Language.php * * @param {string[]} list - * @return {string} + * @returns {string} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-method-listToText */ function listToText(list: string[]): string; @@ -203,72 +178,56 @@ declare global { * Creates the data mw.Map if there isn't one for the specified language already. * * @param {string} langCode - * @param {string|Object} dataKey Key or object of key/values + * @param {string|Object.} dataKey Key or object of key/values * @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: any, value?: any): void; - - /** - * Apply numeric pattern to absolute value using options. Gives no - * consideration to local customs. - * - * Adapted from dojo/number library with thanks - * - * - * @private - * @param {number} value the number to be formatted, ignores sign - * @param {string} pattern the number portion of a pattern (e.g. `#,##0.00`) - * @param {Object} [options] If provided, all option keys must be present: - * @param {string} options.decimal The decimal separator. Defaults to: `'.'`. - * @param {string} options.group The group separator. Defaults to: `','`. - * @param {number|null} options.minimumGroupingDigits - * @return {string} - */ - function commafyNumber( - value: number, - pattern: string, - options?: { decimal: string; group: string; minimumGroupingDigits: number | null } - ): string; - - /** - * Pad a string to guarantee that it is at least `size` length by - * filling with the character `ch` at either the start or end of the - * string. Pads at the start, by default. - * - * Example: Fill the string to length 10 with '+' characters on the right. - * - * pad( 'blah', 10, '+', true ); // => 'blah++++++' - * - * @private - * @param {string} text The string to pad - * @param {number} size The length to pad to - * @param {string} [ch='0'] Character to pad with - * @param {boolean} [end=false] Adds padding at the end if true, otherwise pads at start - * @return {string} - */ - function pad(text: string, size: number, ch?: string, end?: boolean): string; + function setData(langCode: string, dataKey: string, value: any): void; + function setData(langCode: string, dataKey: Record): void; /** * Pads an array to a specific length by copying the last one element. * * @private - * @param {Array} forms Number of forms given to convertPlural + * @param {string[]} forms Number of forms given to convertPlural * @param {number} count Number of forms required - * @return {Array} Padded array of forms + * @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[]]; /** - * Replicate a string 'n' times. + * Information about month names in current UI language. * - * @private - * @param {string} str The string to replicate - * @param {number} num Number of times to replicate the string - * @return {string} + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.language-property-months */ - function replicate(str: string, num: number): string; + namespace months { + /** + * Array of month names (in nominative case in languages which have the distinction), + * zero-indexed. + */ + const abbrev: string[]; + + /** + * Object containing zero-indexed arrays of message keys for appropriate messages + * which can be passed to {@link mw.msg}. + */ + const keys: Record<"abbrev" | "genitive" | "names", string[]>; + + /** + * Array of month names in genitive case, zero-indexed. + */ + const genitive: string[]; + + /** + * Array of month names (in nominative case in languages which have the distinction), + * zero-indexed. + */ + const names: string[]; + } } } } diff --git a/mw/loader.d.ts b/mw/loader.d.ts index 9b48087..177c2ff 100644 --- a/mw/loader.d.ts +++ b/mw/loader.d.ts @@ -1,3 +1,71 @@ +interface Module { + exports: any; +} + +type ModuleKey = `${string}@${string}`; +type ModuleState = + | "error" + | "executing" + | "loaded" + | "loading" + | "missing" + | "ready" + | "registered"; +type ModuleMessages = Record; +type ModuleStyle = Record; +type ModuleTemplates = Record; + +interface ModuleDeclarator { + (): [ + module: string, + script?: ModuleScript | null, + style?: ModuleStyle | null, + messages?: ModuleMessages | null, + templates?: ModuleTemplates | null, + deprecationWarning?: string | null + ]; +} + +interface ModuleRequire { + /** + * Get the exported value of a module. + * + * @param moduleName Module name + * @returns Exported value + */ + (moduleName: string): any; +} + +type ModuleScript = + | string[] + | (($: JQuery, jQuery: JQuery, require: ModuleRequire, module: Module) => void) + | { + files: { [key: string]: any }; + main: string; + } + | string; + +interface ModuleRegistryEntry { + declarator?: ModuleDeclarator | null; + dependencies: string[]; + deprecationWarning?: string | null; + group: number | null; + messages?: ModuleMessages | null; + module: Module; + packageExports: any; + skip: string | null; + source: string; + state: "error" | "loaded" | "missing" | "registered" | "ready"; + version: string; +} + +interface ResourceLoaderStoreStats { + expired: number; + failed: number; + hits: number; + misses: number; +} + declare global { namespace mw { /** @@ -10,8 +78,6 @@ declare global { * For more information, refer to * * - * @class mw.loader - * @singleton * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader */ namespace loader { @@ -21,7 +87,7 @@ declare global { * @param {string} text CSS text * @param {Node|null} [nextNode] The element where the style tag * should be inserted before - * @return {HTMLStyleElement} Reference to the created style element + * @returns {HTMLStyleElement} Reference to the created style element * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader-method-addStyleTag */ function addStyleTag(text: string, nextNode?: Node | null): HTMLStyleElement; @@ -29,8 +95,7 @@ declare global { /** * Get the names of all registered ResourceLoader modules. * - * @member mw.loader - * @return {string[]} + * @returns {string[]} * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader-method-getModuleNames */ function getModuleNames(): string[]; @@ -40,20 +105,21 @@ declare global { * * Example: * - * mw.loader.getScript( - * 'https://example.org/x-1.0.0.js' - * ) - * .then( function () { - * // Script succeeded. You can use X now. - * }, function ( e ) { - * // Script failed. X is not avaiable - * mw.log.error( e.message ); // => "Failed to load script" - * } ); + * ```js + * mw.loader.getScript( + * 'https://example.org/x-1.0.0.js' + * ) + * .then( function () { + * // Script succeeded. You can use X now. + * }, function ( e ) { + * // Script failed. X is not avaiable + * mw.log.error( e.message ); // => "Failed to load script" * } ); + * } ); + * ``` * - * @member mw.loader * @param {string} url Script URL - * @return {JQuery.Promise} Resolved when the script is loaded + * @returns {JQuery.Promise} Resolved when the script is loaded * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader-method-getScript */ function getScript(url: string): JQuery.Promise; @@ -61,12 +127,102 @@ declare global { /** * Get the state of a module. * + * Possible states for the public API: + * + * - `registered`: The module is available for loading but not yet requested. + * - `loading`, `loaded`, or `executing`: The module is currently being loaded. + * - `ready`: The module was succesfully and fully loaded. + * - `error`: The module or one its dependencies has failed to load, e.g. due to + * uncaught error from the module's script files. + * - `missing`: The module was requested but is not defined according to the server. + * * @param {string} module Name of module - * @return {string|null} The state, or null if the module (or its state) is not + * @returns {string|null} The state, or null if the module (or its state) is not * in the registry. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.loader-method-getState */ - function getState(module: string): string | null; + function getState(module: string): ModuleState | null; + + /** + * Implement a module given a function which returns the components of the module + * + * @param {Function} declarator + * + * The declarator should return an array with the following keys: + * + * - 0. {string} module Name of module and current module version. Formatted + * as '`[name]@[version]`". This version should match the requested version + * (from #batchRequest and #registry). This avoids race conditions (T117587). + * + * - 1. {ModuleScript} [script] Module code. This can be a function, + * a list of URLs to load via `