Data Parsing & Serialization

Deserializing a large API response is one of the few remaining places where a modern single-page app still blocks its own render thread for tens of milliseconds at a time. JSON.parse, schema validation, log tokenization, and binary header decoding are all synchronous, CPU-bound, and impossible to yield out of once started. This guide covers moving that work into a dedicated worker, and it is a specialisation of the broader High-Performance Computation Patterns reference — the thread-isolation, transfer-list, and lifecycle rules described there apply here unchanged.

The Bottleneck: Where Parse Time Actually Goes

The symptom is specific and easy to recognise in a trace: a user hits “load report”, the network request resolves, and then the browser paints nothing for 150–250 ms while a single Long Task sits in the flame chart labelled JSON.parse. Scroll stalls, the spinner freezes mid-rotation, and any click queued during that window is dispatched late.

Measured on a mid-tier laptop (Chrome 126, V8 12.6), a JSON document of 8 MB containing roughly 120,000 objects costs about:

Three of those four stages have no yield point. Chunking them with setTimeout only converts one long block into many medium ones and adds scheduler latency. The durable fix is to run them in a different thread entirely, so the render thread keeps its full 16.7 ms frame budget while a background thread does the work.

Two things make this a non-trivial refactor rather than a one-line change. First, moving data across the boundary is not free: a naive postMessage(jsonString) structured-clones the whole string, which reintroduces a main-thread copy proportional to payload size. Second, whatever the worker returns must also cross back — and returning 120,000 parsed objects can cost more than the parse you just eliminated. Both problems are solved by choosing the right transfer strategy, covered in detail below and in Transferable Objects & Zero-Copy.

Prerequisites

Before implementing the pattern below, confirm each of these:

• A measured baseline. A performance.now() reading (or a DevTools Performance recording) showing that parsing exceeds 4–5 ms on your slowest target device. Below that threshold, worker round-trip overhead makes things worse, not better.
• Module worker support in your bundler. new Worker(new URL('./parse.worker.ts', import.meta.url), { type: 'module' }) is understood natively by Vite, webpack 5, Rollup, and esbuild.
• Familiarity with the message contract — postMessage, onmessage, and the transfer list. See Message Passing Strategies if the request/response correlation pattern is new to you.
• TextEncoder / TextDecoder available in both contexts (every browser since 2017; they exist in WorkerGlobalScope too).
• COOP/COEP headers only if you intend to use SharedArrayBuffer. The transferable ArrayBuffer path used throughout this guide needs no special headers.
• A stable payload schema, or a validator you are willing to run inside the worker. Validation is one of the cheapest things to move across the boundary, because it produces a boolean rather than a large object graph.

Step-by-Step Implementation

1. Measure the baseline before changing anything

Instrument the synchronous path first. Without a number, you cannot tell whether the worker helped, and a worker that helps on a 12-core desktop can regress on a mid-range phone.

// measure-baseline.ts
export function measureParse(jsonText: string, runs = 20): number {
  // Warm up so the JIT has tiered up before the timed loop.
  for (let i = 0; i < 3; i++) JSON.parse(jsonText);

  const t0 = performance.now();
  for (let i = 0; i < runs; i++) JSON.parse(jsonText);
  const perParse = (performance.now() - t0) / runs;

  console.log(`JSON.parse: ${perParse.toFixed(2)} ms per call, ` +
    `${(jsonText.length / 1_048_576).toFixed(1)} MB payload`);
  return perParse;
}

2. Stand up a dedicated parsing worker

Give parsing its own long-lived worker rather than spawning one per request. Worker start-up costs 5–15 ms (module resolution, script evaluation, realm creation), which would dominate the very cost you are trying to remove.

// parse-client.ts — typed request/response contract
export type ParseRequest = {
  id: string;
  format: 'json' | 'ndjson' | 'binary';
  buffer: ArrayBuffer;      // always bytes, never a string
};

export type ParseResponse =
  | { id: string; status: 'complete'; result: unknown; parseMs: number }
  | { id: string; status: 'error'; name: string; message: string };

const worker = new Worker(new URL('./parse.worker.js', import.meta.url), { type: 'module' });
const pending = new Map<string, { resolve: (r: unknown) => void; reject: (e: Error) => void }>();

worker.onmessage = ({ data }: MessageEvent<ParseResponse>) => {
  const entry = pending.get(data.id);
  if (!entry) return;                       // late reply after a timeout — drop it
  pending.delete(data.id);
  if (data.status === 'complete') entry.resolve(data.result);
  else entry.reject(Object.assign(new Error(data.message), { name: data.name }));
};

