node

Node.js Runtime

Async patterns, streams, module systems, package managers, and mise/CI integration for Node.js TypeScript projects.

Async Patterns

async/await over raw Promise chains

async function fetchUserAndPosts(userId: string) {
  const user = await fetchUser(userId);
  const posts = await fetchPosts(user.id);
  return { user, posts };
}

Prefer await in sequence over .then() chains for anything with more than one step — the stack trace on a rejected await points at the actual failing line, where a long .then() chain's error frequently doesn't.

Concurrency with Promise.all / Promise.allSettled

Sequential await calls that don't depend on each other's results waste wall-clock time — run independent async work concurrently:

// Sequential — unnecessarily slow if these don't depend on each other
const user = await fetchUser(id);
const settings = await fetchSettings(id);

// Concurrent — same total work, shorter wall time
const [user, settings] = await Promise.all([fetchUser(id), fetchSettings(id)]);

Promise.all rejects as soon as any one input rejects, discarding the other results. Promise.allSettled never rejects — it resolves with a { status: "fulfilled" | "rejected", ... } record per input, appropriate when partial failure is an expected, handled case (e.g. "notify five webhooks, report which ones failed") rather than a hard error.

EventEmitter

Node's EventEmitter is the base of most non-stream async Node APIs (process, net.Server, child_process) — extend it for a custom object that fires multiple named events over its lifetime, as opposed to a Promise's single resolve/reject:

import { EventEmitter } from "node:events";

class JobQueue extends EventEmitter {
  enqueue(job: Job) {
    // ...
    this.emit("enqueued", job);
  }
}

const queue = new JobQueue();
queue.on("enqueued", (job: Job) => console.log(`queued ${job.id}`));

Reach for EventEmitter for "zero or more things will happen over time, listeners subscribe/unsubscribe" — reach for a Promise for "exactly one thing happens once." Mixing the two (a Promise that also emits progress events) is a common source of Node API confusion; if progress reporting is needed, an EventEmitter combined with a distinct completion Promise (or an async generator) is clearer than overloading one Promise for both jobs.