@musodojo/music-theory-data 23.0.0 → 24.0.0

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

@@ -0,0 +1,9 @@
+export declare const ACCIDENTAL_REGEX: RegExp;
+/**
+ * Parses an accidental string containing ASCII or standard accidental characters
+ * and normalizes it into canonical accidental symbols ('♯', '♭', '𝄪', '𝄫').
+ * @param accidentalString The string containing only accidentals.
+ * @returns A canonical accidental string, or undefined if the string contained invalid characters.
+ */
+export declare function normalizeAccidentalString(accidentalString: string): string | undefined;
+//# sourceMappingURL=accidentals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"accidentals.d.ts","sourceRoot":"","sources":["../../../src/src/utils/accidentals.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,QAA4B,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,gBAAgB,EAAE,MAAM,GACvB,MAAM,GAAG,SAAS,CAoDpB"}

package/esm/src/utils/accidentals.js

@@ -0,0 +1,55 @@
+export const ACCIDENTAL_REGEX = /([#♯xX𝄪]+)|([b♭𝄫]+)/gu;
+/**
+ * Parses an accidental string containing ASCII or standard accidental characters
+ * and normalizes it into canonical accidental symbols ('♯', '♭', '𝄪', '𝄫').
+ * @param accidentalString The string containing only accidentals.
+ * @returns A canonical accidental string, or undefined if the string contained invalid characters.
+ */
+export function normalizeAccidentalString(accidentalString) {
+    if (accidentalString.length === 0)
+        return "";
+    let validAccidentalLength = 0;
+    let alterInteger = 0;
+    for (const match of accidentalString.matchAll(ACCIDENTAL_REGEX)) {
+        const sharps = match[1];
+        if (sharps) {
+            for (const char of sharps) {
+                alterInteger += char.toLowerCase() === "x" || char === "𝄪" ? 2 : 1;
+            }
+            validAccidentalLength += sharps.length;
+        }
+        const flats = match[2];
+        if (flats) {
+            for (const char of flats) {
+                alterInteger -= char === "𝄫" ? 2 : 1;
+            }
+            validAccidentalLength += flats.length;
+        }
+    }
+    if (accidentalString.length > validAccidentalLength) {
+        return undefined;
+    }
+    let accidentalSymbols = "";
+    let currentAlteration = alterInteger;
+    while (currentAlteration > 0) {
+        if (currentAlteration >= 2) {
+            accidentalSymbols += "𝄪";
+            currentAlteration -= 2;
+        }
+        else {
+            accidentalSymbols += "♯";
+            currentAlteration -= 1;
+        }
+    }
+    while (currentAlteration < 0) {
+        if (currentAlteration <= -2) {
+            accidentalSymbols += "𝄫";
+            currentAlteration += 2;
+        }
+        else {
+            accidentalSymbols += "♭";
+            currentAlteration += 1;
+        }
+    }
+    return accidentalSymbols;
+}

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

@@ -1,5 +1,4 @@
-import { type Interval, type IntervalQuality } from "../data/labels/note-labels.js";
-import type { NoteCollection } from "../types/note-collections";
+import { type CompoundInterval, type Interval, type IntervalQuality, type SimpleInterval } from "../data/labels/note-labels.js";
 import { type NoteCollectionKey } from "../data/note-collections/mod.js";
 /**
  * Removes octave intervals (such as "8" or "♮8") from a given list of intervals.
@@ -10,6 +9,46 @@ import { type NoteCollectionKey } from "../data/note-collections/mod.js";
  * @returns A new array excluding any octave intervals.
  */
 export declare function filterOutOctaveIntervals(intervals: readonly Interval[]): Interval[];
+/**
+ * Parses a string and returns a canonical `Interval` if the string is a valid interval.
+ * This handles ASCII accidentals like 'b' and '#' as well as qualities like 'M3', 'm3'.
+ * @param name The string to parse.
+ * @returns A canonical `Interval` (e.g., "♭3", "♯4") or `undefined` if invalid.
+ */
+export declare function normalizeIntervalString(name: string): Interval | undefined;
+/**
+ * Parses an array of strings and returns an array of canonical `Interval`s.
+ * Any invalid interval strings are filtered out from the result.
+ * @param names The array of strings to parse.
+ * @returns An array of canonical `Interval`s.
+ */
+export declare function normalizeIntervalStringArray(names: readonly string[]): Interval[];
+/**
+ * Parses a string and returns a canonical `SimpleInterval` if valid.
+ */
+export declare function normalizeSimpleIntervalString(name: string): SimpleInterval | undefined;
+/**
+ * Parses an array of strings and returns an array of canonical `SimpleInterval`s.
+ */
+export declare function normalizeSimpleIntervalStringArray(names: readonly string[]): SimpleInterval[];
+/**
+ * Parses a string and returns a canonical `CompoundInterval` if valid.
+ */
+export declare function normalizeCompoundIntervalString(name: string): CompoundInterval | undefined;
+/**
+ * Parses an array of strings and returns an array of canonical `CompoundInterval`s.
+ */
+export declare function normalizeCompoundIntervalStringArray(names: readonly string[]): CompoundInterval[];
+/**
+ * Removes any intervals that mathematically resolve to the root note (0 modulo 12),
+ * except for the unison ("1" or "♮1") itself if it is present.
+ * This effectively prevents octaves ("8", "15") from overwriting the explicit unison
+ * slot when mapping intervals into a strict 12-semitone chromatic scale.
+ *
+ * @param intervals The array of intervals to filter.
+ * @returns A new array excluding higher root-equivalent intervals.
+ */
+export declare function filterOutRootLikeIntervals(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.
@@ -37,10 +76,11 @@ export type TransformIntervalsOptions = {
      */
     shouldSort?: boolean;
     /**
-     * A fixed number of steps to rotate the array left (positive) or right (negative).
-     * Rotation pushes elements from the beginning of the array to the end (left) or vice versa.
+     * A fixed number of steps to rotate the array right (positive) or left (negative).
+     * Positive values loop elements at the end of the array to the front.
+     * Negative values loop elements at the front of the array to the end.
      */
-    rotateLeft?: number;
+    rotateRight?: number;
 } & ({
     /**
      * When true, generates a 12-element array representing the chromatic scale (0-11).
@@ -79,24 +119,11 @@ export type TransformIntervalsOptions = {
  * @returns A new transformed array of intervals.
  */
 export declare function transformIntervals(intervals: readonly Interval[], options?: TransformIntervalsOptions): Interval[];
-/**
- * Extracts generic interval qualities (e.g., "P5", "m3" becomes "P", "m") from a list of intervals.
- *
- * @param intervals An array of specific intervals.
- * @returns An array of the corresponding interval qualities.
- */
-export declare function getQualitiesFromIntervals(intervals: readonly Interval[]): IntervalQuality[];
 /**
  * Retrieves the base intervals associated with a given set of interval qualities.
  *
  * @param qualities An array of generic interval qualities.
  * @returns An array of corresponding base intervals.
  */
-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[];
+export declare function getIntervalsFromQualities(qualities: readonly IntervalQuality[]): Interval[];
 //# sourceMappingURL=intervals.d.ts.map

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

@@ -1 +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;AAChE,OAAO,EACL,KAAK,iBAAiB,EAEvB,MAAM,iCAAiC,CAAC;AAIzC;;;;;;;GAOG;AACH,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,4FAA4F;AAC5F,MAAM,MAAM,sBAAsB,GAC9B,mBAAmB,GACnB,mBAAmB,GACnB,kBAAkB,GAClB,kBAAkB,CAAC;AAEvB,kFAAkF;AAClF,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IAChD;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,CACA;IACE;;;;OAIG;IACH,aAAa,EAAE,IAAI,CAAC;IACpB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,GACD;IACE,aAAa,CAAC,EAAE,KAAK,CAAC;IACtB,gBAAgB,CAAC,EAAE,KAAK,CAAC;IACzB,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB,oBAAoB,CAAC,EAAE,KAAK,CAAC;CAC9B,CACJ,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,QAAQ,EAAE,EAC9B,OAAO,GAAE,yBAA8B,GACtC,QAAQ,EAAE,CAiFZ;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,eAAe,EAAE,CAKnB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,eAAe,EAAE,GAC3B,QAAQ,EAAE,CAKZ;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,cAAc,GACzB,eAAe,EAAE,CAEnB"}
+{"version":3,"file":"intervals.d.ts","sourceRoot":"","sources":["../../../src/src/utils/intervals.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EAGrB,KAAK,QAAQ,EACb,KAAK,eAAe,EAGpB,KAAK,cAAc,EAGpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,KAAK,iBAAiB,EAEvB,MAAM,iCAAiC,CAAC;AAOzC;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,QAAQ,EAAE,CAEZ;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAmC1E;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,QAAQ,EAAE,CAIZ;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,GACX,cAAc,GAAG,SAAS,CAU5B;AAED;;GAEG;AACH,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,cAAc,EAAE,CAIlB;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,GACX,gBAAgB,GAAG,SAAS,CAU9B;AAED;;GAEG;AACH,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,gBAAgB,EAAE,CAIpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,QAAQ,EAAE,CAuBZ;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAOxE;AAED,4FAA4F;AAC5F,MAAM,MAAM,sBAAsB,GAC9B,mBAAmB,GACnB,mBAAmB,GACnB,kBAAkB,GAClB,kBAAkB,CAAC;AAEvB,kFAAkF;AAClF,MAAM,MAAM,yBAAyB,GACjC;IACA;;;OAGG;IACH,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IAChD;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACC,CACE;IACA;;;;OAIG;IACH,aAAa,EAAE,IAAI,CAAC;IACpB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,GACC;IACA,aAAa,CAAC,EAAE,KAAK,CAAC;IACtB,gBAAgB,CAAC,EAAE,KAAK,CAAC;IACzB,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB,oBAAoB,CAAC,EAAE,KAAK,CAAC;CAC9B,CACF,CAAC;AAEJ;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,QAAQ,EAAE,EAC9B,OAAO,GAAE,yBAA8B,GACtC,QAAQ,EAAE,CAwFZ;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,eAAe,EAAE,GACpC,QAAQ,EAAE,CAKZ"}

package/esm/src/utils/intervals.js

@@ -1,7 +1,9 @@
-import { compoundToSimpleIntervalMap, extensionToSimpleIntervalMap, intervalQualityToIntervalMap, intervalToIntegerMap, intervalToIntervalQualityMap, simpleToCompoundIntervalMap, simpleToExtensionIntervalMap, } from "../data/labels/note-labels.js";
+import { compoundToSimpleIntervalMap, extensionToSimpleIntervalMap, intervalQualityToIntervalMap, intervalToIntegerMap, simpleToCompoundIntervalMap, simpleToExtensionIntervalMap, } from "../data/labels/note-labels.js";
 import { noteCollections, } from "../data/note-collections/mod.js";
-import { noteLabelCollections } from "../mod.js";
-import { rotateArrayLeft } from "./rotate-array.js";
+import { noteLabelCollections } from "../data/labels/note-label-collections.js";
+import { rotateArrayRight } from "./rotate-array.js";
+import { normalizeAccidentalString } from "./accidentals.js";
+const INTERVAL_NUMBER_REGEX = /\d+$/;
 /**
  * Removes octave intervals (such as "8" or "♮8") from a given list of intervals.
  * Highly useful for standardizing chord and scale definitions (scales conventionally include the octave,
@@ -13,6 +15,121 @@ import { rotateArrayLeft } from "./rotate-array.js";
 export function filterOutOctaveIntervals(intervals) {
     return intervals.filter((i) => i !== "8" && i !== "♮8");
 }
+/**
+ * Parses a string and returns a canonical `Interval` if the string is a valid interval.
+ * This handles ASCII accidentals like 'b' and '#' as well as qualities like 'M3', 'm3'.
+ * @param name The string to parse.
+ * @returns A canonical `Interval` (e.g., "♭3", "♯4") or `undefined` if invalid.
+ */
+export function normalizeIntervalString(name) {
+    if (typeof name !== "string" || name.length === 0) {
+        return undefined;
+    }
+    // 1. Check if it's an explicit interval quality like "M3" or "d5"
+    if (intervalQualityToIntervalMap.has(name)) {
+        return intervalQualityToIntervalMap.get(name);
+    }
+    // 2. Check if it's already a canonical interval like "♭3" or "3"
+    if (intervalToIntegerMap.has(name)) {
+        return name;
+    }
+    // 3. Try to parse ASCII accidentals before the interval number
+    const numberMatch = name.match(INTERVAL_NUMBER_REGEX);
+    if (!numberMatch) {
+        return undefined;
+    }
+    const intervalNumberStr = numberMatch[0];
+    const accidentalString = name.substring(0, name.length - intervalNumberStr.length);
+    const accidentalSymbols = normalizeAccidentalString(accidentalString);
+    if (accidentalSymbols === undefined) {
+        return undefined;
+    }
+    const result = (accidentalSymbols + intervalNumberStr);
+    return intervalToIntegerMap.has(result) ? result : undefined;
+}
+/**
+ * Parses an array of strings and returns an array of canonical `Interval`s.
+ * Any invalid interval strings are filtered out from the result.
+ * @param names The array of strings to parse.
+ * @returns An array of canonical `Interval`s.
+ */
+export function normalizeIntervalStringArray(names) {
+    return names
+        .map((name) => normalizeIntervalString(name))
+        .filter((name) => name !== undefined);
+}
+/**
+ * Parses a string and returns a canonical `SimpleInterval` if valid.
+ */
+export function normalizeSimpleIntervalString(name) {
+    const normalized = normalizeIntervalString(name);
+    if (normalized) {
+        // A simple interval has a number <= 8
+        const num = parseInt(normalized.match(INTERVAL_NUMBER_REGEX)[0], 10);
+        if (num <= 8) {
+            return normalized;
+        }
+    }
+    return undefined;
+}
+/**
+ * Parses an array of strings and returns an array of canonical `SimpleInterval`s.
+ */
+export function normalizeSimpleIntervalStringArray(names) {
+    return names
+        .map((name) => normalizeSimpleIntervalString(name))
+        .filter((name) => name !== undefined);
+}
+/**
+ * Parses a string and returns a canonical `CompoundInterval` if valid.
+ */
+export function normalizeCompoundIntervalString(name) {
+    const normalized = normalizeIntervalString(name);
+    if (normalized) {
+        // A compound interval has a number >= 9
+        const num = parseInt(normalized.match(INTERVAL_NUMBER_REGEX)[0], 10);
+        if (num >= 9) {
+            return normalized;
+        }
+    }
+    return undefined;
+}
+/**
+ * Parses an array of strings and returns an array of canonical `CompoundInterval`s.
+ */
+export function normalizeCompoundIntervalStringArray(names) {
+    return names
+        .map((name) => normalizeCompoundIntervalString(name))
+        .filter((name) => name !== undefined);
+}
+/**
+ * Removes any intervals that mathematically resolve to the root note (0 modulo 12),
+ * except for the unison ("1" or "♮1") itself if it is present.
+ * This effectively prevents octaves ("8", "15") from overwriting the explicit unison
+ * slot when mapping intervals into a strict 12-semitone chromatic scale.
+ *
+ * @param intervals The array of intervals to filter.
+ * @returns A new array excluding higher root-equivalent intervals.
+ */
+export function filterOutRootLikeIntervals(intervals) {
+    const hasUnison = intervals.some((i) => i === "1" || i === "♮1" || i === "𝄫2");
+    return intervals.filter((interval) => {
+        const semitones = intervalToIntegerMap.get(interval);
+        if (semitones === undefined)
+            return true; // keep it if invalid, though shouldn't happen
+        const isRootSlot = semitones % 12 === 0;
+        // If it falls on the root slot, we only keep it if it IS the unison
+        if (isRootSlot) {
+            if (hasUnison &&
+                interval !== "1" &&
+                interval !== "♮1" &&
+                interval !== "𝄫2") {
+                return false;
+            }
+        }
+        return true;
+    });
+}
 /**
  * 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.
@@ -37,7 +154,7 @@ export function sortIntervals(intervals) {
  * @returns A new transformed array of intervals.
  */
 export function transformIntervals(intervals, options = {}) {
-    const { intervalTransformation, filterOutOctave = false, shouldSort = true, fillChromatic = false, mostSimilarScale, rotateLeft, } = options;
+    const { intervalTransformation, filterOutOctave = false, shouldSort = true, fillChromatic = false, mostSimilarScale, rotateRight, rotateToRootInteger0, rootNoteInteger, } = options;
     const intervalMap = (() => {
         switch (intervalTransformation) {
             case "simpleToExtension":
@@ -55,7 +172,6 @@ export function transformIntervals(intervals, options = {}) {
     const fundamentalIntervals = filterOutOctave
         ? filterOutOctaveIntervals(intervals)
         : intervals;
-    const transformedIntervals = fundamentalIntervals.map((interval) => intervalMap.get(interval) ?? interval);
     if (fillChromatic) {
         const chromaticMap = [
             ...noteLabelCollections.intervalsFlat.labels,
@@ -64,50 +180,39 @@ export function transformIntervals(intervals, options = {}) {
             const collection = noteCollections[mostSimilarScale];
             if (collection && collection.intervals !== intervals) {
                 collection.intervals.forEach((interval) => {
-                    const transformed = intervalMap.get(interval) ?? interval;
-                    const semitones = intervalToIntegerMap.get(transformed);
+                    const semitones = intervalToIntegerMap.get(interval);
                     if (semitones !== undefined) {
-                        chromaticMap[semitones % 12] = transformed;
+                        chromaticMap[semitones % 12] = interval;
                     }
                 });
             }
         }
         // Now overlay the provided parsed intervals
-        transformedIntervals.forEach((interval) => {
+        const filteredIntervalsForOverlay = filterOutRootLikeIntervals(fundamentalIntervals);
+        filteredIntervalsForOverlay.forEach((interval) => {
             const semitones = intervalToIntegerMap.get(interval);
             if (semitones !== undefined) {
                 chromaticMap[semitones % 12] = interval;
             }
         });
-        let result = chromaticMap;
-        if (options.rotateToRootInteger0 && options.rootNoteInteger !== undefined) {
-            result = rotateArrayLeft(result, -options.rootNoteInteger);
+        let result = chromaticMap.map((interval) => intervalMap.get(interval) ?? interval);
+        if (rotateToRootInteger0 && rootNoteInteger !== undefined) {
+            result = rotateArrayRight(result, rootNoteInteger);
         }
-        if (rotateLeft !== undefined) {
-            result = rotateArrayLeft(result, rotateLeft);
+        if (rotateRight !== undefined) {
+            result = rotateArrayRight(result, rotateRight);
         }
         return result;
     }
+    const transformedIntervals = fundamentalIntervals.map((interval) => intervalMap.get(interval) ?? interval);
     let result = shouldSort
         ? sortIntervals(transformedIntervals)
         : transformedIntervals;
-    if (rotateLeft !== undefined) {
-        result = rotateArrayLeft(result, rotateLeft);
+    if (rotateRight !== undefined) {
+        result = rotateArrayRight(result, rotateRight);
     }
     return result;
 }
-/**
- * Extracts generic interval qualities (e.g., "P5", "m3" becomes "P", "m") from a list of intervals.
- *
- * @param intervals An array of specific intervals.
- * @returns An array of the corresponding interval qualities.
- */
-export function getQualitiesFromIntervals(intervals) {
-    return intervals.flatMap((interval) => {
-        const quality = intervalToIntervalQualityMap.get(interval);
-        return quality ? [quality] : [];
-    });
-}
 /**
  * Retrieves the base intervals associated with a given set of interval qualities.
  *
@@ -120,11 +225,3 @@ export function getIntervalsFromQualities(qualities) {
         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.js

@@ -1,4 +1,4 @@
-import { noteMidiAndIntervalToMidi } from "./midi.js";
+import { getMidiFromNoteMidiAndInterval } from "./midi.js";
 /**
  * Generates a monotonic sequence of MIDI notes.
  * @param rootNoteMidi The root MIDI note number.
@@ -21,7 +21,7 @@ function getMonotonicMidiNoteSequence(rootNoteMidi, intervals, numNotes, startFr
             intervalIndex = (startFromIndex + i) % intervalsLength;
             octaveOffset = Math.floor((startFromIndex + i) / intervalsLength) * 12;
             const interval = intervals[intervalIndex];
-            const note = noteMidiAndIntervalToMidi(rootNoteMidi, interval);
+            const note = getMidiFromNoteMidiAndInterval(rootNoteMidi, interval);
             if (note === undefined) {
                 throw new Error(`Could not calculate MIDI note for interval ${interval} at index ${intervalIndex}`);
             }
@@ -44,7 +44,7 @@ function getMonotonicMidiNoteSequence(rootNoteMidi, intervals, numNotes, startFr
                 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);
+            const note = getMidiFromNoteMidiAndInterval((rootNoteMidi - octaveOffset), interval);
             if (note === undefined) {
                 throw new Error(`Could not calculate MIDI note for interval ${interval} at index ${intervalIndex}`);
             }

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

@@ -9,7 +9,7 @@ import type { MidiNoteNumber } from "../types/midi";
  * @param interval The interval to apply.
  * @returns The computed MIDI note number, or `undefined` if the interval is invalid.
  */
-export declare function noteIntegerAndIntervalToMidi(noteInteger: number, noteOctaveNumber: number, interval: Interval): MidiNoteNumber | undefined;
+export declare function getMidiFromNoteIntegerAndInterval(noteInteger: number, noteOctaveNumber: number, interval: Interval): MidiNoteNumber | undefined;
 /**
  * Calculates a MIDI note number based on a starting note name and an interval.
  *
@@ -18,7 +18,7 @@ export declare function noteIntegerAndIntervalToMidi(noteInteger: number, noteOc
  * @param interval The interval to apply.
  * @returns The computed MIDI note number, or `undefined` if the note name or interval is invalid.
  */
-export declare function noteNameAndIntervalToMidi(noteName: NoteName, noteOctaveNumber: number, interval: Interval): MidiNoteNumber | undefined;
+export declare function getMidiFromNoteNameAndInterval(noteName: NoteName, noteOctaveNumber: number, interval: Interval): MidiNoteNumber | undefined;
 /**
  * Calculates a new MIDI note number by applying a musical interval to a starting MIDI note number.
  *
@@ -26,7 +26,7 @@ export declare function noteNameAndIntervalToMidi(noteName: NoteName, noteOctave
  * @param interval The interval to add.
  * @returns The new computed MIDI note number, or `undefined` if the interval is invalid.
  */
-export declare function noteMidiAndIntervalToMidi(noteMidi: MidiNoteNumber, interval: Interval): MidiNoteNumber | undefined;
+export declare function getMidiFromNoteMidiAndInterval(noteMidi: MidiNoteNumber, interval: Interval): MidiNoteNumber | undefined;
 /**
  * Converts a note name and its specific octave into a standard MIDI note number.
  *
@@ -34,5 +34,5 @@ export declare function noteMidiAndIntervalToMidi(noteMidi: MidiNoteNumber, inte
  * @param noteOctaveNumber The scientific pitch octave number.
  * @returns The standard MIDI note number, or `undefined` if the note name is invalid.
  */
-export declare function noteNameToMidi(noteName: NoteName, noteOctaveNumber: number): MidiNoteNumber | undefined;
+export declare function getMidiFromNoteName(noteName: NoteName, noteOctaveNumber: number): MidiNoteNumber | undefined;
 //# sourceMappingURL=midi.d.ts.map

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

@@ -1 +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;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,QAAQ,GACjB,cAAc,GAAG,SAAS,CAM5B;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,QAAQ,GACjB,cAAc,GAAG,SAAS,CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,QAAQ,GACjB,cAAc,GAAG,SAAS,CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,MAAM,GACvB,cAAc,GAAG,SAAS,CAI5B"}
+{"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;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,QAAQ,GACjB,cAAc,GAAG,SAAS,CAM5B;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,QAAQ,GACjB,cAAc,GAAG,SAAS,CAQ5B;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,QAAQ,GACjB,cAAc,GAAG,SAAS,CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,MAAM,GACvB,cAAc,GAAG,SAAS,CAI5B"}

package/esm/src/utils/midi.js

@@ -8,7 +8,7 @@ import { intervalToIntegerMap, noteNameToIntegerMap, } from "../data/labels/note
  * @param interval The interval to apply.
  * @returns The computed MIDI note number, or `undefined` if the interval is invalid.
  */
-export function noteIntegerAndIntervalToMidi(noteInteger, noteOctaveNumber, interval) {
+export function getMidiFromNoteIntegerAndInterval(noteInteger, noteOctaveNumber, interval) {
     const intervalInteger = intervalToIntegerMap.get(interval);
     if (intervalInteger === undefined)
         return undefined;
@@ -24,11 +24,11 @@ export function noteIntegerAndIntervalToMidi(noteInteger, noteOctaveNumber, inte
  * @param interval The interval to apply.
  * @returns The computed MIDI note number, or `undefined` if the note name or interval is invalid.
  */
-export function noteNameAndIntervalToMidi(noteName, noteOctaveNumber, interval) {
+export function getMidiFromNoteNameAndInterval(noteName, noteOctaveNumber, interval) {
     const noteInteger = noteNameToIntegerMap.get(noteName);
     if (noteInteger === undefined)
         return undefined;
-    return noteIntegerAndIntervalToMidi(noteInteger, noteOctaveNumber, interval);
+    return getMidiFromNoteIntegerAndInterval(noteInteger, noteOctaveNumber, interval);
 }
 /**
  * Calculates a new MIDI note number by applying a musical interval to a starting MIDI note number.
@@ -37,7 +37,7 @@ export function noteNameAndIntervalToMidi(noteName, noteOctaveNumber, interval)
  * @param interval The interval to add.
  * @returns The new computed MIDI note number, or `undefined` if the interval is invalid.
  */
-export function noteMidiAndIntervalToMidi(noteMidi, interval) {
+export function getMidiFromNoteMidiAndInterval(noteMidi, interval) {
     const intervalValue = intervalToIntegerMap.get(interval);
     if (intervalValue === undefined)
         return undefined;
@@ -50,7 +50,7 @@ export function noteMidiAndIntervalToMidi(noteMidi, interval) {
  * @param noteOctaveNumber The scientific pitch octave number.
  * @returns The standard MIDI note number, or `undefined` if the note name is invalid.
  */
-export function noteNameToMidi(noteName, noteOctaveNumber) {
+export function getMidiFromNoteName(noteName, noteOctaveNumber) {
     const noteValue = noteNameToIntegerMap.get(noteName);
     if (noteValue === undefined)
         return undefined;

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

@@ -6,4 +6,5 @@ export * from "./midi.js";
 export * from "./note-collections.js";
 export * from "./note-names.js";
 export * from "./rotate-array.js";
+export * from "./qualities.js";
 //# sourceMappingURL=mod.d.ts.map

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

@@ -1 +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"}
+{"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;AAClC,cAAc,gBAAgB,CAAC"}

package/esm/src/utils/mod.js

@@ -6,3 +6,4 @@ export * from "./midi.js";
 export * from "./note-collections.js";
 export * from "./note-names.js";
 export * from "./rotate-array.js";
+export * from "./qualities.js";

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

@@ -9,6 +9,13 @@ import { type TransformIntervalsOptions } from "./intervals.js";
  * @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 an array of strings and returns an array of canonical `NoteName`s.
+ * Any invalid note name strings are filtered out from the result.
+ * @param names The array of strings to parse.
+ * @returns An array of canonical `NoteName`s.
+ */
+export declare function normalizeNoteNameStringArray(names: readonly string[]): NoteName[];
 /**
  * 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.
@@ -17,6 +24,13 @@ export declare function normalizeNoteNameString(name: string): NoteName | undefi
  * @returns A canonical `RootNote` or `undefined` if the input is not a valid root note.
  */
 export declare function normalizeRootNoteString(name: string): RootNote | undefined;
+/**
+ * Parses an array of strings and returns an array of canonical `RootNote`s.
+ * Any invalid root note strings are filtered out from the result.
+ * @param names The array of strings to parse.
+ * @returns An array of canonical `RootNote`s.
+ */
+export declare function normalizeRootNoteStringArray(names: readonly string[]): RootNote[];
 /**
  * Gets the integer representation (0-11, where C=0) of a given note name string.
  * @param noteName The note name string to evaluate.

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

@@ -1 +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;AAQxB;;;;;;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;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,GACf,eAAe,GAAG,SAAS,CAI7B;AA4CD;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,QAAQ,EAAE,EAC9B,OAAO,GAAE,yBAA8B,GACtC,QAAQ,EAAE,CAgCZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,QAAQ,EAClB,iBAAiB,EAAE,iBAAiB,EACpC,OAAO,GAAE,IAAI,CAAC,yBAAyB,EAAE,kBAAkB,CAAM,GAChE,QAAQ,EAAE,CAuBZ"}
+{"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;AAQxB;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CA2B1E;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,QAAQ,EAAE,CAIZ;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAQ1E;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,QAAQ,EAAE,CAIZ;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,GACf,eAAe,GAAG,SAAS,CAI7B;AA4CD;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,QAAQ,EAAE,EAC9B,OAAO,GAAE,yBAA8B,GACtC,QAAQ,EAAE,CA+BZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,QAAQ,EAClB,iBAAiB,EAAE,iBAAiB,EACpC,OAAO,GAAE,IAAI,CAAC,yBAAyB,EAAE,kBAAkB,CAAM,GAChE,QAAQ,EAAE,CAqBZ"}