chordsheetjs 7.3.1 → 7.4.0

package/README.md

@@ -639,9 +639,9 @@ If not, it returns [INDETERMINATE](#INDETERMINATE)</p>
     * [.clone()](#Song+clone) ⇒ [<code>Song</code>](#Song)
     * [.setKey(key)](#Song+setKey) ⇒ [<code>Song</code>](#Song)
     * [.setCapo(capo)](#Song+setCapo) ⇒ [<code>Song</code>](#Song)
-    * [.transpose(delta)](#Song+transpose) ⇒ [<code>Song</code>](#Song)
-    * [.transposeUp()](#Song+transposeUp) ⇒ [<code>Song</code>](#Song)
-    * [.transposeDown()](#Song+transposeDown) ⇒ [<code>Song</code>](#Song)
+    * [.transpose(delta, [options])](#Song+transpose) ⇒ [<code>Song</code>](#Song)
+    * [.transposeUp([options])](#Song+transposeUp) ⇒ [<code>Song</code>](#Song)
+    * [.transposeDown([options])](#Song+transposeDown) ⇒ [<code>Song</code>](#Song)
     * [.changeKey(newKey)](#Song+changeKey) ⇒ [<code>Song</code>](#Song)
     * [.changeMetadata(name, value)](#Song+changeMetadata)
     * [.mapItems(func)](#Song+mapItems) ⇒ [<code>Song</code>](#Song)
@@ -729,7 +729,7 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 
 <a name="Song+transpose"></a>
 
-### song.transpose(delta) ⇒ [<code>Song</code>](#Song)
+### song.transpose(delta, [options]) ⇒ [<code>Song</code>](#Song)
 <p>Transposes the song by the specified delta. It will:</p>
 <ul>
 <li>transpose all chords, see: [transpose](#Chord+transpose)</li>
@@ -740,13 +740,15 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 **Kind**: instance method of [<code>Song</code>](#Song)  
 **Returns**: [<code>Song</code>](#Song) - <p>The transposed song</p>  
 
-| Param | Type | Description |
-| --- | --- | --- |
-| delta | <code>number</code> | <p>The number of semitones (positive or negative) to transpose with</p> |
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| delta | <code>number</code> |  | <p>The number of semitones (positive or negative) to transpose with</p> |
+| [options] | <code>Object</code> | <code>{}</code> | <p>options</p> |
+| [options.normalizeChordSuffix] | <code>boolean</code> | <code>false</code> | <p>whether to normalize the chord suffixes after transposing</p> |
 
 <a name="Song+transposeUp"></a>
 
-### song.transposeUp() ⇒ [<code>Song</code>](#Song)
+### song.transposeUp([options]) ⇒ [<code>Song</code>](#Song)
 <p>Transposes the song up by one semitone. It will:</p>
 <ul>
 <li>transpose all chords, see: [transpose](#Chord+transpose)</li>
@@ -756,9 +758,15 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 
 **Kind**: instance method of [<code>Song</code>](#Song)  
 **Returns**: [<code>Song</code>](#Song) - <p>The transposed song</p>  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>Object</code> | <code>{}</code> | <p>options</p> |
+| [options.normalizeChordSuffix] | <code>boolean</code> | <code>false</code> | <p>whether to normalize the chord suffixes after transposing</p> |
+
 <a name="Song+transposeDown"></a>
 
-### song.transposeDown() ⇒ [<code>Song</code>](#Song)
+### song.transposeDown([options]) ⇒ [<code>Song</code>](#Song)
 <p>Transposes the song down by one semitone. It will:</p>
 <ul>
 <li>transpose all chords, see: [transpose](#Chord+transpose)</li>
@@ -768,6 +776,12 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 
 **Kind**: instance method of [<code>Song</code>](#Song)  
 **Returns**: [<code>Song</code>](#Song) - <p>The transposed song</p>  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>Object</code> | <code>{}</code> | <p>options</p> |
+| [options.normalizeChordSuffix] | <code>boolean</code> | <code>false</code> | <p>whether to normalize the chord suffixes after transposing</p> |
+
 <a name="Song+changeKey"></a>
 
 ### song.changeKey(newKey) ⇒ [<code>Song</code>](#Song)
@@ -1188,7 +1202,7 @@ Inherits from [ChordSheetParser](#ChordSheetParser)</p>
         * [.toNumericString([key])](#Chord+toNumericString) ⇒ <code>string</code>
         * [.isNumeral()](#Chord+isNumeral) ⇒ <code>boolean</code>
         * [.toString()](#Chord+toString) ⇒ <code>string</code>
-        * [.normalize()](#Chord+normalize) ⇒ [<code>Chord</code>](#Chord)
+        * [.normalize([key], [options])](#Chord+normalize) ⇒ [<code>Chord</code>](#Chord)
         * [.useModifier(newModifier)](#Chord+useModifier) ⇒ [<code>Chord</code>](#Chord)
         * [.transposeUp()](#Chord+transposeUp) ⇒ [<code>Chord</code>](#Chord)
         * [.transposeDown()](#Chord+transposeDown) ⇒ [<code>Chord</code>](#Chord)
@@ -1312,7 +1326,7 @@ For example, a chord symbol A# with reference key E will return the numeric chor
 **Returns**: <code>string</code> - <p>the chord string</p>  
 <a name="Chord+normalize"></a>
 
-### chord.normalize() ⇒ [<code>Chord</code>](#Chord)
+### chord.normalize([key], [options]) ⇒ [<code>Chord</code>](#Chord)
 <p>Normalizes the chord root and bass notes:</p>
 <ul>
 <li>Fb becomes E</li>
@@ -1324,11 +1338,19 @@ For example, a chord symbol A# with reference key E will return the numeric chor
 <li>7# becomes 1</li>
 <li>3# becomes 4</li>
 </ul>
-<p>Besides that it normalizes the suffix. For example, <code>sus2</code> becomes <code>2</code>, <code>sus4</code> becomes <code>sus</code>.
+<p>Besides that it normalizes the suffix if <code>normalizeSuffix</code> is <code>true</code>.
+For example, <code>sus2</code> becomes <code>2</code>, <code>sus4</code> becomes <code>sus</code>.
 All suffix normalizations can be found in <code>src/normalize_mappings/suffix-mapping.txt</code>.</p>
 
 **Kind**: instance method of [<code>Chord</code>](#Chord)  
 **Returns**: [<code>Chord</code>](#Chord) - <p>the normalized chord</p>  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [key] | <code>Key</code> \| <code>string</code> | <code></code> | <p>the key to normalize to</p> |
+| [options] | <code>Object</code> | <code>{}</code> | <p>options</p> |
+| [options.normalizeSuffix] | <code>boolean</code> | <code>true</code> | <p>whether to normalize the chord suffix after transposing</p> |
+
 <a name="Chord+useModifier"></a>
 
 ### chord.useModifier(newModifier) ⇒ [<code>Chord</code>](#Chord)

package/lib/bundle.js

@@ -3088,7 +3088,7 @@ var $e12151f977ef7bf6$export$2e2bcd8739ae039 = $e12151f977ef7bf6$var$mapping;
 
 
 
-function $26f57998457eb2d4$var$normalizeSuffix(suffix) {
+function $26f57998457eb2d4$var$normalizeChordSuffix(suffix) {
     if ((0, $e12151f977ef7bf6$export$2e2bcd8739ae039)[suffix] === "[blank]") return null;
     return (0, $e12151f977ef7bf6$export$2e2bcd8739ae039)[suffix] || suffix;
 }
@@ -3135,7 +3135,7 @@ const $26f57998457eb2d4$var$regexes = [
         const keyObj = (0, $bff5407e03fdc8ee$export$2e2bcd8739ae039).wrap(key);
         const rootKey = this.root.toChordSymbol(keyObj).normalizeEnharmonics(keyObj);
         let chordSymbolChord = new $26f57998457eb2d4$var$Chord({
-            suffix: $26f57998457eb2d4$var$normalizeSuffix(this.suffix),
+            suffix: $26f57998457eb2d4$var$normalizeChordSuffix(this.suffix),
             root: rootKey,
             bass: this.bass?.toChordSymbol(keyObj).normalizeEnharmonics(rootKey)
         });
@@ -3171,7 +3171,7 @@ const $26f57998457eb2d4$var$regexes = [
         });
         const keyObj = (0, $bff5407e03fdc8ee$export$2e2bcd8739ae039).wrap(key);
         return new $26f57998457eb2d4$var$Chord({
-            suffix: $26f57998457eb2d4$var$normalizeSuffix(this.suffix),
+            suffix: $26f57998457eb2d4$var$normalizeChordSuffix(this.suffix),
             root: this.root.toNumeric(keyObj),
             bass: this.bass?.toNumeric(keyObj)
         });
@@ -3189,7 +3189,7 @@ const $26f57998457eb2d4$var$regexes = [
         });
         const keyObj = (0, $bff5407e03fdc8ee$export$2e2bcd8739ae039).wrap(key);
         return new $26f57998457eb2d4$var$Chord({
-            suffix: $26f57998457eb2d4$var$normalizeSuffix(this.suffix),
+            suffix: $26f57998457eb2d4$var$normalizeChordSuffix(this.suffix),
             root: this.root.toNumeral(keyObj),
             bass: this.bass?.toNumeral(keyObj)
         });
@@ -3243,17 +3243,21 @@ const $26f57998457eb2d4$var$regexes = [
    * - 7# becomes 1
    * - 3# becomes 4
    *
-   * Besides that it normalizes the suffix. For example, `sus2` becomes `2`, `sus4` becomes `sus`.
+   * Besides that it normalizes the suffix if `normalizeSuffix` is `true`.
+   * For example, `sus2` becomes `2`, `sus4` becomes `sus`.
    * All suffix normalizations can be found in `src/normalize_mappings/suffix-mapping.txt`.
-   *
+   * @param {Key|string} [key=null] the key to normalize to
+   * @param {Object} [options={}] options
+   * @param {boolean} [options.normalizeSuffix=true] whether to normalize the chord suffix after transposing
    * @returns {Chord} the normalized chord
-   */ normalize(key = null) {
+   */ normalize(key = null, { normalizeSuffix: normalizeSuffix = true  } = {}) {
+        const suffix = normalizeSuffix ? $26f57998457eb2d4$var$normalizeChordSuffix(this.suffix) : this.suffix;
         if ((0, $21a34a464e7bc609$export$7ee701e290d9865)(key)) return this.process("normalize").set({
-            suffix: (0, $21a34a464e7bc609$export$ed9b06b5ee264ad3)($26f57998457eb2d4$var$normalizeSuffix(this.suffix))
+            suffix: suffix
         });
         return this.set({
+            suffix: suffix,
             root: this.root.normalizeEnharmonics(key),
-            suffix: (0, $21a34a464e7bc609$export$ed9b06b5ee264ad3)($26f57998457eb2d4$var$normalizeSuffix(this.suffix)),
             bass: this.bass ? this.bass.normalizeEnharmonics(this.root.toString()) : null
         });
     }
@@ -3374,11 +3378,13 @@ var $26f57998457eb2d4$export$2e2bcd8739ae039 = $26f57998457eb2d4$var$Chord;
             lyrics: lyrics
         });
     }
-    transpose(delta, key = null) {
+    transpose(delta, key = null, { normalizeChordSuffix: normalizeChordSuffix = false  } = {}) {
         const chordObj = (0, $26f57998457eb2d4$export$2e2bcd8739ae039).parse(this.chords);
         if (chordObj) {
             let transposedChord = chordObj.transpose(delta);
-            if (key) transposedChord = transposedChord.normalize(key);
+            if (key) transposedChord = transposedChord.normalize(key, {
+                normalizeSuffix: normalizeChordSuffix
+            });
             return this.set({
                 chords: transposedChord.toString()
             });
@@ -4141,8 +4147,10 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
    * - transpose the song key in {@link metadata}
    * - update any existing `key` directive
    * @param {number} delta The number of semitones (positive or negative) to transpose with
+   * @param {Object} [options={}] options
+   * @param {boolean} [options.normalizeChordSuffix=false] whether to normalize the chord suffixes after transposing
    * @returns {Song} The transposed song
-   */ transpose(delta) {
+   */ transpose(delta, { normalizeChordSuffix: normalizeChordSuffix = false  } = {}) {
         const wrappedKey = (0, $bff5407e03fdc8ee$export$2e2bcd8739ae039).wrap(this.key);
         let transposedKey = null;
         let song = this;
@@ -4151,7 +4159,9 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
             song = song.setKey(transposedKey);
         }
         return song.mapItems((item)=>{
-            if (item instanceof (0, $d454f4215ba01af2$export$2e2bcd8739ae039)) return item.transpose(delta, transposedKey);
+            if (item instanceof (0, $d454f4215ba01af2$export$2e2bcd8739ae039)) return item.transpose(delta, transposedKey, {
+                normalizeChordSuffix: normalizeChordSuffix
+            });
             return item;
         });
     }
@@ -4160,18 +4170,26 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
    * - transpose all chords, see: {@link Chord#transpose}
    * - transpose the song key in {@link metadata}
    * - update any existing `key` directive
+   * @param {Object} [options={}] options
+   * @param {boolean} [options.normalizeChordSuffix=false] whether to normalize the chord suffixes after transposing
    * @returns {Song} The transposed song
-   */ transposeUp() {
-        return this.transpose(1);
+   */ transposeUp({ normalizeChordSuffix: normalizeChordSuffix = false  } = {}) {
+        return this.transpose(1, {
+            normalizeChordSuffix: normalizeChordSuffix
+        });
     }
     /**
    * Transposes the song down by one semitone. It will:
    * - transpose all chords, see: {@link Chord#transpose}
    * - transpose the song key in {@link metadata}
    * - update any existing `key` directive
+   * @param {Object} [options={}] options
+   * @param {boolean} [options.normalizeChordSuffix=false] whether to normalize the chord suffixes after transposing
    * @returns {Song} The transposed song
-   */ transposeDown() {
-        return this.transpose(-1);
+   */ transposeDown({ normalizeChordSuffix: normalizeChordSuffix = false  } = {}) {
+        return this.transpose(-1, {
+            normalizeChordSuffix: normalizeChordSuffix
+        });
     }
     /**
    * Returns a copy of the song with the key set to the specified key. It changes:

package/lib/index.js

@@ -3087,7 +3087,7 @@ var $e12151f977ef7bf6$export$2e2bcd8739ae039 = $e12151f977ef7bf6$var$mapping;
 
 
 
-function $26f57998457eb2d4$var$normalizeSuffix(suffix) {
+function $26f57998457eb2d4$var$normalizeChordSuffix(suffix) {
     if ((0, $e12151f977ef7bf6$export$2e2bcd8739ae039)[suffix] === "[blank]") return null;
     return (0, $e12151f977ef7bf6$export$2e2bcd8739ae039)[suffix] || suffix;
 }
@@ -3134,7 +3134,7 @@ const $26f57998457eb2d4$var$regexes = [
         const keyObj = (0, $bff5407e03fdc8ee$export$2e2bcd8739ae039).wrap(key);
         const rootKey = this.root.toChordSymbol(keyObj).normalizeEnharmonics(keyObj);
         let chordSymbolChord = new $26f57998457eb2d4$var$Chord({
-            suffix: $26f57998457eb2d4$var$normalizeSuffix(this.suffix),
+            suffix: $26f57998457eb2d4$var$normalizeChordSuffix(this.suffix),
             root: rootKey,
             bass: this.bass?.toChordSymbol(keyObj).normalizeEnharmonics(rootKey)
         });
@@ -3170,7 +3170,7 @@ const $26f57998457eb2d4$var$regexes = [
         });
         const keyObj = (0, $bff5407e03fdc8ee$export$2e2bcd8739ae039).wrap(key);
         return new $26f57998457eb2d4$var$Chord({
-            suffix: $26f57998457eb2d4$var$normalizeSuffix(this.suffix),
+            suffix: $26f57998457eb2d4$var$normalizeChordSuffix(this.suffix),
             root: this.root.toNumeric(keyObj),
             bass: this.bass?.toNumeric(keyObj)
         });
@@ -3188,7 +3188,7 @@ const $26f57998457eb2d4$var$regexes = [
         });
         const keyObj = (0, $bff5407e03fdc8ee$export$2e2bcd8739ae039).wrap(key);
         return new $26f57998457eb2d4$var$Chord({
-            suffix: $26f57998457eb2d4$var$normalizeSuffix(this.suffix),
+            suffix: $26f57998457eb2d4$var$normalizeChordSuffix(this.suffix),
             root: this.root.toNumeral(keyObj),
             bass: this.bass?.toNumeral(keyObj)
         });
@@ -3242,17 +3242,21 @@ const $26f57998457eb2d4$var$regexes = [
    * - 7# becomes 1
    * - 3# becomes 4
    *
-   * Besides that it normalizes the suffix. For example, `sus2` becomes `2`, `sus4` becomes `sus`.
+   * Besides that it normalizes the suffix if `normalizeSuffix` is `true`.
+   * For example, `sus2` becomes `2`, `sus4` becomes `sus`.
    * All suffix normalizations can be found in `src/normalize_mappings/suffix-mapping.txt`.
-   *
+   * @param {Key|string} [key=null] the key to normalize to
+   * @param {Object} [options={}] options
+   * @param {boolean} [options.normalizeSuffix=true] whether to normalize the chord suffix after transposing
    * @returns {Chord} the normalized chord
-   */ normalize(key = null) {
+   */ normalize(key = null, { normalizeSuffix: normalizeSuffix = true  } = {}) {
+        const suffix = normalizeSuffix ? $26f57998457eb2d4$var$normalizeChordSuffix(this.suffix) : this.suffix;
         if ((0, $21a34a464e7bc609$export$7ee701e290d9865)(key)) return this.process("normalize").set({
-            suffix: (0, $21a34a464e7bc609$export$ed9b06b5ee264ad3)($26f57998457eb2d4$var$normalizeSuffix(this.suffix))
+            suffix: suffix
         });
         return this.set({
+            suffix: suffix,
             root: this.root.normalizeEnharmonics(key),
-            suffix: (0, $21a34a464e7bc609$export$ed9b06b5ee264ad3)($26f57998457eb2d4$var$normalizeSuffix(this.suffix)),
             bass: this.bass ? this.bass.normalizeEnharmonics(this.root.toString()) : null
         });
     }
@@ -3373,11 +3377,13 @@ var $26f57998457eb2d4$export$2e2bcd8739ae039 = $26f57998457eb2d4$var$Chord;
             lyrics: lyrics
         });
     }
-    transpose(delta, key = null) {
+    transpose(delta, key = null, { normalizeChordSuffix: normalizeChordSuffix = false  } = {}) {
         const chordObj = (0, $26f57998457eb2d4$export$2e2bcd8739ae039).parse(this.chords);
         if (chordObj) {
             let transposedChord = chordObj.transpose(delta);
-            if (key) transposedChord = transposedChord.normalize(key);
+            if (key) transposedChord = transposedChord.normalize(key, {
+                normalizeSuffix: normalizeChordSuffix
+            });
             return this.set({
                 chords: transposedChord.toString()
             });
@@ -4140,8 +4146,10 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
    * - transpose the song key in {@link metadata}
    * - update any existing `key` directive
    * @param {number} delta The number of semitones (positive or negative) to transpose with
+   * @param {Object} [options={}] options
+   * @param {boolean} [options.normalizeChordSuffix=false] whether to normalize the chord suffixes after transposing
    * @returns {Song} The transposed song
-   */ transpose(delta) {
+   */ transpose(delta, { normalizeChordSuffix: normalizeChordSuffix = false  } = {}) {
         const wrappedKey = (0, $bff5407e03fdc8ee$export$2e2bcd8739ae039).wrap(this.key);
         let transposedKey = null;
         let song = this;
@@ -4150,7 +4158,9 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
             song = song.setKey(transposedKey);
         }
         return song.mapItems((item)=>{
-            if (item instanceof (0, $d454f4215ba01af2$export$2e2bcd8739ae039)) return item.transpose(delta, transposedKey);
+            if (item instanceof (0, $d454f4215ba01af2$export$2e2bcd8739ae039)) return item.transpose(delta, transposedKey, {
+                normalizeChordSuffix: normalizeChordSuffix
+            });
             return item;
         });
     }
@@ -4159,18 +4169,26 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
    * - transpose all chords, see: {@link Chord#transpose}
    * - transpose the song key in {@link metadata}
    * - update any existing `key` directive
+   * @param {Object} [options={}] options
+   * @param {boolean} [options.normalizeChordSuffix=false] whether to normalize the chord suffixes after transposing
    * @returns {Song} The transposed song
-   */ transposeUp() {
-        return this.transpose(1);
+   */ transposeUp({ normalizeChordSuffix: normalizeChordSuffix = false  } = {}) {
+        return this.transpose(1, {
+            normalizeChordSuffix: normalizeChordSuffix
+        });
     }
     /**
    * Transposes the song down by one semitone. It will:
    * - transpose all chords, see: {@link Chord#transpose}
    * - transpose the song key in {@link metadata}
    * - update any existing `key` directive
+   * @param {Object} [options={}] options
+   * @param {boolean} [options.normalizeChordSuffix=false] whether to normalize the chord suffixes after transposing
    * @returns {Song} The transposed song
-   */ transposeDown() {
-        return this.transpose(-1);
+   */ transposeDown({ normalizeChordSuffix: normalizeChordSuffix = false  } = {}) {
+        return this.transpose(-1, {
+            normalizeChordSuffix: normalizeChordSuffix
+        });
     }
     /**
    * Returns a copy of the song with the key set to the specified key. It changes: