gedcom-ts 2.1.0 → 2026.5.1

package/dist/edit/GedcomExportOptionsEdit.d.ts

@@ -0,0 +1,20 @@
+import type { GedcomExportOptions } from "../export/GEDCOM";
+/**
+ * Mutation in-place des {@link GedcomExportOptions} (export `.ged` / `.zip`).
+ */
+export declare class GedcomExportOptionsEdit {
+    private readonly target;
+    constructor(target: GedcomExportOptions);
+    get value(): GedcomExportOptions;
+    setExtraTopLevelRecords(lines: readonly string[] | null | undefined): this;
+    clearExtraTopLevelRecords(): this;
+    setHeadLanguageTag(tag: string | null | undefined): this;
+    setHeadCopyright(text: string | null | undefined): this;
+    setHeadDestination(dest: string | null | undefined): this;
+    setHeadSchemaTagDefs(defs: readonly {
+        readonly tag: string;
+        readonly uri: string;
+    }[] | null | undefined): this;
+    clearHeadSchemaTagDefs(): this;
+}
+export declare function editGedcomExportOptions(options: GedcomExportOptions): GedcomExportOptionsEdit;

package/dist/edit/IndiAttributesEdit.d.ts

@@ -0,0 +1,38 @@
+import type { IndiGedcomSubLine } from "../commons/IndiGedcomSubLine";
+import type { IndiAttribute } from "../commons/IndiAttribute";
+/**
+ * API d’édition cohérente autour d’un {@link IndiAttribute} existant.
+ */
+export declare class IndiAttributeEdit {
+    private readonly target;
+    constructor(target: IndiAttribute);
+    get value(): IndiAttribute;
+    setTag(tag: string): this;
+    setValue(value: string): this;
+    setChildren(children: readonly IndiGedcomSubLine[]): this;
+    appendChild(child: IndiGedcomSubLine): this;
+    clearChildren(): this;
+}
+export declare function editIndiAttribute(attr: IndiAttribute): IndiAttributeEdit;
+/**
+ * Liste d’attributs individuels (`FACT`, `DSCR`, …) sur une {@link Person}.
+ */
+export declare class IndiAttributesEdit {
+    private readonly target;
+    constructor(target: {
+        attributes: IndiAttribute[];
+    });
+    get value(): IndiAttribute[];
+    add(attr: IndiAttribute): this;
+    addNew(tag: string, value?: string, children?: readonly IndiGedcomSubLine[]): IndiAttributeEdit;
+    insertAt(index: number, attr: IndiAttribute): this;
+    insertNewAt(index: number, tag: string, value?: string, children?: readonly IndiGedcomSubLine[]): IndiAttributeEdit;
+    removeLast(): this;
+    replaceAt(index: number, attr: IndiAttribute): this;
+    removeAt(index: number): this;
+    clear(): this;
+    at(index: number): IndiAttributeEdit;
+}
+export declare function editIndiAttributes(person: {
+    attributes: IndiAttribute[];
+}): IndiAttributesEdit;

package/dist/edit/MultimediaFileEdit.d.ts

@@ -0,0 +1,17 @@
+import { MultimediaFile } from "../commons/MultimediaFile";
+/**
+ * API d’édition cohérente autour d’un {@link MultimediaFile} existant.
+ */
+export declare class MultimediaFileEdit {
+    private readonly target;
+    constructor(target: MultimediaFile);
+    get value(): MultimediaFile;
+    setRelativePath(path: string): this;
+    setFile(file: File | undefined): this;
+    clearFile(): this;
+    setSourceUri(uri: string | null | undefined): this;
+    clearSourceUri(): this;
+    setObjeXrefId(id: number | null | undefined): this;
+    clearObjeXrefId(): this;
+}
+export declare function editMultimediaFile(file: MultimediaFile): MultimediaFileEdit;

package/dist/edit/NameVariantsEdit.d.ts

