Tech Insights on Nodejs, Javascript, Mongodb

AI Gateway vs API Gateway: Build LLM Middleware in Node.js

Manish Prasad — Tue, 06 Oct 2026 00:00:00 +0530

Middleware used to mean an Express function that checked a JWT and logged the request. A request that ends in an LLM call needs more than that. Something has to pick the model, check the tenant’s token budget, redact the email address in the response and decide what to do after the third 429 in a minute. If a dedicated layer doesn’t do it, forty route handlers do, each slightly differently.

Quick answer

An AI gateway (also called an LLM gateway or AI middleware) sits between your app and model providers. It owns five jobs: model routing, caching, token-aware rate limiting, observability and failover. You need one once you call more than one model, serve more than one tenant, or get a bill you can’t explain.

AI gateway vs API gateway

	API gateway	AI gateway
Unit of traffic	Requests	Tokens and requests
Reads the payload	No	Yes: prompts, completions, tool calls
Rate limiting	Requests per second	Tokens per minute + requests per minute
Caching	Exact key match	Semantic similarity
Routing	Path, header	Task difficulty, cost, provider health

Keep the API gateway at the edge for auth and validation (the usual Express middleware patterns). The AI layer sits behind it, with a thin provider adapter underneath:

API gateway (auth, validation)  →  AI middleware (decisions)  →  provider adapter (SDK calls)

Route handlers should never call a model ID directly. Once they do, you can’t change the model through config, attribute its cost or cache its responses.

1. Model routing

Most production traffic doesn’t need a frontier model. LMSYS’s RouteLLM cut costs by over 85% on MT Bench compared with sending everything to GPT-4, while keeping 95% of its quality score. Rules are enough for a first version:

typescript

type Tier = 'small' | 'frontier';

interface AIRequest {
  tenant: string;
  prompt: string;
  maxTokens?: number;
  requireCapability?: 'vision' | 'code' | 'reasoning';
}

function pickTier(req: AIRequest, inputTokens: number): Tier {
  if (req.requireCapability === 'reasoning') return 'frontier';
  if (inputTokens > 8_000) return 'frontier';
  return 'small';
}

// Ordered lists: primary model first, then fallbacks on other providers.
const MODELS: Record<Tier, string[]> = {
  small: process.env.MODELS_SMALL!.split(','),
  frontier: process.env.MODELS_FRONTIER!.split(','),
};

Log the tier on every call. A week of that data tells you whether a trained router would pay for itself.

2. Caching

Prompt caching is the cheap win. Anthropic charges up to 90% less for cached input reads, and OpenAI caches prompts over 1,024 tokens automatically. Keep the prefix stable: system prompt and tool definitions first, user content last, and no timestamps near the top.

Semantic caching skips the provider call when a new prompt means the same as one already answered. The similarity threshold decides everything. Prem AI’s measurements show 0.85 giving 45-70% hits but 15-30% wrong answers, while 0.93-0.95 gives around 30% hits with 3-7% wrong. Tune the threshold on your own labelled query pairs.

typescript

interface SemanticCache {
  // Keyed by tenant: a shared index will eventually serve one customer's answer to another.
  lookup(tenant: string, prompt: string): Promise<AIResponse | null>;
  store(tenant: string, prompt: string, res: AIResponse, ttlSec: number): Promise<void>;
}

function isCacheable(ctx: { usesTools: boolean; personalised: boolean }) {
  return !ctx.usesTools && !ctx.personalised; // "what's my balance?" must never hit the cache
}

A 20% hit rate on a $5,000 monthly bill saves $1,000 a month.

3. Token-aware rate limiting

Providers enforce tokens per minute (TPM) and requests per minute (RPM) at the same time. One 80,000-token job can be under the RPM limit and still block dozens of short chats. Use two buckets: reserve the worst case before the call, then correct it with real usage afterwards.

typescript

class TokenBucket {
  private tokens: number;
  private last = Date.now();
  constructor(private ratePerSec: number, private capacity: number) { this.tokens = capacity; }

  private refill() {
    const now = Date.now();
    this.tokens = Math.min(this.capacity, this.tokens + ((now - this.last) / 1000) * this.ratePerSec);
    this.last = now;
  }
  tryConsume(n: number) { this.refill(); if (this.tokens < n) return false; this.tokens -= n; return true; }
  adjust(n: number) { this.refill(); this.tokens = Math.min(this.capacity, this.tokens - n); }
}

export class DualBucketLimiter {
  private tpm: TokenBucket;
  private rpm: TokenBucket;

  constructor(tpmLimit: number, rpmLimit: number) {
    this.tpm = new TokenBucket(tpmLimit / 60, tpmLimit);
    this.rpm = new TokenBucket(rpmLimit / 60, rpmLimit);
  }

  acquire(estimatedInput: number, maxOutput: number): number | null {
    const reserved = estimatedInput + maxOutput;
    if (!this.tpm.tryConsume(reserved)) return null;
    if (!this.rpm.tryConsume(1)) { this.tpm.adjust(-reserved); return null; }
    return reserved; // returned, not stored, so concurrent requests can't overwrite it
  }

  reconcile(reserved: number, actualInput: number, actualOutput: number) {
    this.tpm.adjust(actualInput + actualOutput - reserved); // charge overruns, refund the rest
  }
}

Estimate input tokens with gpt-tokenizer or js-tiktoken, or use characters ÷ 4 as a fallback. Keep one limiter per tenant so a noisy tenant can’t use up a shared key. With more than one process, move the buckets to Redis: in-memory counters under cluster multiply the real limit.

4. Observability with OpenTelemetry

Use the OpenTelemetry GenAI semantic conventions so calls to OpenAI, Anthropic and local models share one schema. Note that v1.37.0 replaced gen_ai.system with gen_ai.provider.name.

typescript

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('ai-middleware');

function tracedCall(provider: ModelProvider, model: string, req: AIRequest, signal: AbortSignal) {
  return tracer.startActiveSpan(`chat ${model}`, async (span) => {
    span.setAttributes({
      'gen_ai.operation.name': 'chat',
      'gen_ai.provider.name': provider.name,
      'gen_ai.request.model': model,
      'app.tenant': req.tenant,
    });
    try {
      const res = await provider.complete(model, req, signal);
      span.setAttributes({
        'gen_ai.usage.input_tokens': res.usage.input,
        'gen_ai.usage.output_tokens': res.usage.output,
        'app.cost_usd': res.costUsd,
      });
      return res;
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw err;
    } finally {
      span.end();
    }
  });
}

Redact PII before spans and logs leave the process (Pino redaction paths handle the log side). The agent and tool-call conventions are still marked Development, so pin your semconv version.

5. Resilience

Retry 408, 429, 5xx and timeouts. Never retry a 400, because it fails the same way every time. Give each attempt its own AbortSignal deadline, and stop calling a provider after repeated failures.

typescript

const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function withRetry<T>(fn: (signal: AbortSignal) => Promise<T>, attempts = 3) {
  for (let i = 0; ; i++) {
    try {
      return await fn(AbortSignal.timeout(15_000));
    } catch (err: any) {
      if (err?.status !== undefined && !RETRYABLE.has(err.status)) throw err;
      if (i === attempts - 1) throw err;
      const base = 250 * 2 ** i;
      await sleep(base + Math.random() * base); // backoff with jitter
    }
  }
}

class CircuitBreaker {
  private failures = 0;
  private openedAt = 0;
  constructor(private threshold = 5, private coolDownMs = 30_000) {}

  canCall() { return this.failures < this.threshold || Date.now() - this.openedAt > this.coolDownMs; }
  success() { this.failures = 0; }
  failure() { if (++this.failures >= this.threshold) this.openedAt = Date.now(); }
}

Fall back across providers within the same tier. Don’t quietly downgrade a reasoning task to a small model; fail and say so.

Putting it together

typescript

class PolicyViolation extends Error {}
class RateLimited extends Error {}

export class AIMiddleware {
  private limiters = new Map<string, DualBucketLimiter>();
  private breakers = new Map<string, CircuitBreaker>();

  constructor(private providers: Map<string, ModelProvider>, private cache: SemanticCache) {}

  async complete(req: AIRequest, ctx = { usesTools: false, personalised: false }) {
    const violation = checkInputPolicy(req.prompt);
    if (violation) throw new PolicyViolation(violation);

    const cacheable = isCacheable(ctx);
    const hit = cacheable && (await this.cache.lookup(req.tenant, req.prompt));
    if (hit) return hit;

    const inputTokens = estimateTokens(req.prompt);
    const limiter = this.get(this.limiters, req.tenant, () => new DualBucketLimiter(200_000, 500));
    const reserved = limiter.acquire(inputTokens, req.maxTokens ?? 1024);
    if (reserved === null) throw new RateLimited();

    for (const model of MODELS[pickTier(req, inputTokens)]) {
      const breaker = this.get(this.breakers, model, () => new CircuitBreaker());
      if (!breaker.canCall()) continue;
      try {
        const res = await withRetry((signal) => tracedCall(this.providers.get(model)!, model, req, signal));
        breaker.success();
        limiter.reconcile(reserved, res.usage.input, res.usage.output);
        res.text = redactPII(res.text);
        if (cacheable) await this.cache.store(req.tenant, req.prompt, res, 3600);
        return res;
      } catch {
        breaker.failure();
      }
    }
    limiter.reconcile(reserved, 0, 0); // nothing consumed, return the budget
    throw new Error('No healthy provider');
  }

  private get<T>(map: Map<string, T>, key: string, make: () => T): T {
    if (!map.has(key)) map.set(key, make());
    return map.get(key)!;
  }
}

The Express route doesn’t know which model answered. The tenant comes from the verified JWT:

typescript

app.post('/api/chat', async (req, res, next) => {
  try {
    const answer = await ai.complete({ tenant: req.user.orgId, prompt: req.body.message, maxTokens: 800 });
    res.json({ text: answer.text });
  } catch (err) {
    if (err instanceof RateLimited) return res.set('Retry-After', '10').status(429).json({ error: 'Token budget exceeded' });
    if (err instanceof PolicyViolation) return res.status(422).json({ error: err.message });
    next(err);
  }
});

Agent middleware and MCP

Agent frameworks expose the same interception points inside the agent loop. LangChain 1.0 has before_model, after_model and wrap_model_call hooks; before_* hooks run in list order and after_* hooks run in reverse, as in Express. The Vercel AI SDK uses wrapLanguageModel:

typescript

import { wrapLanguageModel } from 'ai';
import type { LanguageModelV4Middleware } from '@ai-sdk/provider'; // V2 in AI SDK 5

const redactOutput: LanguageModelV4Middleware = {
  specificationVersion: 'v4',
  wrapGenerate: async ({ doGenerate }) => {
    const result = await doGenerate();
    return {
      ...result,
      content: result.content.map((p) => (p.type === 'text' ? { ...p, text: redactPII(p.text) } : p)),
    };
  },
};

