PDF-Lite Examples

This directory contains example scripts demonstrating how to use the PDF-Lite library.

PDF creation from scratch example

import { writeFileSync } from 'fs'
import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
import { PdfDictionary } from 'pdf-lite/core/objects/pdf-dictionary'
import { PdfIndirectObject } from 'pdf-lite/core/objects/pdf-indirect-object'
import { PdfName } from 'pdf-lite/core/objects/pdf-name'
import { PdfNumber } from 'pdf-lite/core/objects/pdf-number'
import { PdfObjectReference } from 'pdf-lite/core/objects/pdf-object-reference'
import { PdfStream } from 'pdf-lite/core/objects/pdf-stream'
import { PdfDocument } from 'pdf-lite/pdf/pdf-document'

function createPage(
    contentStreamRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const pageDict = new PdfDictionary()
    pageDict.set('Type', new PdfName('Page'))
    pageDict.set(
        'MediaBox',
        new PdfArray([
            new PdfNumber(0),
            new PdfNumber(0),
            new PdfNumber(612),
            new PdfNumber(792),
        ]),
    )
    pageDict.set('Contents', contentStreamRef)
    return new PdfIndirectObject({ content: pageDict })
}

function createPages(
    pages: PdfIndirectObject<PdfDictionary>[],
): PdfIndirectObject<PdfDictionary> {
    const pagesDict = new PdfDictionary()
    pagesDict.set('Type', new PdfName('Pages'))
    pagesDict.set('Kids', new PdfArray(pages.map((x) => x.reference)))
    pagesDict.set('Count', new PdfNumber(pages.length))
    return new PdfIndirectObject({ content: pagesDict })
}

function createCatalog(
    pagesRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const catalogDict = new PdfDictionary()
    catalogDict.set('Type', new PdfName('Catalog'))
    catalogDict.set('Pages', pagesRef)
    return new PdfIndirectObject({ content: catalogDict })
}

function createFont(): PdfIndirectObject<PdfDictionary> {
    const fontDict = new PdfDictionary()
    fontDict.set('Type', new PdfName('Font'))
    fontDict.set('Subtype', new PdfName('Type1'))
    fontDict.set('BaseFont', new PdfName('Helvetica'))
    return new PdfIndirectObject({ content: fontDict })
}

function createResources(
    fontRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const resourcesDict = new PdfDictionary()
    const fontDict = new PdfDictionary()
    fontDict.set('F1', fontRef)
    resourcesDict.set('Font', fontDict)
    return new PdfIndirectObject({ content: resourcesDict })
}

// Create the document
const document = new PdfDocument()

// Create font
const font = createFont()
document.add(font)

// Create resources with the font
const resources = createResources(font.reference)
document.add(resources)

// Create content stream
const contentStream = new PdfIndirectObject({
    content: new PdfStream({
        header: new PdfDictionary(),
        original: 'BT /F1 24 Tf 100 700 Td (Hello, PDF-Lite!) Tj ET',
    }),
})

// Create a page
const page = createPage(contentStream.reference)
// Add resources to the page
page.content.set('Resources', resources.reference)
document.add(page)

// Create pages collection
const pages = createPages([page])
// Set parent reference for the page
page.content.set('Parent', pages.reference)
document.add(pages)

// Create catalog
const catalog = createCatalog(pages.reference)
document.add(catalog)

// Set the catalog as the root
document.trailerDict.set('Root', catalog.reference)

document.add(contentStream)
await document.commit()

const file = `${import.meta.dirname}/tmp/created.pdf`
console.log(`Writing PDF to: ${file}`)

await writeFileSync(`${file}`, document.toBytes())
Copy

PDF creation with encryption example

import { writeFileSync } from 'fs'
import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
import { PdfDictionary } from 'pdf-lite/core/objects/pdf-dictionary'
import { PdfIndirectObject } from 'pdf-lite/core/objects/pdf-indirect-object'
import { PdfName } from 'pdf-lite/core/objects/pdf-name'
import { PdfNumber } from 'pdf-lite/core/objects/pdf-number'
import { PdfObjectReference } from 'pdf-lite/core/objects/pdf-object-reference'
import { PdfStream } from 'pdf-lite/core/objects/pdf-stream'
import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
import { PdfV2SecurityHandler } from 'pdf-lite/security/handlers/v2'

function createPage(
    contentStreamRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const pageDict = new PdfDictionary()
    pageDict.set('Type', new PdfName('Page'))
    pageDict.set(
        'MediaBox',
        new PdfArray([
            new PdfNumber(0),
            new PdfNumber(0),
            new PdfNumber(612),
            new PdfNumber(792),
        ]),
    )
    pageDict.set('Contents', contentStreamRef)
    return new PdfIndirectObject({ content: pageDict })
}

function createPages(
    pages: PdfIndirectObject<PdfDictionary>[],
): PdfIndirectObject<PdfDictionary> {
    const pagesDict = new PdfDictionary()
    pagesDict.set('Type', new PdfName('Pages'))
    pagesDict.set('Kids', new PdfArray(pages.map((x) => x.reference)))
    pagesDict.set('Count', new PdfNumber(pages.length))
    return new PdfIndirectObject({ content: pagesDict })
}

function createCatalog(
    pagesRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const catalogDict = new PdfDictionary()
    catalogDict.set('Type', new PdfName('Catalog'))
    catalogDict.set('Pages', pagesRef)
    return new PdfIndirectObject({ content: catalogDict })
}

