@finbheara/domain 0.1.0 → 0.3.0

package/README.md

@@ -16,6 +16,8 @@ person names.
   team's `averageAge`.
 - **Dances**: a spoken or printed set dance or céilí dance in, the dances it may name out,
   with tempo rules and hand counts.
+- **A database-backed index** of any of these nouns: the slots an in-memory name map hashes
+  on, stored as indexed columns of a SQLite table you own.
 
 It was built on the stage announcements and results sheets of Irish dance competitions,
 where one school arrives as `Ardvarna Academy of Irish Dance (Calgary, AB)` and as
@@ -33,11 +35,12 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any d
 |---|---|
 | `@finbheara/domain/place` | `place()`, `createPlaceReader`, `placeRelation`, the `Place` types |
 | `@finbheara/domain/clrg-regions` | `REGIONS`, `regionOf`, `resolvePhrase` |
-| `@finbheara/domain/school` | `createSchoolNameReader`, `DEFAULT_SCHOOL_NAME_READER`, `compareSchoolNames`, `foldSchoolName` |
+| `@finbheara/domain/school` | `createSchoolNameReader`, `DEFAULT_SCHOOL_NAME_READER`, `compareSchoolNames`, `foldSchoolName`, `schoolEncoder`, `schoolColumns` |
 | `@finbheara/domain/tune` | `tune()`, `tuneRelation`, `tempoLegal`, `settingAt`, `TUNE_NODES`: the CLRG set dance list |
 | `@finbheara/domain/ceili` | `ceili()`, `ceiliRelation`, `CEILI_NODES`: the céilí handbook dances |
 | `@finbheara/domain/dance` | `dance()`: a print read as a tune and a céilí dance, narrowed by its round |
-| `@finbheara/domain/age` | `Age.from`, `Age.fromYOB`, `ageRelation`, `canOverlap`, `averageAge`, `isAveraged`, the age constants |
+| `@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 |
 
 The library does no I/O and installs nothing process-wide. Every reader has a default and a
@@ -177,6 +180,19 @@ Age.fromYOB(1999).fitsIn(Age.from("Over 21", { year: 2026, top: true })); // tru
 canOverlap(u12, Age.from("U14", { year: 2026 }), dancer);                 // true
 ```
 
+A value the reader cannot stand behind is returned, not thrown. Every `Age` answers
+`isValid()` and `invalidReason()`: an age group under `U3` admits nobody old enough to dance,
+and a year of birth outside 1900 to 2099 is not one. An invalid `Age` has no birth years and
+rules nothing out.
+
+```ts
+Age.from("U2", { year: 2026 }).isValid();               // false
+Age.from("U2", { year: 2026 }).invalidReason();         // "below-youngest-band"
+Age.fromYOB(2222).invalidReason();                      // "year-out-of-range"
+Age.from("All", { year: 2026 }).invalidReason();        // "not-a-band"
+Age.from("", { year: 2026 }).isValid();                 // true: empty, not invalid
+```
+
 A team's age is the average of its dancers' ages, rounded to two decimals. `averageAge`
 takes exact ages only and returns an `AverageAge`, a separate type that refuses, by name,
 any use that would treat it as one dancer's age.
