Skip to content
Tutorials Center
My learning

Topics

Lesson 129 of 133 ยท Projects

Project: Document and Report Generator

Build a report generator in Node.js. Parse CSV, summarize data, render HTML with an SVG chart, export safe CSV, write a valid PDF by hand and stream huge reports with constant memory.

Sooner or later every business application is asked for "a report": monthly sales as a PDF for the boss, an invoice for a customer, a spreadsheet export for accounting, a printable certificate. The input is data (rows from a database or a CSV file) and the output is a document in a specific format. Doing this well means solving four problems that have little to do with each other: turning raw rows into useful numbers, rendering the same content in several formats safely, writing a binary format such as PDF correctly, and producing very large documents without running out of memory.

In this project you build a small report generator that does all four with nothing but Node's standard library. You will parse CSV and summarize it, render HTML with an inline SVG chart, export CSV that is safe to open in a spreadsheet, write a PDF file by hand (it is a lot simpler than its reputation), and stream a 200,000-row report through compression with flat memory use. In real projects you would often reach for libraries such as pdfkit, exceljs, csv-stringify or a headless browser; building the pieces once teaches you what they do and how to judge them.

Plan

  1. Data: a CSV parser that handles quotes, then grouping and totals.
  2. Renderers: one report object, rendered to Markdown, HTML (with a chart) and CSV.
  3. PDF: a tiny writer for text pages with a correct cross-reference table.
  4. Streaming: generate, format, compress and deliver a huge report with back-pressure.

Stage 1: from CSV text to numbers

Reports usually start with a CSV export. The format looks trivial and is not: fields can be quoted, quoted fields can contain commas, quotes (written twice) and even line breaks. Splitting on commas is the classic bug. A small state machine handles it. We then convert strings to numbers explicitly, because CSV has no types, and compute totals. For money, work in integer cents: summing 0.1 + 0.2 as floating-point numbers produces 0.30000000000000004 in front of a customer.

Node.js Parse quoted CSV, then group and total in integer cents

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The parser kept Widget, large as one field, turned ""Pro"" into "Pro", and survived a quoted field that spans two lines. Money is parsed strictly: 12,50 is rejected instead of being guessed at. Intl formatting (Intl.NumberFormat) takes care of currency symbols and separators for each locale; see Internationalization. For production-size files use a streaming parser so the whole file is not read into memory (stage 4 shows the pattern), or a tested library.

Stage 2: one report, three renderers

A good design separates what the report says from how it looks. The report is plain data: a title, a period, a table of rows and a total. Each renderer is a function that turns it into one format. Adding a new format later means writing one more function, not touching the data code.

Two rules protect the people who open your documents:

  • HTML must escape every value. A product named <img src=x onerror=...> must show as text. We use a small esc() helper for every cell and attribute. Never build HTML by concatenating unescaped input (Web Security).
  • CSV exports must defuse spreadsheet formulas. Excel and Sheets treat a cell that starts with =, +, - or @ as a formula, so a "name" like =HYPERLINK("http://evil",...) from user input becomes an attack when the accountant opens your export (CSV injection). The accepted fix is to prefix such cells with a single quote ', in addition to the normal CSV quoting rules.

The chart needs no library either. An SVG is just text: a rectangle per bar, scaled to the largest value. Inline SVG scales without blur, prints well and can be embedded in HTML directly.

Node.js Render one report as Markdown, HTML with an SVG chart, and safe CSV

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check the details in the output. The <Q1 2026> in the title appears escaped in the HTML (and in the Markdown it is data, which a Markdown renderer must escape in turn). The hostile region name in the last row is written to the CSV with a leading ' and, because it contains quotes and a comma, wrapped in quotes with the inner quotes doubled. Real numbers such as -12.50 are not mangled, because the check Number.isNaN(Number(text)) leaves valid numbers alone. Line endings in CSV are \r\n by the RFC, which every spreadsheet reads.

To turn the HTML report into a PDF you can open it in a headless browser (Puppeteer or Playwright) and call page.pdf(). That gives you the best layout support, because the browser's print engine does the typesetting. It needs a browser binary on the server and a few hundred megabytes of memory per run, so queue the jobs (Job Queue project). The alternative, writing PDF directly, is lighter and is what the next stage does.

Stage 3: writing a PDF by hand

A PDF file is less mysterious than it looks. It is a list of numbered objects written as text, followed by a cross-reference table (xref) that lists the byte offset of every object, and a trailer that says where the table starts. The reader jumps to the end, finds startxref, reads the table and can then fetch any object at once. The only hard rule: the offsets must be exact byte positions, so you count bytes, not characters.

The objects we need for a document of text pages are:

  1. the catalog (the root), pointing to the page tree;
  2. the pages object, listing all page objects;
  3. a font object (Helvetica is one of 14 standard fonts that every reader has, so nothing is embedded);
  4. for each page, a page object and a content stream with drawing commands: BT (begin text), /F1 11 Tf (font and size), 72 760 Td (move to x, y in points, with the origin at the bottom left), (text) Tj (show text), ET.

