@ironsoftware/ironpdf 2026.5.1 → 2026.6.1

package/src/public/pdfDocument.ts

@@ -67,7 +67,10 @@ import {mergePdfs, renderHtmlToPdf, renderHtmlZipToPdf, renderUrlToPdf, renderHt
 import {disposePdf, getBinaryData, openPdfFileBuffer} from "../internal/grpc_layer/pdfium/io";
 import {Access} from "../internal/access";
 import {renderImagesBufferToPdf, renderImagesFilesToPdf} from "../internal/grpc_layer/chrome/image";
-import {compressAndSaveAs, compressImage, compressInMemory, compressInMemoryStream, compressStructTree} from "../internal/grpc_layer/pdfium/compress";
+import {compressAndSaveAs, compressImage, compressInMemory, compressInMemoryStream, compressStructTree, compressAndSaveAsAdvanced, compressAndSaveAsAdvancedFromBytes} from "../internal/grpc_layer/pdfium/compress";
+import {disableFormFontFallback, setFormFont} from "../internal/grpc_layer/pdfium/form";
+import {AdvancedCompressionOptions} from "./compression";
+import * as path from "path";
 import {
 	isLinearizedFromBytes,
 	linearizeCoreFromBytes,
@@ -471,6 +474,117 @@ export class PdfDocument{
 			(filePath, imageQuality);
 	}
 
+	/**
+	 * Apply the advanced compression pipeline and save the result to a file.
+	 *
+	 * Combines pdfium-side image DPI downsampling with qpdf-side structural
+	 * optimization in a single call.
+	 *
+	 * @param filePath the file path to save the compressed PDF
+	 * @param options  advanced compression options; pass an empty object `{}` to
+	 *                 reproduce the legacy compressAndSaveAs behaviour with no
+	 *                 image downsampling
+	 * @param password the PDF password (empty string if none)
+	 */
+	public async compressAndSaveAsAdvanced(
+		filePath: string,
+		options: AdvancedCompressionOptions,
+		password?: string
+	): Promise<void> {
+		return this.internal_compressAndSaveAsAdvanced(filePath, options, password);
+	}
+
+	/**
+	 * Apply the advanced compression pipeline to byte[] input and save the
+	 * compressed result to a file. Returns the compressed bytes as well.
+	 */
+	public static async compressAndSaveAsAdvancedFromBytes(
+		pdfBytes: Buffer,
+		filePath: string,
+		options: AdvancedCompressionOptions,
+		password?: string
+	): Promise<Buffer> {
+		if (!pdfBytes || pdfBytes.length === 0) {
+			throw new Error("pdfBytes must not be null or empty");
+		}
+		if (!options) {
+			throw new Error("options must not be null");
+		}
+		return compressAndSaveAsAdvancedFromBytes(pdfBytes, filePath, options, password ?? "");
+	}
+
+	//#endregion
+
+	//#region form (PDF-2184)
+
+	/**
+	 * Set the document-wide form font for subsequent form-field fills. When
+	 * set, the engine skips its automatic Tahoma/Arial fallback embed for
+	 * non-ASCII form values and registers the supplied font in the AcroForm
+	 * /DR /Font dictionary so default-appearance strings resolve correctly
+	 * at render time.
+	 *
+	 * File-size impact:
+	 * - Name-only mode (`fontData` omitted or empty): zero bytes added; the
+	 *   font must already be in the document.
+	 * - Bytes mode and the font is already embedded with usable glyph data:
+	 *   zero bytes added.
+	 * - Bytes mode and the font is missing or has no glyph data: the full
+	 *   font is embedded.
+	 * - Bytes mode with `forceEmbed = true`: a fresh font copy is added
+	 *   alongside any existing copy; the document grows on every call.
+	 *
+	 * @param fontName   PDF font name to register (e.g. "Poppins-Regular").
+	 *                   Allowed characters: letters, digits, `_`, `-`, `.`, `+`.
+	 * @param fontData   Raw TrueType/OpenType bytes; pass `undefined` or an
+	 *                   empty Buffer for name-only mode.
+	 * @param forceEmbed When true, embed `fontData` even if a font with the
+	 *                   same name and usable glyph data is already present.
+	 */
+	public async setFormFont(
+		fontName: string,
+		fontData?: Buffer,
+		forceEmbed = false
+	): Promise<void> {
+		return setFormFont(await this.internal_getId(), fontName, fontData, forceEmbed);
+	}
+
+	/**
+	 * Load a TrueType/OpenType font from disk and apply it as the
+	 * document-wide form font. The PDF font name is derived from the file
+	 * name (without extension) when `fontName` is omitted.
+	 *
+	 * @param fontFilePath Path to a TTF/OTF/TTC font file
+	 * @param fontName     Optional PDF font name. When omitted the file name
+	 *                     (without extension) is used.
+	 * @param forceEmbed   When true, embed even if the font is already present.
+	 */
+	public async setFormFontFromFile(
+		fontFilePath: string,
+		fontName?: string,
+		forceEmbed = false
+	): Promise<void> {
+		if (!fontFilePath) {
+			throw new Error("fontFilePath must not be empty");
+		}
+		const fontData = fs.readFileSync(fontFilePath);
+		const resolvedName = fontName ?? deriveFontNameFromPath(fontFilePath);
+		return setFormFont(await this.internal_getId(), resolvedName, fontData, forceEmbed);
+	}
+
+	/**
+	 * Suppress the automatic Tahoma/Arial fallback embed for non-ASCII form
+	 * values without registering any replacement font. Use when zero
+	 * file-size growth is required and the template's existing font
+	 * references are sufficient for the values being filled.
+	 *
+	 * Rendering of non-ASCII characters then depends entirely on the
+	 * viewer's font substitution.
+	 */
+	public async disableFormFontFallback(): Promise<void> {
+		return disableFormFontFallback(await this.internal_getId());
+	}
+
 	//#endregion
 
 	//#region linearize
@@ -1839,6 +1953,34 @@ export class PdfDocument{
 		);
 	}
 
+	private async internal_compressAndSaveAsAdvanced(
+		filePath: string,
+		options: AdvancedCompressionOptions,
+		password?: string
+	): Promise<void> {
+		if (!filePath || filePath.trim().length === 0) {
+			throw new Error("filePath must not be empty");
+		}
+		if (!options) {
+			throw new Error("options must not be null");
+		}
+		if (
+			options.jpegQuality !== undefined &&
+			options.jpegQuality !== null &&
+			(options.jpegQuality < 1 || options.jpegQuality > 100)
+		) {
+			throw new Error(
+				`Invalid jpegQuality (${options.jpegQuality}). Must be between 1 and 100.`
+			);
+		}
+		return await compressAndSaveAsAdvanced(
+			await this.internal_getId(),
+			filePath,
+			options,
+			password ?? ""
+		);
+	}
+
 	//#endregion
 
 	//#region linearize
@@ -2570,3 +2712,14 @@ export class PdfDocument{
 
 	//#endregion
 }
+
+/**
+ * Derive a PDF font name from a font file path: strip the directory and the
+ * extension. Used by {@link PdfDocument.setFormFontFromFile} when no
+ * explicit name is supplied.
+ */
+function deriveFontNameFromPath(fontFilePath: string): string {
+	const base = path.basename(fontFilePath);
+	const dot = base.lastIndexOf(".");
+	return dot > 0 ? base.substring(0, dot) : base;
+}