@musodojo/music-theory-data 16.0.6 → 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": "16.0.6",
+  "version": "16.0.7",
   "description": "The musician-friendly TypeScript library for modes, scales, chords, and more.",
   "keywords": [
     "music",

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/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) {