@adnsistemas/pdf-lib 1.18.0

package/src/api/PDFDocumentOptions.ts

@@ -0,0 +1,50 @@
+import { EmbeddedFileOptions } from 'src/core/embedders/FileEmbedder';
+import { TypeFeatures } from 'src/types/fontkit';
+
+export enum ParseSpeeds {
+  Fastest = Infinity,
+  Fast = 1500,
+  Medium = 500,
+  Slow = 100,
+}
+
+export interface AttachmentOptions extends EmbeddedFileOptions {}
+
+export interface SaveOptions {
+  useObjectStreams?: boolean;
+  addDefaultPage?: boolean;
+  objectsPerTick?: number;
+  updateFieldAppearances?: boolean;
+  rewrite?: boolean;
+}
+
+export interface IncrementalSaveOptions {
+  objectsPerTick?: number;
+}
+
+export interface Base64SaveOptions extends SaveOptions {
+  dataUri?: boolean;
+}
+
+export interface LoadOptions {
+  ignoreEncryption?: boolean;
+  parseSpeed?: ParseSpeeds | number;
+  throwOnInvalidObject?: boolean;
+  updateMetadata?: boolean;
+  capNumbers?: boolean;
+  forIncrementalUpdate?: boolean;
+}
+
+export interface CreateOptions {
+  updateMetadata?: boolean;
+}
+
+export interface EmbedFontOptions {
+  subset?: boolean;
+  customName?: string;
+  features?: TypeFeatures;
+}
+
+export interface SetTitleOptions {
+  showInWindowTitleBar: boolean;
+}

package/src/api/PDFEmbeddedFile.ts

@@ -0,0 +1,90 @@
+import Embeddable from 'src/api/Embeddable';
+import PDFDocument from 'src/api/PDFDocument';
+import FileEmbedder from 'src/core/embedders/FileEmbedder';
+import { PDFName, PDFArray, PDFDict, PDFHexString, PDFRef } from 'src/core';
+
+/**
+ * Represents a file that has been embedded in a [[PDFDocument]].
+ */
+export default class PDFEmbeddedFile implements Embeddable {
+  /**
+   * > **NOTE:** You probably don't want to call this method directly. Instead,
+   * > consider using the [[PDFDocument.attach]] method, which will create
+   * instances of [[PDFEmbeddedFile]] for you.
+   *
+   * Create an instance of [[PDFEmbeddedFile]] from an existing ref and embedder
+   *
+   * @param ref The unique reference for this file.
+   * @param doc The document to which the file will belong.
+   * @param embedder The embedder that will be used to embed the file.
+   */
+  static of = (ref: PDFRef, doc: PDFDocument, embedder: FileEmbedder) =>
+    new PDFEmbeddedFile(ref, doc, embedder);
+
+  /** The unique reference assigned to this embedded file within the document. */
+  readonly ref: PDFRef;
+
+  /** The document to which this embedded file belongs. */
+  readonly doc: PDFDocument;
+
+  private alreadyEmbedded = false;
+  private readonly embedder: FileEmbedder;
+
+  private constructor(ref: PDFRef, doc: PDFDocument, embedder: FileEmbedder) {
+    this.ref = ref;
+    this.doc = doc;
+    this.embedder = embedder;
+  }
+
+  /**
+   * > **NOTE:** You probably don't need to call this method directly. The
+   * > [[PDFDocument.save]] and [[PDFDocument.saveAsBase64]] methods will
+   * > automatically ensure all embeddable files get embedded.
+   *
+   * Embed this embeddable file in its document.
+   *
+   * @returns Resolves when the embedding is complete.
+   */
+  async embed(): Promise<void> {
+    if (!this.alreadyEmbedded) {
+      const ref = await this.embedder.embedIntoContext(
+        this.doc.context,
+        this.ref,
+      );
+
+      if (!this.doc.catalog.has(PDFName.of('Names'))) {
+        this.doc.catalog.set(PDFName.of('Names'), this.doc.context.obj({}));
+      }
+      const Names = this.doc.catalog.lookup(PDFName.of('Names'), PDFDict);
+
+      if (!Names.has(PDFName.of('EmbeddedFiles'))) {
+        Names.set(PDFName.of('EmbeddedFiles'), this.doc.context.obj({}));
+      }
+      const EmbeddedFiles = Names.lookup(PDFName.of('EmbeddedFiles'), PDFDict);
+
+      if (!EmbeddedFiles.has(PDFName.of('Names'))) {
+        EmbeddedFiles.set(PDFName.of('Names'), this.doc.context.obj([]));
+      }
+      const EFNames = EmbeddedFiles.lookup(PDFName.of('Names'), PDFArray);
+
+      EFNames.push(PDFHexString.fromText(this.embedder.fileName));
+      EFNames.push(ref);
+
+      /**
+       * The AF-Tag is needed to achieve PDF-A3 compliance for embedded files
+       *
+       * The following document outlines the uses cases of the associated files (AF) tag.
+       * See:
+       * https://www.pdfa.org/wp-content/uploads/2018/10/PDF20_AN002-AF.pdf
+       */
+
+      if (!this.doc.catalog.has(PDFName.of('AF'))) {
+        this.doc.catalog.set(PDFName.of('AF'), this.doc.context.obj([]));
+      }
+      const AF = this.doc.catalog.lookup(PDFName.of('AF'), PDFArray);
+      AF.push(ref);
+
+      this.alreadyEmbedded = true;
+    }
+  }
+}

