Purpose: Field manual for using browser-shaped APIs inside Node.js as production primitives, connecting Node.js V8 Runtime Engineering with 11 Networking HTTP TLS DNS Sockets Undici and Fetch, Web Streams, URL handling, Blob and FormData, AbortController, Web Crypto, and the built-in test runner before native boundary work in 13 Native Addons N-API WASM FFI and Embedding.

Web Platform APIs in Node.js URL Blob Web Streams AbortController and Test Runner

Node.js has steadily adopted Web Platform APIs so server code can share concepts with browsers, edge runtimes, workers, and standards-based libraries. These APIs are useful because they create portable boundaries: URL, URLSearchParams, AbortSignal, Blob, FormData, ReadableStream, Request, Response, Headers, crypto.subtle, and node:test all make integration code less tied to legacy callback patterns.

The trap is assuming browser-shaped means browser-identical. Node has a process lifecycle, filesystem access, server-side security concerns, pooled network clients, worker threads, OpenSSL, and local test execution. Treat Web Platform APIs as stable contracts, not as a reason to ignore runtime context.

API map

Area	API	Use it for	Watch
URL parsing	`URL`, `URLSearchParams`	Canonical parsing, mutation, query encoding.	Never build URLs by string concatenation.
Binary payloads	`Blob`, `File`, `FormData`	Fetch bodies, multipart payloads, immutable byte bundles.	Blob is not a streaming storage strategy by itself.
Streams	`ReadableStream`, `WritableStream`, `TransformStream`	Web-compatible streaming, fetch bodies, transforms.	Locking, cancellation, and Node stream interop.
Cancellation	`AbortController`, `AbortSignal`	Deadlines, cascading shutdown, request cancellation.	Cancellation is cooperative and must be wired through.
Crypto	`crypto.subtle`, `CryptoKey`, `getRandomValues`	Standards-shaped cryptography.	Algorithm support and key extractability.
Events	`EventTarget`, `Event`, `CustomEvent`	Web-compatible event APIs.	Not a replacement for every Node `EventEmitter`.
Testing	`node:test`	Built-in test runner, subtests, mocks, coverage, snapshots.	Isolation model, concurrency, and state leakage.

URL and URLSearchParams

The WHATWG URL implementation is the safest default for parsing and constructing URLs. It normalizes encoding rules, separates origin/path/query parts, and avoids string-splitting mistakes around ?, #, IPv6 literals, username/password, and percent encoding.

Rules:

Parse first, then validate.
Validate scheme, hostname, port, and pathname separately.
For SSRF-sensitive code, resolve DNS and enforce network policy after redirects, not only before the first request.
Use URLSearchParams for query mutation.
Use new URL(relative, base) for relative resolution.

Example: safe API URL builder.

export function buildApiUrl(baseUrl, tenantId, filters) {
  const url = new URL(`/v1/tenants/${encodeURIComponent(tenantId)}/events`, baseUrl);

  for (const [key, value] of Object.entries(filters)) {
    if (value !== undefined && value !== null) {
      url.searchParams.set(key, String(value));
    }
  }

  if (url.protocol !== 'https:') {
    throw new Error('API base URL must use https');
  }

  return url;
}

Footguns:

Bad habit	Failure mode	Better pattern
`base + path + '?' + query`	Double slashes, missing encoding, query injection.	`new URL(path, base)` plus `searchParams`.
Validate with `includes()`	`https://trusted.example.evil` bypasses weak checks.	Compare parsed `hostname` and `origin`.
Assume path is decoded	Percent encoding changes comparison.	Normalize and compare with explicit policy.
Keep credentials in URL logs	Secrets leak into traces and errors.	Redact `username`, `password`, tokens, and signed query strings.

Blob, File, and FormData

Blob is an immutable binary object. In Node it is useful for standards-compatible fetch bodies and APIs that expect browser-shaped payloads. File adds file-like metadata. FormData models multipart form submissions.

Use cases:

Uploading JSON plus files through fetch.
Passing binary data across web-compatible boundaries.
Returning a byte body with a content type.
Testing upload code without writing temporary files.

Example: multipart request body.

export async function uploadReport(endpoint, reportBuffer) {
  const form = new FormData();
  form.set('metadata', new Blob([
    JSON.stringify({ kind: 'daily-report' }),
  ], { type: 'application/json' }));
  form.set('report', new File([reportBuffer], 'report.json', {
    type: 'application/json',
  }));

  const response = await fetch(endpoint, {
    method: 'POST',
    body: form,
    signal: AbortSignal.timeout(15_000),
  });

  if (!response.ok) {
    await response.body?.cancel();
    throw new Error(`upload failed: ${response.status}`);
  }
}

Blob guidance:

Concern	Guidance
Memory	A Blob can still represent large data; do not materialize giant payloads casually.
Type	Treat `type` as metadata, not proof that bytes match the claimed format.
Streaming	Prefer streams for unbounded or long-running payloads.
Immutability	Good for stable snapshots, less good for incremental writes.

Web Streams

Node supports Web Streams through globals and node:stream/web. Fetch bodies are Web Streams. Web Streams are not the same API as classic Node streams, but Node provides interop helpers through node:stream.

