@musodojo/music-theory-data 15.4.0 → 16.0.7

package/README.md

@@ -1,17 +1,87 @@
-# Music Theory Data
-
-## Currently Under Review for Accuracy
+# Muso Dojo | Music Theory Data
 
 **The musician-friendly TypeScript library for modes, scales, chords, and
 more.**
 
-A modern, Deno/TypeScript-first collection of **music theory data structures**
-and **utility functions** for working with modes, scales, arpeggios, chords, and
-beyond.
+> **Note:** This library is currently under review for accuracy. Please verify
+> data before use in a critical application.
+
+## Features
+
+- **Rich Data Structures:** Access detailed information for scales, modes,
+  chords, and more, including intervals, integer notations, and common names.
+- **Practical Utility Functions:** Helpers for common tasks like generating note
+  names from a root note and a collection key.
+- **Fully Typed:** Written in TypeScript with comprehensive type definitions for
+  a great developer experience.
+- **Deno First, NPM Ready:** A modern Deno module that is also published to npm
+  for use in Node.js projects.
+
+## Installation
+
+### Deno / JSR
+
+Import directly from JSR in your Deno project:
+
+```ts
+import * as music_theory_data from "@musodojo/music-theory-data";
+```
+
+or
+
+```ts
+import * as music_theory_data from "jsr:@musodojo/music-theory-data";
+```
+
+### Node.js / npm
+
+Install the package from the npm registry:
+
+```bash
+npm install @musodojo/music-theory-data
+```
+
+Then import it into your project:
+
+```ts
+import * as music_theory_data from "@musodojo/music-theory-data";
+```
+
+## Usage Example
+
+Get the notes of a scale or the details of a mode.
+
+```ts
+import * as music_theory_data from "jsr:@musodojo/music-theory-data";
+
+// Get the notes of A Harmonic Minor
+const notes = music_theory_data.getNoteNamesFromRootAndCollectionKey(
+  "A",
+  "harmonicMinor",
+);
+console.log(notes);
+// ["A", "B", "C", "D", "E", "F", "G♯", "A"]
+
+// Get the full data structure for the Ionian mode (Major Scale)
+const ionian = music_theory_data.noteCollections.ionian;
+
+console.log(ionian.primaryName);
+// "Major"
+
+console.log(ionian.intervals);
+// ["1", "2", "3", "4", "5", "6", "7", "8"]
+
+// Log the array of all available Note Collection Keys
+console.log(Object.keys(music_theory_data.noteCollections));
+// ["ionian", "dorian", "phrygian", ...]
+
+// Log the array of all available Grouped Note Collections Keys
+console.log(Object.keys(music_theory_data.groupedNoteCollections));
+// ["diatonicModes", "pentatonicVariants", ...]
+```
 
-Built for **musicians, educators, and creative coders**, it goes beyond raw note
-lists — providing rich, structured metadata and practical helpers for
-**analysis, composition, and interactive tools**.
+## API Documentation
 
-> **Goal:** To be _the_ library that powers next-generation interactive music
-> tools, practice apps, and educational software.
+For a full list of all available data, types, and utility functions, please see
+the
+**[auto-generated API documentation on JSR](https://jsr.io/@musodojo/music-theory-data/doc)**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@musodojo/music-theory-data",
-  "version": "15.4.0",
+  "version": "16.0.7",
   "description": "The musician-friendly TypeScript library for modes, scales, chords, and more.",
   "keywords": [
     "music",
@@ -12,7 +12,7 @@
   "main": "src/mod.ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/conor-dowdall/music-theory-data.git"
+    "url": "git+https://github.com/conor-dowdall/music-theory-data.git"
   },
   "bugs": {
     "url": "https://github.com/conor-dowdall/music-theory-data/issues"

package/src/data/labels/note-labels.ts

@@ -366,76 +366,106 @@ export const compoundToSimpleIntervalMap: ReadonlyMap<
   ][],
 );
 
