@reportwright/engine 0.0.0-stage → 0.11.0

package/dist/types/src/exporters/xlsxwriter.d.ts

@@ -0,0 +1,83 @@
+/** A worksheet's XML up to and including <sheetData> (what must be known before the rows: widths, frozen rows, outline). */
+export function sheetHead({ widths, frozenRows, outlineLevelRow }: {
+    widths: any;
+    frozenRows: any;
+    outlineLevelRow: any;
+}): string;
+/** The rest of a worksheet after its rows: merges (they come after <sheetData>, so they can be gathered while rows stream). */
+export function sheetTail(merges: any, drawing?: boolean): string;
+export function colName(c: any): string;
+/**
+ * @typedef {{ numFmt?: string|null, bold?: boolean, fill?: boolean }} CellStyle
+ * @typedef {{ v?: any, f?: string, style?: CellStyle }} Cell
+ */
+export class Sheet {
+    /** @param {Book} book @param {string} name */
+    constructor(book: Book, name: string);
+    book: Book;
+    name: string;
+    /** @type {string[]} */ xml: string[];
+    /** @type {number[]} */ widths: number[];
+    /** @type {string[]} */ merges: string[];
+    /** @type {{ bytes: Uint8Array, ext: string, col: number, row: number, w: number, h: number }[]} */ images: {
+        bytes: Uint8Array;
+        ext: string;
+        col: number;
+        row: number;
+        w: number;
+        h: number;
+    }[];
+    rowCount: number;
+    frozenRows: number;
+    outlineLevelRow: number;
+    /**
+     * Add a row (1-based number returned). cells: one per column (null = empty).
+     * @param {(Cell|null)[]} cells @param {{ outlineLevel?: number }} [opt]
+     */
+    addRow(cells: (Cell | null)[], opt?: {
+        outlineLevel?: number;
+    }): number;
+    /** Merge (1-based, inclusive). */
+    merge(r1: any, c1: any, r2: any, c2: any): void;
+    /** A picture with its top-left at (col, row), 0-based, w × h pixels. */
+    addImage(bytes: any, ext: any, col: any, row: any, w: any, h: any): void;
+    /** @param {number} i */
+    toXml(i: number): string;
+}
+export class Book {
+    constructor({ title, creator }?: {
+        title?: string;
+        creator?: string;
+    });
+    title: string;
+    creator: string;
+    fullCalcOnLoad: boolean;
+    /** @type {Sheet[]} */ sheets: Sheet[];
+    /** @type {Map<string, number>} */ styles: Map<string, number>;
+    /** @type {Map<string, number>} */ numFmts: Map<string, number>;
+    /** @param {string} name */
+    addSheet(name: string): Sheet;
+    /** cellXfs index for a style */
+    style(st: CellStyle | undefined): number;
+    /** One <c> element. @param {string} ref @param {Cell} c */
+    cell(ref: string, c: Cell): string;
+    stylesXml(): string;
+    /** The .xlsx bytes. */
+    write(): Uint8Array<ArrayBuffer>;
+    /**
+     * The workbook's own parts, written after the sheets (their names, the styles they used): styles, workbook,
+     * relationships, properties and content types. over: [part, content type] of the sheets and drawings.
+     * @param {[string, string][]} over @returns {[string, string][]}
+     */
+    bookParts(over: [string, string][]): [string, string][];
+}
+export type CellStyle = {
+    numFmt?: string | null;
+    bold?: boolean;
+    fill?: boolean;
+};
+export type Cell = {
+    v?: any;
+    f?: string;
+    style?: CellStyle;
+};

