@libraz/libcantus 0.9.1 → 0.9.3

package/src/{timeline → analyze/timeline}/index.ts

@@ -1,14 +1,21 @@
-import type { Chord } from '../chord/index.js';
-import { chordPitchClasses, makeChord } from '../chord/index.js';
+import { createNoteEventIndex } from '../../core/event-index/index.js';
+import type { TimeSignature } from '../../core/meter/index.js';
+import { beatsPerBar, metricWeight, parseTimeSignature } from '../../core/meter/index.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import {
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertNoteEvents,
+  assertRange,
+  assertTimeSignature,
+} from '../../core/validation/index.js';
+import type { Chord, ChordSpan } from '../../theory/chord/index.js';
+import { chordPitchClasses, makeChord } from '../../theory/chord/index.js';
+import { isScaleTone, majorKey } from '../../theory/scale/index.js';
 import type { ChordMatch } from '../detect/index.js';
 import { detectChord, detectChordBest, detectKey } from '../detect/index.js';
 import type { Cadence } from '../functional/index.js';
 import { detectCadence } from '../functional/index.js';
-import type { TimeSignature } from '../meter/index.js';
-import { beatsPerBar, metricWeight, parseTimeSignature } from '../meter/index.js';
-import type { GeneratedChord } from '../progression/index.js';
-import { isScaleTone, majorKey } from '../scale/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
 
 /**
  * A chord occupying a half-open beat span.
@@ -45,15 +52,25 @@ export type ChordTimeline = {
  * @returns A queryable chord timeline.
  * @category Arrangement & Analysis
  */
