@libraz/libcantus 0.9.2 → 0.9.4

package/src/model/key.ts

@@ -1,266 +0,0 @@
-import { isMinorKey, romanToChord } from '../analyze/functional/index.js';
-import type { Note as NoteData } from '../core/pitch/index.js';
-import type { KeyScale } from '../core/types.js';
-import {
-  type ChordQuality,
-  chordFromDegree,
-  diatonicSeventh,
-  diatonicTriad,
-} from '../theory/chord/index.js';
-import {
-  isScaleTone,
-  majorKey,
-  minorKey,
-  scaleByName,
-  scaleTonesInDegreeOrder,
-} from '../theory/scale/index.js';
-import { spellScale } from '../theory/spelling/index.js';
-import { Chord } from './chord.js';
-import { Note } from './note.js';
-import { mod12, spellPitchClassBare } from './shared.js';
-
-/** Resolve a string or numeric key root into a spelled tonic note. */
-function resolveTonic(root: string | number, spelling: 'sharp' | 'flat'): Note {
-  return typeof root === 'string' ? Note.of(root) : new Note(spellPitchClassBare(root, spelling));
-}
-
-/** Total accidentals a spelled tonic produces across a key's whole scale. */
-function accidentalLoad(tonic: NoteData, scale: KeyScale): number {
-  return spellScale(tonic, scale).reduce((sum, note) => sum + Math.abs(note.alter), 0);
-}
-
-/**
- * Choose the tonic spelling (sharp- or flat-side) that spells `scale` with the
- * fewest accidentals, so a numeric root never yields a double-flat/double-sharp
- * scale (e.g. pitch class 6 minor spells as F# minor, not Gb minor with Bbb).
- */
-function bestTonicForScale(rootPc: number, scale: KeyScale): Note {
-  const sharp = spellPitchClassBare(rootPc, 'sharp');
-  const flat = spellPitchClassBare(rootPc, 'flat');
-  if (sharp.letter === flat.letter && sharp.alter === flat.alter) {
-    return new Note(sharp);
-  }
-  return accidentalLoad(flat, scale) <= accidentalLoad(sharp, scale)
-    ? new Note(flat)
-    : new Note(sharp);
-}
-
-/**
- * An immutable key/scale: a `KeyScale` (root pitch class plus mode mask) paired
- * with a spelled tonic that anchors letter-name spelling. Acts as the factory
- * for key-aware chords.
- *
- * @category Class API
- * @example
- * ```ts
- * import { Key } from '@libraz/libcantus';
- * Key.major('C').chord(4).symbol(); // 'G' (the diatonic triad on scale degree 4)
- * ```
- */
-export class Key {
-  readonly #scale: KeyScale;
-  readonly #tonic: Note;
-
-  /**
-   * Wrap a key/scale and its spelled tonic.
-   *
-   * @param scale The key/scale; its root is normalized to a pitch class.
-   * @param tonic The spelled tonic anchoring letter-name spelling.
-   */
-  constructor(scale: KeyScale, tonic: Note) {
-    this.#scale = { rootPc: mod12(scale.rootPc), modeMask12: scale.modeMask12 };
-    this.#tonic = tonic;
-  }
-
-  /**
-   * A major key.
-   *
-   * @param root Tonic as a note name (e.g. `'Eb'`) or a pitch class; a numeric
-   *   root is spelled with whichever accidental side yields the fewest
-   *   accidentals across the scale.
-   * @returns The major key.
-   */
-  static major(root: string | number): Key {
-    if (typeof root === 'string') {
-      const tonic = Note.of(root);
-      return new Key(majorKey(tonic.pitchClass), tonic);
-    }
-    const scale = majorKey(root);
-    return new Key(scale, bestTonicForScale(root, scale));
-  }
-
-  /**
-   * A natural-minor key.
-   *
-   * @param root Tonic as a note name or a pitch class; a numeric root is
-   *   spelled with whichever accidental side yields the fewest accidentals
-   *   across the scale.
-   * @returns The minor key.
-   */
-  static minor(root: string | number): Key {
-    if (typeof root === 'string') {
-      const tonic = Note.of(root);
-      return new Key(minorKey(tonic.pitchClass), tonic);
-    }
-    const scale = minorKey(root);
-    return new Key(scale, bestTonicForScale(root, scale));
-  }
-
-  /**
-   * A key on a named scale (e.g. `'dorian'`, `'harmonicMinor'`).
-   *
-   * @param name The scale name, a key of the scale module's named-scale table.
-   * @param root Tonic as a note name or a pitch class.
-   * @returns The key.
-   * @throws If the name is not a known scale.
-   */
-  static named(name: string, root: string | number): Key {
-    const tonic = resolveTonic(root, 'sharp');
-    return new Key(scaleByName(name, tonic.pitchClass), tonic);
-  }
-
-  /**
-   * Wrap an existing `KeyScale`, synthesizing a spelled tonic when none is
-   * given (flat-preferred for minor-third scales, sharp-preferred otherwise).
-   *
-   * @param scale The key/scale to wrap.
-   * @param tonic Optional spelled tonic.
-   * @returns The key.
-   */
-  static of(scale: KeyScale, tonic?: Note): Key {
-    const spelled =
-      tonic ?? new Note(spellPitchClassBare(scale.rootPc, isMinorKey(scale) ? 'flat' : 'sharp'));
-    return new Key(scale, spelled);
-  }
-
-  /** A copy of the underlying plain `KeyScale`. */
-  get scale(): KeyScale {
-    return { rootPc: this.#scale.rootPc, modeMask12: this.#scale.modeMask12 };
-  }
-
-  /** The spelled tonic. */
-  get tonic(): Note {
-    return this.#tonic;
-  }
-
-  /** The tonic pitch class (0..11). */
-  get rootPc(): number {
-    return this.#scale.rootPc;
-  }
-
-  /** Whether the scale has a minor third and no major third. */
-  get isMinor(): boolean {
-    return isMinorKey(this.#scale);
-  }
-
-  /**
-   * The scale's pitch classes in ascending scale-degree order (degree 0 first).
-   *
-   * @returns One pitch class per scale degree.
-   */
-  pitchClasses(): number[] {
-    return scaleTonesInDegreeOrder(this.#scale);
-  }
-
-  /**
-   * The spelled scale, one note per degree (e.g. C D E F G A B for C major).
-   *
-   * @returns Spelled octave-less notes in scale-degree order.
-   */
-  notes(): Note[] {
-    return spellScale(this.#tonic.data, this.#scale).map((note) => new Note(note));
-  }
-
-  /**
-   * Alias of {@link Key.notes}.
-   *
-   * @returns Spelled octave-less notes in scale-degree order.
-   */
-  spell(): Note[] {
-    return this.notes();
-  }
-
-  /**
-   * The spelled scale as letter-name strings.
-   *
-   * @returns One name per scale degree.
-   */
-  noteNames(): string[] {
-    return this.notes().map((note) => note.name);
-  }
-
-  /**
-   * Build a chord on a scale degree, carrying this key as context.
-   *
-   * With an explicit quality the quality's interval template is attached to the
-   * degree's diatonic root; without one the scale-correct diatonic triad is
-   * stacked (e.g. a diminished triad on the leading tone of a major key).
-   *
-   * @param degree 0-based scale degree of the chord root.
-   * @param quality Optional chord quality.
-   * @returns The chord, with this key attached.
-   */
-  chord(degree: number, quality?: ChordQuality): Chord {
-    const data =
-      quality === undefined
-        ? diatonicTriad(degree, this.#scale)
-        : chordFromDegree(degree, quality, this.#scale);
-    return new Chord(data, this);
-  }
-
-  /**
-   * The diatonic triad on a scale degree, carrying this key as context.
-   *
-   * @param degree 0-based scale degree of the chord root.
-   * @returns The triad, with this key attached.
-   */
-  diatonicTriad(degree: number): Chord {
-    return new Chord(diatonicTriad(degree, this.#scale), this);
-  }
-
-  /**
-   * The diatonic seventh chord on a scale degree, carrying this key as context.
-   *
-   * @param degree 0-based scale degree of the chord root.
-   * @returns The seventh chord, with this key attached.
-   */
-  diatonicSeventh(degree: number): Chord {
-    return new Chord(diatonicSeventh(degree, this.#scale), this);
-  }
-
-  /**
-   * Build the chord denoted by a Roman numeral in this key (including applied
-   * chords such as `'V7/V'`), carrying this key as context.
-   *
-   * @param text The Roman numeral.
-   * @returns The chord, with this key attached.
-   * @throws If the numeral is not valid.
-   */
-  roman(text: string): Chord {
-    return new Chord(romanToChord(text, this.#scale), this);
-  }
-
-  /**
-   * Whether a pitch belongs to the scale.
-   *
-   * @param x A MIDI pitch, bare pitch class, or note.
-   * @returns True if the pitch class is a scale tone.
-   */
-  contains(x: number | Note): boolean {
-    return isScaleTone(typeof x === 'number' ? x : x.pitchClass, this.#scale);
-  }
-
-  /**
-   * The plain key data, for JSON serialization.
-   *
-   * Private class fields do not serialize, so an explicit `toJSON` keeps
-   * `JSON.stringify(key)` from collapsing to `{}`. The result pairs the
-   * `KeyScale` with the spelled tonic, enough to reconstruct the key via
-   * {@link Key.of}.
-   *
-   * @returns The key/scale and its spelled tonic.
-   */
-  toJSON(): { scale: KeyScale; tonic: NoteData } {
-    return { scale: this.scale, tonic: this.#tonic.data };
-  }
-}

package/src/model/note.ts

@@ -1,176 +0,0 @@
-import {
-  formatNote,
-  midiToNote,
-  type Note as NoteData,
-  noteToMidi,
-  noteToPitchClass,
-  parseNote,
-  type SpelledInterval,
-  spelledInterval,
-} from '../core/pitch/index.js';
-import { spellPitchClassBare } from './shared.js';
-
-/** Defensive copy of a plain note. */
-function copyNote(data: NoteData): NoteData {
-  const copy: NoteData = { letter: data.letter, alter: data.alter };
-  if (data.octave !== undefined) {
-    copy.octave = data.octave;
-  }
-  return copy;
-}
-
-/**
- * An immutable spelled note: a diatonic letter plus a chromatic alteration and
- * an optional octave. Wraps the plain note object and delegates to the pitch
- * module; every transformation returns a new instance.
- *
- * @category Class API
- * @example
- * ```ts
- * import { Note } from '@libraz/libcantus';
- * Note.of('C4').transpose(7).name; // 'G4'
- * ```
- */
-export class Note {
-  readonly #data: NoteData;
-
-  /**
-   * Wrap a plain note object.
-   *
-   * @param data The spelled note; it is copied, never retained or mutated.
-   */
-  constructor(data: NoteData) {
-    this.#data = copyNote(data);
-  }
-
-  /**
-   * Parse scientific pitch notation (e.g. `'C#4'`, `'Bb'`, `'F##3'`).
-   *
-   * @param name The note text.
-   * @returns The parsed note.
-   * @throws If the text is not a valid note.
-   */
-  static of(name: string): Note {
-    return new Note(parseNote(name));
-  }
-
-  /**
-   * Name a MIDI number (middle C = C4 = 60) as a note.
-   *
-   * @param midi The MIDI number.
-   * @param spelling Whether to prefer sharps or flats for black keys.
-   * @returns The spelled note, with octave.
-   */
-  static fromMidi(midi: number, spelling: 'sharp' | 'flat' = 'sharp'): Note {
-    return new Note(midiToNote(midi, spelling));
-  }
-
-  /**
-   * Wrap an existing plain note object.
-   *
-   * @param data The plain note.
-   * @returns The wrapped note.
-   */
-  static fromData(data: NoteData): Note {
-    return new Note(data);
-  }
-
-  /** The note rendered as scientific pitch notation, e.g. `'G4'` or `'Bb'`. */
-  get name(): string {
-    return formatNote(this.#data);
-  }
-
-  /** The pitch class (0..11), ignoring octave. */
-  get pitchClass(): number {
-    return noteToPitchClass(this.#data);
-  }
-
-  /**
-   * The MIDI number (middle C = C4 = 60).
-   *
-   * @throws If the note has no octave and therefore no fixed pitch.
-   */
-  get midi(): number {
-    if (this.#data.octave === undefined) {
-      throw new Error(`note ${this.name} has no octave, so it has no MIDI number`);
-    }
-    return noteToMidi(this.#data);
-  }
-
-  /** The diatonic letter number: 0..6 for C..B. */
-  get letter(): number {
-    return this.#data.letter;
-  }
-
-  /** The chromatic alteration in semitones: -1 flat, 0 natural, +1 sharp, ... */
-  get alter(): number {
-    return this.#data.alter;
-  }
-
-  /** The octave (scientific pitch notation), or undefined for a bare pitch class. */
-  get octave(): number | undefined {
-    return this.#data.octave;
-  }
-
-  /** A copy of the underlying plain note object. */
-  get data(): NoteData {
-    return copyNote(this.#data);
-  }
-
-  /**
-   * Transpose by a signed number of semitones.
-   *
-   * When the note carries an octave the transposition happens in MIDI space and
-   * the result is spelled with a sharp preference. An octave-less note stays
-   * octave-less: only its pitch class is moved. Transposing by zero is the
-   * identity: the original spelling is preserved (no enharmonic respelling).
-   *
-   * @param semitones The signed semitone offset.
-   * @returns The transposed note.
-   */
-  transpose(semitones: number): Note {
-    if (semitones === 0) {
-      return new Note(this.#data);
-    }
-    if (this.#data.octave !== undefined) {
-      return Note.fromMidi(this.midi + semitones);
-    }
-    return new Note(spellPitchClassBare(this.pitchClass + semitones, 'sharp'));
-  }
-
-  /**
-   * The spelled interval from this note to another.
-   *
-   * @param other The second note.
-   * @returns The diatonic number, quality, and semitone span.
-   */
-  intervalTo(other: Note): SpelledInterval {
-    return spelledInterval(this.#data, other.#data);
-  }
-
-  /**
-   * Whether another note has the same letter, alteration, and octave.
-   *
-   * @param other The note to compare.
-   * @returns True if the spellings are identical.
-   */
-  equals(other: Note): boolean {
-    return (
-      this.#data.letter === other.#data.letter &&
-      this.#data.alter === other.#data.alter &&
-      this.#data.octave === other.#data.octave
-    );
-  }
-
-  /**
-   * The plain note data, for JSON serialization.
-   *
-   * Private class fields do not serialize, so an explicit `toJSON` keeps
-   * `JSON.stringify(note)` from collapsing to `{}`.
-   *
-   * @returns A copy of the underlying plain note object.
-   */
-  toJSON(): NoteData {
-    return this.data;
-  }
-}

package/src/model/progression.ts

@@ -1,161 +0,0 @@
-import {
-  type Cadence,
-  type ChordAnalysis,
-  detectCadence,
-  type HarmonicFunction,
-} from '../analyze/functional/index.js';
-import type { Note as NoteData } from '../core/pitch/index.js';
-import type { KeyScale } from '../core/types.js';
-import type { Chord as ChordData } from '../theory/chord/index.js';
-import { type VoicingOptions, voiceProgression } from '../theory/voicing/index.js';
-import type { Chord } from './chord.js';
-import type { Key } from './key.js';
-
-/**
- * An immutable ordered sequence of chords, optionally carrying a {@link Key}
- * context shared by its analysis methods.
- *
- * @category Class API
- * @example
- * ```ts
- * import { Key } from '@libraz/libcantus';
- * const key = Key.major('C');
- * key.chord(1).progressionTo(key.chord(4), key.chord(0)).roman();
- * // ['ii', 'V', 'I']
- * ```
- */
-export class Progression {
-  readonly #chords: readonly Chord[];
-  readonly #key: Key | undefined;
-
-  /**
-   * Wrap a chord sequence.
-   *
-   * @param chords The chords in order; the array is copied.
-   * @param key Optional key context for analysis methods.
-   */
-  constructor(chords: readonly Chord[], key?: Key) {
-    this.#chords = [...chords];
-    this.#key = key;
-  }
-
-  /** A copy of the chord sequence. */
-  get chords(): readonly Chord[] {
-    return [...this.#chords];
-  }
-
-  /** The carried key context, if any. */
-  get key(): Key | undefined {
-    return this.#key;
-  }
-
-  /** The number of chords. */
-  get length(): number {
-    return this.#chords.length;
-  }
-
-  /**
-   * A copy of this progression with a chord appended.
-   *
-   * @param chord The chord to append.
-   * @returns The new progression.
-   */
-  add(chord: Chord): Progression {
-    return new Progression([...this.#chords, chord], this.#key);
-  }
-
-  /**
-   * A copy of this progression carrying the given key context.
-   *
-   * @param key The key context to attach.
-   * @returns The new progression.
-   */
-  withKey(key: Key): Progression {
-    return new Progression(this.#chords, key);
-  }
-
-  /**
-   * Voice the progression with smooth voice leading.
-   *
-   * @param opts Voicing options; defaults to four SATB voices.
-   * @returns One ascending voicing (MIDI pitches) per chord.
-   * @throws If any chord admits no voicing within the given ranges.
-   */
-  voice(opts?: VoicingOptions): number[][] {
-    return voiceProgression(
-      this.#chords.map((chord) => chord.data),
-      opts,
-    );
-  }
-
-  /**
-   * The Roman numeral of each chord in a key.
-   *
-   * @param key Key to analyze in; falls back to the carried context.
-   * @returns One numeral per chord.
-   * @throws If no key is given and none is carried.
-   */
-  roman(key?: Key): string[] {
-    const resolved = this.#resolveKey(key);
-    return this.#chords.map((chord) => chord.roman(resolved));
-  }
-
-  /**
-   * The harmonic function of each chord in a key.
-   *
-   * @param key Key to analyze in; falls back to the carried context.
-   * @returns One function per chord.
-   * @throws If no key is given and none is carried.
-   */
-  functions(key?: Key): HarmonicFunction[] {
-    const resolved = this.#resolveKey(key);
-    return this.#chords.map((chord) => chord.function(resolved));
-  }
-
-  /**
-   * Analyze every chord and classify the closing cadence.
-   *
-   * The cadence is detected on the final chord pair and is null when the
-   * progression has fewer than two chords.
-   *
-   * @param key Key to analyze in; falls back to the carried context.
-   * @returns Per-chord analyses and the closing cadence.
-   * @throws If no key is given and none is carried.
-   */
-  analyze(key?: Key): { chords: ChordAnalysis[]; cadence: Cadence } {
-    const resolved = this.#resolveKey(key);
-    const chords = this.#chords.map((chord) => chord.analyze(resolved));
-    const from = this.#chords[this.#chords.length - 2];
-    const to = this.#chords[this.#chords.length - 1];
-    const cadence =
-      from !== undefined && to !== undefined
-        ? detectCadence(from.data, to.data, resolved.scale)
-        : null;
-    return { chords, cadence };
-  }
-
-  /**
-   * The plain progression data, for JSON serialization.
-   *
-   * Private class fields do not serialize, so an explicit `toJSON` keeps
-   * `JSON.stringify(progression)` from collapsing to `{}`. The chords are
-   * emitted as plain data and the carried key, when present, as its own data.
-   *
-   * @returns The chord data sequence and the carried key, if any.
-   */
-  toJSON(): { chords: ChordData[]; key: { scale: KeyScale; tonic: NoteData } | undefined } {
-    return {
-      chords: this.#chords.map((chord) => chord.data),
-      key: this.#key?.toJSON(),
-    };
-  }
-
-  /** Resolve the key for an analysis method: explicit first, then carried. */
-  #resolveKey(key?: Key): Key {
-    const resolved = key ?? this.#key;
-    if (resolved === undefined) {
-      throw new Error('progression has no key context; pass a Key or attach one with withKey()');
-    }
-    return resolved;
-  }
-}

package/src/model/shared.ts

@@ -1,12 +0,0 @@
-import { midiToNote, type Note as NoteData } from '../core/pitch/index.js';
-
-/** Reduce any integer to a pitch class in [0, 11]. */
-export function mod12(n: number): number {
-  return ((n % 12) + 12) % 12;
-}
-
-/** Spell a bare pitch class as an octave-less note with a sharp/flat preference. */
-export function spellPitchClassBare(pc: number, spelling: 'sharp' | 'flat'): NoteData {
-  const spelled = midiToNote(60 + mod12(pc), spelling);
-  return { letter: spelled.letter, alter: spelled.alter };
-}