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

Various declarations, either functions or namespace constants may use custom types or interfaces, 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.

Firstly: 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:

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

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

the first argument is type-checked properly. But if we want to declare the experiment separately in an experiment variable, there is no easy way to specify its type directly. 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.

Secondly: Remove dependencies to nested modules of types-mediawiki, so declaration files can be merged, split and moved without affecting users. This is particularly related to proposal #35, where nested modules would match (and be used to import) ResourceLoader modules.

Proposed changes

The first change is the main one of this proposal, the next ones are optional (and to be discussed?).

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 parts, when the namespace provides the same information.
3. Use 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.

Below is an exhaustive list of proposed type changes:

File	Current type name	Proposed type name	Exported
api_params/index.d.ts	timestamp	(remove, use string instead)
	expiry	(remove, use string instead)
	namespace	(remove, use number instead)
	limit	mw.Api.Limit
	password	(remove, use string instead)
	upload	(remove, use File instead)
	OneOrMore	(remove, use mw.TypeOrArray instead)
	ApiAssert	mw.Api.Assert	X
	ApiTokenType	mw.Api.TokenType	X
	ApiLegacyTokenType	mw.Api.LegacyTokenType	X
	ApiParams	mw.Api.Params	X
jquery/client.d.ts	Client	JQuery.Client
	ClientNavigator	JQuery.Client.Navigator	X
	ClientProfileName	JQuery.Client.ProfileName
	ComparisonOperator	JQuery.Client.ComparisonOperator
	ClientSupportCondition	JQuery.Client.SupportMap.Condition
	UndirectedClientSupportMap	JQuery.Client.SupportMap.Undirected
	ClientSupportMap	JQuery.Client.SupportMap
	ClientProfile	JQuery.Client.Profile
	ClientNavigator	JQuery.ClientNavigator
jquery/collapsibleTabs.d.ts	CollapsibleTabsOptions	JQuery.CollapsibleTabs.Options
	CollapsibleTabsStatic	JQuery.CollapsibleTabs.Static
	CollapsibleTabs	JQuery.CollapsibleTabs
jquery/colorUtil.d.ts	Color	JQuery.ColorUtil.Color
	ColorUtil	JQuery.ColorUtil
jquery/confirmable.d.ts	Confirmable	JQuery.Confirmable
	Options	JQuery.Confirmable.Options
	I18N	JQuery.Confirmable.I18N
jquery/footHovzer.d.ts	FootHovzer	JQuery.FootHovzer
jquery/highlightText.d.ts	Method	JQuery.HighlightText.Method
	HighlightText	JQuery.HighlightText
	Options	JQuery.HighlightText.Options
jquery/lengthLimit.d.ts	FilterFunction	JQuery.LengthLimit.FilterFunction
	TrimResult	JQuery.LengthLimit.TrimResult
jquery/makeCollapsible.d.ts	Options	JQuery.MakeCollapsible.Options
jquery/spinner.d.ts	Size	JQuery.Spinner.Size
	Type	JQuery.Spinner.Type
	Options	JQuery.Spinner.Options
jquery/suggestions.d.ts	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
jquery/tablesorter.d.ts	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
jquery/textSelection.d.ts	TextSelectionEncapsulateOptions	JQuery.TextSelection.EncapsulateOptions
jquery/updateTooltipAccessKeys.d.ts	KeyModifier	JQuery.TooltipAccessKeys.KeyModifier
	TooltipAccessKeys	JQuery.TooltipAccessKeys
mw/Api.d.ts	TypeOrArray	mw.TypeOrUnionArray
	ReplaceValue	mw.ReplaceValue
	UnknownApiParams	mw.Api.UnknownParams
	ApiResponse	mw.Api.Response	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
	WatchStatus	mw.Api.Response.Watch
	RollbackInfo	mw.Api.Response.Rollback
	FinishUpload	mw.Api.FinishUpload
	ApiOptions	mw.Api.Options	X