package/dist/types/src/importers/xml.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Parse an XML document into its root element.
+ * @param {string} src
+ * @param {Partial<typeof XML_LIMITS>} [limits]
+ * @returns {XmlElement}
+ */
+export function parseXml(src: string, limits?: Partial<typeof XML_LIMITS>): XmlElement;
+/**
+ * A small XML reader for untrusted files (SSRS .rdl). Pure JavaScript, no DOM, so it runs anywhere.
+ *
+ * Safe by construction:
+ *   - no DTDs: <!DOCTYPE and <!ENTITY are refused, so there is no entity expansion (XXE, billion laughs);
+ *     only the five XML entities and character references are read;
+ *   - caps on size, nesting depth, element count and attributes per element;
+ *   - linear time: it scans with indexOf and character tests, no regular expression runs over the input.
+ *
+ * Elements come back as { name, ns, attrs, children, text }: name is the local name (prefix removed),
+ * ns the namespace URI, text the element's own character data (CDATA included).
+ */
+export class XmlError extends Error {
+}
+export namespace XML_LIMITS {
+    let maxChars: number;
+    let maxDepth: number;
+    let maxElements: number;
+    let maxAttributes: number;
+}
+export type XmlElement = {
+    name: string;
+    ns: string;
+    attrs: Record<string, string>;
+    children: XmlElement[];
+    text: string;
+};

package/index.d.ts

@@ -0,0 +1,3 @@
+// @reportwright/engine types: the API (generated from the engine's JSDoc into dist/types) and the report schema.
+export * from './dist/types/packages/engine/entry.js';
+export type * from './report.js';

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@reportwright/engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.11.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "license": "MIT",
+  "author": "Arun Mallikarjun",
+  "homepage": "https://github.com/MrArun005/reportwright/tree/main/packages/engine#readme",
+  "bugs": {
+    "url": "https://github.com/MrArun005/reportwright/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrArun005/reportwright.git",
+    "directory": "packages/engine"
+  },
+  "keywords": [
+    "reportwright",
+    "report",
+    "reporting",
+    "pdf",
+    "pdf-a",
+    "excel",
+    "xlsx",
+    "docx",
+    "pptx",
+    "report-engine",
+    "jasperreports",
+    "ssrs",
+    "rdl"
+  ],
+  "description": "ReportWright report engine: JSON report definitions to pages, PDF (incl. PDF/A), Word, Excel, PowerPoint, HTML and CSV. Node and browsers. Fonts: @reportwright/fonts; CLI: @reportwright/cli.",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./report": {
+      "types": "./report.d.ts"
+    },
+    "./schema.json": "./schema.json",
+    "./pool": {
+      "types": "./pool/index.d.ts",
+      "default": "./pool/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "dist",
+    "pool",
+    "index.d.ts",
+    "report.d.ts",
+    "schema.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.9"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "pdf-lib": "1.17.1",
+    "@pdf-lib/fontkit": "1.1.1",
+    "bwip-js": "4.11.4",
+    "fflate": "0.8.3",
+    "bidi-js": "1.0.3"
+  },
+  "peerDependencies": {
+    "@reportwright/fonts": "0.11.0"
+  },
+  "peerDependenciesMeta": {
+    "@reportwright/fonts": {
+      "optional": true
+    }
+  }
+}

package/pool/index.d.ts

@@ -0,0 +1,23 @@
+// @reportwright/engine/pool (Node only): render many reports in parallel on worker threads.
+import type { Report } from '../report.js';
+export interface PoolRenderOptions {
+  /** default pdf */
+  format?: 'pdf' | 'xlsx' | 'docx' | 'pptx' | 'csv' | 'html';
+  parameters?: Record<string, unknown>;
+  timeZone?: string;
+  timeoutMs?: number;
+  /** passed to the exporter: exportPdf's title, pdfa, … */
+  options?: Record<string, unknown>;
+}
+export interface Pool {
+  /** the file's bytes */
+  render(definition: Report | object, opts?: PoolRenderOptions): Promise<Uint8Array>;
+  /** stops the workers; renders still waiting are rejected */
+  close(): Promise<void>;
+  readonly size: number;
+  /** renders waiting or running */
+  readonly pending: number;
+}
+/** workers: default the CPU count less one. fontsDir: a folder of the fonts (default @reportwright/fonts).
+ *  heapMB: each worker's heap limit (default 1024). timeoutMs: stop a render past it with status 504 (default 0: no limit). */
+export function createPool(opt?: { workers?: number; fontsDir?: string; maxQueue?: number; heapMB?: number; timeoutMs?: number }): Pool;

