PDF.js Deep Dive from Demo 2: getDocument

Introduction

The demo in the previous article called getDocument with only { url: '...' }. This article follows that single call through the full execution chain of getDocument.

The getDocument call

The source parameter is named src. The demo passes only one key:

Based on the definition of getDocument in display/api.js, the execution flow is as follows.

Lines 235-236: Initialize the loading task

Instantiate the PDFDocumentLoadingTask class: view source, and assign the return value to the task variable.

Extract docId from task; at this point docId is d0.

Lines 238-335: Validate and process parameters

This block of code expands the user-provided src object into 35+ local variables: provided values are validated and type-converted, while missing ones fall back to defaults. The demo only passes url, so the vast majority of parameters take the default branch.

The only provided url is converted into a URL object by getUrlProp:

const url = URL.parse('https://assets-blog.streampdf.com/PDF32000_2008.pdf', window.location); // const url = src.url ? getUrlProp(src.url) : null; 

All other parameters are absent. In source order, the computed results are:

These are all the local variables produced by this block of code. Most of the checks are trivial "fall back to default when absent" cases, but a few deserve a closer look.

ignoreErrors: a semantically inverted internal variable

The user-facing parameter is called stopAtErrors, yet the internal variable is called ignoreErrors, computed as src.stopAtErrors !== true. In other words, the default behavior is to ignore errors: when parsing fails, try to recover rather than rejecting promises such as getOperatorList / getTextContent / RenderTask. When reading the source, it is very easy to copy the name and value the wrong way around here.

rangeChunkSize: the 64KB setup for later

rangeChunkSize defaults to 64KB. Since disableRange = false, when the transport is created later, range requests will be issued against the PDF, and each fetched chunk will be exactly this size. Keep it in mind for now.

docBaseUrl: why data: URLs are excluded

The source comment explains the reason: a data: URL cannot be used to resolve absolute paths, and it contains the entire PDF document with no upper bound on length, so it is not sent to the worker thread.

gpuPromise: designed to run in parallel with worker startup

const gpuPromise = Promise.resolve(false); // enableWebGPU ? initGPU() : Promise.resolve(false); 

Even when WebGPU is disabled, this immediately returns a resolved promise instead of deferring the check until it is used. The comment explains the intent: let GPU initialization run in parallel with worker startup, with the resolved boolean forwarded to the worker afterwards.

The three Factories: environment branches

const CanvasFactory = DOMCanvasFactory; // src.CanvasFactory || (GENERIC build && isNodeJS ? NodeCanvasFactory : DOMCanvasFactory); 

The same applies to FilterFactory and BinaryDataFactory. The check has three tiers: user-provided custom > Node environment implementation > DOM implementation. The demo runs in a browser without customization, so all three factories are the DOM versions. Their responsibilities:

• CanvasFactory: creates canvases for rendering
• FilterFactory: creates image filters (such as SVG filters)
• BinaryDataFactory: downloads built-in static assets; works together with useWorkerFetch below

useSystemFonts: the default depends on other parameters

const useSystemFonts = true; // typeof src.useSystemFonts === "boolean" ? src.useSystemFonts : !isNodeJS && !disableFontFace; 

Its default depends on disableFontFace, which was just parsed above. Why? Fonts not embedded in the PDF are loaded as FontFaces; if disableFontFace is true, that loading path is disabled, and falling back to system fonts at that point would produce completely garbled glyphs. So in that scenario the default is simply false as well, avoiding rendering utterly broken fonts.

useWorkerFetch: a compound check

const useWorkerFetch = false; // typeof src.useWorkerFetch === "boolean" // ? src.useWorkerFetch // : MOZCENTRAL || // !!( // BinaryDataFactory === DOMBinaryDataFactory && // cMapUrl && cMapPacked && standardFontDataUrl && wasmUrl && // isValidFetchUrl(cMapUrl, document.baseURI) && // isValidFetchUrl(standardFontDataUrl, document.baseURI) && // isValidFetchUrl(wasmUrl, document.baseURI) // ); 

Q: What is this check doing?
A: It decides who downloads the built-in static assets (CMap files, standard font files, wasm files): the worker thread downloads them itself via the Fetch API (true), or the main thread downloads them and forwards them to the worker (false).

If the user explicitly passes a boolean, the user's value is used directly. Otherwise the default is computed: MOZCENTRAL (the Firefox built-in viewer) is always true; for a regular build, all three of the following conditions must hold at the same time for it to be true:

1. No custom BinaryDataFactory — because when useWorkerFetch is true, that parameter is simply ignored (inside transportFactory, binaryDataFactory is set to null). A user-provided factory must be respected, so the default cannot be true;
2. cMapUrl / standardFontDataUrl / wasmUrl are all provided, and cMapPacked is true — without URLs there is nothing to fetch;
3. These three URLs resolve to http/https relative to document.baseURI — the Fetch API only supports http/https, not file/ftp.

The demo in this article only passes url, so cMapUrl is null, condition 2 is not met, and therefore useWorkerFetch = false: the main-thread path is taken, with DOMBinaryDataFactory downloading on the main thread, and the worker requesting data from the main thread via FetchBinaryData messages when needed.

Lines 338: Set the main-thread log level

setVerbosityLevel(verbosity); // verbosity is undefined 

verbosity is undefined, so the main-thread log level stays at its default. Note that this only affects the main thread; the worker thread's log level is passed separately when the worker is created.

Lines 342-350: Instantiate the three factories

const transportFactory = { canvasFactory: new DOMCanvasFactory({ ownerDocument: document, enableHWA: false }), filterFactory: new DOMFilterFactory({ docId: 'd0', ownerDocument: document }), binaryDataFactory: new DOMBinaryDataFactory({ cMapUrl: null, standardFontDataUrl: null, wasmUrl: null, }), }; // binaryDataFactory: null when MOZCENTRAL or useWorkerFetch is true 

