APIが出しうる例外を pdf-lib 独自のエラークラスに統一 (#12)

* refactor: utils/errors を削除して throw new Error() に置き換え

* refactor: エラークラス用のベースクラス（PDFLibError等）を追加

* chore: add property `type: PDFLibErrorType` to `PDFLibError` class

* refactor: remove unused error classes

* refactor: validatorsモジュールの一部コードを別モジュールに分離

* chore: core系モジュールの生のエラーを独自エラークラスに置き換え

* chore: utils系モジュールの生のエラーを独自エラークラスに置き換え

* chore: api系モジュールの生のエラーを独自エラークラスに置き換え

* test: エラークラスの変更を反映

* chore: fontkitが出すエラーをcatchしてpdf-lib独自エラークラスに変換

* refactor: InvalidPngErrorクラスを汎用化

* chore: UPNGが出すエラーをcatchしてpdf-lib独自エラークラスに変換

* refactor: 役割が重複したエラークラスを統合

* fix: fontkitが出すエラーをより広範囲で捕捉

* docs: update changelog

* v1.17.1-mod.2025.8

* test: make makeStubTTFFont slightly more type-safe

---------

Co-authored-by: FAL <contact@fal-works.com>

Author: falworks-dy

MODIFICATIONS.md

@@ -1,6 +1,6 @@
 # Modifications
 
-## [Unreleased]
+## [1.17.1-mod.2025.8]
 
 ### Feature Removals
 
@@ -11,6 +11,12 @@
 - Remove Base64 output by removing the `PDFDocument#saveAsBase64` method;
   use `PDFDocument#save` which resolves a `Uint8Array` instead.
 
+### Error Handling
+
+- Introduced `PDFLibError` (exported from `src/core`) with a machine-readable `type: PDFLibErrorType` to classify errors.
+- Refactored API/core/utils errors so that all errors extend `PDFLibError` instead of throwing bare `Error`/`TypeError`.
+- Normalize external failure surfaces by catching `@denkiyagi/fontkit` and `@pdf-lib/upng` exceptions and rethrowing corresponding `PDFLibError` subclasses (e.g., `InvalidFontDataError`) instead of leaking third-party errors.
+
 ### Internal Changes
 
 - Update several devDependencies including `typescript` to their latest versions.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denkiyagi/pdf-lib",
-  "version": "1.17.1-mod.2025.7",
+  "version": "1.17.1-mod.2025.8",
   "description": "A modified version of pdf-lib. Create and modify PDF files with JavaScript",
   "author": "DenkiYagi Inc. (modified version author), Andrew Dillon <andrew.dillon.j@gmail.com> (orignal version author)",
   "contributors": [

src/api/PDFDocument.ts

@@ -3,6 +3,7 @@ import type { Embeddable } from 'src/api/Embeddable';
 import {
   EncryptedPDFError,
   ForeignPageError,
+  InvalidFontSubsetOptionError,
   RemovePageFromEmptyDocumentError,
 } from 'src/api/errors';
 import { PDFEmbeddedPage } from 'src/api/PDFEmbeddedPage';
@@ -11,7 +12,7 @@ import { PDFImage } from 'src/api/PDFImage';
 import { PDFPage } from 'src/api/PDFPage';
 import { PDFForm } from 'src/api/form/PDFForm';
 import { PageSizes } from 'src/api/sizes';
-import type { StandardFonts } from 'src/api/StandardFonts';
+import { StandardFonts } from 'src/api/StandardFonts';
 import {
   AbstractCustomFontEmbedder,
   CustomFontEmbedder,
@@ -37,6 +38,7 @@ import {
   StandardFontEmbedder,
   UnexpectedObjectTypeError,
 } from 'src/core';
+import { mapFontkitError } from 'src/core/embedders/fontkit-helpers';
 import {
   ParseSpeeds,
   AttachmentOptions,
@@ -50,6 +52,8 @@ import type { PDFObject } from 'src/core/objects/PDFObject';
 import type { PDFRef } from 'src/core/objects/PDFRef';
 import type { TransformationMatrix } from 'src/types/matrix';
 import {
+  InvalidOptionPassedError,
+  InvalidTypePassedError,
   assertIs,
   assertIsOneOfOrUndefined,
   assertOrUndefined,
@@ -60,6 +64,7 @@ import {
   pluckIndices,
   range,
   toUint8Array,
+  values,
 } from 'src/utils';
 import { FileEmbedder, AFRelationship } from 'src/core/embedders/FileEmbedder';
 import { PDFEmbeddedFile } from 'src/api/PDFEmbeddedFile';
@@ -876,12 +881,20 @@ export class PDFDocument {
       embedder = StandardFontEmbedder.for(font, customName);
     } else if (canBeConvertedToUint8Array(font)) {
       const bytes = toUint8Array(font);
-      embedder = subset
-        ? CustomFontSubsetEmbedder.for(bytes, customName, vertical, advanced)
-        : CustomFontEmbedder.for(bytes, customName, vertical, advanced);
+      try {
+        embedder = subset
+          ? CustomFontSubsetEmbedder.for(bytes, customName, vertical, advanced)
+          : CustomFontEmbedder.for(bytes, customName, vertical, advanced);
+      } catch (error) {
+        const mappedError = mapFontkitError(error);
+        if (mappedError) throw mappedError;
+        throw error;
+      }
     } else {
-      throw new TypeError(
-        '`font` must be one of `StandardFonts | Uint8Array | ArrayBuffer`',
+      throw new InvalidTypePassedError(
+        'font',
+        ['string', Uint8Array, ArrayBuffer],
+        font,
       );
     }
 
@@ -906,17 +919,22 @@ export class PDFDocument {
   embedTTFFont(font: TTFFont, options: EmbedFontOptions): PDFFont {
     const { subset, customName, vertical, advanced } = options;
     if (subset !== true) {
-      throw new TypeError(
-        '`subset` must explicitly be true when embedding a TTFFont',
-      );
+      throw new InvalidFontSubsetOptionError(subset);
     }
 
-    const embedder = CustomFontSubsetEmbedder.forTTFFont(
-      font,
-      customName,
-      vertical,
-      advanced,
-    );
+    let embedder: AbstractCustomFontEmbedder;
+    try {
+      embedder = CustomFontSubsetEmbedder.forTTFFont(
+        font,
+        customName,
+        vertical,
+        advanced,
+      );
+    } catch (error) {
+      const mappedError = mapFontkitError(error);
+      if (mappedError) throw mappedError;
+      throw error;
+    }
 
     const ref = this.context.nextRef();
     const pdfFont = PDFFont.of(ref, this, embedder);
@@ -939,7 +957,7 @@ export class PDFDocument {
   embedStandardFont(font: StandardFonts, customName?: string): PDFFont {
     assertIs(font, 'font', ['string']);
     if (!isStandardFont(font)) {
-      throw new TypeError('`font` must be one of type `StandardFonts`');
+      throw new InvalidOptionPassedError('font', values(StandardFonts), font);
     }
 
     const embedder = StandardFontEmbedder.for(font, customName);

src/api/PDFFont.ts

@@ -8,6 +8,7 @@ import {
   PDFRef,
   StandardFontEmbedder,
 } from 'src/core';
+import { mapFontkitError } from 'src/core/embedders/fontkit-helpers';
 import type { SingleLineTextOrGlyphs } from 'src/types/text';
 import { assertIs, assertOrUndefined } from 'src/utils';
 
@@ -76,7 +77,13 @@ export class PDFFont implements Embeddable {
   ): PDFHexString {
     assertIs(text, 'text', ['string', Array, Uint16Array, Uint32Array]);
     this.modified = true;
-    return this.embedder.encodeText(text, layoutAdvancedParams);
+    try {
+      return this.embedder.encodeText(text, layoutAdvancedParams);
+    } catch (error) {
+      const mappedError = mapFontkitError(error);
+      if (mappedError) throw mappedError;
+      throw error;
+    }
   }
 
   /**
@@ -93,7 +100,13 @@ export class PDFFont implements Embeddable {
   widthOfTextAtSize(text: string, size: number): number {
     assertIs(text, 'text', ['string']);
     assertIs(size, 'size', ['number']);
-    return this.embedder.widthOfTextAtSize(text, size);
+    try {
+      return this.embedder.widthOfTextAtSize(text, size);
+    } catch (error) {
+      const mappedError = mapFontkitError(error);
+      if (mappedError) throw mappedError;
+      throw error;
+    }
   }
 
   /**
@@ -173,7 +186,13 @@ export class PDFFont implements Embeddable {
   async embed(): Promise<void> {
     // TODO: Cleanup orphan embedded objects if a font is embedded multiple times...
     if (this.modified) {
-      await this.embedder.embedIntoContext(this.doc.context, this.ref);
+      try {
+        this.embedder.embedIntoContext(this.doc.context, this.ref);
+      } catch (error) {
+        const mappedError = mapFontkitError(error);
+        if (mappedError) throw mappedError;
+        throw error;
+      }
       this.modified = false;
     }
   }

src/api/colors.ts

@@ -6,7 +6,8 @@ import {
   setStrokingGrayscaleColor,
   setStrokingRgbColor,
 } from 'src/api/operators';
-import { assertRange, error } from 'src/utils';
+import { InvalidColorError } from 'src/api/errors';
+import { assertRange } from 'src/utils';
 
 export enum ColorTypes {
   Grayscale = 'Grayscale',
@@ -63,19 +64,41 @@ export const cmyk = (
 
 const { Grayscale, RGB, CMYK } = ColorTypes;
 
-// prettier-ignore
-export const setFillingColor = (color: Color) => 
-    color.type === Grayscale ? setFillingGrayscaleColor(color.gray)
-  : color.type === RGB       ? setFillingRgbColor(color.red, color.green, color.blue)
-  : color.type === CMYK      ? setFillingCmykColor(color.cyan, color.magenta, color.yellow, color.key)
-  : error(`Invalid color: ${JSON.stringify(color)}`);
+export const setFillingColor = (color: Color) => {
+  switch (color.type) {
+    case Grayscale:
+      return setFillingGrayscaleColor(color.gray);
+    case RGB:
+      return setFillingRgbColor(color.red, color.green, color.blue);
+    case CMYK:
+      return setFillingCmykColor(
+        color.cyan,
+        color.magenta,
+        color.yellow,
+        color.key,
+      );
+    default:
+      throw new InvalidColorError(color);
+  }
+};
 
-// prettier-ignore
-export const setStrokingColor = (color: Color) => 
-    color.type === Grayscale ? setStrokingGrayscaleColor(color.gray)
-  : color.type === RGB       ? setStrokingRgbColor(color.red, color.green, color.blue)
-  : color.type === CMYK      ? setStrokingCmykColor(color.cyan, color.magenta, color.yellow, color.key)
-  : error(`Invalid color: ${JSON.stringify(color)}`);
+export const setStrokingColor = (color: Color) => {
+  switch (color.type) {
+    case Grayscale:
+      return setStrokingGrayscaleColor(color.gray);
+    case RGB:
+      return setStrokingRgbColor(color.red, color.green, color.blue);
+    case CMYK:
+      return setStrokingCmykColor(
+        color.cyan,
+        color.magenta,
+        color.yellow,
+        color.key,
+      );
+    default:
+      throw new InvalidColorError(color);
+  }
+};
 
 // prettier-ignore
 export const componentsToColor = (comps?: number[], scale = 1) => (
@@ -96,9 +119,15 @@ export const componentsToColor = (comps?: number[], scale = 1) => (
   : undefined
 );
 
-// prettier-ignore
-export const colorToComponents = (color: Color) =>
-    color.type === Grayscale ? [color.gray]
-  : color.type === RGB       ? [color.red, color.green, color.blue]
-  : color.type === CMYK      ? [color.cyan, color.magenta, color.yellow, color.key]
-  : error(`Invalid color: ${JSON.stringify(color)}`);
+export const colorToComponents = (color: Color) => {
+  switch (color.type) {
+    case Grayscale:
+      return [color.gray];
+    case RGB:
+      return [color.red, color.green, color.blue];
+    case CMYK:
+      return [color.cyan, color.magenta, color.yellow, color.key];
+    default:
+      throw new InvalidColorError(color);
+  }
+};