Zaravand Report Print Engine

Schema-driven table report PDF and print engine by Zaravand for JavaScript and TypeScript applications.

The package receives two inputs:

data + schema -> Report Engine -> print-friendly HTML

Operation outputs:

• printPdf: opens browser print dialog from the print-friendly HTML layout.
• openPdf: opens the same print-friendly HTML layout inside a preview viewer in a new browser tab.
• downloadPdf: downloads the print-friendly HTML file.
• generatePdf / generatePdfDataUrl: create direct PDF output.

It is designed for invoices, sales reports, inventory lists, financial reports, administrative reports, contracts, forms, and other table-heavy documents.

Installation

npm install @zaravandcodeteam/report-print-engine

Basic Usage

import { createReportEngine, type ReportDataRow, type ReportSchema } from "@zaravandcodeteam/report-print-engine"

const data: ReportDataRow[] = [
  { product: "Laptop", quantity: 1, unitPrice: 1200, total: 1200 },
  { product: "Mouse", quantity: 2, unitPrice: 25, total: 50 },
]

const schema: ReportSchema = {
  title: "Invoice Report",
  subtitle: "Generated by Report Print Engine",
  page: { size: "A4", orientation: "portrait", margins: [40, 40, 40, 40] },
  options: { direction: "ltr", locale: "en-US", currency: "USD" },
  tables: [
    {
      header: {
        title: "Invoice Items",
        subtitle: "Products and services",
        showGeneratedAt: true,
        fields: [
          { label: "Invoice No", value: "INV-1001" },
          { label: "Customer", value: "Customer" },
        ],
      },
      options: { showRowNumber: true, repeatHeader: true, emptyValue: "-" },
      columns: [
        { key: "product", title: "Product", width: 40, type: "text" },
        { key: "quantity", title: "Qty", width: 20, type: "number", align: "right" },
        { key: "unitPrice", title: "Unit Price", width: 20, type: "currency", align: "right" },
        { key: "total", title: "Total", width: 20, type: "currency", align: "right", bold: true },
      ],
    },
  ],
}

const engine = createReportEngine()
await engine.downloadPdf(data, schema, { fileName: "invoice.html" })

Schema-driven Approach

Users pass records and a JSON schema that defines page settings, tables, table headers, columns, formatting, and behavior.

Table Header Example

{
  "header": {
    "title": "Invoice Items",
    "subtitle": "Products and services",
    "description": "This table contains all invoice line items.",
    "showGeneratedAt": true,
    "fields": [
      { "label": "Invoice No", "value": "INV-1001" },
      { "label": "Customer", "value": "Ali Ahmadi" }
    ]
  }
}

The table header appears above the table body. It is separate from the column header row.

Multi-table Example

const data = {
  summary: [{ metric: "Total Sales", value: 6840 }],
  sales: [{ invoiceNo: "INV-1001", amount: 2400 }],
  payments: [{ receiptNo: "PAY-8001", amount: 2400 }],
}

const schema = {
  title: "Business Report",
  tables: [
    { dataKey: "summary", header: { title: "Summary" }, columns: [{ key: "metric", title: "Metric" }] },
    { dataKey: "sales", header: { title: "Sales" }, columns: [{ key: "invoiceNo", title: "Invoice No" }] },
    { dataKey: "payments", header: { title: "Payments" }, columns: [{ key: "receiptNo", title: "Receipt No" }] },
  ],
}

Common Operations

const blob = await engine.generatePdf(data, schema)
const dataUrl = await engine.generatePdfDataUrl(data, schema)
await engine.downloadPdf(data, schema, { fileName: "report.html" })
await engine.openPdf(data, schema)
await engine.printPdf(data, schema)

Documentation

Run the documentation site:

npm run docs:dev

For npm publishing and consumer usage, see the one-page Publishing and Usage checklist.

Publishing

Before publishing, run:

npm run typecheck
npm run build
npm pack --dry-run

Then publish the scoped public package:

npm login
npm publish --access public

Performance Notes

The default renderer is built into the package and does not launch a heavy browser process. This keeps common table reports lightweight and schema-driven. Very large reports should be paginated, chunked, or moved to a worker/server renderer in future adapter implementations.

The bundled renderer includes print-friendly table colors and prepares Persian/Arabic text for stable RTL output in PDF tables.

Browser Printing Limitations

Browsers do not allow reliable silent printing from normal web pages. The package can trigger the browser print dialog, but the user or browser policy controls the final print action.

Roadmap

Planned areas include a native print agent, server-side renderer, Chromium renderer adapter, visual template designer, RTL and custom font improvements, Excel/CSV export, branding, page headers and footers, page numbers, and watermarks.