@musodojo/music-theory-data 20.3.0 → 20.6.1

package/src/utils/note-collections.ts

@@ -1,188 +0,0 @@
-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 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<NoteCollection>();
-
-  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: Primary name starts with the query
-    (theme: NoteCollection) =>
-      normalizeSearchTerm(theme.primaryName).startsWith(normalizedQuery),
-    // Pass 4: Any name starts with the query
-    (theme: NoteCollection) =>
-      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: SearchOptions,
-): NoteCollection | undefined {
-  return searchNoteCollections(options)[0];
-}

package/src/utils/note-names.ts

@@ -1,182 +0,0 @@
-import {
-  enharmonicNoteNameGroups,
-  type Interval,
-  intervalToIntegerMap,
-  type NoteLetter,
-  noteLetters,
-  type NoteName,
-  noteNamesSet,
-  noteNameToIntegerMap,
-  type RootNote,
-  type RootNoteInteger,
-  rootNotesSet,
-} from "../data/labels/note-labels.ts";
-import {
-  type NoteCollectionKey,
-  noteCollections,
-} from "../data/note-collections/mod.ts";
-import {
-  transformIntervals,
-  type TransformIntervalsOptions,
-} from "./intervals.ts";
-import { isValidNoteCollectionKey } from "./note-collections.ts";
-
-/**
- * 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 function normalizeNoteNameString(name: string): NoteName | undefined {
-  if (typeof name !== "string" || name.length === 0) {
-    return undefined;
-  }
-
-  // Check if the name is already a canonical note name (e.g., "C", "B♭")
-  // This check is case-sensitive.
-  if (noteNamesSet.has(name as NoteName)) {
-    return name as NoteName;
-  }
-
-  const noteLetterRegex = /^[A-Ga-g]/;
-  const accidentalRegex = /([#♯xX𝄪]+)|([b♭𝄫]+)/gu;
-
-  const noteLetterMatch = name.match(noteLetterRegex);
-  if (!noteLetterMatch) {
-    return undefined;
-  }
-
-  const noteLetter = noteLetterMatch[0].toUpperCase() as NoteLetter;
-  const accidentalString = name.substring(noteLetterMatch[0].length);
-  let validAccidentalLength = 0;
-  let noteAlterInteger = 0;
-
-  for (const match of accidentalString.matchAll(accidentalRegex)) {
-    const sharps = match[1];
-    if (sharps) {
-      for (const char of sharps) {
-        noteAlterInteger += (char.toLowerCase() === "x" || char === "𝄪")
-          ? 2
-          : 1;
-      }
-      validAccidentalLength += sharps.length;
-    }
-
-    const flats = match[2];
-    if (flats) {
-      for (const char of flats) {
-        noteAlterInteger -= (char === "𝄫") ? 2 : 1;
-      }
-      validAccidentalLength += flats.length;
-    }
-  }
-
-  // Check if the entire accidental string had valid accidentals
-  if (accidentalString.length > validAccidentalLength) {
-    return undefined;
-  }
-
-  let accidentalSymbols = "";
-  let currentAlteration = noteAlterInteger;
-
-  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;
-    }
-  }
-
-  const result = (noteLetter + accidentalSymbols) as NoteName;
-
-  return noteNamesSet.has(result) ? result : 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 function normalizeRootNoteString(name: string): RootNote | undefined {
-  const normalizedNote = normalizeNoteNameString(name);
-
-  if (normalizedNote && rootNotesSet.has(normalizedNote as RootNote)) {
-    return normalizedNote as RootNote;
-  }
-
-  return undefined;
-}
-
-export function getNoteIntegerFromString(
-  noteName: string,
-): RootNoteInteger | undefined {
-  const normalized = normalizeNoteNameString(noteName);
-  if (!normalized) return undefined;
-  return noteNameToIntegerMap.get(normalized);
-}
-
-export function getNoteNamesFromRootAndIntervals(
-  rootNote: RootNote,
-  intervals: readonly Interval[],
-  options: TransformIntervalsOptions = {},
-): NoteName[] {
-  const rootNoteInteger = noteNameToIntegerMap.get(rootNote);
-  if (rootNoteInteger === undefined) return [];
-  const rootNoteLetter = rootNote.charAt(0).toUpperCase();
-  const rootNoteLetterIndex = noteLetters.indexOf(rootNoteLetter as NoteLetter);
-
-  const intervalsToConvert = Object.keys(options).length > 0
-    ? transformIntervals(intervals, options)
-    : intervals;
-
-  const noteNames: NoteName[] = intervalsToConvert.flatMap((interval) => {
-    const intervalInteger = intervalToIntegerMap.get(interval);
-    if (intervalInteger === undefined) return []; // skip over invalid intervals silently
-
-    const absoluteNoteInteger = (rootNoteInteger + intervalInteger) % 12;
-
-    const intervalNumberMatch = interval.match(/\d+/)!;
-    const intervalNumber = parseInt(intervalNumberMatch[0], 10);
-
-    const targetNoteLetter =
-      noteLetters[(rootNoteLetterIndex + intervalNumber - 1) % 7];
-
-    const enharmonicGroup = enharmonicNoteNameGroups[absoluteNoteInteger];
-    const selectedNote = enharmonicGroup.find((noteName) =>
-      noteName.startsWith(targetNoteLetter)
-    );
-
-    return [selectedNote ?? enharmonicGroup[0]];
-  });
-
-  return noteNames;
-}
-
-export function getNoteNamesFromRootAndCollectionKey(
-  rootNote: RootNote,
-  noteCollectionKey: NoteCollectionKey,
-  options: TransformIntervalsOptions = {},
-): NoteName[] {
-  if (!isValidNoteCollectionKey(noteCollectionKey)) return [];
-
-  return getNoteNamesFromRootAndIntervals(
-    rootNote,
-    noteCollections[noteCollectionKey].intervals,
-    options,
-  );
-}