@@ -0,0 +1,43 @@
+import type { IndiGedcomSubLine } from "../commons/IndiGedcomSubLine";
+import { PersonNameTranslation, PersonNameVariant } from "../commons/PersonNameVariant";
+/**
+ * API d’édition cohérente autour d’un {@link PersonNameVariant} existant.
+ */
+export declare class PersonNameVariantEdit {
+    private readonly target;
+    constructor(target: PersonNameVariant);
+    get value(): PersonNameVariant;
+    setPayload(payload: string): this;
+    setType(type: string | null | undefined): this;
+    clearType(): this;
+    setParts(parts: readonly IndiGedcomSubLine[]): this;
+    appendPart(part: IndiGedcomSubLine): this;
+    clearParts(): this;
+    setTranslations(translations: readonly PersonNameTranslation[]): this;
+    appendTranslation(translation: PersonNameTranslation): this;
+    clearTranslations(): this;
+}
+export declare function editPersonNameVariant(variant: PersonNameVariant): PersonNameVariantEdit;
+/**
+ * Variants `1 NAME` sur une {@link Person}.
+ */
+export declare class NameVariantsEdit {
+    private readonly target;
+    constructor(target: {
+        nameVariants: PersonNameVariant[];
+    });
+    get value(): PersonNameVariant[];
+    add(variant: PersonNameVariant): this;
+    /** Ajoute un variant minimal (`1 NAME` / `2 TYPE` optionnel) et renvoie sa facade. */
+    addNew(payload: string, type?: string): PersonNameVariantEdit;
+    insertAt(index: number, variant: PersonNameVariant): this;
+    insertNewAt(index: number, payload: string, type?: string): PersonNameVariantEdit;
+    removeLast(): this;
+    replaceAt(index: number, variant: PersonNameVariant): this;
+    removeAt(index: number): this;
+    clear(): this;
+    at(index: number): PersonNameVariantEdit;
+}
+export declare function editNameVariants(person: {
+    nameVariants: PersonNameVariant[];
+}): NameVariantsEdit;

package/dist/edit/NoteEdit.d.ts

@@ -0,0 +1,18 @@
+import { Note, type TypeNote } from "../commons/Note";
+/**
+ * API d’édition cohérente autour d’une {@link Note} existante (mutation in-place).
+ */
+export declare class NoteEdit {
+    private readonly target;
+    constructor(target: Note);
+    get value(): Note;
+    setType(type: TypeNote): this;
+    /** Remplace le texte de la note (y compris tableau vide). */
+    setLines(lines: readonly string[]): this;
+    appendLine(line: string): this;
+    clearLines(): this;
+    setIndis(ids: readonly number[]): this;
+    appendIndi(indi: number): this;
+    clearIndis(): this;
+}
+export declare function editNote(note: Note): NoteEdit;

package/dist/edit/NotesEdit.d.ts

@@ -1,4 +1,5 @@
 import { Note, Notes } from "../commons/Note";
+import { NoteEdit } from "./NoteEdit";
 /**
  * API d’édition cohérente autour d'un {@link Notes}.
  */
@@ -6,9 +7,19 @@ export declare class NotesEdit {
     private readonly target;
     constructor(target: Notes);
     get value(): Notes;
+    /**
+     * Crée une {@link Note}, l’ajoute en fin de liste et renvoie sa facade d’édition.
+     */
+    addNew(initialLines?: readonly string[] | null): NoteEdit;
     add(note: Note): this;
+    insertAt(index: number, note: Note): this;
+    insertNewAt(index: number, initialLines?: readonly string[] | null): NoteEdit;
+    removeLast(): this;
+    indexOfNote(note: Note): number;
+    removeNote(note: Note): boolean;
     replaceAt(index: number, note: Note): this;
     removeAt(index: number): this;
     clear(): this;
+    at(index: number): NoteEdit;
 }
 export declare function editNotes(notes: Notes): NotesEdit;

package/dist/edit/PersonEdit.d.ts

@@ -2,7 +2,10 @@ import type { IndiAttribute } from "../commons/IndiAttribute";
 import { Person, Sex } from "../commons/Person";
 import type { PersonNameVariant } from "../commons/PersonNameVariant";
 import { ActsEdit } from "./ActsEdit";
+import { IndiAttributesEdit } from "./IndiAttributesEdit";
+import { NameVariantsEdit } from "./NameVariantsEdit";
 import { NotesEdit } from "./NotesEdit";
+import { PersonMediaEdit } from "./PersonMediaEdit";
 /**
  * API d’édition cohérente autour d'un {@link Person} existant (identité, unions, actes, notes).
  */
