Copy page

Backend

Export Library

Export Library

Relevant source files

The following files were used as context for generating this wiki page:

• src/i18n/en-GB.json
• src/i18n/it-IT.json
• src/lib/export/README.md
• src/lib/export/example.ts
• src/lib/export/helpers.ts
• src/lib/export/index.ts
• src/lib/export/types.ts
• templates/customer_export_template.html
• templates/customer_export_template.xlsx
• templates/customer_export_template_2.xlsx

The Export Library is a template-based streaming system designed to generate high-volume XLSX and CSV files with constant memory usage src/lib/export/README.md:3-7. It supports locale-aware formatting, timezone conversions, and dynamic field mapping through a declarative configuration src/lib/export/README.md:9-12.

System Architecture

The library operates in two distinct phases to ensure performance and layout fidelity. It leverages ExcelJS for spreadsheet manipulation and Handlebars for HTML-based exports src/lib/export/index.ts:1-5.

Data Flow and Processing

1. Template Scanning: The system reads the provided .xlsx template to identify placeholders and capture styles src/lib/export/index.ts:131-150.
2. Streaming Generation: It initializes ExcelJS.stream.xlsx.WorkbookWriter to process data row-by-row, ensuring the server does not buffer large datasets in RAM src/lib/export/index.ts:200-205.

Logic Entity Bridge: Export Components

The following diagram maps the logical export concepts to the specific TypeScript entities and interfaces defined in the codebase.

Code
graph TD
    subgraph "Natural Language Space"
        Template["Excel Template (.xlsx)"]
        Locale["Locale (e.g., it-IT)"]
        DataStream["Data Source"]
        Config["Export Settings"]
    end

    subgraph "Code Entity Space"
        ExportConfig["interface ExportConfig"]
        ExportMetadata["interface ExportFieldMetadata"]
        HelperFuncs["helpers.ts (Intl Formatting)"]
        MainFunc["exportDataWithTemplate()"]
    end

    Template --> MainFunc
    Config --> ExportConfig
    Locale --> HelperFuncs
    DataStream --> ExportConfig
    ExportConfig --> MainFunc
    ExportMetadata --> ExportConfig

Sources: src/lib/export/types.ts:7-37, src/lib/export/index.ts:111-124, src/lib/export/helpers.ts:1-3

Placeholder Syntax

The library uses a specific placeholder syntax within Excel templates to define where data and translations should be injected.

Syntax	Type	Description	Example
{?field}	Scalar	Injects a single value from translations or static data. Used for headers/titles.	{?report_title} src/lib/export/README.md:16-24
{#field}	Loop	Defines a vertical data loop. The row containing this tag becomes the template for all data rows.	{#first_name} src/lib/export/README.md:26-34

Template Pre-processing

For HTML exports, the library converts these custom tags into standard Handlebars syntax using regex src/lib/export/index.ts:34-43.

• {#field} becomes {{field}}
• {?field} becomes {{field}}

Locale-Aware Formatting

The library uses the Intl API to dynamically generate Excel format patterns and HTML strings based on the user's locale src/lib/export/helpers.ts:5-10.

Supported Field Types

The ExportFieldMetadata interface defines how fields are processed src/lib/export/types.ts:7-12:

• string: Plain text.
• number: Numeric values with configurable precision src/lib/export/helpers.ts:45-49.
• date / datetime: Formatted using locale patterns (e.g., dd/mm/yyyy). Supports IANA timezones via timezoneField src/lib/export/helpers.ts:10-38.
• currency: Automatically places currency symbols based on locale and ISO codes (e.g., € vs $) src/lib/export/helpers.ts:58-74.
• percentage: Multiplies by 100 and appends % src/lib/export/helpers.ts:81-84.

Sources: src/lib/export/types.ts:7-12, src/lib/export/helpers.ts:1-214

Implementation Details

Execution Flow: exportDataWithTemplate

This function is the primary entry point for the export system src/lib/export/index.ts:111-115.

Code
sequenceDiagram
    participant App as Caller
    participant Lib as exportDataWithTemplate
    participant Tpl as Template Scanner
    participant Writer as WorkbookWriter (Stream)

    App->>Lib: Call with TemplatePath, OutputPaths, Config
    Lib->>Lib: loadTranslations(locale)
    Lib->>Tpl: readFile(templatePath)
    Tpl-->>Lib: Identify dataStartRow & colMapping
    Lib->>Writer: Initialize XLSX & CSV Streams
    loop For each record in config.data
        Lib->>Lib: applyTimezone() & format values
        Lib->>Writer: writeRow(formattedData)
    end
    Lib->>Writer: commit()
    Lib-->>App: Export Complete

Sources: src/lib/export/index.ts:111-209, src/lib/export/helpers.ts:93-112

Field Mapping

The fieldMapping object allows decoupling the template's placeholder names from the actual database/JSON property names src/lib/export/index.ts:67-69.

• Example: Mapping codice_cliente in the template to the id property in the data source src/lib/export/example.ts:45-46.

Timezone Handling

1. If a field has a timezoneField defined in metadata, the library uses the value from that specific record src/lib/export/example.ts:63-67.
2. Otherwise, it falls back to the defaultTimezone provided in the ExportConfig src/lib/export/helpers.ts:93-95.

Customer Export Templates

The system includes pre-defined templates for customer data:

• Excel: templates/customer_export_template.xlsx templates/customer_export_template.xlsx:1
• HTML/PDF: templates/customer_export_template.html. This template uses a CSS-heavy approach to ensure A4 print compatibility and styled table headers (#2B4C7E) templates/customer_export_template.html:2-68. It iterates through {{#each data}} to populate rows templates/customer_export_template.html:80-87.

Sources: src/lib/export/index.ts:1-210, src/lib/export/types.ts:1-48, src/lib/export/helpers.ts:1-215, templates/customer_export_template.html:1-88

---