@musodojo/music-theory-data 14.0.0

package/src/utils/get-chords.ts

@@ -0,0 +1,166 @@
+import {
+  diatonicSeventhChords,
+  diatonicTriads,
+  harmonicMinorSeventhChords,
+  harmonicMinorTriads,
+  lowerCaseRomanNumerals,
+  melodicMinorSeventhChords,
+  melodicMinorTriads,
+  upperCaseRomanNumerals,
+} from "../data/chords/mod.ts";
+import type {
+  ChordDetails,
+  RomanSeventhChord,
+  RomanTriad,
+  SeventhChord,
+  Triad,
+} from "../types/chords.d.ts";
+import { rotateArray } from "./rotate-array.ts";
+import {
+  type HarmonicMinorModeKey,
+  harmonicMinorModes,
+} from "../data/note-collections/harmonic-minor-modes.ts";
+import {
+  type MelodicMinorModeKey,
+  melodicMinorModes,
+} from "../data/note-collections/melodic-minor-modes.ts";
+import type { Interval } from "../data/labels/note-labels.ts";
+import {
+  type DiatonicModeKey,
+  diatonicModes,
+} from "../data/note-collections/diatonic-modes.ts";
+
+export function getRomanTriads(triads: Triad[]): RomanTriad[] {
+  return triads.map((quality, i) => {
+    switch (quality) {
+      case "M":
+        return upperCaseRomanNumerals[i];
+      case "m":
+        return lowerCaseRomanNumerals[i];
+      case "°":
+        return lowerCaseRomanNumerals[i] + quality;
+      case "+":
+        return upperCaseRomanNumerals[i] + quality;
+      default:
+        return upperCaseRomanNumerals[i];
+    }
+  }) as RomanTriad[];
+}
+
+export function getRomanSeventhChords(
+  sevenths: SeventhChord[],
+): RomanSeventhChord[] {
+  return sevenths.map((quality, i) => {
+    switch (quality) {
+      case "M7":
+        return upperCaseRomanNumerals[i] + quality;
+      case "m7":
+        return lowerCaseRomanNumerals[i] + quality;
+      case "7":
+        return upperCaseRomanNumerals[i] + quality;
+      case "ø7":
+        return lowerCaseRomanNumerals[i] + quality;
+      case "m7♭5":
+        return lowerCaseRomanNumerals[i] + quality;
+      case "°7":
+        return lowerCaseRomanNumerals[i] + quality;
+      case "m(M7)":
+        return lowerCaseRomanNumerals[i] + "M7";
+      case "+M7":
+        return upperCaseRomanNumerals[i] + quality;
+      case "M7♯5":
+        return upperCaseRomanNumerals[i] + quality;
+      default:
+        return upperCaseRomanNumerals[i] + quality;
+    }
+  }) as RomanSeventhChord[];
+}
+
+export function getChordDetailsForMode(
+  intervals: readonly Interval[],
+  triads: readonly Triad[],
+  sevenths: readonly SeventhChord[],
+  romanTriads: readonly RomanTriad[],
+  romanSeventhChords: readonly RomanSeventhChord[],
+): ChordDetails[] {
+  return intervals
+    .filter((interval) => interval !== "8")
+    .map((interval, i) => ({
+      interval,
+      triad: triads[i],
+      seventh: sevenths[i],
+      romanTriad: romanTriads[i],
+      romanSeventhChord: romanSeventhChords[i],
+    }));
+}
+
+export function getChordDetailsForDiatonicMode(
+  diatonicModeKey: DiatonicModeKey,
+): ChordDetails[] {
+  const mode = diatonicModes[diatonicModeKey];
+  const rotation = mode.rotation as number;
+  const rotatedTriads = rotateArray(diatonicTriads, rotation);
+  const rotatedSeventhChords = rotateArray(diatonicSeventhChords, rotation);
+  return getChordDetailsForMode(
+    mode.intervals,
+    rotatedTriads,
+    rotatedSeventhChords,
+    getRomanTriads(rotatedTriads),
+    getRomanSeventhChords(rotatedSeventhChords),
+  );
+}
+
+export function getChordDetailsForHarmonicMinorMode(
+  harmonicMinorModeKey: HarmonicMinorModeKey,
+): ChordDetails[] {
+  const mode = harmonicMinorModes[harmonicMinorModeKey];
+  const rotation = mode.rotation as number;
+  const rotatedTriads = rotateArray(harmonicMinorTriads, rotation);
+  const rotatedSeventhChords = rotateArray(
+    harmonicMinorSeventhChords,
+    rotation,
+  );
+  return getChordDetailsForMode(
+    mode.intervals,
+    rotatedTriads,
+    rotatedSeventhChords,
+    getRomanTriads(rotatedTriads),
+    getRomanSeventhChords(rotatedSeventhChords),
+  );
+}
+
+export function getChordDetailsForMelodicMinorMode(
+  melodicMinorModeKey: MelodicMinorModeKey,
+): ChordDetails[] {
+  const mode = melodicMinorModes[melodicMinorModeKey];
+  const rotation = mode.rotation as number;
+  const rotatedTriads = rotateArray(melodicMinorTriads, rotation);
+  const rotatedSeventhChords = rotateArray(melodicMinorSeventhChords, rotation);
+  return getChordDetailsForMode(
+    mode.intervals,
+    rotatedTriads,
+    rotatedSeventhChords,
+    getRomanTriads(rotatedTriads),
+    getRomanSeventhChords(rotatedSeventhChords),
+  );
+}
+
+export type AnyModeKey =
+  | DiatonicModeKey
+  | HarmonicMinorModeKey
+  | MelodicMinorModeKey;
+
+export function getChordDetailsForModeKey(
+  modeKey: AnyModeKey,
+): ChordDetails[] {
+  if (Object.prototype.hasOwnProperty.call(diatonicModes, modeKey)) {
+    return getChordDetailsForDiatonicMode(modeKey as DiatonicModeKey);
+  }
+  if (Object.prototype.hasOwnProperty.call(harmonicMinorModes, modeKey)) {
+    return getChordDetailsForHarmonicMinorMode(modeKey as HarmonicMinorModeKey);
+  }
+  if (Object.prototype.hasOwnProperty.call(melodicMinorModes, modeKey)) {
+    return getChordDetailsForMelodicMinorMode(modeKey as MelodicMinorModeKey);
+  }
+  return [];
+}