-export function chordTimelineFromChords(
-  chords: GeneratedChord[],
-  totalBeats: number,
-): ChordTimeline {
-  const sorted = [...chords].sort((a, b) => a.startBeat - b.startBeat);
+export function chordTimelineFromChords(chords: ChordSpan[], totalBeats: number): ChordTimeline {
+  assertRange(totalBeats, 0, Number.MAX_SAFE_INTEGER, 'timeline totalBeats');
+  assertGenerationBudget(chords.length, 'timeline chords');
+  for (let index = 0; index < chords.length; index += 1) {
+    assertRange(
+      chords[index]?.startBeat ?? Number.NaN,
+      0,
+      Number.MAX_SAFE_INTEGER,
+      `chords[${index}].startBeat`,
+    );
+  }
+  const sorted = [...chords]
+    .filter((chord) => chord.startBeat < totalBeats)
+    .sort((a, b) => a.startBeat - b.startBeat);
   const segments: ChordSegment[] = sorted
     .map((gc, i) => {
       const next = sorted[i + 1];
-      const endBeat = Math.max(gc.startBeat, next ? next.startBeat : totalBeats);
+      const nextBeat = next ? next.startBeat : totalBeats;
+      const endBeat = Math.min(totalBeats, Math.max(gc.startBeat, nextBeat));
       return {
         startBeat: gc.startBeat,
         endBeat,
@@ -68,6 +85,7 @@ export function chordTimelineFromChords(
 /** Build the `at(beat)` lookup over a segment list. */
 function segmentLookup(segments: ChordSegment[]): (beat: number) => Chord | null {
   return (beat) => {
+    assertFiniteNumber(beat, 'timeline query beat');
     for (const seg of segments) {
       if (beat >= seg.startBeat && beat < seg.endBeat) {
         return seg.chord;
@@ -321,23 +339,37 @@ export function chordTimelineFromNotes(
   opts: ChordTimelineOptions = {},
 ): ChordTimelineResult {
   const ts = opts.ts ?? parseTimeSignature('4/4');
+  assertTimeSignature(ts);
   const harmonicRhythm = opts.harmonicRhythm ?? beatsPerBar(ts);
-  if (!(harmonicRhythm > 0)) {
-    throw new Error(`Invalid harmonic rhythm: ${harmonicRhythm}`);
-  }
+  assertRange(harmonicRhythm, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER, 'harmonic rhythm');
+  assertNoteEvents(notes, 'timeline notes', { allowNonPositiveDuration: true });
   // Zero/negative-length notes never sound; drop them before any inference.
-  const sounding = notes.filter((note) => note.durationBeat > 0);
+  const soundingIndex = createNoteEventIndex(notes.filter((note) => note.durationBeat > 0));
+  const sounding = soundingIndex.notes.map(({ note }) => note);
   const lastNoteEnd = sounding.reduce((end, n) => Math.max(end, n.startBeat + n.durationBeat), 0);
   const totalBeats = opts.totalBeats ?? lastNoteEnd;
+  assertRange(totalBeats, 0, Number.MAX_SAFE_INTEGER, 'timeline totalBeats');
   const key = opts.key ?? detectKey(sounding.map((n) => n.pitch))[0]?.key ?? majorKey(0);
 
   const segments: ChordSegment[] = [];
   const segmentConfidence: number[] = [];
   const windowCount = Math.max(0, Math.ceil(totalBeats / harmonicRhythm - EPS));
+  assertGenerationBudget(windowCount, 'timeline windows');
+  const windowNotes: NoteEvent[][] = Array.from({ length: windowCount }, () => []);
+  let memberships = 0;
+  for (const indexed of soundingIndex.notes) {
+    const first = Math.max(0, Math.floor(indexed.note.startBeat / harmonicRhythm));
+    const lastExclusive = Math.min(windowCount, Math.ceil(indexed.endBeat / harmonicRhythm));
+    memberships += Math.max(0, lastExclusive - first);
+    assertGenerationBudget(memberships, 'timeline note-to-window memberships');
+    for (let window = first; window < lastExclusive; window += 1) {
+      windowNotes[window]?.push(indexed.note);
+    }
+  }
   for (let i = 0; i < windowCount; i += 1) {
     const start = i * harmonicRhythm;
     const end = Math.min(start + harmonicRhythm, totalBeats);
-    const inferred = analyzeWindow(sounding, start, end, ts, key);
+    const inferred = analyzeWindow(windowNotes[i] ?? [], start, end, ts, key);
     if (!inferred) {
       continue;
     }

package/src/{analysis → analyze/voice}/index.ts

@@ -1,8 +1,12 @@
-import type { Chord } from '../chord/index.js';
-import { chordPitchClasses, chordToneRole } from '../chord/index.js';
-import { createsVerticalDissonance, isLeadingToneResolution } from '../counterpoint/index.js';
-import type { VoiceSnapshot } from '../safety/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import { assertNoteEvents } from '../../core/validation/index.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { chordPitchClasses, chordToneRole } from '../../theory/chord/index.js';
+import {
+  createsVerticalDissonance,
+  isLeadingToneResolution,
+} from '../../theory/counterpoint/index.js';
+import type { VoiceSnapshot } from '../../theory/safety/index.js';
 
 /**
  * A theory annotation attached to a note.
@@ -162,6 +166,7 @@ export function analyzeVoice(
   key: KeyScale,
   otherVoicesAtBeat: (beat: number) => VoiceSnapshot[],
 ): AnalyzedNote[] {
+  assertNoteEvents(voice, 'voice notes', { allowNonPositiveDuration: true });
   const result: AnalyzedNote[] = [];
 
   for (let i = 0; i < voice.length; i += 1) {
@@ -174,10 +179,17 @@ export function analyzeVoice(
     // A neighboring note sharing this note's onset is a simultaneous cluster
     // member, not a melodic predecessor/successor; treating it as one would
     // fabricate passing/suspension figures, so it is dropped here.
+    const prevEnd =
+      prevNote === undefined
+        ? Number.NEGATIVE_INFINITY
+        : prevNote.startBeat + prevNote.durationBeat;
+    const noteEnd = note.startBeat + note.durationBeat;
     const prev =
-      prevNote !== undefined && prevNote.startBeat < note.startBeat - EPS ? prevNote : undefined;
+      prevNote !== undefined && Math.abs(prevEnd - note.startBeat) <= EPS ? prevNote : undefined;
     const next =
-      nextNote !== undefined && nextNote.startBeat > note.startBeat + EPS ? nextNote : undefined;
+      nextNote !== undefined && Math.abs(noteEnd - nextNote.startBeat) <= EPS
+        ? nextNote
+        : undefined;
     const chord = chordAtBeat(note.startBeat);
     const labels: TheoryLabel[] = [];
     const member = isChordMember(note.pitch, chord);

package/src/core/event-index/index.ts

@@ -0,0 +1,104 @@
+import type { NoteEvent } from '../types.js';
+import { assertNoteEvents } from '../validation/index.js';
+
+/** A validated note retaining its position in the caller's original array. */
+export type IndexedNoteEvent = {
+  note: NoteEvent;
+  originalIndex: number;
+  endBeat: number;
+};
+
+/** Binary-searchable, stable-sorted index over note onsets and active spans. */
+export type NoteEventIndex = {
+  notes: IndexedNoteEvent[];
+  /** Latest-onset note sounding at `beat`, with later input order winning ties. */
+  at: (beat: number) => IndexedNoteEvent | undefined;
+  /** Whether one or more notes attack at `beat`. */
+  attacksAt: (beat: number) => boolean;
+  /** Unique attack beats strictly inside `(startBeat, endBeat)`. */
+  onsetsBetween: (startBeat: number, endBeat: number) => number[];
+};
+
+const EPS = 1e-9;
+
+function upperBound(values: IndexedNoteEvent[], beat: number): number {
+  let low = 0;
+  let high = values.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if ((values[middle]?.note.startBeat ?? Number.POSITIVE_INFINITY) <= beat) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  return low;
+}
+
+/**
+ * Validate and stable-sort note events once, then expose logarithmic onset and
+ * active-note lookups. Non-positive-duration notes may be retained for callers
+ * that intentionally filter them later, but never count as sounding.
+ */
+export function createNoteEventIndex(
+  events: NoteEvent[],
+  options: { allowNonPositiveDuration?: boolean } = {},
+): NoteEventIndex {
+  assertNoteEvents(events, 'note events', options);
+  const notes = events
+    .map((note, originalIndex) => ({
+      note,
+      originalIndex,
+      endBeat: note.startBeat + note.durationBeat,
+    }))
+    .sort((a, b) => a.note.startBeat - b.note.startBeat || a.originalIndex - b.originalIndex);
+  const prefixMaxEnd: number[] = [];
+  let maxEnd = Number.NEGATIVE_INFINITY;
+  for (const indexed of notes) {
+    maxEnd = Math.max(maxEnd, indexed.endBeat);
+    prefixMaxEnd.push(maxEnd);
+  }
+
+  return {
+    notes,
+    at(beat) {
+      let index = upperBound(notes, beat + EPS) - 1;
+      while (index >= 0) {
+        if ((prefixMaxEnd[index] ?? Number.NEGATIVE_INFINITY) <= beat + EPS) {
+          return undefined;
+        }
+        const indexed = notes[index];
+        if (
+          indexed &&
+          indexed.note.durationBeat > 0 &&
+          indexed.note.startBeat - EPS <= beat &&
+          beat < indexed.endBeat - EPS
+        ) {
+          return indexed;
+        }
+        index -= 1;
+      }
+      return undefined;
+    },
+    attacksAt(beat) {
+      const firstAfter = upperBound(notes, beat + EPS);
+      const candidate = notes[firstAfter - 1];
+      return candidate !== undefined && Math.abs(candidate.note.startBeat - beat) < EPS;
+    },
+    onsetsBetween(startBeat, endBeat) {
+      const result: number[] = [];
+      let index = upperBound(notes, startBeat + EPS);
+      while (index < notes.length) {
+        const onset = notes[index]?.note.startBeat;
+        if (onset === undefined || onset >= endBeat - EPS) {
+          break;
+        }
+        if (result[result.length - 1] !== onset) {
+          result.push(onset);
+        }
+        index += 1;
+      }
+      return result;
+    },
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Public API of the core layer. Re-exports every core-layer module;
+ * also available from the package root.
+ */
+
+export type { IndexedNoteEvent, NoteEventIndex } from './event-index/index.js';
+export { createNoteEventIndex } from './event-index/index.js';
+export {
+  classifyInterval,
+  IntervalQuality,
+  isConsonantInterval,
+  isPerfectInterval,
+} from './interval/index.js';
+export type { BarPosition, TimeSignature } from './meter/index.js';
+export {
+  barPositionToBeat,
+  beatsPerBar,
+  beatToBarPosition,
+  formatTimeSignature,
+  isCompound,
+  isStrongBeat,
+  metricWeight,
+  parseTimeSignature,
+  pulsesPerBar,
+  tuplet,
+} from './meter/index.js';
+export type { Note as NoteData, SpelledInterval } from './pitch/index.js';
+export {
+  formatNote,
+  midiToNote,
+  noteToMidi,
+  noteToPitchClass,
+  parseNote,
+  spelledInterval,
+} from './pitch/index.js';
+export type { Rng } from './random/index.js';
+export { createRng } from './random/index.js';
+export type { Tuning } from './tuning/index.js';
+export {
+  centsBetweenFreq,
+  centsOfSteps,
+  edo,
+  frequencyOf,
+  JUST_RATIOS,
+  justDeviationCents,
+  nearestStep,
+  ratioToCents,
+  TWELVE_TET,
+} from './tuning/index.js';
+export type { KeyScale, NoteEvent } from './types.js';
+export {
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertInteger,
+  assertNoteEvent,
+  assertNoteEvents,
+  assertPositiveInt,
+  assertRange,
+  assertTimeSignature,
+  DEFAULT_GENERATION_BUDGET,
+} from './validation/index.js';

package/src/{meter → core/meter}/index.ts

@@ -6,6 +6,14 @@
  * of the library's beat convention (four quarter-note beats per bar in 4/4).
  */
 
+import {
+  assertFiniteNumber,
+  assertInteger,
+  assertPositiveInt,
+  assertRange,
+  assertTimeSignature,
+} from '../validation/index.js';
+
 /**
  * A time signature as a numerator over a note-value denominator.
  *
@@ -68,7 +76,12 @@ export function parseTimeSignature(text: string): TimeSignature {
   }
   const numerator = Number.parseInt(match[1] ?? '', 10);
   const denominator = Number.parseInt(match[2] ?? '', 10);
-  if (numerator <= 0 || denominator <= 0) {
+  if (
+    !Number.isSafeInteger(numerator) ||
+    !Number.isSafeInteger(denominator) ||
+    numerator <= 0 ||
+    denominator <= 0
+  ) {
     throw new Error(`Invalid time signature: ${text}`);
   }
   return { numerator, denominator };
@@ -80,6 +93,7 @@ export function parseTimeSignature(text: string): TimeSignature {
  * @category Rhythm & Meter
  */
 export function formatTimeSignature(ts: TimeSignature): string {
+  assertTimeSignature(ts);
   return `${ts.numerator}/${ts.denominator}`;
 }
 
@@ -94,6 +108,7 @@ export function formatTimeSignature(ts: TimeSignature): string {
  * @category Rhythm & Meter
  */
 export function isCompound(ts: TimeSignature): boolean {
+  assertTimeSignature(ts);
   return ts.numerator % 3 === 0 && ts.numerator > 3;
 }
 
@@ -110,6 +125,7 @@ function unitBeats(ts: TimeSignature): number {
  * @category Rhythm & Meter
  */
 export function beatsPerBar(ts: TimeSignature): number {
+  assertTimeSignature(ts);
   return ts.numerator * unitBeats(ts);
 }
 
@@ -181,6 +197,7 @@ function isGroupHead(grouping: number[], pulseIndex: number): boolean {
  * @category Rhythm & Meter
  */
 export function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition {
+  assertFiniteNumber(beatInQuarters, 'beat');
   const barLen = beatsPerBar(ts);
   const bar = Math.floor(beatInQuarters / barLen);
   return { bar, beat: beatInQuarters - bar * barLen };
@@ -196,6 +213,8 @@ export function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): Ba
  * @category Rhythm & Meter
  */
 export function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number {
+  assertInteger(pos.bar, 'bar position bar');
+  assertFiniteNumber(pos.beat, 'bar position beat');
   return pos.bar * beatsPerBar(ts) + pos.beat;
 }
 
@@ -225,6 +244,8 @@ export function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number {
  * @category Rhythm & Meter
  */
 export function metricWeight(beatInQuarters: number, ts: TimeSignature): number {
+  assertFiniteNumber(beatInQuarters, 'beat');
+  assertTimeSignature(ts);
   const { beat } = beatToBarPosition(beatInQuarters, ts);
   const pulse = pulseBeats(ts);
   if (!isMultiple(beat, pulse)) {
@@ -275,8 +296,7 @@ export function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean
  * @category Rhythm & Meter
  */
 export function tuplet(totalBeats: number, count: number): number[] {
-  if (!Number.isInteger(count) || count <= 0) {
-    throw new Error(`Invalid tuplet count: ${count}`);
-  }
+  assertRange(totalBeats, 0, Number.MAX_SAFE_INTEGER, 'tuplet total beats');
+  assertPositiveInt(count, 'tuplet count');
   return new Array<number>(count).fill(totalBeats / count);
 }

package/src/{random → core/random}/index.ts

@@ -5,6 +5,8 @@
  * seed the stream is fully reproducible.
  */
 
+import { assertFiniteNumber, assertInteger, assertRange } from '../validation/index.js';
+
 /**
  * A deterministic PRNG with the sampling helpers the generators need.
  *
@@ -36,6 +38,7 @@ export type Rng = {
  * @category Utilities
  */
 export function createRng(seed: number): Rng {
+  assertFiniteNumber(seed, 'seed');
   let state = seed >>> 0;
   const next = () => {
     state = (state + 0x6d2b79f5) >>> 0;
@@ -46,8 +49,28 @@ export function createRng(seed: number): Rng {
   };
   return {
     next,
-    prob: (p) => next() < p,
-    range: (lo, hi) => lo + Math.floor(next() * (hi - lo + 1)),
-    float: (lo, hi) => lo + next() * (hi - lo),
+    prob: (p) => next() < assertRange(p, 0, 1, 'probability'),
+    range: (lo, hi) => {
+      assertInteger(lo, 'range lower bound');
+      assertInteger(hi, 'range upper bound');
+      if (lo > hi) {
+        throw new RangeError(
+          `range lower bound must not exceed upper bound; received ${lo} > ${hi}`,
+        );
+      }
+      assertInteger(hi - lo, 'range span', 0);
+      return lo + Math.floor(next() * (hi - lo + 1));
+    },
+    float: (lo, hi) => {
+      assertFiniteNumber(lo, 'float lower bound');
+      assertFiniteNumber(hi, 'float upper bound');
+      if (lo > hi) {
+        throw new RangeError(
+          `float lower bound must not exceed upper bound; received ${lo} > ${hi}`,
+        );
+      }
+      assertFiniteNumber(hi - lo, 'float span');
+      return lo + next() * (hi - lo);
+    },
   };
 }

package/src/{tuning → core/tuning}/index.ts

@@ -8,6 +8,13 @@
  * acoustic (just) tuning behind the tempered intervals.
  */
 
+import {
+  assertFiniteNumber,
+  assertInteger,
+  assertPositiveInt,
+  assertRange,
+} from '../validation/index.js';
+
 /**
  * An equal-tempered tuning: a reference pitch and a number of equal divisions of
  * the octave. With `divisions === 12` a step index is an ordinary MIDI number.
@@ -30,6 +37,13 @@ export type Tuning = {
  */
 export const TWELVE_TET: Tuning = { refStep: 69, refFreq: 440, divisions: 12 };
 
+function assertTuning(tuning: Tuning): Tuning {
+  assertFiniteNumber(tuning.refStep, 'tuning.refStep');
+  assertRange(tuning.refFreq, Number.MIN_VALUE, Number.MAX_VALUE, 'tuning.refFreq');
+  assertPositiveInt(tuning.divisions, 'tuning.divisions');
+  return tuning;
+}
+
 /**
  * Build an equal temperament with `n` divisions of the octave.
  *
@@ -46,6 +60,9 @@ export const TWELVE_TET: Tuning = { refStep: 69, refFreq: 440, divisions: 12 };
  * @category Pitch & Intervals
  */
 export function edo(n: number, refFreq = 440, refStep = 69): Tuning {
+  assertPositiveInt(n, 'EDO divisions');
+  assertRange(refFreq, Number.MIN_VALUE, Number.MAX_VALUE, 'reference frequency');
+  assertFiniteNumber(refStep, 'reference step');
   return { refStep, refFreq, divisions: n };
 }
 
@@ -64,7 +81,10 @@ export function edo(n: number, refFreq = 440, refStep = 69): Tuning {
  * @category Pitch & Intervals
  */
 export function frequencyOf(step: number, tuning: Tuning = TWELVE_TET): number {
-  return tuning.refFreq * 2 ** ((step - tuning.refStep) / tuning.divisions);
+  assertFiniteNumber(step, 'step');
+  assertTuning(tuning);
+  const result = tuning.refFreq * 2 ** ((step - tuning.refStep) / tuning.divisions);
+  return assertRange(result, Number.MIN_VALUE, Number.MAX_VALUE, 'frequency result');
 }
 
 /**
@@ -77,6 +97,8 @@ export function frequencyOf(step: number, tuning: Tuning = TWELVE_TET): number {
  * @category Pitch & Intervals
  */
 export function nearestStep(freq: number, tuning: Tuning = TWELVE_TET): number {
+  assertRange(freq, Number.MIN_VALUE, Number.MAX_VALUE, 'frequency');
+  assertTuning(tuning);
   return Math.round(tuning.refStep + tuning.divisions * Math.log2(freq / tuning.refFreq));
 }
 
@@ -89,7 +111,9 @@ export function nearestStep(freq: number, tuning: Tuning = TWELVE_TET): number {
  * @category Pitch & Intervals
  */
 export function centsBetweenFreq(a: number, b: number): number {
-  return 1200 * Math.log2(b / a);
+  assertRange(a, Number.MIN_VALUE, Number.MAX_VALUE, 'first frequency');
+  assertRange(b, Number.MIN_VALUE, Number.MAX_VALUE, 'second frequency');
+  return 1200 * (Math.log2(b) - Math.log2(a));
 }
 
 /**
@@ -101,7 +125,9 @@ export function centsBetweenFreq(a: number, b: number): number {
  * @category Pitch & Intervals
  */
 export function centsOfSteps(steps: number, tuning: Tuning = TWELVE_TET): number {
-  return (steps * 1200) / tuning.divisions;
+  assertFiniteNumber(steps, 'steps');
+  assertTuning(tuning);
+  return assertFiniteNumber((steps * 1200) / tuning.divisions, 'cents result');
 }
 
 /**
@@ -114,7 +140,9 @@ export function centsOfSteps(steps: number, tuning: Tuning = TWELVE_TET): number
  * @category Pitch & Intervals
  */
 export function ratioToCents(numerator: number, denominator: number): number {
-  return 1200 * Math.log2(numerator / denominator);
+  assertRange(numerator, Number.MIN_VALUE, Number.MAX_VALUE, 'ratio numerator');
+  assertRange(denominator, Number.MIN_VALUE, Number.MAX_VALUE, 'ratio denominator');
+  return 1200 * (Math.log2(numerator) - Math.log2(denominator));
 }
 
 /**
@@ -144,13 +172,15 @@ export const JUST_RATIOS: Record<number, [number, number]> = {
  * (positive means the just interval is wider).
  *
  * @param semitoneClass Semitone class in [0, 12].
- * @returns The deviation in cents, or NaN if the class has no listed ratio.
+ * @returns The deviation in cents.
+ * @throws If `semitoneClass` is not an integer in [0, 12].
  * @category Pitch & Intervals
  */
 export function justDeviationCents(semitoneClass: number): number {
+  assertInteger(semitoneClass, 'semitone class', 0, 12);
   const ratio = JUST_RATIOS[semitoneClass];
   if (!ratio) {
-    return Number.NaN;
+    throw new RangeError(`semitone class has no just ratio: ${semitoneClass}`);
   }
   return ratioToCents(ratio[0], ratio[1]) - semitoneClass * 100;
 }

package/src/core/validation/index.ts

@@ -0,0 +1,119 @@
+import type { TimeSignature } from '../meter/index.js';
+import type { NoteEvent } from '../types.js';
+
+/** Default upper bound for synchronous event/window/candidate generation. */
+export const DEFAULT_GENERATION_BUDGET = 1_000_000;
+
+/** Require a finite JavaScript number and return it unchanged. */
+export function assertFiniteNumber(value: number, name: string): number {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`${name} must be finite; received ${value}`);
+  }
+  return value;
+}
+
+/** Require an integer in the inclusive range `[min, max]`. */
+export function assertInteger(
+  value: number,
+  name: string,
+  min = Number.MIN_SAFE_INTEGER,
+  max = Number.MAX_SAFE_INTEGER,
+): number {
+  assertFiniteNumber(value, name);
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw new RangeError(`${name} must be an integer in [${min}, ${max}]; received ${value}`);
+  }
+  return value;
+}
+
+/** Require a positive safe integer, optionally capped by `max`. */
+export function assertPositiveInt(
+  value: number,
+  name: string,
+  max = DEFAULT_GENERATION_BUDGET,
+): number {
+  return assertInteger(value, name, 1, max);
+}
+
+/** Require a finite number in the inclusive range `[min, max]`. */
+export function assertRange(value: number, min: number, max: number, name: string): number {
+  assertFiniteNumber(value, name);
+  if (value < min || value > max) {
+    throw new RangeError(`${name} must be in [${min}, ${max}]; received ${value}`);
+  }
+  return value;
+}
+
+/** Reject work estimates that would exceed a synchronous generation budget. */
+export function assertGenerationBudget(
+  estimated: number,
+  name: string,
+  limit = DEFAULT_GENERATION_BUDGET,
+): number {
+  assertFiniteNumber(estimated, name);
+  assertPositiveInt(limit, `${name} limit`, Number.MAX_SAFE_INTEGER);
+  if (estimated < 0 || estimated > limit) {
+    throw new RangeError(`${name} exceeds the generation budget ${limit}; received ${estimated}`);
+  }
+  return estimated;
+}
+
+/** Validate a time signature, including additive grouping, before any early return. */
+export function assertTimeSignature(ts: TimeSignature, name = 'time signature'): TimeSignature {
+  assertPositiveInt(ts.numerator, `${name}.numerator`);
+  assertPositiveInt(ts.denominator, `${name}.denominator`);
+  if (ts.grouping !== undefined) {
+    if (ts.grouping.length === 0) {
+      throw new RangeError(`${name}.grouping must not be empty`);
+    }
+    let sum = 0;
+    for (let index = 0; index < ts.grouping.length; index += 1) {
+      sum += assertPositiveInt(ts.grouping[index] ?? Number.NaN, `${name}.grouping[${index}]`);
+    }
+    const compound = ts.numerator % 3 === 0 && ts.numerator > 3;
+    const pulses = compound ? ts.numerator / 3 : ts.numerator;
+    if (sum !== pulses) {
+      throw new RangeError(`${name}.grouping must sum to ${pulses}; received ${sum}`);
+    }
+  }
+  return ts;
+}
+
+/** Validate the finite fields of one timeline note event. */
+export function assertNoteEvent(
+  event: NoteEvent,
+  name = 'note event',
+  options: { allowNonPositiveDuration?: boolean } = {},
+): NoteEvent {
+  assertFiniteNumber(event.pitch, `${name}.pitch`);
+  assertRange(event.startBeat, 0, Number.MAX_SAFE_INTEGER, `${name}.startBeat`);
+  assertRange(
+    event.durationBeat,
+    options.allowNonPositiveDuration ? -Number.MAX_SAFE_INTEGER : Number.MIN_VALUE,
+    Number.MAX_SAFE_INTEGER,
+    `${name}.durationBeat`,
+  );
+  if (!options.allowNonPositiveDuration && event.durationBeat <= 0) {
+    throw new RangeError(`${name}.durationBeat must be positive; received ${event.durationBeat}`);
+  }
+  if (event.velocity !== undefined) {
+    assertRange(event.velocity, 0, 127, `${name}.velocity`);
+  }
+  return event;
+}
+
+/** Validate an event array and its allocation budget without copying it. */
+export function assertNoteEvents(
+  events: NoteEvent[],
+  name = 'note events',
+  options: { allowNonPositiveDuration?: boolean; budget?: number } = {},
+): NoteEvent[] {
+  assertGenerationBudget(events.length, `${name} count`, options.budget);
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    if (event !== undefined) {
+      assertNoteEvent(event, `${name}[${index}]`, options);
+    }
+  }
+  return events;
+}