The three Factory classes selected earlier are instantiated and packaged as transportFactory, which is then handed to the transport. Since useWorkerFetch = false, binaryDataFactory is not null — echoing the Q&A in the previous section: built-in static assets are downloaded on the main thread.

Instantiate DOMCanvasFactory: view source

Instantiate DOMFilterFactory: view source

Instantiate DOMBinaryDataFactory: view source

Lines 352-360: Create the worker

worker = PDFWorker.create({ verbosity: undefined, port: undefined }); // port comes from GlobalWorkerOptions.workerPort, which the demo does not set task._worker = worker; 

The demo does not pass a worker, so PDF.js creates and owns one itself. PDFWorker.create synchronously returns a PDFWorker instance; its constructor reads GlobalWorkerOptions.workerSrc (the worker file URL configured in the first article), creates a Worker, and completes the startup handshake through ready / test messages — covered in detail in Article 8. For now, just remember: worker.promise is a Promise<void> that resolves (to undefined) once the test reply succeeds, and rejects if startup fails or the worker is destroyed.

Lines 362-402: Assemble the two parameter packages

The first is docParams, which will later be sent across threads to the worker:

const docParams = { docId: 'd0', apiVersion: '6.3.289', // build version number data: null, password: null, disableAutoFetch: false, rangeChunkSize: 65536, docBaseUrl: null, enableXfa: false, evaluatorOptions: { maxImageSize: -1, disableFontFace: false, ignoreErrors: true, isOffscreenCanvasSupported: true, isImageDecoderSupported: true, canvasMaxAreaInBytes: -1, fontExtraProperties: false, useSystemFonts: true, useWasm: true, useWorkerFetch: false, cMapUrl: null, cMapPacked: true, iccUrl: null, standardFontDataUrl: null, wasmUrl: null, hasGPU: false, // placeholder, backfilled later }, }; 

The second is transportParams, which stays on the main thread:

const transportParams = { ownerDocument: document, pdfBug: false, styleElement: null, enableHWA: false, loadingParams: { disableAutoFetch: false, enableXfa: false }, }; 

One sentence to distinguish them: docParams is the "work order" sent to the worker, while transportParams is the "local configuration" kept on the main thread.

Lines 404-473: The handshake after the worker is ready

Promise.all([worker.promise, gpuPromise]).then(...) 

Once both worker readiness and GPU probing (resolving to false) complete, the following happens in sequence:

1. hasGPU = false is backfilled into evaluatorOptions;
2. A GetDocRequest message is sent to the worker with docParams as the payload. Since data is null, there is no buffer whose ownership needs to be transferred;
3. Choose the network stream: with data being null and rangeTransport being null, the url branch is taken and a network stream is instantiated (the fetch implementation is preferred, with a fallback to XHR when unsupported; see Article 9 for how range requests are issued internally):

networkStream = new NetworkStream({ url, httpHeaders: null, withCredentials: false, rangeChunkSize: 65536, disableRange: false, disableStream: false, }); 

NetworkStream here is not a fixed imported class; it is picked at runtime inside this branch:

const NetworkStream = getNetworkStream(url); // api.js#L431 

getNetworkStream makes a three-way choice:

function getNetworkStream(url) { // eslint-disable-next-line no-nested-ternary return isValidFetchUrl(url) ? PDFFetchStream : typeof PDFJSDev !== 'undefined' && PDFJSDev.test('GENERIC') && isNodeJS ? PDFNodeStream : PDFNetworkStream; } 

The demo's url is https://..., so it actually instantiates PDFFetchStream. The other inputs have their own streams too: rangeTransport uses PDFDataTransportStream, while data means the whole PDF is already in memory and no stream is created at all.

In summary: const NetworkStream = PDFFetchStream.

Execution continues:

1. Receive the worker's acknowledgment of GetDocRequest (workerId): click to view the event. The value returned here is d0_worker, assigned to the workerId variable
2. Create a MessageHandler with { docId: 'd0', workerId: 'd0_worker', port: Worker }: click to view the call, assigned to the messageHandler variable
3. Create a WorkerTransport with { messageHandler, task, networkStream, transportParams, transportFactory, pagesMapper }: click to view the call, attached to task._transport
4. Send a Ready message to the worker, declaring the main-thread side ready: click to view the event

At the end of the chain, task._setupCapability.resolve is called to settle the task's asynchronous setup.

Lines 474-475: Return value

All of the above .then chain proceeds asynchronously in the background, while getDocument itself returns task synchronously. If any step in the chain fails, the capability inside task is rejected — the very promise that the demo waits on with await loadingTask.promise.

At this point, getDocument has finished executing.

Summary

In this section we followed the demo through the complete getDocument call:

1. Create PDFDocumentLoadingTask and extract docId = 'd0';
2. Expand src into 35+ local variables; the demo only passes url, and everything else falls back to defaults;
3. Instantiate the three DOM factories and package them as transportFactory;
4. PDFWorker.create creates the worker and starts the handshake;
5. Assemble docParams (sent to the worker) and transportParams (kept on the main thread);
6. Once the worker is ready, send GetDocRequest, set up the network stream, create MessageHandler and WorkerTransport, and finally send Ready;
7. Return task synchronously; the demo waits for the document to be ready via await loadingTask.promise.

Back to the demo in the first article: lines 4-7 call exactly the getDocument dissected here.

Following the caller chain upward, the next call site is: getPage

About me: Creator of StreamPDF, focused on research and development in AI and PDF.

Original article: https://streampdf.com/blog/pdfjs-deep-dive-from-demo-1-custom-viewer