Allow custom font name on embed (Hopding#543)

* allow custom font name on embed

* linting

* customFontName -> customName, additional testing around font embedding

* address additional comments

* remove console log

Author: ztoben

src/api/PDFDocument.ts

@@ -792,20 +792,20 @@ export default class PDFDocument {
     font: StandardFonts | string | Uint8Array | ArrayBuffer,
     options: EmbedFontOptions = {},
   ): Promise<PDFFont> {
-    const { subset = false } = options;
+    const { subset = false, customName } = options;
 
     assertIs(font, 'font', ['string', Uint8Array, ArrayBuffer]);
     assertIs(subset, 'subset', ['boolean']);
 
     let embedder: CustomFontEmbedder | StandardFontEmbedder;
     if (isStandardFont(font)) {
-      embedder = StandardFontEmbedder.for(font);
+      embedder = StandardFontEmbedder.for(font, customName);
     } else if (canBeConvertedToUint8Array(font)) {
       const bytes = toUint8Array(font);
       const fontkit = this.assertFontkit();
       embedder = subset
-        ? await CustomFontSubsetEmbedder.for(fontkit, bytes)
-        : await CustomFontEmbedder.for(fontkit, bytes);
+        ? await CustomFontSubsetEmbedder.for(fontkit, bytes, customName)
+        : await CustomFontEmbedder.for(fontkit, bytes, customName);
     } else {
       throw new TypeError(
         '`font` must be one of `StandardFonts | string | Uint8Array | ArrayBuffer`',
@@ -827,15 +827,16 @@ export default class PDFDocument {
    * const helveticaFont = pdfDoc.embedFont(StandardFonts.Helvetica)
    * ```
    * @param font The standard font to be embedded.
+   * @param customName The name to be used when embedding the font.
    * @returns The embedded font.
    */
-  embedStandardFont(font: StandardFonts): PDFFont {
+  embedStandardFont(font: StandardFonts, customName?: string): PDFFont {
     assertIs(font, 'font', ['string']);
     if (!isStandardFont(font)) {
-      throw new TypeError('`font` must be one of type `StandardFontsr`');
+      throw new TypeError('`font` must be one of type `StandardFonts`');
     }
 
-    const embedder = StandardFontEmbedder.for(font);
+    const embedder = StandardFontEmbedder.for(font, customName);
 
     const ref = this.context.nextRef();
     const pdfFont = PDFFont.of(ref, this, embedder);

src/api/PDFDocumentOptions.ts

@@ -33,4 +33,5 @@ export interface CreateOptions {
 
 export interface EmbedFontOptions {
   subset?: boolean;
+  customName?: string;
 }

src/core/embedders/CustomFontEmbedder.ts

@@ -20,24 +20,30 @@ import {
  *   https://github.com/devongovett/pdfkit/blob/e71edab0dd4657b5a767804ba86c94c58d01fbca/lib/image/jpeg.coffee
  */
 class CustomFontEmbedder {
-  static async for(fontkit: Fontkit, fontData: Uint8Array) {
+  static async for(
+    fontkit: Fontkit,
+    fontData: Uint8Array,
+    customName?: string,
+  ) {
     const font = await fontkit.create(fontData);
-    return new CustomFontEmbedder(font, fontData);
+    return new CustomFontEmbedder(font, fontData, customName);
   }
 
   readonly font: Font;
   readonly scale: number;
   readonly fontData: Uint8Array;
   readonly fontName: string;
+  readonly customName: string | undefined;
 
   protected baseFontName: string;
   protected glyphCache: Cache<Glyph[]>;
 
-  protected constructor(font: Font, fontData: Uint8Array) {
+  protected constructor(font: Font, fontData: Uint8Array, customName?: string) {
     this.font = font;
     this.scale = 1000 / this.font.unitsPerEm;
     this.fontData = fontData;
     this.fontName = this.font.postscriptName || 'Font';
+    this.customName = customName;
 
     this.baseFontName = '';
     this.glyphCache = Cache.populatedBy(this.allGlyphsInFontSortedById);
@@ -83,7 +89,7 @@ class CustomFontEmbedder {
   }
 
   embedIntoContext(context: PDFContext, ref?: PDFRef): Promise<PDFRef> {
-    this.baseFontName = addRandomSuffix(this.fontName);
+    this.baseFontName = this.customName || addRandomSuffix(this.fontName);
     return this.embedFontDict(context, ref);
   }
 

src/core/embedders/CustomFontSubsetEmbedder.ts

@@ -10,17 +10,25 @@ import { Cache, mergeUint8Arrays, toHexStringOfMinLength } from 'src/utils';
  *   https://github.com/devongovett/pdfkit/blob/e71edab0dd4657b5a767804ba86c94c58d01fbca/lib/image/jpeg.coffee
  */
 class CustomFontSubsetEmbedder extends CustomFontEmbedder {
-  static async for(fontkit: Fontkit, fontData: Uint8Array) {
+  static async for(
+    fontkit: Fontkit,
+    fontData: Uint8Array,
+    customFontName?: string,
+  ) {
     const font = await fontkit.create(fontData);
-    return new CustomFontSubsetEmbedder(font, fontData);
+    return new CustomFontSubsetEmbedder(font, fontData, customFontName);
   }
 
   private readonly subset: Subset;
   private readonly glyphs: Glyph[];
   private readonly glyphIdMap: Map<number, number>;
 
-  private constructor(font: Font, fontData: Uint8Array) {
-    super(font, fontData);
+  private constructor(
+    font: Font,
+    fontData: Uint8Array,
+    customFontName?: string,
+  ) {
+    super(font, fontData, customFontName);
 
     this.subset = this.font.createSubset();
     this.glyphs = [];

src/core/embedders/StandardFontEmbedder.ts

@@ -21,13 +21,15 @@ export interface Glyph {
  *   https://github.com/foliojs/pdfkit/blob/f91bdd61c164a72ea06be1a43dc0a412afc3925f/lib/font/afm.coffee
  */
 class StandardFontEmbedder {
-  static for = (fontName: FontNames) => new StandardFontEmbedder(fontName);
+  static for = (fontName: FontNames, customName?: string) =>
+    new StandardFontEmbedder(fontName, customName);
 
   readonly font: Font;
   readonly encoding: Encoding;
   readonly fontName: string;
+  readonly customName: string | undefined;
 
-  private constructor(fontName: FontNames) {
+  private constructor(fontName: FontNames, customName?: string) {
     // prettier-ignore
     this.encoding = (
         fontName === FontNames.ZapfDingbats ? Encodings.ZapfDingbats
@@ -36,6 +38,7 @@ class StandardFontEmbedder {
     );
     this.font = Font.load(fontName);
     this.fontName = this.font.FontName;
+    this.customName = customName;
   }
 
   /**
@@ -85,7 +88,7 @@ class StandardFontEmbedder {
     const fontDict = context.obj({
       Type: 'Font',
       Subtype: 'Type1',
-      BaseFont: this.font.FontName,
+      BaseFont: this.customName || this.fontName,
 
       Encoding:
         this.encoding === Encodings.WinAnsi ? 'WinAnsiEncoding' : undefined,

tests/api/PDFDocument.spec.ts

@@ -1,3 +1,4 @@
+import fontkit from '@pdf-lib/fontkit';
 import fs from 'fs';
 import {
   EncryptedPDFError,
@@ -123,6 +124,43 @@ describe(`PDFDocument`, () => {
     });
   });
 
+  describe(`embedFont() method`, () => {
+    it(`serializes the same value on every save when using a custom font name`, async () => {
+      const customFont = fs.readFileSync('assets/fonts/ubuntu/Ubuntu-B.ttf');
+      const customName = 'Custom-Font-Name';
+      const pdfDoc1 = await PDFDocument.create({ updateMetadata: false });
+      const pdfDoc2 = await PDFDocument.create({ updateMetadata: false });
+
+      pdfDoc1.registerFontkit(fontkit);
+      pdfDoc2.registerFontkit(fontkit);
+
+      await pdfDoc1.embedFont(customFont, { customName });
+      await pdfDoc2.embedFont(customFont, { customName });
+
+      const savedDoc1 = await pdfDoc1.save();
+      const savedDoc2 = await pdfDoc2.save();
+
+      expect(savedDoc1).toEqual(savedDoc2);
+    });
+
+    it(`does not serialize the same on save when not using a custom font name`, async () => {
+      const customFont = fs.readFileSync('assets/fonts/ubuntu/Ubuntu-B.ttf');
+      const pdfDoc1 = await PDFDocument.create();
+      const pdfDoc2 = await PDFDocument.create();
+
+      pdfDoc1.registerFontkit(fontkit);
+      pdfDoc2.registerFontkit(fontkit);
+
+      await pdfDoc1.embedFont(customFont);
+      await pdfDoc2.embedFont(customFont);
+
+      const savedDoc1 = await pdfDoc1.save();
+      const savedDoc2 = await pdfDoc2.save();
+
+      expect(savedDoc1).not.toEqual(savedDoc2);
+    });
+  });
+
   describe(`setLanguage() method`, () => {
     it(`sets the language of the document`, async () => {
       const pdfDoc = await PDFDocument.create();

tests/core/embedders/CustomFontEmbedder.spec.ts

@@ -25,6 +25,16 @@ describe(`CustomFontEmbedder`, () => {
     expect(embedder.fontName).toBe('Ubuntu');
   });
 
+  it(`can set a custom font name`, async () => {
+    const customName = 'abc123';
+    const embedder = await CustomFontEmbedder.for(
+      fontkit,
+      new Uint8Array(ubuntuFont),
+      customName,
+    );
+    expect(embedder.customName).toBe(customName);
+  });
+
   it(`can embed font dictionaries into PDFContexts without a predefined ref`, async () => {
     const context = PDFContext.create();
     const embedder = await CustomFontEmbedder.for(

tests/core/embedders/StandardFontEmbedder.spec.ts

@@ -18,6 +18,15 @@ describe(`StandardFontEmbedder`, () => {
     expect(embedder.fontName).toBe('Helvetica-Oblique');
   });
 
+  it(`can use a custom font name`, () => {
+    const customName = 'Roboto 2';
+    const embedder = StandardFontEmbedder.for(
+      FontNames.HelveticaOblique,
+      customName,
+    );
+    expect(embedder.customName).toBe(customName);
+  });
+
   it(`can embed standard font dictionaries into PDFContexts without a predefined ref`, () => {
     const context = PDFContext.create();
     const embedder = StandardFontEmbedder.for(FontNames.Courier);