pdfBuilder

Chainable constructive DSL for assembling a PDF document from scratch.

Module pdfBuilder | Source packages/front/office/pdf/src/document/builder.js | Deps pdfErrors, pdfParserObj, pdfWriter | Worker-safe yes

An ergonomic layer over pdfWriter.writeDocument: instead of hand-assembling a typed indirect-object graph, builder() returns a chainable object (addPage → addContent/addFont/addImage → … → build()) that tracks pages, content streams, fonts (referenced or embedded), image XObjects and the Info dict internally, then emits Uint8Array bytes on .build(). The returned chain is closure-based (no class, no this), so it stays worker-transportable.

Resolve

const b = runtime.resolve('pdfBuilder');
// Returns: { builder }
const doc = b.builder();
// doc: { addPage, addContent, addFont, addImage, addMetadata, setVersion, setId, build }

API

Builder chain

Every chain method except build returns the same Builder instance.

addFont spec — non-embedded shape

Shared dictionary. A non-embedded font dictionary is allocated once per distinct (baseFont, subtype, encoding) and shared by every page that registers it: subtype is the defaulted value, so { baseFont: 'Helvetica' } and { baseFont: 'Helvetica', subtype: 'Type1' } share one object. Each page (and each resource name) still gets its own /Resources /Font entry; only the referenced object is shared. A 3-page document that registers the same four faces on every page therefore carries 4 font dictionaries, not 12. A document that never repeats a (baseFont, subtype, encoding) triple is byte-identical to one built without sharing.

Examples

Minimal one-page document

const { builder } = runtime.resolve('pdfBuilder');
const bytes = builder()
    .addPage({ mediaBox: [0, 0, 612, 792] })
    .build();

Page with a font and content stream

const bytes = builder()
    .addPage({ mediaBox: [0, 0, 612, 792] })
    .addFont({ name: 'F1', baseFont: 'Helvetica', subtype: 'Type1' })
    .addContent('BT /F1 12 Tf 100 700 Td (Hello) Tj ET')
    .build();

Metadata + explicit /ID

const bytes = builder()
    .addPage()
    .addMetadata({ Title: 'Demo', Author: 'awa' })
    .setId('0102030405060708090a0b0c0d0e0f10')
    .build();

Embedded fonts

addFont({ name, embedded }) accepts a pdfFontEmbed result — embedSimple (a SimpleEmbed: /TrueType + /WinAnsiEncoding) or embedCid (a CidEmbed: /Type0 + /Identity-H + /CIDFontType2). The adapter deliberately returns inline dicts and leaves every indirect to its consumer; the builder is that consumer.

An embedded value must carry fontFile (Uint8Array), descriptor, toUnicodeStream and either fontDict or type0Dict + cidFontDict — never both — else pdf/builder/bad-font.

What gets allocated

Per embed result object, not per addFont call:

So a simple embedding costs 4 indirects and a composite one 5 — i.e. +3 and +4 over the single object a legacy addFont allocates. Only the last one lands in the page's /Resources /Font.

Identity cache. The builder keeps a WeakMap keyed by the embedded object, so registering the same result on several pages (under any resource names) allocates the graph once and every page references the same font object number. Two distinct results — even from the same face — are two graphs.

No mutation. Every patched dict is shallow-cloned; the caller's descriptor / fontDict / type0Dict / cidFontDict come back exactly as pdfFontEmbed returned them, so one result can be reused across builders.

Example — pdfFontEmbed → addFont → addContent

const fontsMod = runtime.resolve('fonts');
const embed    = runtime.resolve('pdfFontEmbed');
const { builder } = runtime.resolve('pdfBuilder');

const face = fontsMod.read(ttfBytes);
const text = 'Unicode fi ⁄ ⁴';
const cps  = [...new Set([...text].map(c => c.codePointAt(0)))];

const e = embed.embedCid(face, cps);           // or embedSimple for WinAnsi
const hex = [...e.encode(text)]
    .map(b => b.toString(16).padStart(2, '0')).join('');

const bytes = builder()
    .addPage({ mediaBox: [0, 0, 612, 792] })
    .addFont({ name: 'F1', embedded: e })
    .addContent(`BT /F1 12 Tf 72 700 Td <${hex}> Tj ET`)
    .build();

e.encode(text) yields the character codes the written font expects — WinAnsi bytes for the simple route, big-endian 2-byte CIDs for Identity-H — and e.widthOf(codePoint) gives the 1000/em advance for layout.

Images

addImage({ name, … }) is the image counterpart of addFont's embedded route: it allocates the image as an indirect stream object — the serializer refuses an inline one — and maps name to it in the current page's /Resources /XObject.

The seam decodes nothing. The caller supplies data that is already encoded plus the parameters that describe it. This module does not parse a PNG IHDR, a JPEG SOF, or anything else; it does not transcode, resample or colour-manage, and it never inspects data — the bytes reach the file verbatim. Choosing /Filter, /ColorSpace and /BitsPerComponent consistently with those bytes is the caller's job.

And it places no ink. addImage makes the resource reachable; drawing it is a content-stream matter, so the caller emits the operators itself (see the snippet below).

Spec

The emitted dict is << /Type /XObject /Subtype /Image /Width … /Height … /ColorSpace … /BitsPerComponent … >>, plus /Filter, /DecodeParms and /SMask when those were given.

Soft masks

An sMask is allocated first, as its own image XObject, and the parent's /SMask holds a reference to it. It is referenced, never named: it does not appear in the page's /XObject dict, so no content operator can draw it directly. A masked image therefore costs 2 indirects instead of 1.

builder().addPage()
    .addImage({
        name: 'Im0', width: w, height: h,
        colorSpace: 'DeviceRGB', bitsPerComponent: 8,
        filter: 'FlateDecode', data: rgbDeflated,
        sMask: {                       // no `name` here
            width: w, height: h,
            colorSpace: 'DeviceGray', bitsPerComponent: 8,
            filter: 'FlateDecode', data: alphaDeflated
        }
    })
    .build();

Resource precedence

/XObject follows the pre-existing /Font rule exactly: addPage's resources passthrough is merged after the built resource classes and only fills keys the builder did not produce. So on a page that called addImage, a caller-supplied /XObject is dropped; on a page that did not, it passes through untouched. Nothing about that rule changed.

Example — place a JPEG on the page

const bytes = builder()
    .addPage({ mediaBox: [0, 0, 612, 792] })
    .addImage({
        name: 'Im0',
        width: 800, height: 600,          // the image's own pixel size
        colorSpace: 'DeviceRGB',
        bitsPerComponent: 8,
        filter: 'DCTDecode',              // the bytes ARE a JPEG already
        data: jpegBytes
    })
    // The seam placed the resource; the caller places the ink.
    // `cm` is width height 0 0 x y in USER SPACE units, not pixels:
    // 400x300 pt with its lower-left corner at (100, 400).
    .addContent('q 400 0 0 300 100 400 cm /Im0 Do Q')
    .build();

q … Q brackets the transform so the CTM is restored afterwards; the image XObject's own space is the unit square, which is why the cm matrix carries the on-page size directly.

Errors

It also propagates every code from pdfWriter (raised inside writeDocument).

See also

• pdfWriter — the underlying emitter.
• pdfFontEmbed — produces the embedded value (embedSimple / embedCid).
• pdfParserObj — typed-object constructors (obj.dict, obj.ref, …) used internally.
• pdfIncrementalWriter · pdfEncryptedWriter