From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- toolkit/components/extensions/types/README.md | 86 +++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 toolkit/components/extensions/types/README.md (limited to 'toolkit/components/extensions/types/README.md') diff --git a/toolkit/components/extensions/types/README.md b/toolkit/components/extensions/types/README.md new file mode 100644 index 0000000000..ebd01dec60 --- /dev/null +++ b/toolkit/components/extensions/types/README.md @@ -0,0 +1,86 @@ +# PoC Type-Checking JavaScript Using JSDocs + +## Intro + +TypeScript can be used on plain JavaScript files documented with JSDoc comments +to check types without a build step. This is a proof of concept to show +viability and benefits of doing this for a "typical" component. + +* [Handbook: Type Checking JavaScript Files][handbook] +* [JSDoc Reference][jsdoc] + +## New files + + * `tsconfig.json`: at the root of a TypeScript "project" configures how to find + and check files. + + * `types/globals.ts`: defines available globals, types and various utilities. + + * `types/XPCShellContentUtils.sys.mts`: an example of type definitions file for + an external module which was automatically generated by `tsc`. + +## How to use and expectations + +Use [npm or yarn to install][download] TypeScript. +Then run `tsc` in the extensions directory to check types: + +``` +mozilla-central/toolkit/components/extensions $ tsc +``` + +You can also use an editor which supports the [language server][langserv]. +VSCode should pick it up automatically, but others like Vim might need +[some configuring][nvim]. + +Other than continuing to use JSDocs, trying to follow guidelines below, and +hopefully remembering to run `tsc` occasionally, for now there is explicitly +*no expectation* that all new code must be fully typed, or pass typecheck +on every commit. + +If you are in a hurry, or run into a confusing type problem, feel free to +slap a @ts-ignore and/or ask for help from someone more familiar. Hopefully +as workflow gets better integrations, we all learn some typescript along +the way, and the whole process remains non-disruptive. + +## Guidelines for type-friendly code + +Using more modern and idiomatic code patterns can enable better type inference +by the TypeScript compiler. + +These fall under 5 main categories: + + 1) Declare and/or initialize all class fields in the constructor. + * (general good practice) + + 2) Use real getters and redefineGetter instead of defineLazyGetter. + * (also keeps related code closer together) + + 3) When extending, don't override class fields with getters, or vice versa. + * https://github.com/microsoft/TypeScript/pull/33509 + + 4) Declare and assign object literals at the same time, not separately. + * (don't use `let foo;` at the top of the file, use `var foo = {`) + + 5) Don't re-use local variables unnecessarily with different types. + * (general good practice, local variables are "free") + +### @ts-ignore recommendations + +*Don't* use `@ts-ignore` for class fields and function or method signatures. + +*Feel free* to use it: + * locally inside methods, + * when the alternative is more noise than signal, + * when doing so isn't preventing passthrough of type-inference through other + parts of the codebase. + + +[handbook]: https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html + +[jsdoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html + +[download]: https://www.typescriptlang.org/download + +[langserv]: https://github.com/typescript-language-server/typescript-language-server + +[nvim]: https://www.reddit.com/r/neovim/comments/131l9cw/theres_another_typescript_lsp_that_wraps_the/ -- cgit v1.2.3