Key concepts:

Concept	Meaning
`ReadableStream`	Pull-based readable data source.
`WritableStream`	Sink with backpressure and close/abort behavior.
`TransformStream`	Readable plus writable pair for transformation.
Locking	A stream can have an active reader or pipe, and that locks it.
Cancellation	Reader cancellation tells upstream it can stop producing.
Backpressure	Pull and desired size signals shape production rate.

Example: transform a fetch response without buffering the whole body.

const decoder = new TextDecoder();
const encoder = new TextEncoder();

export async function uppercaseLines(url) {
  const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
  if (!response.ok || !response.body) {
    throw new Error(`bad response: ${response.status}`);
  }

  const transform = new TransformStream({
    transform(chunk, controller) {
      const text = decoder.decode(chunk, { stream: true });
      controller.enqueue(encoder.encode(text.toUpperCase()));
    },
    flush(controller) {
      const tail = decoder.decode();
      if (tail) controller.enqueue(encoder.encode(tail.toUpperCase()));
    },
  });

  return response.body.pipeThrough(transform);
}

Interop with Node streams:

import { Readable } from 'node:stream';
import { createWriteStream } from 'node:fs';

export async function saveWebStream(webReadable, path) {
  const nodeReadable = Readable.fromWeb(webReadable);
  const file = createWriteStream(path, { flags: 'wx' });

  await new Promise((resolve, reject) => {
    nodeReadable.pipe(file);
    nodeReadable.on('error', reject);
    file.on('error', reject);
    file.on('finish', resolve);
  });
}

Stream footguns:

Footgun	Symptom	Fix
Reading a stream twice	"ReadableStream is locked" or empty second read.	Tee explicitly or buffer once with a size cap.
Breaking async iteration early	Upstream may be canceled.	Use `values({ preventCancel: true })` when needed.
Ignoring `pipeTo` rejection	Silent partial writes.	Await the promise and handle abort/error.
Mixing Buffer and Uint8Array assumptions	Encoding bugs.	Normalize chunks at boundaries.
Using Blob for huge streams	Memory pressure.	Keep data as stream where possible.

AbortController and AbortSignal

AbortController is the cancellation primitive used by many Promise-based Node and Web APIs. It does not kill arbitrary work by magic. It carries a signal, and called code must observe that signal.

Patterns:

Pattern	Example
Deadline	`AbortSignal.timeout(10_000)`
Parent plus deadline	`AbortSignal.any([parentSignal, AbortSignal.timeout(10_000)])`
Immediate canceled signal	`AbortSignal.abort(reason)`
Synchronous check	`signal.throwIfAborted()`
Listener cleanup	`signal.addEventListener('abort', onAbort, { once: true })`

Example: cascading cancellation.

export async function loadUserBundle(userId, { signal }) {
  signal?.throwIfAborted();

  const timeout = AbortSignal.timeout(8_000);
  const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;

  const [profile, invoices] = await Promise.all([
    fetchJson(`/api/users/${userId}`, { signal: combined }),
    fetchJson(`/api/users/${userId}/invoices`, { signal: combined }),
  ]);

  return { profile, invoices };
}