@@ -15,13 +18,30 @@ export declare class PersonEdit {
     setFirstnames(firstnames: readonly string[]): this;
     setSosa(sosa: number | undefined): this;
     setFamc(famc: number | undefined): this;
+    /** Efface le lien de filiation (`FAMC`). */
+    clearFamc(): this;
     /** Remplace la liste des unions (`FAMS`). */
     setFams(fams: readonly number[]): this;
     clearFams(): this;
     appendFams(famId: number): this;
+    /** Retire l’identifiant de famille à l’index donné dans `FAMS`. */
+    removeFamsAt(index: number): this;
+    /** Retire la première occurrence de `familyId` dans `FAMS` (no-op si absent). */
+    removeFamsByFamilyId(familyId: number): this;
     setNameVariants(variants: readonly PersonNameVariant[]): this;
+    /** Édition élément par élément des blocs `1 NAME`. */
+    nameVariants(): NameVariantsEdit;
     setAttributes(attrs: readonly IndiAttribute[]): this;
+    /** Édition élément par élément des attributs de niveau 1 (`FACT`, …). */
+    attributes(): IndiAttributesEdit;
     acts(): ActsEdit;
     notes(): NotesEdit;
+    /** Médias de niveau individu (fichiers locaux via {@link Person.addMultimedia}). */
+    multimedia(): PersonMediaEdit;
+    clearActs(): this;
+    clearNotes(): this;
+    clearMultimedia(): this;
+    clearNameVariants(): this;
+    clearAttributes(): this;
 }
 export declare function editPerson(person: Person): PersonEdit;

package/dist/edit/PersonMediaEdit.d.ts

@@ -0,0 +1,27 @@
+import { MultimediaFile } from "../commons/MultimediaFile";
+import type { Person } from "../commons/Person";
+import { MultimediaFileEdit } from "./MultimediaFileEdit";
+/**
+ * Médias au niveau individu : s'appuie sur {@link Person.addMultimedia} / {@link Person.deleteMultimedia}.
+ */
+export declare class PersonMediaEdit {
+    private readonly target;
+    constructor(target: Person);
+    get value(): Person;
+    /**
+     * Crée un {@link MultimediaFile} à partir d'un fichier local, l'ajoute et renvoie sa facade.
+     */
+    addNewFromFile(file: File): MultimediaFileEdit;
+    /**
+     * Ajoute un média à partir d’une URI (sans fichier local), voir {@link Person.addMultimediaFromUri}.
+     */
+    addNewFromUri(uri: string, objeXrefId?: number | null): MultimediaFileEdit;
+    /**
+     * Ajoute un média avec fichier local (chemins relatifs gérés comme dans {@link Person.addMultimedia}).
+     */
+    add(multimediaFile: MultimediaFile): this;
+    removeAt(index: number): this;
+    clear(): this;
+    at(index: number): MultimediaFileEdit;
+}
+export declare function editPersonMedia(person: Person): PersonMediaEdit;

package/dist/edit/factories.d.ts

@@ -0,0 +1,35 @@
+import { Act, type ActConstructionOptions, type TypeAct } from "../commons/Act";
+import { DateAct } from "../commons/DateAct";
+import type { IndiGedcomSubLine } from "../commons/IndiGedcomSubLine";
+import { IndiAttribute } from "../commons/IndiAttribute";
+import { Note, Notes } from "../commons/Note";
+import { Person, Sex } from "../commons/Person";
+import { PersonNameVariant } from "../commons/PersonNameVariant";
+import { Place } from "../commons/Place";
+export type CreateActInit = {
+    dateAct?: DateAct | null;
+    place?: Place | null;
+    indis?: readonly number[] | null;
+    construction?: ActConstructionOptions | null;
+    notes?: Notes;
+};
+/** Construit un {@link Act} (pour `ActsEdit.add`, `addNew`, etc.). */
+export declare function createAct(type: TypeAct, init?: CreateActInit | null): Act;
+/**
+ * Construit une {@link Note} avec des lignes initialisées (tableau vide par défaut).
+ */
+export declare function createNote(initialLines?: readonly string[] | null): Note;
+export type CreatePersonStubInit = {
+    sosa?: number;
+    sex?: Sex;
+    firstnames?: readonly string[];
+    lastname?: string;
+    famc?: number;
+    fams?: readonly number[];
+};
+/**
+ * Crée un {@link Person} minimal avec un `INDI` connu (arbre vide ou ajout manuel).
+ */
+export declare function createPersonStub(indi: number, init?: CreatePersonStubInit | null): Person;
+export declare function createPersonNameVariant(payload: string, type?: string): PersonNameVariant;
+export declare function createIndiAttribute(tag: string, value?: string, children?: readonly IndiGedcomSubLine[]): IndiAttribute;

