@libraz/libcantus 0.9.2 → 0.9.3

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

@@ -2,6 +2,9 @@
  * 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,
@@ -45,3 +48,14 @@ export {
   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/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/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/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;
+}

package/src/generate/bass/index.ts

@@ -15,6 +15,12 @@
 import { isStrongBeat, type TimeSignature } from '../../core/meter/index.js';
 import { createRng } from '../../core/random/index.js';
 import type { KeyScale, NoteEvent } from '../../core/types.js';
+import {
+  assertGenerationBudget,
+  assertInteger,
+  assertRange,
+  assertTimeSignature,
+} from '../../core/validation/index.js';
 import type { Chord } from '../../theory/chord/index.js';
 import { nearestScaleTone } from '../../theory/scale/index.js';
 
@@ -282,14 +288,31 @@ function buildWalking(ctx: BuildContext, seg: BassSegment, next: BassSegment | u
  * @category Composition
  */
 export function generateBassLine(opts: BassLineOptions): NoteEvent[] {
+  assertGenerationBudget(opts.segments.length, 'bass segments');
+  for (let index = 0; index < opts.segments.length; index += 1) {
+    const segment = opts.segments[index];
+    if (!segment) continue;
+    assertRange(segment.startBeat, 0, Number.MAX_SAFE_INTEGER, `segments[${index}].startBeat`);
+    assertRange(segment.endBeat, 0, Number.MAX_SAFE_INTEGER, `segments[${index}].endBeat`);
+    if (segment.endBeat <= segment.startBeat) {
+      throw new RangeError(`segments[${index}] must have a positive duration`);
+    }
+  }
   const segments = [...opts.segments].sort((a, b) => a.startBeat - b.startBeat);
   if (segments.length === 0) {
     return [];
   }
 
   const ts = opts.ts ?? DEFAULT_TS;
+  assertTimeSignature(ts);
   const style = opts.style ?? DEFAULT_STYLE;
   const octave = opts.octave ?? DEFAULT_OCTAVE;
+  assertInteger(octave, 'bass octave', -1, 9);
+  const estimatedNotes = segments.reduce(
+    (count, segment) => count + Math.max(1, Math.ceil(segment.endBeat - segment.startBeat)),
+    0,
+  );
+  assertGenerationBudget(estimatedNotes, 'bass notes');
   const low = octave * 12 + 12;
 
   const ctx: BuildContext = {