gedcom/dist/index.d.cts

a simple and readable gedcom parser

import { Node, Parent } from "unist";
import { Graph } from "graphlib";

//#region lib/types.d.ts
type GEDCOMData = {
  formal_name?: string;
  value?: string | undefined;
  xref_id?: string | undefined;
  pointer?: string | undefined;
  custom_tag?: boolean | undefined;
} & Record<string, unknown>;
interface Node$1 extends Node {
  data: GEDCOMData;
  children?: (Parent$1 | Node$1)[];
}
interface Parent$1 extends Parent {
  data?: GEDCOMData;
  children: (Parent$1 | Node$1)[];
}
//#endregion
//#region lib/parse-to-unist.d.ts
/**
 * Parse a string of GEDCOM data into an unist-compatible
 * abstract syntax tree. This is the core function for transforming
 * GEDCOM into JSON data that captures all of its detail, but
 * for practical usage you may also want to run `compact`
 * on the generated syntax tree to compress attributes.
 *
 * **Note**: the AST format uses 'children' to indicate the children
 * of abstract syntax tree nodes, but these are not equivalent to
 * parent/child relationships in family data.
 *
 * @param input - GEDCOM data as a string
 * @returns ast
 */
declare function parse(input: string): Parent$1;
//#endregion
//#region lib/formal_names.d.ts
declare const FORMAL_NAMES: {
  ABBR: string;
  ADDR: string;
  ADR1: string;
  ADR2: string;
  ADOP: string;
  AFN: string;
  AGE: string;
  AGNC: string;
  ALIA: string;
  ANCE: string;
  ANCI: string;
  ANUL: string;
  ASSO: string;
  AUTH: string;
  BAPL: string;
  BAPM: string;
  BARM: string;
  BASM: string;
  BIRT: string;
  BLES: string;
  BURI: string;
  CALN: string;
  CAST: string;
  CAUS: string;
  CENS: string;
  CHAN: string;
  CHAR: string;
  CHIL: string;
  CHR: string;
  CHRA: string;
  CITY: string;
  CONC: string;
  CONF: string;
  CONL: string;
  CONT: string;
  COPR: string;
  CORP: string;
  CREM: string;
  CTRY: string;
  DATA: string;
  DATE: string;
  DEAT: string;
  DESC: string;
  DESI: string;
  DEST: string;
  DIV: string;
  DIVF: string;
  DSCR: string;
  EDUC: string;
  EMAI: string;
  EMIG: string;
  ENDL: string;
  ENGA: string;
  EVEN: string;
  FACT: string;
  FAM: string;
  FAMC: string;
  FAMF: string;
  FAMS: string;
  FAX: string;
  FCOM: string;
  FILE: string;
  FORM: string;
  FONE: string;
  GEDC: string;
  GIVN: string;
  GRAD: string;
  HEAD: string;
  HUSB: string;
  IDNO: string;
  IMMI: string;
  INDI: string;
  LANG: string;
  LATI: string;
  LONG: string;
  MAP: string;
  MARB: string;
  MARC: string;
  MARL: string;
  MARR: string;
  MARS: string;
  MEDI: string;
  NAME: string;
  NATI: string;
  NATU: string;
  NCHI: string;
  NICK: string;
  NMR: string;
  NOTE: string;
  NPFX: string;
  NSFX: string;
  OBJE: string;
  OCCU: string;
  ORDI: string;
  ORDN: string;
  PAGE: string;
  PEDI: string;
  PHON: string;
  PLAC: string;
  POST: string;
  PROB: string;
  PROP: string;
  PUBL: string;
  QUAY: string;
  REFN: string;
  RELA: string;
  RELI: string;
  REPO: string;
  RESI: string;
  RESN: string;
  RETI: string;
  RFN: string;
  RIN: string;
  ROLE: string;
  ROMN: string;
  SEX: string;
  SLGC: string;
  SLGS: string;
  SOUR: string;
  SPFX: string;
  SSN: string;
  STAE: string;
  STAT: string;
  SUBM: string;
  SUBN: string;
  SURN: string;
  TEMP: string;
  TEXT: string;
  TIME: string;
  TITL: string;
  TRLR: string;
  TYPE: string;
  VERS: string;
  WIFE: string;
  WILL: string;
  WWW: string;
};
//#endregion
//#region lib/tokenize.d.ts
type TagName = keyof typeof FORMAL_NAMES;
type Line = {
  level: number;
  tag: TagName;
  xref_id?: string;
  pointer?: string;
  value?: string;
};
/**
 * Lowest-level API to parse-gedcom: parses a single line
 * of GEDCOM into its constituent tag, level, xref_id,
 * and so on. It's unlikely that external applications would use this API.
 * Instead they will more often use `parse`.
 *
 * @param buf - One line of GEDCOM data as a string
 * @returns a line object.
 */