function createFont(): PdfIndirectObject<PdfDictionary> {
    const fontDict = new PdfDictionary()
    fontDict.set('Type', new PdfName('Font'))
    fontDict.set('Subtype', new PdfName('Type1'))
    fontDict.set('BaseFont', new PdfName('Helvetica'))
    return new PdfIndirectObject({ content: fontDict })
}

function createResources(
    fontRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const resourcesDict = new PdfDictionary()
    const fontDict = new PdfDictionary()
    fontDict.set('F1', fontRef)
    resourcesDict.set('Font', fontDict)
    return new PdfIndirectObject({ content: resourcesDict })
}

// Create the document
const document = new PdfDocument()

// Create font
const font = createFont()
document.add(font)

// Create resources with the font
const resources = createResources(font.reference)
document.add(resources)

// Create content stream
const contentStream = new PdfIndirectObject({
    content: new PdfStream({
        header: new PdfDictionary(),
        original: 'BT /F1 24 Tf 100 700 Td (Hello, PDF-Lite!) Tj ET',
    }),
})

// Create a page
const page = createPage(contentStream.reference)
// Add resources to the page
page.content.set('Resources', resources.reference)
document.add(page)

// Create pages collection
const pages = createPages([page])
// Set parent reference for the page
page.content.set('Parent', pages.reference)
document.add(pages)

// Create catalog
const catalog = createCatalog(pages.reference)
document.add(catalog)

// Set the catalog as the root
document.trailerDict.set('Root', catalog.reference)

document.add(contentStream)
await document.commit()

document.securityHandler = new PdfV2SecurityHandler({
    password: 'up',
    documentId: 'cafebabe',
    encryptMetadata: true,
})

await document.encrypt()

const file = `${import.meta.dirname}/tmp/encrypted.pdf`
console.log(`Writing encrypted PDF to: ${file}. Password: "up"`)

await writeFileSync(`${file}`, document.toBytes())
Copy

PDF signature example

import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
import { PdfDictionary } from 'pdf-lite/core/objects/pdf-dictionary'
import { PdfIndirectObject } from 'pdf-lite/core/objects/pdf-indirect-object'
import { PdfName } from 'pdf-lite/core/objects/pdf-name'
import { PdfNumber } from 'pdf-lite/core/objects/pdf-number'
import { PdfObjectReference } from 'pdf-lite/core/objects/pdf-object-reference'
import { PdfStream } from 'pdf-lite/core/objects/pdf-stream'
import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
import { PdfString } from 'pdf-lite/core/objects/pdf-string'
import {
    PdfAdbePkcsX509RsaSha1SignatureObject,
    PdfAdbePkcs7DetachedSignatureObject,
    PdfAdbePkcs7Sha1SignatureObject,
    PdfEtsiCadesDetachedSignatureObject,
    PdfEtsiRfc3161SignatureObject,
} from 'pdf-lite'
import { rsaSigningKeys } from '../packages/pdf-lite/test/unit/fixtures/rsa-2048/index'
import fs from 'fs/promises'

function createPage(
    contentStreamRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const pageDict = new PdfDictionary()
    pageDict.set('Type', new PdfName('Page'))
    pageDict.set(
        'MediaBox',
        new PdfArray([
            new PdfNumber(0),
            new PdfNumber(0),
            new PdfNumber(612),
            new PdfNumber(792),
        ]),
    )
    pageDict.set('Contents', contentStreamRef)
    return new PdfIndirectObject({ content: pageDict })
}

function createPages(
    pages: PdfIndirectObject<PdfDictionary>[],
): PdfIndirectObject<PdfDictionary> {
    const pagesDict = new PdfDictionary()
    pagesDict.set('Type', new PdfName('Pages'))
    pagesDict.set('Kids', new PdfArray(pages.map((x) => x.reference)))
    pagesDict.set('Count', new PdfNumber(pages.length))
    return new PdfIndirectObject({ content: pagesDict })
}

function createCatalog(
    pagesRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const catalogDict = new PdfDictionary()
    catalogDict.set('Type', new PdfName('Catalog'))
    catalogDict.set('Pages', pagesRef)
    return new PdfIndirectObject({ content: catalogDict })
}

function createFont(): PdfIndirectObject<PdfDictionary> {
    const fontDict = new PdfDictionary()
    fontDict.set('Type', new PdfName('Font'))
    fontDict.set('Subtype', new PdfName('Type1'))
    fontDict.set('BaseFont', new PdfName('Helvetica'))
    return new PdfIndirectObject({ content: fontDict })
}

function createResources(
    fontRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const resourcesDict = new PdfDictionary()
    const fontDict = new PdfDictionary()
    fontDict.set('F1', fontRef)
    resourcesDict.set('Font', fontDict)
    return new PdfIndirectObject({ content: resourcesDict })
}

function createPageWithSignatureField(
    contentStreamRef: PdfObjectReference,
    signatureAnnotRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const pageDict = new PdfDictionary()
    pageDict.set('Type', new PdfName('Page'))
    pageDict.set(
        'MediaBox',
        new PdfArray([
            new PdfNumber(0),
            new PdfNumber(0),
            new PdfNumber(612),
            new PdfNumber(792),
        ]),
    )
    pageDict.set('Contents', contentStreamRef)
    pageDict.set('Annots', new PdfArray([signatureAnnotRef]))

    return new PdfIndirectObject({ content: pageDict })
}

