@musodojo/music-theory-data 20.3.0 → 20.6.1

package/esm/src/utils/chords.js

@@ -0,0 +1,93 @@
+import { diatonicSeventhChords, diatonicTriads, harmonicMinorSeventhChords, harmonicMinorTriads, lowerCaseRomanNumerals, melodicMinorSeventhChords, melodicMinorTriads, upperCaseRomanNumerals, } from "../data/chords/mod.js";
+import { rotateArray } from "./rotate-array.js";
+import { harmonicMinorModes, } from "../data/note-collections/harmonic-minor-modes.js";
+import { melodicMinorModes, } from "../data/note-collections/melodic-minor-modes.js";
+import { diatonicModes, } from "../data/note-collections/diatonic-modes.js";
+export function getRomanTriads(triads) {
+    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:
+                // This should not happen with valid data. Fail fast if it does.
+                throw new Error(`Unhandled triad quality: ${quality}`);
+        }
+    });
+}
+export function getRomanSeventhChords(sevenths) {
+    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:
+                // This should not happen with valid data. Fail fast if it does.
+                throw new Error(`Unhandled seventh chord quality: ${quality}`);
+        }
+    });
+}
+export function getChordDetailsForMode(intervals, triads, sevenths, romanTriads, romanSeventhChords) {
+    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) {
+    const mode = diatonicModes[diatonicModeKey];
+    const rotation = mode.rotation;
+    const rotatedTriads = rotateArray(diatonicTriads, rotation);
+    const rotatedSeventhChords = rotateArray(diatonicSeventhChords, rotation);
+    return getChordDetailsForMode(mode.intervals, rotatedTriads, rotatedSeventhChords, getRomanTriads(rotatedTriads), getRomanSeventhChords(rotatedSeventhChords));
+}
+export function getChordDetailsForHarmonicMinorMode(harmonicMinorModeKey) {
+    const mode = harmonicMinorModes[harmonicMinorModeKey];
+    const rotation = mode.rotation;
+    const rotatedTriads = rotateArray(harmonicMinorTriads, rotation);
+    const rotatedSeventhChords = rotateArray(harmonicMinorSeventhChords, rotation);
+    return getChordDetailsForMode(mode.intervals, rotatedTriads, rotatedSeventhChords, getRomanTriads(rotatedTriads), getRomanSeventhChords(rotatedSeventhChords));
+}
+export function getChordDetailsForMelodicMinorMode(melodicMinorModeKey) {
+    const mode = melodicMinorModes[melodicMinorModeKey];
+    const rotation = mode.rotation;
+    const rotatedTriads = rotateArray(melodicMinorTriads, rotation);
+    const rotatedSeventhChords = rotateArray(melodicMinorSeventhChords, rotation);
+    return getChordDetailsForMode(mode.intervals, rotatedTriads, rotatedSeventhChords, getRomanTriads(rotatedTriads), getRomanSeventhChords(rotatedSeventhChords));
+}
+export function getChordDetailsForModeKey(modeKey) {
+    if (Object.prototype.hasOwnProperty.call(diatonicModes, modeKey)) {
+        return getChordDetailsForDiatonicMode(modeKey);
+    }
+    if (Object.prototype.hasOwnProperty.call(harmonicMinorModes, modeKey)) {
+        return getChordDetailsForHarmonicMinorMode(modeKey);
+    }
+    if (Object.prototype.hasOwnProperty.call(melodicMinorModes, modeKey)) {
+        return getChordDetailsForMelodicMinorMode(modeKey);
+    }
+    return [];
+}

