gedcom-ts 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,222 @@
+# Changelog
+
+All notable changes of gedcom-ts
+
+## [Unreleased]
+
+## [2.1.0] - 2026-05-13
+
+### Highlights
+
+- Major GEDCOM 7 coverage push: round-trip preservation (`preservedTopLevelRecords`, label-keyed FAM / NOTE xrefs, level-0 `OBJE`), richer `HEAD` export options, full P1.4 dates and places (INT/EST/CAL, `3 PHRASE`, `3 TIME`, `2 SDATE`, `2 PHRASE` event-level, ISO date input, verbatim fallback).
+- New **fluent edit layer** (`editPerson`, `editAct`, `editActs`, `editDateAct`, `editPlace`, `editNotes` + `*Edit` classes) for in-place model mutations with chainable APIs.
+- **README fully rewritten** with a complete public-API reference and a link to the live graphical demo at **[https://gedcomts.jaunet.me](https://gedcomts.jaunet.me)**.
+
+### Added
+
+#### Import
+
+- `ReadGed.preservedTopLevelRecords`: top-level `0 …` GEDCOM records that are not loaded into the typed model (e.g. `REPO`, `SOUR`, `SUBM`, and undecodable `OBJE`) are preserved in file order. `0 TRLR` is not stored.
+- **FAM / `@N` xrefs non numériques** : enregistrements `0 @F…@ FAM` et `0 @N…@ NOTE|SNOTE` indexés par libellé puis mappés vers des ids internes numériques (comme pour les `INDI` textuels) ; `FAMS` / `FAMC` / notes résolus via tables de pointeurs.
+- **OBJE de niveau 0** : si le bloc contient un `FILE` exploitable, il est retiré de `preservedTopLevelRecords` et sert à hydrater `MultimediaFile.sourceUri` pour les pointeurs `1 OBJE` / `2 OBJE` (`PersonGedcomImportOptions` / résolution interne dans `ReadGed`).
+- **Import actes (FAM)** : `1 HUSB` / `1 WIFE` avec pointeur `@I{n}@` **ou** xref textuelle `@Libellé@` (même clé que `0 @Libellé@ INDI`) alimentent les participants des actes extraits (`extractActEntriesAndIndis`).
+- `ReadGed.resolveIndividualPointer(raw)`, `ReadGed.getChildrenForParent(parent)`, `ReadGed.getChildrenOfFamily(familyId)` exposés publiquement pour naviguer le graphe importé.
+
+#### Export
+
+- `GedcomExportOptions` enrichies : `extraTopLevelRecords` (round-trip), `headLanguageTag`, **`headCopyright`** (`1 COPR`), **`headDestination`** (`1 DEST`), **`headSchemaTagDefs`** (`HEAD`.`SCHMA` / `2 TAG …`).
+- `HEAD`.`SOUR` structuré : émission de **`2 VERS`** + **`2 NAME`** sous `SOUR`, en plus du `CHAR` / `LANG` standard.
+- Constante **`GEDCOM_LIBRARY_VERSION`** (`src/version.ts`, alignée sur `package.json` via test) utilisée pour `2 VERS` à l’export.
+- **FAM** : sexes U / X / indéfini sont exportés en **`1 HUSB`** (placeholder GEDCOM moins biaisé que `WIFE`).
+
+#### Domain model — dates, places, events (P1.4)
+
+- **`DateAct`** :
+  - qualificateurs **INT**, **EST**, **CAL** ;
+  - phrase finale `(...)` et **`datePhrase`** ;
+  - import **`3 PHRASE`** sous `DATE` ;
+  - **`3 TIME`** sous `DATE` / **`SDATE`** (`dateTime`) ;
+  - entrée date **`YYYY-MM-DD`** / **`YYYY-MM`** ;
+  - **`verbatimDatePayload`** pour charges non typées (URI, texte hors parseur) ;
+  - tolérance `(...)` sur les bornes d’intervalles (`parseCoreDateValue`) ;
+  - format mois/année slash strict **`d{1,2}/d{2,4}`** uniquement (évite les faux positifs sur URL).
+- **`Act`** :
+  - **`2 SDATE`** (+ sous-lignes) sur `sdateAct` ;
+  - **`2 PHRASE`** niveau événement (`eventPhrases`) ;
+  - **`preservedSubrecordPrefix`** / **`preservedSubrecordSuffix`** pour sous-lignes non modélisées (`HUSB`/`AGE`/`4 PHRASE`, `3 DATE` sous `STAT`, …) avec ré-export ;
+  - tri des actes : **`DATE`** sinon **`SDATE`** valide.
+- **`Place`** : **`placPhrase`** et import **`3 PHRASE`** direct sous `PLAC` ; export **`3 PHRASE`** pour date et lieu quand présents ; export **`3 TIME`** / blocs **`SDATE`** / **`2 PHRASE`** événement.
+
+#### Fluent edit layer
+
+- Nouveau module `src/edit/` réexporté depuis la racine du paquet :
+  - **`editPerson`** / `PersonEdit` (identité, liens `FAMC` / `FAMS`, name variants, attributes, accès chaîné à `acts()` / `notes()`) ;
+  - **`editActs`** / `ActsEdit` (add, replaceAt, removeAt, clear, sortByDate, at) ;
+  - **`editAct`** / `ActEdit` (type, indis, date, sdate, place, EVEN, phrases, preserved prefix/suffix) ;
+  - **`editDateAct`** / `DateActEdit` (clear, applyGedcomPayload, setExactDate, setQualified, setBetween, setFromTo, setTime, setDatePhrase, setVerbatimPayload) ;
+  - **`editPlace`** / `PlaceEdit` (city/county/state/country, GEDCOM 7 payload, placPhrase, coordinates) ;
+  - **`editNotes`** / `NotesEdit` (add, replaceAt, removeAt, clear) ;
+  - chaînage cohérent (`this`) sur le modèle existant, mutation in-place.
+
+#### Public API surface
+
+- Types exportés : `PersonGedcomImportOptions`, `GedcomExportOptions`, `TypeDateActSimpleQualifier`, `Gedcom7EventTag`, `IndiGedcomSubLine`, `GedcomDatasetVersion`.
+- Classes / valeurs réexportées depuis l’index : `PersonNameVariant`, `PersonNameTranslation`, `IndiAttribute`, `ActConstructionOptions`, `GEDCOM_7_ALL_EVENT_TAGS`, `GEDCOM_7_EVENT_SORT_ORDER`, `GEDCOM_7_EVENT_TAG_SET`, `selectPrimaryNameVariant`, `extractPersonNameVariants`, `extractIndiAttributes`, `createEmptyReadGed`, `IMPORT_ERR_ZIP_GED_UNREADABLE`, **`GEDCOM_LIBRARY_VERSION`**.
+
+#### Tests
+
+- **Golden export** : fixture `tests/fixtures/golden-in/marriage-marr-roundtrip.ged` + fichiers attendus `tests/fixtures/golden-out/*.golden.txt` ; `tests/import/goldenMarrExport.spec.ts` verrouille le bloc `1 MARR` exporté (fixture minimale + extrait `maximal70` pour `@I1@`) et l’idempotence import → export → import.
+- Non-régression `ReadGed.groupPartners()` appelée plusieurs fois (les enfants et conjoints ne sont plus dupliqués).
+
+#### Documentation
+
+- **README intégralement réécrit** : référence complète de l’API publique (un sous-titre par export de `src/index.ts`), tables synthétiques pour `ReadGed`, `GedcomExportOptions` et la couche `*Edit`, exemples mis à jour pour chaque type / classe / fonction exposés.
+- Mention en tête du README du **site de démo graphique** : **[https://gedcomts.jaunet.me](https://gedcomts.jaunet.me)**.
+
+### Changed
+
+- Export `FAM` : sexe inconnu / non binaire / absent (`U`, `X`, `undefined`) émet **`1 HUSB`** au lieu de **`1 WIFE`** pour le rôle conjoint (placeholder GEDCOM moins biaisé).
+
+### Fixed
+
+- Export GEDCOM : terminaison correcte `0 TRLR` avec saut de ligne (au lieu du seul tag `TRLR`).
+- **`ReadGed.groupPartners()`** : les cartes `partnersMap` et `childsMap` sont vidées avant reconstruction, afin que des rappels successifs (après édition des liens en mémoire) ne dupliquent plus conjoints ni enfants.
+
+## [2.0.4] - 2026-05-11
+
+### Added
+
+- GEDCOM 7–oriented export: default `SUBM` pointer in `HEAD` and a minimal `@U1@ SUBM` record before `TRLR`.
+- `Place` supports structured locality fields (`county`, `state`, `country`) and comma-separated `PLAC` payloads aligned with the default `HEAD`.`PLAC`.`FORM`.
+- Event and person media: `FILE` with `https?://` URIs without a local `File`; optional `OBJE @O{n}@` pointers with generated `0 @O{n}@ OBJE` records when `MultimediaFile.sourceUri` and `objeXrefId` are set.
+- Import of `2 OBJE @O{n}@` under individual events (same model as level-1 `OBJE` on `INDI`).
+- `guessMediaFormFromUri()` exported from the package entrypoint (MIME guess for `OBJE`.`FILE`.`FORM`).
+- `resolveDatasetVersion` / `GedcomDatasetVersion` and GEDCOM 7 event tag constants (`GEDCOM_7_ALL_EVENT_TAGS`, etc.) on the public API.
+- Tests: `gedcom7Export`, `mediaFormFromUri`, `datasetVersion`, import smoke test against the gedcom.io `maximal70.ged` sample (file added to the repo for CI).
+
+## [2.0.2] - 2026-05-11
+
+### Fixed
+
+- Sorting of undated acts now follows the expected genealogical order:
+  - `BIRT`, `CHR`, `MARR`, `DIV`, `DEAT`, `BURI`
+- Undated/invalid dates are now handled consistently during sorting to avoid `BURI` appearing first.
+- Month comparison now treats unknown months as later than known months for stable ordering.
+- Added non-regression tests for invalid dates and undated act type ordering.
+
+## [2.0.1] - 2026-05-06
+
+### Changed
+
+- Removed `file-saver` dependency.
+
+## [2.0.0] - 2026-05-05
+
+### Highlights
+
+- Major modernization of GEDCOM import/export and typed genealogy models.
+- Better media lifecycle for acts and persons, including ZIP path reliability.
+- New build and quality toolchain (esbuild, ESLint, Vitest).
+- Fully rewritten technical documentation and improved package metadata.
+
+### Added
+
+- New domain models and helpers:
+  - `Person` model replacing previous `People` flow
+  - `MultimediaFile` / `MultimediaFiles`
+  - `Note` / `Notes`
+  - `ActsByYear` / `EventsByYears`
+  - GED helpers (`parseGedcomLine`, note formatting, media path utilities, Sosa and INDI helpers)
+- New import entrypoint for GED and ZIP: `importGedFile`.
+- ZIP export support with media path strategy for acts:
+  - single INDI: `INDI/TYPE/file`
+  - multi-INDI: `media/events/indi1-indi2/TYPE/file`
+- Dedicated loader/parser components:
+  - `LoadFile`
+  - `SplitedInformations`
+- `LICENSE` file added and package license reference aligned (`SEE LICENSE IN LICENSE`).
+- New test suites for core domains and export behavior:
+  - `tests/commons/Act.spec.ts`
+  - `tests/commons/Person.spec.ts`
+  - `tests/export/GEDCOM.spec.ts`
+  - `tests/utils/nextAvailableRelativeMediaPath.spec.ts`
+
+### Changed
+
+- Full build migration to esbuild (`build.js`) and webpack removal.
+- Test stack migrated from Jest to Vitest (`vitest.config.ts`) with `jsdom`.
+- Build output now minified (esbuild minification + tree-shaking, ES2020 target).
+- Obfuscation pipeline introduced with a moderated profile compatible with modern front-end apps.
+- ZIP generation now uses `DEFLATE` compression level `9`.
+- README rewritten with dedicated sections:
+  - Import
+  - Utilisation
+  - Export
+  - public API examples for all exports from `src/index.ts`
+- Package metadata improved (`description`, `keywords`) for npm discoverability.
+- CI/config/tooling updates (`.gitlab-ci.yml`, `.npmignore`, `.gitignore`, `tsconfig.json`, eslint config).
+
+### Fixed
+
+- ZIP export no longer misses act media directories in edge cases.
+- Fallback media path handling fixed to prevent `undefined/...` directories.
+- GED `FILE` lines are now consistent with real ZIP archive paths.
+- Import robustness improved:
+  - fallback to `file.text()` when `File.stream()` is unavailable
+  - more reliable GED record block parsing (`0 ...` headers preserved and detected)
+- Multiple reliability fixes around acts, notes, places and media handling.
+
+## [1.0.9] - 2023-06-16
+
+### Added
+
+- support multiple FAMS
+
+## [1.0.8] - 2023-06-15
+
+### Added
+
+- all right reserved - proprietary code explicit in licence package
+
+## [1.0.7] - 2023-06-15
+
+### Added
+
+- FAMS and FAMC are exported
+
+## [1.0.6] - 2023-06-15
+
+### Added
+
+- export birth and death date and place
+
+## [1.0.5] - 2023-06-10
+
+### Added
+
+- act birth and death
+
+## [1.0.4] - 2020-03-10
+
+### Added
+
+- read FAMS (code for two parents) and FAMC (code for childs). It's same code between them.
+- read Sex with two possibilities: M or F
+- group partnersMap, it's a map for all parents
+- jest / test in Person / runner
+- createDirectAncestries
+
+
+## 1.0.3 - 2019-10-01
+
+### Added
+
+- add import gedcom file and return a JSON data model of an array of Person. It just extract names and firstnames
+
+## 1.0.2-alpha - 2019-09-01
+
+### Added
+ 
+- export for birth and death in gedcom
+- All identificators can be used for a developper. It's an enum of properties used for all gedcom
+- City is removed and replaced by Place. Place gets more informations