const model = wrapLanguageModel({ model: baseModel, middleware: [cacheMiddleware, redactOutput] });

MCP doesn’t replace any of this. It is the wire protocol agents use to discover and call tools. Middleware decides whether a tool call should happen at all. Treat tool descriptions and results as untrusted input, for the reasons covered in indirect prompt injection.

Which AI gateway to use

Gateway	Best at	Status in late 2026
LiteLLM	100+ providers, self-hosting	Active; PyPI releases 1.82.7 and 1.82.8 were hijacked on 2026-03-24, so pin versions and verify hashes
Bifrost	Throughput (~11µs overhead at 5,000 RPS, vendor-reported)	Active, Go
Portkey	Guardrails, governance, MCP gateway	Acquired by Palo Alto Networks
Vercel AI Gateway	Next.js and AI SDK apps	Active, managed
Helicone	Observability	Maintenance mode since March 2026; no new signups

Start with one of these rather than the class above. Write your own layer only once you’ve outgrown them; by then you’ll know which of the five jobs you need to own.

Five mistakes to avoid

Calling LLMs from route handlers. No cache, no limit, no cost tracking, no failover.
Hardcoding one model ID. Model choice belongs in config.
Sharing a semantic cache across tenants. Similarity search doesn’t check ownership.
Retrying every error. A retried 400 costs money and still fails.
Logging raw prompts. Redact before anything leaves the process.

Frequently Asked Questions

What is an AI gateway? A proxy between your app and LLM providers that routes, caches, rate-limits by tokens, applies guardrails and records cost per call. “LLM gateway” means the same thing.

Do I need one with a single provider? Not on day one. A thin wrapper like the one above covers budgets, retries and tracing. Add a gateway when you add a second provider or tenant.

How do I rate-limit LLM calls by tokens? Use two buckets per tenant (TPM and RPM). Reserve estimated input plus max_tokens before the call and reconcile with real usage after it.

Is semantic caching safe? It is, with a threshold tuned on your own data, entries scoped per tenant, and no caching of personalised or tool-based answers.

Integrating AI and LLMs with Node.js. SDK basics, streaming and function calling.
Indirect Prompt Injection Is a Backend Architecture Problem. Why tool input needs a policy gate.
7 Node.js Middleware Patterns for Express. The edge-layer patterns.
Promise.all() Is Fine… Until It Isn’t. Capping concurrency when you fan out LLM calls.
Node.js Error Handling Patterns. Which errors to surface and which to retry.

Moment.js to Temporal: A Migration Guide for 2026

Manish Prasad — Thu, 17 Sep 2026 00:00:00 +0530

TC39 moved Temporal to Stage 4 in March 2026, so it’s part of ECMAScript 2026. Node.js 26 shipped on May 5 with Temporal enabled by default. Chrome and Edge have had it since version 144 (January 2026), and Firefox since 139 (May 2025).

Whether to move off Date and Moment.js is settled. The open questions are practical ones. How do my Moment calls translate? Do I still need a polyfill? What happens to the dates in my JSON and my database?

This guide answers those in the order you’ll hit them. If you’re here for the Node 26 upgrade itself, the Node.js 26 upgrade guide covers type stripping, the ABI bump and the other breaking changes.

Should you migrate now?

New code: yes. Old code: gradually. Libraries: not yet.

On Node 26, Temporal costs nothing to use. In the browser, Safari and iOS Safari still don’t ship it outside Technology Preview, and caniuse puts global support at about 69%. Browser apps need a polyfill for now.

If you publish an npm package, a Temporal dependency sets a Node 26 floor for your users. Node 24 LTS is supported until April 2028, so most of them aren’t there yet.

Why `Date` had to be replaced

Date shipped in 1995, copied from Java’s java.util.Date. Java deprecated most of that class two years later. JavaScript kept it.

Its problems are well known. It’s mutable, so date.setMonth(13) changes every reference to that object. Months start at zero. new Date('2026-03-29') parses as UTC, but new Date(2026, 2, 29) parses as local time. The only time zone information is getTimezoneOffset(), a minute count that knows nothing about IANA zones like Europe/London or when DST starts. Precision stops at milliseconds.

The test suites show the difference in scope. According to Igalia, test262 has 594 tests for Date and about 4,500 for Temporal.

Moment, date-fns, Luxon and Day.js all exist to work around Date. Temporal replaces it.

The Temporal types

Temporal is a global namespace, like Math or Intl. Date uses one object for every date and time concept. Temporal gives each concept its own type:

Type	Represents	Use it for
`Temporal.Instant`	An exact point in time (epoch nanoseconds)	Log timestamps, `createdAt`, elapsed time
`Temporal.ZonedDateTime`	An instant plus an IANA time zone	Meetings, reminders, anything that crosses DST
`Temporal.PlainDate`	A calendar date with no time or zone	Birthdays, due dates, holidays
`Temporal.PlainTime`	A wall-clock time	“Store opens at 09:00”
`Temporal.PlainDateTime`	Date and time, no zone	Form input before you know the user’s zone
`Temporal.PlainYearMonth`	A year and month	Billing periods, card expiry
`Temporal.Duration`	A length of time	SLAs, retry windows, “1 year 2 months”

Non-Gregorian calendars are string IDs, not a type. Early versions of the proposal had Temporal.Calendar and Temporal.TimeZone classes; both were removed in 2024. You now write date.withCalendar('hebrew') and read zdt.timeZoneId.

Every Temporal object is immutable:

javascript

const invoiceDate = Temporal.PlainDate.from('2026-08-18');
const due = invoiceDate.add({ days: 30 });

due.toString();          // '2026-09-17'
invoiceDate.toString();  // '2026-08-18', unchanged

Time zone conversion needs no extra package, because the runtime ships the IANA database:

javascript

const call = Temporal.ZonedDateTime.from('2026-10-05T09:00[Asia/Tokyo]');
call.withTimeZone('Europe/London').toString();
// '2026-10-05T01:00:00+01:00[Europe/London]'

Moment.js, date-fns, Day.js, Luxon or Temporal?

Sizes are min+gzip from Bundlephobia.

	Moment.js	date-fns 4	Day.js	Luxon	Temporal
Status	Maintenance mode	Active	Active	Active	ES2026 standard
Size	20.3 kB, plus locales	17.5 kB full; far less per function	3.1 kB core, plus plugins	21.9 kB	0 on Node 26, Chrome, Firefox; ~19 kB polyfill elsewhere
Immutable	No	Yes (returns new `Date`s)	Yes	Yes	Yes
Time zones	`moment-timezone`	`@date-fns/tz`	Plugin	Built in	Built in
Non-Gregorian calendars	No	No	No	Via `Intl`	Yes
Types	Bundled	Bundled	Bundled	`@types/luxon`	TypeScript 6.0 `lib`
Token formatting (`YYYY-MM-DD`)	Yes	Yes	Yes	Yes	No; `Intl` only

Here’s how I’d choose:

New Node 26 service: Temporal. No dependency.
New browser app: Temporal plus temporal-polyfill, loaded only where it’s missing. If ~19 kB for Safari users is too much, use date-fns 4 with @date-fns/tz and revisit once Safari ships.
Existing Moment app: migrate module by module (steps below). Moving to Day.js first is only worth it if bundle size is the immediate problem, since you’d migrate twice.
Heavy time zone or calendar logic: Temporal. That’s the case it was designed for.
Existing date-fns or Luxon app: no rush. Both are maintained. Write new code in Temporal and let the old code age out.

Moment’s maintainers have called it a legacy project since 2020. It still gets time zone data updates and fixes, but no new features, no ES modules and no tree-shaking. Keeping it in a legacy app is fine. Adding new Moment code isn’t.

Moment and date-fns to Temporal: cheat sheet

This is the table most people are looking for. date is a PlainDate, zdt a ZonedDateTime and inst an Instant.

Task	Moment.js	date-fns	Temporal
Now	`moment()`	`new Date()`	`Temporal.Now.zonedDateTimeISO()`
Now, UTC timestamp	`moment.utc()`	`new Date()`	`Temporal.Now.instant()`
Today’s date	`moment().startOf('day')`	`startOfToday()`	`Temporal.Now.plainDateISO()`
Parse ISO date	`moment('2026-03-29')`	`parseISO('2026-03-29')`	`Temporal.PlainDate.from('2026-03-29')`
Parse in a zone	`moment.tz('2026-03-29 09:00', 'Europe/London')`	`new TZDate(2026, 2, 29, 9, 'Europe/London')`	`Temporal.ZonedDateTime.from('2026-03-29T09:00[Europe/London]')`
Add	`m.add(7, 'days')` (mutates)	`addDays(d, 7)`	`date.add({ days: 7 })`
Subtract	`m.subtract(1, 'month')`	`subMonths(d, 1)`	`date.subtract({ months: 1 })`
Start of day	`m.startOf('day')`	`startOfDay(d)`	`zdt.startOfDay()`
Start of month	`m.startOf('month')`	`startOfMonth(d)`	`date.with({ day: 1 })`
End of month	`m.endOf('month')`	`endOfMonth(d)`	`date.with({ day: date.daysInMonth })`
Difference in days	`b.diff(a, 'days')`	`differenceInCalendarDays(b, a)`	`a.until(b).days`
Difference in hours	`b.diff(a, 'hours', true)`	`differenceInHours(b, a)`	`a.until(b).total({ unit: 'hour' })`
Is before	`a.isBefore(b)`	`isBefore(a, b)`	`Temporal.PlainDate.compare(a, b) < 0`
Same day	`a.isSame(b, 'day')`	`isSameDay(a, b)`	`a.toPlainDate().equals(b.toPlainDate())`
Convert zone	`m.tz('Asia/Tokyo')`	`d.withTimeZone('Asia/Tokyo')` (`TZDate`)	`zdt.withTimeZone('Asia/Tokyo')`
ISO string	`m.format('YYYY-MM-DD')`	`format(d, 'yyyy-MM-dd')`	`date.toString()`
Display format	`m.format('D MMM YYYY')`	`format(d, 'd MMM yyyy')`	`date.toLocaleString('en-GB', { dateStyle: 'medium' })`
Epoch ms	`m.valueOf()`	`d.getTime()`	`inst.epochMilliseconds`
From a `Date`	`moment(d)`	n/a	`d.toTemporalInstant()`
Relative time	`m.fromNow()`	`formatDistanceToNow(d)`	No built-in; see below

Two things catch everyone the first time.

Comparison operators throw. Temporal objects have no usable valueOf(), so a < b raises a TypeError instead of quietly comparing strings. Use Temporal.X.compare(a, b) for sorting and .equals() for equality:

javascript

invoices.sort((a, b) => Temporal.PlainDate.compare(a.dueOn, b.dueOn));

until() and since() return a Duration. A PlainDate difference is in days by default. For other units, pass largestUnit or call .total():

javascript

const start = Temporal.PlainDate.from('2026-01-15');
const end = Temporal.PlainDate.from('2026-09-17');

start.until(end).days;                              // 245
start.until(end, { largestUnit: 'month' }).toString(); // 'P8M2D'

Formatting without tokens

Temporal has no format('YYYY-MM-DD'). For machine-readable output, toString() already returns ISO 8601. For display, toLocaleString() passes your options to Intl.DateTimeFormat:

javascript

const zdt = Temporal.ZonedDateTime.from('2026-09-17T14:30[Asia/Kolkata]');

zdt.toLocaleString('en-IN', { dateStyle: 'long', timeStyle: 'short' });
// '17 September 2026 at 2:30 pm'

The exact output depends on the ICU data in your runtime, so don’t assert on formatted strings in tests.

If your UI depends on dozens of custom format strings, keep a small formatting module that wraps Intl.DateTimeFormat instances. Creating a formatter is slower than calling one, so cache them by locale and options.

Relative time: `fromNow()`

Intl.RelativeTimeFormat does the wording. You pick the unit:

javascript

const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
const UNITS = ['years', 'months', 'days', 'hours', 'minutes', 'seconds'];

export function fromNow(zdt, now = Temporal.Now.zonedDateTimeISO(zdt.timeZoneId)) {
  const diff = zdt.since(now, { largestUnit: 'year', smallestUnit: 'second' });
  const unit = UNITS.find((u) => diff[u] !== 0) ?? 'seconds';
  return rtf.format(diff[unit], unit.slice(0, -1));
}

const now = Temporal.ZonedDateTime.from('2026-09-17T10:00[Europe/London]');
fromNow(now.subtract({ minutes: 3 }), now); // '3 minutes ago'
fromNow(now.add({ days: 1 }), now);         // 'tomorrow'

Pass now explicitly when you compare against a value derived from the current time. Otherwise the clock moves between the two reads, and “1 day from now” prints as “in 23 hours”.

This truncates: 1 month and 20 days prints as “last month”. If you need Moment’s rounding thresholds, round the duration with diff.round({ largestUnit: unit, smallestUnit: unit, relativeTo: now }) before formatting.

TypeScript setup

TypeScript 6.0 added Temporal types. Include them through lib:

json

{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["esnext", "dom"]
  }
}

For narrower libs, esnext.temporal adds the namespace and esnext.date adds Date.prototype.toTemporalInstant(). On TypeScript 5.x, the temporal-spec package supplies the types. See TypeScript 6.0 breaking changes if you haven’t upgraded yet.

Pick a polyfill

There are two, and they behave differently.

	`temporal-polyfill` (FullCalendar)	`@js-temporal/polyfill`
Version	1.0.x	0.5.x, labelled alpha
Size (min+gzip)	~19 kB (~23 kB with all calendars)	~52 kB
Installs a global	Yes, via `temporal-polyfill/global`, and only if `Temporal` is missing	No; you import `Temporal` from the package
Calendars	ISO and Gregorian by default; others from `/full`	All

For an app, temporal-polyfill/global is the one to use. It does nothing where Temporal is native, so Node 26 and Chrome users run the engine’s version.

The import still adds bytes to every user’s bundle. To ship it only to browsers that need it, load it on demand at your entry point:

javascript

// src/temporal.js - import this before anything that uses Temporal
if (typeof globalThis.Temporal === 'undefined') {
  await import('temporal-polyfill/global');
}

That relies on top-level await, so the entry must be an ES module. If you’re still on CommonJS or UMD, the ESM migration guide covers the switch.

Avoid @js-temporal/polyfill on Node 26. It never checks for the native global, so you end up with two Temporal implementations whose objects fail instanceof checks against each other.

JSON and database boundaries

Temporal objects serialize to strings. JSON.stringify calls toJSON(), which emits RFC 9557 strings such as 2026-09-17T09:00:00Z or 2026-09-17T14:30:00+05:30[Asia/Kolkata]. JSON.parse gives you those strings back, not Temporal objects. Revive them by key:

javascript

const REVIVERS = {
  createdAt: Temporal.Instant,
  dueOn: Temporal.PlainDate,
  meetingAt: Temporal.ZonedDateTime,
};

export const parseApiBody = (text) =>
  JSON.parse(text, (key, value) =>
    typeof value === 'string' && REVIVERS[key] ? REVIVERS[key].from(value) : value
  );

If you already validate request bodies, do the conversion in the schema. A Zod .transform() or a Joi custom rule works; see Joi vs Zod input validation.

Database drivers don’t know about Temporal. The MongoDB driver and pg both expect Date. Store by type:

Instant or ZonedDateTime: store a Date from new Date(inst.epochMilliseconds). Keep the zone ID in a separate field if you need to show the time in the user’s zone later. MongoDB TTL indexes only work on BSON Date fields, so this matters for expiring documents.
PlainDate: store the YYYY-MM-DD string or a SQL date column. Storing it as midnight UTC reintroduces the off-by-one-day bug you’re migrating away from.
Reading back: row.createdAt.toTemporalInstant().

In Mongoose, getters and setters on the schema path keep this out of your services. The Node.js 26 guide has the full conversion snippet.

Testing code that calls `Temporal.Now`

Tests that depend on the current time are flaky, with or without Temporal. The clean fix is to pass the clock in:

javascript

export function isOverdue(invoice, today = Temporal.Now.plainDateISO()) {
  return Temporal.PlainDate.compare(invoice.dueOn, today) < 0;
}

// test
assert.equal(isOverdue(invoice, Temporal.PlainDate.from('2026-10-01')), true);

For code you can’t change yet, replace the method for one test. With Node’s built-in node:test runner:

javascript

import { test } from 'node:test';

test('overdue after due date', (t) => {
  t.mock.method(Temporal.Now, 'plainDateISO', () => Temporal.PlainDate.from('2026-10-01'));
  // ...
});

Don’t assume fake-timer utilities cover Temporal. Many of them patch Date and the timer functions only, so check yours before trusting a green test.

Migrating an existing codebase

You don’t need a rewrite. This is the order I’d follow.

1. Add the polyfill and types. Browser apps need the loader above. Node 26 services need nothing. Set lib as shown in the TypeScript section.

2. Block new Moment imports. no-restricted-imports in ESLint states the rule and the reason:

javascript

// eslint.config.js
export default [
  {
    rules: {
      'no-restricted-imports': ['error', {
        paths: [
          { name: 'moment', message: 'Use Temporal. See src/lib/dates.js.' },
          { name: 'moment-timezone', message: 'Use Temporal.ZonedDateTime.' },
        ],
      }],
    },
  },
  { files: ['src/legacy/**'], rules: { 'no-restricted-imports': 'off' } },
];

3. Find where date code lives. Usage tends to cluster in a few utility, billing and reporting modules. Count imports per file:

bash

git grep -cE "from ['\"](moment|moment-timezone|date-fns|dayjs|luxon)" -- src \
  | sort -t: -k2 -nr | head -20

4. Rewrite the utility layer first. Change the internals of formatDate(), addBusinessDays() and parseUserDate() and keep their signatures. If they take and return Date, convert inside with toTemporalInstant() and epochMilliseconds. Call sites don’t change, so the diff stays reviewable.

5. Fix the call sites that already have bugs. Search your issue tracker for “timezone”, “DST” and “off by one day”. Those are the places where Temporal fixes something rather than just changing syntax, and they’re worth a close review.

6. Remove the dependency. When the grep from step 3 returns nothing, uninstall Moment (and moment-timezone) in one PR. Leave the polyfill in until Safari ships Temporal and your analytics show old browsers are gone.

What Temporal doesn’t cover

Temporal handles date arithmetic and time zones. Some jobs stay with Intl:

Need	Use
“3 minutes ago”	`Intl.RelativeTimeFormat` (helper above)
Localized dates	`toLocaleString()` / `Intl.DateTimeFormat`
“2 hours, 5 minutes”	`duration.toLocaleString()` (`Intl.DurationFormat`)
Parsing “next Tuesday” or `03/04/26`	Your own parser or a library; `from()` accepts ISO 8601 / RFC 9557 only

Node.js v26 Upgrade: Temporal by Default, Type Stripping. Breaking changes and a pre-upgrade scanner script.
TypeScript 6.0 Breaking Changes & New Features Explained. The release that added Temporal types.
From AMD/UMD to ESM: A No-Nonsense Migration Guide. Needed for the conditional polyfill loader.
Guide to Node.js Timers: setTimeout, setImmediate & nextTick. The other half of time in Node: scheduling rather than dates.
Structured Logging in Node.js with Pino. Where Instant timestamps end up.

✨ Thank you for reading and I hope you find it helpful. I sincerely request for your feedback in the comment’s section.

Worker Threads vs Cluster vs Child Process in Node.js

Manish Prasad — Wed, 16 Sep 2026 00:00:00 +0530

A request comes in, one function spends 400 ms on the CPU, and every other request waits behind it. p99 drifts away from p50. Then someone opens a “Scaling Strategy” doc, and the first line asks whether to use worker threads or cluster.

That’s the wrong question. The two tools fix different problems, and production apps often run both. This post measures what each option costs, shows a worker pool and cluster setup I’d put in production, and ends with a decision table you can paste into that doc.

Quick answer

Use cluster (or more container replicas) to handle more requests per second on a multi-core machine.
Use worker_threads when a single function blocks the event loop for tens of milliseconds or more: hashing, image resizing, PDF rendering, parsing a 20 MB JSON body.
Use child_process to run something that isn’t your Node app, like ffmpeg, a Python script or untrusted code, or anything that must be able to crash without taking your server down.

If you’re asking because the API feels slow, profile it first. Worker threads do nothing for I/O-bound work. When the time goes to database queries or HTTP calls, the event loop is already handling it well, and the fix is in the query or the connection pool.

At a glance

	`worker_threads`	`cluster`	`child_process`
Unit	OS thread, same process	OS process (a `fork`)	OS process
Runs	JavaScript from your app	Copies of your server	Any executable
Shared memory	Yes, `SharedArrayBuffer`	No	No
Messaging	`postMessage`, transferables	IPC channel	IPC (`fork`) or stdio
Idle memory (measured)	~10 MB	~46 MB	~46 MB (`fork`)
A crash takes down	the worker, unless handled	one worker process	the child only
Fixes	Latency (a blocked loop)	Throughput	Isolation

Is Node.js single-threaded?

Your JavaScript is. The process isn’t.