-export type IntervalQualityType = "d" | "m" | "P" | "M" | "A";
+export type IntervalQualityType = "dd" | "d" | "m" | "P" | "M" | "A" | "AA";
 
 const _intervalQualityToIntegerMap = {
+  "dd1": -2,
   "d1": -1,
   "P1": 0,
   "A1": 1,
+  "AA1": 2,
 
+  "dd2": -1,
   "d2": 0,
   "m2": 1,
   "M2": 2,
   "A2": 3,
+  "AA2": 4,
 
+  "dd3": 1,
   "d3": 2,
   "m3": 3,
   "M3": 4,
   "A3": 5,
+  "AA3": 6,
 
+  "dd4": 3,
   "d4": 4,
   "P4": 5,
   "A4": 6,
+  "AA4": 7,
 
+  "dd5": 5,
   "d5": 6,
   "P5": 7,
   "A5": 8,
+  "AA5": 9,
 
+  "dd6": 6,
   "d6": 7,
   "m6": 8,
   "M6": 9,
   "A6": 10,
+  "AA6": 11,
 
+  "dd7": 8,
   "d7": 9,
   "m7": 10,
   "M7": 11,
   "A7": 12,
+  "AA7": 13,
 
+  "dd8": 10,
   "d8": 11,
   "P8": 12,
   "A8": 13,
+  "AA8": 14,
 
+  "dd9": 11,
   "d9": 12,
   "m9": 13,
   "M9": 14,
   "A9": 15,
+  "AA9": 16,
 
+  "dd10": 13,
   "d10": 14,
   "m10": 15,
   "M10": 16,
   "A10": 17,
+  "AA10": 18,
 
+  "dd11": 15,
   "d11": 16,
   "P11": 17,
   "A11": 19,
+  "AA11": 20,
 
+  "dd12": 17,
   "d12": 18,
   "P12": 19,
   "A12": 20,
+  "AA12": 21,
 
+  "dd13": 18,
   "d13": 19,
   "m13": 20,
   "M13": 21,
   "A13": 22,
+  "AA13": 23,
 
+  "dd14": 20,
   "d14": 21,
   "m14": 22,
   "M14": 23,
   "A14": 24,
+  "AA14": 25,
 
+  "dd15": 22,
   "d15": 23,
   "P15": 24,
   "A15": 25,
+  "AA15": 26,
 } as const;
 
 export type IntervalQuality = keyof typeof _intervalQualityToIntegerMap;
@@ -449,3 +479,124 @@ export const intervalQualityToIntegerMap: ReadonlyMap<
     number,
   ][],
 );
+
+//TODO: add beyond an octave
+const _intervalToIntervalQualityMap = {
+  "𝄫1": "dd1",
+  "♭1": "d1",
+  "1": "P1",
+  "♮1": "P1",
+  "♯1": "A1",
+  "𝄪1": "AA1",
+
+  "𝄫2": "dd2",
+  "♭2": "m2",
+  "2": "M2",
+  "♮2": "M2",
+  "♯2": "A2",
+  "𝄪2": "AA2",
+
+  "𝄫3": "dd3",
+  "♭3": "m3",
+  "3": "M3",
+  "♮3": "M3",
+  "♯3": "A3",
+  "𝄪3": "AA3",
+
+  "𝄫4": "dd4",
+  "♭4": "d4",
+  "4": "P4",
+  "♮4": "P4",
+  "♯4": "A4",
+  "𝄪4": "AA4",
+
+  "𝄫5": "dd5",
+  "♭5": "d5",
+  "5": "P5",
+  "♮5": "P5",
+  "♯5": "A5",
+  "𝄪5": "AA5",
+
+  "𝄫6": "dd6",
+  "♭6": "m6",
+  "6": "M6",
+  "♮6": "M6",
+  "♯6": "A6",
+  "𝄪6": "AA6",
+
+  "𝄫7": "dd7",
+  "♭7": "m7",
+  "7": "M7",
+  "♮7": "M7",
+  "♯7": "A7",
+  "𝄪7": "AA7",
+} as const;
+
+export const intervalToIntervalQualityMap: ReadonlyMap<
+  Interval,
+  IntervalQuality
+> = new Map(
+  Object.entries(_intervalToIntervalQualityMap) as [
+    Interval,
+    IntervalQuality,
+  ][],
+);
+
+//TODO: add beyond an octave
+const _intervalQualityToIntervalMap = {
+  "dd1": "𝄫1",
+  "d1": "♭1",
+  "P1": "1",
+  "A1": "♯1",
+  "AA1": "𝄪1",
+
+  "dd2": "𝄫2",
+  "d2": "♭2",
+  "m2": "♭2",
+  "M2": "2",
+  "A2": "♯2",
+  "AA2": "𝄪2",
+
+  "dd3": "𝄫3",
+  "d3": "♭3",
+  "m3": "♭3",
+  "M3": "3",
+  "A3": "♯3",
+  "AA3": "𝄪3",
+
+  "dd4": "𝄫4",
+  "d4": "♭4",
+  "P4": "4",
+  "A4": "♯4",
+  "AA4": "𝄪4",
+
+  "dd5": "𝄫5",
+  "d5": "♭5",
+  "P5": "5",
+  "A5": "♯5",
+  "AA5": "𝄪5",
+
+  "dd6": "𝄫6",
+  "d6": "♭6",
+  "m6": "♭6",
+  "M6": "6",
+  "A6": "♯6",
+  "AA6": "𝄪6",
+
+  "dd7": "𝄫7",
+  "d7": "♭7",
+  "m7": "♭7",
+  "M7": "7",
+  "A7": "♯7",
+  "AA7": "𝄪7",
+} as const;
+
+export const intervalQualityToIntervalMap: ReadonlyMap<
+  IntervalQuality,
+  Interval
+> = new Map(
+  Object.entries(_intervalQualityToIntervalMap) as [
+    IntervalQuality,
+    Interval,
+  ][],
+);

