@finbheara/names 0.15.0 → 0.17.0

package/dist/types/normalize/given-families.d.ts

@@ -0,0 +1,53 @@
+/**
+ * given-families.ts — THE EXTENDED GIVEN-NAME FAMILY LIST, read by the TypeScript side.
+ *
+ * `./given-families.json` is the list and this file is its reader; `scripts/given-families.ts`
+ * builds the list and `./given-families.MANIFEST.json` records its sources.
+ *
+ * TWO TIERS OF GIVEN-NAME KNOWLEDGE. `./given-diminutives.json` is the GATE tier: pairs this
+ * package is sure of, curated by hand, some of them admitted at an identity gate. This list
+ * is the EXTENDED tier: every family the sources record for English, Irish, Scottish, Welsh,
+ * French, Italian, Spanish, German, Dutch and Polish usage, about 2,600 names. A pair it
+ * relates MAY be one name, and the answer is `given-maybe`, which no gate admits.
+ *
+ * AN EXACT LIST, NOT A FILTER. A bloom filter of the same pairs at 8 KB answers about fifty
+ * false partners for every given name it is asked about; the exact list is a few KB more
+ * and answers none.
+ *
+ * A FAMILY IS CLOSED. Two names relate when they are a root and its form, or two forms of
+ * one root (`Kate` / `Katie`, both Catherine's). A form under several roots meets each
+ * root's family, and nothing is transitive across families: `Kit` meets Catherine's and
+ * Christopher's, and `Kate` / `Chris` stay apart.
+ *
+ * A TIER BOUNDS HOW RARE A FORM MAY BE. Each form carries 1 (common), 2 (uncommon) or 3
+ * (rare); a pair's tier is its rarer member's, the root counting as 1, and where two names
+ * share several families the commonest counts. `maxTier` admits pairs up to that tier.
+ */
+/** How common a form is: 1 common, 2 uncommon, 3 rare. */
+export type GivenFamilyTier = 1 | 2 | 3;
+export interface GivenFamilyListOptions {
+    /** The rarest tier admitted. Default 3: every pair the list holds. */
+    readonly maxTier?: GivenFamilyTier;
+    /**
+     * The families, one `ROOT,FORM:TIER,…` line each, NN3 upper case. Default: the shipped
+     * `given-families.json`. A caller with its own list passes it here.
+     */
+    readonly families?: readonly string[];
+}
+/** A given-name provider over the extended list: `given-maybe` or `null`. */
+export type GivenFamilyList = (a: string, b: string) => "given-maybe" | null;
+/**
+ * The extended list as a `GivenProvider` for `createNameKinship`: `given-maybe` where two
+ * DIFFERENT names (NN3) share a family within `maxTier`, `null` otherwise. Two equal names
+ * answer `null`, as `givenFamilyTable`'s do.
+ *
+ * The list is parsed on the first question, once per provider.
+ */
+export declare function createGivenFamilyList(options?: GivenFamilyListOptions): GivenFamilyList;
+/**
+ * The shipped list as root -> form -> tier, roots and forms sorted, for `names tables
+ * given-name`, which prints it. Not a package export: the printed form is the contract.
+ */
+export declare function givenFamilyTiers(): Record<string, Record<string, GivenFamilyTier>>;
+/** The shipped list, every tier: the second given-name provider of `nameKinship`. */
+export declare const givenFamilyList: GivenFamilyList;

package/dist/types/normalize/index.d.ts