package/src/api/PDFEmbeddedPage.ts

@@ -0,0 +1,104 @@
+import Embeddable from 'src/api/Embeddable';
+import PDFDocument from 'src/api/PDFDocument';
+import { PDFPageEmbedder, PDFRef } from 'src/core';
+import { assertIs } from 'src/utils';
+
+/**
+ * Represents a PDF page that has been embedded in a [[PDFDocument]].
+ */
+export default class PDFEmbeddedPage implements Embeddable {
+  /**
+   * > **NOTE:** You probably don't want to call this method directly. Instead,
+   * > consider using the [[PDFDocument.embedPdf]] and
+   * > [[PDFDocument.embedPage]] methods, which will create instances of
+   * > [[PDFEmbeddedPage]] for you.
+   *
+   * Create an instance of [[PDFEmbeddedPage]] from an existing ref and embedder
+   *
+   * @param ref The unique reference for this embedded page.
+   * @param doc The document to which the embedded page will belong.
+   * @param embedder The embedder that will be used to embed the page.
+   */
+  static of = (ref: PDFRef, doc: PDFDocument, embedder: PDFPageEmbedder) =>
+    new PDFEmbeddedPage(ref, doc, embedder);
+
+  /** The unique reference assigned to this embedded page within the document. */
+  readonly ref: PDFRef;
+
+  /** The document to which this embedded page belongs. */
+  readonly doc: PDFDocument;
+
+  /** The width of this page in pixels. */
+  readonly width: number;
+
+  /** The height of this page in pixels. */
+  readonly height: number;
+
+  private alreadyEmbedded = false;
+  private readonly embedder: PDFPageEmbedder;
+
+  private constructor(
+    ref: PDFRef,
+    doc: PDFDocument,
+    embedder: PDFPageEmbedder,
+  ) {
+    assertIs(ref, 'ref', [[PDFRef, 'PDFRef']]);
+    assertIs(doc, 'doc', [[PDFDocument, 'PDFDocument']]);
+    assertIs(embedder, 'embedder', [[PDFPageEmbedder, 'PDFPageEmbedder']]);
+
+    this.ref = ref;
+    this.doc = doc;
+    this.width = embedder.width;
+    this.height = embedder.height;
+
+    this.embedder = embedder;
+  }
+
+  /**
+   * Compute the width and height of this page after being scaled by the
+   * given `factor`. For example:
+   * ```js
+   * embeddedPage.width  // => 500
+   * embeddedPage.height // => 250
+   *
+   * const scaled = embeddedPage.scale(0.5)
+   * scaled.width  // => 250
+   * scaled.height // => 125
+   * ```
+   * This operation is often useful before drawing a page with
+   * [[PDFPage.drawPage]] to compute the `width` and `height` options.
+   * @param factor The factor by which this page should be scaled.
+   * @returns The width and height of the page after being scaled.
+   */
+  scale(factor: number) {
+    assertIs(factor, 'factor', ['number']);
+    return { width: this.width * factor, height: this.height * factor };
+  }
+
+  /**
+   * Get the width and height of this page. For example:
+   * ```js
+   * const { width, height } = embeddedPage.size()
+   * ```
+   * @returns The width and height of the page.
+   */
+  size() {
+    return this.scale(1);
+  }
+
+  /**
+   * > **NOTE:** You probably don't need to call this method directly. The
+   * > [[PDFDocument.save]] and [[PDFDocument.saveAsBase64]] methods will
+   * > automatically ensure all embeddable pages get embedded.
+   *
+   * Embed this embeddable page in its document.
+   *
+   * @returns Resolves when the embedding is complete.
+   */
+  async embed(): Promise<void> {
+    if (!this.alreadyEmbedded) {
+      await this.embedder.embedIntoContext(this.doc.context, this.ref);
+      this.alreadyEmbedded = true;
+    }
+  }
+}

