@finbheara/names 0.9.1 → 0.10.0

package/README.md

@@ -26,7 +26,7 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT.
 
 ## Entry points
 
-Import only what you use; `/lexicon`, `/particles` and `/normalize` never load the
+Import only what you use; `/lexicon`, `/particles`, `/normalize` and `/phonetic` never load the
 classifier's bloom tables.
 
 | import | what |
@@ -35,6 +35,7 @@ classifier's bloom tables.
 | `@finbheara/names/lexicon` | `names.txt` parsed: flags, multi-word phrases, spellings, roles |
 | `@finbheara/names/particles` | the particle vocabulary |
 | `@finbheara/names/classifier` | person / school / location classification and segmentation |
+| `@finbheara/names/phonetic` | Double Metaphone: how a word sounds, as a key |
 | `@finbheara/names/measure` | the census and the classifier evaluation |
 | `@finbheara/names` | all of the above |
 | `@finbheara/names/names.txt` | the raw lexicon |
@@ -141,6 +142,42 @@ The verdict is a declaration the caller makes about a document; grouping rows in
 documents is the caller's. `bun run names order <file>` prints the same for a file of
 name cells, one per line. The specification is `docs/NAME-NORMALIZATION.md`.
 
+## Phonetic and blocking keys
+
+```ts
+import { doubleMetaphone } from "@finbheara/names/phonetic";
+import { initialsBlock, metaphoneBlocks, personName, surnameBlock } from "@finbheara/names/normalize";
+
+doubleMetaphone("SMITH");      // ["SM0", "XMT"]  primary, secondary
+doubleMetaphone("KAVANAGH");   // ["KFNK", "KFNK"]
+
+const n = personName("Moira O'Rervton");
+surnameBlock(n.surnameKey());                     // "ORERVTON"  A-Z letters only
+metaphoneBlocks(n.surnameKey());                  // ["ARRF"]
+initialsBlock(n.givenFields()[0] ?? "", n.surnameKey());  // "MO"
+```
+
+`doubleMetaphone` is a general phonetic key: a printed name and a transcribed spoken
+word are asked the same question. The three block keys bucket names that are worth
+comparing and decide nothing; each answers `null` (or `[]`) where there is nothing to
+bucket on, so a self-join never pools the blanks.
+
+### A name as database columns
+
+```ts
+import { NAME_COLUMNS, nameColumns, personName } from "@finbheara/names/normalize";
+
+NAME_COLUMNS;  // ["nn0", …, "nn4", "surname_key", "given_key", "blk_surname", "blk_initials",
+               //  "blk_metaphone", "blk_metaphone_alt"]
+nameColumns(personName("Moira O'Rervton"));
+// { nn0: "Moira O'Rervton", …, nn3: "ORERVTON<<MOIRA", surname_key: "ORERVTON",
+//   given_key: "MOIRA", blk_surname: "ORERVTON", blk_initials: "MO", blk_metaphone: "ARRF", … }
+```
+
+One encoder for every key a store indexes, with no database dependency. A level column
+is the slot `createNameMap` files a name under, `null` for a print that names no person,
+so a map lookup at a level is one equality on one column.
+
 ## The lexicon
 
 ```ts

package/dist/chunks/{index-b2k3er3h.js → index-7sppf1vh.js}

@@ -3,7 +3,13 @@ import {
   isGiven2,
   isAmbiguous2,
   Lexicon2
-} from "./index-0qptxnwh.js";
+} from "./index-7vvt5hhy.js";
+import {
+  isPlaceWordFlags
+} from "./index-kw6gbrnq.js";
+import {
+  doubleMetaphone2
+} from "./index-ebebeamh.js";
 import {
   nameFold2,
   isPlaceholderPrint2,
@@ -13,10 +19,7 @@ import {
   commaReading2,
   levelOf2,
   defaultPersonNameFactory2
-} from "./index-fzzq5txh.js";
-import {
-  isPlaceWordFlags
-} from "./index-2fsdvhaf.js";
+} from "./index-khxa4qjy.js";
 import {
   isTeamPrint2
 } from "./index-0phgwy52.js";
@@ -94,11 +97,14 @@ var given_diminutives_default = {
     "the two names."
   ],
   families: {
+    ABIGAIL: ["ABBY", "ABBIE"],
     AIDAN: ["AIDEN", "AODHAN", "AIDY"],
     ALEXANDER: ["ALEX", "ALEC", "SANDY", "XANDER", "ALEXANDRA", "ALEXA", "LEXI", "LEXIE"],
+    AMANDA: ["MANDY"],
     ANDREW: ["ANDY"],
     ANNE: ["ANN", "ANNA", "ANNIE", "NANCY", "NAN", "ANYA"],
     ANTHONY: ["TONY"],
+    BARBARA: ["BARB"],
     BRIDGET: ["BRIDIE", "BRID", "BRIGID", "BRIGHID", "BREDA", "BREEDA", "BIDDY"],
     CAITLIN: ["CAITLYN", "KAITLIN", "KAITLYN", "KATELYN", "CAIT"],
     CATHERINE: [
@@ -119,13 +125,18 @@ var given_diminutives_default = {
     CHRISTOPHER: ["CHRIS", "KIT", "TOPHER"],
     CIARA: ["KIERA", "KEIRA", "CIARRA"],
     CIARAN: ["KIERAN", "KEIRAN"],
+    CYNTHIA: ["CINDY"],
     DANIEL: ["DAN", "DANNY", "DANIELLE", "DANI"],
+    DEBORAH: ["DEBRA", "DEBBIE", "DEB"],
     DEIRDRE: ["DEE", "DIDI"],
+    DOROTHY: ["DOT", "DOTTIE"],
     EDWARD: ["ED", "EDDIE", "TED", "TEDDY", "NED"],
     EILEEN: ["EILISH", "EILIS", "AILEEN"],
     ELIZABETH: ["LIZ", "LIZZIE", "BETH", "BETSY", "BETTY", "ELIZA", "LIBBY", "ELSIE", "ELISE"],
     EOIN: ["OWEN", "EOGHAN"],
+    FIONNUALA: ["FIONNULA", "FINOLA", "NUALA"],
     FRANCIS: ["FRANK", "FRANKIE", "FRAN", "FRANCES"],
+    GILLIAN: ["GILL"],
     GRAINNE: ["GRANIA", "GRACE", "GRAINE"],
     JACQUELINE: ["JACKIE"],
     JAMES: ["JIM", "JIMMY", "JAMIE", "SEAMUS", "JAY"],
@@ -133,6 +144,7 @@ var given_diminutives_default = {
     JOHN: ["JACK", "JOHNNY", "SEAN", "SHANE", "JOHNNIE", "EOIN"],
     JOSEPH: ["JOE", "JOEY", "JOSEPHINE", "JO"],
     JUDITH: ["JUDY"],
+    KIMBERLY: ["KIMBERLEY", "KIM"],
     MARGARET: [
       "MAGGIE",
       "PEGGY",
@@ -150,8 +162,10 @@ var given_diminutives_default = {
     MICHAEL: ["MIKE", "MICK", "MICKEY", "MICHEAL", "MICHELLE", "MICHAELA"],
     NICHOLAS: ["NICK", "NICKY", "NICOLE", "NICOLA", "NIKKI"],
     NIAMH: ["NEVE", "NEEVE"],
+    PAMELA: ["PAM"],
     PATRICK: ["PAT", "PADDY", "PADRAIG", "PATSY", "PATRICIA", "TRICIA", "TRISH", "PATTY"],
     PETER: ["PETE", "PEADAR"],
+    PHILIPPA: ["PIPPA"],
     RAYMOND: ["RAY"],
     REBECCA: ["BECKY", "BECCA", "BEX"],
     RICHARD: ["RICK", "RICKY", "DICK", "RICH", "RICHIE"],
@@ -160,11 +174,15 @@ var given_diminutives_default = {
     SIOBHAN: ["SHIVAUN", "CHEVONNE", "SIOBHAIN"],
     STEPHEN: ["STEVEN", "STEVE", "STEPHANIE", "STEPH"],
     SUSAN: ["SUE", "SUSIE", "SUZANNE", "SUZY"],
+    TERESA: ["THERESA", "TESS"],
     THOMAS: ["TOM", "TOMMY", "TOMAS", "THOM"],
+    VICTORIA: ["VICKY", "VICKI"],
     VINCENT: ["VINNIE"],
     WILLIAM: ["WILL", "BILL", "BILLY", "WILLIE", "LIAM"]
   },
   notAtGate: [
+    "ABBIE",
+    "ABBY",
     "ALEXA",
     "ALEXANDRA",
     "ANNA",
@@ -187,6 +205,7 @@ var given_diminutives_default = {
     "JO",
     "JOSEPHINE",
     "KATHLEEN",
+    "KIM",
     "LEXI",
     "LEXIE",
     "LIAM",
@@ -206,6 +225,7 @@ var given_diminutives_default = {
     "NICOLA",
     "NICOLE",
     "NIKKI",
+    "NUALA",
     "OWEN",
     "PADRAIG",
     "PATRICIA",
@@ -221,6 +241,7 @@ var given_diminutives_default = {
     "STEPH",
     "STEPHANIE",
     "SUZANNE",
+    "TESS",
     "TOMAS",
     "TRICIA",
     "TRISH"
@@ -951,6 +972,67 @@ function personList2(print, factory = defaultPersonNameFactory2()) {
   }
   return out;
 }
+// src/normalize/block-keys.ts
+function blockLetters(surname) {
+  return surname.toUpperCase().replace(/[^A-Z]/g, "");
+}
+function firstLetter(s) {
+  const m = s.match(/[A-Za-z]/);
+  return m ? m[0].toUpperCase() : null;
+}
+function surnameBlock2(surname) {
+  return blockLetters(surname) || null;
+}
+function initialsBlock2(given, surname) {
+  const first = firstLetter(given);
+  const last = firstLetter(blockLetters(surname));
+  return first && last ? first + last : null;
+}
+function metaphoneBlocks2(surname) {
+  const letters = blockLetters(surname);
+  if (!letters)
+    return [];
+  const [primary, secondary] = doubleMetaphone2(letters);
+  if (!primary)
+    return [];
+  return secondary && secondary !== primary ? [primary, secondary] : [primary];
+}
+// src/normalize/name-columns.ts
+var NAME_LEVEL_COLUMNS2 = [
+  "nn0",
+  "nn1",
+  "nn2",
+  "nn3",
+  "nn4"
+];
+var NAME_COLUMNS2 = [
+  ...NAME_LEVEL_COLUMNS2,
+  "surname_key",
+  "given_key",
+  "blk_surname",
+  "blk_initials",
+  "blk_metaphone",
+  "blk_metaphone_alt"
+];
+function nameColumns2(name) {
+  const person = name.isPerson();
+  const level = (dop) => person ? name[dop] : null;
+  const surname = person ? name.surnameKey() : "";
+  const [metaphone, metaphoneAlt] = metaphoneBlocks2(surname);
+  return {
+    nn0: level("nn0"),
+    nn1: level("nn1"),
+    nn2: level("nn2"),
+    nn3: level("nn3"),
+    nn4: level("nn4"),
+    surname_key: surname || null,
+    given_key: person && name.givenName() || null,
+    blk_surname: surnameBlock2(surname),
+    blk_initials: person ? initialsBlock2(name.givenFields()[0] ?? "", surname) : null,
+    blk_metaphone: metaphone ?? null,
+    blk_metaphone_alt: metaphoneAlt ?? null
+  };
+}
 // src/normalize/name-format.ts
 var NAME_FORMATS2 = ["First Last", "Last, First", "Last First"];
 function nameFormatOrder2(verdict) {
@@ -1338,7 +1420,7 @@ function deriveNameFormat2(prints, options = {}) {
     return first;
   return scoreReadings(cells.map((c) => readNameCell2(c, { ...options, placeColumn: true })), NAME_FORMAT_MODEL, threshold, schoolRead);
 }
-export { repairMojibake2, sameGivenFamily2, comparePosition2, nameRelation2, nameCompare2, probablySame2, createNameSet2, createNameMap2, createNameClusters2, MAX_READINGS2, surnameParts2, printAttestsOrder2, nameReadings2, meetReading2, refinesReading2, sameReading2, chooseReadingPair2, composeReadings2, composeNames2, meetReadings2, nameMeet2, showReading2, blockKeysOfReadings2, nameBlockKeys2, namesFeasible2, INFEASIBLE_CLASSES2, editDistance2, nearSpelling2, compoundGiven2, middleForm2, infeasibleClass2, isListJoiner2, personList2, NAME_FORMATS2, nameFormatOrder2, ORDER_READINGS2, readNameCell2, DEFAULT_NAME_FORMAT_THRESHOLD2, deriveNameFormat2 };
+export { repairMojibake2, sameGivenFamily2, comparePosition2, nameRelation2, nameCompare2, probablySame2, createNameSet2, createNameMap2, createNameClusters2, MAX_READINGS2, surnameParts2, printAttestsOrder2, nameReadings2, meetReading2, refinesReading2, sameReading2, chooseReadingPair2, composeReadings2, composeNames2, meetReadings2, nameMeet2, showReading2, blockKeysOfReadings2, nameBlockKeys2, namesFeasible2, INFEASIBLE_CLASSES2, editDistance2, nearSpelling2, compoundGiven2, middleForm2, infeasibleClass2, isListJoiner2, personList2, surnameBlock2, initialsBlock2, metaphoneBlocks2, NAME_LEVEL_COLUMNS2, NAME_COLUMNS2, nameColumns2, NAME_FORMATS2, nameFormatOrder2, ORDER_READINGS2, readNameCell2, DEFAULT_NAME_FORMAT_THRESHOLD2, deriveNameFormat2 };
 
-//# debugId=82AC2FB0D34BD09D64756E2164756E21
-//# sourceMappingURL=index-b2k3er3h.js.map
+//# debugId=A39684B9543A024164756E2164756E21
+//# sourceMappingURL=index-7sppf1vh.js.map