@tspro/web-music-score 3.2.0 → 4.0.0

package/dist/theory/index.js

@@ -1,4 +1,4 @@
-/* WebMusicScore v3.2.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v4.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -34,11 +34,10 @@ __export(theory_exports, {
   Handedness: () => Handedness,
   Interval: () => Interval,
   KeySignature: () => KeySignature,
-  MaxNoteLength: () => MaxNoteLength,
-  MinNoteLength: () => MinNoteLength,
   Mode: () => Mode,
   Note: () => Note,
   NoteLength: () => NoteLength,
+  NoteLengthProps: () => NoteLengthProps,
   PitchNotation: () => PitchNotation,
   PitchNotationList: () => PitchNotationList,
   RhythmProps: () => RhythmProps,
@@ -48,6 +47,7 @@ __export(theory_exports, {
   SymbolSet: () => SymbolSet,
   TimeSignature: () => TimeSignature,
   TuningNameList: () => TuningNameList,
+  Tuplet: () => Tuplet,
   alterTempoSpeed: () => alterTempoSpeed,
   getDefaultKeySignature: () => getDefaultKeySignature,
   getDefaultScale: () => getDefaultScale,
@@ -65,7 +65,8 @@ __export(theory_exports, {
   validateNoteLength: () => validateNoteLength,
   validatePitchNotation: () => validatePitchNotation,
   validateScaleType: () => validateScaleType,
-  validateTuningName: () => validateTuningName
+  validateTuningName: () => validateTuningName,
+  validateTupletRatio: () => validateTupletRatio
 });
 module.exports = __toCommonJS(theory_exports);
 
@@ -91,10 +92,10 @@ var PitchNotation = /* @__PURE__ */ ((PitchNotation2) => {
 var PitchNotationList = import_ts_utils_lib.Utils.Enum.getEnumValues(PitchNotation);
 var DefaultPitchNotation = 0 /* Scientific */;
 function validatePitchNotation(pn) {
-  if (!import_ts_utils_lib.Utils.Is.isEnumValue(pn, PitchNotation)) {
-    throw new import_core.MusicError(import_core.MusicErrorType.InvalidArg, `Invalid pitchNotation: ${pn}`);
-  } else {
+  if (import_ts_utils_lib.Utils.Is.isEnumValue(pn, PitchNotation)) {
     return pn;
+  } else {
+    throw new import_core.MusicError(import_core.MusicErrorType.InvalidArg, `Invalid pitchNotation: ${pn}`);
   }
 }
 function getPitchNotationName(pn) {
@@ -109,10 +110,10 @@ var GuitarNoteLabel = /* @__PURE__ */ ((GuitarNoteLabel2) => {
 var DefaultGuitarNoteLabel = "Default" /* Default */;
 var GuitarNoteLabelList = import_ts_utils_lib.Utils.Enum.getEnumValues(GuitarNoteLabel);
 function validateGuitarNoteLabel(label) {
-  if (!import_ts_utils_lib.Utils.Is.isEnumValue(label, GuitarNoteLabel)) {
-    throw new import_core.MusicError(import_core.MusicErrorType.Timesignature, `Invalid guitarNoteLabel: ${label}`);
-  } else {
+  if (import_ts_utils_lib.Utils.Is.isEnumValue(label, GuitarNoteLabel)) {
     return label;
+  } else {
+    throw new import_core.MusicError(import_core.MusicErrorType.Timesignature, `Invalid guitarNoteLabel: ${label}`);
   }
 }
 
@@ -1048,10 +1049,19 @@ function validateScaleType(scaleType) {
   if (import_ts_utils_lib5.Utils.Is.isEnumValue(scaleType, ScaleType)) {
     return scaleType;
   } else {
-    throw new import_core5.MusicError(import_core5.MusicErrorType.Scale, `Invalid scaleType: ${scaleType}`);
+    throw new import_core5.MusicError(import_core5.MusicErrorType.Scale, `Invalid scaleType: "${scaleType}"`);
   }
 }
-function getScale(tonic, scaleType) {
+function getScale(arg0, arg1) {
+  let tonic;
+  let scaleType;
+  if (arg1 !== void 0) {
+    tonic = arg0;
+    scaleType = validateScaleType(arg1);
+  } else {
+    tonic = arg0.split(" ")[0];
+    scaleType = validateScaleType(arg0.substring(tonic.length + 1));
+  }
   return getScaleFactory(scaleType).getScale(tonic);
 }
 var DefaultScale = getScale("C", "Major" /* Major */);
@@ -1542,10 +1552,10 @@ var Handedness = /* @__PURE__ */ ((Handedness2) => {
 })(Handedness || {});
 var DefaultHandedness = 0 /* RightHanded */;
 function validateHandedness(h) {
-  if (!import_ts_utils_lib7.Utils.Is.isEnumValue(h, Handedness)) {
-    throw new import_core7.MusicError(import_core7.MusicErrorType.InvalidArg, `Invalid handedness: ${h}`);
-  } else {
+  if (import_ts_utils_lib7.Utils.Is.isEnumValue(h, Handedness)) {
     return h;
+  } else {
+    throw new import_core7.MusicError(import_core7.MusicErrorType.InvalidArg, `Invalid handedness: ${h}`);
   }
 }
 var TuningNameList = tunings_default.list.map((data) => data.name);
@@ -1580,81 +1590,213 @@ var import_ts_utils_lib9 = require("@tspro/ts-utils-lib");
 // src/theory/rhythm.ts
 var import_ts_utils_lib8 = require("@tspro/ts-utils-lib");
 var import_core8 = require("@tspro/web-music-score/core");
+var cmp = (a, b) => a === b ? 0 : a < b ? -1 : 1;
+var MaxTupletRatioValue = 12;
+var TicksMultiplier = 12 * 11 * 9 * 7 * 5;
 var NoteLength = /* @__PURE__ */ ((NoteLength3) => {
-  NoteLength3[NoteLength3["Whole"] = 192] = "Whole";
-  NoteLength3[NoteLength3["Half"] = 96] = "Half";
-  NoteLength3[NoteLength3["Quarter"] = 48] = "Quarter";
-  NoteLength3[NoteLength3["Eighth"] = 24] = "Eighth";
-  NoteLength3[NoteLength3["Sixteenth"] = 12] = "Sixteenth";
-  NoteLength3[NoteLength3["ThirtySecond"] = 6] = "ThirtySecond";
-  NoteLength3[NoteLength3["SixtyFourth"] = 3] = "SixtyFourth";
+  NoteLength3["Whole"] = "1n";
+  NoteLength3["WholeTriplet"] = "1t";
+  NoteLength3["WholeDot"] = "1.";
+  NoteLength3["Whole12Dots"] = "1..";
+  NoteLength3["Whole3Dots"] = "1...";
+  NoteLength3["Whole4Dots"] = "1....";
+  NoteLength3["Whole5Dots"] = "1.....";
+  NoteLength3["Whole6Dots"] = "1......";
+  NoteLength3["Half"] = "2n";
+  NoteLength3["HalfTriplet"] = "2t";
+  NoteLength3["HalfDot"] = "2.";
+  NoteLength3["Half2Dots"] = "2..";
+  NoteLength3["Half3Dots"] = "2...";
+  NoteLength3["Half4Dots"] = "2....";
+  NoteLength3["Half5Dots"] = "2.....";
+  NoteLength3["Quarter"] = "4n";
+  NoteLength3["QuarterTriplet"] = "4t";
+  NoteLength3["QuarterDot"] = "4.";
+  NoteLength3["Quarter2Dots"] = "4..";
+  NoteLength3["Quarter3Dots"] = "4...";
+  NoteLength3["Quarter4Dots"] = "4....";
+  NoteLength3["Eighth"] = "8n";
+  NoteLength3["EighthTriplet"] = "8t";
+  NoteLength3["EighthDot"] = "8.";
+  NoteLength3["Eighth2Dots"] = "8..";
+  NoteLength3["Eighth3Dots"] = "8...";
+  NoteLength3["Sixteenth"] = "16n";
+  NoteLength3["SixteenthTriplet"] = "16t";
+  NoteLength3["SixteenthDot"] = "16.";
+  NoteLength3["Sixteenth2Dots"] = "16..";
+  NoteLength3["ThirtySecond"] = "32n";
+  NoteLength3["ThirtySecondTriplet"] = "32t";
+  NoteLength3["ThirtySecondDot"] = "32.";
+  NoteLength3["SixtyFourth"] = "64n";
+  NoteLength3["SixtyFourthTriplet"] = "64t";
   return NoteLength3;
 })(NoteLength || {});
-var MaxNoteLength = 192 /* Whole */;
-var MinNoteLength = 3 /* SixtyFourth */;
-var FlagCountMap = /* @__PURE__ */ new Map([
-  [192 /* Whole */, 0],
-  [96 /* Half */, 0],
-  [48 /* Quarter */, 0],
-  [24 /* Eighth */, 1],
-  [12 /* Sixteenth */, 2],
-  [6 /* ThirtySecond */, 3],
-  [3 /* SixtyFourth */, 4]
-]);
-var NoteSymbolMap = /* @__PURE__ */ new Map([
-  [192 /* Whole */, "\u{1D15D}"],
-  [96 /* Half */, "\u{1D15E}"],
-  [48 /* Quarter */, "\u{1D15F}"],
-  [24 /* Eighth */, "\u{1D160}"],
-  [12 /* Sixteenth */, "\u{1D161}"],
-  [6 /* ThirtySecond */, "\u{1D162}"],
-  [3 /* SixtyFourth */, "\u{1D163}"]
-]);
 function validateNoteLength(noteLength) {
-  if (!import_ts_utils_lib8.Utils.Is.isEnumValue(noteLength, NoteLength)) {
+  if (import_ts_utils_lib8.Utils.Is.isEnumValue(noteLength, NoteLength)) {
+    return noteLength;
+  } else {
     throw new import_core8.MusicError(import_core8.MusicErrorType.InvalidArg, `Invalid noteLength: ${noteLength}`);
+  }
+}
+var _NoteLengthProps = class _NoteLengthProps {
+  // Is solid (black) note head?
+  constructor(noteLength) {
+    __publicField(this, "noteLength");
+    __publicField(this, "noteSize");
+    __publicField(this, "ticks");
+    // Not altered by isTriplet!
+    __publicField(this, "flagCount");
+    __publicField(this, "dotCount");
+    __publicField(this, "maxDotCount");
+    __publicField(this, "isTriplet");
+    __publicField(this, "hasStem");
+    __publicField(this, "isSolid");
+    this.noteLength = validateNoteLength(noteLength);
+    this.noteSize = parseInt(noteLength);
+    this.isTriplet = noteLength.endsWith("t");
+    this.maxDotCount = this.isTriplet ? 0 : Math.floor(Math.log2(_NoteLengthProps.ShortestNoteSize / this.noteSize));
+    this.dotCount = import_ts_utils_lib8.Utils.Str.charCount(noteLength, ".");
+    this.flagCount = this.noteSize > 4 ? Math.floor(Math.log2(this.noteSize / 4)) : 0;
+    this.ticks = TicksMultiplier * _NoteLengthProps.ShortestNoteSize / this.noteSize;
+    this.hasStem = this.noteSize > 1;
+    this.isSolid = this.noteSize > 2;
+    if (this.dotCount > this.maxDotCount) {
+      throw new import_core8.MusicError(import_core8.MusicErrorType.Note, `dotCount ${this.dotCount} > maxDotCount ${this.maxDotCount}, for noteLength "${this.noteLength}".`);
+    } else if (this.isTriplet && this.dotCount > 0) {
+      throw new import_core8.MusicError(import_core8.MusicErrorType.Note, `noteLength "${this.noteLength}" is both triplet and dotted!`);
+    }
+  }
+  static get(noteLength) {
+    let p = this.cache.get(noteLength);
+    if (!p) {
+      this.cache.set(noteLength, p = new _NoteLengthProps(noteLength));
+    }
+    return p;
+  }
+  static create(noteLength, dotCount = 0) {
+    let noteSize = typeof noteLength === "number" ? noteLength : this.get(noteLength).noteSize;
+    return this.get(noteSize + (import_ts_utils_lib8.Utils.Is.isIntegerGte(dotCount, 1) ? ".".repeat(dotCount) : "n"));
+  }
+  /**
+   * Compare note lengths/sizes. Whole (1) > half (2) > quarter (4), etc.
+   * Ignores possible triplet property of note length.
+   * @param a - NoteLengthProps, NoteLength/Str or noteSize
+   * @param b - NoteLengthProps, NoteLength/Str or noteSize
+   * @returns - -1: a < b, 0: a === b, +1: a > b (note length/size comparisons)
+   */
+  static cmp(a, b) {
+    let aNoteSize = a instanceof _NoteLengthProps ? a.noteSize : typeof a === "number" ? a : _NoteLengthProps.get(a).noteSize;
+    let bNoteSize = b instanceof _NoteLengthProps ? b.noteSize : typeof b === "number" ? b : _NoteLengthProps.get(b).noteSize;
+    return cmp(bNoteSize, aNoteSize);
+  }
+  /**
+   * Compare note lengths/sizes for equality.
+   * Ignores possible triplet property of note length.
+   * @param a - NoteLengthProps, NoteLength/Str or noteSize
+   * @param b - NoteLengthProps, NoteLength/Str or noteSize
+   * @returns - true: a === b, false: a !== b (note length/size comparisons)
+   */
+  static equals(a, b) {
+    let aNoteSize = a instanceof _NoteLengthProps ? a.noteSize : typeof a === "number" ? a : _NoteLengthProps.get(a).noteSize;
+    let bNoteSize = b instanceof _NoteLengthProps ? b.noteSize : typeof b === "number" ? b : _NoteLengthProps.get(b).noteSize;
+    return aNoteSize === bNoteSize;
+  }
+};
+__publicField(_NoteLengthProps, "LongestNoteSize", Math.min(...import_ts_utils_lib8.Utils.Enum.getEnumValues(NoteLength).map((noteLength) => parseInt(noteLength))));
+__publicField(_NoteLengthProps, "ShortestNoteSize", Math.max(...import_ts_utils_lib8.Utils.Enum.getEnumValues(NoteLength).map((noteLength) => parseInt(noteLength))));
+__publicField(_NoteLengthProps, "cache", /* @__PURE__ */ new Map());
+var NoteLengthProps = _NoteLengthProps;
+function validateTupletRatio(tupletRatio) {
+  if (import_ts_utils_lib8.Utils.Is.isObject(tupletRatio) && import_ts_utils_lib8.Utils.Is.isIntegerBetween(tupletRatio.parts, 2, MaxTupletRatioValue) && import_ts_utils_lib8.Utils.Is.isIntegerBetween(tupletRatio.inTimeOf, 2, MaxTupletRatioValue)) {
+    return tupletRatio;
   } else {
-    return noteLength;
+    throw new import_core8.MusicError(import_core8.MusicErrorType.Note, `Invalid tupletRatio ${JSON.stringify(tupletRatio)}`);
   }
 }
-var RhythmProps = class _RhythmProps {
-  constructor(noteLength, dotted, triplet) {
+var Tuplet = {
+  /** 2 in the time of 3 */
+  Duplet: { parts: 2, inTimeOf: 3 },
+  /** 3 in the time of 2 */
+  Triplet: { parts: 3, inTimeOf: 2 },
+  /** 4 in the time of 3 */
+  Quadruplet: { parts: 4, inTimeOf: 3 }
+};
+var _RhythmProps = class _RhythmProps {
+  constructor(noteLength, dotCount, tupletRatio) {
     __publicField(this, "noteLength");
-    __publicField(this, "dotted");
-    __publicField(this, "triplet");
+    __publicField(this, "noteSize");
+    // whole=1, half=2, quarter=4, etc.
+    __publicField(this, "dotCount");
+    __publicField(this, "tupletRatio");
     __publicField(this, "ticks");
     __publicField(this, "flagCount");
-    var _a;
+    __publicField(this, "hasStem");
+    __publicField(this, "isSolidNoteHead");
     this.noteLength = validateNoteLength(noteLength);
-    this.dotted = dotted === true;
-    this.triplet = triplet === true;
-    this.ticks = this.noteLength;
-    this.flagCount = (_a = FlagCountMap.get(this.noteLength)) != null ? _a : 0;
-    if (this.dotted && this.triplet) {
-      throw new import_core8.MusicError(import_core8.MusicErrorType.Note, "Note cannot be both dotted and triplet!");
-    } else if (this.dotted && this.noteLength === MinNoteLength) {
-      throw new import_core8.MusicError(import_core8.MusicErrorType.Note, "Shortest note cannot be dotted!");
+    let p = NoteLengthProps.get(noteLength);
+    this.noteSize = p.noteSize;
+    this.ticks = p.ticks;
+    this.flagCount = p.flagCount;
+    this.dotCount = dotCount != null ? dotCount : p.dotCount;
+    this.hasStem = p.hasStem;
+    this.isSolidNoteHead = p.isSolid;
+    if (import_ts_utils_lib8.Utils.Is.isObject(tupletRatio)) {
+      this.tupletRatio = validateTupletRatio(tupletRatio);
+    } else if (p.isTriplet) {
+      this.tupletRatio = Tuplet.Triplet;
+    } else {
+      this.tupletRatio = void 0;
     }
-    if (this.dotted) {
-      this.ticks += this.noteLength / 2;
+    if (this.dotCount > 0 && this.tupletRatio !== void 0) {
+      throw new import_core8.MusicError(import_core8.MusicErrorType.Note, `Note cannot be both dotted and tuplet!`);
+    } else if (this.dotCount > p.maxDotCount) {
+      throw new import_core8.MusicError(import_core8.MusicErrorType.Note, `Too big dot count ${this.dotCount} for note length ${this.noteLength}.`);
     }
-    if (this.triplet) {
-      this.ticks = this.ticks * 2 / 3;
+    for (let add = this.ticks / 2, i = 1; i <= this.dotCount; i++, add /= 2) {
+      this.ticks += add;
+    }
+    if (this.tupletRatio) {
+      this.ticks *= this.tupletRatio.inTimeOf / this.tupletRatio.parts;
     }
   }
-  static createFromNoteSize(noteSize) {
-    return new _RhythmProps(MaxNoteLength / noteSize);
+  toString() {
+    let sym = _RhythmProps.NoteSymbolMap.get(this.noteSize);
+    let dots = ".".repeat(this.dotCount);
+    return sym ? sym + dots : "" + this.noteSize + (dots.length > 0 ? dots : "n");
   }
-  canDot() {
-    return !this.dotted && this.noteLength !== MinNoteLength;
+  static get(noteLength, dotCount, tupletRatio) {
+    if (dotCount !== void 0 || tupletRatio !== void 0) {
+      return new _RhythmProps(noteLength, dotCount, tupletRatio);
+    } else {
+      let rhythmProps = this.cache.get(noteLength);
+      if (!rhythmProps) {
+        this.cache.set(noteLength, rhythmProps = new _RhythmProps(noteLength));
+      }
+      return rhythmProps;
+    }
   }
-  hasStem() {
-    return this.noteLength < 192 /* Whole */;
+  /**
+   * Compare duration of rhythm props.
+   * @param a - RhythmProps
+   * @param b - RhythmProps
+   * @returns - -1: a < b, 0: a === b, +1: a > b (duration comparisons)
+   */
+  static cmp(a, b) {
+    return cmp(a.ticks, b.ticks);
   }
-  toString() {
-    return NoteSymbolMap.get(this.noteLength) + (this.dotted ? "." : "");
+  /**
+   * Compare duration equality of rhythm props.
+   * @param a - RhythmProps
+   * @param b - RhythmProps
+   * @returns - true: a === b, false: a !== b (duration comparisons)
+   */
+  static equals(a, b) {
+    return a.ticks === b.ticks;
   }
 };
+__publicField(_RhythmProps, "NoteSymbolMap", /* @__PURE__ */ new Map([[1, "\u{1D15D}"], [2, "\u{1D15E}"], [4, "\u{1D15F}"], [8, "\u{1D160}"], [16, "\u{1D161}"], [32, "\u{1D162}"], [64, "\u{1D163}"], [128, "\u{1D164}"]]));
+__publicField(_RhythmProps, "cache", /* @__PURE__ */ new Map());
+var RhythmProps = _RhythmProps;
 
 // src/theory/time-signature.ts
 var import_core9 = require("@tspro/web-music-score/core");
@@ -1682,9 +1824,9 @@ var TimeSignature = class {
     } else if (!import_ts_utils_lib9.Utils.Is.isIntegerGte(this.beatSize, 1)) {
       throw new import_core9.MusicError(import_core9.MusicErrorType.Timesignature, `Invalid beatSize: ${this.beatSize}`);
     }
-    let beatLengthValue = RhythmProps.createFromNoteSize(this.beatSize);
-    this.beatLength = beatLengthValue.noteLength;
-    this.measureTicks = this.beatCount * beatLengthValue.ticks;
+    let props = NoteLengthProps.create(this.beatSize);
+    this.beatLength = props.noteLength;
+    this.measureTicks = this.beatCount * props.ticks;
     if (this.is(2, 4) || this.is(3, 4) || this.is(4, 4)) {
       this.beamGroupCount = this.beatCount;
     } else if (this.is(6, 8) || this.is(9, 8)) {
@@ -1717,17 +1859,17 @@ function getDefaultTimeSignature() {
 var defaultTempo;
 function getDefaultTempo() {
   if (!defaultTempo) {
-    defaultTempo = { beatsPerMinute: 120, options: { beatLength: 48 /* Quarter */, dotted: false } };
+    defaultTempo = { beatsPerMinute: 120, options: { beatLength: "4n" /* Quarter */, dotCount: 0 } };
   }
   return defaultTempo;
 }
 function getTempoString(tempo) {
-  return new RhythmProps(tempo.options.beatLength, tempo.options.dotted).toString() + "=" + tempo.beatsPerMinute;
+  return RhythmProps.get(tempo.options.beatLength, tempo.options.dotCount).toString() + "=" + tempo.beatsPerMinute;
 }
 function alterTempoSpeed(tempo, speed) {
   return {
     beatsPerMinute: tempo.beatsPerMinute * speed,
-    options: { beatLength: tempo.options.beatLength, dotted: tempo.options.dotted }
+    options: { beatLength: tempo.options.beatLength, dotCount: tempo.options.dotCount }
   };
 }
 
@@ -1747,11 +1889,10 @@ var import_core10 = require("@tspro/web-music-score/core");
   Handedness,
   Interval,
   KeySignature,
-  MaxNoteLength,
-  MinNoteLength,
   Mode,
   Note,
   NoteLength,
+  NoteLengthProps,
   PitchNotation,
   PitchNotationList,
   RhythmProps,
@@ -1761,6 +1902,7 @@ var import_core10 = require("@tspro/web-music-score/core");
   SymbolSet,
   TimeSignature,
   TuningNameList,
+  Tuplet,
   alterTempoSpeed,
   getDefaultKeySignature,
   getDefaultScale,
@@ -1778,6 +1920,7 @@ var import_core10 = require("@tspro/web-music-score/core");
   validateNoteLength,
   validatePitchNotation,
   validateScaleType,
-  validateTuningName
+  validateTuningName,
+  validateTupletRatio
 });
 //# sourceMappingURL=index.js.map