TypeScript

This article is about using TypeScript in the MediaWiki ecosystem. There are many excellent resources for general TypeScript usage elsewhere, some are referenced below.

TypeScript as a JavaScript documentation linter
The TypeScript executable,, can be used to lint the documentation in plain JavaScript files.

JSDoc typing
JSDoc is the preferred way to write JavaScript documentation in MediaWiki software (JSDuck is deprecated). TypeScript can parse and understand JSDocs. A typical type would be documented as:

And a function would be:

The above examples on the TypeScript playground.

Sharing types across files

 * Type definitions are global scripts by default.
 * Type definitions become non-global modules if the file contains any s or  s. Any types you wish to be globals must be explicitly made so. E.g:
 * s and s bring along their types.
 * Import types look like.

TypeScript definitions
TypeScript definitions are a common means to describe and share the documentation and typing information for an entire library such as jQuery. They're also useful more broadly for sharing definitions across files and globals.

An equivalent TypeScript definition (or TSD) of the above type and function (with documentation and implementation stripped) is:

The above examples on the TypeScript playground.

Documentation in TSDs are still JSDocs so it could be identical to the preceding examples (or omit the JSDoc typing). However, TSDs cannot contain implementation as they are not compiled and have no functional impact.

MediaWiki TypeScript definitions
A library exists for documenting MediaWiki core and other common libraries.

TypeScript as a compiler
TypeScript also supports more direct means to describe typing information called annotations. However, this syntax requires TypeScript proper and a compilation step. Examples include (in roughly reverse chronological order):


 * Wikidata Bridge (repository) Edit wikidata’s data directly from wikipedia
 * wikibase tainted references A part of wikibase UI for statement editing
 * wikibase-termbox A part of wikibase item/property page UI, incl. SSR capability
 * A (dated) TypeScript Preact prototype

Project setup
For projects with mixed JavaScript and TypeScript files or only plain JavaScript files, you may wish to include or exclude files until their typing is fully accurate with respect to the documentation. There are several ways to do that including:


 * tsconfig.json: add files via the includes or remove files via the excludes field. More details can be found under compiler options.
 * / : add or remove entire files with a single comment.
 * : ignore the errors on a single line. Should generally be used as a temporary fix pointing to a Phabricator ticket, as this can (and has)led to production errors.

Example JavaScript documentation configuration
Complete project example.