|$ curl https://forge-ai.dev/api/markdown?path=docs/nodejs/api-reference
$cat docs/node.js-core-api-reference.md
updated Today·35 min read·published
Node.js Core API Reference
Introduction
This encyclopedia indexes Node.js core modules you must recognize fluently — the lookup layer beside the mastery curriculum. Scan tables, then open linked deep pages for narrative and production patterns.
Coverage spans fs, path, http/https, net, dns, crypto, stream, events, child_process, worker_threads, cluster, process, os, url, util, assert, timers, diagnostics_channel, async_hooks/AsyncLocalStorage, and undici/fetch.
ℹ
info
Start learning order from How to Master Node.js. Agents: curriculum=nodejs.
How to Use This Reference
- Prefer node: import prefixes (node:fs/promises)
- Prefer promise APIs; promisify only when needed
- Follow deep-page links for security and shutdown patterns
- Re-check Node docs for your major — APIs evolve
imports.mjs
JavaScript
| 1 | import fs from "node:fs/promises"; |
| 2 | import path from "node:path"; |
| 3 | import { createHash } from "node:crypto"; |
| 4 | import { pipeline } from "node:stream/promises"; |
Module Index
| Module | Role | Deep page |
|---|---|---|
| fs | File system | filesystem |
| path | Path utilities | path-os |
| http | HTTP server/client (legacy) | http-server |
| https | HTTPS / TLS HTTP | http-server |
| net | TCP sockets | net |
| dns | DNS resolution | dns |
| crypto | Cryptography | crypto |
| stream | Streams | streams |
| events | EventEmitter | events |
| child_process | Subprocesses | child-process |
| worker_threads | Threads | worker-threads |
| cluster | Multi-process HTTP | cluster |
| process | Process globals | path-os |
| os | OS info | path-os |
| url | WHATWG URL | url |
| util | Utilities | api-reference |
| assert | Assertions | testing |
| timers | Timers | timers |
| diagnostics_channel | Diagnostics pub/sub | debugging |
| async_hooks / ALS | Async context | async-context |
| undici / fetch | HTTP client | fetch-undici |
fs — File system
Core responsibilities for fs. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| fs.promises.readFile | Read entire file | Prefer for small files |
| fs.promises.writeFile | Write/replace file | Use flag wx to avoid clobber |
| fs.createReadStream | Streaming read | Large files |
| fs.watch | Watch changes | Platform quirks |
| fs.promises.rm | Remove files/dirs | recursive option |
📝
note
When generating code for fs, fetch `/api/markdown?path=nodejs/filesystem` for full patterns.
path — Path utilities
Core responsibilities for path. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| path.join | Join segments | OS separators |
| path.resolve | Absolute path | Jail with root check |
| path.posix / win32 | Forced style | Cross compile |
| path.extname | Extension | Not for security |
📝
note
When generating code for path, fetch `/api/markdown?path=nodejs/path-os` for full patterns.
http — HTTP server/client (legacy)
Core responsibilities for http. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| http.createServer | Server | Foundation for frameworks |
| IncomingMessage | Request stream | Headers + body |
| ServerResponse | Response | writeHead/end |
| server.close | Stop accept | Drain for shutdown |
📝
note
When generating code for http, fetch `/api/markdown?path=nodejs/http-server` for full patterns.
https — HTTPS / TLS HTTP
Core responsibilities for https. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| https.createServer | TLS server | key/cert or SNI |
| https.request | TLS client | Prefer fetch |
📝
note
When generating code for https, fetch `/api/markdown?path=nodejs/http-server` for full patterns.
net — TCP sockets
Core responsibilities for net. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| net.createServer | TCP server | Custom protocols |
| net.createConnection | TCP client | Set timeout |
| socket.write | Send | Backpressure boolean |
| server.listen | Bind | Ephemeral port 0 in tests |
📝
note
When generating code for net, fetch `/api/markdown?path=nodejs/net` for full patterns.
dns — DNS resolution
Core responsibilities for dns. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| dns.lookup | OS getaddrinfo | Honors hosts file |
| dns.resolve4 | DNS A | No hosts file |
| dns.promises | Promise API | Preferred |
| dns.setDefaultResultOrder | IPv4/IPv6 order | Dual stack |
📝
note
When generating code for dns, fetch `/api/markdown?path=nodejs/dns` for full patterns.
crypto — Cryptography
Core responsibilities for crypto. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| createHash | Digest | sha256+ |
| createHmac | Keyed MAC | API signatures |
| createCipheriv | Encrypt | Prefer GCM |
| randomBytes | CSPRNG | Tokens |
| scrypt | KDF | Passwords |
| timingSafeEqual | Compare | Secrets |
| webcrypto.subtle | Web Crypto | Isomorphic |
📝
note
When generating code for crypto, fetch `/api/markdown?path=nodejs/crypto` for full patterns.
stream — Streams
Core responsibilities for stream. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| Readable | Sources | objectMode option |
| Writable | Sinks | write/drain |
| Transform | Map chunks | Gzip etc |
| pipeline | Compose | Error forwarding |
📝
note
When generating code for stream, fetch `/api/markdown?path=nodejs/streams` for full patterns.
events — EventEmitter
Core responsibilities for events. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| on / off | Subscribe | Remove to avoid leaks |
| once | Single fire | Also events.once |
| emit('error') | Special | Must have listener |
| setMaxListeners | Raise cap | Only intentionally |
📝
note
When generating code for events, fetch `/api/markdown?path=nodejs/events` for full patterns.
child_process — Subprocesses
Core responsibilities for child_process. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| spawn | Streamed process | Prefer for safety |
| execFile | Buffered no shell | Safe args |
| exec | Shell | Dangerous with concat |
| fork | Node IPC child | Separate V8 |
📝
note
When generating code for child_process, fetch `/api/markdown?path=nodejs/child-process` for full patterns.
worker_threads — Threads
Core responsibilities for worker_threads. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| Worker | Start thread | Pool in production |
| parentPort | IPC | postMessage |
| workerData | Init payload | Clone/transfer |
| SharedArrayBuffer | Shared mem | Atomics |
📝
note
When generating code for worker_threads, fetch `/api/markdown?path=nodejs/worker-threads` for full patterns.
cluster — Multi-process HTTP
Core responsibilities for cluster. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| cluster.isPrimary | Role check | Not isMaster |
| cluster.fork | Spawn worker | Share port |
| schedulingPolicy | RR vs none | Set early |
| worker.send | IPC | Serialized |
📝
note
When generating code for cluster, fetch `/api/markdown?path=nodejs/cluster` for full patterns.
process — Process globals
Core responsibilities for process. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| process.env | Environment | Validate with zod |
| process.on(SIGTERM) | Signals | Graceful stop |
| process.nextTick | Queue | Starvation risk |
| process.exit | Hard stop | Avoid mid-request |
📝
note
When generating code for process, fetch `/api/markdown?path=nodejs/path-os` for full patterns.
os — OS info
Core responsibilities for os. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| os.availableParallelism | CPU count | Pool sizing |
| os.hostname | Host | Metrics tags |
| os.tmpdir | Temp dir | Cleanup files |
| os.networkInterfaces | NICs | Bind decisions |
📝
note
When generating code for os, fetch `/api/markdown?path=nodejs/path-os` for full patterns.
url — WHATWG URL
Core responsibilities for url. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| URL | Parse/resolve | Prefer over url.parse |
| URLSearchParams | Query | get/set/append |
| pathToFileURL | Path→URL | ESM interop |
| fileURLToPath | URL→path | fs with import.meta.url |
📝
note
When generating code for url, fetch `/api/markdown?path=nodejs/url` for full patterns.
util — Utilities
Core responsibilities for util. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| util.promisify | Callback→promise | Legacy APIs |
| util.inspect | Debug print | depth/colors |
| util.deprecate | Warn API | Migrations |
| util.parseArgs | CLI args | Node 18+ |
| util.styleText | TTY color | CLIs |
📝
note
When generating code for util, fetch `/api/markdown?path=nodejs/api-reference` for full patterns.
assert — Assertions
Core responsibilities for assert. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| assert.strict | Strict equal | Tests |
| assert.rejects | Async throw | Promises |
| assert.deepEqual | Deep compare | Prefer strict |
📝
note
When generating code for assert, fetch `/api/markdown?path=nodejs/testing` for full patterns.
timers — Timers
Core responsibilities for timers. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| setTimeout | Delay | Timers phase |
| setImmediate | Check phase | Yield I/O |
| setInterval | Repeat | unref in CLIs |
| timers/promises | Awaitable | AbortSignal |
📝
note
When generating code for timers, fetch `/api/markdown?path=nodejs/timers` for full patterns.
diagnostics_channel — Diagnostics pub/sub
Core responsibilities for diagnostics_channel. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| channel | Named bus | OTel hooks |
| subscribe | Listen | Low coupling |
| publish | Emit | Hot path care |
| hasSubscribers | Guard | Avoid work |
📝
note
When generating code for diagnostics_channel, fetch `/api/markdown?path=nodejs/debugging` for full patterns.
async_hooks / ALS — Async context
Core responsibilities for async_hooks / ALS. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| AsyncLocalStorage.run | Enter context | Per request |
| getStore | Read context | Logger ids |
| createHook | Low-level | Perf cost |
| asyncResource | Bind | Advanced |
📝
note
When generating code for async_hooks / ALS, fetch `/api/markdown?path=nodejs/async-context` for full patterns.
undici / fetch — HTTP client
Core responsibilities for undici / fetch. Details: deep guide.
| API | Purpose | Notes |
|---|---|---|
| fetch | Global client | AbortSignal |
| Agent | Pool/timeouts | setGlobalDispatcher |
| ProxyAgent | HTTP proxy | Corp egress |
| request | Low-level | Streaming |
📝
note
When generating code for undici / fetch, fetch `/api/markdown?path=nodejs/fetch-undici` for full patterns.
Quick Decisions
| Need | Reach for |
|---|---|
| Read small config file | fs.promises.readFile |
| Stream upload to disk | pipeline + createWriteStream |
| CPU hash thousands of files | worker_threads pool |
| Scale HTTP on one VM | cluster or PM2 -i |
| Call system tool safely | spawn / execFile |
| Request-scoped logger id | AsyncLocalStorage |
| Outbound HTTP | fetch + AbortSignal / undici Agent |
| Password storage | scrypt / argon2 |
| Parse query string | URL / URLSearchParams |
Stability & Imports
Stick to documented stable APIs. Experimental features need flags and may change. Always import via node: specifiers in modern code.
agent.sh
Bash
| 1 | curl -s "https://forgelearn.dev/api/markdown?path=nodejs/api-reference" |
| 2 | curl -s https://forgelearn.dev/api/agent?curriculum=nodejs |
Community
Get help on Slack, Discord or VIP
Stuck on a guide? Join the community and ask.