PDF.js Deep Dive 4: MessageHandler
October 22, 2026 · StreamPDF Team

Introduction
In the previous three articles, we covered PDF.js's rendering architecture and the basics of worker communication. This time we go deep into the communication layer itself — the MessageHandler class that sits on both sides of the main-worker boundary and coordinates every message that flows between them.
All code in this article is based on PDF.js v6.3.289.
MessageHandler
Both the main thread and the worker thread use the MessageHandler class to exchange messages.
Thread-level wiring — one handler per worker:
// Source: display/api.js PDFWorker.#initialize
const worker = new Worker(workerSrc, { type: 'module' });
const messageHandler = new MessageHandler('main', 'worker', worker);
// Source: core/worker.js WorkMessageHandler.initializeFromPort
static initializeFromPort(port) {
const handler = new MessageHandler("worker", "main", port);
this.setup(handler, port);
handler.send("ready", null);
}
Document-level wiring — one handler per document:
// Source: display/api.js getDocument
const messageHandler = new MessageHandler(docId, workerId, worker.port);
const transport = new WorkerTransport(
messageHandler, task, networkStream,
transportParams, transportFactory, pagesMapper,
);
// Source: core/worker.js WorkMessageHandler.createDocumentHandler
const workerHandlerName = docId + '_worker';
let handler = new MessageHandler(workerHandlerName, docId, port);
A MessageHandler exposes these methods:
- constructor
- #onMessage
- on
- send
- sendWithPromise
- sendWithStream
- #createStreamSink
- #processStreamMessage
- #deleteStreamController
Let's walk through each one.
constructor
// Source: shared/message_handler.js MessageHandler
constructor(sourceName, targetName, comObj) {
this.sourceName = sourceName;
this.targetName = targetName;
this.comObj = comObj;
this.callbackId = 1;
this.streamId = 1;
this.streamSinks = Object.create(null);
this.streamControllers = Object.create(null);
this.callbackCapabilities = Object.create(null);
this.actionHandler = Object.create(null);
comObj.addEventListener("message", this.#onMessage.bind(this), {
signal: this.#messageAC.signal,
});
}
Three constructor arguments:
sourceName— name of this end (e.g."main"or"worker"). Used for defensive dispatch: a message whosetargetNamedoesn't matchthis.sourceNameis simply dropped.targetName— name of the remote end.comObj— the communication channel. Usually aWorkeror aMessagePort; both speakmessage/postMessage.
The signal option wires this listener into an AbortController so tearing down the MessageHandler cleanly removes the listener.
The class maintains three maps that back the three send methods:
| Field | Backs |
|---|---|
actionHandler | plain on / send (fire-and-forget) |
callbackId + callbackCapabilities | sendWithPromise (request-response) |
streamId + streamSinks + streamControllers | sendWithStream (streaming + backpressure — the most complex of the three) |
#onMessage
#onMessage({ data }) {
if (data.targetName !== this.sourceName) {
return;
}
if (data.stream) {
this.#processStreamMessage(data);
return;
}
if (data.callback) {
const callbackId = data.callbackId;
const capability = this.callbackCapabilities[callbackId];
if (!capability) {
throw new Error(`Cannot resolve callback ${callbackId}`);
}
delete this.callbackCapabilities[callbackId];
if (data.callback === CallbackKind.DATA) {
capability.resolve(data.data);
} else if (data.callback === CallbackKind.ERROR) {
capability.reject(wrapReason(data.reason));
} else {
throw new Error("Unexpected callback case");
}
return;
}
const action = this.actionHandler[data.action];
if (!action) {
throw new Error(`Unknown action from worker: ${data.action}`);
}
if (data.callbackId) {
const sourceName = this.sourceName,
targetName = data.sourceName,
comObj = this.comObj;
Promise.try(action, data.data).then(
function (result) {
comObj.postMessage({
sourceName, targetName,
callback: CallbackKind.DATA,
callbackId: data.callbackId,
data: result,
});
},
function (reason) {
comObj.postMessage({
sourceName, targetName,
callback: CallbackKind.ERROR,
callbackId: data.callbackId,
reason: wrapReason(reason),
});
}
);
return;
}
if (data.streamId) {
this.#createStreamSink(data);
return;
}
action(data.data);
}
After the targetName defensive check, the dispatches fall into four categories — mirroring the four message shapes produced by the three send methods:
| Test | Producer | Consumer side effect |
|---|---|---|
data.stream | sendWithStream's pull / cancel | #processStreamMessage handles PULL, ENQUEUE, CLOSE, ERROR, … |
data.callback | remote end responding to sendWithPromise | resolve / reject the waiting Promise in callbackCapabilities |
data.callbackId | remote end receiving sendWithPromise | run the handler with Promise.try, post the result back |
data.streamId | remote end receiving sendWithStream | create a streamSink via #createStreamSink |
| default | send | just action(data.data) — no reply expected |
on
on(actionName, handler) {
if (typeof PDFJSDev === "undefined" || PDFJSDev.test("TESTING")) {
assert(
typeof handler === "function",
'MessageHandler.on: Expected "handler" to be a function.'
);
}
const ah = this.actionHandler;
if (ah[actionName]) {
throw new Error(`There is already an actionName called "${actionName}"`);
}
ah[actionName] = handler;
}
Registers a handler under an action name. Under sendWithStream, the handler also receives the streamSink as a second argument — not obvious from this method alone, but important for the streaming case.
send
send(actionName, data, transfers) {
this.comObj.postMessage(
{
sourceName: this.sourceName,
targetName: this.targetName,
action: actionName,
data,
},
transfers
);
}
The fire-and-forget primitive. One-way, no callback, no stream.
Q: What is
transfers?It's the second argument to
postMessage— a list of Transferable Objects (ArrayBuffer,TypedArray,MessagePort,ImageBitmap,OffscreenCanvas, …). The name is misleading: it doesn't select what data to send — it selects whose ownership to hand over to the other side.Without
transfers,postMessageuses the Structured Clone algorithm: the receiver gets a deep copy, cost proportional to size. Withtransfers, the bytes travel untouched, the sender'sArrayBufferis immediately detached (byteLengthbecomes 0, further access throws). So it's only for data the sender truly no longer needs.PDF.js produces huge amounts of such data: worker-decoded image pixels (
imgData.data.buffer/imgData.bitmap), path geometry (data.buffer,minMax.buffer), font export buffers (fontData.buffer), and operator-list chunks collected into_transfersbefore each flush. Fromcore/evaluator.js:const transfers = imgData ? [imgData.bitmap || imgData.data.buffer] : null; this.handler.send("commonobj", [objId, "Image", imgData], transfers);Note
datastill references the sameArrayBuffer. The receiver dereferences it directly — zero-copy in action.As a bonus, passing
transfersalso probes the runtime: if transferables aren't supported,postMessagethrowsDataCloneError. PDF.js pre-flights this inPDFWorker.#initializewith a dummy message and falls back to a fake worker if it fails.
sendWithPromise
sendWithPromise(actionName, data, transfers) {
const callbackId = this.callbackId++;
const capability = Promise.withResolvers();
this.callbackCapabilities[callbackId] = capability;
try {
this.comObj.postMessage(
{
sourceName: this.sourceName,
targetName: this.targetName,
action: actionName,
callbackId,
data,
},
transfers
);
} catch (ex) {
capability.reject(ex);
}
return capability.promise;
}
A send with a Promise attached. The trick is callbackId: each outgoing call gets a unique id, stored alongside a withResolvers() capability. The remote end runs the handler and posts back a message carrying callback: CallbackKind.DATA | ERROR plus the same callbackId. The sender's #onMessage finds the waiting capability, resolves or rejects it.
The message lifecycle:
- Caller sends
{ action, callbackId, data } - Receiver:
data.callbackIdis truthy →Promise.try(action, data.data)→ posts back{ callback: DATA, callbackId, data } - Caller:
data.callbackis truthy → resolves the Promise stored underdata.callbackId
sendWithStream
sendWithStream(actionName, data, queueingStrategy, transfers) {
const streamId = this.streamId++,
sourceName = this.sourceName,
targetName = this.targetName,
comObj = this.comObj;
return new ReadableStream(
{
start: controller => {
const startCapability = Promise.withResolvers();
this.streamControllers[streamId] = {
controller,
startCall: startCapability,
pullCall: null,
cancelCall: null,
isClosed: false,
};
comObj.postMessage(
{
sourceName, targetName,
action: actionName,
streamId, data,
desiredSize: controller.desiredSize,
},
transfers
);
return startCapability.promise;
},
pull: controller => {
const pullCapability = Promise.withResolvers();
this.streamControllers[streamId].pullCall = pullCapability;
comObj.postMessage({
sourceName, targetName,
stream: StreamKind.PULL,
streamId,
desiredSize: controller.desiredSize,
});
return pullCapability.promise;
},
cancel: reason => {
assert(reason instanceof Error, "cancel must have a valid reason");
const cancelCapability = Promise.withResolvers();
this.streamControllers[streamId].cancelCall = cancelCapability;
this.streamControllers[streamId].isClosed = true;
comObj.postMessage({
sourceName, targetName,
stream: StreamKind.CANCEL,
streamId,
reason: wrapReason(reason),
});
return cancelCapability.promise;
},
},
queueingStrategy
);
}
Before we trace this method, let's recall what ReadableStream is and why PDF.js picks it here.
ReadableStream
Streams let you break a resource you want to fetch over the network into small chunks, then process those chunks. This is exactly how browsers handle video buffers and progressive image rendering. — MDN
The old all-at-once download has two problems:
- Memory — loading a multi-GB binary into a single buffer blows up the heap.
- Latency — a 100-second video cannot begin playback until the download finishes. The same applies to PDFs: loading the entire file before rendering means the first paint waits for all bytes.
Note: Non-linearized PDFs (xref table at the end) force Chrome PDFium into full-download mode too. Only linearized ("Fast Web View") PDFs stream progressively.
ReadableStream takes a builder object with three callbacks:
| Callback | When it fires | Responsibility |
|---|---|---|
start(controller) | immediately on new | Initialize resources; do not produce data |
pull(controller) | consumer calls read() and queue is empty | Produce a chunk or close the stream |
cancel(reason) | stream is cancelled | Clean up resources |
Three usage patterns:
| Pattern | Producer role | When production happens | When pull fires | Typical use case |
|---|---|---|---|---|
| start-only | Active push | setInterval / onmessage shoves chunks in | Never (queue stays full) | WebSocket / SSE push |
| pull-only | Passive pull | Consumer-driven | Every read() when queue empty | Instantly-computable data, TransformStream readable side |
| start + pull | Warm-up + on-demand | start initializes, pull produces | Every read() when queue empty | fetch(), DB pagination, pipe pipelines |
Key invariants: enqueue() never blocks — it always returns synchronously. The queue length (the negative of desiredSize) is a suggestion, not a hard gate. pull only fires when the queue is empty and the consumer calls read() — that is natural backpressure. Default highWaterMark = 1, so desiredSize = highWaterMark - queue.length.
start + pull minimal example (the exact pattern PDF.js uses)
let pullCount = 0;
const stream = new ReadableStream({
start(controller) {
this.resource = { ready: true }; // "open a remote connection"
console.log('start: channel ready');
},
pull(controller) {
pullCount++;
controller.enqueue(new Uint8Array([pullCount]));
if (pullCount >= 5) controller.close();
},
cancel() { pullCount = 0; },
});
// start runs first (logs "channel ready"), then pull fires on read() when queue is empty
await stream.getReader().read();
💡 Try all three patterns live in the browser: start-only demo · pull-only demo · start + pull demo
The Worker-side counterpart to sendWithStream
sendWithStream on the Main side returns a standard ReadableStream. On the Worker side, #onMessage receives a message with streamId and dispatches to #createStreamSink, which builds a custom streamSink object — the mirror of the Main-side controller but for the producer role.
#createStreamSink(data) {
const streamId = data.streamId,
sourceName = this.sourceName,
targetName = data.sourceName,
comObj = this.comObj;
const self = this,
action = this.actionHandler[data.action];
const streamSink = {
enqueue(chunk, size = 1, transfers) {
if (this.isCancelled) return;
const lastDesiredSize = this.desiredSize;
this.desiredSize -= size;
// When desiredSize crosses from positive to non-positive,
// we create an unresolved Promise that the producer will await.
if (lastDesiredSize > 0 && this.desiredSize <= 0) {
this.sinkCapability = Promise.withResolvers();
this.ready = this.sinkCapability.promise;
}
comObj.postMessage(
{
sourceName, targetName,
stream: StreamKind.ENQUEUE,
streamId, chunk,
},
transfers
);
},
close() {
if (this.isCancelled) return;
this.isCancelled = true;
comObj.postMessage({
sourceName, targetName,
stream: StreamKind.CLOSE,
streamId,
});
delete self.streamSinks[streamId];
},
error(reason) {
assert(reason instanceof Error, "error must have a valid reason");
if (this.isCancelled) return;
this.isCancelled = true;
comObj.postMessage({
sourceName, targetName,
stream: StreamKind.ERROR,
streamId,
reason: wrapReason(reason),
});
},
sinkCapability: Promise.withResolvers(),
onPull: null,
onCancel: null,
isCancelled: false,
desiredSize: data.desiredSize,
ready: null,
};
streamSink.sinkCapability.resolve();
streamSink.ready = streamSink.sinkCapability.promise;
this.streamSinks[streamId] = streamSink;
Promise.try(action, data.data, streamSink).then(
function () {
comObj.postMessage({
sourceName, targetName,
stream: StreamKind.START_COMPLETE,
streamId, success: true,
});
},
function (reason) {
comObj.postMessage({
sourceName, targetName,
stream: StreamKind.START_COMPLETE,
streamId, reason: wrapReason(reason),
});
}
);
}
The handler registered with on is invoked with (data.data, streamSink). Once it resolves, the Worker posts START_COMPLETE back, letting the Main side's start() Promise settle.
Example: GetOperatorList
Main side — PDFPageProxy._pumpOperatorList:
const readableStream = this._transport.messageHandler.sendWithStream(
'GetOperatorList',
{
pageId: this.#pagesMapper.getPageId(this._pageIndex + 1) - 1,
pageIndex: this._pageIndex,
intent: renderingIntent,
cacheKey, annotationStorage: map, modifiedIds,
},
/* queueingStrategy = */ undefined,
transfer,
);
const reader = readableStream.getReader();
const intentState = this._intentStates.get(cacheKey);
intentState.streamReader = reader;
const pump = () => {
reader.read().then(
({ value, done }) => {
if (done) {
intentState.streamReader = null;
return;
}
if (this._transport.destroyed) return;
this._renderPageChunk(value, intentState);
pump();
},
reason => {
intentState.streamReader = null;
if (this._transport.destroyed) return;
if (intentState.operatorList) {
intentState.operatorList.lastChunk = true;
for (const internalRenderTask of intentState.renderTasks) {
internalRenderTask.operatorListChanged();
}
this.#tryCleanup();
}
if (intentState.displayReadyCapability) {
intentState.displayReadyCapability.reject(reason);
} else if (intentState.opListReadCapability) {
intentState.opListReadCapability.reject(reason);
} else {
throw reason;
}
},
);
};
pump();
Worker side — handler registered in WorkMessageHandler.createDocumentHandler:
handler.on(
'GetOperatorList',
function ({ pageId, pageIndex, intent, cacheKey, annotationStorage, modifiedIds }, sink) {
pdfManager.getPage(pageId).then(function (page) {
const task = new WorkerTask(`GetOperatorList: page ${pageIndex}`);
startWorkerTask(task);
const start = verbosity >= VerbosityLevel.INFOS ? Date.now() : 0;
page
.getOperatorList({
handler, sink, task, intent, cacheKey,
annotationStorage, modifiedIds, pageIndex,
})
.then(
opListInfo => {
if (start) info(`${task.name}; time=${Date.now() - start}ms, len=${opListInfo.length}`);
sink.close();
},
reason => {
if (task.terminated) return;
sink.error(reason);
},
)
.finally(() => finishWorkerTask(task));
});
},
);
The handler doesn't return anything, so Promise.try(...) resolves immediately and #createStreamSink posts START_COMPLETE.
Back on Main: #processStreamMessage
#processStreamMessage(data) {
const streamId = data.streamId,
sourceName = this.sourceName,
targetName = data.sourceName,
comObj = this.comObj;
const streamController = this.streamControllers[streamId],
streamSink = this.streamSinks[streamId];
switch (data.stream) {
case StreamKind.START_COMPLETE:
if (data.success) {
streamController.startCall.resolve();
} else {
streamController.startCall.reject(wrapReason(data.reason));
}
break;
case StreamKind.PULL_COMPLETE:
if (data.success) {
streamController.pullCall.resolve();
} else {
streamController.pullCall.reject(wrapReason(data.reason));
}
break;
case StreamKind.PULL:
if (!streamSink) {
comObj.postMessage({ stream: StreamKind.PULL_COMPLETE, success: true });
break;
}
// desiredSize goes from negative to positive → resolve sink.ready,
// releasing the Worker-side backpressure
if (streamSink.desiredSize <= 0 && data.desiredSize > 0) {
streamSink.sinkCapability.resolve();
}
streamSink.desiredSize = data.desiredSize;
Promise.try(streamSink.onPull).then(
() => comObj.postMessage({ stream: StreamKind.PULL_COMPLETE, success: true }),
reason => comObj.postMessage({ stream: StreamKind.PULL_COMPLETE, reason })
);
break;
case StreamKind.ENQUEUE:
// Worker produced a chunk → stuff it into the ReadableStream internal queue
if (streamController.isClosed) break;
streamController.controller.enqueue(data.chunk);
break;
case StreamKind.CLOSE:
streamController.isClosed = true;
streamController.controller.close();
this.#deleteStreamController(streamController, streamId);
break;
case StreamKind.ERROR:
streamController.controller.error(wrapReason(data.reason));
this.#deleteStreamController(streamController, streamId);
break;
default:
throw new Error("Unexpected stream case");
}
}
START_COMPLETE resolves the start() Promise. Then the pump() loop runs:
reader.read() queue empty → triggers pull callback
→ postMessage(PULL, desiredSize)
↓
Worker: onPull → produces chunk(s)
↓
postMessage(ENQUEUE) or (CLOSE)
↓
Main: controller.enqueue(chunk)
↓
reader.read() resolves → _renderPageChunk → pump() (recursion)
↓
repeats until CLOSE → done: true
Backpressure in action: every sink.enqueue(chunk, size) on the Worker side decrements desiredSize. When it crosses from positive to non-positive, sink.ready becomes an unresolved Promise. The Worker's parsing loop await sink.ready — not a spin-wait, not a busy loop — just suspends the async function. When the Main side drains its queue and sends the next PULL with a fresh desiredSize, the Worker resolves sink.ready and resumes. Both sides run at the consumer's pace; memory stays bounded.
Summary
PDF.js's MessageHandler layers three communication abstractions over the same postMessage primitive:
| Method | Pattern | Use case | Message shape |
|---|---|---|---|
| send | Fire-and-forget | Notifications (ready, close, commonobj) | One-way, no reply |
| sendWithPromise | Request-response | One-shot async queries (getPage, getMetadata) | callbackId pairs the call with exactly one reply |
| sendWithStream | Streaming + backpressure | Large continuous data (operatorList, images, fonts) | streamId ties a sequence of PULL/ENQUEUE/CLOSE messages together |
The progression is deliberate:
sendWithPromiseissendplus acallbackId— it pairs a Promise's resolve/reject with a message round-trip.sendWithStreamissendplusstart/pull— the Main side gets a realReadableStream, while the Worker side gets a customstreamSink. The interfaces are asymmetric, butpostMessagemessages tagged with astreamfield (PULL,ENQUEUE,CLOSE,ERROR,PULL_COMPLETE,START_COMPLETE,CANCEL,CANCEL_COMPLETE) keep them coordinated.
sendWithStream is the article's centerpiece — it is the reason PDF.js can parse and render concurrently with bounded memory. The implementation is a textbook ReadableStream:
startsendsSTARTand waits forSTART_COMPLETE— the Main side'sstart()Promise settlespullsendsPULL; the Worker'sstreamSink.onPullproduces data and postsENQUEUE— noread()on Main means no data produced on Worker- Backpressure is Worker-local:
sink.enqueuedecrementsdesiredSize; crossing non-positive hangssink.ready; the Worker parsing loopawait ready; the nextPULLwith a largerdesiredSizeresolves it
What makes this elegant is that the Worker never blocks the JS thread. It doesn't spin on while (desiredSize <= 0) — it suspends an async function with a Promise. The Main and Worker both process other messages concurrently; backpressure just politely asks the Worker to "take a breather".
And the entire contract is just one number (desiredSize) travelling on each side of a postMessage, plus one Promise whose resolve/reject signals how much the consumer wants right now.
More from PDF.js Deep Dive
- PDF.js Deep Dive 1: The Architecture of PDF.jsOctober 16, 2026
- PDF.js Deep Dive 2: getDocument & getPageOctober 19, 2026
- PDF.js Deep Dive 3: getViewport & renderOctober 22, 2026
- PDF.js Deep Dive 5: PDFFetchStream and PDFWorkerStreamOctober 25, 2026
- PDF.js Deep Dive 6: PDFManager.initDocumentOctober 25, 2026