# naturalintelligence/fast-xml-parser architecture

> Architecture diagram of the GitHub repository naturalintelligence/fast-xml-parser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naturalintelligence/fast-xml-parser
- Repository: https://github.com/naturalintelligence/fast-xml-parser

## Overview

##### Project Type and Purpose
- This is an open-source JavaScript library/tool (“fast-xml-parser”) providing:
– XML validation, parsing (XML→JS), and building (JS→XML)
– Multiple module targets: CommonJS, ESM, browser bundle
– A CLI wrapper for command-line usage
- It ships with benchmarks, specs (tests), docs, and demo assets.

##### File Structure
Top-level directories/files:
- src/
– core parsing modules (xmlparser/, xmlbuilder/, util.js, validator.js)
– v6/ experimental rewrite (parser, builders, value parsers)
– cli/ (cli.js, read.js, man.js)
– type declarations (fxp.d.ts)
- lib/ transpiled outputs (.cjs, .d.cts)
- spec/ automated tests (unit, asset-based)
- benchmark/ performance scripts (XmlParser.mjs, XmlBuilder.mjs, try.mjs)
- docs/ user-facing documentation (v3/v4/v6 guides, images)
- static/ static demo (html, css, js)
- webpack.cjs.config.js & config files for build (babel, eslint, prettier)

##### README for Insights
- Describes the three core features (Validator, Parser, Builder) and CLI
- Targets Node.js, the browser, and direct CLI usage
- Mentions versioning strategy (v4/v5 stable, v6 experimental)
- Lists bundle sizes and usage examples

##### Main Components & Their Relationships

A. Core Library Modules
1. XMLValidator
2. XMLParser
3. XMLBuilder
4. Utilities (util.js, ignoreAttributes.js)
5. Entities & Value-parsers (in v6 folder)

B. Module Targets / Packaging
1. CommonJS (lib/fxp.cjs)
2. ESM (via package.json "module" pointing to src/fxp.js)
3. Browser bundle (fxp.min.js via webpack + static/js)

C. CLI Layer
- src/cli calls XMLParser, XMLBuilder, XMLValidator
- Exposes “fxparser” command (shebang script + man page)

D. Experimental v6 Engine
- Separate sub-package within src/v6
- Shares high-level entrypoints but different internal parsers/builders

E. Test & Benchmark Suite
- spec/ (unit-test harness invoking core APIs)
- benchmark/ (performance tests, measuring parser/builder throughput)

F. Documentation & Static Demo
- docs/ guides for v3/v4/v6
- static/ (example HTML + JS for browser demos)

G. External Environments
- Node.js runtime
- Browser runtime (via bundled script)
- npm / CLI shell

Relationships:
– Core Library → Packaging → Consumers (Node.js apps, browser, CLI)
– CLI → invokes Core Library APIs → outputs to stdout/files
– Tests & Benchmarks → import Core Library → exercise features
– Docs/static → demonstrate usage of both core and CLI

##### Key Architectural Patterns & Design Principles
- Modular Layering: separation of core parsing logic, value-parsers, output-builders
- Dual-publishing: CJS + ESM + UMD/browser bundles
- Plugin-style extensibility in v6 (valueParsers, inputSource interfaces)
- Single Responsibility: each module handles one concern (e.g. EntitiesParser vs. XMLParser)