package/src/api/PDFFont.ts

@@ -0,0 +1,154 @@
+import Embeddable from 'src/api//Embeddable';
+import PDFDocument from 'src/api/PDFDocument';
+import {
+  CustomFontEmbedder,
+  PDFHexString,
+  PDFRef,
+  StandardFontEmbedder,
+} from 'src/core';
+import { assertIs, assertOrUndefined } from 'src/utils';
+
+export type FontEmbedder = CustomFontEmbedder | StandardFontEmbedder;
+
+/**
+ * Represents a font that has been embedded in a [[PDFDocument]].
+ */
+export default class PDFFont implements Embeddable {
+  /**
+   * > **NOTE:** You probably don't want to call this method directly. Instead,
+   * > consider using the [[PDFDocument.embedFont]] and
+   * > [[PDFDocument.embedStandardFont]] methods, which will create instances
+   * > of [[PDFFont]] for you.
+   *
+   * Create an instance of [[PDFFont]] from an existing ref and embedder
+   *
+   * @param ref The unique reference for this font.
+   * @param doc The document to which the font will belong.
+   * @param embedder The embedder that will be used to embed the font.
+   */
+  static of = (ref: PDFRef, doc: PDFDocument, embedder: FontEmbedder) =>
+    new PDFFont(ref, doc, embedder);
+
+  /** The unique reference assigned to this font within the document. */
+  readonly ref: PDFRef;
+
+  /** The document to which this font belongs. */
+  readonly doc: PDFDocument;
+
+  /** The name of this font. */
+  readonly name: string;
+
+  private modified = true;
+  private readonly embedder: FontEmbedder;
+
+  private constructor(ref: PDFRef, doc: PDFDocument, embedder: FontEmbedder) {
+    assertIs(ref, 'ref', [[PDFRef, 'PDFRef']]);
+    assertIs(doc, 'doc', [[PDFDocument, 'PDFDocument']]);
+    assertIs(embedder, 'embedder', [
+      [CustomFontEmbedder, 'CustomFontEmbedder'],
+      [StandardFontEmbedder, 'StandardFontEmbedder'],
+    ]);
+
+    this.ref = ref;
+    this.doc = doc;
+    this.name = embedder.fontName;
+
+    this.embedder = embedder;
+  }
+
+  /**
+   * > **NOTE:** You probably don't need to call this method directly. The
+   * > [[PDFPage.drawText]] method will automatically encode the text it is
+   * > given.
+   *
+   * Encodes a string of text in this font.
+   *
+   * @param text The text to be encoded.
+   * @returns The encoded text as a hex string.
+   */
+  encodeText(text: string): PDFHexString {
+    assertIs(text, 'text', ['string']);
+    this.modified = true;
+    return this.embedder.encodeText(text);
+  }
+
+  /**
+   * Measure the width of a string of text drawn in this font at a given size.
+   * For example:
+   * ```js
+   * const width = font.widthOfTextAtSize('Foo Bar Qux Baz', 36)
+   * ```
+   * @param text The string of text to be measured.
+   * @param size The font size to be used for this measurement.
+   * @returns The width of the string of text when drawn in this font at the
+   *          given size.
+   */
+  widthOfTextAtSize(text: string, size: number): number {
+    assertIs(text, 'text', ['string']);
+    assertIs(size, 'size', ['number']);
+    return this.embedder.widthOfTextAtSize(text, size);
+  }
+
+  /**
+   * Measure the height of this font at a given size. For example:
+   * ```js
+   * const height = font.heightAtSize(24)
+   * ```
+   *
+   * The `options.descender` value controls whether or not the font's
+   * descender is included in the height calculation.
+   *
+   * @param size The font size to be used for this measurement.
+   * @param options The options to be used when computing this measurement.
+   * @returns The height of this font at the given size.
+   */
+  heightAtSize(size: number, options?: { descender?: boolean }): number {
+    assertIs(size, 'size', ['number']);
+    assertOrUndefined(options?.descender, 'options.descender', ['boolean']);
+    return this.embedder.heightOfFontAtSize(size, {
+      descender: options?.descender ?? true,
+    });
+  }
+
+  /**
+   * Compute the font size at which this font is a given height. For example:
+   * ```js
+   * const fontSize = font.sizeAtHeight(12)
+   * ```
+   * @param height The height to be used for this calculation.
+   * @returns The font size at which this font is the given height.
+   */
+  sizeAtHeight(height: number): number {
+    assertIs(height, 'height', ['number']);
+    return this.embedder.sizeOfFontAtHeight(height);
+  }
+
+  /**
+   * Get the set of unicode code points that can be represented by this font.
+   * @returns The set of unicode code points supported by this font.
+   */
+  getCharacterSet(): number[] {
+    if (this.embedder instanceof StandardFontEmbedder) {
+      return this.embedder.encoding.supportedCodePoints;
+    } else {
+      return this.embedder.font.characterSet;
+    }
+  }
+
+  /**
+   * > **NOTE:** You probably don't need to call this method directly. The
+   * > [[PDFDocument.save]] and [[PDFDocument.saveAsBase64]] methods will
+   * > automatically ensure all fonts get embedded.
+   *
+   * Embed this font in its document.
+   *
+   * @returns Resolves when the embedding is complete.
+   */
+  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);
+      this.modified = false;
+    }
+  }
+}

