@finbheara/names 0.15.0 → 0.16.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);
@@ -242,6 +247,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