package/src/utils/get-midi-note-sequences.ts

@@ -0,0 +1,168 @@
+import type { Interval } from "../data/labels/note-labels.ts";
+import type { MidiNoteNumber, MidiNoteSequence } from "../types/midi.d.ts";
+import { rootMidiAndIntervalToMidi } from "./midi.ts";
+
+export type MidiNoteSequenceDirection =
+  | "ascending"
+  | "descending"
+  | "ascending-descending"
+  | "descending-ascending";
+
+// TODO: add property `restsAtEnd` to add null values to array end
+export interface MidiNoteSequenceOptions {
+  rootNoteMidi: MidiNoteNumber;
+  intervals: Interval[];
+  direction: MidiNoteSequenceDirection;
+  startFromIndex?: number;
+  filterOutOctave?: boolean;
+  numNotes?: number;
+  numOctaves?: number;
+  extraNotes?: number;
+}
+
+/**
+ * Generates a monotonic sequence of MIDI notes.
+ * @param rootNoteMidi The root MIDI note number.
+ * @param intervals The array of intervals to generate the sequence from.
+ * @param numNotes The number of notes to generate.
+ * @param startFromIndex The starting index in the intervals array.
+ * @param direction The direction of the sequence ('ascending' or 'descending').
+ * @returns An array of MIDI note numbers.
+ * @throws {Error} If a MIDI note cannot be calculated for an interval.
+ */
+function getMonotonicMidiNoteSequence(
+  rootNoteMidi: MidiNoteNumber,
+  intervals: Interval[],
+  numNotes: number,
+  startFromIndex: number,
+  direction: "ascending" | "descending",
+): MidiNoteSequence {
+  const notes: MidiNoteNumber[] = [];
+  const intervalsLength = intervals.length;
+
+  if (intervalsLength === 0 || numNotes <= 0) return [];
+
+  for (let i = 0; i < numNotes; i++) {
+    let intervalIndex: number;
+    let octaveOffset: number;
+
+    if (direction === "ascending") {
+      intervalIndex = (startFromIndex + i) % intervalsLength;
+      octaveOffset = Math.floor((startFromIndex + i) / intervalsLength) * 12;
+      const interval = intervals[intervalIndex];
+      const note = rootMidiAndIntervalToMidi(rootNoteMidi, interval);
+      if (note === undefined) {
+        throw new Error(
+          `Could not calculate MIDI note for interval ${interval} at index ${intervalIndex}`,
+        );
+      }
+      notes.push((note + octaveOffset) as MidiNoteNumber);
+    } // descending...
+    else {
+      intervalIndex =
+        ((startFromIndex - i) % intervalsLength + intervalsLength) %
+        intervalsLength;
+      /**
+       * octaveOffset increases every time we've looped through all intervals
+       * The Math.max(0, ...) is a piece of defensive programming. It protects the function from producing illogical results if it
+       * ever receives invalid input.
+       * @example
+       * intervalsLength = 7
+       * Imagine we accidentally pass startFromIndex = 10. This is not a valid index for the intervals array,
+       * but a robust function should handle it gracefully.
+       */
+      octaveOffset =
+        Math.max(0, Math.ceil((i - startFromIndex) / intervalsLength)) * 12;
+      const interval = intervals[intervalIndex];
+      // Subtract octaveOffset from root before applying interval
+      const note = rootMidiAndIntervalToMidi(
+        (rootNoteMidi - octaveOffset) as MidiNoteNumber,
+        interval,
+      );
+      if (note === undefined) {
+        throw new Error(
+          `Could not calculate MIDI note for interval ${interval} at index ${intervalIndex}`,
+        );
+      }
+      notes.push(note);
+    }
+  }
+
+  return notes;
+}
+
+/**
+ * Generates a sequence of MIDI notes based on the provided options.
+ * The sequence can be ascending, descending, or a combination of both.
+ * @param options The options for generating the MIDI note sequence.
+ * @returns A sequence of MIDI notes.
+ * @throws {Error} If a MIDI note cannot be calculated for an interval.
+ */
+export function getMidiNoteSequence(
+  options: MidiNoteSequenceOptions,
+): MidiNoteSequence {
+  const {
+    rootNoteMidi,
+    intervals,
+    direction,
+    startFromIndex = 0,
+    filterOutOctave = true,
+    numNotes,
+    numOctaves = 1,
+    extraNotes = 0,
+  } = options;
+
+  const fundamentalIntervals = filterOutOctave
+    ? intervals.filter((i) => i !== "8" && i !== "♮8")
+    : intervals;
+
+  if (fundamentalIntervals.length === 0) return [];
+
+  // Calculate the total number of notes for the (first) monotonic part of the sequence.
+  // This is simply reversed and sliced to create the ascending-descending or descending-ascending sequences.
+  // numOctaves = 0: fundamentalIntervals.length
+  // numOctaves = 1: fundamentalIntervals.length + 1
+  // numOctaves = 2: 2 * fundamentalIntervals.length + 1
+  const monotonicNoteCount = numNotes ??
+    (numOctaves === 0
+        ? fundamentalIntervals.length
+        : numOctaves * fundamentalIntervals.length + 1) +
+      extraNotes;
+
+  if (monotonicNoteCount <= 0) return [];
+
+  let sequence: MidiNoteSequence = [];
+  const monotonicNotes = (dir: "ascending" | "descending") =>
+    getMonotonicMidiNoteSequence(
+      rootNoteMidi,
+      fundamentalIntervals,
+      monotonicNoteCount,
+      startFromIndex,
+      dir,
+    );
+
+  switch (direction) {
+    case "ascending":
+      sequence = monotonicNotes("ascending");
+      break;
+    case "descending":
+      sequence = monotonicNotes("descending");
+      break;
+    case "ascending-descending": {
+      const ascendingNotes = monotonicNotes("ascending");
+      // Exclude the peak note to avoid duplication when reversing
+      const descendingPart = [...ascendingNotes].reverse().slice(1);
+      sequence = [...ascendingNotes, ...descendingPart];
+      break;
+    }
+    case "descending-ascending": {
+      const descendingNotes = monotonicNotes("descending");
+      // Exclude the lowest note to avoid duplication when reversing
+      const ascendingPart = [...descendingNotes].reverse().slice(1);
+      sequence = [...descendingNotes, ...ascendingPart];
+      break;
+    }
+  }
+
+  return sequence;
+}

