@quario/pdf 0.1.0

package/lib/index.js

@@ -0,0 +1,201 @@
+/**
+ * @quario/pdf — the PDF render target: a pure consumer of the engine's public
+ * event stream, passed to a compiled report's `render`, laying the banded walk out on
+ * pages. Layout is ours — wrapped paragraphs, keep-together, repeated table
+ * headers, page bands, `break: "page"`, `reset: "page"` — while the writing is pdf-lib's, so
+ * this target carries a typesetter rather than a PDF implementation. Output
+ * is deterministic: the document carries no dates of its own, so the same
+ * input renders the same bytes. Page geometry is target configuration
+ * (`pdf({ page })`), never schema.
+ *
+ * This file is options, fonts and geometry, the walk itself, and the passes
+ * that follow it over the finished pages — page furniture and the marking,
+ * neither of which can be drawn until the page count is known. Every handler
+ * the driver dispatches to is the band flow's, next door in `layout.js`; this
+ * file adds none. The work lives in the sibling modules, which ship beside it
+ * — the package publishes `lib/` verbatim.
+ */
+import { PDFDocument } from "pdf-lib";
+import { breathe, walk } from "quario";
+import { drawing, frame, stamp } from "./canvas.js";
+import { embedFonts } from "./fonts.js";
+import { flow, furniture } from "./layout.js";
+import { outline } from "./outline.js";
+
+// The options are described once, in the hand-written public declarations, and
+// read back here — a second copy in JSDoc is a copy that drifts.
+/** @import { PdfOptions } from './index.d.ts' */
+
+let SIZES = /** @type {Record<string, [number, number]>} */ ({
+  A4: [595.28, 841.89],
+  letter: [612, 792],
+});
+
+/** @type {(msg: string) => never} */
+let err = (msg) => {
+  throw Error(msg);
+};
+
+/** @type {(value: any) => boolean} */
+let finite = (value) => typeof value === "number" && Number.isFinite(value);
+
+/** @type {(value: number) => boolean} */
+let positive = (value) => Number.isFinite(value) && value > 0;
+
+/** @type {(options: any) => any} */
+let pageOf = (options) => options?.page ?? {};
+
+/** @type {(options: any) => { meta: any, fonts: any }} */
+let host = (options) => ({ meta: options?.meta, fonts: options?.fonts });
+
+/** @type {(size: any) => any} */
+let named = (size) => {
+  let dimensions = Array.isArray(size) ? size : SIZES[size];
+  // oxlint-disable-next-line no-unused-expressions
+  dimensions || err('options.page.size: unknown page size "' + size + '"');
+  return dimensions;
+};
+
+/** @type {(page: any) => any} */
+let pageSize = (page) => named(page.size ?? "A4");
+
+/** @type {(dimensions: any) => { width: number, height: number }} */
+let pair = (dimensions) => {
+  let width = +dimensions[0],
+    height = +dimensions[1];
+  // oxlint-disable-next-line no-unused-expressions
+  (positive(width) && positive(height)) ||
+    err("options.page.size: expected finite positive dimensions");
+  return { width, height };
+};
+
+/** @type {(page: any) => any} */
+let marginArg = (page) => page.margin ?? 54;
+
+/** @type {(margin: any, width: number, height: number) => number} */
+let marginOf = (margin, width, height) => {
+  let fits = finite(margin) && margin >= 0 && 2 * margin < Math.min(width, height);
+  // oxlint-disable-next-line no-unused-expressions
+  fits || err("options.page.margin: expected a non-negative number smaller than half the page");
+  return margin;
+};
+
+/** @type {(options: any) => any} */
+let baseArg = (options) => options?.baseSize ?? 10;
+
+/** @type {(base: any) => number} */
+let baseOf = (base) => {
+  // oxlint-disable-next-line no-unused-expressions
+  (finite(base) && base > 0) || err("options.baseSize: expected a positive number of points");
+  return base;
+};
+
+// The page box and the content box in one, settled here beside the validation
+// that produced them. This frame never moves at all: it serves every render the
+// target compiles, so a narrowing here would be one document's page bands
+// reserved out of the next one too. The one narrowing a render does make is the
+// band flow's, off that render's own canvas.
+/** @type {(options: any) => import('./canvas.js').Frame} */
+let geometry = (options) => {
+  let page = pageOf(options);
+  let { width, height } = pair(pageSize(page));
+  return frame(width, height, marginOf(marginArg(page), width, height), baseOf(baseArg(options)));
+};
+
+let META = [
+  ["title", "setTitle"],
+  ["author", "setAuthor"],
+  ["subject", "setSubject"],
+];
+
+/** @type {(doc: any, meta: any, entry: string[]) => void} */
+let field = (doc, meta, [key, method]) => {
+  if (typeof meta[key] === "string") doc[method](meta[key]);
+};
+
+// Optional document information. Never a date: pdf-lib stamps the current time
+// unless told otherwise, and a timestamp would make the same input render
+// different bytes on every run.
+/** @type {(doc: any, meta: any) => void} */
+let describe = (doc, meta) => {
+  doc.setCreationDate(new Date(0));
+  doc.setModificationDate(new Date(0));
+  if (meta) for (let entry of META) field(doc, meta, entry);
+};
+
+/** @type {(canvas: import('./canvas.js').Drawing, draw: (i: number) => void) => Promise<void>} */
+let overPages = async (canvas, draw) => {
+  for (let i = 0; i < canvas.count; i++) {
+    canvas.select(i);
+    draw(i);
+    if (i % 50 === 49) await breathe();
+  }
+};
+
+/** @type {(opening: any) => { bands: any, marking: any }} */
+let openingOf = (opening) => ({ bands: opening?.page, marking: opening?.marking });
+
+/** @type {(canvas: import('./canvas.js').Drawing, bands: any,
+ *   pages: { number: number, total: number }[]) => Promise<void>} */
+let furnish = async (canvas, bands, pages) => {
+  if (!bands) return;
+  await overPages(canvas, (i) => furniture(canvas, bands, pages[i]));
+};
+
+/** @type {(canvas: import('./canvas.js').Drawing, marking: any) => Promise<void>} */
+let markPages = async (canvas, marking) => {
+  if (!marking) return;
+  let mark = stamp(canvas, marking);
+  await overPages(canvas, () => canvas.watermark(mark));
+};
+
+/**
+ * The PDF render target:
+ * `quario().report(schema).render(pdf({ page }), data)` resolves the
+ * complete document as a `Uint8Array` (the host writes the file). Rendering
+ * hands the loop back between event and page batches, so large reports stay
+ * cooperative. Geometry and options are validated here, at the factory call.
+ *
+ * @param {PdfOptions} [options] Host controls (see SCHEMA.md, "The PDF target").
+ * @returns {{name: "pdf", compile: (stream: any) => (data?: any) => Promise<Uint8Array>}}
+ *   The target (see SCHEMA.md, "Instances and targets").
+ */
+export function pdf(options) {
+  let geo = geometry(options);
+  let { meta, fonts: custom } = host(options);
+  /** @type {(stream: any) => (data?: any) => Promise<Uint8Array>} */
+  let compile = (stream) => async (data) => {
+    let doc = await PDFDocument.create();
+    describe(doc, meta);
+    // Every face is embedded before the walk, so resolving a style to a
+    // font during layout stays synchronous.
+    let fonts = await embedFonts(doc, custom);
+    let canvas = drawing(doc, geo, fonts);
+    // The band flow owns the placement state and every handler over it, and
+    // opens the first page as it is built; this file only hands it the stream.
+    let { handlers, finish } = flow(canvas);
+    await walk(stream(data), handlers);
+    // The flow settled the opening event on its way past — it reserves the
+    // page bands off it — and hands it back with the marks. What is left on it
+    // is what the passes below want: the band closures to render per page, and
+    // the marking's wording to stamp.
+    let { marks, opening, pages } = finish();
+    let { bands, marking } = openingOf(opening);
+    // The passes below run over the finished pages, not the stream — no walk
+    // at all — so they open each page themselves and breathe on their own
+    // rather than through the driver.
+    await furnish(canvas, bands, pages);
+    // Every image the walk and the furniture pass placed, embedded and drawn
+    // now: a walk handler cannot await, and the page bands' images are not
+    // placed until the pass above has run. Before the marking, so an image can
+    // never cover it.
+    await canvas.pictures();
+    // The unlicensed marking goes on last, over content and page furniture
+    // alike, once per page (LICENSE section 6). Its wording rode in on
+    // `report-start`; only the placement is this target's.
+    await markPages(canvas, marking);
+    outline(doc, marks, canvas.refs);
+    return doc.save();
+  };
+  return { name: "pdf", compile };
+}