@procedures/pdf 0.0.0-stage → 0.4.0

package/src/browser.ts

@@ -0,0 +1,96 @@
+/**
+ * Find a Chromium browser that is already installed: Microsoft Edge, Google Chrome or Chromium.
+ * The package does not download a browser.
+ */
+
+import { existsSync } from "node:fs";
+import { posix, win32 } from "node:path";
+
+/** The environment variable that names the browser program. It comes before the search. */
+export const BROWSER_ENV = "PDF_BROWSER";
+
+/** The second environment variable for the browser program. Other tools use this name too. */
+export const CHROME_PATH_ENV = "CHROME_PATH";
+
+/** The program names that the search looks for on the `PATH`, in order. */
+export const BROWSER_NAMES: readonly string[] = [
+  "google-chrome",
+  "google-chrome-stable",
+  "chromium",
+  "chromium-browser",
+  "microsoft-edge",
+  "microsoft-edge-stable",
+];
+
+/** The program names on the `PATH` of Windows, in order. */
+export const WINDOWS_BROWSER_NAMES: readonly string[] = ["msedge.exe", "chrome.exe"];
+
+/** The options of `findBrowser`. Each one has a default from the host. */
+export interface FindBrowserOptions {
+  /** The browser program. When it is set, the search does not occur. */
+  readonly executable?: string | undefined;
+  /** The environment (default: `process.env`). */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /** The operating system (default: `process.platform`). */
+  readonly platform?: NodeJS.Platform | undefined;
+  /** The function that tells if a file exists (default: `existsSync`). */
+  readonly exists?: ((path: string) => boolean) | undefined;
+}
+
+/** This function gives the folders of the `PATH`, in order. */
+function pathFolders(env: Readonly<Record<string, string | undefined>>, windows: boolean): string[] {
+  const value = windows ? (env["Path"] ?? env["PATH"]) : env["PATH"];
+  if (value === undefined) return [];
+  return value.split(windows ? ";" : ":").filter((folder) => folder.length > 0);
+}
+
+/**
+ * This function gives the paths that the search examines on an operating system, in order. The
+ * install folders come first, then the folders of the `PATH`.
+ */
+export function browserCandidates(platform: NodeJS.Platform, env: Readonly<Record<string, string | undefined>>): string[] {
+  if (platform === "win32") {
+    const programFiles = env["ProgramFiles"] ?? env["PROGRAMFILES"] ?? "C:\\Program Files";
+    const programFilesX86 = env["ProgramFiles(x86)"] ?? env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)";
+    const localAppData = env["LOCALAPPDATA"];
+    const installed = [
+      win32.join(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe"),
+      win32.join(programFiles, "Microsoft", "Edge", "Application", "msedge.exe"),
+      win32.join(programFiles, "Google", "Chrome", "Application", "chrome.exe"),
+      win32.join(programFilesX86, "Google", "Chrome", "Application", "chrome.exe"),
+      ...(localAppData !== undefined
+        ? [win32.join(localAppData, "Google", "Chrome", "Application", "chrome.exe"), win32.join(localAppData, "Chromium", "Application", "chrome.exe")]
+        : []),
+    ];
+    const onPath = pathFolders(env, true).flatMap((folder) => WINDOWS_BROWSER_NAMES.map((name) => win32.join(folder, name)));
+    return [...installed, ...onPath];
+  }
+  const installed: string[] = [];
+  if (platform === "darwin") {
+    const bundles = [
+      "Google Chrome.app/Contents/MacOS/Google Chrome",
+      "Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      "Chromium.app/Contents/MacOS/Chromium",
+    ];
+    const home = env["HOME"];
+    installed.push(...bundles.map((bundle) => posix.join("/Applications", bundle)));
+    if (home !== undefined) installed.push(...bundles.map((bundle) => posix.join(home, "Applications", bundle)));
+  }
+  const onPath = pathFolders(env, false).flatMap((folder) => BROWSER_NAMES.map((name) => posix.join(folder, name)));
+  return [...installed, ...onPath];
+}
+
+/**
+ * This function finds the browser program. The order is `executable`, then `PDF_BROWSER`, then
+ * `CHROME_PATH`, then the install folders and the `PATH`. It gives `undefined` when it finds none.
+ */
+export function findBrowser(options: FindBrowserOptions = {}): string | undefined {
+  if (options.executable !== undefined && options.executable.length > 0) return options.executable;
+  const env = options.env ?? process.env;
+  for (const name of [BROWSER_ENV, CHROME_PATH_ENV]) {
+    const value = env[name];
+    if (value !== undefined && value.length > 0) return value;
+  }
+  const exists = options.exists ?? existsSync;
+  return browserCandidates(options.platform ?? process.platform, env).find((candidate) => exists(candidate));
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// The root registers nothing: import "<package>/register", or give the module to createRegistry()
+export * from "./module.js";
+export * from "./types.js";
+export * from "./browser.js";
+export * from "./render.js";
+export { pdfRender } from "./procedures/pdf/index.js";

package/src/module.ts

@@ -0,0 +1,48 @@
+/**
+ * The procedures of @procedures/pdf as data. An import of this file registers nothing.
+ *
+ * Scaffold a procedure with: mark procedure new <name> --path packages/pdf
+ */
+
+import {
+  defineModule,
+  registerModules,
+  PROCEDURE_REGISTRY,
+  type AnyProcedure,
+  type ProcedureModule,
+  type ProcedureRegistry,
+  createProcedure,
+  zodAdapter,
+} from "@procedures/client";
+import { pdfRender } from "./procedures/pdf/render.js";
+import { PdfRenderInputSchema, PdfRenderOutputSchema, type PdfRenderInput, type PdfRenderOutput } from "./types.js";
+
+export const pdfRenderProcedure: AnyProcedure = createProcedure()
+  .path(["pdf", "render"])
+  .input(zodAdapter<PdfRenderInput>(PdfRenderInputSchema))
+  .output(zodAdapter<PdfRenderOutput>(PdfRenderOutputSchema))
+  .meta({
+    description: "Render HTML to a PDF file with a headless Chromium browser",
+    args: [],
+    shorts: { output: "o", timeout: "t" },
+    output: "json",
+    // The browser reads the page and the files and addresses that the page names. The caller can
+    // choose the browser program, so the procedure writes "process". It replaces the output file.
+    effects: { reads: ["fs", "network", "process"], writes: ["fs", "process"], destructive: true },
+  })
+  .handler(async (input: PdfRenderInput, ctx): Promise<PdfRenderOutput> => pdfRender(input, ctx))
+  .build() as AnyProcedure;
+
+export const pdfProcedures: AnyProcedure[] = [pdfRenderProcedure];
+
+export const pdfModule: ProcedureModule = defineModule("@procedures/pdf", pdfProcedures);
+
+export default pdfModule;
+
+/**
+ * This function registers the procedures of @procedures/pdf in a registry. The default is the
+ * global registry.
+ */
+export function registerPdfProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [pdfModule]);
+}

