Expose all types

[Derugon]

Expose all local types used in all declaration files, inside the mw namespace or nested namespaces in jquery and mw.

To review these changes, I highly suggest to hide whitespace differences, since most of the lines have whitespace differences, and diff editors seem to mostly not align anything with these on.

Context

Custom types and interfaces are used by functions or namespace constants, either to simplify declarations or for extensibility/maintenance reasons. Most of these types are not declared in the JSDoc from the MediaWiki source code, and are specific to this package, so they are implemented as local types within modules. When they need to be accessible to other nested modules of this package or to npm users, types are exported within their module.

Motivations

There are two main motivations for these changes.

1. Sub-module dependency

Remove dependencies to nested modules of types-mediawiki, so declaration files can be merged, split and moved from one file to another without affecting users.

This is related to proposal #35, where nested modules would match (and be used to import) ResourceLoader modules.

2. End-user usage

Allow to use JSDoc or TypeScript types to specify the type of variables, and not only rely on type inference.

For example, the first argument of mw.experiments.getBucket is an instance of the Experiment interface. Suppose we want to call this function with a new object that satisfies the Experiment interface. If we create the object directly when calling the function, the first argument is type-checked properly.

/** @type {Record<string, number>} */
var bucketProbs = ...;
/** @type {string} */
var token = ...;

var bucket = mw.experiments.getBucket({ name: "someExperiment", enabled: true, buckets: bucketProbs }, token);

But if we want to declare the experiment separately in an experiment variable, there is no easy way to specify its type directly.

/** @type {Record<string, number>} */
var bucketProbs = ...;
/** @type {string} */
var token = ...;

/** @type {?} */
var experiment = {
    name: "someExperiment",
    enabled: true,
    buckets: bucketProbs
};

var bucket = mw.experiments.getBucket(experiment, token);

We could use typeof in some situations to get the type of already existing object properties or mw namespace constants, but there is not always a constant or property somewhere in the mw namespace with the type we're looking for. This becomes even harder when trying to extend existing interfaces when writing custom ResourceLoader modules, since a lot of interfaces are not accessible at all.

With the type changes proposed in this PR, the previous example would be written:

/** @type {mw.experiments.Experiment} */
var experiment = {
    name: "someExperiment",
    enabled: true,
    buckets: bucketProbs
};

Proposed changes

1. Move local types (whether exported or not) to mw or jquery namespaces, by using existing (or creating new) nested namespaces.

2. Remove redundant type name prefixes/suffixes, when the namespace provides the same information.

To simplify the migration process and prevent breaking existing code:

3. Add type synonyms to keep existing exports from nested modules, and @deprecate these exports in favor of global declarations (e.g. /** @deprecated */ export type X = mw.X).

4. Set mw as default export of the root module, so import syntax can still be used if desired, such as to prevent naming conflicts with other JQuery libraries.

Alternatives

Below are alternative solutions, that still meet the motivations mentioned above, and may be preferred from the previous implementation.

1. Do not expose local types at all, and instead re-export all existing local types from the root module.
   • I.e., add export to all local types and use export * from X instead of import X in all index.d.ts files.
   • Pros: does not fill mw nested namespaces with types, and some basic types can be kept private (e.g. TypeOrArray<T>, Title.Like)
   • Cons: requires users to use import with types in JSdoc
2. Do not use nested namespaces within the JQuery namespace.
   • Some jQuery plugins on DefinitelyTyped declare nested namespaces, but a lot of plugins instead declare a separated namespace, so I'm not sure which convention should be used here.
3. Do not deprecate exports, just remove old exports.
   • Do we care for compatibility with previous package versions?

Proposed type names

Below is an exhaustive list of proposed type changes.

MediaWiki API parameters (api_params)

Types are unchanged.