declare function tokenize(buf: string, lineNumber: number): Line;
//#endregion
//#region lib/unist-compact.d.ts
/**
 * This applies an opinionated transformation to GEDCOM data,
 * making it easier for common use cases. In the raw GEDCOM
 * AST, attributes like birth years are represented as nodes.
 * This transformation compresses those attributes into properties
 * of a node’s `.data` member.
 *
 * Here's how this transformation works:
 *
 * For example, let's say you have this content:
 *
 * ```
 * 0 INDI
 *   1 BIRT
 *     2 DATE 12 MAY 1920
 *   1 DEAT
 *     2 DATE 1960
 * ```
 *
 * The output of `parse` will create nodes for the INDI, BIRT, DATE,
 * DEAT, and DATE objects. If you simply want to ask 'when was this individual
 * alive?' This can be a difficult question to answer. Compact will transform
 * those nodes into a simplified form:
 *
 * ```js
 *  {
 *   type: "INDI",
 *   data: {
 *     formal_name: "INDIVIDUAL",
 *     "BIRTH/DATE": "12 MAY 1920",
 *     "DEATH/DATE": "1960",
 *   },
 *   value: undefined,
 *   children: [],
 * }
 * ```
 *
 * If there are multiple values for something like a birth date, they'll be
 * included in an additional property with a `+`:
 *
 * {
 *   "BIRTH/DATE": "12 MAY 1920",
 *   "+BIRTH/DATE": ["13 MAY 1920"],
 * }
 *
 * This also removes nodes from the syntax tree that are unlikely
 * to have any use for genealogical or visualization applications.
 *
 * @param root - a parsed GEDCOM document
 * @param removeNodes - a list of nodes that should be removed.
 * @returns the same document, with attributes compacted.
 */
declare function compact(root: Parent$1, removeNodes?: string[]): Parent$1;
//#endregion
//#region lib/to-d3-force.d.ts
type Link = {
  source: string;
  target: string;
  value: string;
};
type ForceData = {
  nodes: (Node$1 | Parent$1)[];
  links: Link[];
};
/**
 * Transforms a GEDCOM AST - likely produced using
 * `parse` - into a data structure suited for
 * a [D3 force directed graph](https://observablehq.com/@d3/force-directed-graph)
 * layout.
 *
 * @param root - Parsed GEDCOM content
 * @returns D3-friendly JSON
 */
declare function toD3Force(root: Parent$1): ForceData;
//#endregion
//#region lib/to-dot.d.ts
/**
 * Transforms a GEDCOM AST - likely produced using
 * `parse` - into a [Graphviz DOT](https://graphviz.org/doc/info/lang.html)
 * language file.
 *
 * @param root - Parsed GEDCOM content
 * @returns DOT-formatted graph
 */
declare function toDot(root: Parent$1): string;
//#endregion
//#region lib/to-graphlib.d.ts
/**
 * Transforms a GEDCOM AST into a [Graphlib](https://github.com/dagrejs/graphlib)
 * Graph object.
 *
 * @param root - Parsed GEDCOM content
 * @returns graphviz Graph object
 */
declare function toGraphlib(root: Parent$1): Graph;
//#endregion
export { compact, parse, toD3Force, toDot, toGraphlib, tokenize };