package/dist/edit/index.d.ts

@@ -12,8 +12,22 @@
  * ```
  */
 export { ActEdit, editAct } from "./ActEdit";
+export { ActMediaEdit, editActMedia } from "./ActMediaEdit";
 export { ActsEdit, editActs } from "./ActsEdit";
+export { cloneAct, clonePerson } from "../dataset/cloneModels";
 export { DateActEdit, editDateAct } from "./DateActEdit";
+export { createAct, createIndiAttribute, createNote, createPersonNameVariant, createPersonStub, type CreateActInit, type CreatePersonStubInit, } from "./factories";
+export { editGedcomExportOptions, GedcomExportOptionsEdit } from "./GedcomExportOptionsEdit";
+export { addPersonToReadGed, commandBlockingIssues, createMarriageFamily, linkChildToFamily, nextFamilyId, removeFamilyReferencesFromDataset, removePersonFromReadGedByIndi, tryAddPersonToReadGed, tryCreateMarriageFamily, tryLinkChildToFamily, tryRemovePersonFromReadGedByIndi, tryUnlinkChildFromFamily, unlinkChildFromFamily, validateAddPersonCommand, validateCreateMarriageCommand, validateLinkChildCommand, validateUnlinkChildCommand, } from "../dataset";
+export type { CommandFail, CommandOk, CommandResult, CreateUnionFamilyOptions } from "../dataset";
+export { IndiAttributeEdit, IndiAttributesEdit, editIndiAttribute, editIndiAttributes } from "./IndiAttributesEdit";
+export { MultimediaFileEdit, editMultimediaFile } from "./MultimediaFileEdit";
+export { NameVariantsEdit, PersonNameVariantEdit, editNameVariants, editPersonNameVariant } from "./NameVariantsEdit";
+export { NoteEdit, editNote } from "./NoteEdit";
 export { NotesEdit, editNotes } from "./NotesEdit";
 export { PersonEdit, editPerson } from "./PersonEdit";
+export { PersonMediaEdit, editPersonMedia } from "./PersonMediaEdit";
 export { PlaceEdit, editPlace } from "./PlaceEdit";
+export { PreservedTopLevelEdit, ReadGedEdit, editReadGed } from "../dataset/ReadGedEdit";
+export { assertPersonConsistent, assertReadGedConsistent, validatePerson, validateReadGed, } from "../dataset/validation";
+export type { AssertConsistencyOptions, ConsistencySeverity, ModelConsistencyIssue, ModelConsistencyIssueCode, ValidatePersonContext, ValidateReadGedOptions, } from "../dataset/validation";

package/dist/geocode/index.d.ts

@@ -0,0 +1,3 @@
+export { normalizeCityKey, tidyCityDisplay, findCanonicalCityLabel, } from "./place-city-utils";
+export { type GeocodeCandidate, type GeocodeContext, type GeocodeFetchFn, type GeocodeSearchOptions, NOMINATIM_SEARCH_URL, defaultGeocodeUserAgent, parseCityQuery, countryLabelToIso, isoToCountryLabel, inferGeocodeContext, buildGeocodeQuery, geocodeContextWithHint, rankGeocodeCandidates, searchPlaces, searchPlacesWithContext, } from "./place-geocode";
+export { type CoordVariant, type CityHarmonizationCluster, levenshteinDistance, citiesAreSimilar, clusterKeyForCity, findHarmonizationClustersFromActs, findHarmonizationClusters, applyCoordinatesToActs, applyGeocodeCandidateToActs, } from "./place-clusters";

package/dist/geocode/place-city-utils.d.ts

@@ -0,0 +1,11 @@
+import type { Act } from "../commons/Act";
+import type { ReadGed } from "../import/ReadGed";
+/** Clé de regroupement : casse, espaces, compatibilité Unicode (NFKC). */
+export declare function normalizeCityKey(city: string): string;
+/** Libellé affiché : trim + espaces internes unifiés (sans forcer la casse). */
+export declare function tidyCityDisplay(city: string): string;
+/**
+ * Harmonise l’écriture avec le reste de l’arbre : même clé normalisée → libellé le plus fréquent
+ * (exclut l’acte en cours d’édition pour le décompte).
+ */
+export declare function findCanonicalCityLabel(ged: ReadGed, cityInput: string, excludeAct: Act | null): string;

package/dist/geocode/place-clusters.d.ts

@@ -0,0 +1,34 @@
+import type { Act } from "../commons/Act";
+import type { ReadGed } from "../import/ReadGed";
+import { type GeocodeCandidate } from "./place-geocode";
+export interface CoordVariant {
+    readonly lat: number;
+    readonly lng: number;
+    readonly actCount: number;
+}
+/** Groupe de lieux similaires à harmoniser (libellés ou coordonnées divergents). */
+export interface CityHarmonizationCluster {
+    readonly clusterKey: string;
+    readonly labels: readonly string[];
+    readonly coordVariants: readonly CoordVariant[];
+    readonly acts: readonly Act[];
+    readonly actsWithoutCoord: number;
+}
+/** Distance de Levenshtein (petites chaînes de noms de villes). */
+export declare function levenshteinDistance(a: string, b: string): number;
+/** Ville proche : même clé, faute légère, ou inclusion évidente (Saint-X / St-X). */
+export declare function citiesAreSimilar(a: string, b: string): boolean;
+/**
+ * Regroupe les actes dont les villes se ressemblent (libellés uniques + clés normalisées).
+ * Complexité ~ O(m²) sur le nombre de villes distinctes, pas sur le nombre d’actes.
+ */
+export declare function findHarmonizationClustersFromActs(acts: readonly Act[]): CityHarmonizationCluster[];
+/** Analyse toute l’arbre (préférer {@link findHarmonizationClustersFromActs} sur un sous-ensemble). */
+export declare function findHarmonizationClusters(ged: ReadGed): CityHarmonizationCluster[];
+export declare function applyCoordinatesToActs(acts: readonly Act[], lat: number, lng: number, patch?: {
+    city?: string;
+    country?: string | null;
+}): void;
+export declare function applyGeocodeCandidateToActs(acts: readonly Act[], candidate: GeocodeCandidate, preferredCityLabel?: string): void;
+/** Clé de regroupement carte : villes similaires → un marqueur. */
+export declare function clusterKeyForCity(city: string): string;

package/dist/geocode/place-geocode.d.ts

@@ -0,0 +1,50 @@
+import type { ReadGed } from "../import/ReadGed";
+/** Résultat Nominatim présenté à l’utilisateur. */
+export interface GeocodeCandidate {
+    readonly label: string;
+    readonly shortLabel: string;
+    readonly lat: number;
+    readonly lng: number;
+    readonly country: string | null;
+    readonly countryCode: string | null;
+    readonly region: string | null;
+    readonly kind: string | null;
+    readonly importance: number;
+}
+export interface GeocodeContext {
+    /** Codes ISO 3166-1 alpha-2 (ex. `fr`), du plus au moins probable. */
+    readonly countryCodes: readonly string[];
+    readonly defaultCountryLabel: string | null;
+    readonly centroid: {
+        lat: number;
+        lng: number;
+    } | null;
+}
+export type GeocodeFetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface GeocodeSearchOptions {
+    readonly countryCodes?: readonly string[];
+    readonly limit?: number;
+    /** Défaut : `gedcom-ts/<version> (genealogy library)` */
+    readonly userAgent?: string;
+    /** Client HTTP injectable (tests, Node sans fetch global). */
+    readonly fetchFn?: GeocodeFetchFn;
+}
+export declare const NOMINATIM_SEARCH_URL = "https://nominatim.openstreetmap.org/search";
+export declare function defaultGeocodeUserAgent(): string;
+/** Parse « Valence », « Valence, Drôme », « Valence, France ». */
+export declare function parseCityQuery(raw: string): {
+    city: string;
+    countryHint: string | null;
+};
+export declare function countryLabelToIso(label: string): string | null;
+export declare function isoToCountryLabel(code: string | null | undefined): string | null;
+/** Contexte géographique déduit de l’arbre (pays et centroïde des lieux déjà géolocalisés). */
+export declare function inferGeocodeContext(ged: ReadGed | null): GeocodeContext;
+export declare function buildGeocodeQuery(cityInput: string, context: GeocodeContext, extraCountryHint?: string | null): string;
+/** Priorise le pays saisi par l’utilisateur pour filtre Nominatim et classement. */
+export declare function geocodeContextWithHint(context: GeocodeContext, extraCountryHint?: string | null): GeocodeContext;
+/** Trie les candidats : pays de l’arbre, proximité du centroïde, correspondance du nom. */
+export declare function rankGeocodeCandidates(candidates: GeocodeCandidate[], cityInput: string, context: GeocodeContext): GeocodeCandidate[];
+export declare function searchPlaces(query: string, options?: GeocodeSearchOptions): Promise<GeocodeCandidate[]>;
+/** Recherche avec repli sans filtre pays si trop peu de résultats. */
+export declare function searchPlacesWithContext(cityInput: string, context: GeocodeContext, extraCountryHint?: string | null, options?: GeocodeSearchOptions): Promise<GeocodeCandidate[]>;

package/dist/import/PreservedRecordsBuffer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Liste interne des blocs `0 …` conservés pour diagnostic / round-trip (hors `0 TRLR`).
+ */
+export declare class PreservedRecordsBuffer {
+    private readonly items;
+    get length(): number;
+    /** Vue en lecture seule (référence au tableau interne, comme l’ancien `_preservedTopLevelRecords`). */
+    asReadonly(): readonly string[];
+    at(index: number): string | undefined;
+    /**
+     * Ajoute le bloc tel quel (sauf filtre `0 TRLR`), pour l’ingestion GEDCOM — aligné sur l’ancien `preserveTopLevelRecord`.
+     */
+    appendRaw(block: string): void;
+    append(block: string): void;
+    insertAt(index: number, block: string): void;
+    replaceAt(index: number, block: string): void;
+    removeAt(index: number): void;
+    clear(): void;
+    /** Retire l’élément à l’index sans normalisation (usage interne parse / absorb). */
+    spliceRemoveAt(index: number): void;
+}

package/dist/import/ReadGed.d.ts

@@ -53,6 +53,12 @@ export declare class ReadGed extends SplitGedcom {
     getChildrenForParent(parent: Person): Person[];
     /** Enfants d’une famille donnée (identifiant interne `F`, ex. `0` pour `@F0000@`). */
     getChildrenOfFamily(familyId: number): Person[];
+    /**
+     * Reconstruit {@link placesMap} à partir des lieux des actes (après édition du graphe).
+     * Préférez la façade `editReadGed` pour les mutations ; cette méthode est utile si vous modifiez
+     * les personnes hors façade.
+     */
+    rehydratePlacesFromActs(): void;
     private haveParentsOfPerson;
     private createPersons;
     /**

package/dist/import/SplitedInformations.d.ts

@@ -11,8 +11,14 @@ export declare class SplitGedcom {
      * numérique, etc.). Conservés dans l’ordre du fichier pour diagnostic ou futur re‑export.
      * `0 TRLR` n’est pas conservé (terminaison standard).
      */
-    private readonly _preservedTopLevelRecords;
+    private readonly preservedRecords;
     get preservedTopLevelRecords(): readonly string[];
+    /** Ajoute un bloc `0 …` complet (multi-lignes) en fin de liste préservée. */
+    appendPreservedTopLevelRecord(block: string): void;
+    insertPreservedTopLevelRecordAt(index: number, block: string): void;
+    replacePreservedTopLevelRecordAt(index: number, block: string): void;
+    removePreservedTopLevelRecordAt(index: number): void;
+    clearPreservedTopLevelRecords(): void;
     constructor(gedcomContent?: string);
     protected ingestGedcomText(gedcomContent: string): void;
     protected ingestGedcomFileStream(file: File): Promise<void>;