package/esm/src/utils/colors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses a hex color string and returns its RGB components.
+ * Supports 3-digit (#RGB) and 6-digit (#RRGGBB) formats.
+ * @param hex The hex color string.
+ * @returns An array [r, g, b] or null if the format is invalid.
+ */
+export declare function parseHexColor(hex: string): [number, number, number] | null;
+/**
+ * Calculates whether black or white text has a better contrast ratio against a given background color.
+ * @param {string} color - The background color in hex format, e.g. "#E21C48"
+ * @returns {'black' | 'white'} - The color that provides better contrast.
+ */
+export declare function getContrastColor(color: string): "black" | "white";
+//# sourceMappingURL=colors.d.ts.map

package/esm/src/utils/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../../src/src/utils/colors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAkB1E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAyBjE"}

package/esm/src/utils/colors.js

@@ -0,0 +1,47 @@
+/**
+ * Parses a hex color string and returns its RGB components.
+ * Supports 3-digit (#RGB) and 6-digit (#RRGGBB) formats.
+ * @param hex The hex color string.
+ * @returns An array [r, g, b] or null if the format is invalid.
+ */
+export function parseHexColor(hex) {
+    const hexRegex = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i;
+    const shorthandHexRegex = /^#?([a-f\d])([a-f\d])([a-f\d])$/i;
+    // Expand shorthand form (e.g. "03F") to full form (e.g. "0033FF")
+    const fullHex = hex.replace(shorthandHexRegex, (_, r, g, b) => r + r + g + g + b + b);
+    const result = hexRegex.exec(fullHex);
+    return result
+        ? [
+            parseInt(result[1], 16),
+            parseInt(result[2], 16),
+            parseInt(result[3], 16),
+        ]
+        : null;
+}
+/**
+ * Calculates whether black or white text has a better contrast ratio against a given background color.
+ * @param {string} color - The background color in hex format, e.g. "#E21C48"
+ * @returns {'black' | 'white'} - The color that provides better contrast.
+ */
+export function getContrastColor(color) {
+    // For now, we only support hex colors as that's what's in the library.
+    // This can be expanded to support rgb(), hsl(), and color keywords if needed.
+    const rgb = parseHexColor(color);
+    if (!rgb) {
+        return "black"; // Default to black if color parsing fails
+    }
+    const [r, g, b] = rgb;
+    // Formula for relative luminance (from WCAG)
+    // https://www.w3.org/TR/WCAG20/#relativeluminancedef
+    const getLuminance = (c) => {
+        const sRGB = c / 255;
+        return sRGB <= 0.03928
+            ? sRGB / 12.92
+            : Math.pow((sRGB + 0.055) / 1.055, 2.4);
+    };
+    const luminance = 0.2126 * getLuminance(r) +
+        0.7152 * getLuminance(g) +
+        0.0722 * getLuminance(b);
+    // Use a threshold of 0.179 as recommended by WCAG for contrast
+    return luminance > 0.179 ? "black" : "white";
+}

package/esm/src/utils/intervals.d.ts

@@ -0,0 +1,26 @@
+import { type Interval, type IntervalQuality } from "../data/labels/note-labels.js";
+import type { NoteCollection } from "../types/note-collections";
+export declare function filterOutOctaveIntervals(intervals: readonly Interval[]): Interval[];
+/**
+ * Sorts an array of intervals in ascending order based on their integer value.
+ * This is a pure function and returns a new sorted array, leaving the original array unchanged.
+ * @param intervals The array of intervals to sort.
+ * @returns A new array with the sorted intervals.
+ */
+export declare function sortIntervals(intervals: readonly Interval[]): Interval[];
+export type IntervalTransformation = "simpleToExtension" | "extensionToSimple" | "simpleToCompound" | "compoundToSimple";
+export interface TransformIntervalsOptions {
+    intervalTransformation?: IntervalTransformation;
+    filterOutOctave?: boolean;
+    shouldSort?: boolean;
+}
+export declare function transformIntervals(intervals: readonly Interval[], options?: TransformIntervalsOptions): Interval[];
+export declare function getQualitiesFromIntervals(intervals: readonly Interval[]): IntervalQuality[];
+export declare function getIntervalsFromQualities(qualities: IntervalQuality[]): Interval[];
+/**
+ * Extracts the interval qualities (e.g., "P1", "M2", "m3") from a NoteCollection.
+ * @param collection The NoteCollection object.
+ * @returns An array of IntervalQuality strings.
+ */
+export declare function getQualitiesFromNoteCollection(collection: NoteCollection): IntervalQuality[];
+//# sourceMappingURL=intervals.d.ts.map

package/esm/src/utils/intervals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intervals.d.ts","sourceRoot":"","sources":["../../../src/src/utils/intervals.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,eAAe,EAMrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,QAAQ,EAAE,CAEZ;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAOxE;AAED,MAAM,MAAM,sBAAsB,GAC9B,mBAAmB,GACnB,mBAAmB,GACnB,kBAAkB,GAClB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,yBAAyB;IACxC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IAChD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,QAAQ,EAAE,EAC9B,OAAO,GAAE,yBAA8B,GACtC,QAAQ,EAAE,CA+BZ;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,eAAe,EAAE,CAKnB;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,eAAe,EAAE,GAC3B,QAAQ,EAAE,CAKZ;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,cAAc,GACzB,eAAe,EAAE,CAEnB"}

package/esm/src/utils/intervals.js

@@ -0,0 +1,61 @@
+import { compoundToSimpleIntervalMap, extensionToSimpleIntervalMap, intervalQualityToIntervalMap, intervalToIntegerMap, intervalToIntervalQualityMap, simpleToCompoundIntervalMap, simpleToExtensionIntervalMap, } from "../data/labels/note-labels.js";
+export function filterOutOctaveIntervals(intervals) {
+    return intervals.filter((i) => i !== "8" && i !== "♮8");
+}
+/**
+ * Sorts an array of intervals in ascending order based on their integer value.
+ * This is a pure function and returns a new sorted array, leaving the original array unchanged.
+ * @param intervals The array of intervals to sort.
+ * @returns A new array with the sorted intervals.
+ */
+export function sortIntervals(intervals) {
+    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 function transformIntervals(intervals, options = {}) {
+    const { intervalTransformation, filterOutOctave = false, shouldSort = true, } = options;
+    const intervalMap = (() => {
+        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 shouldSort ? sortIntervals(finalIntervals) : finalIntervals;
+}
+export function getQualitiesFromIntervals(intervals) {
+    return intervals.flatMap((interval) => {
+        const quality = intervalToIntervalQualityMap.get(interval);
+        return quality ? [quality] : [];
+    });
+}
+export function getIntervalsFromQualities(qualities) {
+    return qualities.flatMap((quality) => {
+        const interval = intervalQualityToIntervalMap.get(quality);
+        return interval ? [interval] : [];
+    });
+}
+/**
+ * Extracts the interval qualities (e.g., "P1", "M2", "m3") from a NoteCollection.
+ * @param collection The NoteCollection object.
+ * @returns An array of IntervalQuality strings.
+ */
+export function getQualitiesFromNoteCollection(collection) {
+    return getQualitiesFromIntervals(collection.intervals);
+}

package/esm/src/utils/midi-note-sequences.d.ts

@@ -0,0 +1,23 @@
+import type { Interval } from "../data/labels/note-labels.js";
+import type { MidiNoteNumber, MidiNoteSequence } from "../types/midi";
+export type MidiNoteSequenceDirection = "ascending" | "descending" | "ascending-descending" | "descending-ascending";
+export interface MidiNoteSequenceOptions {
+    rootNoteMidi: MidiNoteNumber;
+    intervals: Interval[];
+    direction: MidiNoteSequenceDirection;
+    startFromIndex?: number;
+    filterOutOctave?: boolean;
+    restsAtEnd?: number;
+    numNotes?: number;
+    numOctaves?: number;
+    extraNotes?: number;
+}
+/**
+ * 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 declare function getMidiNoteSequence(options: MidiNoteSequenceOptions): MidiNoteSequence;
+//# sourceMappingURL=midi-note-sequences.d.ts.map

package/esm/src/utils/midi-note-sequences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"midi-note-sequences.d.ts","sourceRoot":"","sources":["../../../src/src/utils/midi-note-sequences.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtE,MAAM,MAAM,yBAAyB,GACjC,WAAW,GACX,YAAY,GACZ,sBAAsB,GACtB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,cAAc,CAAC;IAC7B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,SAAS,EAAE,yBAAyB,CAAC;IACrC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAyED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,uBAAuB,GAC/B,gBAAgB,CAoElB"}

package/esm/src/utils/midi-note-sequences.js

@@ -0,0 +1,109 @@
+import { noteMidiAndIntervalToMidi } from "./midi.js";
+/**
+ * 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, intervals, numNotes, startFromIndex, direction) {
+    const notes = [];
+    const intervalsLength = intervals.length;
+    if (intervalsLength === 0 || numNotes <= 0)
+        return [];
+    for (let i = 0; i < numNotes; i++) {
+        let intervalIndex;
+        let octaveOffset;
+        if (direction === "ascending") {
+            intervalIndex = (startFromIndex + i) % intervalsLength;
+            octaveOffset = Math.floor((startFromIndex + i) / intervalsLength) * 12;
+            const interval = intervals[intervalIndex];
+            const note = noteMidiAndIntervalToMidi(rootNoteMidi, interval);
+            if (note === undefined) {
+                throw new Error(`Could not calculate MIDI note for interval ${interval} at index ${intervalIndex}`);
+            }
+            notes.push((note + octaveOffset));
+        } // 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 = noteMidiAndIntervalToMidi((rootNoteMidi - octaveOffset), 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) {
+    const { rootNoteMidi, intervals, direction, startFromIndex = 0, filterOutOctave = true, numNotes, numOctaves = 1, restsAtEnd = 0, 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 = [];
+    const monotonicNotes = (dir) => 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;
+        }
+    }
+    if (restsAtEnd > 0)
+        sequence.push(...Array(restsAtEnd).fill(null));
+    return sequence;
+}

package/esm/src/utils/midi.d.ts

@@ -0,0 +1,7 @@
+import { type Interval, type NoteName } from "../data/labels/note-labels.js";
+import type { MidiNoteNumber } from "../types/midi";
+export declare function noteIntegerAndIntervalToMidi(noteInteger: number, noteOctaveNumber: number, interval: Interval): MidiNoteNumber | undefined;
+export declare function noteNameAndIntervalToMidi(noteName: NoteName, noteOctaveNumber: number, interval: Interval): MidiNoteNumber | undefined;
+export declare function noteMidiAndIntervalToMidi(noteMidi: MidiNoteNumber, interval: Interval): MidiNoteNumber | undefined;
+export declare function noteNameToMidi(noteName: NoteName, noteOctaveNumber: number): MidiNoteNumber | undefined;
+//# sourceMappingURL=midi.d.ts.map

package/esm/src/utils/midi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"midi.d.ts","sourceRoot":"","sources":["../../../src/src/utils/midi.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,QAAQ,EAEb,KAAK,QAAQ,EAEd,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,QAAQ,GACjB,cAAc,GAAG,SAAS,CAK5B;AAED,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,QAAQ,GACjB,cAAc,GAAG,SAAS,CAQ5B;AAED,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,QAAQ,GACjB,cAAc,GAAG,SAAS,CAI5B;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,MAAM,GACvB,cAAc,GAAG,SAAS,CAI5B"}

package/esm/src/utils/midi.js

@@ -0,0 +1,26 @@
+import { intervalToIntegerMap, noteNameToIntegerMap, } from "../data/labels/note-labels.js";
+export function noteIntegerAndIntervalToMidi(noteInteger, noteOctaveNumber, interval) {
+    const intervalInteger = intervalToIntegerMap.get(interval);
+    if (intervalInteger === undefined)
+        return undefined;
+    return (noteOctaveNumber + 1) * 12 + noteInteger +
+        intervalInteger;
+}
+export function noteNameAndIntervalToMidi(noteName, noteOctaveNumber, interval) {
+    const noteInteger = noteNameToIntegerMap.get(noteName);
+    if (noteInteger === undefined)
+        return undefined;
+    return noteIntegerAndIntervalToMidi(noteInteger, noteOctaveNumber, interval);
+}
+export function noteMidiAndIntervalToMidi(noteMidi, interval) {
+    const intervalValue = intervalToIntegerMap.get(interval);
+    if (intervalValue === undefined)
+        return undefined;
+    return noteMidi + intervalValue;
+}
+export function noteNameToMidi(noteName, noteOctaveNumber) {
+    const noteValue = noteNameToIntegerMap.get(noteName);
+    if (noteValue === undefined)
+        return undefined;
+    return noteValue + (noteOctaveNumber + 1) * 12;
+}

package/esm/src/utils/mod.d.ts

@@ -0,0 +1,9 @@
+export * from "./colors.js";
+export * from "./chords.js";
+export * from "./intervals.js";
+export * from "./midi-note-sequences.js";
+export * from "./midi.js";
+export * from "./note-collections.js";
+export * from "./note-names.js";
+export * from "./rotate-array.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/src/utils/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/src/utils/mod.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/esm/src/utils/mod.js

@@ -0,0 +1,8 @@
+export * from "./colors.js";
+export * from "./chords.js";
+export * from "./intervals.js";
+export * from "./midi-note-sequences.js";
+export * from "./midi.js";
+export * from "./note-collections.js";
+export * from "./note-names.js";
+export * from "./rotate-array.js";

package/esm/src/utils/note-collections.d.ts

@@ -0,0 +1,24 @@
+import { type NoteCollectionKey } from "../data/note-collections/mod.js";
+import type { Interval } from "../data/labels/note-labels.js";
+import type { NoteCollection } from "../types/note-collections";
+/**
+ * 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 declare function isValidNoteCollectionKey(key: string): key is NoteCollectionKey;
+export interface SearchOptions {
+    query?: string;
+    intervals?: Interval[];
+    type?: string;
+}
+export declare function searchNoteCollections(options: SearchOptions): NoteCollection[];
+/**
+ * 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 declare function findNoteCollection(options: SearchOptions): NoteCollection | undefined;
+//# sourceMappingURL=note-collections.d.ts.map

package/esm/src/utils/note-collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note-collections.d.ts","sourceRoot":"","sources":["../../../src/src/utils/note-collections.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EAEvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,GACV,GAAG,IAAI,iBAAiB,CAE1B;AAoDD,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,GACrB,cAAc,EAAE,CAkGlB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,GACrB,cAAc,GAAG,SAAS,CAE5B"}

package/esm/src/utils/note-collections.js

@@ -0,0 +1,132 @@
+import { noteCollections, } from "../data/note-collections/mod.js";
+/**
+ * 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) {
+    return Object.prototype.hasOwnProperty.call(noteCollections, key);
+}
+const normalizationMap = new Map();
+const aliasSets = {
+    "♭": ["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) {
+    // 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 function searchNoteCollections(options) {
+    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 normalizedQuery = normalizeSearchTerm(query);
+    if (!normalizedQuery) {
+        return candidates;
+    }
+    const searchWords = normalizedQuery.split(" ");
+    // Filter candidates to those that contain all search words
+    const textFilteredCandidates = candidates.filter((theme) => {
+        const searchableText = [
+            theme.primaryName,
+            ...theme.names,
+            ...theme.type,
+            ...theme.characteristics,
+        ]
+            .map(normalizeSearchTerm)
+            .join(" ");
+        return searchWords.every((word) => {
+            const isCaseSensitiveWord = word === "M" || word === "m";
+            const regex = new RegExp(`\\b${word}\\b`, isCaseSensitiveWord ? "" : "i");
+            return regex.test(searchableText);
+        });
+    });
+    // 3. Prioritize the filtered results
+    const prioritizedResults = new Set();
+    const passes = [
+        // Pass 1: Exact match on primaryName
+        (theme) => normalizeSearchTerm(theme.primaryName) === normalizedQuery,
+        // Pass 2: Exact match on any name
+        (theme) => theme.names.some((name) => normalizeSearchTerm(name) === normalizedQuery),
+        // Pass 3: Primary name starts with the query
+        (theme) => normalizeSearchTerm(theme.primaryName).startsWith(normalizedQuery),
+        // Pass 4: Any name starts with the query
+        (theme) => theme.names.some((name) => normalizeSearchTerm(name).startsWith(normalizedQuery)),
+    ];
+    for (const pass of passes) {
+        for (const theme of textFilteredCandidates) {
+            if (pass(theme)) {
+                prioritizedResults.add(theme);
+            }
+        }
+    }
+    // Add the remaining text-filtered candidates that didn't match a priority pass
+    for (const theme of textFilteredCandidates) {
+        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) {
+    return searchNoteCollections(options)[0];
+}

package/esm/src/utils/note-names.d.ts

@@ -0,0 +1,23 @@
+import { type Interval, type NoteName, type RootNote, type RootNoteInteger } from "../data/labels/note-labels.js";
+import { type NoteCollectionKey } from "../data/note-collections/mod.js";
+import { type TransformIntervalsOptions } from "./intervals.js";
+/**
+ * Parses a string and returns a canonical `NoteName` if the string is a valid note name.
+ * This is useful for handling user input that may use ASCII characters like 'b' and '#',
+ * as well as double accidentals like 'x', '##', and 'bb'.
+ * @param name The string to parse.
+ * @returns A canonical `NoteName` (e.g., "B♭", "C𝄪") or `undefined` if the input is not a valid note.
+ */
+export declare function normalizeNoteNameString(name: string): NoteName | undefined;
+/**
+ * Parses a string and returns a canonical `RootNote` if the string is a valid root note.
+ * This is useful for handling user input that may use ASCII characters for accidentals.
+ * It is stricter than `normalizeNoteNameString` as it only allows notes present in the `rootNotes` array.
+ * @param name The string to parse.
+ * @returns A canonical `RootNote` or `undefined` if the input is not a valid root note.
+ */
+export declare function normalizeRootNoteString(name: string): RootNote | undefined;
+export declare function getNoteIntegerFromString(noteName: string): RootNoteInteger | undefined;
+export declare function getNoteNamesFromRootAndIntervals(rootNote: RootNote, intervals: readonly Interval[], options?: TransformIntervalsOptions): NoteName[];
+export declare function getNoteNamesFromRootAndCollectionKey(rootNote: RootNote, noteCollectionKey: NoteCollectionKey, options?: TransformIntervalsOptions): NoteName[];
+//# sourceMappingURL=note-names.d.ts.map

package/esm/src/utils/note-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note-names.d.ts","sourceRoot":"","sources":["../../../src/src/utils/note-names.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,QAAQ,EAIb,KAAK,QAAQ,EAGb,KAAK,QAAQ,EACb,KAAK,eAAe,EAErB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,KAAK,iBAAiB,EAEvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,gBAAgB,CAAC;AAOxB;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAsE1E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAQ1E;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,GACf,eAAe,GAAG,SAAS,CAI7B;AAED,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,QAAQ,EAAE,EAC9B,OAAO,GAAE,yBAA8B,GACtC,QAAQ,EAAE,CAmCZ;AAED,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,QAAQ,EAClB,iBAAiB,EAAE,iBAAiB,EACpC,OAAO,GAAE,yBAA8B,GACtC,QAAQ,EAAE,CAQZ"}