@@ -189,6 +205,78 @@ team.fitsIn(Age.from("U40", { year: 2026 }));           // true
 averageAge([u12]);                                      // throws AgeMisuseError "not-exact"
 ```
 
+## Index names in a database
+
+`createNameMap` (from `@finbheara/names`) and `mapOfSchools` hold their names in memory. An
+index holds them in a SQLite table, as columns: every slot those maps hash a name on, indexed,
+so a lookup at a level is one equality and nothing is loaded. It is a multi-map: a row is one
+name and one value, and a lookup answers every value filed at the name's slot.
+
+The package depends on no SQLite module. Hand it a handle with `prepare(sql)` returning a
+statement with `run(...)` and `all(...)`: `bun:sqlite`'s `Database` and `node:sqlite`'s
+`DatabaseSync` (Node ≥ 22.5) are both one as they are.
+
+```ts
+import { Database } from "bun:sqlite";            // or: import { DatabaseSync } from "node:sqlite"
+import { createNameMap, personName } from "@finbheara/names/normalize";
+import { createIndex, indexSchema, personEncoder } from "@finbheara/domain/noun-index";
+
+const db = new Database(":memory:");
+const people = personEncoder();
+const { table, indexes } = indexSchema(people, { table: "person" });
+db.prepare(table).run();
+for (const s of indexes) db.prepare(s).run();      // after a bulk load, if you have one
+
+const index = createIndex(db, people, { table: "person" });
+index.add(personName("Aoife Ní Mhaolvarna"), 1);
+index.add(personName("Mhaolvarna, Aoife Ni"), 2);
+index.add(personName("Kestrel Evbatyrov"), 3);
+
+index.get(personName("AOIFE NI MHAOLVARNA"), "nn3");  // [1, 2]
+index.get(personName("Aoife Ní Mhaolvarna"), "nn0");  // [1]
+index.find("surname_key", personName("Aoife Ní Mhaolvarna").surnameKey());  // [1, 2]
+index.nouns(2)[0]?.nn2;                                // "NiMhaolvarna<<Aoife": the parse, read back
+```
+
+`map(level)` is the single-valued view, with `createNameMap`'s interface and its answers:
+the first name filed at a slot keeps it, a later `set` replaces the value, and a print that
+names no person is held and never found.
+
+```ts
+const byName = index.map("nn3");
+byName.get(personName("Aoife Ni Mhaolvarna"));        // 1
+byName.size;                                           // 2
+createNameMap<number>("nn3", [...byName]).size;        // 2
+```
+
+The person columns are the print, the reading it was parsed under, and `nameColumns()` from
+`@finbheara/names`; the levels are `nn0`-`nn4`. A school's (`schoolEncoder` from
+`@finbheara/domain/school`) are the print, `sn0`-`sn4`, `realWords` and `matchKey`, and its
+levels are `mapOfSchools`'s. One print may be filed under several schools, and a school under
+many prints:
+
+```ts
+import { DEFAULT_SCHOOL_NAME_READER, schoolEncoder } from "@finbheara/domain/school";
+
+const read = (p: string) => DEFAULT_SCHOOL_NAME_READER.schoolName(p);
+const schools = createIndex(db, schoolEncoder(), { table: "school" });  // after its indexSchema
+schools.add(read("Ardvarna Academy"), 10);
+schools.add(read("Ardvarna Academy"), 11);
+schools.add(read("Ardvarna Academy (Ontario)"), 11);
+schools.add(read("ARDVARNA ACADEMY - Calgary, Alberta"), 10);
+
+schools.get(read("Ardvarna Academy"), "sn0");         // [10, 11]
+schools.nouns(11).map((s) => s.sn0);                   // ["Ardvarna Academy", "Ardvarna Academy (Ontario)"]
+schools.get(read("Ardvarna Academy of Irish Dance (Calgary, AB)"), "sn3");  // [10]
+```
+
+`rows({ column: keys, ... })` answers every row where any column holds one of its keys, and
+`glob(column, pattern)` a SQLite `GLOB` on one column. An encoder is a plain object: add a
+column of your own by spreading one, `{ ...enc, columns: [...enc.columns, "k"], encode: (x) =>
+({ ...enc.encode(x), k: f(x) }) }`. `indexSchema` takes the table, the value column and its
+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).
+
 ## Known gaps
 
 - `place()` reads `"Derry in Ireland"` and `"Calgary in Western Canada"` as `unread`: it does

package/dist/age.js

@@ -6,6 +6,8 @@ var UNDER_CAP_MAX_TOP = 21;
 var YOUNG_FLOOR = Object.freeze({ hard: 2, soft: 4 });
 var MIN_MAJOR_AGE = 4;
 var MIN_FEIS_AGE = 3;
+var YOUNGEST_BAND_TOP = MAJORS_FLOOR_YEARS;
+var YOB_RANGE = Object.freeze({ first: 1900, last: 2099 });
 var DANCE_UP_YEARS = 1;
 var ageOnJanuary1 = (year, born) => year - born - 1;
 var yearsSinceBirth = (year, born) => year - born;
@@ -116,6 +118,11 @@ function read(token, ladder, top) {
   }
   return { kind: null, interval: null, refusal: "not-a-band", clauses: [], parts: [] };
 }
+function refuseBelowYoungest(r) {
+  if (r.interval === null || r.interval.hi >= YOUNGEST_BAND_TOP)
+    return r;
+  return { ...r, interval: null, refusal: "below-youngest-band", clauses: [] };
+}
 
 class AgeMisuseError extends Error {
   misuse;
@@ -146,7 +153,7 @@ function fromPrint(print, context = {}) {
   const ladder = context.ladder ?? NO_LADDER;
   const year = context.year === undefined ? currentYear() : context.year;
   const ag1 = print.trim().toLowerCase();
-  const reading = ag1 === "" ? { kind: null, interval: null, refusal: null, clauses: [], parts: [] } : read(print.trim(), ladder, context.top === true);
+  const reading = ag1 === "" ? { kind: null, interval: null, refusal: null, clauses: [], parts: [] } : refuseBelowYoungest(read(print.trim(), ladder, context.top === true));
   const iv = reading.interval;
   const arm = ag1 === "" ? "empty" : iv === null ? "open" : "band";
   const ag2 = iv !== null ? display(iv) : ag1 === "" ? "" : `${ag1}?`;
@@ -162,6 +169,8 @@ function fromPrint(print, context = {}) {
     parts: reading.parts,
     length: ag2.length,
     refusal: reading.refusal,
+    isValid: () => reading.refusal === null,
+    invalidReason: () => reading.refusal,
     source,
     clauses: reading.clauses,
     ladder,
@@ -186,7 +195,7 @@ function fromPrint(print, context = {}) {
     floorObserved: () => reading.kind !== "under" || iv === null ? null : reading.clauses.includes("under-floored-on-rung")
   });
 }
-function fromYOB(from, to = from) {
+function fromYOB(from, to = from, context = {}) {
   for (const y of [from, to])
     if (y !== null && !Number.isInteger(y))
       throw new RangeError(`Age.fromYOB(${from}, ${to}): a year of birth is a whole number`);
@@ -194,29 +203,34 @@ function fromYOB(from, to = from) {
     throw new RangeError("Age.fromYOB(null, null): at least one end is a year");
   if (from !== null && to !== null && from > to)
     throw new RangeError(`Age.fromYOB(${from}, ${to}): the earliest year comes first`);
-  const exact = from !== null && from === to;
-  const ag0 = exact ? String(from) : `${from ?? ""}..${to ?? ""}`;
-  const ag2 = `b${ag0}`;
-  const years = Object.freeze({ from, to });
+  const at = context.year ?? null;
+  const valid = [from, to].every((y) => y === null || y >= YOB_RANGE.first && y <= YOB_RANGE.last) && (at === null || to === null || yearsSinceBirth(at, to) >= YOUNG_FLOOR.hard);
+  const refusal = valid ? null : "year-out-of-range";
+  const exact = valid && from !== null && from === to;
+  const ag0 = from !== null && from === to ? String(from) : `${from ?? ""}..${to ?? ""}`;
+  const ag2 = valid ? `b${ag0}` : `b${ag0}?`;
+  const years = Object.freeze(valid ? { from, to } : { from: null, to: null });
   return withRelations({
     [Symbol.toStringTag]: "Age",
     toString: () => ag2,
-    arm: "yob",
+    arm: valid ? "yob" : "open",
     kind: "yob",
     ag0,
     ag1: ag0,
     ag2,
-    parts: exact ? [from] : [from, to].filter((y) => y !== null),
+    parts: from !== null && from === to ? [from] : [from, to].filter((y) => y !== null),
     length: ag2.length,
-    refusal: null,
-    source: "printed-yob",
+    refusal,
+    isValid: () => valid,
+    invalidReason: () => refusal,
+    source: valid ? "printed-yob" : "open",
     clauses: [],
     ladder: NO_LADDER,
     year: null,
     isEmpty: () => false,
-    isAge: () => true,
+    isAge: () => valid,
     isExact: () => exact,
-    isAndOver: () => from === null,
+    isAndOver: () => valid && from === null,
     isAdult: () => false,
     interval: () => null,
     birthYears: () => years,
@@ -250,7 +264,7 @@ function birthYearsOfInterval(iv, year) {
     to: Math.min(year - iv.lo - 1, year - MAJORS_FLOOR_YEARS)
   };
 }
-var inBirthYears = (a) => a.arm === "yob" || a.year !== null;
+var inBirthYears = (a) => a.kind === "yob" || a.year !== null;
 function spanOf(a) {
   if (!a.isAge())
     return null;
@@ -355,6 +369,25 @@ function birthYearsDisjoint(a, b) {
     return true;
   return false;
 }
+function intersectBirthYears(windows) {
+  let from = null;
+  let to = null;
+  let n = 0;
+  for (const w of windows) {
+    if (w.from === null && w.to === null)
+      continue;
+    n++;
+    if (w.from !== null)
+      from = from === null ? w.from : Math.max(from, w.from);
+    if (w.to !== null)
+      to = to === null ? w.to : Math.min(to, w.to);
+  }
+  if (n === 0)
+    return { from: null, to: null, n: 0 };
+  if (from !== null && to !== null && from > to)
+    return null;
+  return { from, to, n };
+}
 function birthYearsMeet(card, other, slack = 0) {
   if (card.from !== null && other.to !== null && card.from > other.to)
     return false;
@@ -378,6 +411,11 @@ function underCappedYears(b, year, n = UNDER_CAP.plain) {
 function underCapRefuses(bandFrom, identityFrom, n) {
   return identityFrom > bandFrom + n;
 }
+function validYOB(y, year) {
+  if (y === null || y === undefined || !Number.isInteger(y))
+    return null;
+  return Age.fromYOB(y, y, { year: year ?? null }).isValid() ? y : null;
+}
 function youngFloor(year, oldest) {
   const s = yearsSinceBirth(year, oldest);
   if (s >= YOUNG_FLOOR.soft)
@@ -399,6 +437,8 @@ export {
   MIN_MAJOR_AGE,
   UNDER_CAP,
   UNDER_CAP_MAX_TOP,
+  YOB_RANGE,
+  YOUNGEST_BAND_TOP,
   YOUNGEST_FLOOR,
   YOUNG_FLOOR,
   ageOnJanuary1,
@@ -408,6 +448,7 @@ export {
   birthYearsMeet,
   birthYearsOfInterval,
   canOverlap,
+  intersectBirthYears,
   isAveraged,
   roundedMeanHundredths,
   tooYoungForFeis,
@@ -415,6 +456,7 @@ export {
   underCapApplies,
   underCapRefuses,
   underCappedYears,
+  validYOB,
   yearsSinceBirth,
   youngFloor
 };

package/dist/ceili.js

@@ -4,8 +4,8 @@ import {
   ceiliById2,
   ceili2,
   ceiliRelation2
-} from "./chunks/place-7gqecaxd.js";
-import"./chunks/place-g6yw4cq6.js";
+} from "./chunks/place-0ehc2q69.js";
+import"./chunks/place-htxgptyv.js";
 export {
   CEILI_NODES2 as CEILI_NODES,
   allCeilis2 as allCeilis,

package/dist/chunks/{place-7gqecaxd.js → place-0ehc2q69.js}

@@ -3,7 +3,7 @@ import {
   matchNodes,
   candidateRelation,
   isDanceTypePrint2
-} from "./place-g6yw4cq6.js";
+} from "./place-htxgptyv.js";
 
 function node(id, name, irish, family, formation, opts = {}) {
   const kind = "round" in formation ? "round" : ("long" in formation) ? "long" : "set";

package/dist/chunks/{place-kr42294h.js → place-2ja9yx08.js}

@@ -5,7 +5,7 @@ import {
   candidateRelation,
   rhythmOfTime2,
   isDanceTypePrint2
-} from "./place-g6yw4cq6.js";
+} from "./place-htxgptyv.js";
 
 var SET_MIN_SPEED2 = Object.freeze({
   jig: 66,

package/dist/chunks/{place-g6yw4cq6.js → place-htxgptyv.js}

@@ -104,6 +104,7 @@ function rhythmOfTime2(time) {
 }
 var TYPE_PRINTS = new Map([
   ["reel", ["reel"]],
+  ["jig", ["light-jig", "single-jig", "treble-jig"]],
   ["light jig", ["light-jig"]],
   ["single jig", ["single-jig"]],
   ["slip jig", ["slip-jig"]],

package/dist/dance-types.js

@@ -4,7 +4,7 @@ import {
   danceTypes2,
   danceTypePrints2,
   isDanceTypePrint2
-} from "./chunks/place-g6yw4cq6.js";
+} from "./chunks/place-htxgptyv.js";
 export {
   DANCE_TYPES2 as DANCE_TYPES,
   danceTypePrints2 as danceTypePrints,

package/dist/dance.js

@@ -1,10 +1,10 @@
-import"./chunks/place-g6yw4cq6.js";
+import"./chunks/place-htxgptyv.js";
 import {
   ceili2
-} from "./chunks/place-7gqecaxd.js";
+} from "./chunks/place-0ehc2q69.js";
 import {
   tune2
-} from "./chunks/place-kr42294h.js";
+} from "./chunks/place-2ja9yx08.js";
 
 function dance(print, round) {
   const setting = round === "traditional-set" ? "traditional" : undefined;

package/dist/noun-index.js

@@ -0,0 +1,233 @@
+import {
+  NAME_COLUMNS,
+  NAME_LEVEL_COLUMNS,
+  nameColumns,
+  personName
+} from "@finbheara/names/normalize";
+var IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+var RESERVED = new Set(`rowid oid _rowid_ __r __v all and as by check create default delete distinct drop
+	from group in index insert into is key limit not null on or order primary references
+	select set table to union unique update values where`.split(/\s+/u));
+function ident(s, what) {
+  if (!IDENT.test(s) || RESERVED.has(s.toLowerCase()))
+    throw new Error(`noun-index: ${what} ${JSON.stringify(s)} is not a usable identifier`);
+  return s;
+}
+function resolve(encoder, options) {
+  const table = ident(options.table ?? "noun_index", "table");
+  const value = ident(options.value ?? "value", "value column");
+  const valueType = (options.valueType ?? "").trim();
+  if (!/^[A-Za-z ()0-9]*$/u.test(valueType))
+    throw new Error(`noun-index: value type ${JSON.stringify(valueType)} is not a type`);
+  const seen = new Set([value.toLowerCase()]);
+  for (const c of encoder.columns) {
+    ident(c, "column");
+    if (seen.has(c.toLowerCase()))
+      throw new Error(`noun-index: column ${c} is declared twice`);
+    seen.add(c.toLowerCase());
+  }
+  for (const c of [...encoder.levels, ...encoder.indexed])
+    if (!encoder.columns.includes(c))
+      throw new Error(`noun-index: ${c} is not a column`);
+  return { table, value, valueType, isKey: /primary\s+key/iu.test(valueType) };
+}
+function indexSchema(encoder, options = {}) {
+  const r = resolve(encoder, options);
+  const cols = [`${r.value}${r.valueType === "" ? "" : ` ${r.valueType}`}`];
+  for (const c of encoder.columns)
+    cols.push(`${c} TEXT`);
+  const indexes = [];
+  if (!r.isKey)
+    indexes.push(`CREATE INDEX IF NOT EXISTS ${r.table}_${r.value} ON ${r.table}(${r.value})`);
+  for (const c of encoder.indexed)
+    indexes.push(`CREATE INDEX IF NOT EXISTS ${r.table}_${c} ON ${r.table}(${c})`);
+  return { table: `CREATE TABLE IF NOT EXISTS ${r.table}(${cols.join(", ")})`, indexes };
+}
+var CHUNK = 500;
+function createIndex(handle, encoder, options = {}) {
+  const r = resolve(encoder, options);
+  const { table: T, value: VC } = r;
+  const cols = encoder.columns;
+  const prepared = new Map;
+  const stmt = (sql) => {
+    let s = prepared.get(sql);
+    if (s === undefined) {
+      s = handle.prepare(sql);
+      prepared.set(sql, s);
+    }
+    return s;
+  };
+  const column = (c) => {
+    if (!cols.includes(c))
+      throw new Error(`noun-index: ${c} is not a column of ${T}`);
+    return c;
+  };
+  const level = (l) => {
+    if (!encoder.levels.includes(l))
+      throw new Error(`noun-index: ${l} is not a level of ${T}`);
+    return l;
+  };
+  const insertSql = `INSERT INTO ${T}(${VC}, ${cols.join(", ")}) VALUES(${cols.map(() => "?").join(", ")}, ?)`;
+  const params = (x) => {
+    const e = encoder.encode(x);
+    return cols.map((c) => e[c] ?? null);
+  };
+  const insert = (x, value) => {
+    stmt(insertSql).run(value, ...params(x));
+  };
+  const keyAt = (x, l) => {
+    level(l);
+    return encoder.key === undefined ? encoder.encode(x)[l] ?? null : encoder.key(x, l);
+  };
+  const valuesWhere = (col, key) => stmt(`SELECT ${VC} AS v FROM ${T} WHERE ${col} = ? ORDER BY rowid`).all(key).map((o) => o.v);
+  const pick = (columns) => columns === undefined ? cols : columns.map(column);
+  const toRows = (raw, picked) => raw.map((o) => {
+    const row = {};
+    for (const c of picked)
+      row[c] = o[c] ?? null;
+    return { value: o.__v, row };
+  });
+  const selectList = (picked) => ["rowid AS __r", `${VC} AS __v`, ...picked].join(", ");
+  const index = {
+    table: T,
+    encoder,
+    add: insert,
+    addAll(entries) {
+      for (const [x, v] of entries)
+        insert(x, v);
+    },
+    get(x, l) {
+      const k = keyAt(x, l);
+      return k === null ? [] : valuesWhere(l, k);
+    },
+    has(x, l) {
+      const k = keyAt(x, l);
+      return k !== null && stmt(`SELECT 1 FROM ${T} WHERE ${l} = ? LIMIT 1`).all(k).length > 0;
+    },
+    find: (c, key) => valuesWhere(column(c), key),
+    rows(where, columns) {
+      const picked = pick(columns);
+      const seen = new Map;
+      for (const [c, keys] of Object.entries(where)) {
+        column(c);
+        const uniq = [...new Set(keys)];
+        for (let i = 0;i < uniq.length; i += CHUNK) {
+          const part = uniq.slice(i, i + CHUNK);
+          const sql = `SELECT ${selectList(picked)} FROM ${T} WHERE ${c} IN (${part.map(() => "?").join(",")})`;
+          for (const o of stmt(sql).all(...part))
+            seen.set(Number(o.__r), o);
+        }
+      }
+      return toRows([...seen].sort((a, b) => a[0] - b[0]).map(([, o]) => o), picked);
+    },
+    glob(c, pattern, columns) {
+      const picked = pick(columns);
+      const raw = stmt(`SELECT ${selectList(picked)} FROM ${T} WHERE ${column(c)} GLOB ? ORDER BY rowid`).all(pattern);
+      return toRows(raw, picked);
+    },
+    nouns(value) {
+      const raw = stmt(`SELECT ${cols.join(", ")} FROM ${T} WHERE ${VC} = ? ORDER BY rowid`).all(value);
+      return raw.map((o) => encoder.decode(o));
+    },
+    remove(value) {
+      const n = stmt(`SELECT count(*) AS n FROM ${T} WHERE ${VC} = ?`).all(value)[0].n;
+      if (n > 0)
+        stmt(`DELETE FROM ${T} WHERE ${VC} = ?`).run(value);
+      return Number(n);
+    },
+    size: () => Number(stmt(`SELECT count(*) AS n FROM ${T}`).all()[0].n),
+    map: (l) => viewAt(l)
+  };
+  function viewAt(l) {
+    const lc = level(l);
+    const heads = `SELECT rowid AS __r, ${VC} AS __v, ${cols.join(", ")} FROM ${T}
+			WHERE ${lc} IS NULL OR rowid IN (SELECT min(rowid) FROM ${T} WHERE ${lc} IS NOT NULL GROUP BY ${lc})
+			ORDER BY rowid`;
+    const head = (k) => stmt(`SELECT rowid AS __r, ${VC} AS __v FROM ${T} WHERE ${lc} = ? ORDER BY rowid LIMIT 1`).all(k)[0];
+    const all = () => stmt(heads).all();
+    const view = {
+      dop: l,
+      get size() {
+        const o = stmt(`SELECT (SELECT count(DISTINCT ${lc}) FROM ${T}) + (SELECT count(*) FROM ${T} WHERE ${lc} IS NULL) AS n`).all()[0];
+        return Number(o.n);
+      },
+      get(x) {
+        const k = keyAt(x, l);
+        return k === null ? undefined : head(k)?.__v;
+      },
+      has(x) {
+        const k = keyAt(x, l);
+        return k !== null && head(k) !== undefined;
+      },
+      set(x, value) {
+        const k = keyAt(x, l);
+        const h = k === null ? undefined : head(k);
+        if (h === undefined)
+          insert(x, value);
+        else
+          stmt(`UPDATE ${T} SET ${VC} = ? WHERE rowid = ?`).run(value, h.__r);
+        return this;
+      },
+      delete(x) {
+        const k = keyAt(x, l);
+        if (k === null || head(k) === undefined)
+          return false;
+        stmt(`DELETE FROM ${T} WHERE ${lc} = ?`).run(k);
+        return true;
+      },
+      clear() {
+        stmt(`DELETE FROM ${T}`).run();
+      },
+      *keys() {
+        for (const o of all())
+          yield encoder.decode(o);
+      },
+      *values() {
+        for (const o of all())
+          yield o.__v;
+      },
+      *entries() {
+        for (const o of all())
+          yield [encoder.decode(o), o.__v];
+      },
+      [Symbol.iterator]() {
+        return this.entries();
+      }
+    };
+    return view;
+  }
+  return index;
+}
+var sameColumns = (a, b) => NAME_COLUMNS.every((c) => a[c] === b[c]);
+function personEncoder(options = {}) {
+  const read = options.read ?? ((p, o) => personName(p, o));
+  const printCol = options.print ?? "print";
+  const readingCol = options.reading ?? "reading";
+  const readingOf = (x, cols) => {
+    const g = read(x.nn0, "given-first");
+    if (g === x || sameColumns(cols, nameColumns(g)))
+      return "given-first";
+    if (sameColumns(cols, nameColumns(read(x.nn0, "surname-first"))))
+      return "surname-first";
+    throw new Error(`personEncoder: ${JSON.stringify(x.nn0)} was not read by this encoder's reader in either order`);
+  };
+  return {
+    columns: [printCol, readingCol, ...NAME_COLUMNS],
+    levels: NAME_LEVEL_COLUMNS,
+    indexed: NAME_COLUMNS.filter((c) => c !== "given_key"),
+    encode(x) {
+      const cols = nameColumns(x);
+      return { [printCol]: x.nn0, [readingCol]: readingOf(x, cols), ...cols };
+    },
+    key: (x, level) => nameColumns(x)[level],
+    decode(row) {
+      const order = row[readingCol] === "surname-first" ? "surname-first" : "given-first";
+      return read(row[printCol] ?? "", order);
+    }
+  };
+}
+export {
+  createIndex,
+  indexSchema,
+  personEncoder
+};