async function fetchJson(path, { signal }) {
  const response = await fetch(new URL(path, 'https://internal.example'), { signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

Cancellation production guidance:

Thread the signal through every nested IO call.
Convert process shutdown into an AbortController.
Differentiate timeout, user cancel, deploy cancel, and dependency cancel in metrics.
Always clean up timers and event listeners for custom cancellable APIs.
Never use cancellation as a substitute for idempotency.

Web Crypto

Node exposes Web Crypto through globalThis.crypto and node:crypto. It is the right shape when code needs to be portable with browsers, workers, or standards-based libraries.

Use Web Crypto for:

Random bytes through crypto.getRandomValues().
Hashing and HMAC with crypto.subtle.
Key import/export using standard formats.
Verifying signatures where supported algorithms fit.

Use classic node:crypto when:

You need Node-specific streams.
You need algorithms not available through Web Crypto.
You need mature ecosystem examples for operational crypto.

Crypto footguns:

Footgun	Risk
Homegrown encoding	Signature mismatches and unverifiable payloads.
Extractable keys by default	Accidental secret export.
Comparing strings directly	Timing leakage for secrets.
Assuming all algorithms exist everywhere	Runtime drift across Node, browser, and edge.
Logging CryptoKey metadata blindly	Operational leakage.

Example: SHA-256 digest with explicit encoding.

export async function sha256Hex(value) {
  const bytes = new TextEncoder().encode(value);
  const digest = await crypto.subtle.digest('SHA-256', bytes);
  return Buffer.from(digest).toString('hex');
}

EventTarget versus EventEmitter

EventTarget is useful for Web-compatible APIs. EventEmitter remains idiomatic in many Node core modules and older packages.

Need	Prefer
Browser-compatible library boundary	`EventTarget`
Node streams and core APIs	`EventEmitter`
Rich error event conventions	`EventEmitter`
Abortable event listeners	`EventTarget` with signal-aware listeners where supported

Do not rewrite stable EventEmitter code just because EventTarget exists. Use the API shape that matches the surrounding contract.

Built-in test runner

node:test is the built-in test runner. It supports tests, subtests, hooks, mocks, timers, snapshots, reporters, coverage integration, and command-line execution. Modern Node test files usually run in process isolation by default when invoked with node --test, with each matching file executed in a child process unless isolation is disabled.

Basic test:

import test from 'node:test';
import assert from 'node:assert/strict';
import { buildApiUrl } from './url-builder.js';

test('buildApiUrl encodes tenant path and query', () => {
  const url = buildApiUrl('https://api.example', 'tenant/a', { limit: 10 });

  assert.equal(url.origin, 'https://api.example');
  assert.equal(url.pathname, '/v1/tenants/tenant%2Fa/events');
  assert.equal(url.searchParams.get('limit'), '10');
});

Subtests and lifecycle:

import test from 'node:test';
import assert from 'node:assert/strict';

test('cache', async (t) => {
  const cache = new Map();

  t.after(() => cache.clear());

  await t.test('miss', () => {
    assert.equal(cache.get('a'), undefined);
  });

  await t.test('hit', () => {
    cache.set('a', 1);
    assert.equal(cache.get('a'), 1);
  });
});

Mock timers:

import test from 'node:test';
import assert from 'node:assert/strict';

test('deadline fires', (t) => {
  t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });

  let fired = false;
  setTimeout(() => {
    fired = true;
  }, 1000);

  t.mock.timers.tick(1000);
  assert.equal(fired, true);
});

Test runner production guidance:

Concern	Guidance
Isolation	Keep tests independent even when process isolation is enabled; shared external services still leak state.
Concurrency	Use deterministic resource names and ports.
Mocking	Prefer injected dependencies over global monkeypatching.
Timers	Mock timers for scheduler logic; use real time for integration behavior.
Snapshots	Good for stable structural outputs; poor for noisy data or opaque blobs.
Coverage	Treat coverage as a signal, not proof of correctness.
Reporters	Use machine-readable output in CI and concise output locally.

Network test pattern for 11 Networking HTTP TLS DNS Sockets Undici and Fetch:

import test from 'node:test';
import assert from 'node:assert/strict';
import http from 'node:http';

test('client handles JSON response', async (t) => {
  const server = http.createServer((req, res) => {
    res.writeHead(200, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ ok: true }));
  });

  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
  t.after(() => server.close());

  const { port } = server.address();
  const response = await fetch(`http://127.0.0.1:${port}/`);
  assert.deepEqual(await response.json(), { ok: true });
});

Operational patterns

Use web APIs at process boundaries

Good boundaries:

Incoming and outgoing HTTP bodies as Web Streams.
Internal cancellation as AbortSignal.
URLs as parsed URL objects.
Binary uploads as Blob only when bounded.
Tests as node:test with explicit fixtures.

Bad boundaries:

Passing raw strings where URL policy matters.
Passing Buffer everywhere even when fetch or streams expect Uint8Array.
Creating a new AbortController inside each helper and dropping the parent signal.
Snapshotting nondeterministic output.

Validate once, preserve structure

Parse URL input at the edge and pass structured data deeper.

export function parseWebhookTarget(input) {
  const url = new URL(input);

  if (url.protocol !== 'https:') throw new Error('https required');
  if (url.username || url.password) throw new Error('credentials not allowed');
  if (!['hooks.example.com', 'events.example.com'].includes(url.hostname)) {
    throw new Error('unsupported webhook host');
  }

  return url;
}

Make cancellation observable

export function classifyAbort(error, signal) {
  if (signal?.aborted) {
    return {
      canceled: true,
      reason: signal.reason?.name ?? signal.reason?.message ?? String(signal.reason),
    };
  }

  return { canceled: false, error: error.code ?? error.name };
}

Troubleshooting

Symptom	Likely cause	First check
`ReadableStream is locked`	Multiple readers or a reader plus pipe.	Find who called `getReader`, `pipeTo`, or `for await`.
Fetch never aborts custom work	Signal is not threaded into nested operation.	Verify every helper accepts `{ signal }`.
URL validation bypass	String checks instead of parsed checks.	Log parsed protocol, hostname, port, and username/password presence.
Test passes alone but fails in suite	Shared state, port conflict, mocked global not restored.	Use `t.after`, random ports, and dependency injection.
Snapshot churn	Nondeterministic fields.	Normalize timestamps, ids, order, and host-specific paths.
Blob upload uses too much memory	Large payload materialized.	Switch to stream body with size cap.

Official reference anchors checked

Node.js v26.3.0 globals, including AbortController, Blob, fetch, URL, WebSocket, and related classes: https://nodejs.org/api/globals.html
Node.js v26.3.0 URL API: https://nodejs.org/api/url.html
Node.js v26.3.0 Buffer and Blob API: https://nodejs.org/api/buffer.html#blob
Node.js v26.3.0 Web Streams API: https://nodejs.org/api/webstreams.html
Node.js v26.3.0 Web Crypto API: https://nodejs.org/api/webcrypto.html
Node.js v26.3.0 test runner: https://nodejs.org/api/test.html