function createSignatureAnnotation(
    signatureRef: PdfObjectReference,
    appearanceStreamRef: PdfObjectReference,
    pageRef: PdfObjectReference,
    signatureName: string,
): PdfIndirectObject<PdfDictionary> {
    const signatureAnnotation = new PdfDictionary()
    signatureAnnotation.set('Type', new PdfName('Annot'))
    signatureAnnotation.set('Subtype', new PdfName('Widget'))
    signatureAnnotation.set('FT', new PdfName('Sig'))
    signatureAnnotation.set('T', new PdfString(signatureName))
    signatureAnnotation.set(
        'Rect',
        new PdfArray([
            new PdfNumber(135), // x1: Start after "Signature: " text (~72 + 63)
            new PdfNumber(640), // y1: Bottom of signature area (652 - 12)
            new PdfNumber(400), // x2: End of signature line
            new PdfNumber(665), // y2: Top of signature area (652 + 13)
        ]),
    )
    signatureAnnotation.set('F', new PdfNumber(4))
    signatureAnnotation.set('P', pageRef) // Reference to parent page
    signatureAnnotation.set('V', signatureRef)

    // Add appearance dictionary
    const appearanceDict = new PdfDictionary()
    appearanceDict.set('N', appearanceStreamRef)
    signatureAnnotation.set('AP', appearanceDict)

    return new PdfIndirectObject({ content: signatureAnnotation })
}

function createSignatureAppearance(): PdfIndirectObject<PdfStream> {
    // Create font for appearance
    const appearanceFont = new PdfDictionary()
    appearanceFont.set('Type', new PdfName('Font'))
    appearanceFont.set('Subtype', new PdfName('Type1'))
    appearanceFont.set('BaseFont', new PdfName('Helvetica'))

    const fontDict = new PdfDictionary()
    fontDict.set('F1', appearanceFont)

    const resourcesDict = new PdfDictionary()
    resourcesDict.set('Font', fontDict)

    // Create appearance stream header
    const appearanceHeader = new PdfDictionary()
    appearanceHeader.set('Type', new PdfName('XObject'))
    appearanceHeader.set('Subtype', new PdfName('Form'))
    appearanceHeader.set(
        'BBox',
        new PdfArray([
            new PdfNumber(0),
            new PdfNumber(0),
            new PdfNumber(265), // Width: 400 - 135
            new PdfNumber(25), // Height: 665 - 640
        ]),
    )
    appearanceHeader.set('Resources', resourcesDict)

    // Create appearance stream for the signature
    return new PdfIndirectObject({
        content: new PdfStream({
            header: appearanceHeader,
            original:
                'BT /F1 10 Tf 5 14 Td (Digitally signed by: Jake Shirley) Tj ET',
        }),
    })
}

// Create the document
const document = new PdfDocument()

// Create font
const font = createFont()
document.add(font)

// Create resources with the font
const resources = createResources(font.reference)
document.add(resources)

// Create content stream for first page
const contentStream = new PdfIndirectObject({
    content: new PdfStream({
        header: new PdfDictionary(),
        original: 'BT /F1 24 Tf 100 700 Td (Hello, PDF-Lite!) Tj ET',
    }),
})
document.add(contentStream)

// Create first page
const page1 = createPage(contentStream.reference)
page1.content.set('Resources', resources.reference)
document.add(page1)

// Array to hold all pages and signature objects
const allPages: PdfIndirectObject<PdfDictionary>[] = [page1]
const allSignatures: any[] = []
const signatureFields: PdfObjectReference[] = []

// Helper function to create a signature page
function createSignaturePage(
    signatureType: string,
    signatureObj: any,
    pageNumber: number,
) {
    const content = new PdfIndirectObject({
        content: new PdfStream({
            header: new PdfDictionary(),
            original: `BT /F1 12 Tf 72 712 Td (Signature Type: ${signatureType}) Tj 0 -60 Td (Signature: ________________________________) Tj ET`,
        }),
    })
    document.add(content)

    const appearance = createSignatureAppearance()
    document.add(appearance)

    // Create page first to get its reference
    const page = createPageWithSignatureField(
        content.reference,
        new PdfObjectReference(0, 0), // Temporary placeholder
    )
    page.content.set('Resources', resources.reference)
    document.add(page)

    // Now create annotation with page reference
    const annotation = createSignatureAnnotation(
        signatureObj.reference,
        appearance.reference,
        page.reference,
        `Signature${pageNumber}`,
    )
    document.add(annotation)

    // Update page's Annots array with actual annotation reference
    page.content.set('Annots', new PdfArray([annotation.reference]))

    signatureFields.push(annotation.reference)
    return page
}

// Page 2: Adobe PKCS7 Detached
const pkcs7DetachedSig = new PdfAdbePkcs7DetachedSignatureObject({
    privateKey: rsaSigningKeys.privateKey,
    certificate: rsaSigningKeys.cert,
    issuerCertificate: rsaSigningKeys.caCert,
    name: 'Jake Shirley',
    location: 'Earth',
    reason: 'PKCS7 Detached Signature',
    contactInfo: 'test@test.com',
    revocationInfo: {
        crls: [rsaSigningKeys.caCrl],
        ocsps: [rsaSigningKeys.ocspResponse],
    },
})
allSignatures.push(pkcs7DetachedSig)
allPages.push(createSignaturePage('Adobe PKCS7 Detached', pkcs7DetachedSig, 2))