package/src/utils/intervals.ts

@@ -0,0 +1,74 @@
+import {
+  compoundToSimpleIntervalMap,
+  extensionToSimpleIntervalMap,
+  type Interval,
+  intervalToIntegerMap,
+  simpleToCompoundIntervalMap,
+  simpleToExtensionIntervalMap,
+} from "../data/labels/note-labels.ts";
+
+export function filterOutOctaveIntervals(
+  intervals: readonly Interval[],
+): Interval[] {
+  return intervals.filter((i) => i !== "8" && i !== "♮8");
+}
+
+export function toSortedIntervals(
+  intervals: readonly Interval[],
+): Interval[] {
+  return intervals
+    .toSorted((a, b) => {
+      const intA = intervalToIntegerMap.get(a);
+      const intB = intervalToIntegerMap.get(b);
+      if (intA === undefined || intB === undefined) return 0;
+      return intA - intB;
+    });
+}
+
+export type IntervalTransformation =
+  | "simpleToExtension"
+  | "extensionToSimple"
+  | "simpleToCompound"
+  | "compoundToSimple";
+
+export interface TransformIntervalsOptions {
+  intervalTransformation?: IntervalTransformation;
+  filterOutOctave?: boolean;
+  sortIntervals?: boolean;
+}
+
+export function transformIntervals(
+  intervals: readonly Interval[],
+  options: TransformIntervalsOptions = {},
+): Interval[] {
+  const {
+    intervalTransformation,
+    filterOutOctave = false,
+    sortIntervals = true,
+  } = options;
+
+  const intervalMap: ReadonlyMap<Interval, Interval> = (() => {
+    switch (intervalTransformation) {
+      case "simpleToExtension":
+        return simpleToExtensionIntervalMap;
+      case "extensionToSimple":
+        return extensionToSimpleIntervalMap;
+      case "simpleToCompound":
+        return simpleToCompoundIntervalMap;
+      case "compoundToSimple":
+        return compoundToSimpleIntervalMap;
+      default:
+        return new Map();
+    }
+  })();
+
+  const fundamentalIntervals = filterOutOctave
+    ? filterOutOctaveIntervals(intervals)
+    : intervals;
+
+  const finalIntervals = fundamentalIntervals.map((interval) =>
+    intervalMap.get(interval) ?? interval
+  );
+
+  return sortIntervals ? toSortedIntervals(finalIntervals) : finalIntervals;
+}