package/dist/school.js

@@ -2172,9 +2172,35 @@ function mapOfSchools(dop, entries) {
     map.set(name, value);
   return map;
 }
+var SCHOOL_LEVEL_COLUMNS = ["sn0", "sn1", "sn2", "sn3", "sn4", "realWords"];
+function schoolColumns(name) {
+  return {
+    sn0: slotOf(name, "sn0"),
+    sn1: slotOf(name, "sn1"),
+    sn2: slotOf(name, "sn2"),
+    sn3: slotOf(name, "sn3"),
+    sn4: slotOf(name, "sn4"),
+    realWords: slotOf(name, "realWords")
+  };
+}
 function isLadderLevel(dop) {
   return LADDER.has(dop);
 }
+function schoolEncoder(options = {}) {
+  const reader = options.reader ?? DEFAULT_SCHOOL_NAME_READER;
+  const printCol = options.print ?? "print";
+  return {
+    columns: [printCol, ...SCHOOL_LEVEL_COLUMNS, "matchKey"],
+    levels: SCHOOL_LEVEL_COLUMNS,
+    indexed: [...SCHOOL_LEVEL_COLUMNS, "matchKey"],
+    encode(x) {
+      const key = foldSchoolName(x.sn0);
+      return { [printCol]: x.sn0, ...schoolColumns(x), matchKey: key === "" ? null : key };
+    },
+    key: (x, level) => schoolColumns(x)[level],
+    decode: (row) => reader.schoolName(row[printCol] ?? "")
+  };
+}
 function compareSchoolNames(a, b, reader) {
   return compareSchools(reader.schoolName(a), reader.schoolName(b));
 }
