officetopdf-js 0.0.1

package/src/__tests__/binary.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { UnsupportedPlatformError } from "../errors/OfficeToPdfError.js";
+import { resolveBinaryPath } from "../internal/binary.js";
+
+const originalEnv = process.env.OFFICE2PDF_BINARY;
+
+function platformPackageInstalled(): boolean {
+  delete process.env.OFFICE2PDF_BINARY;
+  try {
+    resolveBinaryPath();
+    return true;
+  } catch {
+    return false;
+  } finally {
+    restoreEnv();
+  }
+}
+
+function restoreEnv() {
+  if (originalEnv === undefined) delete process.env.OFFICE2PDF_BINARY;
+  else process.env.OFFICE2PDF_BINARY = originalEnv;
+}
+
+const bundled = platformPackageInstalled();
+
+afterEach(restoreEnv);
+
+describe("resolveBinaryPath", () => {
+  test("prefers an explicit override", () => {
+    process.env.OFFICE2PDF_BINARY = "/from/env";
+    expect(resolveBinaryPath("/explicit")).toBe("/explicit");
+  });
+
+  test("falls back to OFFICE2PDF_BINARY", () => {
+    process.env.OFFICE2PDF_BINARY = "/from/env";
+    expect(resolveBinaryPath()).toBe("/from/env");
+  });
+
+  test.skipIf(bundled)("ignores an empty OFFICE2PDF_BINARY", () => {
+    process.env.OFFICE2PDF_BINARY = "";
+    expect(() => resolveBinaryPath()).toThrow(UnsupportedPlatformError);
+  });
+
+  test.skipIf(bundled)("names the platform when no binary is installed", () => {
+    delete process.env.OFFICE2PDF_BINARY;
+    expect(() => resolveBinaryPath()).toThrow(`${process.platform}-${process.arch}`);
+  });
+
+  test.skipIf(!bundled)("resolves the bundled platform binary", () => {
+    delete process.env.OFFICE2PDF_BINARY;
+    expect(resolveBinaryPath()).toContain("office2pdf");
+  });
+});

package/src/__tests__/cli-args.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { buildArgs, fontExtension } from "../internal/cli-args.js";
+import type { ConvertOptions } from "../types.js";
+
+describe("buildArgs", () => {
+  const args = (options: ConvertOptions = {}, fontPaths: string[] = []) =>
+    buildArgs("in.docx", "out.pdf", fontPaths, options);
+
+  test("always passes the input and output paths", () => {
+    expect(args()).toEqual(["in.docx", "--output", "out.pdf"]);
+  });
+
+  test("omits every flag that was not requested", () => {
+    expect(args({ landscape: false, pdfA: false, sheets: [], slides: "" })).toEqual([
+      "in.docx",
+      "--output",
+      "out.pdf",
+    ]);
+  });
+
+  test("maps each option to its CLI flag", () => {
+    expect(
+      args({
+        paperSize: "letter",
+        landscape: true,
+        pdfA: true,
+        tagged: true,
+        pdfUa: true,
+        sheets: ["Sheet1", "Summary"],
+        slides: "1-5",
+      }),
+    ).toEqual([
+      "in.docx",
+      "--output",
+      "out.pdf",
+      "--paper",
+      "letter",
+      "--landscape",
+      "--pdf-a",
+      "--tagged",
+      "--pdf-ua",
+      "--sheets",
+      "Sheet1,Summary",
+      "--slides",
+      "1-5",
+    ]);
+  });
+
+  test("repeats --font-path once per directory", () => {
+    expect(args({}, ["/a", "/b"])).toEqual([
+      "in.docx",
+      "--output",
+      "out.pdf",
+      "--font-path",
+      "/a",
+      "--font-path",
+      "/b",
+    ]);
+  });
+
+  test("keeps every flag value directly after its flag", () => {
+    const result = args({ slides: "1-5", paperSize: "a4" });
+    expect(result[result.indexOf("--slides") + 1]).toBe("1-5");
+    expect(result[result.indexOf("--paper") + 1]).toBe("a4");
+  });
+});
+
+describe("fontExtension", () => {
+  const magic = (tag: string) =>
+    new Uint8Array([...tag].map((character) => character.charCodeAt(0)));
+
+  test("detects a TrueType collection", () => {
+    expect(fontExtension(magic("ttcf"))).toBe("ttc");
+  });
+
+  test("detects OpenType CFF outlines", () => {
+    expect(fontExtension(magic("OTTO"))).toBe("otf");
+  });
+
+  test("falls back to ttf for anything else", () => {
+    expect(fontExtension(new Uint8Array([0, 1, 0, 0]))).toBe("ttf");
+  });
+
+  test("falls back to ttf for bytes shorter than the magic", () => {
+    expect(fontExtension(new Uint8Array([0]))).toBe("ttf");
+  });
+});