package/src/data/note-collections/{augmented.ts → augmented-variants.ts}

@@ -1,6 +1,7 @@
-import type { NoteCollection } from "../../types/note-collections.d.ts";
+import type { ChordCollection } from "../../types/note-collections.d.ts";
 
-const augmentedTriad: NoteCollection = {
+const augmentedTriad: ChordCollection = {
+  category: "chord",
   primaryName: "aug",
   names: ["aug", "+", "Augmented Triad"],
   intervals: ["1", "3", "♯5"],
@@ -11,7 +12,20 @@ const augmentedTriad: NoteCollection = {
   patternShort: ["M3", "M3"],
 } as const;
 
-const italian6: NoteCollection = {
+const augmented7: ChordCollection = {
+  category: "chord",
+  primaryName: "aug7",
+  names: ["aug7", "+7", "7♯5", "Augmented Seventh"],
+  intervals: ["1", "3", "♯5", "♭7"],
+  integers: [0, 4, 8, 10],
+  type: ["augmented", "dominant", "chord", "arpeggio", "tetrad"],
+  characteristics: ["tense", "unstable", "dissonant", "dominant function"],
+  pattern: ["major third", "major third", "minor second"],
+  patternShort: ["M3", "M3", "m2"],
+} as const;
+
+const italian6: ChordCollection = {
+  category: "chord",
   primaryName: "It+6",
   names: ["It+6", "Italian 6th"],
   intervals: ["1", "3", "♭6"],
@@ -26,7 +40,8 @@ const italian6: NoteCollection = {
   patternShort: ["M3", "d4"],
 } as const;
 
-const french6: NoteCollection = {
+const french6: ChordCollection = {
+  category: "chord",
   primaryName: "Fr+6",
   names: ["Fr+6", "French 6th"],
   intervals: ["1", "3", "♯4", "♭6"],
@@ -42,7 +57,8 @@ const french6: NoteCollection = {
   patternShort: ["M3", "m2", "M2"],
 } as const;
 
-const german6: NoteCollection = {
+const german6: ChordCollection = {
+  category: "chord",
   primaryName: "Ger+6",
   names: ["Ger+6", "German 6th"],
   intervals: ["1", "3", "5", "♭6"],
@@ -58,25 +74,15 @@ const german6: NoteCollection = {
   patternShort: ["M3", "m3", "A1"],
 } as const;
 
-const augmented7: NoteCollection = {
-  primaryName: "aug7",
-  names: ["aug7", "+7", "7♯5", "Augmented Seventh"],
-  intervals: ["1", "3", "♯5", "♭7"],
-  integers: [0, 4, 8, 10],
-  type: ["augmented", "dominant", "chord", "arpeggio", "tetrad"],
-  characteristics: ["tense", "unstable", "dissonant", "dominant function"],
-  pattern: ["major third", "major third", "minor second"],
-  patternShort: ["M3", "M3", "m2"],
-} as const;
-
-export const _augmented = {
+export const _augmentedVariants = {
   augmentedTriad,
+  augmented7,
   italian6,
   french6,
   german6,
-  augmented7,
 } as const;
 
-export type AugmentedKey = keyof typeof _augmented;
+export type AugmentedVariantKey = keyof typeof _augmentedVariants;
 
-export const augmented: Record<AugmentedKey, NoteCollection> = _augmented;
+export const augmentedVariants: Record<AugmentedVariantKey, ChordCollection> =
+  _augmentedVariants;

package/src/data/note-collections/diatonic-modes.ts

@@ -1,6 +1,8 @@
-import type { NoteCollection } from "../../types/note-collections.d.ts";
+import type { ScaleCollection } from "../../types/note-collections.d.ts";
 
-const ionian: NoteCollection = {
+const ionian: ScaleCollection = {
+  category: "scale",
+  rotation: 0,
   primaryName: "Major",
   names: [
     "Major",
@@ -11,7 +13,6 @@ const ionian: NoteCollection = {
   ],
   intervals: ["1", "2", "3", "4", "5", "6", "7", "8"],
   integers: [0, 2, 4, 5, 7, 9, 11],
-  rotation: 0,
   type: [
     "major",
     "ionian",
@@ -40,7 +41,9 @@ const ionian: NoteCollection = {
   patternShort: ["W", "W", "H", "W", "W", "W", "H"],
 } as const;
 
-const dorian: NoteCollection = {
+const dorian: ScaleCollection = {
+  category: "scale",
+  rotation: 1,
   primaryName: "Dorian",
   names: [
     "Dorian",
@@ -49,7 +52,6 @@ const dorian: NoteCollection = {
   ],
   intervals: ["1", "2", "♭3", "4", "5", "6", "♭7", "8"],
   integers: [0, 2, 3, 5, 7, 9, 10],
-  rotation: 1,
   type: [
     "minor",
     "dorian",
@@ -78,7 +80,9 @@ const dorian: NoteCollection = {
   patternShort: ["W", "H", "W", "W", "W", "H", "W"],
 } as const;
 
-const phrygian: NoteCollection = {
+const phrygian: ScaleCollection = {
+  category: "scale",
+  rotation: 2,
   primaryName: "Phrygian",
   names: [
     "Phrygian",
@@ -87,7 +91,6 @@ const phrygian: NoteCollection = {
   ],
   intervals: ["1", "♭2", "♭3", "4", "5", "♭6", "♭7", "8"],
   integers: [0, 1, 3, 5, 7, 8, 10],
-  rotation: 2,
   type: [
     "minor",
     "phrygian",
@@ -114,12 +117,13 @@ const phrygian: NoteCollection = {
   patternShort: ["H", "W", "W", "W", "H", "W", "W"],
 } as const;
 
-const lydian: NoteCollection = {
+const lydian: ScaleCollection = {
+  category: "scale",
+  rotation: 3,
   primaryName: "Lydian",
   names: ["Lydian", "Major ♯4", "Lydian Mode"],
   intervals: ["1", "2", "3", "♯4", "5", "6", "7", "8"],
   integers: [0, 2, 4, 6, 7, 9, 11],
-  rotation: 3,
   type: [
     "major",
     "lydian",
@@ -144,7 +148,9 @@ const lydian: NoteCollection = {
   patternShort: ["W", "W", "W", "H", "W", "W", "H"],
 } as const;
 
-const mixolydian: NoteCollection = {
+const mixolydian: ScaleCollection = {
+  category: "scale",
+  rotation: 4,
   primaryName: "Mixolydian",
   names: [
     "Mixolydian",
@@ -154,7 +160,6 @@ const mixolydian: NoteCollection = {
   ],
   intervals: ["1", "2", "3", "4", "5", "6", "♭7", "8"],
   integers: [0, 2, 4, 5, 7, 9, 10],
-  rotation: 4,
   type: [
     "major",
     "dominant",
@@ -180,7 +185,9 @@ const mixolydian: NoteCollection = {
   patternShort: ["W", "W", "H", "W", "W", "H", "W"],
 } as const;
 
-const aeolian: NoteCollection = {
+const aeolian: ScaleCollection = {
+  category: "scale",
+  rotation: 5,
   primaryName: "Minor",
   names: [
     "Minor",
@@ -191,7 +198,6 @@ const aeolian: NoteCollection = {
   ],
   intervals: ["1", "2", "♭3", "4", "5", "♭6", "♭7", "8"],
   integers: [0, 2, 3, 5, 7, 8, 10],
-  rotation: 5,
   type: [
     "minor",
     "aeolian",
@@ -217,7 +223,9 @@ const aeolian: NoteCollection = {
   patternShort: ["W", "H", "W", "W", "H", "W", "W"],
 } as const;
 
-const locrian: NoteCollection = {
+const locrian: ScaleCollection = {
+  category: "scale",
+  rotation: 6,
   primaryName: "Locrian",
   names: [
     "Locrian",
@@ -226,7 +234,6 @@ const locrian: NoteCollection = {
   ],
   intervals: ["1", "♭2", "♭3", "4", "♭5", "♭6", "♭7", "8"],
   integers: [0, 1, 3, 5, 6, 8, 10],
-  rotation: 6,
   type: [
     "diminished",
     "locrian",
@@ -263,5 +270,5 @@ const _diatonicModes = {
 
 export type DiatonicModeKey = keyof typeof _diatonicModes;
 
-export const diatonicModes: Record<DiatonicModeKey, NoteCollection> =
+export const diatonicModes: Record<DiatonicModeKey, ScaleCollection> =
   _diatonicModes;

package/src/data/note-collections/{diminished.ts → diminished-variants.ts}

@@ -1,6 +1,11 @@
-import type { NoteCollection } from "../../types/note-collections.d.ts";
+import type {
+  ChordCollection,
+  NoteCollection,
+  ScaleCollection,
+} from "../../types/note-collections.d.ts";
 
-const diminishedTriad: NoteCollection = {
+const diminishedTriad: ChordCollection = {
+  category: "chord",
   primaryName: "dim",
   names: ["dim", "°", "Diminished Triad"],
   intervals: ["1", "♭3", "♭5"],
@@ -11,7 +16,8 @@ const diminishedTriad: NoteCollection = {
   patternShort: ["m3", "m3"],
 } as const;
 
-const diminished7: NoteCollection = {
+const diminished7: ChordCollection = {
+  category: "chord",
   primaryName: "dim7",
   names: ["dim7", "°7", "Diminished 7th"],
   intervals: ["1", "♭3", "♭5", "𝄫7"],
@@ -22,7 +28,8 @@ const diminished7: NoteCollection = {
   patternShort: ["m3", "m3", "m3"],
 } as const;
 
-const halfDiminished7: NoteCollection = {
+const halfDiminished7: ChordCollection = {
+  category: "chord",
   primaryName: "m7♭5",
   names: ["m7♭5", "ø7", "Half Diminished 7th"],
   intervals: ["1", "♭3", "♭5", "♭7"],
@@ -33,10 +40,11 @@ const halfDiminished7: NoteCollection = {
   patternShort: ["m3", "m3", "M3"],
 } as const;
 
-const wholeHalfDiminished: NoteCollection = {
+const wholeHalfDiminished: ScaleCollection = {
+  category: "scale",
   primaryName: "Whole Half Diminished",
   names: ["Whole Half Diminished"],
-  intervals: ["1", "2", "♭3", "4", "♭5", "♭6", "6", "7"],
+  intervals: ["1", "2", "♭3", "4", "♭5", "♭6", "6", "7", "8"],
   integers: [0, 2, 3, 5, 6, 8, 9, 11],
   type: ["diminished", "scale", "symmetrical", "octatonic"],
   characteristics: ["tense", "jazzy", "symmetrical", "alternating tones"],
@@ -44,10 +52,11 @@ const wholeHalfDiminished: NoteCollection = {
   patternShort: ["W", "H", "W", "H", "W", "H", "W", "H"],
 } as const;
 
-const halfWholeDiminished: NoteCollection = {
+const halfWholeDiminished: ScaleCollection = {
+  category: "scale",
   primaryName: "Half Whole Diminished",
   names: ["Half Whole Diminished", "Dominant Diminished"],
-  intervals: ["1", "♭2", "♭3", "3", "♯4", "5", "6", "♭7"],
+  intervals: ["1", "♭2", "♭3", "3", "♯4", "5", "6", "♭7", "8"],
   integers: [0, 1, 3, 4, 6, 7, 9, 10],
   type: ["diminished", "dominant", "scale", "symmetrical", "octatonic"],
   characteristics: [
@@ -60,7 +69,7 @@ const halfWholeDiminished: NoteCollection = {
   patternShort: ["H", "W", "H", "W", "H", "W", "H", "W"],
 } as const;
 
-export const _diminished = {
+export const _diminishedVariants = {
   diminishedTriad,
   diminished7,
   halfDiminished7,
@@ -68,6 +77,7 @@ export const _diminished = {
   halfWholeDiminished,
 } as const;
 
-export type DiminishedKey = keyof typeof _diminished;
+export type DiminishedVariantKey = keyof typeof _diminishedVariants;
 
-export const diminished: Record<DiminishedKey, NoteCollection> = _diminished;
+export const diminishedVariants: Record<DiminishedVariantKey, NoteCollection> =
+  _diminishedVariants;