From 5ab69c3166a051e2d5d4532342bcddcaabbb3abe Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 28 Jul 2022 14:02:56 -0400 Subject: [PATCH 01/16] doc: add TypeScript execution requirements Add section with high level approach/requirements for enabling TypeScript execution as discussed in the Next-10 [TypeScript mini-summit](https://github.com/nodejs/next-10/pull/150) Signed-off-by: Michael Dawson --- .../maintaining-types-for-nodejs.md | 50 ++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 777405aa93f4cc..e4e53641d16733 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -6,7 +6,7 @@ code of their JavaScript projects. While many people don't annotate their code, or make use of annotations at all, there are enough who do that the project has agreed it's important to work towards having [suitable types for end-users][]. -## High level approach +## High level approach - maintaining types There are a number of ways that types could be maintained for Node.js ranging from shipping them with the Node.js runtime to having them be externally @@ -28,6 +28,54 @@ The agreement was that the ideal flow would be as follows: * Automation within external type projects consumes the JSON and automatically generates a PR to add the API. +## High level approach - development workflow + +The number of people using TypeScript with Node.js is significant enough +that providing a good developer experience is important. While TypeScript +is identified specifically, a secondary goal is that what we provide to improve +development experience with TypeScrtipt would apply to other type +systems as well. + +We have agreed that the approach will `NOT` include bundling TypeScript +tools with Node.js but instead improve the developer experience for how +those tools are installed/configured to work with Node.js. + +The high level developer experience we are working towards was captured in the +[next-10 TypeScript mini-summit](https://github.com/nodejs/next-10/pull/150) +and is as follows: + +1. Users can ask Node.js to execute a file which is not one of the types it + can execute by default (.js, .mjs, etc.). For example `node script.ts`. +2. On startup Node.js will look for a config which is in the scope of the + file being executed. +3. If no config is found, Node.js will echo either: + * If the file was a TypeScript file, a TypeScript specific message with a + reference to a link on Nodejs.org on how to install required components + for TypeScript and how to add the associated config. + * If the file was not a TypeScript file, a generic message +4. If a config is found, Node.js will extract the Node.js options for + that config and apply them as if they had been provided on the command + line. +5. Assuming the options associated with the config add support for the + type of file being loaded, Node.js will execute the file as if it was one + of the file types it can execute by default. + +Some additional specifics around the current thinking include: + +* loaders already provide a number of the components needed to + satisfy the requirements above. They already provide the Node.js + options that are needed to achieve many of the requirements above. +* package.json as the location for the config is potentially a good + choice as Node.js already looks for it as part of startup. +* The implementation chosen should allow for difference configuration in + for different enronments/conditions like prod,dev, etc. +* We don't have consensus on provding an opinionated default but + that should be explored after the initial steps are complete. +* It will be important that as part of the messaging around this + functionality that we avoid confusion that could lead people to ship + TypeScript files (ex `script.ts`) instead of the processed files + (ex `script.js`). + ## Generation/Consumption of machine readable JSON files When you run `make doc` the canonical markdown files used to From 6e7315e15ed985efa11eb3a1d0018aeacf718349 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:51:02 -0400 Subject: [PATCH 02/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Mohammed Keyvanzadeh --- doc/contributing/maintaining-types-for-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index e4e53641d16733..e26daf505672cb 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -33,7 +33,7 @@ The agreement was that the ideal flow would be as follows: The number of people using TypeScript with Node.js is significant enough that providing a good developer experience is important. While TypeScript is identified specifically, a secondary goal is that what we provide to improve -development experience with TypeScrtipt would apply to other type +development experience with TypeScript would apply to other type systems as well. We have agreed that the approach will `NOT` include bundling TypeScript From 67ecbfa3fec79f8712d2a467cd77125878eb9ed8 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:51:11 -0400 Subject: [PATCH 03/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Mohammed Keyvanzadeh --- doc/contributing/maintaining-types-for-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index e26daf505672cb..303c55497d6667 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -46,7 +46,7 @@ and is as follows: 1. Users can ask Node.js to execute a file which is not one of the types it can execute by default (.js, .mjs, etc.). For example `node script.ts`. -2. On startup Node.js will look for a config which is in the scope of the +2. On startup, Node.js will look for a config which is in the scope of the file being executed. 3. If no config is found, Node.js will echo either: * If the file was a TypeScript file, a TypeScript specific message with a From 8e21b27051105237f1c18208a662b7ce3cdb0827 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:51:18 -0400 Subject: [PATCH 04/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Mohammed Keyvanzadeh --- doc/contributing/maintaining-types-for-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 303c55497d6667..30e588b2b19450 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -52,7 +52,7 @@ and is as follows: * If the file was a TypeScript file, a TypeScript specific message with a reference to a link on Nodejs.org on how to install required components for TypeScript and how to add the associated config. - * If the file was not a TypeScript file, a generic message + * If the file was not a TypeScript file, a generic message. 4. If a config is found, Node.js will extract the Node.js options for that config and apply them as if they had been provided on the command line. From 53831d99eae49d1757a96d590957bb5e5bea1163 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:51:23 -0400 Subject: [PATCH 05/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Mohammed Keyvanzadeh --- doc/contributing/maintaining-types-for-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 30e588b2b19450..88cec6a81325d8 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -60,7 +60,7 @@ and is as follows: type of file being loaded, Node.js will execute the file as if it was one of the file types it can execute by default. -Some additional specifics around the current thinking include: +Some additional specifics around the current approach include: * loaders already provide a number of the components needed to satisfy the requirements above. They already provide the Node.js From 51d95c5eeeded308701e1550d1983be4a6bab75d Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:51:29 -0400 Subject: [PATCH 06/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Mohammed Keyvanzadeh --- doc/contributing/maintaining-types-for-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 88cec6a81325d8..d19c89a0b31a02 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -62,7 +62,7 @@ and is as follows: Some additional specifics around the current approach include: -* loaders already provide a number of the components needed to +* Loaders already provide a number of the components needed to satisfy the requirements above. They already provide the Node.js options that are needed to achieve many of the requirements above. * package.json as the location for the config is potentially a good From 19caa9cc8d94e9e8f0b37584a205c6d7da8fc76f Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:51:35 -0400 Subject: [PATCH 07/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Mohammed Keyvanzadeh --- doc/contributing/maintaining-types-for-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index d19c89a0b31a02..2e7e300f04c53b 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -65,7 +65,7 @@ Some additional specifics around the current approach include: * Loaders already provide a number of the components needed to satisfy the requirements above. They already provide the Node.js options that are needed to achieve many of the requirements above. -* package.json as the location for the config is potentially a good +* `package.json` as the location for the config is potentially a good choice as Node.js already looks for it as part of startup. * The implementation chosen should allow for difference configuration in for different enronments/conditions like prod,dev, etc. From f7159b414d842a7ef61671546f6ce71c639727e7 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:51:45 -0400 Subject: [PATCH 08/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Mohammed Keyvanzadeh --- doc/contributing/maintaining-types-for-nodejs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 2e7e300f04c53b..bc1573dfbe2397 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -67,8 +67,8 @@ Some additional specifics around the current approach include: options that are needed to achieve many of the requirements above. * `package.json` as the location for the config is potentially a good choice as Node.js already looks for it as part of startup. -* The implementation chosen should allow for difference configuration in - for different enronments/conditions like prod,dev, etc. +* The implementation chosen should allow for different configuration + in/for different environments/conditions like `prod`, `dev`, etc. * We don't have consensus on provding an opinionated default but that should be explored after the initial steps are complete. * It will be important that as part of the messaging around this From 4327fc89fcd3df452d8598176bb24bbf09125aab Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:51:51 -0400 Subject: [PATCH 09/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Mohammed Keyvanzadeh --- doc/contributing/maintaining-types-for-nodejs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index bc1573dfbe2397..899255935e95df 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -73,8 +73,8 @@ Some additional specifics around the current approach include: that should be explored after the initial steps are complete. * It will be important that as part of the messaging around this functionality that we avoid confusion that could lead people to ship - TypeScript files (ex `script.ts`) instead of the processed files - (ex `script.js`). + TypeScript files (e.g. `script.ts`) instead of the processed files + (e.g. `script.js`). ## Generation/Consumption of machine readable JSON files From 0a4a32e17b8298b9cd9e486d7fa1f91209236010 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:51:57 -0400 Subject: [PATCH 10/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Mohammed Keyvanzadeh --- doc/contributing/maintaining-types-for-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 899255935e95df..f2af265471336e 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -36,7 +36,7 @@ is identified specifically, a secondary goal is that what we provide to improve development experience with TypeScript would apply to other type systems as well. -We have agreed that the approach will `NOT` include bundling TypeScript +We have agreed that the approach will **NOT** include bundling TypeScript tools with Node.js but instead improve the developer experience for how those tools are installed/configured to work with Node.js. From cedeb099b08a3bade61ef9581c2df1d5d016e677 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:52:03 -0400 Subject: [PATCH 11/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Geoffrey Booth <456802+GeoffreyBooth@users.noreply.github.com> --- doc/contributing/maintaining-types-for-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index f2af265471336e..7a9a28c0768da7 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -34,7 +34,7 @@ The number of people using TypeScript with Node.js is significant enough that providing a good developer experience is important. While TypeScript is identified specifically, a secondary goal is that what we provide to improve development experience with TypeScript would apply to other type -systems as well. +systems and transpiled languages as well. We have agreed that the approach will **NOT** include bundling TypeScript tools with Node.js but instead improve the developer experience for how From 85ecf68b423b591668ff5e905cc08b7356c6ebfc Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 29 Jul 2022 10:59:17 -0400 Subject: [PATCH 12/16] squash: incorporate suggestions --- .../maintaining-types-for-nodejs.md | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 7a9a28c0768da7..947b5823888c52 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -44,21 +44,23 @@ The high level developer experience we are working towards was captured in the [next-10 TypeScript mini-summit](https://github.com/nodejs/next-10/pull/150) and is as follows: -1. Users can ask Node.js to execute a file which is not one of the types it - can execute by default (.js, .mjs, etc.). For example `node script.ts`. -2. On startup, Node.js will look for a config which is in the scope of the - file being executed. -3. If no config is found, Node.js will echo either: +1. When Node.js is started with an entry point that is not a file type that + Node.js recognizes, for example `node script.ts`, an informative error + message is printed that directs users to a webpage where they can + learn how to configure Node.js to support that file type. * If the file was a TypeScript file, a TypeScript specific message with a - reference to a link on Nodejs.org on how to install required components - for TypeScript and how to add the associated config. - * If the file was not a TypeScript file, a generic message. -4. If a config is found, Node.js will extract the Node.js options for - that config and apply them as if they had been provided on the command - line. -5. Assuming the options associated with the config add support for the - type of file being loaded, Node.js will execute the file as if it was one - of the file types it can execute by default. + reference to a link on Nodejs.org specific on learning how to + configure TypeScript will be provided. + * For other file types a generic message and shared webpage will be + used. +2. Node.js gains support for loading configuration from a file. Most, if not + all, of the configuration supported by `NODE_OPTIONS` would be + supported in this file (which might be the `package.json` that lives + near the entry point file). The webpage with instructions would tell + users what configuration to put in this file to get Node.js to support + their file type. +3. When Node.js is run with the correct configuration, either in a file or + `NODE_OPTIONS` or flags, the unknown file type is executed as expected. Some additional specifics around the current approach include: From 21cb6b22bf51ebd38fe692fd3aead73f8b2946a7 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 2 Aug 2022 14:51:11 -0400 Subject: [PATCH 13/16] Update doc/contributing/maintaining-types-for-nodejs.md Co-authored-by: Geoffrey Booth <456802+GeoffreyBooth@users.noreply.github.com> --- doc/contributing/maintaining-types-for-nodejs.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 947b5823888c52..0118d0e0c9cba9 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -70,7 +70,14 @@ Some additional specifics around the current approach include: * `package.json` as the location for the config is potentially a good choice as Node.js already looks for it as part of startup. * The implementation chosen should allow for different configuration - in/for different environments/conditions like `prod`, `dev`, etc. + in/for different environments/conditions such as production + versus development, or different types of hosted environments + such as serverless vs traditional, etc.; Node.js would not make + any recommendations or have any expectations as to what the + separate configuration blocks should be named or what their + purposes should be, just that a configuration file should have + the ability to provide different configurations for user-defined + conditions. * We don't have consensus on provding an opinionated default but that should be explored after the initial steps are complete. * It will be important that as part of the messaging around this From 4f559f544135e0473e50214fc9e5abbad6b9bda4 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 2 Aug 2022 14:53:09 -0400 Subject: [PATCH 14/16] Update doc/contributing/maintaining-types-for-nodejs.md --- doc/contributing/maintaining-types-for-nodejs.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 0118d0e0c9cba9..66eec09e9b9a77 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -78,6 +78,7 @@ Some additional specifics around the current approach include: purposes should be, just that a configuration file should have the ability to provide different configurations for user-defined conditions. +* There is no plan to define a default tsconfig.json for all Node.js users * We don't have consensus on provding an opinionated default but that should be explored after the initial steps are complete. * It will be important that as part of the messaging around this From 1b418c48c88183a907d548f9a54ac94be1481f83 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 2 Aug 2022 15:45:41 -0400 Subject: [PATCH 15/16] Update doc/contributing/maintaining-types-for-nodejs.md --- doc/contributing/maintaining-types-for-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 66eec09e9b9a77..48f2e46c1c77e6 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -49,7 +49,7 @@ and is as follows: message is printed that directs users to a webpage where they can learn how to configure Node.js to support that file type. * If the file was a TypeScript file, a TypeScript specific message with a - reference to a link on Nodejs.org specific on learning how to + reference to a link on Nodejs.org specific on learning how to configure TypeScript will be provided. * For other file types a generic message and shared webpage will be used. From e3d90ccfb834687b45bd20104cdebef3c2dfe3c0 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 4 Aug 2022 18:55:14 -0400 Subject: [PATCH 16/16] Update doc/contributing/maintaining-types-for-nodejs.md --- doc/contributing/maintaining-types-for-nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 48f2e46c1c77e6..07667726c79bea 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -60,7 +60,7 @@ and is as follows: users what configuration to put in this file to get Node.js to support their file type. 3. When Node.js is run with the correct configuration, either in a file or - `NODE_OPTIONS` or flags, the unknown file type is executed as expected. + `NODE_OPTIONS` or flags, the unknown file type is executed as expected. Some additional specifics around the current approach include: