@finbheara/names 0.12.0 → 0.13.0

package/README.md

@@ -142,6 +142,36 @@ 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`.
 
+### How two names are related
+
+```ts
+import { 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 }
+nameKinship(personName("Mary Larson"), personName("Mary Conley-Larson")).via;  // ["surname-part"]
+nameKinship(personName("Mary Larson"), personName("Mary Carlson")).reason;     // "surname-differs"
+nameKinship(personName("Kate M Smith"), personName("Katherine Conley-Smith")).via;
+// ["surname-part", "given-family", "middle-absent"]
+
+// the given-name tolerance is a list of providers, asked in order
+const withMaybe = createNameKinship({
+  given: [givenFamilyTable, (a, b) => (a === "EVIE" && b === "GENEVIEVE" ? "given-maybe" : null)],
+});
+withMaybe(personName("Evie Smith"), personName("Genevieve Smith"));
+// { relation: "candidate", via: ["given-maybe"], reason: "middles-equal", gateSafe: false }
+
+const index = createNameIndex<number>("nn3");   // a NameMap with a tolerant lookup
+index.set(personName("Mary Conley-Larson"), 1).set(personName("Mary Carlson"), 2);
+index.get(personName("Mary Larson"));            // undefined: get stays exact
+index.related(personName("Mary Larson"));        // [{ name: Conley-Larson<<Mary, value: 1, kinship: … }]
+```
+
+`candidate` is never a merge: it says two prints MAY be one person. `via` lists every
+tolerance the pair used, and `gateSafe` is false when any of them is one a gate must not
+admit on its own.
+
 ## Phonetic and blocking keys
 
 ```ts

package/dist/chunks/{index-vqbvesky.js → index-wq6kn9jq.js}

@@ -262,11 +262,28 @@ var ROOT = (() => {
 })();
 var NOT_AT_GATE = new Set(TABLE.notAtGate);
 function sameGivenFamily2(a, b) {
-  if (a === b || NOT_AT_GATE.has(a) || NOT_AT_GATE.has(b))
-    return false;
+  return givenFamilyTable2(a, b) === "given-family";
+}
+function givenFamilyTable2(a, b) {
+  if (a === b)
+    return null;
   const ra = ROOT.get(a);
-  return ra !== undefined && ra === ROOT.get(b);
+  if (ra === undefined || ra !== ROOT.get(b))
+    return null;
+  return NOT_AT_GATE.has(a) || NOT_AT_GATE.has(b) ? "given-family-not-gate" : "given-family";
 }
+// src/normalize/multiset.ts
+function subMultiset(outer, inner) {
+  const left = [...inner];
+  for (const part of outer) {
+    const at = left.indexOf(part);
+    if (at < 0)
+      return false;
+    left.splice(at, 1);
+  }
+  return true;
+}
+
 // src/normalize/name-middle.ts
 function suffixCut(p) {
   return Math.max(1, p.givenFields().length - p.suffixes.length);
@@ -298,6 +315,9 @@ function nameRelation2(a, b) {
   if (a.surnameKey() !== b.surnameKey() || ga[0] !== gb[0] || ga[0] === undefined) {
     return { relation: "different", reason: "head-differs" };
   }
+  return tailRelation(a, b);
+}
+function tailRelation(a, b) {
   if (!sameList(suffixFields(a), suffixFields(b))) {
     return { relation: "different", reason: "suffixes-differ" };
   }
@@ -318,138 +338,6 @@ function nameRelation2(a, b) {
   return { relation: "candidate", reason: "initial-agrees" };
 }
 
-// src/normalize/name-compare.ts
-function nameCompare2(a, b, dop) {
-  const x = levelOf2(a, dop);
-  const y = levelOf2(b, dop);
-  if (x < y)
-    return -1;
-  return x > y ? 1 : 0;
-}
-function probablySame2(a, b, dop) {
-  if (!a.isPerson() || !b.isPerson())
-    return false;
-  if (dop === "nn5")
-    return nameRelation2(a, b).relation !== "different";
-  return levelOf2(a, dop) === levelOf2(b, dop);
-}
-function slotOf(name, dop) {
-  return name.isPerson() ? levelOf2(name, dop) : null;
-}
-var loner = 0;
-var lonerSlot = () => `\x1F\x1F${loner++}`;
-function createNameSet2(dop) {
-  const held = new Map;
-  const set = {
-    dop,
-    get size() {
-      return held.size;
-    },
-    get: (name) => {
-      const slot = slotOf(name, dop);
-      return slot === null ? undefined : held.get(slot);
-    },
-    has: (name) => {
-      const slot = slotOf(name, dop);
-      return slot === null ? false : held.has(slot);
-    },
-    add(name) {
-      const slot = slotOf(name, dop);
-      if (slot === null)
-        held.set(lonerSlot(), name);
-      else if (!held.has(slot))
-        held.set(slot, name);
-      return this;
-    },
-    delete: (name) => {
-      const slot = slotOf(name, dop);
-      return slot === null ? false : held.delete(slot);
-    },
-    clear: () => held.clear(),
-    values: () => held.values(),
-    [Symbol.iterator]: () => held.values()
-  };
-  return set;
-}
-function createNameMap2(dop, entries) {
-  const held = new Map;
-  const map = {
-    dop,
-    get size() {
-      return held.size;
-    },
-    get: (name) => {
-      const key = slotOf(name, dop);
-      return key === null ? undefined : held.get(key)?.[1];
-    },
-    has: (name) => {
-      const key = slotOf(name, dop);
-      return key === null ? false : held.has(key);
-    },
-    set(name, value) {
-      const key = slotOf(name, dop);
-      const slot = key === null ? undefined : held.get(key);
-      if (slot === undefined)
-        held.set(key ?? lonerSlot(), [name, value]);
-      else
-        slot[1] = value;
-      return this;
-    },
-    delete: (name) => {
-      const key = slotOf(name, dop);
-      return key === null ? false : held.delete(key);
-    },
-    clear: () => held.clear(),
-    *keys() {
-      for (const [name] of held.values())
-        yield name;
-    },
-    *values() {
-      for (const [, value] of held.values())
-        yield value;
-    },
-    *entries() {
-      for (const slot of held.values())
-        yield [slot[0], slot[1]];
-    },
-    [Symbol.iterator]() {
-      return this.entries();
-    }
-  };
-  for (const [name, value] of entries ?? [])
-    map.set(name, value);
-  return map;
-}
-function createNameClusters2(dop, linkage) {
-  if (dop === "nn5") {
-    throw new Error('createNameClusters at nn5 is unimplemented: a linkage is defined over a distance and NN5 answers a relation. Use nameRelation / probablySame(a, b, "nn5"); see docs/NAME-NORMALIZATION.md § NN5 — the middle-name relation.');
-  }
-  const transitive = dop;
-  const held = new Map;
-  const out = {
-    dop,
-    linkage,
-    get size() {
-      return held.size;
-    },
-    add(name) {
-      const key = slotOf(name, transitive);
-      const cluster = key === null ? undefined : held.get(key);
-      if (cluster === undefined)
-        held.set(key ?? lonerSlot(), [name]);
-      else
-        cluster.push(name);
-      return this;
-    },
-    clusterOf: (name) => {
-      const key = slotOf(name, transitive);
-      return key === null ? undefined : held.get(key);
-    },
-    clusters: () => [...held.values()],
-    [Symbol.iterator]: () => held.values()
-  };
-  return out;
-}
 // src/normalize/name-compose.ts
 var READER_RANK = ["as-parsed", "boundary", "order"];
 var VIA_ORDER = [
@@ -552,16 +440,6 @@ function meetMiddles(x, y) {
   }
   return out;
 }
-function subMultiset(outer, inner) {
-  const left = [...inner];
-  for (const part of outer) {
-    const at = left.indexOf(part);
-    if (at < 0)
-      return false;
-    left.splice(at, 1);
-  }
-  return true;
-}
 function meetSurname(x, y) {
   if (subMultiset(x, y))
     return y;
@@ -817,6 +695,305 @@ function foldUnder(prints, surname) {
     return mx - my || (slotKey(x) < slotKey(y) ? -1 : 1);
   })[0];
 }
+
+// src/normalize/name-kinship.ts
+var KINSHIP_VIAS2 = Object.freeze({
+  "surname-part": Object.freeze({ field: "surname", gateSafe: true }),
+  "given-family": Object.freeze({ field: "given", gateSafe: true }),
+  "given-family-not-gate": Object.freeze({ field: "given", gateSafe: false }),
+  "given-maybe": Object.freeze({ field: "given", gateSafe: false }),
+  "middle-absent": Object.freeze({ field: "middle", gateSafe: true }),
+  "initial-agrees": Object.freeze({ field: "middle", gateSafe: true })
+});
+var VIA_ORDER2 = Object.freeze(Object.keys(KINSHIP_VIAS2));
+var different = (reason) => ({
+  relation: "different",
+  via: [],
+  reason,
+  gateSafe: false
+});
+function surnamePartOf(a, b) {
+  const pa = surnameParts2(a);
+  const pb = surnameParts2(b);
+  if (pa.length === pb.length)
+    return false;
+  const [short, long] = pa.length < pb.length ? [pa, pb] : [pb, pa];
+  return subMultiset(short, long);
+}
+function createNameKinship2(options = {}) {
+  const providers = Object.freeze([
+    ...options.given ?? [givenFamilyTable2]
+  ]);
+  const givenVia = (x, y) => {
+    const [lo, hi] = x < y ? [x, y] : [y, x];
+    for (const provider of providers) {
+      const via = provider(lo, hi);
+      if (via !== null)
+        return via;
+    }
+    return null;
+  };
+  return (a, b) => {
+    if (!a.isPerson() || !b.isPerson())
+      return different("not-a-person");
+    const found = new Set;
+    if (a.surnameKey() !== b.surnameKey()) {
+      if (!surnamePartOf(a, b))
+        return different("surname-differs");
+      found.add("surname-part");
+    }
+    const ga = a.givenFields()[0];
+    const gb = b.givenFields()[0];
+    if (ga === undefined || gb === undefined)
+      return different("given-differs");
+    if (ga !== gb) {
+      const via = givenVia(ga, gb);
+      if (via === null)
+        return different("given-differs");
+      found.add(via);
+    }
+    const tail = tailRelation(a, b);
+    if (tail.relation === "different")
+      return different(tail.reason);
+    if (tail.relation === "candidate")
+      found.add(tail.reason);
+    const via = VIA_ORDER2.filter((v) => found.has(v));
+    return {
+      relation: via.length === 0 ? "same" : "candidate",
+      via,
+      reason: tail.reason,
+      gateSafe: via.every((v) => KINSHIP_VIAS2[v].gateSafe)
+    };
+  };
+}
+var nameKinship2 = createNameKinship2();
+
+// src/normalize/name-compare.ts
+function nameCompare2(a, b, dop) {
+  const x = levelOf2(a, dop);
+  const y = levelOf2(b, dop);
+  if (x < y)
+    return -1;
+  return x > y ? 1 : 0;
+}
+function probablySame2(a, b, dop) {
+  if (!a.isPerson() || !b.isPerson())
+    return false;
+  if (dop === "nn5")
+    return nameRelation2(a, b).relation !== "different";
+  return levelOf2(a, dop) === levelOf2(b, dop);
+}
+function slotOf(name, dop) {
+  return name.isPerson() ? levelOf2(name, dop) : null;
+}
+var loner = 0;
+var lonerSlot = () => `\x1F\x1F${loner++}`;
+function createNameSet2(dop) {
+  const held = new Map;
+  const set = {
+    dop,
+    get size() {
+      return held.size;
+    },
+    get: (name) => {
+      const slot = slotOf(name, dop);
+      return slot === null ? undefined : held.get(slot);
+    },
+    has: (name) => {
+      const slot = slotOf(name, dop);
+      return slot === null ? false : held.has(slot);
+    },
+    add(name) {
+      const slot = slotOf(name, dop);
+      if (slot === null)
+        held.set(lonerSlot(), name);
+      else if (!held.has(slot))
+        held.set(slot, name);
+      return this;
+    },
+    delete: (name) => {
+      const slot = slotOf(name, dop);
+      return slot === null ? false : held.delete(slot);
+    },
+    clear: () => held.clear(),
+    values: () => held.values(),
+    [Symbol.iterator]: () => held.values()
+  };
+  return set;
+}
+function createNameMap2(dop, entries) {
+  const held = new Map;
+  const map = {
+    dop,
+    get size() {
+      return held.size;
+    },
+    get: (name) => {
+      const key = slotOf(name, dop);
+      return key === null ? undefined : held.get(key)?.[1];
+    },
+    has: (name) => {
+      const key = slotOf(name, dop);
+      return key === null ? false : held.has(key);
+    },
+    set(name, value) {
+      const key = slotOf(name, dop);
+      const slot = key === null ? undefined : held.get(key);
+      if (slot === undefined)
+        held.set(key ?? lonerSlot(), [name, value]);
+      else
+        slot[1] = value;
+      return this;
+    },
+    delete: (name) => {
+      const key = slotOf(name, dop);
+      return key === null ? false : held.delete(key);
+    },
+    clear: () => held.clear(),
+    *keys() {
+      for (const [name] of held.values())
+        yield name;
+    },
+    *values() {
+      for (const [, value] of held.values())
+        yield value;
+    },
+    *entries() {
+      for (const slot of held.values())
+        yield [slot[0], slot[1]];
+    },
+    [Symbol.iterator]() {
+      return this.entries();
+    }
+  };
+  for (const [name, value] of entries ?? [])
+    map.set(name, value);
+  return map;
+}
+function kinshipBuckets(name) {
+  return [...new Set([name.surnameKey(), ...surnameParts2(name)])];
+}
+var RELATION_RANK = {
+  same: 0,
+  candidate: 1,
+  different: 2
+};
+function createNameIndex2(dop, options = {}) {
+  const kinship = options.kinship ?? nameKinship2;
+  const map = createNameMap2(dop);
+  const filed = new Map;
+  const buckets = new Map;
+  let seq = 0;
+  const file = (slot, name) => {
+    filed.set(slot, { name, seq: seq++ });
+    for (const key of kinshipBuckets(name)) {
+      const slots = buckets.get(key);
+      if (slots === undefined)
+        buckets.set(key, new Set([slot]));
+      else
+        slots.add(slot);
+    }
+  };
+  const unfile = (slot) => {
+    const held = filed.get(slot);
+    if (held === undefined)
+      return;
+    filed.delete(slot);
+    for (const key of kinshipBuckets(held.name)) {
+      const slots = buckets.get(key);
+      slots?.delete(slot);
+      if (slots?.size === 0)
+        buckets.delete(key);
+    }
+  };
+  const index = {
+    dop,
+    get size() {
+      return map.size;
+    },
+    get: (name) => map.get(name),
+    has: (name) => map.has(name),
+    set(name, value) {
+      const slot = slotOf(name, dop);
+      if (slot !== null && !filed.has(slot))
+        file(slot, name);
+      map.set(name, value);
+      return this;
+    },
+    delete: (name) => {
+      const slot = slotOf(name, dop);
+      if (slot !== null)
+        unfile(slot);
+      return map.delete(name);
+    },
+    clear: () => {
+      filed.clear();
+      buckets.clear();
+      map.clear();
+    },
+    keys: () => map.keys(),
+    values: () => map.values(),
+    entries: () => map.entries(),
+    [Symbol.iterator]: () => map.entries(),
+    related(name) {
+      const slots = new Set;
+      for (const key of kinshipBuckets(name)) {
+        for (const slot of buckets.get(key) ?? [])
+          slots.add(slot);
+      }
+      const found = [];
+      for (const slot of slots) {
+        const held = filed.get(slot);
+        if (held === undefined)
+          continue;
+        const k = kinship(name, held.name);
+        if (k.relation === "different")
+          continue;
+        found.push({
+          name: held.name,
+          value: map.get(held.name),
+          kinship: k,
+          seq: held.seq
+        });
+      }
+      found.sort((x, y) => RELATION_RANK[x.kinship.relation] - RELATION_RANK[y.kinship.relation] || x.seq - y.seq);
+      return found.map(({ name: n, value, kinship: k }) => ({ name: n, value, kinship: k }));
+    }
+  };
+  for (const [name, value] of options.entries ?? [])
+    index.set(name, value);
+  return index;
+}
+function createNameClusters2(dop, linkage) {
+  if (dop === "nn5") {
+    throw new Error('createNameClusters at nn5 is unimplemented: a linkage is defined over a distance and NN5 answers a relation. Use nameRelation / probablySame(a, b, "nn5"); see docs/NAME-NORMALIZATION.md § NN5 — the middle-name relation.');
+  }
+  const transitive = dop;
+  const held = new Map;
+  const out = {
+    dop,
+    linkage,
+    get size() {
+      return held.size;
+    },
+    add(name) {
+      const key = slotOf(name, transitive);
+      const cluster = key === null ? undefined : held.get(key);
+      if (cluster === undefined)
+        held.set(key ?? lonerSlot(), [name]);
+      else
+        cluster.push(name);
+      return this;
+    },
+    clusterOf: (name) => {
+      const key = slotOf(name, transitive);
+      return key === null ? undefined : held.get(key);
+    },
+    clusters: () => [...held.values()],
+    [Symbol.iterator]: () => held.values()
+  };
+  return out;
+}
 // src/normalize/name-infeasible.ts
 var INFEASIBLE_CLASSES2 = ["merge?", "spelling", "rule-gap"];
 function editDistance2(a, b) {
@@ -1420,7 +1597,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, surnameBlock2, initialsBlock2, metaphoneBlocks2, NAME_LEVEL_COLUMNS2, NAME_COLUMNS2, nameColumns2, NAME_FORMATS2, nameFormatOrder2, ORDER_READINGS2, readNameCell2, DEFAULT_NAME_FORMAT_THRESHOLD2, deriveNameFormat2 };
+export { repairMojibake2, sameGivenFamily2, givenFamilyTable2, comparePosition2, nameRelation2, MAX_READINGS2, surnameParts2, printAttestsOrder2, nameReadings2, meetReading2, refinesReading2, sameReading2, chooseReadingPair2, composeReadings2, composeNames2, meetReadings2, nameMeet2, showReading2, blockKeysOfReadings2, nameBlockKeys2, namesFeasible2, KINSHIP_VIAS2, createNameKinship2, nameKinship2, nameCompare2, probablySame2, createNameSet2, createNameMap2, createNameIndex2, createNameClusters2, 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=A39684B9543A024164756E2164756E21
-//# sourceMappingURL=index-vqbvesky.js.map
+//# debugId=4B07A74825028F7364756E2164756E21
+//# sourceMappingURL=index-wq6kn9jq.js.map