@finbheara/names 0.15.0 → 0.17.0

package/README.md

@@ -145,8 +145,10 @@ name cells, one per line. The specification is `docs/NAME-NORMALIZATION.md`.
 ### How two names are related
 
 ```ts
-import { createNameIndex, createNameKinship, givenFamilyTable, nameKinship, personName }
-  from "@finbheara/names/normalize";
+import {
+  createGivenFamilyList, createNameIndex, createNameKinship, givenFamilyTable, nameKinship,
+  personName,
+} from "@finbheara/names/normalize";
 
 nameKinship(personName("Kate Smith"), personName("Katherine Smith"));
 // { relation: "candidate", via: ["given-family"], reason: "middles-equal", gateSafe: true }
@@ -157,13 +159,16 @@ nameKinship(personName("Kate M Smith"), personName("Katherine Conley-Smith")).vi
 nameKinship(personName("Connor Smith"), personName("Conor Smith")).via;       // ["given-variant"]
 nameKinship(personName("Evie Smith"), personName("Genevieve Smith"));
 // { relation: "candidate", via: ["given-family-not-gate"], reason: "middles-equal", gateSafe: false }
+nameKinship(personName("Beth Smith"), personName("Bethany Smith"));   // the extended family list
+// { relation: "candidate", via: ["given-maybe"], reason: "middles-equal", gateSafe: false }
 
 // the given-name tolerance is a list of providers, asked in order
-const withMaybe = createNameKinship({
-  given: [givenFamilyTable, (a, b) => (a === "NAIMH" && b === "NIAMH" ? "given-maybe" : null)],
+const tableOnly = createNameKinship({ given: [givenFamilyTable] });
+tableOnly(personName("Beth Smith"), personName("Bethany Smith")).reason;  // "given-differs"
+const common = createNameKinship({
+  given: [givenFamilyTable, createGivenFamilyList({ maxTier: 1 })],  // common forms only
 });
-withMaybe(personName("Naimh Smith"), personName("Niamh Smith"));
-// { relation: "candidate", via: ["given-maybe"], reason: "middles-equal", gateSafe: false }
+common(personName("Maggie Smith"), personName("Marjorie Smith")).reason;  // "given-differs"
 
 const index = createNameIndex<number>("nn3");   // a NameMap with a tolerant lookup
 index.set(personName("Mary Conley-Larson"), 1).set(personName("Mary Carlson"), 2);
@@ -175,6 +180,39 @@ index.related(personName("Mary Larson"));        // [{ name: Conley-Larson<<Mary
 tolerance the pair used, and `gateSafe` is false when any of them is one a gate must not
 admit on its own.
 
+### The given-name tables, for another language
+
+The tables behind `givenFamilyTable` and `givenFamilyList` print as JSON, for a consumer
+that is not JavaScript:
+
+```sh
+npx @finbheara/names tables given-name > given-name-tables.json   # or bunx
+```
+
+`--output json` and `--schema 1` are the defaults. The PRINTED form is the contract: a
+schema keeps its shape for as long as the package offers it, and a new shape is a new
+schema, so a command written today keeps working. The files the tables are stored in are
+not part of it. Schema 1 is
+
+```jsonc
+{
+  "$comment": [ /* how to read it */ ],
+  "table": "given-name", "schema": 1,
+  "variants":  { "CONNOR": ["CONOR"], … },        // canonical -> its other spellings
+  "families":  { "CATHERINE": ["KATE", …], … },   // the curated gate tier: root -> forms
+  "notAtGate": ["MEGAN", …],                      // forms a gate must not admit as forms
+  "extended":  { "BETHANY": { "BETH": 1 }, … }    // root -> form -> tier (1 common .. 3 rare)
+}
+```
+
+Read it as the library does, and as `$comment` says: read each name as its canonical
+spelling first; two names relate only when they share a root, a form meets EVERY root it
+sits under, and nothing is transitive (`EVIE` meets `EVE` and `EVA`, which do not meet each
+other). A shared root is `given-family` unless one name reaches it only as a `notAtGate`
+form; a name that is the root itself always passes. An `extended` pair's tier is its rarer
+member's, the root counting as 1. To avoid comparing every pair, index each name under
+every root it has and compare within a root, never on one root per name.
+
 ## Phonetic and blocking keys
 
 ```ts
@@ -242,6 +280,7 @@ given name. Flags are case-sensitive and combine (`Kelly:AF`, `New York:BG`).
 | `B` | multi-word entry (bigram or trigram) |
 | `S` | a known typo, kept so it is recognised |
 | `X` | excluded from the display renderer's round-trip check |
+| `D` | a given name a diminutive table holds (`Kate:FD`); a mark, like `S` and `X` |
 
 A digit after `L` or `A` is a **tradition footnote**: `1` Armenian, `2` Germanic,
 `3` Iberian, `4` Irish/Gaelic, `5` Nordic, `6` Slavic (`Kowalski:L6`). An index is