package/src/utils/midi.ts

@@ -0,0 +1,50 @@
+import {
+  type Interval,
+  intervalToIntegerMap,
+  type NoteInteger,
+  type NoteName,
+  noteNameToIntegerMap,
+} from "../data/labels/note-labels.ts";
+
+import type { MidiNoteNumber, OctaveNumber } from "../types/midi.d.ts";
+
+export function rootIntegerAndIntervalToMidi(
+  rootNoteInteger: NoteInteger,
+  interval: Interval,
+  rootNoteOctaveNumber: OctaveNumber = 4,
+): MidiNoteNumber | undefined {
+  const intervalValue = intervalToIntegerMap.get(interval);
+  if (intervalValue === undefined) return undefined;
+  return (rootNoteOctaveNumber + 1) * 12 + rootNoteInteger +
+    intervalValue as MidiNoteNumber;
+}
+
+export function rootMidiAndIntervalToMidi(
+  rootNoteMidi: MidiNoteNumber,
+  interval: Interval,
+): MidiNoteNumber | undefined {
+  const intervalValue = intervalToIntegerMap.get(interval);
+  if (intervalValue === undefined) return undefined;
+  return rootNoteMidi + intervalValue as MidiNoteNumber;
+}
+
+export function noteNameToMidi(
+  noteName: NoteName,
+  octaveNumber: OctaveNumber = 4,
+): MidiNoteNumber | undefined {
+  const noteValue = noteNameToIntegerMap.get(noteName);
+  if (noteValue === undefined) return undefined;
+  return noteValue + (octaveNumber + 1) * 12 as MidiNoteNumber;
+}
+
+export function noteNameAndIntervalToMidi(
+  noteName: NoteName,
+  interval: Interval,
+  octaveNumber: OctaveNumber = 4,
+): MidiNoteNumber | undefined {
+  const noteValue = noteNameToIntegerMap.get(noteName);
+  if (noteValue === undefined) return undefined;
+  const intervalValue = intervalToIntegerMap.get(interval);
+  if (intervalValue === undefined) return undefined;
+  return noteValue + (octaveNumber + 1) * 12 as MidiNoteNumber;
+}

