@finbheara/domain 0.3.0 → 0.4.0

package/README.md

@@ -42,6 +42,7 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any d
 | `@finbheara/domain/age` | `Age.from`, `Age.fromYOB`, `ageRelation`, `canOverlap`, `averageAge`, `isAveraged`, `intersectBirthYears`, the `Validated` type, the age constants |
 | `@finbheara/domain/noun-index` | `createIndex`, `indexSchema`, `personEncoder`, and the `SqlHandle`/`NounEncoder` types: a database-backed name map (below) |
 | `@finbheara/domain/dance-types` | `danceTypes()`, `DANCE_TYPES`, `rhythmOfTime`, and the shared `DanceMatch`/`DanceRelation`/`SetRhythm`/`TimeSignature` types |
+| `@finbheara/domain/promotion` | `samePromotedRow`, `samePromotedSchool`, `samePromotedHeir`, `samePromotedName`, `questionMarksRead`, `foldCharSynonyms`: is a row the same row after a promotion (below) |
 
 The library does no I/O and installs nothing process-wide. Every reader has a default and a
 factory: build your own with options when the default is not what you want.
@@ -277,6 +278,67 @@ column of your own by spreading one, `{ ...enc, columns: [...enc.columns, "k"],
 type (`{ value: "id", valueType: "INTEGER PRIMARY KEY" }` makes the value the row id); on such a table `map(level)` iterates in value order, and a `set` to a value another row
 holds is refused by the key).
 
+## Decide whether a promoted row is the same row
+
+A results sheet can be collected twice: first as a secondary view (an aggregator's copy), and
+later as the primary transcript read from the publisher's own document, which supersedes it.
+Whoever filed something against a row of the old view must then ask whether the row at the
+same card of the new transcript is the same row. The producer that retires old rows and every
+consumer that moves filed records onto successors must give the same answer, so the rule lives
+here once. **A consumer re-deciding a superseded view's address must use these functions, not a
+copy of them.**
+
+```ts
+import {
+  samePromotedHeir,
+  samePromotedRow,
+  samePromotedSchool,
+} from "@finbheara/domain/promotion";
+
+samePromotedSchool("Brambleton : Mid Region", "Brambleton");    // true: a location tail
+samePromotedSchool("Brambleton :", "Brambleton");               // true: a colon alone
+samePromotedSchool("Brambleton Academy", "Brambleton");         // false
+
+samePromotedRow(
+  { name: "Foireann A", school: "Brambleton" },
+  { name: "Team A", school: "Brambleton" },
+);                                                              // true: one designation
+
+samePromotedHeir(
+  { name: "?ilis O?zumock", school: "Rinceoir? Na Zumock" },
+  { name: "Éilis O'zumock", school: "Rinceoirí Na Zumock" },
+);                                                              // true: `?` for one character
+samePromotedHeir(
+  { name: "LenaZumock", school: "Brambleton" },
+  { name: "Lena (Xia) Zumock", school: "Brambleton" },
+);                                                              // true: glued, an aside added
+samePromotedHeir(
+  { name: "?ilis Zumock", school: "Brambleton" },
+  { name: "Éilis Rervton", school: "Brambleton" },
+);                                                              // false: another surname
+```
+
+What counts as the same row:
+
+- **Both prints go through the character fold first** (`foldCharSynonyms`): the apostrophe,
+  dash and space glyphs each to their lowest code point, then runs of whitespace as one space.
+- **The school** (`samePromotedSchool`) is equal after the fold, or the old print is the new one
+  with an apostrophe restored, or followed by `:` and a location, or by `:` alone.
+- **An ordinary promotion** (`samePromotedRow`): the school the same, and the name equal after
+  the fold, an apostrophe restored, or the same team designation.
+- **The heir of a retired row** (`samePromotedHeir`), where the producer retired the old row and
+  named no successor: the name byte-identical, or the school the same and the name the same
+  person's (`samePromotedName`). A `?` in the old print stands for exactly one character, an
+  apostrophe or a letter outside ASCII, and is read back from the new print at the same
+  position (`questionMarksRead`). The names are then compared through `@finbheara/names` at
+  NN3, which drops case, punctuation and accents and strips a parenthetical aside; a given name
+  and surname the old view glued into one token are compared by the name fold against the new
+  name's fields, in either order.
+
+Anything else is another row: a different surname or given name, one letter printed for
+another, a `?` over an ASCII letter, a school that differs anywhere but a trailing `: location`.
+The caller pairs the card; nothing here reads an address.
+
 ## Known gaps
 
 - `place()` reads `"Derry in Ireland"` and `"Calgary in Western Canada"` as `unread`: it does

package/dist/promotion.js

@@ -0,0 +1,105 @@
+import { canonicalTeamName, nameFold, personName, probablySame } from "@finbheara/names/normalize";
+var CHAR_SYNONYM_CLASSES = [
+  {
+    name: "apostrophe",
+    canonical: "'",
+    members: ["'", "’", "ʼ", "‘", "’"]
+  },
+  {
+    name: "dash",
+    canonical: "-",
+    members: ["-", "‐", "‑", "–", "—"]
+  },
+  {
+    name: "space",
+    canonical: " ",
+    members: [" ", " ", " ", " ", " ", "　"]
+  }
+];
+var FOLD_MAP = new Map(CHAR_SYNONYM_CLASSES.flatMap((c) => c.members.map((m) => [m, c.canonical])));
+var FOLD_PATTERN = new RegExp(`[${[...FOLD_MAP.keys()].map((m) => `\\u${(m.codePointAt(0) ?? 0).toString(16).padStart(4, "0")}`).join("")}]`, "gu");
+function foldCharSynonyms(text) {
+  return text.replace(FOLD_PATTERN, (ch) => FOLD_MAP.get(ch) ?? ch);
+}
+var collapse = (s) => foldCharSynonyms(s).replace(/\s+/gu, " ").trim();
+function samePromotedSchool(was, now) {
+  const a = collapse(was);
+  const b = collapse(now);
+  if (a === b || apostropheRestored(was, now))
+    return true;
+  return b !== "" && a.startsWith(b) && /^ ?:( ?\S|$)/u.test(a.slice(b.length));
+}
+function apostropheRestored(was, now) {
+  const count = (s) => (collapse(s).match(/'/gu) ?? []).length;
+  const bare = (s) => collapse(collapse(s).replace(/'/gu, ""));
+  return count(now) >= count(was) && bare(was) === bare(now);
+}
+function samePromotedRow(was, now) {
+  if (!samePromotedSchool(was.school, now.school))
+    return false;
+  if (collapse(was.name) === collapse(now.name))
+    return true;
+  if (apostropheRestored(was.name, now.name))
+    return true;
+  const team = canonicalTeamName(collapse(was.name));
+  return team !== null && team === canonicalTeamName(collapse(now.name));
+}
+var STOOD_FOR = /^(?:'|(?![A-Za-z])\p{L})$/u;
+function questionMarksRead(was, now) {
+  const a = [...collapse(was)];
+  if (!a.includes("?"))
+    return a.join("");
+  const b = [...collapse(now)];
+  if (a.length !== b.length)
+    return null;
+  const out = [];
+  for (let i = 0;i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x === "?") {
+      if (!STOOD_FOR.test(y))
+        return null;
+      out.push(y);
+    } else if (x !== y)
+      return null;
+    else
+      out.push(x);
+  }
+  return out.join("");
+}
+function samePromotedName(was, now) {
+  const read = questionMarksRead(was, now);
+  if (read === null)
+    return false;
+  const n = collapse(now);
+  if (read === n)
+    return true;
+  const b = personName(n);
+  if (!b.isPerson())
+    return false;
+  const a = personName(read);
+  if (a.isPerson())
+    return probablySame(a, b, "nn3");
+  const glued = nameFold(read);
+  const given = b.givenFields().join("");
+  const surname = b.surnameKey();
+  return glued !== "" && (glued === nameFold(`${given}${surname}`) || glued === nameFold(`${surname}${given}`));
+}
+function samePromotedHeir(was, now) {
+  if (was.name !== "" && was.name === now.name)
+    return true;
+  const school = questionMarksRead(was.school, now.school);
+  if (school === null || !samePromotedSchool(school, now.school))
+    return false;
+  return samePromotedName(was.name, now.name);
+}
+export {
+  CHAR_SYNONYM_CLASSES,
+  collapse,
+  foldCharSynonyms,
+  questionMarksRead,
+  samePromotedHeir,
+  samePromotedName,
+  samePromotedRow,
+  samePromotedSchool
+};

package/dist/types/promotion.d.ts

@@ -0,0 +1,16 @@
+export interface PromotedPrint {
+    name: string;
+    school: string;
+}
+export declare const CHAR_SYNONYM_CLASSES: readonly {
+    readonly name: string;
+    readonly canonical: string;
+    readonly members: readonly string[];
+}[];
+export declare function foldCharSynonyms(text: string): string;
+export declare const collapse: (s: string) => string;
+export declare function samePromotedSchool(was: string, now: string): boolean;
+export declare function samePromotedRow(was: PromotedPrint, now: PromotedPrint): boolean;
+export declare function questionMarksRead(was: string, now: string): string | null;
+export declare function samePromotedName(was: string, now: string): boolean;
+export declare function samePromotedHeir(was: PromotedPrint, now: PromotedPrint): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/domain",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Places, CLRG regions, school names, ages and dances as they are printed: read, compared and told apart",
 	"keywords": [
 		"places",
@@ -53,6 +53,10 @@
 			"types": "./dist/types/noun-index.d.ts",
 			"default": "./dist/noun-index.js"
 		},
+		"./promotion": {
+			"types": "./dist/types/promotion.d.ts",
+			"default": "./dist/promotion.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"files": ["dist/*.js", "dist/chunks/*.js", "dist/types/**/*.d.ts", "README.md", "LICENSE"],