types-mediawiki Expose all types

Expose all types

Open Derugon opened this issue 11 months ago • 0 comments

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?).

Move local types (whether exported or not) to mw or jquery namespaces, by using existing (or creating new) nested namespaces.
Remove redundant type name parts, when the namespace provides the same information.
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).
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`	`RequiredOrUndefined`	`mw.RequiredOrUndefined`
	`Confirmable`	`JQuery.Confirmable`
	`Options`	`JQuery.Confirmable.Options`
	`RequiredOptions`	`JQuery.Confirmable.RequiredOptions`
	`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.EncapsulateSelectionOptions`
	`GetCaretPositionOptions`	`JQuery.TextSelection.GetCaretPositionOptions`
	`SetSelectionOptions`	`JQuery.TextSelection.SetSelectionOptions`
	`ScrollToCaretPositionOptions`	`JQuery.TextSelection.ScrollToCaretPositionOptions`
`jquery/tipsy.d.ts`	`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`
`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`
	`RollbackInfo`	`mw.Api.Response.Rollback`
	`FinishUpload`	`mw.Api.FinishUpload`
`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/hook.d.ts`	`Hook`	`mw.Hook`
	`PostEditData`	`mw.PostEditData`
	`SearchIndex`	`mw.SearchIndex`
	`SearchIndexEntry`	`mw.SearchIndexEntry`
	`EditRecovery`	`mw.EditRecovery`
`mw/index.d.ts`	`IdleCallbackOptions`	`mw.IdleCallbackOptions`
	`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.Module.Require`
	`ModuleScript`	`mw.loader.Module.Script`
	`ModuleRegistryEntry`	`mw.loader.Module.RegistryEntry`
	`JsonModuleStore`	`mw.loader.store.Json`
	`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`	`Notification`	`mw.Notification`
	`mw.notification.NotificationOptions`	`mw.notification.Options`
`mw/Rest.d.ts`	`RestResponse`	`mw.Rest.Response`	X
`mw/searchSuggest.d.ts`	`ResponseFunction`	`mw.searchSuggest.ResponseFunction`
	`ResponseMetaData`	`mw.searchSuggest.ResponseMetaData`
`mw/storage.d.ts`	`SafeStorage`	`mw.SafeStorage`
	`MwStorage`	`mw.Storage`
`mw/template.d.ts`	`TemplateRenderer`	`mw.template.Renderer`
	`TemplateCompiler`	`mw.template.Compiler`
`mw/Title.d.ts`	`TitleLike`	`mw.TitleLike`	X
	`TitleExistenceStore`	`mw.Title.ExistenceStore`
	`UserInputOptions`	`mw.Title.UserInputOptions`
`mw/Uri.d.ts`	`QueryParams`	`mw.QueryParams`	X
	`UriParser`	`mw.Uri.Parser`
	`mw.Uri.UriOptions`	`mw.Uri.Options`
`mw/User.d.ts`	`UserTokens`	`mw.User.Tokens`
	`User`	`mw.User`	X
`mw/util.d.ts`	`NoReturn`	`mw.NoReturn`
	`ResizeableThumbnailUrl`	`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.

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
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.
Do not deprecate exports, just remove old exports.
- Do we care for compatibility with previous package versions?

Mar 15 '24 17:03 Derugon

types-mediawiki types-mediawiki copied to clipboard

Expose all types

Context

Motivations

Proposed changes

Note on api_params

Alternatives

types-mediawiki
types-mediawiki copied to clipboard

Note on `api_params`