// Page 3: Adobe PKCS7 SHA1
const pkcs7Sha1Sig = new PdfAdbePkcs7Sha1SignatureObject({
    privateKey: rsaSigningKeys.privateKey,
    certificate: rsaSigningKeys.cert,
    issuerCertificate: rsaSigningKeys.caCert,
    name: 'Jake Shirley',
    location: 'Earth',
    reason: 'PKCS7 SHA1 Signature',
    contactInfo: 'test@test.com',
})
allSignatures.push(pkcs7Sha1Sig)
allPages.push(createSignaturePage('Adobe PKCS7 SHA1', pkcs7Sha1Sig, 3))

// Page 4: Adobe X509 RSA SHA1
const x509RsaSha1Sig = new PdfAdbePkcsX509RsaSha1SignatureObject({
    privateKey: rsaSigningKeys.privateKey,
    certificate: rsaSigningKeys.cert,
    additionalCertificates: [rsaSigningKeys.caCert],
    name: 'Jake Shirley',
    location: 'Earth',
    reason: 'X509 RSA SHA1 Signature',
    contactInfo: 'test@test.com',
    revocationInfo: {
        crls: [rsaSigningKeys.caCrl],
        ocsps: [rsaSigningKeys.ocspResponse],
    },
})
allSignatures.push(x509RsaSha1Sig)
allPages.push(createSignaturePage('Adobe X509 RSA SHA1', x509RsaSha1Sig, 4))

// Page 5: ETSI CAdES Detached
const cadesDetachedSig = new PdfEtsiCadesDetachedSignatureObject({
    privateKey: rsaSigningKeys.privateKey,
    certificate: rsaSigningKeys.cert,
    issuerCertificate: rsaSigningKeys.caCert,
    name: 'Jake Shirley',
    location: 'Earth',
    reason: 'CAdES Detached Signature',
    contactInfo: 'test@test.com',
    revocationInfo: {
        crls: [rsaSigningKeys.caCrl],
        ocsps: [rsaSigningKeys.ocspResponse],
    },
})
allSignatures.push(cadesDetachedSig)
allPages.push(createSignaturePage('ETSI CAdES Detached', cadesDetachedSig, 5))

// Page 6: ETSI RFC3161 (Timestamp)
const rfc3161Sig = new PdfEtsiRfc3161SignatureObject({
    timeStampAuthority: {
        url: 'https://freetsa.org/tsr',
    },
})
allSignatures.push(rfc3161Sig)
allPages.push(createSignaturePage('ETSI RFC3161 Timestamp', rfc3161Sig, 6))

// Create pages collection with all pages
const pages = createPages(allPages)
// Set parent reference for all pages
allPages.forEach((page) => {
    page.content.set('Parent', pages.reference)
})
document.add(pages)

// Create catalog with AcroForm
const catalog = createCatalog(pages.reference)

// Add AcroForm to catalog with all signature fields
const acroForm = new PdfDictionary()
acroForm.set('Fields', new PdfArray(signatureFields))
acroForm.set('SigFlags', new PdfNumber(3))
const acroFormObj = new PdfIndirectObject({ content: acroForm })
document.add(acroFormObj)
catalog.content.set('AcroForm', acroFormObj.reference)

document.add(catalog)

// Set the catalog as the root
document.trailerDict.set('Root', catalog.reference)

// IMPORTANT: Add all signatures LAST - after all other objects
// This ensures the ByteRange is calculated correctly for each signature
allSignatures.forEach((sig) => {
    document.startNewRevision()
    document.add(sig)
})

await document.commit()

const tmpFolder = `${import.meta.dirname}/tmp`
await fs.mkdir(tmpFolder, { recursive: true })
await fs.writeFile(`${tmpFolder}/signed-output.pdf`, document.toBytes())
Copy

Incremental PDF update example

import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
import { PdfDictionary } from 'pdf-lite/core/objects/pdf-dictionary'
import { PdfIndirectObject } from 'pdf-lite/core/objects/pdf-indirect-object'
import { PdfName } from 'pdf-lite/core/objects/pdf-name'
import { PdfNumber } from 'pdf-lite/core/objects/pdf-number'
import { PdfObjectReference } from 'pdf-lite/core/objects/pdf-object-reference'
import { PdfStream } from 'pdf-lite/core/objects/pdf-stream'
import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
import fs from 'fs/promises'

const tmpFolder = `${import.meta.dirname}/tmp`
await fs.mkdir(tmpFolder, { recursive: true })

// Helper functions for creating PDF objects
function createPage(
    contentStreamRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const pageDict = new PdfDictionary()
    pageDict.set('Type', new PdfName('Page'))
    pageDict.set(
        'MediaBox',
        new PdfArray([
            new PdfNumber(0),
            new PdfNumber(0),
            new PdfNumber(612),
            new PdfNumber(792),
        ]),
    )
    pageDict.set('Contents', contentStreamRef)
    return new PdfIndirectObject({ content: pageDict })
}

function createPages(
    pages: PdfIndirectObject<PdfDictionary>[],
): PdfIndirectObject<PdfDictionary> {
    const pagesDict = new PdfDictionary()
    pagesDict.set('Type', new PdfName('Pages'))
    pagesDict.set('Kids', new PdfArray(pages.map((x) => x.reference)))
    pagesDict.set('Count', new PdfNumber(pages.length))
    return new PdfIndirectObject({ content: pagesDict })
}

function createCatalog(
    pagesRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const catalogDict = new PdfDictionary()
    catalogDict.set('Type', new PdfName('Catalog'))
    catalogDict.set('Pages', pagesRef)
    return new PdfIndirectObject({ content: catalogDict })
}