package/pool/index.js

@@ -0,0 +1,85 @@
+// @reportwright/engine/pool (Node only): render many reports in parallel on worker threads.
+//   const pool = createPool({ workers: 4 });
+//   const pdf = await pool.render(definition, { format: 'pdf', parameters: { id: 42 } });
+//   await pool.close();
+import { Worker } from 'node:worker_threads';
+import os from 'node:os';
+
+/**
+ * @typedef {{ format?: 'pdf' | 'xlsx' | 'docx' | 'pptx' | 'csv' | 'html', parameters?: Record<string, unknown>,
+ *   timeZone?: string, timeoutMs?: number, options?: Record<string, unknown> }} PoolRenderOptions
+ *   options: passed to the exporter (exportPdf's title, pdfa, …)
+ * @typedef {{ render: (definition: object, opts?: PoolRenderOptions) => Promise<Uint8Array>, close: () => Promise<void>, readonly size: number, readonly pending: number }} Pool
+ */
+
+/**
+ * A pool of worker threads, each with the engine and its fonts loaded once.
+ * @param {{ workers?: number, fontsDir?: string, maxQueue?: number, heapMB?: number, timeoutMs?: number }} [opt]
+ *   workers: default the CPU count less one. fontsDir: a folder of the fonts (default @reportwright/fonts).
+ *   maxQueue: renders waiting beyond it are refused (default 10,000).
+ *   heapMB: each worker's heap limit (default 1024): a render past it fails alone (its worker is replaced), instead of
+ *   taking the whole process down. timeoutMs: a render running longer is stopped (status 504) and its worker replaced
+ *   (default: no limit; the engine's own opts.timeoutMs per render is checked between rows, this one always holds).
+ * @returns {Pool}
+ */
+export function createPool({ workers = Math.max(1, (os.availableParallelism?.() ?? os.cpus().length) - 1), fontsDir, maxQueue = 10000, heapMB = 1024, timeoutMs = 0 } = {}) {
+  if (!Number.isInteger(workers) || workers < 1) throw new TypeError('createPool({ workers }): workers must be a whole number of at least 1');
+  if (!Number.isFinite(heapMB) || heapMB < 32) throw new TypeError('createPool({ heapMB }): heapMB must be a number of at least 32');
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new TypeError('createPool({ timeoutMs }): timeoutMs must be 0 (no limit) or more');
+  /** @type {{ def: object, opts: PoolRenderOptions, resolve: (b: Uint8Array) => void, reject: (e: Error) => void }[]} */
+  const queue = [];
+  /** @type {Set<Worker>} */
+  const idle = new Set();
+  /** @type {Map<Worker, (typeof queue)[number]>} */
+  const busy = new Map();
+  /** @type {Map<Worker, any>} */
+  const timers = new Map();
+  let closed = false;
+  const done = (w) => { clearTimeout(timers.get(w)); timers.delete(w); const job = busy.get(w); busy.delete(w); return job; };
+  const spawn = () => {
+    const w = new Worker(new URL('./worker.js', import.meta.url), { workerData: { fontsDir }, resourceLimits: { maxOldGenerationSizeMb: heapMB } });
+    w.on('message', (msg) => {
+      const job = done(w);
+      if (job) msg.error ? job.reject(Object.assign(new Error(msg.error.message), msg.error)) : job.resolve(new Uint8Array(msg.bytes));
+      idle.add(w);
+      next();
+    });
+    w.on('error', (e) => {
+      const oom = /** @type {any} */ (e)?.code === 'ERR_WORKER_OUT_OF_MEMORY';
+      done(w)?.reject(oom ? Object.assign(new Error(`the render ran out of memory (heapMB: ${heapMB}) and was stopped`), { status: 500, code: e.code }) : e);
+    });
+    w.on('exit', () => {
+      idle.delete(w);
+      done(w)?.reject(new Error('the render worker stopped'));
+      if (!closed) { idle.add(spawn()); next(); } // a crashed worker is replaced
+    });
+    return w;
+  };
+  const next = () => {
+    while (queue.length && idle.size) {
+      const w = /** @type {Worker} */ (idle.values().next().value);
+      idle.delete(w);
+      const job = /** @type {(typeof queue)[number]} */ (queue.shift());
+      busy.set(w, job);
+      // past the time limit the worker is stopped (a render in a long synchronous step cannot be interrupted otherwise)
+      if (timeoutMs > 0) timers.set(w, setTimeout(() => { done(w)?.reject(Object.assign(new Error(`the render ran longer than ${timeoutMs} ms and was stopped`), { status: 504 })); w.terminate(); }, timeoutMs));
+      w.postMessage({ def: job.def, opts: job.opts });
+    }
+  };
+  for (let i = 0; i < workers; i++) idle.add(spawn());
+  return {
+    get size() { return workers; },
+    get pending() { return queue.length + busy.size; },
+    render(def, opts = {}) {
+      if (closed) return Promise.reject(new Error('the pool is closed'));
+      if (!def || typeof def !== 'object') return Promise.reject(new TypeError('pool.render(definition, opts): definition must be a report object'));
+      if (queue.length >= maxQueue) return Promise.reject(new Error(`the pool queue is full (${maxQueue} renders waiting)`));
+      return new Promise((resolve, reject) => { queue.push({ def, opts, resolve, reject }); next(); });
+    },
+    async close() {
+      closed = true;
+      for (const job of queue.splice(0)) job.reject(new Error('the pool is closed'));
+      await Promise.all([...idle, ...busy.keys()].map(w => w.terminate()));
+    },
+  };
+}

