Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 86 insertions, 0 deletions

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/