function createFont(): PdfIndirectObject<PdfDictionary> {
    const fontDict = new PdfDictionary()
    fontDict.set('Type', new PdfName('Font'))
    fontDict.set('Subtype', new PdfName('Type1'))
    fontDict.set('BaseFont', new PdfName('Helvetica'))
    return new PdfIndirectObject({ content: fontDict })
}

function createResources(
    fontRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const resourcesDict = new PdfDictionary()
    const fontDict = new PdfDictionary()
    fontDict.set('F1', fontRef)
    resourcesDict.set('Font', fontDict)
    return new PdfIndirectObject({ content: resourcesDict })
}

// Step 1: Create an initial PDF document
console.log('Step 1: Creating initial PDF document...')
const document = new PdfDocument()

const font = createFont()
document.add(font)
const resources = createResources(font.reference)
document.add(resources)

const contentStream = new PdfIndirectObject({
    content: new PdfStream({
        header: new PdfDictionary(),
        original:
            'BT /F1 24 Tf 100 700 Td (Original Document - Revision 1) Tj ET',
    }),
})

const page = createPage(contentStream.reference)
page.content.set('Resources', resources.reference)
document.add(page)

const pages = createPages([page])
page.content.set('Parent', pages.reference)
document.add(pages)

const catalog = createCatalog(pages.reference)
document.add(catalog)

document.trailerDict.set('Root', catalog.reference)
document.add(contentStream)

await document.commit()
// Save the original PDF
const originalPdfPath = `${tmpFolder}/original.pdf`
await fs.writeFile(originalPdfPath, document.toBytes())
console.log(`Original PDF saved to: ${originalPdfPath}`)
console.log(`Original PDF has ${document.revisions.length} revision(s)`)

// Step 2: Load the PDF and perform an incremental update
console.log('\nStep 2: Loading PDF and performing incremental update...')

// Read the existing PDF
const existingPdfBytes = await fs.readFile(originalPdfPath)
const loadedDocument = await PdfDocument.fromBytes([existingPdfBytes])

// Lock existing revisions to enable incremental mode
// This ensures changes are added as new revisions instead of modifying existing ones
loadedDocument.setIncremental(true)

// Create new content for the incremental update
// In a real scenario, this could be adding annotations, form fields, signatures, etc.
const newContentStream = new PdfIndirectObject({
    objectNumber: contentStream.objectNumber,
    generationNumber: contentStream.generationNumber,
    content: new PdfStream({
        header: new PdfDictionary(),
        original:
            'BT /F1 18 Tf 100 650 Td (This content was added in Revision 2) Tj ET',
    }),
})

// Add the new content to the document
loadedDocument.add(newContentStream)
await loadedDocument.commit()

// Save the incrementally updated PDF
const updatedPdfPath = `${tmpFolder}/incremental-update.pdf`
await fs.writeFile(updatedPdfPath, loadedDocument.toBytes())
console.log(`Incrementally updated PDF saved to: ${updatedPdfPath}`)
console.log(`Updated PDF has ${loadedDocument.revisions.length} revision(s)`)

// Step 3: Verify the incremental update preserved the original content
console.log('\nStep 3: Verifying incremental update...')

// Check file sizes to confirm incremental update (new file should be larger)
const originalStats = await fs.stat(originalPdfPath)
const updatedStats = await fs.stat(updatedPdfPath)

console.log(`Original PDF size: ${originalStats.size} bytes`)
console.log(`Updated PDF size: ${updatedStats.size} bytes`)
console.log(
    `Size difference: ${updatedStats.size - originalStats.size} bytes (new revision data)`,
)

// The updated PDF contains the original bytes plus the new revision
// This is the key feature of incremental updates - the original PDF is preserved
const updatedPdfBytes = await fs.readFile(updatedPdfPath)
const originalPdfBytesForComparison = await fs.readFile(originalPdfPath)

// Verify that the beginning of the updated PDF matches the original
const originalBytesMatch = updatedPdfBytes
    .slice(0, originalPdfBytesForComparison.length - 10) // Exclude the %%EOF marker area
    .toString()
    .includes(
        originalPdfBytesForComparison
            .subarray(0, -10)
            .toString()
            .substring(0, 100),
    )

console.log(`Original content preserved: ${originalBytesMatch ? 'Yes' : 'No'}`)

// Step 4: Add another incremental revision
console.log('\nStep 4: Adding another incremental revision...')

const secondUpdate = await PdfDocument.fromBytes([updatedPdfBytes])
secondUpdate.setIncremental(true)

const thirdRevisionContent = new PdfIndirectObject({
    objectNumber: contentStream.objectNumber,
    generationNumber: contentStream.generationNumber,
    content: new PdfStream(
        'BT /F1 14 Tf 100 600 Td (Third revision - demonstrates multiple incremental updates) Tj ET',
    ),
})

secondUpdate.add(thirdRevisionContent)
await secondUpdate.commit()

const multiRevisionPdfPath = `${tmpFolder}/multi-revision.pdf`
await fs.writeFile(multiRevisionPdfPath, secondUpdate.toBytes())
console.log(`Multi-revision PDF saved to: ${multiRevisionPdfPath}`)
console.log(
    `Multi-revision PDF has ${secondUpdate.revisions.length} revision(s)`,
)

const multiRevisionStats = await fs.stat(multiRevisionPdfPath)
console.log(`Multi-revision PDF size: ${multiRevisionStats.size} bytes`)

console.log('\n=== Summary ===')
console.log('Incremental updates allow you to:')
console.log('1. Preserve the original PDF content (important for signatures)')
console.log('2. Add new content without modifying existing revisions')
console.log('3. Maintain a complete history of document changes')
console.log('4. Stack multiple revisions on top of each other')
Copy