##### Final Checklist
– Capture all essential components: Validator, Parser, Builder, CLI, Packaging, Docs, Tests
– Show how code flows from source modules to published artifacts to end users
– Highlight experimental v6 path alongside stable v4/v5
– Include environment boundaries (Node + Browser + Shell)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Modules
    subgraph "Source Modules"
        XMLValidator["XMLValidator"]:::core
        XMLParser["XMLParser"]:::core
        XMLBuilder["XMLBuilder"]:::core
        OrderedBuilder["Ordered XML Builder"]:::core
        PrettyBuilder["Pretty-print Builder"]:::core
        Util["Utilities"]:::core
        IgnoreAttributes["Attribute Ignore Utility"]:::core
        ESMEntry["ESM Entry (fxp.js)"]:::core
        TypeDecl["Type Declarations (fxp.d.ts)"]:::core
    end

    %% Experimental v6 Modules
    subgraph "Experimental v6 Modules"
        v6Parser["v6 XMLParser"]:::core
        v6Xml2Js["v6 Xml2JsParser"]:::core
        v6EntitiesParser["v6 EntitiesParser"]:::core
        v6ValueParsers["v6 value-parsers"]:::core
        v6OutputBuilders["v6 output-builders"]:::core
        v6InputSources["v6 input-source"]:::core
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution"
        CJS["CommonJS Bundle (lib/fxp.cjs)"]:::pack
        ESM["ESM Module"]:::pack
        BrowserBundle["Browser Bundle (fxp.min.js)"]:::pack
    end

    %% CLI Tools
    subgraph "CLI Tools"
        CLIEntry["CLI Entry (cli.js)"]:::cli
        CLIRead["CLI Reader (read.js)"]:::cli
        CLIMan["CLI Man Page (man.js)"]:::cli
    end

    %% Test & Benchmark
    subgraph "Test & Benchmark"
        TestSuite["Test Suite (spec/)"]:::test
        Benchmark["Benchmark Scripts"]:::test
    end

    %% Documentation & Demo
    subgraph "Docs & Demo"
        Docs["Documentation (docs/)"]:::docs
        StaticDemo["Static Browser Demo (static/)"]:::docs
    end

    %% Environments
    subgraph "Environments"
        NodeJS["Node.js Runtime"]:::env
        Browser["Browser Runtime"]:::env
        Shell["CLI Shell"]:::env
    end

    %% Relationships
    XMLValidator --> XMLParser
    XMLParser --> XMLBuilder
    XMLBuilder --> OrderedBuilder
    XMLBuilder --> PrettyBuilder
    Util --> XMLParser
    Util --> XMLBuilder
    IgnoreAttributes --> XMLParser

    XMLParser --> ESMEntry
    XMLBuilder --> ESMEntry
    ESMEntry --> ESM

    XMLParser --> CJS
    XMLBuilder --> CJS
    XMLValidator --> CJS

    ESMEntry --> CJS

    srcWebpack["webpack.cjs.config.js"]:::util --> BrowserBundle
    BrowserBundle --> Browser

    CLIRead --> CLIEntry
    CLIMan --> CLIEntry
    CLIEntry --> XMLParser
    CLIEntry --> XMLBuilder
    CLIEntry --> XMLValidator
    CLIEntry --> Shell

    TestSuite --> XMLParser
    TestSuite --> XMLBuilder
    TestSuite --> XMLValidator
    Benchmark --> XMLParser
    Benchmark --> XMLBuilder

    Docs --> XMLParser
    Docs --> XMLBuilder
    Docs --> CLIEntry
    StaticDemo --> BrowserBundle

    CJS --> NodeJS
    ESM --> NodeJS

    %% v6 flows
    v6Parser --> v6Xml2Js
    v6EntitiesParser --> v6Parser
    v6ValueParsers --> v6Parser
    v6InputSources --> v6Parser
    v6OutputBuilders --> v6Xml2Js
    v6Parser --> ESMEntry
    v6Parser --> CJS

    %% Click Events
    click XMLValidator "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/validator.js"
    click XMLParser "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/xmlparser/XMLParser.js"
    click XMLBuilder "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/xmlbuilder/json2xml.js"
    click OrderedBuilder "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/xmlbuilder/orderedJs2Xml.js"
    click PrettyBuilder "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/xmlbuilder/prettifyJs2Xml.js"
    click Util "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/util.js"
    click IgnoreAttributes "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/ignoreAttributes.js"
    click ESMEntry "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/fxp.js"
    click TypeDecl "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/fxp.d.ts"
    click CJS "https://github.com/naturalintelligence/fast-xml-parser/blob/master/lib/fxp.cjs"
    click CLIEntry "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/cli/cli.js"
    click CLIRead "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/cli/read.js"
    click CLIMan "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/cli/man.js"
    click v6Parser "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/v6/XMLParser.js"
    click v6Xml2Js "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/v6/Xml2JsParser.js"
    click v6EntitiesParser "https://github.com/naturalintelligence/fast-xml-parser/blob/master/src/v6/EntitiesParser.js"
    click v6ValueParsers "https://github.com/naturalintelligence/fast-xml-parser/tree/master/src/v6/valueParsers/"
    click v6OutputBuilders "https://github.com/naturalintelligence/fast-xml-parser/tree/master/src/v6/OutputBuilders/"
    click v6InputSources "https://github.com/naturalintelligence/fast-xml-parser/tree/master/src/v6/inputSource/"
    click TestSuite "https://github.com/naturalintelligence/fast-xml-parser/tree/master/spec/"
    click Benchmark "https://github.com/naturalintelligence/fast-xml-parser/tree/master/benchmark/"
    click Docs "https://github.com/naturalintelligence/fast-xml-parser/tree/master/docs/"
    click StaticDemo "https://github.com/naturalintelligence/fast-xml-parser/tree/master/static/"
    click srcWebpack "https://github.com/naturalintelligence/fast-xml-parser/blob/master/webpack.cjs.config.js"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef pack fill:#D0F0D8,stroke:#22863A,color:#22863A
    classDef cli fill:#FFE8D0,stroke:#D93F0B,color:#D93F0B
    classDef test fill:#F4E1FF,stroke:#6F42C1,color:#6F42C1
    classDef docs fill:#F0F0F0,stroke:#586069,color:#586069
    classDef env fill:#FFF5B1,stroke:#DBAB09,color:#735C0F
    classDef util fill:#EFEFEF,stroke:#CCCCCC,color:#333333
```
