💥 Replace pdf-lib with pdf-core, bump to 0.6.0

This change replaces `pdf-lib` and `fontkit` with `@ralfstx/pdf-core` as
the underlying PDF generation library. This results in faster PDF
generation, smaller bundle size, and opens up new possibilities such as
font shaping.

Loading font and image data from base64-encoded strings was a feature of
`pdf-lib`. Reading encoded data should better be done outside of the
library, so we drop this feature and require `Uint8Array`.

With `pdf-core`, we can directly use the OS/2 typographic metrics for
font metrics instead of relying on the hhea table values. This is the
correct approach but it results in tighter line spacing for fonts whose
hhea values include extra spacing that was effectively double-counted
with the `lineHeight` multiplier.

Links and anchors are supported by `pdf-core`, so the custom rendering
code is removed. Parsing JPEG and PNG data is also handled by
`pdf-core`, so the related code is removed. Rendering functions are
simplified to use the `ContentStream` API directly.

The version is bumped to 0.6.0 to account for the breaking changes in
the API.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ralfstx

CHANGELOG.md

@@ -1,6 +1,24 @@
 # Changelog
 
-## [0.5.7] - Unreleased
+## [0.6.0] - Unreleased
+
+### Changed
+
+- Replaced `pdf-lib` with `@ralfstx/pdf-core` as the underlying PDF
+  generation library. This results in faster PDF generation and a
+  smaller bundle size. It also opens up new possibilities for new
+  features such as font shaping.
+
+### Breaking
+
+- Font and image data must now be provided as `Uint8Array`.
+  Base64-encoded strings and `ArrayBuffer`s are no longer accepted.
+
+- Text height is now based on the OS/2 typographic metrics
+  (`sTypoAscender` / `sTypoDescender`) instead of the hhea table values.
+  This results in tighter line spacing for fonts whose hhea values
+  include extra spacing that was effectively double-counted with the
+  `lineHeight` multiplier.
 
 ## [0.5.6] - 2025-01-19
 

README.md