package/pool/worker.js

@@ -0,0 +1,27 @@
+// One render thread of @reportwright/engine/pool: the engine and the fonts load once, then one job at a time.
+import { parentPort, workerData } from 'node:worker_threads';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { render, FontStore, fontFile, defaultFontStore, exportPdf, exportXlsx, exportDocx, exportPptx, exportHtml, exportCsv, needsExportData } from '@reportwright/engine';
+
+const fonts = workerData?.fontsDir ? new FontStore((key) => fs.readFile(path.join(workerData.fontsDir, fontFile(key)))) : defaultFontStore();
+const EXPORT = {
+  pdf: (m, o) => exportPdf(m, { fonts, ...o }),
+  xlsx: (m, o) => exportXlsx(m, { fonts, ...o }),
+  docx: (m, o) => exportDocx(m, { fonts, ...o }),
+  pptx: (m, o) => exportPptx(m, { fonts, ...o }),
+  html: async (m, o) => new TextEncoder().encode(await exportHtml(m, fonts, o)),
+  csv: async (m, o) => new TextEncoder().encode(exportCsv(m, o)),
+};
+/** @type {import('node:worker_threads').MessagePort} */ (parentPort).on('message', async ({ def, opts }) => {
+  try {
+    const format = opts.format || 'pdf';
+    if (!EXPORT[format]) throw new Error(`unknown format "${format}" (pdf, xlsx, docx, pptx, html, csv)`);
+    const model = await render(def, { fontStore: fonts, parameters: opts.parameters, timeZone: opts.timeZone, timeoutMs: opts.timeoutMs, exportData: needsExportData(format, opts.options) });
+    const bytes = await EXPORT[format](model, opts.options || {});
+    const buf = bytes.buffer.byteLength === bytes.byteLength ? bytes.buffer : bytes.slice().buffer;
+    parentPort?.postMessage({ bytes: buf }, [buf]);
+  } catch (e) {
+    parentPort?.postMessage({ error: { message: String(e?.message || e), status: e?.status } });
+  }
+});