gedcom-ts 1.1.0 → 2.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+GEDCOM-TS© - 2019/2026 - Bertrand Jaunet
+All rights reserved.
+
+This license (the "License") governs the use of the software and associated documentation files (the "Software").
+1. Non-commercial use
+
+Personal, non-commercial use of the Software is permitted free of charge.
+2. Commercial use
+
+Any commercial use of the Software by a legal entity or professional organization, including but not limited to SaaS services, paid services, internal business operations, or any revenue-generating activity, requires prior subscription to a paid plan of 20 EUR per month.
+3. Retroactive payment obligation
+
+If commercial use of the Software begins before subscribing to the required plan, the user agrees to pay all fees due for the entire period of commercial use on a retroactive basis ("catch-up payment"), including the current month if any commercial use occurred during that month.
+4. Restrictions
+
+Except as expressly permitted by this License, no rights are granted to copy, modify, adapt, merge, publish, distribute, sublicense, or sell the Software, in whole or in part, without prior written permission from the copyright holder.
+5. Warranty disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+6. Limitation of liability
+
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,58 +1,251 @@
 # gedcom-ts
 
-A TypeScript library to manipulate genealogy tree data model in JSON and to export data in a GEDCOM file (.ged).
+`gedcom-ts` is a browser-oriented TypeScript library to:
 
-## INFORMATIONS
+- import genealogy data from GEDCOM (`.ged`) or ZIP (`.zip`)
+- work with a typed JSON model (persons, acts, notes, media, places)
+- export data back to GEDCOM (`.ged`) or ZIP (`.zip`)
 
-Gedcom-ts is an amazing library that allows you to work with genealogical files in the GEDCOM format in a simple and convenient way. You can easily import your GEDCOM files and convert them into JSON format for easier manipulation.
+## Project
 