package/src/api/PDFImage.ts

@@ -0,0 +1,143 @@
+import Embeddable from 'src/api/Embeddable';
+import PDFDocument from 'src/api/PDFDocument';
+import { JpegEmbedder, PDFRef, PngEmbedder } from 'src/core';
+import { assertIs } from 'src/utils';
+
+export type ImageEmbedder = JpegEmbedder | PngEmbedder;
+
+/**
+ * Represents an image that has been embedded in a [[PDFDocument]].
+ */
+export default class PDFImage implements Embeddable {
+  /**
+   * > **NOTE:** You probably don't want to call this method directly. Instead,
+   * > consider using the [[PDFDocument.embedPng]] and [[PDFDocument.embedJpg]]
+   * > methods, which will create instances of [[PDFImage]] for you.
+   *
+   * Create an instance of [[PDFImage]] from an existing ref and embedder
+   *
+   * @param ref The unique reference for this image.
+   * @param doc The document to which the image will belong.
+   * @param embedder The embedder that will be used to embed the image.
+   */
+  static of = (ref: PDFRef, doc: PDFDocument, embedder: ImageEmbedder) =>
+    new PDFImage(ref, doc, embedder);
+
+  /** The unique reference assigned to this image within the document. */
+  readonly ref: PDFRef;
+
+  /** The document to which this image belongs. */
+  readonly doc: PDFDocument;
+
+  /** The width of this image in pixels. */
+  readonly width: number;
+
+  /** The height of this image in pixels. */
+  readonly height: number;
+
+  private embedder: ImageEmbedder | undefined;
+  private embedTask: Promise<PDFRef> | undefined;
+
+  private constructor(ref: PDFRef, doc: PDFDocument, embedder: ImageEmbedder) {
+    assertIs(ref, 'ref', [[PDFRef, 'PDFRef']]);
+    assertIs(doc, 'doc', [[PDFDocument, 'PDFDocument']]);
+    assertIs(embedder, 'embedder', [
+      [JpegEmbedder, 'JpegEmbedder'],
+      [PngEmbedder, 'PngEmbedder'],
+    ]);
+
+    this.ref = ref;
+    this.doc = doc;
+    this.width = embedder.width;
+    this.height = embedder.height;
+
+    this.embedder = embedder;
+  }
+
+  /**
+   * Compute the width and height of this image after being scaled by the
+   * given `factor`. For example:
+   * ```js
+   * image.width  // => 500
+   * image.height // => 250
+   *
+   * const scaled = image.scale(0.5)
+   * scaled.width  // => 250
+   * scaled.height // => 125
+   * ```
+   * This operation is often useful before drawing an image with
+   * [[PDFPage.drawImage]] to compute the `width` and `height` options.
+   * @param factor The factor by which this image should be scaled.
+   * @returns The width and height of the image after being scaled.
+   */
+  scale(factor: number) {
+    assertIs(factor, 'factor', ['number']);
+    return { width: this.width * factor, height: this.height * factor };
+  }
+
+  /**
+   * Get the width and height of this image after scaling it as large as
+   * possible while maintaining its aspect ratio and not exceeding the
+   * specified `width` and `height`. For example:
+   * ```
+   * image.width  // => 500
+   * image.height // => 250
+   *
+   * const scaled = image.scaleToFit(750, 1000)
+   * scaled.width  // => 750
+   * scaled.height // => 375
+   * ```
+   * The `width` and `height` parameters can also be thought of as the width
+   * and height of a box that the scaled image must fit within.
+   * @param width The bounding box's width.
+   * @param height The bounding box's height.
+   * @returns The width and height of the image after being scaled.
+   */
+  scaleToFit(width: number, height: number) {
+    assertIs(width, 'width', ['number']);
+    assertIs(height, 'height', ['number']);
+
+    const imgWidthScale = width / this.width;
+    const imgHeightScale = height / this.height;
+    const scale = Math.min(imgWidthScale, imgHeightScale);
+
+    return this.scale(scale);
+  }
+
+  /**
+   * Get the width and height of this image. For example:
+   * ```js
+   * const { width, height } = image.size()
+   * ```
+   * @returns The width and height of the image.
+   */
+  size() {
+    return this.scale(1);
+  }
+
+  /**
+   * > **NOTE:** You probably don't need to call this method directly. The
+   * > [[PDFDocument.save]] and [[PDFDocument.saveAsBase64]] methods will
+   * > automatically ensure all images get embedded.
+   *
+   * Embed this image in its document.
+   *
+   * @returns Resolves when the embedding is complete.
+   */
+  async embed(): Promise<void> {
+    if (!this.embedder) return;
+
+    // The image should only be embedded once. If there's a pending embed
+    // operation then wait on it. Otherwise we need to start the embed.
+    if (!this.embedTask) {
+      const { doc, ref } = this;
+      this.embedTask = this.embedder.embedIntoContext(doc.context, ref);
+    }
+    await this.embedTask;
+
+    // We clear `this.embedder` so that the indirectly referenced image data
+    // can be garbage collected, thus avoiding a memory leak.
+    // See https://github.com/Hopding/pdf-lib/pull/1032/files.
+    this.embedder = undefined;
+  }
+}