@@ -668,10 +668,9 @@ const document = {
 
 ## Thanks
 
-This project is inspired by [pdfmake] and builds on [pdf-lib] and
-[fontkit]. It would not exist without the great work and the profound
-knowledge contributed by the authors of those projects.
+This project is inspired by [pdfmake] and [pdf-lib]. It would not exist
+without the great work and the profound knowledge contributed by the
+authors of those projects.
 
 [pdfmake]: https://github.com/bpampuch/pdfmake
 [pdf-lib]: https://github.com/Hopding/pdf-lib
-[fontkit]: https://github.com/Hopding/fontkit

eslint.config.js

@@ -66,11 +66,9 @@ export default tseslint.config(
       '@typescript-eslint/parameter-properties': 'error',
       '@typescript-eslint/consistent-type-imports': ['error', { prefer: 'type-imports' }],
 
-      // TODO: revisit when we got rid of pdf-lib internals
+      // TODO: remove when we got rid of any in the code base
       '@typescript-eslint/no-unsafe-assignment': ['off'],
-      '@typescript-eslint/no-unsafe-call': ['off'],
       '@typescript-eslint/no-unsafe-member-access': ['off'],
-      '@typescript-eslint/no-unsafe-return': ['off'],
 
       'simple-import-sort/imports': 'error',
       'import/extensions': ['error', 'ignorePackages', { js: 'never', ts: 'always' }],

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pdfmkr",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "description": "Generate PDF documents from JavaScript objects",
   "license": "MIT",
   "repository": {
@@ -25,16 +25,15 @@
     "npm": ">=10"
   },
   "scripts": {
-    "build": "rm -rf build/ dist/ && tsc && esbuild src/index.ts --bundle --sourcemap --platform=browser --target=es2022 --outdir=dist --format=esm --external:pdf-lib --external:@pdf-lib/fontkit && cp -a build/index.d.ts build/api/ dist/",
+    "build": "rm -rf build/ dist/ && tsc && esbuild src/index.ts --bundle --sourcemap --platform=browser --target=es2022 --outdir=dist --format=esm --external:@ralfstx/pdf-core && cp -a build/index.d.ts build/api/ dist/",
     "lint": "eslint . --max-warnings=0 && prettier --check .",
     "test": "vitest run test",
     "format": "prettier -w .",
     "fix": "eslint . --fix && prettier -w .",
     "examples": "./examples/run-all-examples.sh"
   },
   "dependencies": {
-    "@pdf-lib/fontkit": "^1.1.1",
-    "pdf-lib": "^1.17.1"
+    "@ralfstx/pdf-core": "^0.1.0"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",

package.json

@@ -1,9 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it } from 'vitest';
 
-import { image, text } from './layout.ts';
 import { PdfMaker } from './PdfMaker.ts';
 
 describe('makePdf', () => {
@@ -31,25 +30,4 @@ describe('makePdf', () => {
     const string = Buffer.from(pdf.buffer).toString();
     expect(string).toMatch(/[^\n]\n$/);
   });
-
-  it('includes a trailer ID in the document', async () => {
-    const pdf = await pdfMaker.makePdf({ content: [{}] });
-
-    const string = Buffer.from(pdf.buffer).toString();
-    expect(string).toMatch(/\/ID \[ <[0-9A-F]{64}> <[0-9A-F]{64}> \]/);
-  });
-
-  it('creates consistent results across runs', async () => {
-    // ensure same timestamps in generated PDF
-    vi.useFakeTimers();
-    // include fonts and images to ensure they can be reused
-    const content = [text('Test'), image('file:/torus.png')];
-
-    const pdf1 = await pdfMaker.makePdf({ content });
-    const pdf2 = await pdfMaker.makePdf({ content });
-
-    const pdfStr1 = Buffer.from(pdf1.buffer).toString();
-    const pdfStr2 = Buffer.from(pdf2.buffer).toString();
-    expect(pdfStr1).toEqual(pdfStr2);
-  });
 });

src/api/PdfMaker.test.ts

@@ -238,14 +238,12 @@ export type FontsDefinition = { [name: string]: FontDefinition[] };
  */
 export type FontDefinition = {
   /**
-   * The font data, as a Uint8Array, ArrayBuffer, or a base64-encoded
-   * string.
+   * The font data as a Uint8Array.
    *
-   * Supports TrueType (`.ttf`), OpenType (`.otf`), WOFF, WOFF2,
-   * TrueType Collection (`.ttc`), and Datafork TrueType (`.dfont`) font
-   * files (see https://github.com/Hopding/fontkit).
+   * Supports TrueType font files (`.ttf`) and OpenType (`.otf`) font
+   * files with TrueType outlines.
    */
-  data: string | Uint8Array | ArrayBuffer;
+  data: Uint8Array;
 
   /**
    * Whether this is a bold font.
@@ -272,12 +270,12 @@ export type ImagesDefinition = { [name: string]: ImageDefinition };
  */
 export type ImageDefinition = {
   /**
-   * The image data, as a Uint8Array, ArrayBuffer, or a base64-encoded string.
+   * The image data as a Uint8Array.
    * Supported image formats are PNG and JPEG.
    *
    *  @deprecated Use URLs to include images.
    */
-  data: string | Uint8Array | ArrayBuffer;
+  data: Uint8Array;
 };
 
 /**

src/api/document.ts

@@ -1,38 +1,28 @@
 import { describe, expect, it } from 'vitest';
 
-import { parseBinaryData } from './binary-data.ts';
+import { readBinaryData } from './binary-data.ts';
 
-const data = Uint8Array.of(1, 183, 0);
-
-describe('parseBinaryData', () => {
+describe('readBinaryData', () => {
   it('returns original Uint8Array', () => {
-    expect(parseBinaryData(data)).toBe(data);
-  });
+    const data = Uint8Array.of(1, 183, 0);
 
-  it('returns Uint8Array for ArrayBuffer', () => {
-    expect(parseBinaryData(data.buffer)).toEqual(data);
+    expect(readBinaryData(data)).toBe(data);
   });
 
-  it('returns Uint8Array for base64-encoded string', () => {
-    expect(parseBinaryData('Abc=`')).toEqual(data);
-  });
+  it('throws for ArrayBuffer', () => {
+    const buffer = Uint8Array.of(1, 183, 0).buffer;
 
-  it('returns Uint8Array for data URL', () => {
-    expect(parseBinaryData('data:image/jpeg;base64,Abc=`')).toEqual(data);
+    expect(() => readBinaryData(buffer)).toThrow(
+      new TypeError('Expected Uint8Array, got: ArrayBuffer [1, 183, 0]'),
+    );
   });
 
-  it('throws for arrays', () => {
-    expect(() => parseBinaryData([1, 2, 3])).toThrow(
-      new TypeError('Expected Uint8Array, ArrayBuffer, or base64-encoded string, got: [1, 2, 3]'),
-    );
+  it('throws for strings', () => {
+    expect(() => readBinaryData('AbcA')).toThrow(new TypeError("Expected Uint8Array, got: 'AbcA'"));
   });
 
   it('throws for other types', () => {
-    expect(() => parseBinaryData(23)).toThrow(
-      new TypeError('Expected Uint8Array, ArrayBuffer, or base64-encoded string, got: 23'),
-    );
-    expect(() => parseBinaryData(null)).toThrow(
-      new TypeError('Expected Uint8Array, ArrayBuffer, or base64-encoded string, got: null'),
-    );
+    expect(() => readBinaryData(23)).toThrow(new TypeError('Expected Uint8Array, got: 23'));
+    expect(() => readBinaryData(null)).toThrow(new TypeError('Expected Uint8Array, got: null'));
   });
 });

src/binary-data.test.ts

@@ -1,10 +1,6 @@
-import { decodeFromBase64DataUri } from 'pdf-lib';
-
 import { typeError } from './types.ts';
 
-export function parseBinaryData(input: unknown): Uint8Array {
+export function readBinaryData(input: unknown): Uint8Array {
   if (input instanceof Uint8Array) return input;
-  if (input instanceof ArrayBuffer) return new Uint8Array(input);
-  if (typeof input === 'string') return decodeFromBase64DataUri(input);
-  throw typeError('Uint8Array, ArrayBuffer, or base64-encoded string', input);
+  throw typeError('Uint8Array', input);
 }

src/binary-data.ts

@@ -0,0 +1,33 @@
+import type { ContentStream } from '@ralfstx/pdf-core';
+
+export type Color = {
+  type: 'RGB';
+  red: number;
+  green: number;
+  blue: number;
+};
+
+export const rgb = (red: number, green: number, blue: number): Color => {
+  assertRange(red, 'red', 0, 1);
+  assertRange(green, 'green', 0, 1);
+  assertRange(blue, 'blue', 0, 1);
+  return { type: 'RGB', red, green, blue };
+};
+
+export function setFillingColor(cs: ContentStream, color: Color): void {
+  if (color.type === 'RGB') {
+    cs.setFillRGB(color.red, color.green, color.blue);
+  } else throw new Error(`Invalid color: ${JSON.stringify(color)}`);
+}
+
+export function setStrokingColor(cs: ContentStream, color: Color): void {
+  if (color.type === 'RGB') {
+    cs.setStrokeRGB(color.red, color.green, color.blue);
+  } else throw new Error(`Invalid color: ${JSON.stringify(color)}`);
+}
+
+function assertRange(value: number, valueName: string, min: number, max: number) {
+  if (typeof value !== 'number' || value < min || value > max) {
+    throw new Error(`${valueName} must be a number between ${min} and ${max}, got: ${value}`);
+  }
+}