package/src/utils/mod.ts

@@ -0,0 +1,5 @@
+export * from "./get-midi-note-sequences.ts";
+export * from "./get-chords.ts";
+export * from "./note-names.ts";
+export * from "./rotate-array.ts";
+export * from "./note-collections.ts";

package/src/utils/note-collections.ts

@@ -0,0 +1,170 @@
+import {
+  type NoteCollectionKey,
+  noteCollections,
+} from "../data/note-collections/mod.ts";
+import type { Interval } from "../data/labels/note-labels.ts";
+import type { NoteCollection } from "../types/note-collections.d.ts";
+
+/**
+ * Checks if a given string is a valid `NoteCollectionKey`.
+ * @param key The string to check.
+ * @returns `true` if the key is a valid `NoteCollectionKey`, `false` otherwise.
+ */
+export function isValidNoteCollectionKey(
+  key: string,
+): key is NoteCollectionKey {
+  return Object.prototype.hasOwnProperty.call(noteCollections, key);
+}
+
+const normalizationMap = new Map<string, string>();
+
+const aliasSets: Record<string, string[]> = {
+  "♭": ["b", "flat"],
+  "♯": ["#", "sharp"],
+  "♮": ["n", "natural"],
+  "𝄫": ["bb", "doubleflat"],
+  "𝄪": ["##", "doublesharp"],
+
+  "M": ["maj", "major"],
+  "m": ["min", "minor"],
+  "°": ["dim", "diminished"],
+  "+": ["aug", "augmented"],
+  "ø": ["halfdiminished"],
+
+  "7": ["seventh"],
+  "dominant": ["dom"],
+};
+
+for (const [canonical, aliases] of Object.entries(aliasSets)) {
+  for (const alias of aliases) {
+    normalizationMap.set(alias, canonical);
+  }
+}
+
+/**
+ * Normalizes a search string by converting aliases to their canonical form,
+ * removing non-essential characters, and collapsing whitespace.
+ * @param str The string to normalize.
+ * @returns A normalized string for searching.
+ */
+function normalizeSearchTerm(str: string): string {
+  // Start with trimming, but preserve original case for now.
+  let normalized = str.trim();
+
+  // Iteratively replace all aliases, using a case-insensitive regex.
+  // This is crucial because we can't simply lowercase the entire string,
+  // as that would merge "M" (major) and "m" (minor) into the same character.
+  for (const [alias, canonical] of normalizationMap.entries()) {
+    // This regex looks for an alias that is either a whole word (\b)
+    // or is immediately followed by a digit (for cases like "b2", "maj7").
+    // The "i" flag makes the search case-insensitive.
+    const regex = new RegExp(`\\b${alias}(?=[0-9]|\\b)`, "gi");
+    normalized = normalized.replace(regex, canonical);
+  }
+
+  // Final cleanup: remove non-essential characters and collapse whitespace.
+  return normalized.replace(/[-()]/g, "").replace(/\s+/g, " ").trim();
+}
+
+export interface SearchOptions {
+  query?: string;
+  intervals?: Interval[];
+  type?: string;
+}
+
+export function searchNoteCollections(
+  options: SearchOptions,
+): NoteCollection[] {
+  const { query, intervals, type } = options;
+  let candidates = Object.values(noteCollections);
+
+  // 1. Apply hard filters first to narrow down the candidate pool
+  if (type) {
+    const normalizedType = normalizeSearchTerm(type);
+    const searchWords = normalizedType.split(" ");
+
+    candidates = candidates.filter((theme) => {
+      const themeTypesString = theme.type.map(normalizeSearchTerm).join(" ");
+      return searchWords.every((word) => {
+        // Use case-sensitive search for 'M' and 'm'
+        const isCaseSensitiveWord = word === "M" || word === "m";
+        const regex = new RegExp(
+          `\\b${word}\\b`,
+          isCaseSensitiveWord ? "" : "i",
+        );
+        return regex.test(themeTypesString);
+      });
+    });
+  }
+
+  if (intervals && intervals.length > 0) {
+    candidates = candidates.filter((theme) =>
+      intervals.every((interval) => theme.intervals.includes(interval))
+    );
+  }
+
+  // If there's no text query, the filtered list is the final result.
+  if (!query) {
+    return candidates;
+  }
+
+  // 2. Apply prioritized text search on the filtered candidates
+  const prioritizedResults = new Set<NoteCollection>();
+  const normalizedQuery = normalizeSearchTerm(query);
+
+  if (!normalizedQuery) {
+    return candidates;
+  }
+
+  // Use case-sensitive search for "M" and "m" to avoid incorrect matches.
+  const isCaseSensitiveQuery = normalizedQuery === "M" ||
+    normalizedQuery === "m";
+  const regexFlags = isCaseSensitiveQuery ? "" : "i";
+  const searchRegex = new RegExp(`\\b${normalizedQuery}\\b`, regexFlags);
+
+  const passes = [
+    // Pass 1: Exact match on primaryName
+    (theme: NoteCollection) =>
+      normalizeSearchTerm(theme.primaryName) === normalizedQuery,
+    // Pass 2: Exact match on any name
+    (theme: NoteCollection) =>
+      theme.names.some((name) => normalizeSearchTerm(name) === normalizedQuery),
+    // Pass 3: Whole word match on primaryName
+    (theme: NoteCollection) =>
+      searchRegex.test(normalizeSearchTerm(theme.primaryName)),
+    // Pass 4: Whole word match on any name
+    (theme: NoteCollection) =>
+      theme.names.some((name) => searchRegex.test(normalizeSearchTerm(name))),
+    // Pass 7: Whole word match on any type
+    (theme: NoteCollection) =>
+      theme.type.some((t) => searchRegex.test(normalizeSearchTerm(t))),
+    // Pass 8: Whole word match on any characteristic
+    (theme: NoteCollection) =>
+      theme.characteristics.some((c) =>
+        searchRegex.test(normalizeSearchTerm(c))
+      ),
+  ];
+
+  for (const pass of passes) {
+    for (const theme of candidates) {
+      if (pass(theme)) {
+        prioritizedResults.add(theme);
+      }
+    }
+  }
+
+  return Array.from(prioritizedResults);
+}
+
+/**
+ * Finds the single best matching `NoteCollection` based on search options.
+ * This is a convenience wrapper around `searchNoteCollections` that returns only the first result.
+ * The search is prioritized to return the most relevant match first.
+ * @param options The search options.
+ * @returns The best matching `NoteCollection` or `undefined` if no match is found.
+ */
+export function findNoteCollection(
+  options: SearchOptions,
+): NoteCollection | undefined {
+  return searchNoteCollections(options)[0];
+}