-
Notifications
You must be signed in to change notification settings - Fork 9
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Expose all types #40
Draft
Derugon
wants to merge
12
commits into
wikimedia-gadgets:main
Choose a base branch
from
Derugon:expose
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Expose all types #40
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Only keep type renaming changes, remove all other type changes. There are more type improvements we can do easily with the API params, so these changes will instead be proposed in another PR.
some interfaces were added to the JSdoc shipped with MW 1.42, so use the "official" names if they differ from the ones used in this PR
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Expose all local types used in all declaration files, inside the
mw
namespace or nested namespaces injquery
andmw
.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 theExperiment
interface. Suppose we want to call this function with a new object that satisfies theExperiment
interface. If we create the object directly when calling the function: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 usetypeof
in some situations to get the type of already existing object properties ormw
namespace constants, but there is not always a constant or property somewhere in themw
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?).
mw
orjquery
namespaces, by using existing (or creating new) nested namespaces.@deprecate
these exports in favor of global declarations (e.g./** @deprecated */ export type X = mw.X
).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:
api_params/index.d.ts
timestamp
string
instead)expiry
string
instead)namespace
number
instead)limit
mw.Api.Limit
password
string
instead)upload
File
instead)OneOrMore
mw.TypeOrArray
instead)ApiAssert
mw.Api.Assert
ApiTokenType
mw.Api.TokenType
ApiLegacyTokenType
mw.Api.LegacyTokenType
ApiParams
mw.Api.Params
jquery/client.d.ts
Client
JQuery.Client
ClientNavigator
JQuery.Client.Navigator
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
ParserMap
JQuery.TableSorter.ParserMap
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
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
mw/Map.d.ts
TypeOrArray
mw.TypeOrArray
GetOrDefault
mw.GetOrDefault
PickOrDefault
mw.PickOrDefault
ExtensibleMap
mw.Map.Extensible
mw/notification.d.ts
Notification
mw.Notification
mw.notification.NotificationOptions
mw.notification.Options
mw/Rest.d.ts
RestResponse
mw.Rest.Response
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
TitleExistenceStore
mw.Title.ExistenceStore
UserInputOptions
mw.Title.UserInputOptions
mw/Uri.d.ts
QueryParams
mw.QueryParams
UriParser
mw.Uri.Parser
mw.Uri.UriOptions
mw.Uri.Options
mw/User.d.ts
UserTokens
mw.User.Tokens
User
mw.User
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 insidemw.Api.Params
. All changes have been done directly to theapi-types-generator.js
script. Type names are currently mostly generated asXApiYParams
, withX
the PHP concatenated PHP namespaces andY
the PHP class name. The proposed names are:mw.Api.Params.X.Y
for action parametersmw.Api.Params.Format.X.Y
for format parametersmw.Api.Params.Query.X.Y
for query, list and metadata parametersFor all types, single-class namespaces are flattened, so for example the proposed name of
AntiSpoofApiAntiSpoofParams
is onlymw.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.
export
to all local types and useexport * from X
instead ofimport X
in allindex.d.ts
files.mw
nested namespaces with types, and some basic types can be kept private (e.g.TypeOrArray<T>
,TitleLike
)import
with types in JSdocJQuery
namespace.