libuv keeps a thread pool, four threads by default and resizable with UV_THREADPOOL_SIZE, for filesystem calls, DNS lookups, zlib and some crypto. Your own code runs on one thread inside one event loop. If the event loop is new to you, read how the Node.js event loop works before going further.

That leaves two ways to get into trouble:

You block the loop. A synchronous, CPU-bound function stalls every open connection. That shows up as latency.
You saturate the loop. No single call takes long, but one core can’t keep up with the total work. That shows up as a throughput ceiling.

Each tool targets one of these. cluster runs N copies of your server that share a listening socket, which raises throughput. worker_threads moves the blocking function off the loop but keeps it in your process, which fixes latency. child_process runs something else as a separate process that can die without taking you with it.

Most scaling docs go wrong by treating these two problems as one.

How each primitive works

child_process

child_process starts a separate OS process with its own V8 instance, heap and event loop. There are four ways to create one:

Function	Uses a shell	stdout	IPC channel
`spawn`	no	streamed	no
`exec`	yes	buffered	no
`execFile`	no	buffered	no
`fork`	no	streamed	yes (`process.send`)

fork is spawn specialised for running another Node script with a message channel attached. Its default serialization is slow for binary data, as Benchmark 5 shows.

Streamed stdout is a Readable stream, so large outputs from spawn follow the usual backpressure rules. Buffered output from exec stops at maxBuffer (1 MB by default), and the child is killed if it writes more.

Security note: exec runs your command through a shell. If any part of the command string comes from user input, you have a command injection bug. Use execFile with an argument array, and validate the input anyway. The Node.js security checklist covers the rest.

cluster

cluster is child_process.fork() plus one addition: every worker can accept connections on the same port. I covered the basics and the IPC messages in clustering and IPC in Node.js. This section covers what changes in production.

On every platform except Windows, the default scheduling policy is SCHED_RR. The primary process owns the listening socket, accepts each connection and passes it to a worker in round-robin order. With SCHED_NONE, every worker calls accept() on the shared socket and the kernel picks the winner. That skips a hop, but the kernel tends to favour whichever worker was idle a moment ago, so under bursty traffic the load spreads less evenly.

Workers share nothing. No memory, no module-level variables, no in-process cache. An in-memory Map cache becomes N caches that disagree with each other. A setInterval job runs N times.

Do you still need cluster with PM2 or Kubernetes?

Usually not. PM2’s cluster mode is the cluster module with restarts and log handling added. On Kubernetes, ECS or another container platform, the common pattern is one Node process per container, with the orchestrator handling replicas, restarts and rolling deploys. Adding cluster inside that gives you two supervisors that don’t know about each other. PM2 inside Docker inside Kubernetes gives you three.

cluster still makes sense on a VM or bare-metal box where nothing else supervises your process, or when pod count is fixed and each pod gets several cores. The code later in this post is written for that case.

worker_threads

A worker thread is a real OS thread inside your process, with its own V8 isolate and event loop. Each isolate has its own heap, so by default there are no shared JS objects and no data races on your arrays. Data moves between threads in three ways:

postMessage copies the value using the structured clone algorithm.
Transferables hand over an ArrayBuffer with no copy, and the sender loses access to it.
SharedArrayBuffer is actual shared memory, coordinated with Atomics.

The third option is the one only threads have. It is also the only one of the three that can give you a data race:

// Both threads see the same 4 bytes. Atomics.add is atomic; counter[0]++ is not.
const shared = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT);
const counter = new Int32Array(shared);

const worker = new Worker('./counter.worker.js', { workerData: shared });
Atomics.add(counter, 0, 1);

Worker threads don’t speed up fs or network calls. Those already leave the main thread through libuv, so moving them to a worker only adds messaging cost.

The benchmarks

Test machine: Node v22.22.2, Linux, Intel Xeon @ 2.10 GHz. Numbers are p50 unless noted.

Caveat: this machine has 1 vCPU. I didn’t benchmark throughput scaling because four workers on one core only compete with each other, and any speedup figure would be wrong. Instead I measured costs that don’t depend much on core count: startup time, memory and message passing. The throughput harness is in the repo, and the section after the code explains what to look for when you run it on multi-core hardware.

Benchmark 1: Startup cost

Time from creating the worker or child to receiving its first message, over 20 runs:

Primitive	min	p50	p95
`worker_threads`	26.5 ms	32.6 ms	91.3 ms
`child_process.fork`	24.2 ms	29.3 ms	57.5 ms

I expected threads to start faster, since they skip fork/exec and don’t load a new process image. On one core they came out even. A new worker still has to build a V8 isolate, and with a single core that work can’t run in parallel with anything else.

The ranking matters less than the scale. Both take tens of milliseconds. If your endpoint normally answers in 5 ms, you can’t create a worker for each request. You need a pool. The mistake I see most often is new Worker() inside a route handler, which turns a 5 ms endpoint into a 40 ms one.

Benchmark 2: Memory per instance

Four idle instances, with RSS summed across the process tree:

Primitive	Per instance	4 instances, total
`worker_threads`	10.0 MB	92 MB
`child_process.fork`	45.9 MB	236 MB

Of all five results, this one depends least on the hardware, and it has the biggest practical effect. A forked process carries a whole Node runtime: bootstrap code, built-in modules and everything else. A worker thread shares the process’s code and native structures and pays mainly for its isolate and stack.

For a container, that means a 4-worker cluster uses about 180 to 230 MB before your app allocates anything. In a 512 MB container, that’s most of your memory. Four worker threads cost about 40 MB. The Node.js memory management guide explains how to read these RSS numbers.

Benchmark 3: Round-trip message latency

2,000 round trips of a small message:

Primitive	p50	p99
`worker_threads`	0.013 ms	0.099 ms
`child_process`	0.027 ms	0.792 ms

Threads were 2x faster at the median and 8x faster at p99. The difference in the tail comes from the transport. The child process channel is a real pipe, subject to kernel buffering and scheduling. A worker’s postMessage is a memory operation followed by a wakeup of the event loop.

If your design sends many small messages per task, this gap adds up quickly.

Benchmark 4: Moving 16 MB

Method	p50
`worker.postMessage(buf)`, structured clone	66.7 ms
`worker.postMessage(buf, [buf])`, transferable	0.12 ms
`child.send({ buf })`, base64 over JSON IPC	376.6 ms

Transferring the same buffer was 555x faster than copying it. A transfer only hands over a pointer. Afterwards the sender’s ArrayBuffer is detached and its byteLength is 0. A copy does a real memcpy plus the structured-clone bookkeeping.

If threads pass image buffers, parsed files or columnar data to each other, use transferables. At this size, copying makes the design unusable.

Benchmark 5: One option, 73x faster

fork() takes a serialization option, and the default is 'json'. Sending a 4 MB Buffer:

`serialization`	p50
`'json'` (default)	688.21 ms
`'advanced'`	9.43 ms

In JSON mode, a Buffer serialises to {"type":"Buffer","data":[7,7,7,...]}: four million numbers written out as text and then parsed back. 'advanced' uses V8’s structured-clone serializer. It handles binary data natively and keeps Map, Set, Date, BigInt and typed arrays intact instead of converting them to plain objects or strings.

// Set this on any fork() that sends more than small JSON messages.
const child = fork('./worker.js', [], { serialization: 'advanced' });

It isn’t faster for everything. For tiny payloads like booleans, short strings and small objects, JSON is about 1.3x faster in execa’s measurements. That’s a few microseconds against hundreds of milliseconds in the case above, so I’d still use 'advanced' for new code.

The repo

The layout below lets you clone and run everything. Benchmark scripts are under bench/, and the reusable production code is under src/.

node-parallelism-bench/
├── package.json
├── tsconfig.json
├── src/
│   ├── pool/
│   │   ├── worker-pool.ts        # reusable worker_threads pool
│   │   └── pool.worker.ts        # worker entry point
│   ├── tasks/
│   │   └── cpu-task.ts           # the CPU-bound work under test
│   └── server/
│       ├── cluster.ts            # cluster primary + graceful shutdown
│       └── app.ts                # the Express app itself
└── bench/
    ├── spawn-cost.mjs
    ├── mem-cost.mjs
    ├── ipc-latency.mjs
    └── throughput.mjs            # run this one on real hardware

The TypeScript is compiled with tsc. On newer Node versions you can run it directly using type stripping once you rename the worker imports to .ts.

src/tasks/cpu-task.ts

Put the actual work in a plain module with no dependencies. It shouldn’t care whether it runs on the main thread, in a worker or in a cluster child. That’s what lets you unit-test it without starting any threads.

// src/tasks/cpu-task.ts
import { createHash } from 'node:crypto';

export interface HashRequest {
  readonly payload: string;
  readonly rounds: number;
}

export interface HashResult {
  readonly digest: string;
  readonly rounds: number;
  readonly durationMs: number;
}

/**
 * Deliberately CPU-bound and synchronous. Stands in for whatever
 * your real blocking function is: image resize, PDF render,
 * regex over a large document, JSON.parse of a 20 MB body.
 */
export function iteratedHash({ payload, rounds }: HashRequest): HashResult {
  const start = performance.now();
  let current = payload;

  for (let i = 0; i < rounds; i++) {
    current = createHash('sha256').update(current).digest('hex');
  }

  return {
    digest: current,
    rounds,
    durationMs: performance.now() - start,
  };
}

src/pool/pool.worker.ts

The worker entry point is short. It unpacks a message, calls the function and sends back the result. Errors go back as messages rather than being thrown, because an uncaught exception terminates the worker thread. Failing one task is cheaper than losing a pool member. The same idea runs through error handling patterns for Node.js.

// src/pool/pool.worker.ts
import { parentPort } from 'node:worker_threads';
import { iteratedHash, type HashRequest } from '../tasks/cpu-task.js';

if (!parentPort) {
  throw new Error('pool.worker.ts must be run as a worker thread');
}

export interface TaskEnvelope {
  readonly id: number;
  readonly request: HashRequest;
}

export type ResultEnvelope =
  | { readonly id: number; readonly ok: true; readonly value: unknown }
  | { readonly id: number; readonly ok: false; readonly error: string };

parentPort.on('message', (task: TaskEnvelope) => {
  try {
    const value = iteratedHash(task.request);
    parentPort!.postMessage({ id: task.id, ok: true, value } satisfies ResultEnvelope);
  } catch (err) {
    parentPort!.postMessage({
      id: task.id,
      ok: false,
      error: err instanceof Error ? err.message : String(err),
    } satisfies ResultEnvelope);
  }
});

src/pool/worker-pool.ts

Pools are easy to get subtly wrong. This one needs a fixed set of workers created once, a task queue, a promise for each task, timeouts, replacement of crashed workers and a clean shutdown.

