|
| 1 | +# Maintaining types for Node.js |
| 2 | + |
| 3 | +While JavaScript is an untyped language, there are a number of complementary |
| 4 | +technologies like [TypeScript](https://www.typescriptlang.org/) and |
| 5 | +[Flow](https://flow.org/) which allow developers to use types within their |
| 6 | +JavaScript projects. While many people don't use types, there are enough |
| 7 | +who do that the project has agreed it's important to work towards having |
| 8 | +[suitable types for end-users](https://github.com/nodejs/node/blob/master/doc/contributing/technical-priorities.md#suitable-types-for-end-users). |
| 9 | + |
| 10 | +## High level approach |
| 11 | + |
| 12 | +There are a number of ways that types could be maintained for Node.js ranging |
| 13 | +from shipping them with the Node.js runtime to having them be externally |
| 14 | +maintained. |
| 15 | + |
| 16 | +The different options were discussed as part of the |
| 17 | +[next-10](https://github.com/nodejs/next-10/blob/main/meetings/summit-nov-2021.md#suitable-types-for-end-users) |
| 18 | +effort and it was agreed that maintaining them externally is the best approach. |
| 19 | +Some of the advantages to this approach include: |
| 20 | + |
| 21 | +* Node.js maintainers do not need to be familiar with any given type |
| 22 | + system/technology. |
| 23 | +* Types can be updated without requiring Node.js releases. |
| 24 | + |
| 25 | +The agreement was that the ideal flow would be as follows: |
| 26 | + |
| 27 | +* APIs are added/documented in the existing Node.js markdown files. |
| 28 | +* Automation in the Node.js project creates a machine readable JSON |
| 29 | + representation of the API from the documentation. |
| 30 | +* Automation within external type projects consumes the JSON and automatically |
| 31 | + generates a PR to add the API. |
| 32 | + |
| 33 | +## Generation/Consumption of machine readable JSON files |
| 34 | + |
| 35 | +When you run `make doc` the canonical markdown files used to |
| 36 | +document the Node.js APIs in the |
| 37 | +[doc/api](https://github.com/nodejs/node/tree/master/doc/api) |
| 38 | +directory are converted to both an `.html` file and a `.json` file. |
| 39 | + |
| 40 | +As part of the regular build/release process both the `html` and |
| 41 | +`json` files are published to [nodejs.org](https://nodejs.org/en/docs/). |
| 42 | + |
| 43 | +The generator that does the conversion is in the |
| 44 | +[tools/doc](https://github.com/nodejs/node/tree/master/tools/doc) |
| 45 | +directory. |
| 46 | + |
| 47 | +## Markdown structure |
| 48 | + |
| 49 | +The constraints required on the markdown files in the |
| 50 | +[doc/api](https://github.com/nodejs/node/tree/master/doc/api) directory |
| 51 | +in order to be able to generate the JSON files are defined in the |
| 52 | +[documentation-style-guide](https://github.com/nodejs/node/blob/master/doc/README.md#documentation-style-guide). |
| 53 | + |
| 54 | +## Planned changes (as of Jan 1 2022) |
| 55 | + |
| 56 | +While JSON files are already being generated and published, they are not |
| 57 | +structured well enough for them to be easily consumed by the type projects. |
| 58 | +Generally external teams need some custom scripts along with manual fixup |
| 59 | +afterwards. |
| 60 | + |
| 61 | +There is an ongoing effort to add additional markdown constraints and |
| 62 | +then update the flow in order to be able to generate a better |
| 63 | +JSON output. |