export function parseInWorker(buffer: ArrayBuffer, format: ParseRequest['format']) {
  const id = crypto.randomUUID();
  return new Promise<unknown>((resolve, reject) => {
    pending.set(id, { resolve, reject });
    // The buffer is listed as transferable: ownership moves, nothing is copied.
    worker.postMessage({ id, format, buffer } satisfies ParseRequest, [buffer]);
  });
}

3. Move bytes, not strings

The single highest-leverage decision on this page: never send a JavaScript string over postMessage when the payload is large. Strings are structured-cloned, which copies every UTF-16 code unit on the sending side and allocates a fresh string on the receiving side. ArrayBuffer can be transferred instead — the receiving realm takes ownership of the same memory and the send costs a pointer hand-off.

Where possible, skip the string entirely: Response.arrayBuffer() gives you the raw network bytes without ever materialising a JS string on the main thread.

// fetch-as-bytes.ts
export async function fetchAndParse(url: string): Promise<unknown> {
  const response = await fetch(url);
  // arrayBuffer() never creates a JS string — no UTF-8 → UTF-16 conversion here.
  const buffer = await response.arrayBuffer();
  return parseInWorker(buffer, 'json');       // transferred, zero-copy
}

// If you already hold a string (e.g. from localStorage), encode it once:
export function encodeForTransfer(jsonText: string): ArrayBuffer {
  const bytes = new TextEncoder().encode(jsonText);   // UTF-16 → UTF-8, one pass
  return bytes.buffer;                                 // detachable, transferable
}

4. Decode, parse, and validate inside the worker

The worker owns the whole tail of the pipeline: decode bytes → parse → validate → reshape. Validation and reshaping matter as much as the parse, because they decide how big the reply will be.

// parse.worker.js
const decoder = new TextDecoder('utf-8');

self.onmessage = ({ data }) => {
  const { id, format, buffer } = data;
  const t0 = performance.now();
  try {
    const text = decoder.decode(buffer);          // buffer is owned by this realm now
    const parsed = format === 'ndjson'
      ? text.split('\n').filter(Boolean).map((line) => JSON.parse(line))
      : JSON.parse(text);

    const problems = validate(parsed);
    if (problems.length) {
      throw Object.assign(new Error(problems[0]), { name: 'SchemaError' });
    }

    // Reshape to the narrow view model the UI actually renders.
    const result = summarise(parsed);
    self.postMessage({ id, status: 'complete', result, parseMs: performance.now() - t0 });
  } catch (err) {
    self.postMessage({ id, status: 'error', name: err.name, message: err.message });
  }
};

function validate(rows) {
  const problems = [];
  if (!Array.isArray(rows)) return ['expected a top-level array'];
  for (let i = 0; i < rows.length; i++) {
    const r = rows[i];
    if (typeof r?.id !== 'number') problems.push(`row ${i}: missing numeric id`);
    if (problems.length > 5) break;               // fail fast, do not build a huge report
  }
  return problems;
}

function summarise(rows) {
  // Return aggregates plus a first page — not 120,000 objects.
  let total = 0;
  for (const r of rows) total += r.value ?? 0;
  return { count: rows.length, total, page: rows.slice(0, 100) };
}

5. Route adaptively by payload size

Worker offload has a fixed cost — roughly 0.5–2 ms of round-trip latency plus the reply clone — so it is a loss on small payloads. Measure the crossover on your own data and encode it as a threshold; on typical desktop hardware it lands between 1 and 2 MB.

// adaptive-route.ts
const WORKER_THRESHOLD_BYTES = 1.5 * 1024 * 1024;   // measured, not guessed

export async function parseAdaptive(buffer: ArrayBuffer): Promise<unknown> {
  if (buffer.byteLength < WORKER_THRESHOLD_BYTES) {
    // Small enough that a round-trip would cost more than the parse.
    return JSON.parse(new TextDecoder().decode(buffer));
  }
  return parseInWorker(buffer, 'json');
}

6. Compress payloads that are large or network-bound

When bytes travel over the network, or get persisted in IndexedDB, CompressionStream shrinks JSON dramatically — text compresses well because of repeated key names. Compress on the producing side, decompress inside the worker so the CPU cost stays off the render thread.

// compress-and-send.ts
export async function compressAndSend(jsonText: string, worker: Worker): Promise<void> {
  const input = new Blob([jsonText]).stream();
  const compressed = input.pipeThrough(new CompressionStream('gzip'));
  const buffer = await new Response(compressed).arrayBuffer();
  worker.postMessage({ kind: 'gzip-json', buffer }, [buffer]);   // ownership moves
}

// parse.worker.js — decompression branch
async function decodeGzipJson(buffer) {
  const stream = new Response(buffer).body.pipeThrough(new DecompressionStream('gzip'));
  const text = await new Response(stream).text();
  return JSON.parse(text);
}