// src/pool/worker-pool.ts
import { Worker } from 'node:worker_threads';
import { fileURLToPath } from 'node:url';
import { availableParallelism } from 'node:os';
import type { ResultEnvelope, TaskEnvelope } from './pool.worker.js';

const WORKER_URL = new URL('./pool.worker.js', import.meta.url);

interface PendingTask {
  readonly envelope: TaskEnvelope;
  readonly resolve: (value: any) => void;
  readonly reject: (reason: Error) => void;
  timer?: NodeJS.Timeout;
}

export interface WorkerPoolOptions {
  /** Defaults to availableParallelism() - 1, floored at 1. Leave a core for the event loop. */
  readonly size?: number;
  /** Reject a task if a worker hasn't answered in this long. */
  readonly taskTimeoutMs?: number;
  /** Reject new work once the queue is this deep, instead of growing forever. */
  readonly maxQueueDepth?: number;
}

export class WorkerPool {
  readonly #workers: Worker[] = [];
  readonly #idle: Worker[] = [];
  readonly #queue: PendingTask[] = [];
  readonly #inFlight = new Map<number, PendingTask>();
  readonly #busyBy = new Map<Worker, number>();

  readonly #taskTimeoutMs: number;
  readonly #maxQueueDepth: number;
  readonly #size: number;

  #nextId = 0;
  #closing = false;

  constructor(options: WorkerPoolOptions = {}) {
    this.#size = options.size ?? Math.max(1, availableParallelism() - 1);
    this.#taskTimeoutMs = options.taskTimeoutMs ?? 30_000;
    this.#maxQueueDepth = options.maxQueueDepth ?? 1_000;

    for (let i = 0; i < this.#size; i++) this.#spawn();
  }

  #spawn(): void {
    const worker = new Worker(fileURLToPath(WORKER_URL));

    worker.on('message', (result: ResultEnvelope) => {
      const task = this.#inFlight.get(result.id);
      this.#inFlight.delete(result.id);
      this.#busyBy.delete(worker);

      if (task) {
        clearTimeout(task.timer);
        if (result.ok) task.resolve(result.value);
        else task.reject(new Error(result.error));
      }

      this.#idle.push(worker);
      this.#drain();
    });

    // A worker that dies takes its in-flight task with it. Fail that
    // task explicitly, then replace the worker so the pool keeps its size.
    worker.on('error', (err) => this.#retire(worker, err));
    worker.on('exit', (code) => {
      if (code !== 0 && !this.#closing) {
        this.#retire(worker, new Error(`worker exited with code ${code}`));
      }
    });

    this.#workers.push(worker);
    this.#idle.push(worker);
  }

  #retire(worker: Worker, cause: Error): void {
    // 'error' is followed by 'exit', and terminate() also fires 'exit'.
    // Only the first call for a given worker should do anything.
    const wi = this.#workers.indexOf(worker);
    if (wi === -1) return;
    this.#workers.splice(wi, 1);

    const ii = this.#idle.indexOf(worker);
    if (ii !== -1) this.#idle.splice(ii, 1);

    const taskId = this.#busyBy.get(worker);
    if (taskId !== undefined) {
      const task = this.#inFlight.get(taskId);
      this.#inFlight.delete(taskId);
      this.#busyBy.delete(worker);
      if (task) {
        clearTimeout(task.timer);
        task.reject(cause);
      }
    }

    void worker.terminate();
    if (!this.#closing) {
      this.#spawn();
      this.#drain();
    }
  }

  #drain(): void {
    while (this.#idle.length > 0 && this.#queue.length > 0) {
      const worker = this.#idle.pop()!;
      const task = this.#queue.shift()!;

      this.#inFlight.set(task.envelope.id, task);
      this.#busyBy.set(worker, task.envelope.id);

      task.timer = setTimeout(() => {
        this.#retire(worker, new Error(`task ${task.envelope.id} timed out`));
      }, this.#taskTimeoutMs);

      worker.postMessage(task.envelope);
    }
  }