-With Gedcom-ts, you can intuitively visualize your family trees starting from a specific person. You can also discover Sosa numbers, which help you quickly identify your direct ancestors.
+- NPM package: [gedcom-ts](https://www.npmjs.com/package/gedcom-ts)
 
-The library supports the management of family relationships, enabling you to represent family ties such as parents and children. You can also record the first names and surnames of your ancestors, as well as birth and death records.
+## Installation
 
-While marriage records are not yet supported, you can still manage couples and their relationships. The library allows you to export your data in the GEDCOM format for easy sharing with others using compatible software.
+```bash
+npm install gedcom-ts
+```
+
+## Runtime Requirements
+
+- modern browser runtime (`File`, `Blob`, `XMLHttpRequest`, `URL.createObjectURL`)
+- for pure Node.js usage, DOM polyfills are required
+
+## Import
+
+```ts
+import { importGedFile } from "gedcom-ts";
+
+async function loadGenealogy(file: File) {
+  const readGed = await importGedFile(file);
+  return readGed.persons;
+}
+```
+
+`importGedFile(file)` accepts:
+
+- a GED file (`.ged`)
+- a ZIP containing one GED file + optional media files
+
+It returns a `ReadGed` instance with parsed persons, families, notes, acts, media and maps.
+
+## Utilisation
+
+```ts
+import { ReadGed, Person, createSosaMap } from "gedcom-ts";
+
+function buildViewModel(readGed: ReadGed, root: Person) {
+  const persons = readGed.persons;
+  const personByIndi = readGed.mapPersons;
+  const sosaMap = createSosaMap(root, readGed.partnersMap);
+  return { persons, personByIndi, sosaMap };
+}
+```
+
+Typical workflow:
+
+1. import a file with `importGedFile`
+2. read and update `Person` objects
+3. export as `.ged` or `.zip`
+
+## Export
+
+### GED (`.ged`)
+
+```ts
+import { ExportGedcomFile, Person } from "gedcom-ts";
+
+function exportGed(persons: Person[]) {
+  new ExportGedcomFile("my-tree", persons).download();
+}
+```
+
+### ZIP (`.zip`) GED + media
+
+```ts
+import { ExportGedzipFile, Person } from "gedcom-ts";
+
+async function exportZip(persons: Person[]) {
+  await new ExportGedzipFile("my-tree", persons).download();
+}
+```
+
+## Public API with Examples
+
+Everything exported from `src/index.ts` is shown below with a minimal usage snippet.
+
+### Person, Sex
+
+```ts
+import { Person, Sex } from "gedcom-ts";
+
+const person = new Person();
+person.INDI = 1;
+person.SEX = Sex.M;
+person.firstnames = ["Jean"];
+person.lastname = "DUPONT";
+```
+
+### Act, Acts, TypeAct
+
+```ts
+import { Act, Acts, TypeAct, Identificator } from "gedcom-ts";
+
+const actType: TypeAct = Identificator.BIRT;
+const act = new Act(actType);
+const acts = new Acts();
+acts.add(act);
+```
+
+### DateAct, Day, Month, dateToDateLine, days, months
+
+```ts
+import { DateAct, Day, Month, dateToDateLine, days, months } from "gedcom-ts";
+
+const day: Day = 12;
+const month: Month = months[0]; // JAN
+const dateLine = dateToDateLine(1901, month, day); // "12 JAN 1901"
+const dateAct = new DateAct(dateLine);
+const formattedDate = dateAct.date;
+const knownDaysCount = days.length;
+```
 
-We are actively working on clear and precise documentation that will soon be available to guide you step-by-step in using Gedcom-ts. Stay tuned for updates and new features to come!
+### MultimediaFile, MultimediaFiles
 
-With Gedcom-ts, genealogy becomes more accessible and exciting. Enjoy this library to explore your family history and share your discoveries with your loved ones.
+```ts
+import { MultimediaFile, MultimediaFiles } from "gedcom-ts";
+
+const bucket = new MultimediaFiles();
+bucket.relativePath = "1/BIRT";
+bucket.add(new MultimediaFile(new File(["img"], "birth.jpg")));
+```
+
+### Place, CoordinateGPS
+
+```ts
+import { Place, CoordinateGPS } from "gedcom-ts";
+
+const place = new Place("Paris, FR", new CoordinateGPS(48.8566, 2.3522));
+```
+
+### Notes, Note, TypeNote
+
+```ts
+import { Notes, Note, TypeNote, Identificator } from "gedcom-ts";
+
+const typeNote: TypeNote = Identificator.CONT;
+const note = new Note();
+note.updateType(typeNote);
+note.updateLines(["first line", "second line"]);
+const notes = new Notes();
+notes.addNote(note);
+```
+
+### Identificator
+
+```ts
+import { Identificator } from "gedcom-ts";
+
+const birthTag = Identificator.BIRT;
+```
+
+### ExportGedcomFile, ExportGedzipFile
+
+```ts
+import { ExportGedcomFile, ExportGedzipFile, Person } from "gedcom-ts";
+
+const persons: Person[] = [];
+new ExportGedcomFile("tree", persons).download();
+await new ExportGedzipFile("tree", persons).download();
+```
 
-To provide any advice or suggestions for improvement, please contact me at: bertrand.jaunet@gmail.com
+### ReadGed
 
+```ts
+import { ReadGed } from "gedcom-ts";
+
+function useReadGed(readGed: ReadGed) {
+  return {
+    persons: readGed.persons,
+    places: readGed.placesMap,
+  };
+}
+```
+
+### importGedFile
+
+```ts
+import { importGedFile } from "gedcom-ts";
+
+const readGed = await importGedFile(fileInput.files![0]);
+```
+
+### createSosaMap
+
+```ts
+import { createSosaMap, Person } from "gedcom-ts";
+
+const root = new Person();
+root.INDI = 1;
+const sosaMap = createSosaMap(root, new Map());
+```
 
-## Install the gedcom-ts library
+### remainingTypesAct
 
-__NPM__
+```ts
+import { remainingTypesAct, Acts } from "gedcom-ts";
 
+const availableTypes = remainingTypesAct(new Acts());
 ```
-npm i --save gedcom-ts
+
+### EventsByYears, ActsByYear
+
+```ts
+import { EventsByYears, ActsByYear } from "gedcom-ts";
+
+const grouped = new EventsByYears([]);
+const yearBucket = new ActsByYear(1901);
+const eventsByYear = grouped.events;
+const selectedYear = yearBucket.year;
 ```
 
-## All instantiations JSON data model of Peoples
+## End-to-End Example
 
 ```ts
-import { Place, People, Act, DateAct, Identificator, GEDCOM, ReadGed } from 'gedcom-ts';
+import { importGedFile, ExportGedzipFile } from "gedcom-ts";
+
+async function importModifyExport(file: File) {
+  const readGed = await importGedFile(file);
+  const persons = readGed.persons;
+
+  if (persons.length > 0) {
+    persons[0].lastname = persons[0].lastname.toUpperCase();
+  }
+
+  await new ExportGedzipFile("updated-tree", persons).download();
+}
 ```
 
-Output in gedcom
+## Error Handling
 
-```ged
-0 HEAD
-1 SOUR generated by gedcom-ts
-1 DATE 13 07 2019
-2 TIME 19:10:22
-1 FILE monFichierGEDCOM
-1 GEDC
-2 VERS 5.5.1
-2 FORM LINEAGE-LINKED
-1 CHAR UTF-8
-0 @I1@ INDI
-1 NAME "Bruce" Thomas /WAYNE/
-1 SEX H
-1 BIRT
-2 DATE 01 Jan 1938
-2 PLAC Gotham City,USA
-1 DEAT
-2 DATE 01 Jan 2000
-2 PLAC Gotham City,USA
-TRLR
+```ts
+import { importGedFile } from "gedcom-ts";
+
+try {
+  const readGed = await importGedFile(file);
+  const personsCount = readGed.persons.length;
+} catch (error) {
+  console.error("GED import failed:", error);
+}
 ```
+

package/dist/commons/Act.d.ts

@@ -1,8 +1,41 @@
 import { DateAct } from "./DateAct";
+import { Place } from "./Place";
+import { Identificator } from "./Identificator.enum";
+import { MultimediaFile, MultimediaFiles } from "./MultimediaFile";
+import { Notes } from "./Note";
+export type TypeAct = Identificator.BIRT | Identificator.DEAT | Identificator.MARR;
 export declare class Act {
-    dateAct?: DateAct;
-    place: string;
-    act: string;
-    files: Array<Blob>;
-    constructor(dateAct?: DateAct, place?: string, act?: string, files?: Array<Blob>);
+    type: TypeAct;
+    dateAct?: DateAct | null;
+    place: Place | null;
+    INDIS: number[];
+    private newMultimediaFiles;
+    multimediaFiles: MultimediaFiles;
+    notes: Notes;
+    get files(): MultimediaFile[];
+    get keysFiles(): string[];
+    constructor(type: TypeAct, dateAct?: DateAct | null, place?: Place | null, indis?: number[] | null, multimediaFiles?: MultimediaFiles | null, newMultimediaFiles?: Map<string, MultimediaFile>, notes?: Notes);
+    /**
+     * Média rattaché à l’acte : `{indi}/{type}/{nomFichier}` (indi = premier INDI connu ou paramètre).
+     * Suffixe `_1`, `_2`, … avant l’extension si le chemin est déjà pris sur cet acte.
+     */
+    addMultimedia(multimediaFile: MultimediaFile, ownerIndi?: number): void;
+    removeMultimedia(index: number): void;
+    private mediaRelativePathsInUse;
+    updateType(typeAct: TypeAct): void;
+    addIndis(INDIS: number[]): void;
+    updatePlace(place: Place): void;
+    updateDateAct(dateAct: DateAct): void;
+}
+export declare class Acts {
+    list: Act[];
+    add(act: Act): void;
+    updateFromIndex(act: Act, indexAct: number): void;
+    removeFromIndex(indexAct: number): void;
+    removeAll(): void;
+    sortByDate(): void;
+}
+export declare class ActsByExtraction extends Acts {
+    extractActsInfo(lines: string[], INDIS: number[], mapFiles: Map<string, File>): void;
+    private convertToActs;
 }

package/dist/commons/ActsByYears.d.ts

@@ -0,0 +1,10 @@
+import { Act, Acts } from "./Act";
+export declare class ActsByYear extends Acts {
+    year: number;
+    constructor(year: number);
+}
+export declare class EventsByYears {
+    events: ActsByYear[];
+    constructor(acts: Act[]);
+    private sortByYear;
+}

package/dist/commons/DateAct.d.ts

@@ -3,13 +3,32 @@ export declare enum TypeDateAct {
     ABT = "ABT",
     NULL = "NULL"
 }
+export declare enum MonthEnum {
+    JAN = "JAN",
+    FEB = "FEB",
+    MAR = "MAR",
+    APR = "APR",
+    MAY = "MAY",
+    JUN = "JUN",
+    JUL = "JUL",
+    AUG = "AUG",
+    SEP = "SEP",
+    OCT = "OCT",
+    NOV = "NOV",
+    DEC = "DEC"
+}
+export type Day = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | null;
+export declare const days: number[];
+export type Month = MonthEnum.JAN | MonthEnum.FEB | MonthEnum.MAR | MonthEnum.APR | MonthEnum.MAY | MonthEnum.JUN | MonthEnum.JUL | MonthEnum.AUG | MonthEnum.SEP | MonthEnum.OCT | MonthEnum.NOV | MonthEnum.DEC | null;
+export declare const months: Month[];
 export declare class DateAct {
     typeDateAct?: TypeDateAct;
-    day?: string;
-    month?: string;
-    year?: string;
-    date?: Date | null;
+    day?: Day;
+    month?: Month;
+    year?: number;
     constructor(dateLine: string);
+    get date(): string | null;
     private convertMonth;
-    private parseDate;
+    isValid(): boolean;
 }
+export declare const dateToDateLine: (year?: number, month?: Month, day?: Day) => string;

package/dist/commons/MultimediaFile.d.ts

@@ -0,0 +1,14 @@
+export declare class MultimediaFile {
+    relativePath: string;
+    file: File;
+    constructor(file?: File);
+    get filename(): string;
+}
+export declare class MultimediaFiles {
+    /** Répertoire logique (sans slash final), ex. `1` ou `1/BIRT`. */
+    relativePath: string;
+    files: MultimediaFile[];
+    add(multimediaFile: MultimediaFile): void;
+    removeFromIndex(indexMultimediaFile: number): void;
+    removeAll(): void;
+}

package/dist/commons/Note.d.ts

@@ -0,0 +1,18 @@
+import { Identificator } from "./Identificator.enum";
+export type TypeNote = Identificator.CONC | Identificator.CONT | undefined;
+export declare class Note {
+    INDIS: number[];
+    type: TypeNote;
+    lines: string[];
+    updateLines(lines: string[]): void;
+    removeLines(): void;
+    updateType(typeNote: TypeNote): void;
+    addIndis(INDIS: number[]): void;
+}
+export declare class Notes {
+    list: Note[];
+    addNote(note: Note): void;
+    updateFromIndex(note: Note, indexNote: number): void;
+    removeFromIndex(indexNote: number): void;
+    removeAll(): void;
+}

package/dist/commons/Person.d.ts

@@ -0,0 +1,44 @@
+import { Acts } from './Act';
+import { MultimediaFile, MultimediaFiles } from "./MultimediaFile";
+import { Notes } from "./Note";
+export declare enum Sex {
+    M = "M",
+    F = "F"
+}
+export declare class Person {
+    sosa: number | undefined;
+    INDI: number;
+    SEX: Sex | undefined;
+    firstnames: Array<string>;
+    lastname: string;
+    FAMC?: number;
+    FAMS: number[];
+    private newMultimediaFiles;
+    multimediaFiles: MultimediaFiles;
+    acts: Acts;
+    notes: Notes;
+    get files(): MultimediaFile[];
+    get keysFiles(): string[];
+    constructor(sosa?: number, SEX?: Sex, firstnames?: Array<string>, lastname?: string, FAMC?: number, FAMS?: number[], INDI?: number, multimediaFiles?: MultimediaFiles, newMultimediaFiles?: Map<string, MultimediaFile>, acts?: Acts);
+    createPersonJson(personLines: string[], informationFamilies?: Map<number, string[]>, mapFiles?: Map<string, File>, globalNotes?: Map<number, string[]>): void;
+    private parsePersonLine;
+    private createIndiFromZeroLine;
+    private createSexFromValue;
+    private createFAMCFromValue;
+    private createFAMSFromValue;
+    private createMultimediaFilesFromValue;
+    private addNoteFromGedcom;
+    /**
+     * Média au niveau individu (hors acte) : chemin logique `{INDI}/{nomFichier}`.
+     * Si le même nom existe déjà pour cet individu, suffixe `_1`, `_2`, etc. avant l’extension.
+     */
+    addMultimedia(multimediaFile: MultimediaFile): void;
+    deleteMultimedia(path: string): void;
+    private mediaRelativePathsInUse;
+    private createFirstnamesAndLastnameJson;
+}
+export declare class TreePerson extends Person {
+    parents: Person[];
+    childrens: Person[];
+    constructor(person: Person, parents: Person[], childrens: Person[], currentSosa: number);
+}

package/dist/commons/Place.d.ts

@@ -1,14 +1,12 @@
 export declare class Place {
-    city: string;
-    zip: number;
-    county: string;
-    region: string;
-    country: string;
+    city: string | null;
     coordinate: CoordinateGPS;
-    constructor(city?: string, zip?: number, county?: string, region?: string, country?: string, coordinate?: CoordinateGPS);
+    constructor(city?: string, coordinate?: CoordinateGPS);
+    addCity(city: string): void;
 }
 export declare class CoordinateGPS {
-    latitude: number;
-    longitude: number;
-    constructor(latitude: number, longitude: number);
+    latitude: number | undefined;
+    longitude: number | undefined;
+    constructor(latitude?: number, longitude?: number);
+    addCoordinates([x, y]: [number, number]): void;
 }

package/dist/export/GEDCOM.d.ts

@@ -1,42 +1,51 @@
-import { Separators } from '../commons/Separators';
-import { People } from '../commons/People';
-import { Act } from '../commons/Act';
-import { Identificator } from '../commons/Identificator.enum';
-export declare class ExportFormatFile {
-    title: string;
-    extension: string;
-    constructor(title: string);
-    export(data: any): void;
+import { Person } from '../commons/Person';
+declare class GEDCOM {
+    protected title: string;
+    protected persons: Array<Person>;
+    protected onCreate: number;
+    private haveFiles;
+    constructor(title: string | undefined, persons: Array<Person>, haveFiles: boolean);
+    private get beginGedcom();
+    private get contentGedcom();
+    gedcomBlob(): Blob;
 }
-export declare class GEDCOM extends ExportFormatFile {
-    peoples: Array<People>;
-    constructor(title: string, peoples: Array<People>);
-    get beginGedcom(): string;
-    get contentGedcom(): string;
-    download(): void;
+export declare class ExportGedzipFile extends GEDCOM {
+    private zip;
+    constructor(...args: [persons: Array<Person>] | [title: string, persons: Array<Person>]);
+    download(): Promise<void>;
+    private collectMediaFiles;
+    private resolvePersonIndi;
+    private resolveActIndis;
+    private resolveZipPath;
+    private zipFile;
 }
-export declare class LineGedcom {
-    cr: Separators;
+export declare class ExportGedcomFile extends GEDCOM {
+    constructor(...args: [persons: Array<Person>] | [title: string, persons: Array<Person>]);
+    download(): void;
 }
-export declare class PeopleLine extends LineGedcom {
-    sosa: number;
-    fams?: number[];
-    famc?: number;
-    firstnames: Array<string>;
-    lastnames: string;
-    constructor(sosa: number, firstnames: Array<string>, lastnames: string, fams: number[], famc: number);
-    get indi(): string;
-    get famsLine(): string;
-    get famcLine(): string | null;
-    get firstnamesAndNames(): string;
-    get sex(): string;
+export declare class FamilyLine {
+    private informationFamilies;
+    constructor(persons: Person[]);
+    lines(): string;
+    private setInformationFamilies;
 }
-export declare class ActLine extends LineGedcom {
-    type: Identificator;
-    act: Act;
-    constructor(type: Identificator, act: Act);
-    get typeLine(): string;
-    get dateLine(): string;
-    get placeLine(): string;
-    private formatDate;
+export declare class PersonLine {
+    private readonly INDI;
+    private readonly NAME;
+    private readonly SEX;
+    private readonly FAMS;
+    private readonly FAMC;
+    private readonly FILES;
+    private readonly ACTS;
+    private readonly NOTES;
+    constructor(person: Person, haveFiles: boolean);
+    line(): string;
+    private getFileLines;
+    private getIndi;
+    private getName;
+    private getSex;
+    private getFiles;
+    private getFams;
+    private getFamc;
 }
+export {};

package/dist/import/LoadFile.d.ts

@@ -0,0 +1,2 @@
+import { ReadGed } from './ReadGed';
+export declare const importGedFile: (file: File) => Promise<ReadGed>;

package/dist/import/ReadGed.d.ts

@@ -1,19 +1,19 @@
-import { People } from '../commons/People';
-export declare class ReadGed {
-    gedcom: string;
-    peoples: People[];
-    partnersMap: Map<number, People[]>;
-    childsMap: Map<number, People[]>;
-    constructor(gedcom: string);
-    get informationHeadFile(): string;
-    get informationPeoplesFile(): string[];
-    get informationMarriagesFile(): string[];
-    private get separate();
-    import(): People[];
+import { Person } from '../commons/Person';
+import { SplitGedcom } from "./SplitedInformations";
+import { Place } from "../commons/Place";
+export declare class ReadGed extends SplitGedcom {
+    persons: Person[];
+    mapPersons: Map<number, Person>;
+    partnersMap: Map<number, Person[]>;
+    childsMap: Map<number, Person[]>;
+    mapFiles: Map<string, File>;
+    placesMap: Map<string, Place>;
+    constructor(gedcomContent?: string, mapFiles?: Map<string, File>, placesMap?: Map<string, Place>, mapPersons?: Map<number, Person>);
+    static fromGedcomFile(gedcomFile: File, mapFiles?: Map<string, File>, placesMap?: Map<string, Place>, mapPersons?: Map<number, Person>): Promise<ReadGed>;
+    private finalizeAfterParse;
     groupPartners(): void;
-    createDirectAncestries(people: People): People[];
-    private haveParentsOfPeople;
-}
-export declare class Create {
-    static json(peoplesFile: string[], marriagesFile: string[]): People[];
+    createDirectAncestries(person: Person): Person[];
+    generateUniqueIndi(): number;
+    private haveParentsOfPerson;
+    private createPersons;
 }

package/dist/import/SplitedInformations.d.ts

@@ -0,0 +1,13 @@
+export declare class SplitGedcom {
+    protected informationPersons: string[][];
+    protected informationFamilies: Map<number, string[]>;
+    protected informationNotes: Map<number, string[]>;
+    constructor(gedcomContent?: string);
+    protected ingestGedcomText(gedcomContent: string): void;
+    protected ingestGedcomFileStream(file: File): Promise<void>;
+    private ingestRecordBlock;
+    private splitInformationPersons;
+    private splitInformationFamilies;
+    private splitInformationNotes;
+    private extractXrefId;
+}