A TypeScript GEDCOM parser for Node and the browser.
npm install @it9gamelog/gedcom-parsergedcom-parser - a TypeScript library that parse GEDCOM into tree-like objects.
``javascript
import { parseGedcomSync, IndividualNode } from "@it9gamelog/gedcom-parser";
const sample = 0 @I1@ INDI
1 NAME John /Doe/
1 BIRT
2 DATE 12 APR 1900
1 FAMS @F1@
0 @I2@ INDI
1 NAME Jane /Doe/
1 FAMS @F1@
0 @I3@ INDI
1 NAME Johnny /Doe/
1 FAMC @F1@
0 @F1@ FAM
1 HUSB @I1@
1 WIFE @I2@
1 CHIL @I3@
1 MARR
2 DATE 1925;`
const res = parseGedcomSync(sample);
const indi = res.nodes.find((n) => n.tag === "INDI") as IndividualNode;
indi.getName() // "John Doe"
indi.getBirthDate() // 1900-04-12
indi.getFamilyGroupsAsSpouse()[0].getMarriageDate()?.parsed // 1925-01-01
fam.getChildren().map((c) => c.id).join(", ") // "@I3"
This repository provides a parser and a small object-model for GEDCOM files. It
focuses on a pluggable decoder system and a NodeFactory so consumers can get
rich node instances (individuals, family groups, places) and optionally resolve
pointers.
Notable features:
- Streaming and synchronous parsing entrypoints
- NodeFactory to return rich node classes (IndividualNode, FamilyGroupNode, PlaceNode),
instead of plain JSON.
- Decoder registry for custom tag decoding (DATE, NAME, etc.)
- Optional pointer resolution to link references (e.g. @I1@ -> resolved node)
Many other GEDCOM parsers convert files into a simplified JSON representation.
During that transformation they often normalize or drop tags that aren't
explicitly supported by their schema or transform, which can hide information
that some consumers need. They also tend to return plain JSON without
higher-level helpers for common tasks.
By contrast, this gedcom-parser preserves the original node tree and is
designed for extensibility: you can register node parsers and value decoders
for additional or custom GEDCOM tags so that unknown tags remain available and
can be decoded according to your needs.
In short: choose this library when you need streaming parsing, pointer
resolution, and a pluggable decoding model that keeps data accessible and easy
to consume.
The library exposes two primary parsing entrypoints:
- parseGedcomSync(input, options) — parse a complete string synchronously andParseResult
return a .parseGedcom(streamOrAsyncIterable, options)
- — parse from a ReadableStream orPromise
async iterable and return a .
The parser returns ParseResult containing:
- nodes: top-level GedcomNode[] (records)byId
- : map of pointer id (@I1@) → GedcomNoderesolvePointers?()
- : optional helper to perform pointer resolution
Gedcom nodes follow the GedcomNode shape and decoders may set typedvalue fields such as GedcomDate or GedcomPointer. The project includesNodeFactory
rich node classes you can obtain by supplying the default :
- IndividualNode — helper methods like getName(), getBirthDate()FamilyGroupNode
- — getHusband(), getWife(), getChildren(), getMarriageDate()PlaceNode
- — getNormalized()
- Provide a custom NodeFactory when calling the parser to return app-specificDecoderRegistry
node classes.
- Provide a custom map to handle custom tags.
See examples directory.
- Open issues for bugs and feature requests.
- Add unit tests for new behaviors.
Run unit tests with Vitest (project already configures tests):
`bash``
yarn test