nodejs

Node.js Standards

Default load: this file only. Pull refs/runtime-safety.md, refs/async-errors.md, refs/tooling.md, or refs/testing.md only when the task explicitly needs that depth.

Node.js owns runtime failure modes only: event-loop behaviour, promise rejection lifecycle in the process, streams/backpressure, worker threads, process signals, Buffer memory safety, dependency install mechanics, and boot-time environment loading. TypeScript rules stay in standards/typescript/; API contracts, security policy, auth, performance strategy, architecture, CI shape, and database persistence stay in their global or database refs and should be linked rather than copied.

Priority: P0 — Runtime Safety

• Every promise is awaited, returned, or has an explicit rejection handler; no floating promises. Node exits on unhandled rejections by default on maintained modern releases, and unobserved rejections still make failures nondeterministic. void is allowed only for a documented fire-and-forget call that attaches .catch() or routes through a helper that centralizes rejection logging. Signal: a call returning a Promise on a statement line with no await, return, .catch, or approved fire-and-forget helper.
• Global unhandledRejection / uncaughtException handlers are last-resort logging plus graceful exit, never primary control flow, and never resume normal operation after uncaughtException. Catch errors where they occur. Signal: business logic such as retry, fallback, or response handling inside a process.on('uncaughtException') handler, or a handler that logs and keeps serving indefinitely.
• Throws across callback, timer, and event boundaries are caught locally and converted to rejections or error events. Normal throws inside an async function become promise rejections; throws in later callbacks (setTimeout, EventEmitter, stream callbacks) escape the original .catch(). Signal: a throw inside a bare setTimeout, emitter.on, or stream callback with no try/catch or error propagation.
• Handle SIGTERM and SIGINT for graceful shutdown: fail readiness or stop accepting connections, drain in-flight work up to a fixed deadline, close DB/Redis/pool resources, then exit before the orchestrator kills the process. Signal: a long-lived server with no signal handler, no shutdown timeout, or process.exit() called inside a request handler.
• Never block the event loop on the request path. No synchronous CPU work such as large JSON.parse, crypto.pbkdf2Sync, compression, image transforms, and no sync fs such as readFileSync or existsSync in a hot handler; offload CPU work to worker_threads or a queue, and use async APIs for I/O. Signal: a *Sync call or tight CPU loop inside a request handler.
• Respect stream backpressure. Prefer stream.pipeline() or stream/promises.pipeline() for multi-stream flows so errors and cleanup propagate; .pipe() is acceptable only when error and cleanup paths are handled. Honour write() returning false and wait for 'drain'. Signal: a.pipe(b) with no error handling, or .write() in a loop ignoring the return value.
• Use Buffer.alloc for buffers that may be read before full overwrite; use Buffer.allocUnsafe only when every byte is overwritten before any read, response, log, persistence, crypto/compression input, or serialization. Unsafe buffers can leak prior heap contents. Signal: Buffer.allocUnsafe or allocUnsafeSlow flowing to an external sink without a complete overwrite first.