Modifying AcroForms example - Creating and filling PDF form fields

import { PdfArray } from 'pdf-lite/core/objects/pdf-array'
import { PdfBoolean } from 'pdf-lite/core/objects/pdf-boolean'
import { PdfDictionary } from 'pdf-lite/core/objects/pdf-dictionary'
import { PdfIndirectObject } from 'pdf-lite/core/objects/pdf-indirect-object'
import { PdfName } from 'pdf-lite/core/objects/pdf-name'
import { PdfNumber } from 'pdf-lite/core/objects/pdf-number'
import { PdfObjectReference } from 'pdf-lite/core/objects/pdf-object-reference'
import { PdfStream } from 'pdf-lite/core/objects/pdf-stream'
import { PdfString } from 'pdf-lite/core/objects/pdf-string'
import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
import fs from 'fs/promises'

const tmpFolder = `${import.meta.dirname}/tmp`
await fs.mkdir(tmpFolder, { recursive: true })

// Helper function to create a basic page
function createPage(
    contentStreamRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const pageDict = new PdfDictionary()
    pageDict.set('Type', new PdfName('Page'))
    pageDict.set(
        'MediaBox',
        new PdfArray([
            new PdfNumber(0),
            new PdfNumber(0),
            new PdfNumber(612),
            new PdfNumber(792),
        ]),
    )
    pageDict.set('Contents', contentStreamRef)
    return new PdfIndirectObject({ content: pageDict })
}

// Helper function to create pages collection
function createPages(
    pages: PdfIndirectObject<PdfDictionary>[],
): PdfIndirectObject<PdfDictionary> {
    const pagesDict = new PdfDictionary()
    pagesDict.set('Type', new PdfName('Pages'))
    pagesDict.set('Kids', new PdfArray(pages.map((x) => x.reference)))
    pagesDict.set('Count', new PdfNumber(pages.length))
    return new PdfIndirectObject({ content: pagesDict })
}

// Helper function to create catalog
function createCatalog(
    pagesRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const catalogDict = new PdfDictionary()
    catalogDict.set('Type', new PdfName('Catalog'))
    catalogDict.set('Pages', pagesRef)
    return new PdfIndirectObject({ content: catalogDict })
}

// Helper function to create font
function createFont(): PdfIndirectObject<PdfDictionary> {
    const fontDict = new PdfDictionary()
    fontDict.set('Type', new PdfName('Font'))
    fontDict.set('Subtype', new PdfName('Type1'))
    fontDict.set('BaseFont', new PdfName('Helvetica'))
    return new PdfIndirectObject({ content: fontDict })
}

// Helper function to create resources
function createResources(
    fontRef: PdfObjectReference,
): PdfIndirectObject<PdfDictionary> {
    const resourcesDict = new PdfDictionary()
    const fontDict = new PdfDictionary()
    fontDict.set('F1', fontRef)
    resourcesDict.set('Font', fontDict)
    return new PdfIndirectObject({ content: resourcesDict })
}

// Helper function to create a text field widget annotation
function createTextField(
    fieldName: string,
    pageRef: PdfObjectReference,
    rect: [number, number, number, number],
    defaultValue: string = '',
): PdfIndirectObject<PdfDictionary> {
    const fieldDict = new PdfDictionary()
    // Annotation properties
    fieldDict.set('Type', new PdfName('Annot'))
    fieldDict.set('Subtype', new PdfName('Widget'))
    // Field type: Text
    fieldDict.set('FT', new PdfName('Tx'))
    // Field name
    fieldDict.set('T', new PdfString(fieldName))
    // Bounding rectangle [x1, y1, x2, y2]
    fieldDict.set(
        'Rect',
        new PdfArray([
            new PdfNumber(rect[0]),
            new PdfNumber(rect[1]),
            new PdfNumber(rect[2]),
            new PdfNumber(rect[3]),
        ]),
    )
    // Annotation flags (4 = print)
    fieldDict.set('F', new PdfNumber(4))
    // Parent page reference
    fieldDict.set('P', pageRef)
    // Default value (if any)
    if (defaultValue) {
        fieldDict.set('V', new PdfString(defaultValue))
        fieldDict.set('DV', new PdfString(defaultValue))
    }
    // Default appearance string (font and size)
    fieldDict.set('DA', new PdfString('/Helv 12 Tf 0 g'))

    return new PdfIndirectObject({ content: fieldDict })
}

// Helper function to create a checkbox field widget annotation
function createCheckboxField(
    fieldName: string,
    pageRef: PdfObjectReference,
    rect: [number, number, number, number],
    checked: boolean = false,
): PdfIndirectObject<PdfDictionary> {
    const fieldDict = new PdfDictionary()
    // Annotation properties
    fieldDict.set('Type', new PdfName('Annot'))
    fieldDict.set('Subtype', new PdfName('Widget'))
    // Field type: Button
    fieldDict.set('FT', new PdfName('Btn'))
    // Field name
    fieldDict.set('T', new PdfString(fieldName))
    // Bounding rectangle
    fieldDict.set(
        'Rect',
        new PdfArray([
            new PdfNumber(rect[0]),
            new PdfNumber(rect[1]),
            new PdfNumber(rect[2]),
            new PdfNumber(rect[3]),
        ]),
    )
    // Annotation flags (4 = print)
    fieldDict.set('F', new PdfNumber(4))
    // Parent page reference
    fieldDict.set('P', pageRef)
    // Value: /Yes for checked, /Off for unchecked
    fieldDict.set('V', new PdfName(checked ? 'Yes' : 'Off'))
    fieldDict.set('AS', new PdfName(checked ? 'Yes' : 'Off'))

    return new PdfIndirectObject({ content: fieldDict })
}