  run<T>(request: TaskEnvelope['request']): Promise<T> {
    if (this.#closing) {
      return Promise.reject(new Error('pool is closing'));
    }
    if (this.#queue.length >= this.#maxQueueDepth) {
      // Backpressure. Shedding load here is far better than an OOM later.
      return Promise.reject(new Error('pool queue is full'));
    }

    return new Promise<T>((resolve, reject) => {
      this.#queue.push({
        envelope: { id: this.#nextId++, request },
        resolve,
        reject,
      });
      this.#drain();
    });
  }

  get stats() {
    return {
      size: this.#workers.length,
      idle: this.#idle.length,
      inFlight: this.#inFlight.size,
      queued: this.#queue.length,
    };
  }

  async close(): Promise<void> {
    this.#closing = true;
    for (const task of this.#queue) task.reject(new Error('pool closed'));
    this.#queue.length = 0;
    for (const task of this.#inFlight.values()) {
      clearTimeout(task.timer);
      task.reject(new Error('pool closed'));
    }
    this.#inFlight.clear();
    await Promise.all(this.#workers.map((w) => w.terminate()));
  }
}

Four details separate this from the typical tutorial pool.

maxQueueDepth. An unbounded queue turns a CPU problem into a memory problem, and the memory problem into a 3 a.m. page. Reject work early, the same way you’d batch and throttle async work elsewhere.

A timeout replaces the worker, not just the task. You can’t interrupt a worker stuck in an infinite loop, and terminate() is the only way to stop it. If you only reject the promise, the stuck thread stays in the pool and keeps using a core.

#retire checks whether it has already run. A crashing worker emits error and then exit, and terminate() emits exit as well. Without that check, one timeout would start two replacement workers, and the pool would grow a little with every failure.

The pool size is availableParallelism() - 1. The main thread still needs a core to accept connections. If the pool uses every core, the thread handling your I/O competes with the threads doing CPU work.

In containers, os.cpus().length returns the host’s core count, not your CPU quota. A pod limited to 500m on a 64-core node will happily start 63 workers. os.availableParallelism() (Node 18.14+) takes cgroup quotas and CPU affinity into account on most setups. Some libuv versions have reported it wrong under cgroups v2 (nodejs/node#58428), so log the value at startup.

Should you use Piscina instead? For most teams, yes. Piscina is a maintained pool with min/max thread counts, idle timeouts, cancellation through AbortSignal and queue limits. The pool above shows what such a library has to handle, so you know which options to set. Whichever you choose, keep the task module pure so switching later is easy. For cancellation, see the AbortController guide.

src/server/cluster.ts

In a cluster setup, the primary adds throughput and restarts workers that crash. Tutorials usually leave out graceful shutdown. If you kill workers in the middle of requests, those connections drop and show up as 502s on every deploy. For health checks and readiness during shutdown, see Express health checks and graceful shutdown.

// src/server/cluster.ts
import cluster from 'node:cluster';
import { availableParallelism } from 'node:os';
import process from 'node:process';

const WORKER_COUNT = Number(process.env.WEB_CONCURRENCY) || availableParallelism();
const SHUTDOWN_GRACE_MS = 15_000;

if (cluster.isPrimary) {
  console.log(`primary ${process.pid} starting ${WORKER_COUNT} workers`);

  for (let i = 0; i < WORKER_COUNT; i++) cluster.fork();

  // Restart crashed workers, but not during an intentional shutdown,
  // or you'll fork replacements forever while trying to exit.
  let shuttingDown = false;

  cluster.on('exit', (worker, code, signal) => {
    if (shuttingDown) return;
    console.error(`worker ${worker.process.pid} died (${signal || code}); restarting`);
    cluster.fork();
  });

  const shutdown = () => {
    if (shuttingDown) return;
    shuttingDown = true;

    for (const worker of Object.values(cluster.workers ?? {})) {
      worker?.send('shutdown');
    }

    // Backstop: if a worker ignores the request, kill it.
    setTimeout(() => {
      for (const worker of Object.values(cluster.workers ?? {})) worker?.kill('SIGKILL');
      process.exit(1);
    }, SHUTDOWN_GRACE_MS).unref();
  };

  process.on('SIGTERM', shutdown);
  process.on('SIGINT', shutdown);
} else {
  const { startServer } = await import('./app.js');
  const server = await startServer();

  process.on('message', (msg) => {
    if (msg !== 'shutdown') return;
    // Stop accepting new connections, let in-flight requests finish.
    server.close(() => process.exit(0));
  });
}

The primary sets no timers of its own until shutdown starts, so it exits on its own once every worker has gone. The .unref() backstop fires only if a worker ignores the shutdown message.

bench/throughput.mjs

Run this one on hardware with more than one core.

// bench/throughput.mjs
// Usage: node bench/throughput.mjs <baseline|pool|cluster> <concurrency> <duration-s>
import autocannon from 'autocannon';

const [mode = 'baseline', concurrency = '50', duration = '20'] = process.argv.slice(2);

const result = await autocannon({
  url: 'http://localhost:3000/hash?rounds=2000',
  connections: Number(concurrency),
  duration: Number(duration),
});

console.table({
  mode,
  rps: result.requests.average.toFixed(0),
  p50: `${result.latency.p50} ms`,
  p99: `${result.latency.p99} ms`,
  errors: result.errors,
});

What to expect for each mode:

Baseline, no parallelism. Throughput stays flat as you add connections. Latency grows in step with concurrency, because requests queue in front of the single event loop.
Worker pool. p99 drops sharply because the loop stays free to accept and answer requests. Throughput improves up to about cores - 1 workers and then levels off.
Cluster. Throughput grows almost linearly with cores until something shared becomes the bottleneck, usually the database connection pool and occasionally the network card. One slow request is still slow, because it still blocks its own event loop.
Cluster with a pool in each worker. For most CPU-heavy apps, this is the setup to run in production.

To see which mode you’re really in once this is live, track event-loop lag and pool queue depth. The Node.js monitoring guide shows how to export both.

Decision table

Your situation	Use	Why
Web server on a multi-core VM, mostly I/O-bound	cluster or PM2	Throughput grows with cores, and one crash doesn’t take down the others
Same server, but on Kubernetes or ECS	more replicas, one process per container	The orchestrator already restarts and scales processes
One function blocks the loop for more than ~50 ms	worker_threads pool	Fixes p99 without paying N times the memory
Moving large binary data between units of work	worker_threads + transferables	0.12 ms vs 377 ms for 16 MB
Need shared mutable state	worker_threads + SharedArrayBuffer	No other option shares memory
Running a non-Node binary (ffmpeg, pandoc, Python)	child_process.spawn	Different language, different process
Running untrusted or crash-prone code	child_process	A process boundary contains segfaults and native crashes
Task needs its own memory limit	child_process	OS-level limits apply per process; a worker’s `resourceLimits` caps only its JS heap
Long-running background work (cron, queue consumers)	separate deployment	It’s a deployment question, not a parallelism one; keep it out of the web process
CPU-heavy and high-throughput	cluster or replicas, plus a pool in each	Cores give throughput; threads keep latency down
Under ~10 ms of CPU per request	none of these	Startup and messaging cost more than the work; profile first

Five mistakes to avoid

1. Creating a worker per request. Workers and forked processes both take tens of milliseconds to start. Keep them in a pool.

2. Leaving serialization: 'json' on fork(). It was 73x slower for binary data in my test. Set it to 'advanced'.

3. Keeping state in memory under cluster. Rate-limit counters, LRU caches and setInterval jobs each exist N times. Move shared state to Redis or a shared SQLite cache, and use a distributed lock for scheduled jobs. Checking cluster.worker.id === 1 looks like it works, but worker IDs keep increasing after restarts, so once worker 1 crashes the job never runs again.

4. Using os.cpus().length in a container. It returns the host’s cores, not your quota. Use availableParallelism() or read /sys/fs/cgroup/cpu.max.

5. Running with an unbounded queue. A pool without a depth limit doesn’t fail outright. It gets slower until the OOM killer steps in. Reject load at a known threshold and return 503 with a Retry-After header.

Frequently Asked Questions

Is Node.js multithreaded? Your JavaScript runs on one thread per event loop. Node itself uses more threads: the libuv pool for file and DNS work, V8’s background threads for garbage collection and compilation, and any worker threads you create.

Are worker threads faster than cluster? They solve different problems. Worker threads start with less memory (10 MB vs 46 MB here) and pass messages 2 to 8x faster, but they don’t add request throughput on their own. Cluster does, by running the whole server several times.

Do worker threads help with database or API calls? No. I/O already runs off the main thread. Workers help only when your JavaScript is doing CPU-heavy work.

Can a worker thread crash the whole process? An uncaught exception ends only the worker, which emits error and then exit. Memory is different. resourceLimits caps only the worker’s JS heap, while Buffers and native allocations come out of the shared process memory. A worker that allocates too much of that memory can get the whole process killed. Use a child process when that matters.

How many workers should I create? Start with os.availableParallelism() - 1 for a CPU pool, and one cluster worker per core (or per CPU of pod quota). Then measure event-loop lag and queue depth and adjust from there.

Should I use cluster inside Docker or Kubernetes? Usually not. Run one process per container and scale with replicas. Use cluster only when a single container is given several cores and you can’t run more replicas.

Before you parallelise

Profile first. Run with --cpu-prof, or wrap the function you suspect in performance.now() calls. If requests spend 8 ms on the CPU, none of these tools will help, and the bottleneck is probably your database.

If they spend 400 ms, work through these in order:

Make the function faster. A 10x algorithmic improvement beats a 4x gain from parallelism, and it doesn’t cost 200 MB. The V8 optimization guide is a good place to start.
Use an async version if one exists. Callback-based crypto.pbkdf2 runs on the libuv pool, and zlib has async variants too. That gets you parallelism without adding anything.
Move the work off the loop with a worker pool.
Add cores with cluster or more replicas.

If you remember one number, make it 10 MB per worker thread vs 46 MB per child process. On memory-limited containers, that difference will shape your architecture more than any throughput chart.

Repo: node-parallelism-bench. It includes the benchmark harness, the pool and the cluster server. Run npm run bench:all on a machine with more cores than mine and open a PR with your numbers.

Understanding the Event Loop in Node.js. What “blocking the loop” means at the level of the loop’s phases.
Clustering and IPC in Node.js. The cluster basics and message passing between the primary and workers.
Node.js Memory Management. Reading RSS and heap numbers like the ones above.
Express Health Checks and Graceful Shutdown. Keeping deploys free of 502s.
Monitoring Node.js Applications. Event-loop lag and custom metrics for your pool.
Production Setup Best Practices. The rest of the production checklist.

Node.js v26 Upgrade: Temporal by Default, Type Stripping

Manish Prasad — Tue, 15 Sep 2026 00:00:00 +0530

Node.js 26 shipped on May 5, 2026 and becomes LTS in October. The changelog looks short: a date API, a stability promotion, a V8 bump and a handful of removals.

The catch is a deprecation warning many teams will see and can’t fix, because their own code doesn’t trigger it.

I’ve run 26 locally since release day. This guide covers what changed, what breaks and a script that checks your app before you switch.

Should you upgrade now?

Test now. Deploy after October.

Node 26 is a Current release until October, so it can still take breaking changes. LTS releases get only security and bug fixes. If you’re on Node 24 LTS, it’s supported through April 2028, so there’s no rush.

Upgrade early in two cases: you want Temporal in production, or you’re starting a new project that will ship after 26 reaches LTS.

Either way, run the scanner and add 26 to your CI matrix this month.

Node.js 26 at a glance


Released	May 5, 2026 (Current)
LTS	October 2026
V8	14.6.202.33 (Chromium 146)
Undici	8.0.2
ICU	78.3
`NODE_MODULE_VERSION`	147

New:

Temporal is enabled by default. No flag, no polyfill.
TypeScript type stripping is stable and on by default.
V8 14.6 adds Map.prototype.getOrInsert(), getOrInsertComputed() and Iterator.concat().

Breaking changes, ordered by how likely they are to hit you:

Change	Symptom	Fix
ABI bumped to 147	`ERR_DLOPEN_FAILED`	`rm -rf node_modules && npm ci`
`module.register()` deprecated (DEP0205)	Warning from your tooling	Upgrade the tool
`--experimental-transform-types` removed	Enums and decorators fail	Stay on `tsc`/`tsx`
`_stream_*` modules removed	`MODULE_NOT_FOUND`	Update the old dependency
`writeHeader()` removed	`TypeError`	Use `writeHead()`
Extensionless CJS in ESM packages	`require is not defined`	Rename to `.cjs`

Temporal: the new date API

Date has been a problem since 1995. It’s mutable and parses ambiguously. Its idea of a timezone is “UTC or whatever this machine calls local”, and months start at zero. That’s why moment, date-fns, dayjs and luxon exist.

Temporal is the standards-track replacement. It isn’t one type but a family, and most of the work is picking the right one.

Pick the right type

Type	Represents	Use it for
`Temporal.Instant`	An exact moment, no timezone	Timestamps, logs, elapsed time
`Temporal.ZonedDateTime`	A moment plus its timezone	Meetings, schedules, anything DST-sensitive
`Temporal.PlainDate`	A calendar date, no time or zone	Birthdays, invoice dates, holidays
`Temporal.Duration`	A length of time	SLAs, timeouts, offsets

javascript

const now = Temporal.Now.instant();
const meeting = Temporal.ZonedDateTime.from('2026-08-18T09:00[America/New_York]');
const invoiceDate = Temporal.PlainDate.from('2026-08-18');
const sla = Temporal.Duration.from({ hours: 48 });

The off-by-one-day bug goes away

new Date('2026-08-18') parses as UTC midnight, so a user in Los Angeles sees August 17th. Most of us have shipped this bug. A PlainDate has no time or timezone, so nothing can shift.

Temporal objects are also immutable. Arithmetic returns a new object:

javascript

const due = invoiceDate.add({ days: 30 });   // PlainDate 2026-09-17
invoiceDate.toString();                       // '2026-08-18' - unchanged

DST arithmetic is correct by default

ZonedDateTime knows that “24 hours later” and “tomorrow at the same time” are different things:

javascript

const beforeDST = Temporal.ZonedDateTime.from(
  '2026-11-01T01:30:00-04:00[America/New_York]'
);

beforeDST.add({ hours: 24 }).toString();
// 2026-11-02T00:30:00-05:00 - 24 real hours, wall clock moved 23
beforeDST.add({ days: 1 }).toString();
// 2026-11-02T01:30:00-05:00 - same wall clock, 25 real hours

With Date, you’d need a library for that, or a bug report six months later.

Comparison and elapsed time:

javascript

const overdue = Temporal.PlainDate.compare(due, Temporal.Now.plainDateISO()) < 0;

const elapsed = Temporal.Now.instant().since(requestStart);
logger.info({ ms: elapsed.total({ unit: 'millisecond' }) }, 'request complete');

Convert at the database boundary

Your database driver doesn’t know about Temporal. The MongoDB driver serialises Date to BSON Date, and pg maps timestamptz to Date. Keep Temporal in your domain logic and convert at the edges:

javascript

// Temporal → driver
const createdAt = new Date(zdt.epochMilliseconds);

// driver → Temporal
const zdt = someMongoDate
  .toTemporalInstant()
  .toZonedDateTimeISO(Temporal.Now.timeZoneId());

Date.prototype.toTemporalInstant() ships with Temporal as the official bridge.

Don’t rip out date-fns yet

Library authors: your consumers may still run Node 22 or 24. Using Temporal sets a hard Node 26 floor.
Polyfill users: @js-temporal/polyfill and temporal-polyfill install a global Temporal, and Node 26 now has a native one. If the polyfill doesn’t guard against this, part of your code gets the native version and part gets the shim, with different prototypes. Remove the polyfill during the upgrade, not after.

Start with new code. Use Temporal in your next feature and let old code age out. When you’re ready to move existing code, the Moment.js to Temporal migration guide maps Moment and date-fns calls to Temporal and covers polyfills, JSON and testing.

TypeScript type stripping

node server.ts now runs without a flag. Node replaces types with whitespace, so line numbers and stack traces stay accurate without source maps. --no-strip-types turns it off.

The breaking part: --experimental-transform-types has been removed, not deprecated. That flag handled TypeScript syntax that can’t simply be erased.

What works and what doesn’t

Construct	Under type stripping
`import type`, interfaces, annotations, generics	✅ Erased cleanly
`enum Foo { A, B }`	❌ Not supported
`namespace` with runtime values	❌ Not supported (type-only is fine)
Parameter properties, `constructor(private x: T)`	❌ Not supported
Decorators, `@Injectable()`	❌ Parser error
`.tsx` files	❌ Not supported
Import aliases	❌ Not supported

Three more limits:

tsconfig.json is ignored at runtime, so paths aliases and downlevelling don’t work.
TypeScript inside node_modules isn’t processed.
Imports need the .ts extension.

NestJS, TypeORM and decorator-heavy code

These frameworks depend on decorators and parameter properties. Node’s stripper will never run that code, because decorators aren’t a JavaScript feature yet and there’s nothing to erase them into.

That’s a design boundary, not a bug. Keep using tsc or tsx. The built-in stripper is for code that treats TypeScript as annotated JavaScript.

A tsconfig that matches Node

If you want to run .ts files on Node directly, make the compiler enforce the same rules:

json

{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "nodenext",
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "rewriteRelativeImportExtensions": true
  }
}

erasableSyntaxOnly makes tsc reject enums, namespaces and parameter properties, so CI catches them before production does.
verbatimModuleSyntax requires the type keyword on type-only imports. Node needs it because it erases by syntax and can’t tell what’s a type:

typescript

import type { User } from './user.ts';                   // ✅ erased
import { createUser, type UserInput } from './user.ts';  // ✅
import { User } from './user.ts';                        // 💥 runtime error - no such export

Smaller additions: Map upsert

V8 14.6 adds getOrInsert() and getOrInsertComputed() to Map and WeakMap. They replace a pattern most of us have typed many times:

javascript

// before
let bucket = groups.get(key);
if (!bucket) {
  bucket = [];
  groups.set(key, bucket);
}
bucket.push(item);

// Node 26
groups.getOrInsertComputed(key, () => []).push(item);

Use getOrInsert for a cheap literal default. Use getOrInsertComputed when building the default costs something; the callback runs only on a miss.

Breaking changes in detail

1. Native addons must be rebuilt

NODE_MODULE_VERSION is now 147. A .node binary built for Node 24 fails with ERR_DLOPEN_FAILED.

bash

npm rebuild
# or, cleanest:
rm -rf node_modules && npm ci

Docker images with a cached node_modules layer get hit hardest, and so do CI caches keyed only on the lockfile hash. Add the Node major version to the cache key.

2. DEP0205: a warning you can’t fix yourself

module.register() is deprecated in favour of module.registerHooks(). The async off-thread loader hooks were too complex to fix, so the replacement runs synchronously in the main thread.

You probably don’t call module.register(). Your tools do. The warning has been reported against Storybook, Cypress, Tailwind, Corepack and @sentry/node, so a clean codebase can print:

(node:41233) [DEP0205] DeprecationWarning: module.register() is
deprecated. Use module.registerHooks() instead.

register() still works; it only warns. The problem is CI with --throw-deprecation, which fails your build on code you can’t patch. Upgrade the tool, or keep that flag away from your dev toolchain.

If you maintain a loader, this is real work. registerHooks() accepts only synchronous hooks, so an async load hook that awaited readFile() must switch to sync I/O.

3. Legacy `_stream_*` modules removed

_stream_wrap, _stream_readable, _stream_writable, _stream_duplex, _stream_transform and _stream_passthrough are gone. They were never public, but old socket and proxy libraries still import _stream_wrap. The failure is a MODULE_NOT_FOUND at require time, so you’ll see it immediately.

4. `writeHeader()` removed

http.Server.prototype.writeHeader() was deprecated for years. Use writeHead().

5. Extensionless CommonJS in ESM packages

Extensionless files in a "type": "module" package no longer load as CommonJS. The usual victim is a CJS bin script with no extension, which now parses as ESM and fails on the first require(). Rename it to .cjs and update bin in package.json.

6. Behaviour changes worth testing

These won’t throw errors, but they can change results:

Streams: Readable now reads one buffer at a time. If you expect one .read() call to drain everything, loop it. for await, pipeline() and .pipe() are unaffected.
fetch: now runs on Undici 8. Check code that relies on exact error shapes or header casing.
Crypto: passing a CryptoKey to node:crypto APIs (DEP0203) and KeyObject.from() with a non-extractable CryptoKey (DEP0204) are deprecated. Convert to KeyObject explicitly.
localStorage: with the experimental web storage flags, it returns undefined when no backing file is set.

7. Building from source

The GCC minimum is 13.2 and Python 3.9 is dropped. This mostly affects node-gyp on old build images; an Ubuntu 20.04 builder won’t work.

Pre-upgrade scanner

Save this as node26-check.mjs in your project root and run node node26-check.mjs. It has no dependencies and checks for:

the Node version you’re running on
native addons that need a rebuild
removed and deprecated APIs in your source
TypeScript syntax that type stripping can’t handle
extensionless bin scripts in ESM packages

javascript

#!/usr/bin/env node
// node26-check.mjs - run with: node node26-check.mjs
import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
import { join, extname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';

const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next']);
const SRC = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts']);
const SELF = fileURLToPath(import.meta.url);
const findings = [];
const add = (level, code, msg, where) => findings.push({ level, code, msg, where });

function walk(dir, onFile) {
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const full = join(dir, entry.name);
    if (entry.isDirectory() && !SKIP.has(entry.name)) walk(full, onFile);
    else if (entry.isFile()) onFile(full);
  }
}

// 1. runtime
const major = Number(process.versions.node.split('.')[0]);
console.log(`node ${process.versions.node} · ABI ${process.versions.modules}\n`);
if (major < 26) add('warn', 'RUNTIME', `Scanning on Node ${major}. Re-run on 26.`, '-');

// 2. native addons need a rebuild (ABI 147)
if (existsSync('node_modules')) {
  const native = new Set();
  const scan = (dir) => {
    for (const e of readdirSync(dir, { withFileTypes: true })) {
      const full = join(dir, e.name);
      if (e.isDirectory()) scan(full);
      else if (extname(e.name) === '.node') {
        const [, a, b] = full.split('/');
        native.add(a.startsWith('@') ? `${a}/${b}` : a);
      }
    }
  };
  scan('node_modules');
  if (native.size) add('warn', 'ABI-147', `Rebuild native addons: ${[...native].join(', ')}`, 'node_modules');
}

// 3. removed & deprecated APIs in source
const PATTERNS = [
  [/require\(\s*['"]_stream_\w+['"]\s*\)/, 'fail', 'REMOVED', 'Legacy _stream_* module removed'],
  [/\.writeHeader\s*\(/, 'fail', 'REMOVED', 'writeHeader() removed - use writeHead()'],
  [/\bmodule\.register\s*\(/, 'warn', 'DEP0205', 'module.register() deprecated'],
  [/experimental-transform-types/, 'fail', 'REMOVED', '--experimental-transform-types removed'],
  [/@js-temporal\/polyfill|temporal-polyfill/, 'warn', 'TEMPORAL', 'Temporal polyfill may collide with native global'],
];
const TS_PATTERNS = [
  [/^\s*(export\s+)?(const\s+)?enum\s+\w+/m, 'fail', 'TS-ENUM', 'enum is not erasable'],
  [/^\s*(export\s+)?namespace\s+\w+/m, 'warn', 'TS-NAMESPACE', 'namespace with runtime values is not erasable'],
  [/constructor\s*\([^)]*\b(private|public|protected|readonly)\b/, 'fail', 'TS-PARAMPROP', 'Parameter properties are not erasable'],
  [/^\s*@[A-Z]\w*\s*\(/m, 'fail', 'TS-DECORATOR', 'Decorators are a parser error'],
];

walk('.', (full) => {
  const ext = extname(full);
  if (resolve(full) === SELF) return;
  if (ext === '.tsx') return add('warn', 'TS-TSX', '.tsx is not supported', full);
  if (!SRC.has(ext) || statSync(full).size > 512 * 1024) return;
  const src = readFileSync(full, 'utf8');
  const rules = ext.includes('ts') ? [...PATTERNS, ...TS_PATTERNS] : PATTERNS;
  for (const [re, level, code, msg] of rules) if (re.test(src)) add(level, code, msg, full);
});

// 4. extensionless bin in an ESM package
if (existsSync('package.json')) {
  const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
  if (pkg.type === 'module' && pkg.bin) {
    const bins = typeof pkg.bin === 'string' ? [pkg.bin] : Object.values(pkg.bin);
    for (const b of bins) {
      if (!extname(b)) add('fail', 'EXTLESS-CJS', `bin "${b}" has no extension - now parsed as ESM`, 'package.json');
    }
  }
}

// report
findings.sort((a, b) => (a.level === 'fail' ? -1 : 1) - (b.level === 'fail' ? -1 : 1));
for (const f of findings) console.log(`${f.level.toUpperCase()}  [${f.code}] ${f.msg}\n      ${f.where}`);
const fails = findings.filter((f) => f.level === 'fail').length;
console.log(`\n${fails} blocking · ${findings.length - fails} to review`);
process.exit(fails ? 1 : 0);

Sample output:

node 26.0.0 · ABI 147

FAIL  [TS-ENUM] enum is not erasable
      src/status.ts
WARN  [ABI-147] Rebuild native addons: bcrypt
      node_modules

1 blocking · 1 to review

It’s a pattern match, not a type checker. A decorator-shaped comment gives a false positive, and it can’t see into your dependencies’ source or into fetch behaviour changes. A clean run means “no obvious blockers”. Your test suite covers the rest.

Upgrade checklist

1. Run the scanner on your current branch. Fix every FAIL line before switching runtimes.

2. Switch locally and reinstall from scratch.

bash

nvm install 26 && nvm use 26
rm -rf node_modules && npm ci

Don’t skip the clean install. A stale node_modules causes ABI failures that look like bugs in your code.

3. Run tests with warnings visible.

bash

NODE_OPTIONS="--trace-warnings --trace-deprecation" npm test

Leave out --throw-deprecation for now. It will fail on DEP0205 from your tooling.

4. Add 26 to the CI matrix. Keep 24.

yaml

strategy:
  matrix:
    node-version: [22, 24, 26]

Add the Node version to your dependency cache key while you’re there.

5. Deploy to staging, then a canary. Watch RSS and event-loop lag for a full traffic cycle before rolling out wider. A major V8 bump changes garbage collection behaviour, and that only shows up under real load.

Moment.js to Temporal: A Migration Guide for 2026. API mappings, polyfill choice and a step-by-step migration.
Understanding the Event Loop in Node.js. The internals worth knowing before you profile anything.
Running TypeScript in Node.js. Where type stripping fits in the toolchain.
Node.js 24: The Game Changer Release. The LTS most teams are upgrading from.
Node.js Memory Management. Useful when you’re watching RSS through a V8 bump.

✨ Thank you for reading and I hope you find it helpful. I sincerely request for your feedback in the comment’s section.

Try-Catch Everywhere? 4 Patterns Senior Devs Use Instead

Manish Prasad — Mon, 13 Jul 2026 00:00:00 +0530

I joined a startup two years ago. The codebase had try-catch blocks wrapping every single function: routes, services, models, utils. Everything. The team called it “safe coding.”

It was not safe. Within three months, we had three production incidents where errors vanished silently. No logs, no alerts, no way to know something broke until a customer complained. The try-catch blocks did not protect us. They hid the problems from us.

Wrapping everything in try-catch is not defensive programming. It is fear-based programming. Senior developers do not reach for try-catch first. They reach for it last, only when it is the only right tool for the job.

Why Junior Devs Default to Try-Catch

It makes sense on the surface. Something might fail? Wrap it. Linter complains? Add a catch block. The tutorial shows a try-catch. Copy it.

Try-catch is a reactive tool, not a preventive one. Every time you wrap code in try-catch, you are saying: “I do not know what will go wrong here, so I will just catch whatever happens.”

Senior devs ask a different question first: can I prevent this from going wrong in the first place?

Also read Node.js Error Handling: Strategies for Production Applications for the wider picture on classification, global handlers and monitoring.

Pattern 1: Validate First, Catch Never

The most common reason junior devs add try-catch is to handle invalid input. A null value comes in, something breaks, and the catch block saves the day.

javascript

// ❌ WRONG - Catching what validation should have prevented
app.post('/users', (req, res) => {
  try {
    const user = userService.create(req.body);
    res.status(200).json(user);
  } catch (error) {
    if (error instanceof TypeError || error.message.includes('null')) {
      res.status(400).json({ error: 'Bad request' });
    } else {
      res.status(500).json({ error: 'Server error' });
    }
  }
});

What Senior Devs Do Instead

Validate at the door with a schema library like Joi or Zod. Nothing bad gets inside.

javascript

// ✅ CORRECT - Validate at the door
const Joi = require('joi');

const userSchema = Joi.object({
  name: Joi.string().required().messages({ 'any.required': 'Name is required' }),
  email: Joi.string().email().required().messages({ 'string.email': 'Must be a valid email', 'any.required': 'Email is required' }),
  age: Joi.number().min(18).required().messages({ 'number.min': 'Must be at least 18', 'any.required': 'Age is required' }),
});

app.post('/users', (req, res, next) => {
  const { error } = userSchema.validate(req.body);
  if (error) {
    return res.status(400).json({ error: error.details[0].message });
  }
  const user = userService.create(req.body);
  res.status(201).json(user);
});

Senior devs never let invalid input reach the point where it breaks.

The Rule: if you are catching an exception caused by bad input, you have a validation problem, not an exception handling problem.

Also read Input Validation and Sanitization: Joi vs Zod to pick the right schema library for your project.

Pattern 2: A Custom Error Hierarchy

Junior devs catch Error. Senior devs build a hierarchy that makes every failure self-explanatory.

javascript

// ❌ WRONG - Generic errors tell you nothing
try {
  orderService.process(order);
} catch (error) {
  console.error(`Something failed: ${error.message}`);
  res.status(500).json({ error: 'Internal server error' });
}

What Senior Devs Do Instead

javascript

// ✅ CORRECT - A structured error hierarchy
class AppError extends Error {
  constructor(message, statusCode, errorCode) {
    super(message);
    this.statusCode = statusCode;
    this.errorCode = errorCode;
  }
}

// Specific errors speak for themselves
class NotFoundError extends AppError {
  constructor(resource, id) {
    super(`${resource} not found with id: ${id}`, 404, 'NOT_FOUND');
  }
}

class BusinessRuleViolatedError extends AppError {
  constructor(rule) {
    super(`Business rule violated: ${rule}`, 409, 'BUSINESS_RULE_VIOLATED');
  }
}

// Usage - no try-catch needed in the service
function processOrder(request) {
  const order = orderModel.findById(request.orderId);
  if (!order) {
    throw new NotFoundError('Order', request.orderId);
  }
  if (order.isAlreadyProcessed) {
    throw new BusinessRuleViolatedError('Order already processed');
  }
  return orderModel.save(order);
}

When NotFoundError gets thrown, you already know what failed, why it failed, and what HTTP status to return. Zero guesswork.

The Rule: if you are catching a generic error and then trying to figure out what actually went wrong, your errors are not specific enough.

Pattern 3: Handle Errors in One Place

Junior devs put try-catch in every route handler. Senior devs handle all errors in a single, centralized middleware.

javascript

// ❌ WRONG - Copy-pasting the same catch logic across 15 routes
app.get('/orders/:id', (req, res) => {
  try {
    const order = orderService.findById(req.params.id);
    res.json(order);
  } catch (error) {
    if (error instanceof NotFoundError) {
      res.status(404).json({ error: error.message });
    } else {
      res.status(500).json({ error: 'Internal server error' });
    }
  }
});

What Senior Devs Do Instead

javascript

// ✅ CORRECT - One handler. All routes. Zero duplication.
// Error-handling middleware (must be last in the app.use chain)
app.use((err, req, res, next) => {
  if (err instanceof NotFoundError) {
    res.status(err.statusCode).json({ code: err.errorCode, message: err.message });
  } else if (err instanceof BusinessRuleViolatedError) {
    res.status(err.statusCode).json({ code: err.errorCode, message: err.message });
  } else if (err.name === 'ValidationError') { // e.g., from Joi
    res.status(400).json({ code: 'VALIDATION_FAILED', message: err.details.map(d => d.message).join(', ') });
  } else {
    console.error('Unexpected error:', err);
    res.status(500).json({ code: 'INTERNAL_ERROR', message: 'Something went wrong' });
  }
});

// Now your routes look like THIS
app.get('/orders/:id', (req, res, next) => {
  const order = orderService.findById(req.params.id); // Errors propagate to middleware
  res.json(order);
});

Your routes become thin and readable. All the error logic lives in one place.

The Rule: if you are writing the same catch block in more than one route, you need error-handling middleware.

Also read 7 Powerful Nodejs Middleware Patterns for Cleaner Expressjs Apps for more on structuring the middleware chain.

Pattern 4: Result Objects for Expected Failures

Not every failure is exceptional. “User not found” is not an error. It is a normal outcome. Using errors for normal outcomes is like using an ambulance to get to work.

javascript

// ❌ WRONG - Throwing errors for expected scenarios
function findUser(id) {
  const user = userModel.findById(id);
  if (!user) {
    throw new NotFoundError('User', id);
  }
  return user;
}

// Now every caller needs to handle this error

What Senior Devs Do Instead

javascript

// ✅ CORRECT - Result objects communicate success and failure explicitly
class Result {
  constructor(value, error, success) {
    this.value = value;
    this.error = error;
    this.success = success;
  }

  static ok(value) {
    return new Result(value, null, true);
  }

  static failure(error) {
    return new Result(null, error, false);
  }

  isSuccess() {
    return this.success;
  }

  getValue() {
    return this.value;
  }

  getError() {
    return this.error;
  }
}

// Usage - no errors, no guessing
function findUser(id) {
  const user = userModel.findById(id);
  return user ? Result.ok(user) : Result.failure(`User not found with id: ${id}`);
}

// Caller knows exactly what happened
const result = userService.findUser(123);
if (result.isSuccess()) {
  res.json(result.getValue());
} else {
  res.status(404).json({ error: result.getError() });
}

The Rule: if a scenario is expected, not a bug and not a system failure, do not throw an error. Return a Result.

The Mental Model

Senior developers think about errors in two categories:

Category	What it means	Examples	How to handle
Exceptional	Should not happen under normal conditions	DB connection drops, third-party API times out, out of memory	try-catch, structured logging, alerts
Expected	Part of normal business logic	User does not exist, order already shipped, payment declined	Validation, Result objects, clean control flow

Once you start categorizing failures this way, you will naturally write fewer try-catch blocks. Not because you are ignoring errors, but because you are handling them better.

Summary

Validate at the boundary - Joi or Zod at the door beats a catch block inside
Build an error hierarchy - NotFoundError tells you more than Error ever will
Centralize handling - One Express error middleware, not fifteen catch blocks
Return Results for expected failures - Reserve exceptions for the exceptional
Classify before you catch - Exceptional vs expected decides the tool

Node.js Error Handling: Strategies for Production Applications - Error classification, global handlers and monitoring
Node.js Error Handling Patterns for Production - Sync, async and uncaught error patterns
Input Validation and Sanitization: Joi vs Zod - Choosing a schema validation library
7 Powerful Nodejs Middleware Patterns for Cleaner Expressjs Apps - Structuring the middleware chain
The Pitfalls of Using Async/Await Inside forEach() Loops - Where async errors quietly disappear

Final Thoughts

Do not refactor everything at once. Start with one change.

Find a single try-catch in your codebase that is catching bad input and replace it with schema validation. Pick one generic catch (error) and replace it with a specific custom error. If catch blocks repeat across routes, build the error-handling middleware. Find one place where you throw for an expected scenario and return a Result instead.

Each change makes your code more honest about what is actually happening. That honesty is what “safe code” really means.

✨ Thank you for reading and I hope you find it helpful. I sincerely request for your feedback in the comment’s section.

Tech Insights on Nodejs, Javascript, Mongodb

AI Gateway vs API Gateway: Build LLM Middleware in Node.js

Quick answer

AI gateway vs API gateway

1. Model routing

2. Caching

3. Token-aware rate limiting

4. Observability with OpenTelemetry

5. Resilience

Putting it together

Agent middleware and MCP

Which AI gateway to use

Five mistakes to avoid

Frequently Asked Questions

Related reading

Moment.js to Temporal: A Migration Guide for 2026

Should you migrate now?

Why Date had to be replaced

The Temporal types

Moment.js, date-fns, Day.js, Luxon or Temporal?

Moment and date-fns to Temporal: cheat sheet

Formatting without tokens

Relative time: fromNow()

TypeScript setup

Pick a polyfill

JSON and database boundaries

Testing code that calls Temporal.Now

Migrating an existing codebase

What Temporal doesn’t cover

Related reading

Worker Threads vs Cluster vs Child Process in Node.js

Quick answer

At a glance

Is Node.js single-threaded?

How each primitive works

child_process

cluster

Do you still need cluster with PM2 or Kubernetes?

worker_threads

The benchmarks

Benchmark 1: Startup cost

Benchmark 2: Memory per instance

Benchmark 3: Round-trip message latency

Benchmark 4: Moving 16 MB

Benchmark 5: One option, 73x faster

The repo

src/tasks/cpu-task.ts

src/pool/pool.worker.ts

src/pool/worker-pool.ts

src/server/cluster.ts

bench/throughput.mjs

Decision table

Five mistakes to avoid

Frequently Asked Questions

Before you parallelise

Related reading

Node.js v26 Upgrade: Temporal by Default, Type Stripping

Should you upgrade now?

Node.js 26 at a glance

Temporal: the new date API

Pick the right type

The off-by-one-day bug goes away

DST arithmetic is correct by default

Convert at the database boundary

Don’t rip out date-fns yet

TypeScript type stripping

What works and what doesn’t

NestJS, TypeORM and decorator-heavy code

A tsconfig that matches Node

Smaller additions: Map upsert

Breaking changes in detail

1. Native addons must be rebuilt

2. DEP0205: a warning you can’t fix yourself

3. Legacy _stream_* modules removed

4. writeHeader() removed

5. Extensionless CommonJS in ESM packages

6. Behaviour changes worth testing

7. Building from source

Pre-upgrade scanner

Upgrade checklist

Why `Date` had to be replaced

Relative time: `fromNow()`

Testing code that calls `Temporal.Now`

3. Legacy `_stream_*` modules removed

4. `writeHeader()` removed