mw/config.d.ts	PageParseReport	mw.PageParseReport
	CacheReport	mw.CacheReport
	LimitReport	mw.LimitReport
	LimitReportValue	mw.LimitReportValue
mw/confirmCloseWindow.d.ts	Options	mw.ConfirmCloseWindow.Options
	ConfirmCloseWindow	mw.ConfirmCloseWindow
mw/cookie.d.ts	SameSite	mw.cookie.SameSite
mw/debug.d.ts	LogEntryType	mw.Debug.LogEntryType
	Data	mw.Debug.Data
	File	mw.Debug.File
	LogEntry	mw.Debug.LogEntry
	Query	mw.Debug.Query
mw/experiments.d.ts	Experiment	mw.experiments.Experiment
mw/ForeignApi.d.ts	ForeignApiOptions	mw.ForeignApi.Options	X
mw/ForeignRest.d.ts	ForeignRestOptions	mw.ForeignRest.Options	X
mw/hook.d.ts	Hook	mw.Hook
	PostEditData	mw.PostEditData
	SearchIndex	mw.SearchIndex
	SearchIndexEntry	mw.SearchIndexEntry
	EditRecovery	mw.EditRecovery
mw/index.d.ts	ObjectAnalyticEventData	mw.AnalyticEvent.ObjectData
	AnalyticEventData	mw.AnalyticEvent.Data
	ErrorAnalyticEventData	mw.AnalyticEvent.ErrorData
	AnalyticEvent	mw.AnalyticEvent
	AnalyticEventCallback	mw.AnalyticEvent.Callback
mw/inspect.d.ts	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
mw/loader.d.ts	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.Require
	ModuleScript	mw.loader.Module.Script
	ModuleRegistryEntry	mw.loader.Module.RegistryEntry
	ResourceLoaderStoreStats	mw.loader.store.Stats	X
mw/Map.d.ts	TypeOrArray	mw.TypeOrArray
	GetOrDefault	mw.GetOrDefault
	PickOrDefault	mw.PickOrDefault
	ExtensibleMap	mw.Map.Extensible	X
mw/notification.d.ts	NotificationOptions	mw.notification.Options
	Notification	mw.Notification
mw/Rest.d.ts	RestOptions	mw.Rest.Options	X
	RestResponse	mw.Rest.Response	X
mw/searchSuggest.d.ts	ResultInfo	mw.searchSuggest.ResponseMetaData
mw/storage.d.ts	SafeStorage	mw.SafeStorage
	MwStorage	mw.SafeStorage.Local
mw/template.d.ts	CompiledTemplate	mw.template.Renderer
	Compiler	mw.template.Compiler
mw/Title.d.ts	TitleLike	mw.TitleLike	X
mw/Uri.d.ts	QueryParams	mw.QueryParams	X
	UriOptions	mw.Uri.Options
	UriParser	mw.Uri.Parser
mw/User.d.ts	UserInfo	mw.Api.UserInfo	X
	UserTokens	mw.User.Tokens
	User	mw.User	X
mw/util.d.ts	NoReturn	mw.NoReturn
	ImageUrlData	mw.util.ResizeableThumbnailUrl

Note on api_params

In this proposal types within api_params/index.d.ts are also all exposed inside mw.Api.Params. All changes have been done directly to the api-types-generator.js script. Type names are currently mostly generated as XApiYParams, with X the PHP concatenated PHP namespaces and Y the PHP class name. The proposed names are:

• mw.Api.Params.X.Y for action parameters
• mw.Api.Params.Format.X.Y for format parameters
• mw.Api.Params.Query.X.Y for query, list and metadata parameters

For all types, single-class namespaces are flattened, so for example the proposed name of AntiSpoofApiAntiSpoofParams is only mw.Api.Params.AntiSpoof.

Alternatives

Below are alternative solutions, that still meet the motivations mentioned above. They are not currently implemented in this proposal, but 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>, TitleLike)
   • 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?