This article is about usingTypeScript in the MediaWiki ecosystem. There are many excellent resources for general TypeScript usage elsewhere, some are referenced below.
The TypeScript executable,tsc, can be used to lint the documentation in plain JavaScript files.
JSDoc is the preferred way to write JavaScript documentation in MediaWiki software. TypeScript can parse and understand JSDocs. A typical type would be documented as:
/** * Template properties for a portlet. * @typedef {Object} PortletContext * @prop {string} portal-id Identifier for wrapper. * @prop {string} html-tooltip Tooltip message. * @prop {string} msg-label-id Aria identifier for label text. * @prop {string} [html-userlangattributes] Additional Element attributes. * @prop {string} msg-label Aria label text. * @prop {string} html-portal-content * @prop {string} [html-after-portal] HTML to inject after the portal. * @prop {string} [html-hook-vector-after-toolbox] Deprecated and used by the toolbox portal. */
And a function would be:
/** * @param {PortletContext} data The properties to render the portlet template with. * @return {HTMLElement} The rendered portlet. */functionwrapPortlet(data){constnode=document.createElement('div');node.setAttribute('id','mw-panel');node.innerHTML=mustache.render(portalTemplate,data);returnnode;}
The above examples on the TypeScript playground.
*.d.ts) areglobal scripts by default.imports orexports. Any types you wish to be globals must be explicitly made so. E.g:declareglobal{interfaceXY{x:number,y:number}}
requires andimports bring along their types./** @typedef {import('../../math/xy').XY} XY */.TypeScript definitions are a common means to describe and share the documentation and typing information for an entire library such asjQuery. 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:
interfacePortletContext{'portal-id':string;'html-tooltip':string;'msg-label-id':string;'html-userlangattributes'?:string;'msg-label':string;'html-portal-content':string;'html-after-portal'?:string;'html-hook-vector-after-toolbox'?:string;}declarefunctionwrapPortlet(data:PortletContext):HTMLElement;
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, TSDscannot contain implementation as they are not compiled and have no functional impact.
Note that type definitions can also supplycode completion in pure JavaScript projects in popular IDEs.
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):
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:
includes or remove files via theexcludes field. More details can be found undercompiler options.@ts-check /@ts-nocheck: add or remove entire files with a single comment.@ts-ignore: 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.{"exclude":["docs","vendor"],"compilerOptions":{"resolveJsonModule":true,"esModuleInterop":true,"strict":true,"noUnusedLocals":true,"noUnusedParameters":true,"noImplicitReturns":true,"newLine":"lf","forceConsistentCasingInFileNames":true,"pretty":true,"target":"es5","lib":["dom"],"allowJs":true,"checkJs":true,"noEmit":true}}