package/src/__tests__/convenience.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { createFormatShortcuts } from "../internal/convenience.js";
+import type { ConvertOptions } from "../types.js";
+
+describe("createFormatShortcuts", () => {
+  const calls: ConvertOptions[] = [];
+  const shortcuts = createFormatShortcuts(async (_input, options = {}) => {
+    calls.push(options);
+    return new Uint8Array();
+  });
+
+  test("docxToPdf pins the docx format", async () => {
+    await shortcuts.docxToPdf(new Uint8Array());
+    expect(calls.at(-1)?.format).toBe("docx");
+  });
+
+  test("pptxToPdf pins the pptx format", async () => {
+    await shortcuts.pptxToPdf(new Uint8Array());
+    expect(calls.at(-1)?.format).toBe("pptx");
+  });
+
+  test("xlsxToPdf pins the xlsx format", async () => {
+    await shortcuts.xlsxToPdf(new Uint8Array());
+    expect(calls.at(-1)?.format).toBe("xlsx");
+  });
+
+  test("forwards the caller's other options", async () => {
+    await shortcuts.docxToPdf(new Uint8Array(), { landscape: true, paperSize: "a4" });
+    expect(calls.at(-1)).toEqual({ landscape: true, paperSize: "a4", format: "docx" });
+  });
+
+  test("does not let the caller override the pinned format", async () => {
+    await shortcuts.xlsxToPdf(new Uint8Array(), { format: "docx" } as ConvertOptions);
+    expect(calls.at(-1)?.format).toBe("xlsx");
+  });
+});

package/src/__tests__/shared.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { OfficeToPdfError } from "../errors/OfficeToPdfError.js";
+import { resolveFormat, toBytes } from "../internal/shared.js";
+
+describe("toBytes", () => {
+  test("passes through a Uint8Array", async () => {
+    const bytes = new Uint8Array([1, 2, 3]);
+    expect(await toBytes(bytes)).toBe(bytes);
+  });
+
+  test("converts an ArrayBuffer", async () => {
+    expect(await toBytes(new Uint8Array([1, 2]).buffer)).toEqual(new Uint8Array([1, 2]));
+  });
+
+  test("converts a Blob", async () => {
+    expect(await toBytes(new Blob([new Uint8Array([7])]))).toEqual(new Uint8Array([7]));
+  });
+
+  test("rejects unsupported input", () => {
+    expect(toBytes("nope" as never)).rejects.toThrow(OfficeToPdfError);
+  });
+});
+
+describe("resolveFormat", () => {
+  const bytes = new Uint8Array();
+
+  test("prefers the explicit format", () => {
+    expect(resolveFormat(bytes, { format: "pptx" })).toBe("pptx");
+  });
+
+  test("infers the format from a File name", () => {
+    const file = new File([bytes], "Report.DOCX");
+    expect(resolveFormat(file, {})).toBe("docx");
+  });
+
+  test("throws when the format cannot be inferred", () => {
+    expect(() => resolveFormat(bytes, {})).toThrow(OfficeToPdfError);
+  });
+
+  test("rejects an unknown format", () => {
+    expect(() => resolveFormat(bytes, { format: "pdf" as never })).toThrow(OfficeToPdfError);
+  });
+});

package/src/browser.ts

