@musodojo/music-theory-data 16.0.6 → 16.1.0

package/README.md

@@ -1,17 +1,92 @@
-# 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
+
+The `tests/` directory contains many useful examples.
+
+```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"]
+
+// Automatically knows whether to use flats or sharps
+notes = music_theory_data.getNoteNamesFromRootAndCollectionKey("F", "ionian");
+console.log(notes);
+//  ["F", "G", "A", "B♭", "C", "D", "E", "F"];
+
+// 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": "16.0.6",
+  "version": "16.1.0",
   "description": "The musician-friendly TypeScript library for modes, scales, chords, and more.",
   "keywords": [
     "music",

package/src/data/note-collections/harmonic-minor-modes.ts

@@ -95,9 +95,9 @@ const ionianSharp5: ScaleCollection = {
     "augmented second",
     "half",
     "whole",
-    "whole",
+    "half",
   ],
-  patternShort: ["W", "W", "H", "A2", "H", "W", "W"],
+  patternShort: ["W", "W", "H", "A2", "H", "W", "H"],
 } as const;
 
 const dorianSharp4: ScaleCollection = {
@@ -122,10 +122,10 @@ const dorianSharp4: ScaleCollection = {
     "augmented second",
     "half",
     "whole",
-    "whole",
     "half",
+    "whole",
   ],
-  patternShort: ["W", "H", "A2", "H", "W", "W", "H"],
+  patternShort: ["W", "H", "A2", "H", "W", "H", "W"],
 } as const;
 
 const phrygianDominant: ScaleCollection = {
@@ -187,9 +187,9 @@ const lydianSharp2: ScaleCollection = {
     "half",
     "whole",
     "whole",
-    "whole",
+    "half",
   ],
-  patternShort: ["A2", "H", "W", "H", "W", "W", "W"],
+  patternShort: ["A2", "H", "W", "H", "W", "W", "H"],
 } as const;
 
 const superLocrianDoubleFlat7: ScaleCollection = {
@@ -211,8 +211,16 @@ const superLocrianDoubleFlat7: ScaleCollection = {
     "altered",
     "theoretical",
   ],
-  pattern: ["half", "whole", "half", "whole", "whole", "half", "whole"],
-  patternShort: ["H", "W", "H", "W", "W", "H", "W"],
+  pattern: [
+    "half",
+    "whole",
+    "half",
+    "whole",
+    "whole",
+    "half",
+    "augmented second",
+  ],
+  patternShort: ["H", "W", "H", "W", "W", "H", "A2"],
 } as const;
 
 export const _harmonicMinorModes = {

package/src/mod.ts

@@ -13,28 +13,59 @@
  * import * as music_theory_data from "jsr:@musodojo/music-theory-data";
  *
  * // You can now access all the data and functions.
+ *
  * // The details for the Ionian Diatonic Mode (Major Scale).
  * console.log("ionian details: ", music_theory_data.noteCollections.ionian);
  * // ionian details:  {
- * // primaryName: "Major",
- * // names: [ "Major", "Ionian", "Major Scale", "Ionian Mode", "Diatonic Major" ],
- * // intervals: [
- * //   "1", "2", "3",
- * //   "4", "5", "6",
- * //   "7", "8"
- * // ],
- * // integers: [
- * //   0, 2,  4, 5,
- * //   7, 9, 11
- * // ],
- * // rotation: 0,
- * // type: [
- * //   "major.
- * // ...
+ * //   category: "scale",
+ * //   rotation: 0,
+ * //   primaryName: "Major",
+ * //   names: [
+ * //     "Major",
+ * //     "Ionian",
+ * //     "Major Scale",
+ * //     "Ionian Mode",
+ * //     "Diatonic Major",
+ * //   ],
+ * //   intervals: ["1", "2", "3", "4", "5", "6", "7", "8"],
+ * //   integers: [0, 2, 4, 5, 7, 9, 11],
+ * //   type: [
+ * //     "major",
+ * //     "ionian",
+ * //     "mode",
+ * //     "scale",
+ * //     "church mode",
+ * //     "diatonic mode",
+ * //     "heptatonic",
+ * //     "first diatonic mode",
+ * //     "do mode",
+ * //   ],
+ * //   characteristics: [
+ * //     "bright",
+ * //     "happy",
+ * //     "stable",
+ * //     "uplifting",
+ * //     "consonant",
+ * //     "western",
+ * //     "foundational",
+ * //     "simple",
+ * //     "pop music",
+ * //     "major tonality",
+ * //     "commonly used western scale",
+ * //   ],
+ * //   pattern: ["whole", "whole", "half", "whole", "whole", "whole", "half"],
+ * //   patternShort: ["W", "W", "H", "W", "W", "W", "H"],
  * // }
+ *
  * // Get the notes of a stored chord, or scale.
  * console.log("A harmonic minor: ", music_theory_data.getNoteNamesFromRootAndCollectionKey("A", "harmonicMinor"))
  * // A harmonic minor: ["A", "B", "C", "D", "E", "F", "G♯", "A"]
+ *
+ * // Log the array of all available Note Collection Keys
+ * console.log(Object.keys(music_theory_data.noteCollections));
+ *
+ * // Log the array of all available Grouped Note Collections Keys
+ * console.log(Object.keys(music_theory_data.groupedNoteCollections));
  * ```
  */
 export * from "./data/mod.ts";

package/src/utils/intervals.ts

@@ -9,6 +9,7 @@ import {
   simpleToCompoundIntervalMap,
   simpleToExtensionIntervalMap,
 } from "../data/labels/note-labels.ts";
+import type { NoteCollection } from "../types/note-collections.d.ts";
 
 export function filterOutOctaveIntervals(
   intervals: readonly Interval[],
@@ -97,3 +98,14 @@ export function getIntervalsFromQualities(
     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: NoteCollection,
+): IntervalQuality[] {
+  return getQualitiesFromIntervals(collection.intervals);
+}

package/src/utils/rotate-array.ts

@@ -1,3 +1,12 @@
+/**
+ * Rotates an array by a given number of steps.
+ * The rotation wraps around, so a positive rotation moves elements to the right,
+ * and a negative rotation moves them to the left.
+ *
+ * @param array The array to rotate.
+ * @param rotation The number of positions to rotate the array.
+ * @returns A new array with the elements rotated.
+ */
 export function rotateArray<T>(array: T[], rotation: number): T[] {
   const normalizedRotation = ((rotation % array.length) + array.length) %
     array.length;
@@ -5,7 +14,13 @@ export function rotateArray<T>(array: T[], rotation: number): T[] {
     array.slice(0, normalizedRotation),
   );
 }
-
+/**
+ * Rotates an array so that it starts with a specific element.
+ * @param array The array to rotate.
+ * @param start The element that should become the first element of the new array.
+ * @returns A new array, rotated to begin with the `start` element.
+ * @throws If the `start` element is not found in the array.
+ */
 export function rotateArrayToStartWith<T>(array: T[], start: T): T[] {
   const index = array.indexOf(start);
   if (index === -1) {