package/src/procedures/pdf/index.ts

@@ -0,0 +1 @@
+export { pdfRender } from "./render.js";

package/src/procedures/pdf/render.ts

@@ -0,0 +1,31 @@
+/**
+ * pdf.render procedure
+ *
+ * This procedure prints an HTML page to a PDF file with a headless Chromium browser that is
+ * already installed.
+ */
+
+import { renderPdf, type CommandRunner } from "../../render.js";
+import type { PdfRenderInput, PdfRenderOutput } from "../../types.js";
+
+/**
+ * This function prints the HTML text or the HTML file of the input to a PDF file. It gives the
+ * path and the size of the file.
+ */
+export async function pdfRender(
+  input: PdfRenderInput,
+  ctx?: { signal?: AbortSignal | undefined },
+  runner?: CommandRunner
+): Promise<PdfRenderOutput> {
+  const result = await renderPdf({
+    html: input.html,
+    file: input.file,
+    output: input.output,
+    executable: input.executable,
+    args: input.args,
+    timeout: input.timeout,
+    signal: ctx?.signal,
+    runner,
+  });
+  return { path: result.path, bytes: result.bytes, browser: result.browser };
+}

package/src/register.ts

@@ -0,0 +1,10 @@
+/**
+ * An import of this file registers the procedures of @procedures/pdf in the global registry:
+ * `import "@procedures/pdf/register"`. The package root registers nothing.
+ */
+
+import { registerPdfProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerPdfProcedures();

package/src/render.ts

@@ -0,0 +1,151 @@
+/**
+ * HTML to PDF with a headless Chromium browser that is already installed.
+ *
+ * The browser starts with argv, not through a shell, through `runCommand` of
+ * `@procedures/shell`. A time limit and the signal of the call stop its process tree.
+ */
+
+import { closeSync, mkdirSync, mkdtempSync, openSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { runCommand, type CommandOptions, type CommandResult } from "@procedures/shell/command";
+import { BROWSER_ENV, findBrowser, type FindBrowserOptions } from "./browser.js";
+
+/** The default time limit of one render, in milliseconds. */
+export const DEFAULT_TIMEOUT_MS = 60_000;
+
+/** The function that runs a program. The default is `runCommand` of `@procedures/shell`. */
+export type CommandRunner = (command: string, options: CommandOptions) => Promise<CommandResult>;
+
+/** The options of `renderPdf`. Give `html` or `file`, not the two. */
+export interface RenderPdfOptions extends FindBrowserOptions {
+  /** The HTML text. The function writes it to a temporary file. */
+  readonly html?: string | undefined;
+  /** The path of an HTML file. */
+  readonly file?: string | undefined;
+  /** The path of the PDF file. The default is a file in a new temporary folder. */
+  readonly output?: string | undefined;
+  /** More flags for the browser, after the default flags. */
+  readonly args?: readonly string[] | undefined;
+  /** The time limit, in milliseconds (default: 60000). */
+  readonly timeout?: number | undefined;
+  /** When the signal aborts, the browser stops. */
+  readonly signal?: AbortSignal | undefined;
+  /** The function that runs the browser (default: `runCommand`). The tests give their own. */
+  readonly runner?: CommandRunner | undefined;
+}
+
+/** The result of `renderPdf`. */
+export interface RenderPdfResult {
+  /** The absolute path of the PDF file. */
+  readonly path: string;
+  /** The size of the PDF file, in bytes. */
+  readonly bytes: number;
+  /** The browser program that made the file. */
+  readonly browser: string;
+}
+
+/**
+ * This function gives the argv of the browser. The argv has the flags of a headless print, the
+ * profile folder, the extra flags and the address of the page.
+ */
+export function pdfArgs(page: string, output: string, profile: string, extra: readonly string[] = []): string[] {
+  return [
+    "--headless",
+    "--disable-gpu",
+    "--no-pdf-header-footer",
+    // A separate profile keeps the print apart from a browser that the user has open
+    `--user-data-dir=${profile}`,
+    `--print-to-pdf=${output}`,
+    ...extra,
+    page,
+  ];
+}
+
+/** This function tells if a file starts with the signature of a PDF file (`%PDF`). */
+export function isPdfFile(path: string): boolean {
+  const fd = openSync(path, "r");
+  try {
+    const head = Buffer.alloc(4);
+    const read = readSync(fd, head, 0, 4, 0);
+    return read === 4 && head.toString("latin1") === "%PDF";
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function fileSize(path: string): number | undefined {
+  try {
+    return statSync(path).size;
+  } catch {
+    return undefined;
+  }
+}
+
+function lastLines(text: string, count = 5): string {
+  return text.trim().split(/\r?\n/).slice(-count).join("\n");
+}
+
+/**
+ * This function prints an HTML page to a PDF file with a headless browser. It gives the path and
+ * the size of the file. It throws when it finds no browser, at the time limit, and when the file
+ * is not a PDF file.
+ */
+export async function renderPdf(options: RenderPdfOptions): Promise<RenderPdfResult> {
+  const hasHtml = options.html !== undefined;
+  const hasFile = options.file !== undefined;
+  if (hasHtml === hasFile) throw new Error("renderPdf needs html or file, and not the two");
+  const browser = findBrowser(options);
+  if (browser === undefined) {
+    throw new Error(`No browser found. Install Microsoft Edge, Google Chrome or Chromium, or set ${BROWSER_ENV} to the browser program.`);
+  }
+
+  const work = mkdtempSync(join(tmpdir(), "procedures-pdf-"));
+  const profile = join(work, "profile");
+  const output = resolve(options.output ?? join(work, "page.pdf"));
+  let made = false;
+  try {
+    let page: string;
+    if (options.html !== undefined) {
+      const htmlFile = join(work, "page.html");
+      writeFileSync(htmlFile, options.html, "utf8");
+      page = pathToFileURL(htmlFile).href;
+    } else {
+      page = pathToFileURL(resolve(options.file!)).href;
+    }
+    mkdirSync(dirname(output), { recursive: true });
+    // An old file must not pass the check of the new one
+    rmSync(output, { force: true });
+
+    const run = options.runner ?? runCommand;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    const result = await run(browser, {
+      args: pdfArgs(page, output, profile, options.args),
+      timeout,
+      signal: options.signal,
+      maxOutputBytes: 64 * 1024,
+      keep: "tail",
+    });
+    if (result.error !== undefined) throw new Error(`The browser did not start: ${result.error}`);
+    if (result.timedOut === true) throw new Error(`The browser did not finish in ${timeout} ms`);
+    if (result.aborted === true) throw new Error("The render was cancelled");
+
+    const bytes = fileSize(output);
+    if (bytes === undefined || bytes === 0) {
+      const detail = lastLines(result.stderr || result.stdout);
+      throw new Error(`The browser made no PDF file (exit code ${result.exitCode})${detail ? `: ${detail}` : ""}`);
+    }
+    if (!isPdfFile(output)) throw new Error(`The file ${output} is not a PDF file`);
+    made = true;
+    return { path: output, bytes, browser };
+  } finally {
+    // The temporary page and profile go. A default output stays in its folder after a success.
+    if (made && options.output === undefined) {
+      rmSync(profile, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+      rmSync(join(work, "page.html"), { force: true });
+    } else {
+      rmSync(work, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+/**
+ * The input and the output of the procedures of this package.
+ */
+
+import { z } from "zod";
+
+// =============================================================================
+// pdf.render: HTML to a PDF file with a headless Chromium browser
+// =============================================================================
+
+/** The input of `pdf.render`. Give `html` or `file`, not the two. */
+export interface PdfRenderInput {
+  html?: string | undefined;
+  file?: string | undefined;
+  output?: string | undefined;
+  executable?: string | undefined;
+  args?: string[] | undefined;
+  timeout?: number | undefined;
+}
+
+export const PdfRenderInputSchema: z.ZodType<PdfRenderInput> = z
+  .object({
+    html: z.string().optional().describe("The HTML text of the page"),
+    file: z.string().min(1).optional().describe("The path of an HTML file"),
+    output: z.string().min(1).optional().describe("The path of the PDF file (default: a file in a new temporary folder)"),
+    executable: z.string().min(1).optional().describe("The browser program (default: PDF_BROWSER, CHROME_PATH, then a search)"),
+    args: z.array(z.string()).optional().describe("More flags for the browser, for example --no-sandbox"),
+    timeout: z.number().int().positive().optional().describe("The time limit, in milliseconds (default: 60000)"),
+  })
+  .refine((input) => (input.html !== undefined) !== (input.file !== undefined), { message: "Give html or file, and not the two" });
+
+/** The output of `pdf.render`. */
+export interface PdfRenderOutput {
+  path: string;
+  bytes: number;
+  browser: string;
+}
+
+export const PdfRenderOutputSchema: z.ZodType<PdfRenderOutput> = z.object({
+  path: z.string().describe("The absolute path of the PDF file"),
+  bytes: z.number().describe("The size of the PDF file, in bytes"),
+  browser: z.string().describe("The browser program that made the file"),
+});