mirror of
https://github.com/nodejs/node.git
synced 2026-11-21 12:59:16 -05:00
Add an experimental `net/promises` namespace, accessible via
`require('node:net/promises')` or `net.promises`, mirroring the existing
`fs/promises` and `dns/promises` modules.
It provides promise-based variants of net's one-shot lifecycle
operations:
- `connect()` returns a promise that fulfills with a connected Socket
once the 'connect' event fires, and rejects on connection failure or
when an optional AbortSignal is aborted, destroying the socket.
- `listen()` creates a server, begins listening, and returns a promise
that fulfills with the listening Server once the 'listening' event
fires. It rejects if the server fails to bind or an optional
AbortSignal is aborted, closing the server.
The functions are named for the actions they await, forming a parallel
`connect()`/`listen()` pair. This is intentionally not the callback
API's factory taxonomy: there `createConnection()` is canonical because
it both creates a socket and initiates connecting, whereas
`createServer()` is a pure factory that does not listen. A
`createConnection`/`createServer` pairing would be inconsistent here
because `createServer` has no completion to await, so no
`createConnection` alias is provided.
Refs: https://github.com/nodejs/node/issues/21482
Assisted-by: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Ethan Arrowood <ethan@arrowood.dev>
PR-URL: https://github.com/nodejs/node/pull/63965
Reviewed-By: Tim Perry <pimterry@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Node.js documentation style guide
This guide provides clear and concise instructions to help you create well-organized and readable documentation for the Node.js community. It covers organization, spelling, formatting, and more to ensure consistency and professionalism across all documents.
Table of contents
- General Guidelines
- Writing Style
- Punctuation
- Document Structure
- API Documentation
- Code Blocks
- Formatting
- Product and Project Naming
General guidelines
File naming
- Markdown Files: Use
lowercase-with-dashes.md.- Use underscores only if they are part of the topic name (e.g.,
child_process). - Some files, like top-level Markdown files, may be exceptions.
- Use underscores only if they are part of the topic name (e.g.,
Text wrapping
- Wrap documents at 120 characters per line to enhance readability and version control.
Editor configuration
- Follow the formatting rules specified in
.editorconfig.- A plugin is available for some editors to enforce these rules.
Testing documentation
- Validate documentation changes using
make test-doc -jorvcbuild test-doc.
Writing style
Spelling and grammar
- Spelling: Use US spelling.
- Grammar: Use clear, concise language. Avoid unnecessary jargon.
Commas
- Serial Commas: Use serial commas for clarity.
- Example: apples, oranges, and bananas
Pronouns
- Avoid first-person pronouns (I, we).
- Exception: Use we recommend foo instead of foo is recommended.
Gender-neutral language
- Use gender-neutral pronouns and plural nouns.
- OK: they, their, them, folks, people, developers
- NOT OK: his, hers, him, her, guys, dudes
Terminology
- Use precise technical terms and avoid colloquialisms.
- Define any specialized terms or acronyms at first use.
Punctuation
Terminal punctuation
- Place inside parentheses or quotes if the content is a complete clause.
- Place outside if the content is a fragment of a clause.
Quotation marks
- Use double quotation marks for direct quotes.
- Use single quotation marks for quotes within quotes.
Colons and semicolons
- Use colons to introduce lists or explanations.
- Use semicolons to link closely related independent clauses.
Document structure
Headings
- Start documents with a level-one heading (
#). - Use subsequent headings (
##,###, etc.) to organize content hierarchically.
Links
- Prefer reference-style links (
[a link][]) over inline links ([a link](http://example.com)).
Lists
- Use bullet points for unordered lists and numbers for ordered lists.
- Keep list items parallel in structure.
Tables
- Use tables to present structured information clearly. Ensure they are readable in plain text.
API documentation
YAML comments
- Update the YAML comments associated with the API, especially when introducing or deprecating an API.
Usage examples
- Provide a usage example or a link to an example for every function.
Parameter descriptions
- Clearly describe parameters and return values, including types and defaults.
- Example:
* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
- Example:
Code blocks
Language-aware fences
-
Use language-aware fences (e.g.,
```js) for code blocks.-
Info String: Use the appropriate info string from the following list:
Language Info String Bash bashC cCommonJS cjsCoffeeScript coffeeTerminal Session consoleC++ cppDiff diffHTTP httpJavaScript jsJSON jsonMarkdown markdownEcmaScript mjsPowershell powershellR rPlaintext textTypeScript typescript -
Use
textfor languages not listed until their grammar is added toremark-preset-lint-node.
-
Code comments
- Use comments to explain complex logic within code examples.
- Follow the standard commenting style of the respective language.
Formatting
Escaping characters
- Use backslash-escaping for underscores, asterisks, and backticks:
\_,\*,\`.
Naming conventions
- Constructors: Use PascalCase.
- Instances: Use camelCase.
- Methods: Indicate methods with parentheses:
socket.end()instead ofsocket.end.
Function arguments and returns
- Arguments:
Example:
* `name` {type|type2} Optional description. **Default:** `value`.* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`. - Returns:
Example:
* Returns: {type|type2} Optional description.* Returns: {AsyncHook} A reference to `asyncHook`.
Product and project naming
Official styling
- Use official capitalization for products and projects.
- OK: JavaScript, Google's V8
- NOT OK: Javascript, Google's v8
Node.js references
- Use Node.js instead of Node, NodeJS, or similar variants.
- For the executable,
nodeis acceptable.
- For the executable,
Version references
- Use Node.js and the version number in prose. Do not prefix the version number with v.
- OK: Node.js 14.x, Node.js 14.3.1
- NOT OK: Node.js v14
For topics not addressed here, please consult the Microsoft Writing Style Guide.