@@ -0,0 +1,125 @@
+import { ConversionFailedError, OfficeToPdfError } from "./errors/OfficeToPdfError.js";
+import { createFormatShortcuts } from "./internal/convenience.js";
+import { resolveFormat, toBytes } from "./internal/shared.js";
+import type {
+  ConversionWarning,
+  Converter,
+  ConverterOptions,
+  ConvertInput,
+  ConvertOptions,
+} from "./types.js";
+
+type WasmModule = typeof import("officetopdf-wasm");
+type ConversionResult = InstanceType<WasmModule["ConversionResult"]>;
+type WasmWarning = InstanceType<WasmModule["ConversionWarning"]>;
+type WasmConverter = InstanceType<WasmModule["Office2PdfConverter"]>;
+
+let wasmModule: Promise<WasmModule> | undefined;
+
+async function loadWasm(): Promise<WasmModule> {
+  wasmModule ??= import("officetopdf-wasm")
+    .then(async (module) => {
+      await module.default();
+      return module;
+    })
+    .catch((cause) => {
+      wasmModule = undefined;
+      throw new OfficeToPdfError(
+        "Failed to load the office2pdf WebAssembly module. Install the optional " +
+          "`officetopdf-wasm` package to convert in the browser.",
+        { cause },
+      );
+    });
+  return wasmModule;
+}
+
+function toWarning(warning: WasmWarning): ConversionWarning {
+  const { kind, format, message, from, to, element, detail, reason } = warning;
+  warning.free();
+  return { kind, format, message, from, to, element, detail, reason };
+}
+
+function reportWarnings(result: ConversionResult, onWarning: ConvertOptions["onWarning"]) {
+  for (let index = 0; index < result.warningCount; index += 1) {
+    const warning = result.warningAt(index);
+    if (warning) onWarning?.(toWarning(warning));
+  }
+}
+
+class BrowserConverter implements Converter {
+  private instance?: Promise<WasmConverter>;
+
+  constructor(private readonly options: ConverterOptions = {}) {}
+
+  async convert(input: ConvertInput, options: ConvertOptions = {}): Promise<Uint8Array> {
+    const format = resolveFormat(input, options);
+    const bytes = await toBytes(input);
+    const converter = await this.getInstance();
+
+    try {
+      const result = converter.convertToPdf(bytes, format);
+      try {
+        reportWarnings(result, options.onWarning);
+        return result.pdf;
+      } finally {
+        result.free();
+      }
+    } catch (cause) {
+      throw new ConversionFailedError(
+        `Converting ${format} to PDF failed`,
+        cause instanceof Error ? cause.message : String(cause),
+      );
+    }
+  }
+
+  async dispose(): Promise<void> {
+    const instance = this.instance;
+    this.instance = undefined;
+    (await instance)?.free();
+  }
+
+  private getInstance(): Promise<WasmConverter> {
+    this.instance ??= (async () => {
+      const { Office2PdfConverter } = await loadWasm();
+      const converter = new Office2PdfConverter();
+
+      for (const font of this.options.fonts ?? []) converter.registerFont(await toBytes(font));
+      if (this.options.lastResortFontFamily) {
+        converter.setLastResortFontFamily(this.options.lastResortFontFamily);
+      }
+      return converter;
+    })();
+    return this.instance;
+  }
+}
+
+export function createConverter(options?: ConverterOptions): Converter {
+  return new BrowserConverter(options);
+}
+
+export async function convert(input: ConvertInput, options?: ConvertOptions): Promise<Uint8Array> {
+  const converter = new BrowserConverter();
+  try {
+    return await converter.convert(input, options);
+  } finally {
+    await converter.dispose();
+  }
+}
+
+export const { docxToPdf, pptxToPdf, xlsxToPdf } = createFormatShortcuts(convert);
+
+export {
+  ConversionFailedError,
+  OfficeToPdfError,
+  UnsupportedPlatformError,
+} from "./errors/OfficeToPdfError.js";
+export type { FormatOptions, FormatShortcut } from "./internal/convenience.js";
+export type {
+  ConversionWarning,
+  Converter,
+  ConverterOptions,
+  ConvertInput,
+  ConvertOptions,
+  OfficeFormat,
+  PaperSize,
+} from "./types.js";