7. Offload tokenization and heavy regular expressions

Log parsing, CSV field splitting, and format sniffing are regex-heavy, and a pattern with nested quantifiers can backtrack catastrophically — turning a 20 ms scan into a multi-second freeze. In a worker, that worst case is survivable: you can terminate the thread.

// tokenize.worker.js
// Compile once at module scope so V8 reuses the compiled regex across messages.
const PATTERNS = {
  'log-entry': /^(?<timestamp>\d{4}-\d{2}-\d{2}T[\d:.Z]+)\s+(?<level>\w+)\s+(?<message>.*)$/gm,
};

self.onmessage = ({ data }) => {
  const { text, pattern } = data;
  const regex = PATTERNS[pattern];
  if (!regex) return self.postMessage({ error: `unknown pattern: ${pattern}` });

  regex.lastIndex = 0;                 // /g regexes are stateful — always reset
  const matches = [];
  let match;
  while ((match = regex.exec(text)) !== null) {
    matches.push(match.groups);
    if (match.index === regex.lastIndex) regex.lastIndex++;   // guard zero-length matches
    if (matches.length % 10_000 === 0) self.postMessage({ progress: matches.length });
  }
  self.postMessage({ matches, count: matches.length });
};

// tokenize-client.ts — bound the worst case with a watchdog
const tokenizer = new Worker(new URL('./tokenize.worker.js', import.meta.url), { type: 'module' });

export function tokenize(text: string, pattern: string, budgetMs = 5000) {
  return new Promise<Array<Record<string, string>>>((resolve, reject) => {
    const watchdog = setTimeout(() => {
      tokenizer.terminate();           // kills the backtracking loop dead
      reject(new Error(`tokenize exceeded ${budgetMs} ms budget`));
    }, budgetMs);

    tokenizer.onmessage = ({ data }) => {
      if (data.progress !== undefined) return;    // progress ping, keep waiting
      clearTimeout(watchdog);
      data.error ? reject(new Error(data.error)) : resolve(data.matches);
    };
  });
}

8. Deserialize binary formats with DataView

Binary containers — protocol frames, custom telemetry blobs, media headers — skip text decoding entirely. DataView reads fixed offsets with explicit endianness, so the worker never allocates an intermediate string.

// binary.worker.js
const MAGIC = 0xDEADBEEF;

self.onmessage = ({ data }) => {
  const { buffer } = data;
  const view = new DataView(buffer);

  if (view.byteLength < 12) {
    return self.postMessage({ error: 'truncated header' });
  }
  const magic = view.getUint32(0, /* littleEndian */ true);
  if (magic !== MAGIC) {
    return self.postMessage({ error: `bad signature 0x${magic.toString(16)}` });
  }

  const headerSize = view.getUint32(4, true);
  const recordCount = view.getUint32(8, true);

  // Read the payload as a typed array over the SAME memory — no copy.
  const records = new Float32Array(buffer, headerSize, recordCount);
  const stats = { min: Infinity, max: -Infinity };
  for (const v of records) {
    if (v < stats.min) stats.min = v;
    if (v > stats.max) stats.max = v;
  }
  self.postMessage({ headerSize, recordCount, stats });
};

Data-Transfer Strategy: Clone, Transfer, or Share

Every design decision on this page reduces to one question: how do the bytes cross the thread boundary? There are three mechanisms, and for parsing workloads they are not interchangeable.

For the overwhelming majority of parsing pipelines, a transferred ArrayBuffer is correct: the main thread has no further use for the raw bytes after handing them off, and detachment enforces that at runtime instead of leaving a stale copy around. Reach for shared memory only when several workers must fan out over the same buffer — the coordination rules are covered in SharedArrayBuffer & Atomics, and the decision itself in postMessage vs SharedArrayBuffer: When to Choose Each.

The reply direction deserves separate thought. A transfer only works for binary-ish results, so a columnar shape often beats a row-oriented one: three Float64Arrays of 120,000 elements transfer in under a millisecond, whereas 120,000 { id, value, label } objects must be cloned. When the full row set is unavoidable, stream it — Streaming JSON Parsing with Transferable Chunks splits a multi-megabyte document into sequential ArrayBuffer slices so partial results render while the tail is still parsing, and CSV & JSON Transform Pipelines applies the same batching discipline to tabular sources.

Verification & Measurement

Offloading is only a win if you can prove the main thread got quieter. Measure three separate numbers — they answer different questions.

// verify.ts
export async function verifyOffload(buffer: ArrayBuffer) {
  // 1. Main-thread occupancy: how long did WE block?
  const sendStart = performance.now();
  const promise = parseInWorker(buffer, 'json');
  const mainThreadCost = performance.now() - sendStart;   // target: <1 ms

  // 2. End-to-end latency: what does the user wait for?
  const result = await promise;
  const roundTrip = performance.now() - sendStart;        // target: <10 ms per 5 MB

  console.table({ mainThreadCost, roundTrip });
  return result;
}