Text inside ( ... ) must escape backslashes and parentheses. The standard fonts only cover Latin-1 characters through simple encodings, so for this project we replace characters outside Latin-1 with ?. Full Unicode support needs embedded fonts, which is where libraries like pdfkit earn their keep.

Node.js A hand-written, multi-page PDF with a verified xref table

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The verification at the bottom does what a PDF reader does first: it reads startxref, jumps to the table and checks each offset. If an offset is off by even one byte, readers show "the file is damaged" (some try to repair it by scanning, which hides the bug on your machine and breaks on someone else's). To look at the result, write the buffer to disk and open it: await fs.writeFile('report.pdf', pdf). In an HTTP handler send it with Content-Type: application/pdf and Content-Disposition: attachment; filename="report.pdf".

This writer is deliberately minimal: no images, no tables with borders, no non-Latin text. For invoices with logos, fonts and layouts, use pdfkit (programmatic drawing) or a browser-based renderer (HTML and CSS layout), and keep this stage in mind as the explanation of what they emit.

Stage 4: streaming a huge report

So far every document fit in memory. A "give me all orders since 2015" export can have millions of rows. If you build the whole CSV as one string, the process grows by hundreds of megabytes and the first byte reaches the user only at the end. Streams fix both problems: generate rows lazily, format them as they pass, compress them on the fly and write them to the destination, while back-pressure makes the generator wait whenever the destination is slow (Pipeline and Backpressure).

The building blocks:

  • an async generator that yields batches of rows (in real life it reads a database cursor in batches);
  • Readable.from(generator) to turn it into a stream;
  • a Transform that formats each batch as CSV lines, with the header first;
  • zlib.createGzip() to compress (CSV compresses very well, often 5-10x);
  • pipeline to connect everything and clean up on errors.
Node.js 200,000 rows through CSV formatting and gzip with flat memory

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The whole export of roughly five megabytes of CSV passed through the pipeline in small chunks, and the heap did not grow with the size of the report. Change ROWS to ten million and the memory use would be the same; only the running time changes. If the destination is a slow network client, pipeline pauses the generator automatically, so a slow download never turns into a memory problem on your side.

In an HTTP server the sink is the response. Set Content-Type: text/csv; charset=utf-8, Content-Disposition: attachment; filename="orders.csv.gz", Content-Encoding: gzip (if the browser should decompress transparently) and do not set Content-Length, because you do not know the size in advance; Node then uses chunked transfer encoding. If the client disconnects, pipeline destroys the whole chain, so the database cursor is closed and no CPU is wasted on a report nobody will read. For reports that take minutes, do not hold a request open at all: create the file in a background job, store it, and email a download link (File Sharing project).

Putting it together

A report service built from these parts looks like this:

  1. GET /reports/sales?from=...&to=...&format=pdf|html|csv validates the dates and the format against a whitelist.
  2. A data function (summarize, a database query) returns the report object.
  3. The renderer for the requested format turns it into the response. Small formats are built in memory; big ones stream.
  4. Headers follow the format: correct Content-Type, Content-Disposition with a safe file name (see the File Sharing project for how to sanitize one) and Cache-Control: private, because reports contain business data.
  5. Heavy or slow reports run as jobs (Job Queue project) and notify the user when ready (Notification project).

Test the renderers with fixed data and compare to expected output (snapshot tests are a good fit, see Mocking and Timers and the Node Test Runner), including hostile input such as <script>, quotes, =cmd and non-Latin names.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why can't you parse CSV by splitting each line on commas?

    A field such as "Widget, large" contains a comma that is data, and a quoted field can span several lines. A small state machine that tracks whether it is inside quotes handles all of that.
  2. 2. Why should money be stored and summed as integer cents?

    Binary floating point rounds many decimal values. With integer cents the arithmetic is exact, and you format to dollars only when you display.
  3. 3. What is CSV injection and how do you defuse it?

    Spreadsheets treat such cells as formulas, so user-controlled text can run commands or leak data. Prefixing the cell with a quote makes it plain text.
  4. 4. Why must the byte offsets in a PDF's xref table be exact?

    The reader finds startxref at the end, reads the table and seeks to each object by offset. Count bytes, not characters, when writing them.
  5. 5. What keeps memory flat when a 10-million-row export is piped through pipeline()?

    Nothing holds the whole report. Each chunk flows through the stages and is released. Back-pressure prevents a fast producer from filling memory when the consumer is slow.

Summary

  • Parse CSV with a quote-aware state machine, type your fields explicitly and keep money in integer cents.
  • Describe a report as data, then write one small renderer per format; escape every value in HTML and defuse formula-looking cells in CSV.
  • Inline SVG gives you charts without libraries; a PDF is numbered objects plus an exact-offset cross-reference table, and standard fonts avoid embedding.
  • Stream large exports with an async generator, Readable.from, Transform, gzip and pipeline: memory stays flat and the first bytes arrive immediately.
  • Pick the right tool for the job: hand-written output for simple, predictable documents; libraries (pdfkit, exceljs) or a headless browser when you need rich layout, fonts and images.

Next: Cheat Sheet