xbrl

xbrl is a TypeScript library for parsing XBRL 2.1 instance documents into typed JavaScript objects. It focuses on practical extraction of reporting data such as contexts, units, facts, schema references, and footnotes.

The library is designed for application code that needs a dependable parser rather than a full validation pipeline. It resolves QNames, preserves reported values as strings, represents tuples recursively, and returns null instead of throwing when the input is empty, malformed, or not an XBRL instance document.

Installation

npm install xbrl

Usage

import { parseXbrl } from "xbrl";
import { readFileSync } from "node:fs";

const xml = readFileSync("filing.xbrl", "utf-8");
const instance = parseXbrl(xml);

if (instance) {
    // Schema references
    for (const ref of instance.schemaRefs) {
        console.log(`Taxonomy: ${ref.href}`);
    }

    // Contexts
    for (const [id, ctx] of Object.entries(instance.contexts)) {
        console.log(`Context ${id}: ${ctx.entity.value} (${ctx.period.type})`);
    }

    // Units
    for (const [id, unit] of Object.entries(instance.units)) {
        const label = unit.measures?.map((m) => m.localName).join("*")
            ?? `${unit.divide?.numerator.map((m) => m.localName).join("*")}/${unit.divide?.denominator.map((m) => m.localName).join("*")}`;
        console.log(`Unit ${id}: ${label}`);
    }

    // Facts (recursive traversal)
    function printFacts(facts: typeof instance.facts, indent = "") {
        for (const fact of facts) {
            if (fact.type === "item") {
                console.log(`${indent}${fact.name.localName} = ${fact.value} [${fact.contextRef}]`);
            } else {
                console.log(`${indent}${fact.name.localName} (tuple)`);
                printFacts(fact.children, indent + "  ");
            }
        }
    }
    printFacts(instance.facts);
}

What The Library Parses

• Contexts, including entity identifiers, periods, segments, and scenarios
• Units, including simple and divide units with resolved measure QNames
• Facts as typed items and tuples
• Schema, linkbase, role, and arcrole references
• Footnote links, locators, resources, and arcs
• Namespace declarations from the root instance element

Design Notes

• parseXbrl(xml) returns an XbrlInstance or null
• Element and measure names are resolved into { namespace, localName, prefix }
• Fact values stay as strings so callers can apply their own numeric and precision rules
• Contexts and units are indexed by ID for direct lookup from fact references
• Segment and scenario dimensions are parsed into structured members when possible

API Reference

Detailed API documentation lives in docs/api_reference.md.

Development

npm test          # run tests in watch mode
npm run test:run  # run tests once
npm run lint      # eslint
npm run format    # prettier
npm run build     # build to dist/
npm run ci        # type-check + lint + test + build

License

MIT