chordsheetjs 7.1.0 → 7.2.0

package/README.md

@@ -639,6 +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)
     * [.changeKey(newKey)](#Song+changeKey) ⇒ [<code>Song</code>](#Song)
     * [.changeMetadata(name, value)](#Song+changeMetadata)
     * [.mapItems(func)](#Song+mapItems) ⇒ [<code>Song</code>](#Song)
@@ -697,7 +700,7 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 ### song.setKey(key) ⇒ [<code>Song</code>](#Song)
 <p>Returns a copy of the song with the key value set to the specified key. It changes:</p>
 <ul>
-<li>the value for <code>key</code> in the <code>metadata</code> set</li>
+<li>the value for <code>key</code> in the [metadata](metadata) set</li>
 <li>any existing <code>key</code> directive</li>
 </ul>
 
@@ -706,14 +709,14 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 
 | Param | Type | Description |
 | --- | --- | --- |
-| key | <code>number</code> \| <code>null</code> | <p>the key. Passing <code>null</code> will:</p> <ul> <li>remove the current key from <code>metadata</code></li> <li>remove any <code>key</code> directive</li> </ul> |
+| key | <code>number</code> \| <code>null</code> | <p>the key. Passing <code>null</code> will:</p> <ul> <li>remove the current key from [metadata](metadata)</li> <li>remove any <code>key</code> directive</li> </ul> |
 
 <a name="Song+setCapo"></a>
 
 ### song.setCapo(capo) ⇒ [<code>Song</code>](#Song)
 <p>Returns a copy of the song with the key value set to the specified capo. It changes:</p>
 <ul>
-<li>the value for <code>capo</code> in the <code>metadata</code> set</li>
+<li>the value for <code>capo</code> in the [metadata](metadata) set</li>
 <li>any existing <code>capo</code> directive</li>
 </ul>
 
@@ -722,14 +725,55 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 
 | Param | Type | Description |
 | --- | --- | --- |
-| capo | <code>number</code> \| <code>null</code> | <p>the capo. Passing <code>null</code> will:</p> <ul> <li>remove the current key from <code>metadata</code></li> <li>remove any <code>capo</code> directive</li> </ul> |
+| capo | <code>number</code> \| <code>null</code> | <p>the capo. Passing <code>null</code> will:</p> <ul> <li>remove the current key from [metadata](metadata)</li> <li>remove any <code>capo</code> directive</li> </ul> |
 
+<a name="Song+transpose"></a>
+
+### song.transpose(delta) ⇒ [<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>
+<li>transpose the song key in [metadata](metadata)</li>
+<li>update any existing <code>key</code> directive</li>
+</ul>
+
+**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> |
+
+<a name="Song+transposeUp"></a>
+
+### song.transposeUp() ⇒ [<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>
+<li>transpose the song key in [metadata](metadata)</li>
+<li>update any existing <code>key</code> directive</li>
+</ul>
+
+**Kind**: instance method of [<code>Song</code>](#Song)  
+**Returns**: [<code>Song</code>](#Song) - <p>The transposed song</p>  
+<a name="Song+transposeDown"></a>
+
+### song.transposeDown() ⇒ [<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>
+<li>transpose the song key in [metadata](metadata)</li>
+<li>update any existing <code>key</code> directive</li>
+</ul>
+
+**Kind**: instance method of [<code>Song</code>](#Song)  
+**Returns**: [<code>Song</code>](#Song) - <p>The transposed song</p>  
 <a name="Song+changeKey"></a>
 
 ### song.changeKey(newKey) ⇒ [<code>Song</code>](#Song)
 <p>Returns a copy of the song with the key set to the specified key. It changes:</p>
 <ul>
-<li>the value for <code>key</code> in the <code>metadata</code> set</li>
+<li>the value for <code>key</code> in the [metadata](metadata) set</li>
 <li>any existing <code>key</code> directive</li>
 <li>all chords, those are transposed according to the distance between the current and the new key</li>
 </ul>

package/lib/bundle.js

@@ -3376,11 +3376,15 @@ var $26f57998457eb2d4$export$2e2bcd8739ae039 = $26f57998457eb2d4$var$Chord;
             lyrics: lyrics
         });
     }
-    transpose(delta, key) {
+    transpose(delta, key = null) {
         const chordObj = (0, $26f57998457eb2d4$export$2e2bcd8739ae039).parse(this.chords);
-        if (chordObj) return this.set({
-            chords: chordObj.transpose(delta).normalize(key).toString()
-        });
+        if (chordObj) {
+            let transposedChord = chordObj.transpose(delta);
+            if (key) transposedChord = transposedChord.normalize(key);
+            return this.set({
+                chords: transposedChord.toString()
+            });
+        }
         return this.clone();
     }
 }
@@ -4107,21 +4111,21 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
     }
     /**
    * Returns a copy of the song with the key value set to the specified key. It changes:
-   * - the value for `key` in the `metadata` set
+   * - the value for `key` in the {@link metadata} set
    * - any existing `key` directive
    * @param {number|null} key the key. Passing `null` will:
-   * - remove the current key from `metadata`
+   * - remove the current key from {@link metadata}
    * - remove any `key` directive
    * @returns {Song} The changed song
    */ setKey(key) {
-        return this.changeMetadata((0, $5e9ede69210ec54a$export$7167c830cefcb6b5), key);
+        return this.changeMetadata((0, $5e9ede69210ec54a$export$7167c830cefcb6b5), key ? key.toString() : key);
     }
     /**
    * Returns a copy of the song with the key value set to the specified capo. It changes:
-   * - the value for `capo` in the `metadata` set
+   * - the value for `capo` in the {@link metadata} set
    * - any existing `capo` directive
    * @param {number|null} capo the capo. Passing `null` will:
-   * - remove the current key from `metadata`
+   * - remove the current key from {@link metadata}
    * - remove any `capo` directive
    * @returns {Song} The changed song
    */ setCapo(capo) {
@@ -4134,8 +4138,46 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
             }), (song)=>song.insertDirective(name, value));
     }
     /**
+   * Transposes the song by the specified delta. It will:
+   * - transpose all chords, see: {@link Chord#transpose}
+   * - 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
+   * @returns {Song} The transposed song
+   */ transpose(delta) {
+        const wrappedKey = (0, $bff5407e03fdc8ee$export$2e2bcd8739ae039).wrap(this.key);
+        let transposedKey = null;
+        let song = this;
+        if (wrappedKey) {
+            transposedKey = wrappedKey.transpose(delta);
+            song = song.setKey(transposedKey);
+        }
+        return song.mapItems((item)=>{
+            if (item instanceof (0, $d454f4215ba01af2$export$2e2bcd8739ae039)) return item.transpose(delta, transposedKey);
+            return item;
+        });
+    }
+    /**
+   * Transposes the song up by one semitone. It will:
+   * - transpose all chords, see: {@link Chord#transpose}
+   * - transpose the song key in {@link metadata}
+   * - update any existing `key` directive
+   * @returns {Song} The transposed song
+   */ transposeUp() {
+        return this.transpose(1);
+    }
+    /**
+   * 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
+   * @returns {Song} The transposed song
+   */ transposeDown() {
+        return this.transpose(-1);
+    }
+    /**
    * Returns a copy of the song with the key set to the specified key. It changes:
-   * - the value for `key` in the `metadata` set
+   * - the value for `key` in the {@link metadata} set
    * - any existing `key` directive
    * - all chords, those are transposed according to the distance between the current and the new key
    * @param {string} newKey The new key.
@@ -4149,7 +4191,7 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
             if (item instanceof (0, $d454f4215ba01af2$export$2e2bcd8739ae039)) return item.transpose(transpose, newKey);
             return item;
         });
-        updatedSong.metadata.set("key", newKey);
+        this.setKey(newKey);
         return updatedSong;
     }
     getTransposeDistance(newKey) {

package/lib/index.js

@@ -3375,11 +3375,15 @@ var $26f57998457eb2d4$export$2e2bcd8739ae039 = $26f57998457eb2d4$var$Chord;
             lyrics: lyrics
         });
     }
-    transpose(delta, key) {
+    transpose(delta, key = null) {
         const chordObj = (0, $26f57998457eb2d4$export$2e2bcd8739ae039).parse(this.chords);
-        if (chordObj) return this.set({
-            chords: chordObj.transpose(delta).normalize(key).toString()
-        });
+        if (chordObj) {
+            let transposedChord = chordObj.transpose(delta);
+            if (key) transposedChord = transposedChord.normalize(key);
+            return this.set({
+                chords: transposedChord.toString()
+            });
+        }
         return this.clone();
     }
 }
@@ -4106,21 +4110,21 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
     }
     /**
    * Returns a copy of the song with the key value set to the specified key. It changes:
-   * - the value for `key` in the `metadata` set
+   * - the value for `key` in the {@link metadata} set
    * - any existing `key` directive
    * @param {number|null} key the key. Passing `null` will:
-   * - remove the current key from `metadata`
+   * - remove the current key from {@link metadata}
    * - remove any `key` directive
    * @returns {Song} The changed song
    */ setKey(key) {
-        return this.changeMetadata((0, $5e9ede69210ec54a$export$7167c830cefcb6b5), key);
+        return this.changeMetadata((0, $5e9ede69210ec54a$export$7167c830cefcb6b5), key ? key.toString() : key);
     }
     /**
    * Returns a copy of the song with the key value set to the specified capo. It changes:
-   * - the value for `capo` in the `metadata` set
+   * - the value for `capo` in the {@link metadata} set
    * - any existing `capo` directive
    * @param {number|null} capo the capo. Passing `null` will:
-   * - remove the current key from `metadata`
+   * - remove the current key from {@link metadata}
    * - remove any `capo` directive
    * @returns {Song} The changed song
    */ setCapo(capo) {
@@ -4133,8 +4137,46 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
             }), (song)=>song.insertDirective(name, value));
     }
     /**
+   * Transposes the song by the specified delta. It will:
+   * - transpose all chords, see: {@link Chord#transpose}
+   * - 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
+   * @returns {Song} The transposed song
+   */ transpose(delta) {
+        const wrappedKey = (0, $bff5407e03fdc8ee$export$2e2bcd8739ae039).wrap(this.key);
+        let transposedKey = null;
+        let song = this;
+        if (wrappedKey) {
+            transposedKey = wrappedKey.transpose(delta);
+            song = song.setKey(transposedKey);
+        }
+        return song.mapItems((item)=>{
+            if (item instanceof (0, $d454f4215ba01af2$export$2e2bcd8739ae039)) return item.transpose(delta, transposedKey);
+            return item;
+        });
+    }
+    /**
+   * Transposes the song up by one semitone. It will:
+   * - transpose all chords, see: {@link Chord#transpose}
+   * - transpose the song key in {@link metadata}
+   * - update any existing `key` directive
+   * @returns {Song} The transposed song
+   */ transposeUp() {
+        return this.transpose(1);
+    }
+    /**
+   * 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
+   * @returns {Song} The transposed song
+   */ transposeDown() {
+        return this.transpose(-1);
+    }
+    /**
    * Returns a copy of the song with the key set to the specified key. It changes:
-   * - the value for `key` in the `metadata` set
+   * - the value for `key` in the {@link metadata} set
    * - any existing `key` directive
    * - all chords, those are transposed according to the distance between the current and the new key
    * @param {string} newKey The new key.
@@ -4148,7 +4190,7 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
             if (item instanceof (0, $d454f4215ba01af2$export$2e2bcd8739ae039)) return item.transpose(transpose, newKey);
             return item;
         });
-        updatedSong.metadata.set("key", newKey);
+        this.setKey(newKey);
         return updatedSong;
     }
     getTransposeDistance(newKey) {