// ============================================
// PART 1: Create a PDF with form fields
// ============================================

const document = new PdfDocument()

// Create font
const font = createFont()
document.add(font)

// Create resources with the font
const resources = createResources(font.reference)
document.add(resources)

// Create content stream with form labels
const contentStream = new PdfIndirectObject({
    content: new PdfStream({
        header: new PdfDictionary(),
        original: `BT
/F1 18 Tf 72 720 Td (PDF Form Example) Tj
/F1 12 Tf 0 -40 Td (Name:) Tj
0 -30 Td (Email:) Tj
0 -30 Td (Phone:) Tj
0 -30 Td (Subscribe to newsletter:) Tj
ET`,
    }),
})
document.add(contentStream)

// Create page
const page = createPage(contentStream.reference)
page.content.set('Resources', resources.reference)
document.add(page)

// Create form fields
const nameField = createTextField('name', page.reference, [150, 665, 400, 685])
const emailField = createTextField(
    'email',
    page.reference,
    [150, 635, 400, 655],
)
const phoneField = createTextField(
    'phone',
    page.reference,
    [150, 605, 400, 625],
)
const subscribeField = createCheckboxField(
    'subscribe',
    page.reference,
    [200, 575, 215, 590],
)

document.add(nameField)
document.add(emailField)
document.add(phoneField)
document.add(subscribeField)

// Add annotations to page
page.content.set(
    'Annots',
    new PdfArray([
        nameField.reference,
        emailField.reference,
        phoneField.reference,
        subscribeField.reference,
    ]),
)

// Create pages collection
const pages = createPages([page])
page.content.set('Parent', pages.reference)
document.add(pages)

// Create catalog
const catalog = createCatalog(pages.reference)

// Create AcroForm with all fields
const acroForm = new PdfDictionary()
acroForm.set(
    'Fields',
    new PdfArray([
        nameField.reference,
        emailField.reference,
        phoneField.reference,
        subscribeField.reference,
    ]),
)
// NeedAppearances flag tells PDF readers to generate appearance streams
acroForm.set('NeedAppearances', new PdfBoolean(true))

// Default resources for the form (font)
const formResources = new PdfDictionary()
const formFontDict = new PdfDictionary()
const helveticaFont = new PdfDictionary()
helveticaFont.set('Type', new PdfName('Font'))
helveticaFont.set('Subtype', new PdfName('Type1'))
helveticaFont.set('BaseFont', new PdfName('Helvetica'))
formFontDict.set('Helv', helveticaFont)
formResources.set('Font', formFontDict)
acroForm.set('DR', formResources)

const acroFormObj = new PdfIndirectObject({ content: acroForm })
document.add(acroFormObj)
catalog.content.set('AcroForm', acroFormObj.reference)

document.add(catalog)

// Set the catalog as the root
document.trailerDict.set('Root', catalog.reference)

await document.commit()

// Save the empty form
// This demonstrates creating a blank form that users can fill in
await fs.writeFile(`${tmpFolder}/form-empty.pdf`, document.toBytes())
console.log('Created form-empty.pdf with empty form fields')

// ============================================
// PART 2: Fill in the form fields
// ============================================
// This demonstrates how to programmatically fill in form fields.
// We now read the previously saved empty form and modify it.

// Read the empty form PDF
const emptyFormBytes = await fs.readFile(`${tmpFolder}/form-empty.pdf`)
const filledDocument = await PdfDocument.fromBytes([emptyFormBytes])

// Get the catalog reference from trailer
const catalogRef = filledDocument.trailerDict.get('Root')
if (!catalogRef || !(catalogRef instanceof PdfObjectReference)) {
    throw new Error('No catalog found in PDF')
}

// Read the catalog object
const catalogObj = await filledDocument.readObject({
    objectNumber: catalogRef.objectNumber,
})
if (!catalogObj || !(catalogObj.content instanceof PdfDictionary)) {
    throw new Error('Catalog object not found')
}

// Get the AcroForm reference
const acroFormRef = catalogObj.content.get('AcroForm')
if (!acroFormRef || !(acroFormRef instanceof PdfObjectReference)) {
    throw new Error('No AcroForm found in PDF')
}

// Read the AcroForm object
const filledAcroFormObj = await filledDocument.readObject({
    objectNumber: acroFormRef.objectNumber,
})
if (
    !filledAcroFormObj ||
    !(filledAcroFormObj.content instanceof PdfDictionary)
) {
    throw new Error('AcroForm object not found')
}

// Get the fields array
const fieldsArray = filledAcroFormObj.content.get('Fields')
if (!fieldsArray || !(fieldsArray instanceof PdfArray)) {
    throw new Error('No fields found in AcroForm')
}

// Helper function to find a field by name
async function findField(
    fieldName: string,
): Promise<PdfIndirectObject<PdfDictionary> | null> {
    for (const fieldRef of fieldsArray.items) {
        if (!(fieldRef instanceof PdfObjectReference)) continue
        const fieldObj = await filledDocument.readObject({
            objectNumber: fieldRef.objectNumber,
        })
        if (!fieldObj || !(fieldObj.content instanceof PdfDictionary)) continue

        const name = fieldObj.content.get('T')
        if (name instanceof PdfString) {
            // Convert bytes to string for comparison
            const nameStr = name.value
            if (nameStr === fieldName) {
                return fieldObj as PdfIndirectObject<PdfDictionary>
            }
        }
    }
    return null
}

