fact-matcher-parser

Parse and serialize XBRL fact-match strings — prefix:name=value pairs joined by ;, used to identify and filter XBRL facts.

Install

npm install fact-matcher-parser

Requires Node ≥ 18. ESM only.

Usage

import { parse, serialize, tryParse, ParseError } from 'fact-matcher-parser';

String → Map

parse('xbrl:concept=us-gaap:Assets;xbrl:unit=iso:USD;xbrl:decimals=3');
// Map(3) {
//   'xbrl:concept'  => 'us-gaap:Assets',  // SQName  → string
//   'xbrl:unit'     => 'iso:USD',          // SQName  → string
//   'xbrl:decimals' => 3,                   // Number  → number
// }

parse returns a Map<string, string | number> preserving insertion order. Quoted values support ;, =, spaces, and \" / \\ escapes — useful for human-readable labels that contain XBRL-significant characters:

parse('xbrl:label="Cash, cash equivalents; restricted cash"').get('xbrl:label');
// 'Cash, cash equivalents; restricted cash'

parse('xbrl:label="Total \\"current\\" assets"').get('xbrl:label');
// 'Total "current" assets'

Map → String (canonical, round-trip safe)

serialize(new Map([
  ['xbrl:concept', 'us-gaap:Revenues'],
  ['xbrl:unit', 'iso:EUR'],
  ['xbrl:period', '2024-Q4'],
]));
// 'xbrl:concept=us-gaap:Revenues;xbrl:unit=iso:EUR;xbrl:period=2024-Q4'

serialize emits SQName-shaped strings and numbers bare; other strings are wrapped in "..." with " and \ escaped. Entries joined by ;. No trailing ;. Empty map → "".

Error handling

const result = tryParse('xbrl:concept=');
if (!result.ok) {
  console.error(result.error.message, result.error.line, result.error.column);
}

parse throws ParseError (with line, column, offset) on invalid input. Use tryParse to get a result object instead of a thrown error.

Invalid input

• Empty input
• Missing = (xbrl:concept)
• Empty value (xbrl:concept=)
• Key that is not an SQName (xbrl=us-gaap:Assets, xbrl:=us-gaap:Assets)
• Identifier starting with a digit (1xbrl:concept=us-gaap:Assets)
• Duplicate keys (xbrl:concept=us-gaap:Assets;xbrl:concept=us-gaap:Revenues)
• Unterminated quoted value (xbrl:label="Cash and)
• ;; or bare ;

Trailing ; is allowed. Whitespace around = and ; is tolerated (but not inside an SQName).

API

type FactMatchMap = Map<string, string | number>;

function parse(input: string): FactMatchMap;
function serialize(map: FactMatchMap): string;
function tryParse(input: string):
  | { ok: true; value: FactMatchMap }
  | { ok: false; error: ParseError };

class ParseError extends Error {
  readonly line: number;
  readonly column: number;
  readonly offset: number;
}

Notes

Numbers are JavaScript Number — values above 2^53 − 1 lose precision. Wrap large integers in quotes (e.g. xbrl:contextRef="ctx-99999999999999999999") to keep them as strings.

License

MIT