Because of PHP file changes in the source code of MediaWiki 1.43 and name collision issues, migration would require more work than just changing a few lines in the type generation script, so this is left out of this proposal (see #41).

JQuery modules (jquery)

File	Current type name	Proposed type name	Exported
client	Client	JQuery.Client
	ClientNavigator	JQuery.Client.Navigator	X
	ClientProfileLayout	JQuery.Client.Profile.Layout
	ClientProfileName	JQuery.Client.Profile.Name
	ClientProfilePlatform	JQuery.Client.Profile.Platform
	ComparisonOperator	JQuery.Client.ComparisonOperator
	ClientSupportCondition	JQuery.Client.SupportMap.Condition
	UndirectedClientSupportMap	JQuery.Client.SupportMap.Undirected
	ClientSupportMap	JQuery.Client.SupportMap
	ClientProfile	JQuery.Client.Profile
collapsibleTabs	CollapsibleTabsOptions	JQuery.CollapsibleTabs.Options
	CollapsibleTabsStatic	JQuery.CollapsibleTabs.Static
	CollapsibleTabs	JQuery.CollapsibleTabs
colorUtil	Color	JQuery.ColorUtil.Color
	ColorUtil	JQuery.ColorUtil
confirmable	RequiredOrUndefined	mw.RequiredOrUndefined
	Confirmable	JQuery.Confirmable
	Options	JQuery.Confirmable.Options
	RequiredOptions	JQuery.Confirmable.RequiredOptions
	I18N	JQuery.Confirmable.I18N
footHovzer	FootHovzer	JQuery.FootHovzer
highlightText	Method	JQuery.HighlightText.Method
	HighlightText	JQuery.HighlightText
	Options	JQuery.HighlightText.Options
lengthLimit	FilterFunction	JQuery.LengthLimit.FilterFunction
	TrimResult	JQuery.LengthLimit.TrimResult
makeCollapsible	Options	JQuery.MakeCollapsible.Options
spinner	Size	JQuery.Spinner.Size
	Type	JQuery.Spinner.Type
	Options	JQuery.Spinner.Options
suggestions	Device	JQuery.Suggestions.Device
	Direction	JQuery.Suggestions.Direction
	Context	JQuery.Suggestions.Context
	Options	JQuery.Suggestions.Options
	ResultOptions	JQuery.Suggestions.Options.Result
	SpecialOptions	JQuery.Suggestions.Options.Special
	UpdateOptions	JQuery.Suggestions.Options.Update
tablesorter	ParserTypeMap	JQuery.TableSorter.ParserTypeMap	X
	ParserMap	JQuery.TableSorter.ParserMap	X
	MultiSortKey	JQuery.TableSorter.MultiSortKey
	ParserFromType	JQuery.TableSorter.ParserFromType
	ParserFromKey	JQuery.TableSorter.ParserFromKey
	Parser	JQuery.TableSorter.Parser
	TableSorter	JQuery.TableSorter
	Options	JQuery.TableSorter.Options
textSelection	TextSelectionEncapsulateOptions	JQuery.TextSelection.EncapsulateSelectionOptions
	GetCaretPositionOptions	JQuery.TextSelection.GetCaretPositionOptions
	SetSelectionOptions	JQuery.TextSelection.SetSelectionOptions
	ScrollToCaretPositionOptions	JQuery.TextSelection.ScrollToCaretPositionOptions
tipsy	StringProvider	JQuery.Tipsy.StringProvider
	MethodsOf	mw.MethodsOf
	NSDirection	JQuery.Tipsy.NSDirection
	EWDirection	JQuery.Tipsy.EWDirection
	Direction	JQuery.Tipsy.Direction
	JQueryTipsy	JQuery.Tipsy
	Options	JQuery.Tipsy.Options
	Tipsy	JQuery.Tipsy.Tipsy
updateTooltipAccessKeys	KeyModifier	JQuery.TooltipAccessKeys.KeyModifier
	TooltipAccessKeys	JQuery.TooltipAccessKeys

MediaWiki modules (mw)

File	Current type name	Proposed type name	Exported
Api	Tail	mw.Tail
	TypeOrArray	mw.TypeOrUnionArray
	ReplaceValue	mw.ReplaceValue
	UnknownApiParams	mw.Api.UnknownParams
	ApiResponse	mw.Api.UnknownResponse	X
	Revision	mw.Api.Revision
	EditResult	mw.Api.Response.Edit
	EditFailureResult	mw.Api.Response.Edit.Failure
	EditSuccessResult	mw.Api.Response.Edit.Success
	EditNoChangeResult	mw.Api.Response.Edit.NoChange
	EditChangedResult	mw.Api.Response.Edit.Changed
	AssertUser	mw.Api.AssertUser
	RollbackInfo	mw.Api.Response.Rollback
	FinishUpload	mw.Api.FinishUpload
config	PageParseReport	mw.PageParseReport
	CacheReport	mw.PageParseReport.Cache
	LimitReport	mw.PageParseReport.Limit
	LimitReportValue	mw.PageParseReport.LimitValue
confirmCloseWindow	Options	mw.ConfirmCloseWindow.Options
	ConfirmCloseWindow	mw.ConfirmCloseWindow
cookie	SameSite	mw.cookie.SameSite
	mw.cookie.CookieOptions	mw.cookie.Options
debug	LogEntryType	mw.Debug.LogEntryType
	Data	mw.Debug.Data
	File	mw.Debug.File
	LogEntry	mw.Debug.LogEntry
	Query	mw.Debug.Query
experiments	Experiment	mw.experiments.Experiment
hook	Hook	mw.Hook
	PostEditData	mw.PostEditData
	SearchIndex	mw.SearchIndex
	SearchIndexEntry	mw.SearchIndex.Entry
	EditRecovery	mw.EditRecovery
index	IdleCallbackOptions	mw.IdleCallbackOptions
	ObjectAnalyticEventData	mw.AnalyticEvent.ObjectData
	AnalyticEventData	mw.AnalyticEvent.Data
	ErrorAnalyticEventData	mw.AnalyticEvent.ErrorData
	AnalyticEvent	mw.AnalyticEvent
	AnalyticEventCallback	mw.AnalyticEvent.Callback
inspect	SelectorCounts	mw.inspect.SelectorCounts
	ResourceLoaderCSSReport	mw.inspect.ResourceLoaderReport.CSS
	ResourceLoaderSizeReport	mw.inspect.ResourceLoaderReport.Size
	ResourceLoaderStoreReport	mw.inspect.ResourceLoaderReport.Store
	ResourceLoaderTimeReport	mw.inspect.ResourceLoaderReport.Time
	ResourceLoaderTimeReport	mw.inspect.ResourceLoaderReport.Time
	ResourceLoaderReport	mw.inspect.ResourceLoaderReport
	ResourceLoaderReportMap	mw.inspect.ResourceLoaderReportMap
	Dependency	mw.inspect.Dependency
loader	Module	mw.loader.Module
	ModuleKey	mw.loader.Module.Key
	ModuleState	mw.loader.Module.State
	ModuleMessage	mw.loader.Module.Message
	ModuleStyle	mw.loader.Module.Style
	ModuleTemplates	mw.loader.Module.Templates
	ModuleDeclarator	mw.loader.Module.Declarator
	ModuleRequire	mw.loader.Module.Require
	ModuleScript	mw.loader.Module.Script
	ModuleRegistryEntry	mw.loader.Module.RegistryEntry
	JsonModuleStore	mw.loader.store.Json
	ResourceLoaderStoreStats	mw.loader.store.Stats	X
Map	TypeOrArray	mw.TypeOrArray
	GetOrDefault	mw.GetOrDefault
	PickOrDefault	mw.PickOrDefault
	ExtensibleMap	mw.Map.Extensible	X
notification	Notification	mw.notification.Notification
	mw.notification.NotificationOptions	mw.notification.Notification.Options
Rest	RestResponse	mw.Rest.Response	X
searchSuggest	ResponseFunction	mw.searchSuggest.ResponseFunction
	ResponseMetaData	mw.searchSuggest.ResponseMetaData
storage	SafeStorage	mw.SafeStorage
	MwStorage	mw.Storage
template	TemplateRenderer	mw.template.Renderer
	TemplateCompiler	mw.template.Compiler
Title	TitleLike	mw.Title.Like	X
	TitleExistenceStore	mw.Title.ExistenceStore
	UserInputOptions	mw.Title.UserInputOptions
Uri	QueryParams	mw.QueryParams	X
	UriParser	mw.Uri.Parser
	mw.Uri.UriOptions	mw.Uri.Options
User	UserTokens	mw.user.Tokens
	User	mw.user.User	X
util	NoReturn	mw.NoReturn
	ResizeableThumbnailUrl	mw.util.ResizeableThumbnailUrl