// Update the name field value
const nameFieldObj = await findField('name')
if (nameFieldObj) {
    nameFieldObj.content.set('V', new PdfString('John Doe'))
}

// Update the email field value
const emailFieldObj = await findField('email')
if (emailFieldObj) {
    emailFieldObj.content.set('V', new PdfString('john.doe@example.com'))
}

// Update the phone field value
const phoneFieldObj = await findField('phone')
if (phoneFieldObj) {
    phoneFieldObj.content.set('V', new PdfString('+1 (555) 123-4567'))
}

// Check the subscribe checkbox
const subscribeFieldObj = await findField('subscribe')
if (subscribeFieldObj) {
    subscribeFieldObj.content.set('V', new PdfName('Yes'))
    subscribeFieldObj.content.set('AS', new PdfName('Yes'))
}

// Save the filled form
await fs.writeFile(`${tmpFolder}/form-filled.pdf`, filledDocument.toBytes())
console.log('Created form-filled.pdf with filled form fields')

console.log('\nForm field values:')
console.log('- Name: John Doe')
console.log('- Email: john.doe@example.com')
console.log('- Phone: +1 (555) 123-4567')
console.log('- Subscribe: Yes')
Copy

Tokeniser usage example

import { PdfByteStreamTokeniser } from 'pdf-lite/core/tokeniser'
import { PdfToken } from 'pdf-lite/core/tokens/token'
import { stringToBytes } from 'pdf-lite/utils/stringToBytes'

/**
 * This example demonstrates how to use the PdfByteStreamTokeniser
 * to tokenize PDF content into individual tokens.
 *
 * The tokeniser converts raw PDF bytes into a stream of tokens that can
 * be further processed by the decoder or used for PDF analysis.
 */

// Sample PDF content to tokenize
const pdfContent = `%PDF-2.0
1 0 obj
<< /Type /Catalog /Pages 2 0 R >>
endobj
2 0 obj
<< /Type /Pages /Kids [3 0 R] /Count 1 >>
endobj
3 0 obj
<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >>
endobj
trailer
<< /Size 4 /Root 1 0 R >>
startxref
0
%%EOF`

// Create the tokeniser
const tokeniser = new PdfByteStreamTokeniser()

// Convert the PDF content to bytes and feed it to the tokeniser
const bytes = stringToBytes(pdfContent)
tokeniser.feedBytes(bytes)

// Signal end of input
tokeniser.eof = true

// Collect all tokens
const tokens: PdfToken[] = []
for (const token of tokeniser.nextItems()) {
    tokens.push(token)
}

// Display tokenisation results
console.log('PDF Tokenisation Example')
console.log('========================\n')
console.log(`Input: ${pdfContent.length} bytes`)
console.log(`Output: ${tokens.length} tokens\n`)

// Group tokens by type for summary
const tokenCounts = new Map<string, number>()
for (const token of tokens) {
    const type = token.constructor.name
    tokenCounts.set(type, (tokenCounts.get(type) ?? 0) + 1)
}

console.log('Token type counts:')
for (const [type, count] of tokenCounts) {
    console.log(`  ${type}: ${count}`)
}

console.log('\nFirst 20 tokens:')
for (const token of tokens.slice(0, 20)) {
    const tokenString = token.toString().slice(0, 40)
    const displayString =
        tokenString.length >= 40 ? tokenString + '...' : tokenString
    console.log(
        `  ${token.constructor.name.padEnd(30)} ${JSON.stringify(displayString)}`,
    )
}

// Example: Tokenising incrementally (useful for streaming)
console.log('\n\nIncremental Tokenisation Example')
console.log('=================================\n')

const incrementalTokeniser = new PdfByteStreamTokeniser()

// Feed bytes in chunks (simulating streaming)
const chunkSize = 50
const numChunks = Math.ceil(bytes.length / chunkSize)

console.log(`Processing ${numChunks} chunks of ~${chunkSize} bytes each...`)

let totalTokens = 0
for (let i = 0; i < bytes.length; i += chunkSize) {
    const chunk = bytes.slice(i, i + chunkSize)
    incrementalTokeniser.feedBytes(chunk)

    // Process tokens as they become available
    for (const _ of incrementalTokeniser.nextItems()) {
        totalTokens++
    }
}

// Signal end of input and collect remaining tokens
incrementalTokeniser.eof = true
for (const _ of incrementalTokeniser.nextItems()) {
    totalTokens++
}

console.log(`Total tokens produced: ${totalTokens}`)

// Example: Custom stream chunk size
console.log('\n\nCustom Stream Chunk Size Example')
console.log('================================\n')

const customTokeniser = new PdfByteStreamTokeniser({
    streamChunkSizeBytes: 512, // Customize the chunk size for stream content
})

const streamContent = `1 0 obj
<< /Length 100 >>
stream
This is stream content that will be chunked by the tokeniser.
The chunk size determines how the stream data is delivered.
endstream
endobj`

customTokeniser.feedBytes(stringToBytes(streamContent))
customTokeniser.eof = true

console.log('Tokens from stream content:')
for (const token of customTokeniser.nextItems()) {
    const type = token.constructor.name
    const preview = token.toString().slice(0, 50).replace(/\n/g, '\\n')
    console.log(`  ${type.padEnd(25)} ${JSON.stringify(preview)}`)
}
Copy