@@ -19,6 +19,7 @@ export { TEAM_DESIGNATION_WORDS, TEAM_WORD, type TeamSuffixPartition, canonicalT
 export { foldNameKey, nameFold } from "./name-fold.ts";
 export { COMPOUND_SURNAMES, isCompoundSurname } from "./compound-surnames.ts";
 export { givenFamilyTable, sameGivenFamily } from "./given-diminutives.ts";
+export { type GivenFamilyList, type GivenFamilyListOptions, type GivenFamilyTier, createGivenFamilyList, givenFamilyList, } from "./given-families.ts";
 export { type ClusterLinkage, type Clusters, type NameIndex, type NameIndexOptions, type NameMap, type NameMatch, type NameSet, createNameClusters, createNameIndex, createNameMap, createNameSet, nameCompare, probablySame, } from "./name-compare.ts";
 export { type NameReading, type NameRelation, type NameRelationReason, comparePosition, nameRelation, } from "./name-middle.ts";
 export { type GivenProvider, type GivenVia, KINSHIP_VIAS, type KinshipReason, type KinshipVia, type MiddleVia, type MiddleViasAreNn5Reasons, type NameKinship, type NameKinshipOptions, type NameKinshipRelation, createNameKinship, nameKinship, } from "./name-kinship.ts";

package/dist/types/normalize/name-kinship.d.ts

@@ -32,14 +32,14 @@
  * narrower: every tolerance used is one this package's own gate comparators already admit —
  * a middle name `probablySame(…, "nn5")` admits, a given-name family `sameGivenFamily`
  * admits, a compound the print itself carries. A table form that is a name in its own right
- * (`given-family-not-gate`) or a probabilistic source (`given-maybe`) is a lead for the rest
- * of the evidence and never a gate.
+ * (`given-family-not-gate`) or the extended family list (`given-maybe`) is a lead for the
+ * rest of the evidence and never a gate.
  *
  * ## THE GIVEN-NAME TOLERANCE IS INJECTED
  *
- * Which given names are one family is DATA, and the data will move: a probabilistic source
- * of diminutive pairs is expected beside the curated table, and the table may shrink. So the
- * relation asks an ordered list of `GivenProvider`s fixed by `createNameKinship`'s options,
+ * Which given names are one family is DATA, and the data will move: the curated table
+ * (`given-diminutives.json`) is the gate tier, the extended family list (`given-families.json`)
+ * stands beside it, and either may grow or shrink. So the relation asks an ordered list of `GivenProvider`s fixed by `createNameKinship`'s options,
  * and the core knows no table. A new provider is an option; a new kind of answer is one
  * line in `KINSHIP_VIAS`, which also carries its gate-safety, so no branch here changes.
  *
@@ -79,7 +79,7 @@ export declare const KINSHIP_VIAS: Readonly<{
         field: "given";
         gateSafe: false;
     }>;
-    /** a probabilistic source says the two MAY be one family; reserved for one */
+    /** the extended family list says the two MAY be one family (`./given-families.ts`) */
     readonly "given-maybe": Readonly<{
         field: "given";
         gateSafe: false;
@@ -136,7 +136,8 @@ export type GivenProvider = (a: string, b: string) => GivenVia | null;
 export interface NameKinshipOptions {
     /**
      * The given-name tolerances, asked in order; THE FIRST NON-NULL ANSWER WINS, so a caller
-     * lists its most trusted source first. Default `[givenFamilyTable]`; `[]` tolerates no
+     * lists its most trusted source first. Default `[givenFamilyTable, givenFamilyList]`: the
+     * curated table, then the extended list for what the table does not relate. `[]` tolerates no
      * given name.
      */
     readonly given?: readonly GivenProvider[];
@@ -158,7 +159,10 @@ export type NameKinshipRelation = (a: PersonName, b: PersonName) => NameKinship;
  * | otherwise | `candidate`, via every tolerance used |
  */
 export declare function createNameKinship(options?: NameKinshipOptions): NameKinshipRelation;
-/** The tolerant relation over the curated given-name table, `givenFamilyTable`. */
+/**
+ * The tolerant relation over the curated given-name table, `givenFamilyTable`, then the
+ * extended family list, `givenFamilyList`.
+ */
 export declare const nameKinship: NameKinshipRelation;
 /**
  * THE MIDDLE VIAS ARE NN5'S CANDIDATE REASONS, ASSERTED IN TYPECHECKED SOURCE. A middle

package/docs/NAME-NORMALIZATION.md

@@ -471,7 +471,7 @@ interface NameKinship {
 | `given-variant` | given | yes | the two first given names are two spellings of one name (`Connor` / `Conor`) |
 | `given-family` | given | yes | a provider says the two first given names are one family, and a gate admits them |
 | `given-family-not-gate` | given | no | the table relates them only through a `notAtGate` form |
-| `given-maybe` | given | no | a probabilistic source says they MAY be one family |
+| `given-maybe` | given | no | the extended family list says they MAY be one family |
 | `middle-absent` | middle | yes | NN5's: one side carries no middle |
 | `initial-agrees` | middle | yes | NN5's: an initial against a full middle that starts with it |
 
@@ -486,9 +486,10 @@ interface NameKinship {
 - The given-name tolerance is INJECTED: `createNameKinship({ given: [p1, p2, …] })` asks
   each `GivenProvider` in order and the first non-null answer wins. A provider is asked
   once per pair, with the two NN3 first given names in code-unit order, and never with two
-  equal names. The default is `[givenFamilyTable]`, which answers from
-  `given-diminutives.json`; `sameGivenFamily(a, b)` is exactly "`givenFamilyTable(a, b)` is
-  `given-variant` or `given-family`". `[]` tolerates no given name.
+  equal names. The default is `[givenFamilyTable, givenFamilyList]`: the curated table
+  (`given-diminutives.json`) first, then the extended family list (`given-families.json`) for
+  a pair the table does not relate. `sameGivenFamily(a, b)` is exactly "`givenFamilyTable(a, b)`
+  is `given-variant` or `given-family`". `[]` tolerates no given name.
 - A new kind of `via` is one entry in `KINSHIP_VIAS`, which carries its field and its
   gate-safety. The relation's rules do not change.
 - With no tolerance used, the answer is `nameRelation`'s. `head-differs` is split into
@@ -520,9 +521,37 @@ interface NameKinship {
 `Kate` and `Katie` are Catherine's, and `Katelyn` is a spelling of Caitlin. They meet below
 the gate through Caitlin as a form of Catherine, so `Kate` / `Katherine` keeps its gate.
 
-Over the 421 forms and spellings of the table (88,410 distinct pairs), `givenFamilyTable`
-answers `given-variant` for 90 pairs, `given-family` for 371, `given-family-not-gate` for 553,
-and `null` for the rest; `sameGivenFamily` admits 461.
+Over the 541 roots, forms and spellings of the table (146,070 distinct pairs),
+`givenFamilyTable` answers `given-variant` for 127 pairs, `given-family` for 540,
+`given-family-not-gate` for 725, and `null` for the rest; `sameGivenFamily` admits 667.
+
+### The extended family list
+
+The table is the GATE tier: pairs this package is sure of. `given-families.json` is the
+EXTENDED tier: every family its sources record for English, Irish, Scottish, Welsh, French,
+Italian, Spanish, German, Dutch and Polish usage — 1,171 families over 2,613 names, the table's
+own families and spellings among them. `givenFamilyList(a, b)` answers `given-maybe` where two
+names share a family, and `null` otherwise; no gate admits it.
+
+- One line per family, `ROOT,FORM:TIER,…`, NN3. A TIER says how common the form is: 1 common,
+  2 uncommon, 3 rare. `createGivenFamilyList({ maxTier })` admits pairs up to that tier; a
+  pair's tier is its rarer member's, the root counting as 1, and where two names share several
+  families the commonest counts. The default admits every tier.
+- A family is CLOSED: two forms of one root relate (`Kate` / `Katie`), as well as a root and
+  its form. Nothing is transitive across families: `Kit` meets Catherine's and Christopher's,
+  and `Kate` / `Chris` stay apart.
+- It is an exact list, not a filter. An 8 KB bloom filter of 6,980 such pairs, asked about
+  every pair of the 4,730 given names in the 0.14.0 `names.txt`, answered 50.6 false partners
+  per name; the list is 11.8 KB gzipped and answers none.
+- `given-families.MANIFEST.json` beside it records the sources, their tiers and the names it
+  excludes; `scripts/given-families.ts` rebuilds it from them.
+
+Every name either table holds is in `names.txt` as a given name carrying the `D` mark, and
+only those carry it (`test/golden.spec.ts`). A SURNAME STAYS A SURNAME: a name `names.txt`
+holds only as a surname (an `L` entry, none on its key with `F`, `M`, `N` or `A`) is in neither
+table, and every pair through it goes with it (`Ward:LT`, so `Ward` / `Eduard` is not related).
+A genuine given name is made one in `names.txt` first (`Henry:AMD`, read `L` before), and the
+list rebuilt.
 
 ### The tolerant lookup