Testing: Add TypeScript types validation for modules

[aduth]

Previously: #17014

While Gutenberg packages are not authored in TypeScript, we can still benefit from its JavaScript type checking using the JSDoc we already write. This will bring us some benefit of type safety, even as we continue to write modules with JavaScript, not TypeScript.

Progress:

All of our modules are to be opted-in to type checking. The progress thus far:

• a11y (A11y: Add types #19096)
• annotations
• api-fetch
  • api-fetch: Add incremental type checking #29685
  • api-fetch: Type several of the middlewares #29719
  • api-fetch: Type the rest of the package #30161
• autop (Packages: Add and check types  #20669)
• babel-plugin-import-jsx-pragma
• babel-plugin-makepot
• babel-preset-default
• base-styles
• blob (Blob: Add types #19092)
• block-directory
• block-editor (Block Editor: Add type-checking for block editor (DOM utils only) #21362, ...)
• block-library
• block-serialization-default-parser
• block-serialization-spec-parser
• blocks
• browserslist-config
• components
  • Components: Start adding types progressively #26066
  • Components: Type BaseControl and VisuallyHidden #26078
  • Components: Add types to Draggable #29792
• compose (Compose: Add types #21580 Compose: Add types (progressively) #27344)
• core-data
  • Core Data: TypeScript definitions for entity records. #38666
  • TypeScript signatures for core-data selectors #39025 (merged in small chunks!)
  • [TypeScript] More specific core-data selector types #41594
• create-block
• custom-templated-path-webpack-plugin
• data
  • [data] Fill out type definition for data registry #39081
  • Autocompletion support for useSelect (via jsDoc annotations) #41596
• data-controls
• date date: Add types #29789
• dependency-extraction-webpack-plugin (Dependency Extraction Webpack Plugin: Add types #22498)
• deprecated (Deprecated: Type package #26429)
• docgen
• dom (split into multiple smaller PRs)
  • Dom: Add type-checking to data-transfer #29682
  • dom: Add types to focusable #29787
  • dom: Add types to clean-node-list #30412
  • dom: Add types to document-has-selection #30386
• dom-ready (Dom Ready: Add types #19089)
• e2e-test-utils
• e2e-tests
• edit-post
• edit-site
• edit-widgets
• editor
• element
  • first pass (Element: Add types #21248)
  • needs work after Types: Hide element, primitives, icons declarations #21613
  • use stricter types config
• env
• escape-html (Packages: Add and check types  #20669)
• eslint-plugin
• format-library
• hooks (Hooks: Type package #26430)
• html-entities (Packages: Add and check types  #20669)
• i18n (i18n: Add types #19099)
• interface
• icons (Icons: Add types #21487, Types: Hide element, primitives, icons declarations #21613, Types: Restore element, icons, primitives types #21781)
• is-shallow-equal (Is Shallow Equal: Add types #19090)
• jest-console
• jest-preset-default
• jest-puppeteer-axe
• keyboard-shortcuts
• keycodes (Keycodes: Add, enhance types #19520)
• library-export-default-webpack-plugin
• list-reusable-blocks
• media-utils
• notices
• npm-package-json-lint-config
• nux
• plugins
• postcss-themes
• prettier-config (Prettier Config: Add type-checking #21053)
• primitives (Primitives: Add types #21482, Types: Hide element, primitives, icons declarations #21613, Types: Restore element, icons, primitives types #21781)
• priority-queue (Priority Queue: Enable types with enhanced JSDoc type details #18997)
• project-management-automation (Project Management Automation: Add TypeScript type-checking #20850)
• redux-routine (Redux routine: Add types #21313)
• rich-text
• scripts
• server-side-render
• shortcode
• token-list (Token List: Add type checking #18839)
• url (chore(url): add jsdoc typescript checking #17014)
• viewport
• warning (Add warning package #19317)
• wordcount (WordCount: Add types #22077)

Guidelines:

See the packages README for details on TypeScript usage. In summary, a package can opt-in by following these steps:

• Add a tsconfig.json to the package root. The @wordpress/i18n package has a good example of a basic config.
• Add "types": "build-types" to the package's package.json so that consumers will pick up the published types from the package.
• Add the package to the root tsconfig.json references.

For single files, you can also include a // @ts-check line at the top of the file. You should use this line when temporarily testing the impact of type checking, or if you are working to convert a very large package one file at a time.

The build:package-types npm script will be run as part of precommit, which handles type checking. It can be very helpful to watch the types build and work through issues surfaced by the compiler as you add types. To watch the types build, run:

npm run build:package-types -- --watch

You may also need to improve existing JSDoc, as it was written based on assumed usage. Type checking will enforce its validity, and in many cases our JSDoc is invalid.

For syntax and usage, reference:

• https://github.com/WordPress/gutenberg/blob/master/docs/contributors/coding-guidelines.md#javascript-documentation-using-jsdoc
• https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/
• https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc
• https://jsdoc.app/

[aduth]

@dsifford Yes, definitely, I think for WordPress dependencies we should aim for what you propose.

There was some previous related discussion to this:

• Consideration for what should be part of the "public types API" of our modules: ESLint plugin: Remove temporary listed types for TypeScript validation (p. 1) #18808 (comment)
• Using TypeScript 3.7 new --declaration parameter for emitting first party types from JSDoc
  • Documentation: Outline third-party developer resources (TypeScript definitions) #15027 (comment)
  • https://andrewduthie.com/2019/11/27/typescript-tooling-for-your-javascript-projects/#comment-259

[dsifford]

Yep, that --declaration flag is a pretty big game-changer. Though, the types still won't be quite as good as those written in typescript due to limited support for generics and overloads.

[annezazu]

Closing this out as the work has either been completed or is no longer relevant. Happy to reopen if we need to but, at this point, a new issue is likely best.