package/src/errors/OfficeToPdfError.ts

@@ -0,0 +1,27 @@
+export class OfficeToPdfError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "OfficeToPdfError";
+  }
+}
+
+export class UnsupportedPlatformError extends OfficeToPdfError {
+  constructor(platform: string, arch: string, options?: ErrorOptions) {
+    super(
+      `No office2pdf binary is available for ${platform}-${arch}. ` +
+        "Install the matching platform package, or set OFFICE2PDF_BINARY to a local binary.",
+      options,
+    );
+    this.name = "UnsupportedPlatformError";
+  }
+}
+
+export class ConversionFailedError extends OfficeToPdfError {
+  constructor(
+    message: string,
+    readonly detail?: string,
+  ) {
+    super(detail ? `${message}: ${detail}` : message);
+    this.name = "ConversionFailedError";
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./node.js";

package/src/internal/binary.ts

@@ -0,0 +1,49 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import { UnsupportedPlatformError } from "../errors/OfficeToPdfError.js";
+
+const require = createRequire(import.meta.url);
+
+const PLATFORM_PACKAGES: Record<string, string> = {
+  "darwin-arm64": "officetopdf-darwin-arm64",
+  "darwin-x64": "officetopdf-darwin-x64",
+  "linux-arm64": "officetopdf-linux-arm64",
+  "linux-x64": "officetopdf-linux-x64",
+  "linux-x64-musl": "officetopdf-linux-x64-musl",
+  "win32-x64": "officetopdf-windows-x64",
+};
+
+function isMusl(): boolean {
+  const report = process.report?.getReport();
+  if (typeof report === "object" && report !== null && "header" in report) {
+    const header = (report as { header?: { glibcVersionRuntime?: string } }).header;
+    return !header?.glibcVersionRuntime;
+  }
+  return false;
+}
+
+function currentTarget(): string {
+  const target = `${process.platform}-${process.arch}`;
+  return target === "linux-x64" && isMusl() ? "linux-x64-musl" : target;
+}
+
+let cached: string | undefined;
+
+export function resolveBinaryPath(override?: string): string {
+  const explicit = override ?? process.env.OFFICE2PDF_BINARY;
+  if (explicit) return explicit;
+  if (cached) return cached;
+
+  const target = currentTarget();
+  const packageName = PLATFORM_PACKAGES[target];
+  if (!packageName) throw new UnsupportedPlatformError(process.platform, process.arch);
+
+  const executable = process.platform === "win32" ? "office2pdf.exe" : "office2pdf";
+  try {
+    cached = join(dirname(require.resolve(`${packageName}/package.json`)), executable);
+  } catch (cause) {
+    throw new UnsupportedPlatformError(process.platform, process.arch, { cause });
+  }
+  return cached;
+}

package/src/internal/cli-args.ts

@@ -0,0 +1,28 @@
+import type { ConvertOptions } from "../types.js";
+
+export function buildArgs(
+  inputPath: string,
+  outputPath: string,
+  fontPaths: readonly string[],
+  options: ConvertOptions,
+): string[] {
+  const args = [inputPath, "--output", outputPath];
+
+  if (options.paperSize) args.push("--paper", options.paperSize);
+  if (options.landscape) args.push("--landscape");
+  if (options.pdfA) args.push("--pdf-a");
+  if (options.tagged) args.push("--tagged");
+  if (options.pdfUa) args.push("--pdf-ua");
+  if (options.sheets?.length) args.push("--sheets", options.sheets.join(","));
+  if (options.slides) args.push("--slides", options.slides);
+  for (const fontPath of fontPaths) args.push("--font-path", fontPath);
+
+  return args;
+}
+
+export function fontExtension(bytes: Uint8Array): string {
+  const magic = String.fromCharCode(...bytes.subarray(0, 4));
+  if (magic === "ttcf") return "ttc";
+  if (magic === "OTTO") return "otf";
+  return "ttf";
+}

package/src/internal/convenience.ts

@@ -0,0 +1,19 @@
+import type { ConvertInput, ConvertOptions, OfficeFormat } from "../types.js";
+
+export type FormatOptions = Omit<ConvertOptions, "format">;
+
+export type FormatShortcut = (input: ConvertInput, options?: FormatOptions) => Promise<Uint8Array>;
+
+type Convert = (input: ConvertInput, options?: ConvertOptions) => Promise<Uint8Array>;
+
+function shortcut(convert: Convert, format: OfficeFormat): FormatShortcut {
+  return (input, options) => convert(input, { ...options, format });
+}
+
+export function createFormatShortcuts(convert: Convert) {
+  return {
+    docxToPdf: shortcut(convert, "docx"),
+    pptxToPdf: shortcut(convert, "pptx"),
+    xlsxToPdf: shortcut(convert, "xlsx"),
+  };
+}

package/src/internal/shared.ts

@@ -0,0 +1,31 @@
+import { OfficeToPdfError } from "../errors/OfficeToPdfError.js";
+import type { ConvertInput, ConvertOptions, OfficeFormat } from "../types.js";
+
+const FORMATS: readonly OfficeFormat[] = ["docx", "pptx", "xlsx"];
+
+export async function toBytes(input: ConvertInput): Promise<Uint8Array> {
+  if (input instanceof Uint8Array) return input;
+  if (input instanceof ArrayBuffer) return new Uint8Array(input);
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    return new Uint8Array(await input.arrayBuffer());
+  }
+  throw new OfficeToPdfError("Input must be a Uint8Array, ArrayBuffer, or Blob.");
+}
+
+export function resolveFormat(input: ConvertInput, options: ConvertOptions): OfficeFormat {
+  if (options.format) {
+    if (!FORMATS.includes(options.format)) {
+      throw new OfficeToPdfError(`Unsupported format "${options.format}".`);
+    }
+    return options.format;
+  }
+
+  const name = (input as { name?: unknown }).name;
+  const extension = typeof name === "string" ? name.split(".").pop()?.toLowerCase() : undefined;
+  const inferred = FORMATS.find((format) => format === extension);
+  if (inferred) return inferred;
+
+  throw new OfficeToPdfError(
+    'Unable to infer the input format. Pass { format: "docx" | "pptx" | "xlsx" }.',
+  );
+}

package/src/node.ts

@@ -0,0 +1,124 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { ConversionFailedError } from "./errors/OfficeToPdfError.js";
+import { resolveBinaryPath } from "./internal/binary.js";
+import { buildArgs, fontExtension } from "./internal/cli-args.js";
+import { createFormatShortcuts } from "./internal/convenience.js";
+import { resolveFormat, toBytes } from "./internal/shared.js";
+import type { Converter, ConverterOptions, ConvertInput, ConvertOptions } from "./types.js";
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+function reportWarnings(stderr: string, onWarning: ConvertOptions["onWarning"]) {
+  if (!onWarning) return;
+  for (const line of stderr.split("\n")) {
+    const message = line.trim();
+    if (message) onWarning({ message });
+  }
+}
+
+class NodeConverter implements Converter {
+  private readonly binaryPath: string;
+  private readonly timeoutMs: number;
+  private fontDir?: Promise<string | undefined>;
+
+  constructor(private readonly options: ConverterOptions = {}) {
+    this.binaryPath = resolveBinaryPath(options.binaryPath);
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  async convert(input: ConvertInput, options: ConvertOptions = {}): Promise<Uint8Array> {
+    const format = resolveFormat(input, options);
+    const bytes = await toBytes(input);
+    const fontPaths = await this.resolveFontPaths();
+
+    const workDir = await mkdtemp(join(tmpdir(), "office2pdf-"));
+    try {
+      const inputPath = join(workDir, `input.${format}`);
+      const outputPath = join(workDir, "output.pdf");
+      await writeFile(inputPath, bytes);
+
+      const { stderr } = await execFileAsync(
+        this.binaryPath,
+        buildArgs(inputPath, outputPath, fontPaths, options),
+        { timeout: this.timeoutMs, signal: options.signal, windowsHide: true },
+      ).catch((cause: NodeJS.ErrnoException & { stderr?: string }) => {
+        throw new ConversionFailedError(
+          `Converting ${format} to PDF failed`,
+          cause.stderr?.trim() || cause.message,
+        );
+      });
+
+      reportWarnings(stderr, options.onWarning);
+
+      return await readFile(outputPath);
+    } finally {
+      await rm(workDir, { recursive: true, force: true });
+    }
+  }
+
+  async dispose(): Promise<void> {
+    const dir = await this.fontDir;
+    this.fontDir = undefined;
+    if (dir) await rm(dir, { recursive: true, force: true });
+  }
+
+  private async resolveFontPaths(): Promise<readonly string[]> {
+    const configured = this.options.fontPaths ?? [];
+    const registered = await this.materializeFonts();
+    return registered ? [...configured, registered] : configured;
+  }
+
+  private materializeFonts(): Promise<string | undefined> {
+    this.fontDir ??= (async () => {
+      const fonts = this.options.fonts ?? [];
+      if (fonts.length === 0) return undefined;
+
+      const dir = await mkdtemp(join(tmpdir(), "office2pdf-fonts-"));
+      await Promise.all(
+        fonts.map(async (font, index) => {
+          const bytes = await toBytes(font);
+          return writeFile(join(dir, `font-${index}.${fontExtension(bytes)}`), bytes);
+        }),
+      );
+      return dir;
+    })();
+    return this.fontDir;
+  }
+}
+
+export function createConverter(options?: ConverterOptions): Converter {
+  return new NodeConverter(options);
+}
+
+export async function convert(input: ConvertInput, options?: ConvertOptions): Promise<Uint8Array> {
+  const converter = new NodeConverter();
+  try {
+    return await converter.convert(input, options);
+  } finally {
+    await converter.dispose();
+  }
+}
+
+export const { docxToPdf, pptxToPdf, xlsxToPdf } = createFormatShortcuts(convert);
+
+export {
+  ConversionFailedError,
+  OfficeToPdfError,
+  UnsupportedPlatformError,
+} from "./errors/OfficeToPdfError.js";
+export type { FormatOptions, FormatShortcut } from "./internal/convenience.js";
+export type {
+  ConversionWarning,
+  Converter,
+  ConverterOptions,
+  ConvertInput,
+  ConvertOptions,
+  OfficeFormat,
+  PaperSize,
+} from "./types.js";

package/src/types/officetopdf-wasm.d.ts

@@ -0,0 +1,37 @@
+declare module "officetopdf-wasm" {
+  export class ConversionWarning {
+    readonly kind: string;
+    readonly format: string;
+    readonly message: string;
+    readonly from: string | undefined;
+    readonly to: string | undefined;
+    readonly element: string | undefined;
+    readonly detail: string | undefined;
+    readonly reason: string | undefined;
+    free(): void;
+  }
+
+  export class ConversionResult {
+    readonly pdf: Uint8Array;
+    readonly warningCount: number;
+    warningAt(index: number): ConversionWarning | undefined;
+    free(): void;
+  }
+
+  export class Office2PdfConverter {
+    registerFont(data: Uint8Array): void;
+    clearFonts(): void;
+    setLastResortFontFamily(family: string): void;
+    clearLastResortFontFamily(): void;
+    convertToPdf(data: Uint8Array, format: string): ConversionResult;
+    convertDocxToPdf(data: Uint8Array): ConversionResult;
+    convertPptxToPdf(data: Uint8Array): ConversionResult;
+    convertXlsxToPdf(data: Uint8Array): ConversionResult;
+    free(): void;
+  }
+
+  export function convertToPdf(data: Uint8Array, format: string): Uint8Array;
+  export function convertToPdfWithResult(data: Uint8Array, format: string): ConversionResult;
+
+  export default function init(input?: unknown): Promise<unknown>;
+}