// 3. Frame health: did anything still block long enough to drop a frame?
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.warn(`Long task ${entry.duration.toFixed(0)} ms`, entry.attribution);
  }
}).observe({ type: 'longtask', buffered: true });

mainThreadCost is the number that must collapse — if it is still tens of milliseconds you are cloning a string somewhere instead of transferring bytes. roundTrip will be larger than the old synchronous parse on small payloads; that is expected and is exactly what the size threshold in step 5 guards against. The Long Task observer catches the case where the reply clone quietly reintroduces the jank you removed on the request side.

In DevTools, record a Performance profile and confirm the parse frames now appear under the worker’s own track rather than “Main”. Chrome shows each worker as a separate lane with its own flame chart; the walkthrough lives in Profiling Worker CPU Usage with the Chrome Performance Tab. To isolate serialization cost specifically, time the postMessage call in isolation as described in Measuring Structured Clone Cost with performance.now().

Correctness needs a check too: parsing in another realm must produce an identical object graph. A cheap regression test is to parse the same fixture both ways and compare canonical serializations — JSON.stringify(mainResult) === JSON.stringify(workerResult) catches key-order and numeric-precision surprises, particularly around integers beyond Number.MAX_SAFE_INTEGER that silently lose precision on both paths.

Failure Modes & Error Handling

A parsing worker fails in ways a synchronous parse cannot, and the default behaviour of each is silence.

Malformed input. JSON.parse throws a SyntaxError inside the worker. Because Error objects do not survive structured clone with their prototype and stack intact, serialize the fields you need by hand — name, message, and a truncated stack — as shown in step 4. The full pattern, including cause chains and custom error classes, is in Structured Error Serialization Across Threads.

Uncaught exceptions and rejections. Anything thrown outside your try block, or inside an unawaited promise, never reaches the caller. Wire both handlers in the worker and an onerror on the client:

// parse.worker.js — catch what the message handler misses
self.addEventListener('error', (e) => {
  self.postMessage({ status: 'fatal', name: 'WorkerError', message: e.message,
                     at: `${e.filename}:${e.lineno}:${e.colno}` });
});
self.addEventListener('unhandledrejection', (e) => {
  self.postMessage({ status: 'fatal', name: 'UnhandledRejection', message: String(e.reason) });
  e.preventDefault();
});

// parse-client.ts — never let a dead worker strand pending promises
worker.onerror = (e) => {
  for (const [, entry] of pending) entry.reject(new Error(`worker crashed: ${e.message}`));
  pending.clear();
};

// Fired when a message ARRIVES but cannot be deserialized in this realm.
worker.onmessageerror = () => {
  for (const [, entry] of pending) entry.reject(new Error('reply failed structured clone'));
  pending.clear();
};

Detached buffer reads. After transferring a buffer, the sender’s reference has byteLength === 0 and any typed-array view over it throws TypeError: Cannot perform Construct on a detached ArrayBuffer. If the main thread needs the raw bytes afterwards — for a retry, or to hash them — slice a copy before posting, and accept that copy’s cost knowingly.

Non-cloneable replies. Functions, DOM nodes, Proxy objects, and class instances with private fields fail structured clone and surface as a DataCloneError at postMessage time. Return plain data only; if your validator produces a rich object, flatten it before posting.

Unbounded work. A pathological regex or a 500 MB payload can pin a worker indefinitely. Pair every request with a watchdog timer as in step 7, and respawn on timeout. A worker that is terminated mid-parse leaves no partial state to clean up — the whole realm goes away — which is precisely why the retry path is simple: construct a new Worker and re-post the request from a preserved copy of the input.

Back-pressure. If requests arrive faster than the worker drains them, the message queue grows without bound and memory follows. Cap the queue depth in the client and reject (or coalesce) beyond it; the general treatment is in Error Handling & Crash Recovery.

Browser Compatibility

Two practical gaps: module workers only reached Firefox in version 114 (May 2023), so if you support older Firefox builds, bundle the worker as a classic script with importScripts or let your bundler emit an IIFE build. And the longtask entry type remains Chromium-only — on Firefox and Safari, fall back to requestAnimationFrame delta timing to detect dropped frames during verification.

Going Further

Format choice is the question that usually follows, and it is often asked in the wrong place. Choosing Between JSON, MessagePack and Protobuf in Workers measures all four stages — network, decode, allocation and the thread hop — and shows why changing the decoded shape moves an order of magnitude more time than changing the wire format.