jsTableBuilder: Developer Internals

This document outlines the internal architecture, design patterns, and coding conventions used within the jsTableBuilder library. It is intended for contributors and maintainers.

Architecture Overview

The library is split into two primary layers:

1. External API Layer (TableBuilder.js): A class-based wrapper that exposes a clean, user-friendly API. It manages state (like sorting and the original/processed data array) and handles DOM injection.
2. Internal Functional Layer (buildTable/): A set of pure and side-effect-managed functions responsible for rendering individual HTML elements (headers, body rows, footer).

Naming Convention (The "in" & "local" Pattern)

To enforce strict boundary checks and avoid unintended mutation of parameters, the internal functions strictly adhere to the following naming convention:

• Parameters Object: All internal functions accept a single object as their argument.
• in Prefix: Every property destructured from the argument object must be prefixed with in (e.g., inData, inColumns, inClasses).
• local Prefix: Inside the function body, these properties must immediately be assigned to variables prefixed with local (e.g., const localData = inData;).

// Example of the standard convention
function buildTableHeader({ inColumns, inClasses }) {
    const localColumns = inColumns;
    const localClasses = inClasses;
    // ...
}

Directory Structure (buildTable/)

The internal renderer is split modularly:

• index.js: The main entry point for the functional table builder. Aggregates all parts (head, body, empty state).
• forHead/: Contains logic for rendering the <thead>, including sorting icons and column labels.
• forBody/: Contains logic for rendering the <tbody> and iterating over data rows.
• forSummary/: Contains logic for rendering the <tfoot>, which can sum up column data.
• utils/: Contains reusable utilities for DOM manipulation (appendToDom.js), data processing (sortUtils.js, searchUtils.js, prepareDataAndColumns.js), and config extraction.
• config/: Stores the default classes and configuration defaults.

Data Flow

1. Initialization: User calls new TableBuilder(config). The config is mapped to the strict internal representation using config mappers (like mapTableOptions).
2. Preparation: prepareDataAndColumns runs. If serial numbers are enabled, it injects a new column definition and modifies the data to include the index.
3. Rendering: When appendToDom() is called, buildTableElements() triggers the functional pipeline (buildTable -> buildTableHeader, buildTableBody, etc.), returning standard DOM nodes.
4. Injection: The constructed DOM nodes are appended to the user-specified htmlId container.
5. Interactivity: Sorting and searching invoke methods on the TableBuilder instance, which recalculates the data array and rebuilds the DOM.