@finbheara/names 0.16.0 → 0.17.0

package/README.md

@@ -180,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