@@ -2217,6 +2243,7 @@ export {
   DEFAULT_SCHOOL_NAME_CAPACITY,
   DEFAULT_SCHOOL_NAME_READER,
   NOT_A_SCHOOL,
+  SCHOOL_LEVEL_COLUMNS,
   SCHOOL_NAME_EXCEPTIONS,
   compareSchoolNames,
   compareSchools,
@@ -2231,7 +2258,9 @@ export {
   realWords,
   realWordsInPrintOrder,
   sameInEveryPart,
+  schoolColumns,
   schoolCompare,
+  schoolEncoder,
   schoolInitials,
   schoolKeyTokens,
   schoolPrintSplit,

package/dist/tune.js

@@ -8,8 +8,8 @@ import {
   settingAt2,
   tune2,
   tuneRelation2
-} from "./chunks/place-kr42294h.js";
-import"./chunks/place-g6yw4cq6.js";
+} from "./chunks/place-2ja9yx08.js";
+import"./chunks/place-htxgptyv.js";
 export {
   PLAUSIBLE_SET_TEMPO_MAX2 as PLAUSIBLE_SET_TEMPO_MAX,
   SET_MIN_SPEED2 as SET_MIN_SPEED,

package/dist/types/age-types.d.ts

@@ -11,6 +11,9 @@ export interface AgeLadder {
     readonly overs: readonly number[];
     readonly ranges: readonly number[];
 }
+export interface YOBContext {
+    readonly year?: number | null;
+}
 export interface AgeContext {
     readonly ladder?: AgeLadder;
     readonly year?: number | null;
@@ -18,7 +21,7 @@ export interface AgeContext {
 }
 export type AgeArm = "band" | "yob" | "open" | "empty";
 export type AgeKind = "under" | "over" | "range" | "adult" | "senior" | "yob";
-export type AgeRefusal = "not-a-band" | "backwards-range" | "senior-without-ladder";
+export type AgeRefusal = "not-a-band" | "backwards-range" | "senior-without-ladder" | "below-youngest-band" | "year-out-of-range";
 export type AgeSource = "sibling-narrowed" | "printed-band" | "printed-range" | "printed-yob" | "open";
 export type AgeClause = "under-floored-on-rung" | "youngest-absorbs" | "over-ceiling-from-next-over" | "over-ceiling-refused-gap" | "and-over-no-ceiling" | "range-overlapping" | "range-inclusive" | "range-floor-on-rung" | "range-floor-widened" | "range-adult-floor";
 export type AgeRelation = "same" | "contains" | "overlaps" | "disjoint" | "silent";

package/dist/types/age.d.ts

@@ -1,5 +1,6 @@
-import type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, YoungFloorVerdict } from "./age-types.ts";
-export type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, YoungFloorVerdict, };
+import type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, YOBContext, YoungFloorVerdict } from "./age-types.ts";
+import type { Validated } from "./validated.ts";
+export type { AgeArm, AgeClause, AgeComparison, AgeContext, AgeInterval, AgeKind, AgeLadder, AgeMisuse, AgeRefusal, AgeRelation, AgeRelationReason, AgeSource, BirthYears, Validated, YOBContext, YoungFloorVerdict, };
 export declare const YOUNGEST_FLOOR = 0;
 export declare const ADULT_FLOOR = 18;
 export declare const MAJORS_FLOOR_YEARS = 3;