package/src/api/PDFJavaScript.ts

@@ -0,0 +1,82 @@
+import Embeddable from 'src/api/Embeddable';
+import PDFDocument from 'src/api/PDFDocument';
+import JavaScriptEmbedder from 'src/core/embedders/JavaScriptEmbedder';
+import { PDFName, PDFArray, PDFDict, PDFHexString, PDFRef } from 'src/core';
+
+/**
+ * Represents JavaScript that has been embedded in a [[PDFDocument]].
+ */
+export default class PDFJavaScript implements Embeddable {
+  /**
+   * > **NOTE:** You probably don't want to call this method directly. Instead,
+   * > consider using the [[PDFDocument.addJavaScript]] method, which will
+   * create instances of [[PDFJavaScript]] for you.
+   *
+   * Create an instance of [[PDFJavaScript]] from an existing ref and script
+   *
+   * @param ref The unique reference for this script.
+   * @param doc The document to which the script will belong.
+   * @param embedder The embedder that will be used to embed the script.
+   */
+  static of = (ref: PDFRef, doc: PDFDocument, embedder: JavaScriptEmbedder) =>
+    new PDFJavaScript(ref, doc, embedder);
+
+  /** The unique reference assigned to this embedded script within the document. */
+  readonly ref: PDFRef;
+
+  /** The document to which this embedded script belongs. */
+  readonly doc: PDFDocument;
+
+  private alreadyEmbedded = false;
+  private readonly embedder: JavaScriptEmbedder;
+
+  private constructor(
+    ref: PDFRef,
+    doc: PDFDocument,
+    embedder: JavaScriptEmbedder,
+  ) {
+    this.ref = ref;
+    this.doc = doc;
+    this.embedder = embedder;
+  }
+
+  /**
+   * > **NOTE:** You probably don't need to call this method directly. The
+   * > [[PDFDocument.save]] and [[PDFDocument.saveAsBase64]] methods will
+   * > automatically ensure all JavaScripts get embedded.
+   *
+   * Embed this JavaScript in its document.
+   *
+   * @returns Resolves when the embedding is complete.
+   */
+  async embed(): Promise<void> {
+    if (!this.alreadyEmbedded) {
+      const { catalog, context } = this.doc;
+
+      const ref = await this.embedder.embedIntoContext(
+        this.doc.context,
+        this.ref,
+      );
+
+      if (!catalog.has(PDFName.of('Names'))) {
+        catalog.set(PDFName.of('Names'), context.obj({}));
+      }
+      const Names = catalog.lookup(PDFName.of('Names'), PDFDict);
+
+      if (!Names.has(PDFName.of('JavaScript'))) {
+        Names.set(PDFName.of('JavaScript'), context.obj({}));
+      }
+      const Javascript = Names.lookup(PDFName.of('JavaScript'), PDFDict);
+
+      if (!Javascript.has(PDFName.of('Names'))) {
+        Javascript.set(PDFName.of('Names'), context.obj([]));
+      }
+      const JSNames = Javascript.lookup(PDFName.of('Names'), PDFArray);
+
+      JSNames.push(PDFHexString.fromText(this.embedder.scriptName));
+      JSNames.push(ref);
+
+      this.alreadyEmbedded = true;
+    }
+  }
+}