@@ -14,10 +15,15 @@ export declare const YOUNG_FLOOR: Readonly<{
 }>;
 export declare const MIN_MAJOR_AGE = 4;
 export declare const MIN_FEIS_AGE = 3;
+export declare const YOUNGEST_BAND_TOP = 3;
+export declare const YOB_RANGE: Readonly<{
+    readonly first: 1900;
+    readonly last: 2099;
+}>;
 export declare const DANCE_UP_YEARS = 1;
 export declare const ageOnJanuary1: (year: number, born: number) => number;
 export declare const yearsSinceBirth: (year: number, born: number) => number;
-export interface Age {
+export interface Age extends Validated<AgeRefusal> {
     readonly [Symbol.toStringTag]: "Age";
     toString(): string;
     readonly arm: AgeArm;
@@ -48,7 +54,7 @@ export declare class AgeMisuseError extends Error {
     constructor(misuse: AgeMisuse, detail: string);
 }
 declare function fromPrint(print: string, context?: AgeContext): Age;
-declare function fromYOB(from: number | null, to?: number | null): Age;
+declare function fromYOB(from: number | null, to?: number | null, context?: YOBContext): Age;
 export declare const Age: Readonly<{
     from: typeof fromPrint;
     fromYOB: typeof fromYOB;
@@ -75,10 +81,16 @@ export interface AverageAge {
 export declare function isAveraged(a: Age | AverageAge): a is AverageAge;
 export declare function averageAge(ages: readonly Age[]): AverageAge;
 export declare function birthYearsDisjoint(a: BirthYears, b: BirthYears): boolean;
+export declare function intersectBirthYears(windows: readonly BirthYears[]): {
+    from: number | null;
+    to: number | null;
+    n: number;
+} | null;
 export declare function birthYearsMeet(card: BirthYears, other: BirthYears, slack?: number): boolean;
 export declare function underCapApplies(bandFrom: number | null, year: number): boolean;
 export declare function underCappedYears(b: BirthYears, year: number, n?: number): BirthYears;
 export declare function underCapRefuses(bandFrom: number, identityFrom: number, n: number): boolean;
+export declare function validYOB(y: number | null | undefined, year?: number | null): number | null;
 export declare function youngFloor(year: number, oldest: number): YoungFloorVerdict;
 export declare const tooYoungForMajor: (year: number, oldest: number) => boolean;
 export declare const tooYoungForFeis: (year: number, oldest: number) => boolean;

package/dist/types/noun-index.d.ts

@@ -0,0 +1,67 @@
+import { type PersonName, type ResolvedNameOrder, type TransitiveLevel } from "@finbheara/names/normalize";
+export type SqlValue = string | number | bigint | null;
+export interface SqlStatement {
+    run(...params: SqlValue[]): unknown;
+    all(...params: SqlValue[]): unknown[];
+}
+export interface SqlHandle {
+    prepare(sql: string): SqlStatement;
+}
+export type EncodedRow = Readonly<Record<string, string | null>>;
+export interface NounEncoder<X, L extends string = string> {
+    readonly columns: readonly string[];
+    readonly levels: readonly L[];
+    readonly indexed: readonly string[];
+    encode(x: X): EncodedRow;
+    key?(x: X, level: L): string | null;
+    decode(row: EncodedRow): X;
+}
+export interface IndexOptions {
+    readonly table?: string;
+    readonly value?: string;
+    readonly valueType?: string;
+}
+export interface IndexRow<V> {
+    readonly value: V;
+    readonly row: EncodedRow;
+}
+export interface IndexMap<X, V, L extends string> {
+    readonly dop: L;
+    readonly size: number;
+    get(x: X): V | undefined;
+    has(x: X): boolean;
+    set(x: X, value: V): this;
+    delete(x: X): boolean;
+    clear(): void;
+    keys(): IterableIterator<X>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<[X, V]>;
+    [Symbol.iterator](): IterableIterator<[X, V]>;
+}
+export interface NounIndex<X, L extends string, V extends SqlValue> {
+    readonly table: string;
+    readonly encoder: NounEncoder<X, L>;
+    add(x: X, value: V): void;
+    addAll(entries: Iterable<readonly [X, V]>): void;
+    get(x: X, level: L): V[];
+    has(x: X, level: L): boolean;
+    find(column: string, key: string): V[];
+    rows(where: Readonly<Record<string, readonly string[]>>, columns?: readonly string[]): IndexRow<V>[];
+    glob(column: string, pattern: string, columns?: readonly string[]): IndexRow<V>[];
+    nouns(value: V): X[];
+    remove(value: V): number;
+    size(): number;
+    map(level: L): IndexMap<X, V, L>;
+}
+export declare function indexSchema(encoder: NounEncoder<unknown>, options?: IndexOptions): {
+    table: string;
+    indexes: string[];
+};
+export declare function createIndex<X, L extends string, V extends SqlValue = SqlValue>(handle: SqlHandle, encoder: NounEncoder<X, L>, options?: IndexOptions): NounIndex<X, L, V>;
+export type PersonReader = (print: string, order: ResolvedNameOrder) => PersonName;
+export interface PersonEncoderOptions {
+    readonly read?: PersonReader;
+    readonly print?: string;
+    readonly reading?: string;
+}
+export declare function personEncoder(options?: PersonEncoderOptions): NounEncoder<PersonName, TransitiveLevel>;

package/dist/types/school-compare.d.ts

@@ -33,4 +33,7 @@ export interface SchoolMap<V> {
 }
 export declare function setOfSchools(dop: SchoolDop): SchoolSet;
 export declare function mapOfSchools<V>(dop: SchoolDop, entries?: Iterable<readonly [SchoolName, V]>): SchoolMap<V>;
+export declare const SCHOOL_LEVEL_COLUMNS: readonly ["sn0", "sn1", "sn2", "sn3", "sn4", "realWords"];
+export type SchoolLevelColumn = (typeof SCHOOL_LEVEL_COLUMNS)[number];
+export declare function schoolColumns(name: SchoolName): Readonly<Record<SchoolLevelColumn, string | null>>;
 export declare function isLadderLevel(dop: SchoolDop): boolean;

package/dist/types/school-encoder.d.ts

@@ -0,0 +1,8 @@
+import type { NounEncoder } from "./noun-index.ts";
+import { type SchoolLevelColumn } from "./school-compare.ts";
+import { type SchoolName, type SchoolNameParser } from "./school-name.ts";
+export interface SchoolEncoderOptions {
+    readonly reader?: SchoolNameParser;
+    readonly print?: string;
+}
+export declare function schoolEncoder(options?: SchoolEncoderOptions): NounEncoder<SchoolName, SchoolLevelColumn>;

package/dist/types/school.d.ts

@@ -1,7 +1,9 @@
 export { createSchoolNameReader, DEFAULT_SCHOOL_NAME_CAPACITY, DEFAULT_SCHOOL_NAME_READER, realWords, realWordsInPrintOrder, schoolInitials, schoolPrintSplit, } from "./school-name.ts";
 export type { LexiconFlags, SchoolConcern, SchoolInitials, SchoolLexicon, SchoolName, SchoolNameParser, SchoolNameReader, SchoolNameReaderOptions, SchoolPart, SchoolPrintSplit, SchoolRefusal, } from "./school-name.ts";
-export { isColumnCutOf, isInitialismOf, isLadderLevel, mapOfSchools, probablySameSchool, sameInEveryPart, schoolCompare, schoolTokensAt, setOfSchools, } from "./school-compare.ts";
-export type { SchoolDop, SchoolMap, SchoolSet } from "./school-compare.ts";
+export { isColumnCutOf, isInitialismOf, isLadderLevel, mapOfSchools, probablySameSchool, SCHOOL_LEVEL_COLUMNS, schoolColumns, sameInEveryPart, schoolCompare, schoolTokensAt, setOfSchools, } from "./school-compare.ts";
+export type { SchoolDop, SchoolLevelColumn, SchoolMap, SchoolSet } from "./school-compare.ts";
+export { schoolEncoder } from "./school-encoder.ts";
+export type { SchoolEncoderOptions } from "./school-encoder.ts";
 export { compareSchoolNames, compareSchools } from "./school-identity.ts";
 export type { IdentityResult, IdentityVerdict } from "./school-identity.ts";
 export { foldSchoolName, hasSpecificToken, schoolKeyTokens } from "./school-match-key.ts";

package/dist/types/validated.d.ts

@@ -0,0 +1,4 @@
+export interface Validated<Reason extends string> {
+    isValid(): boolean;
+    invalidReason(): Reason | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/domain",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "Places, CLRG regions, school names, ages and dances as they are printed: read, compared and told apart",
 	"keywords": [
 		"places",
@@ -49,6 +49,10 @@
 			"types": "./dist/types/dance-types.d.ts",
 			"default": "./dist/dance-types.js"
 		},
+		"./noun-index": {
+			"types": "./dist/types/noun-index.d.ts",
+			"default": "./dist/noun-index.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"files": ["dist/*.js", "dist/chunks/*.js", "dist/types/**/*.d.ts", "README.md", "LICENSE"],
@@ -65,6 +69,6 @@
 		"prepublishOnly": "bun scripts/build.ts && bun scripts/guard-tarball.ts"
 	},
 	"dependencies": {
-		"@finbheara/names": "0.12.0"
+		"@finbheara/names": "0.17.0"
 	}
 }