doc + Masking

src/ArrayExtensions.ts

@@ -344,18 +344,36 @@ export const makeArrayExtensions = (api: UserAPI) => {
   Array.prototype.rand = Array.prototype.random;
 };
 
-Array.prototype.scale = function <T>(this: T[], scaleName: string = "major") {
+Array.prototype.scale = function <T>(this: T[], scaleName: string = "major", maskLength: number = 0) {
+
+    /**
+      * @param scale - the scale name
+      * @param mask - masking the scale array
+    */
 
     const scale = SCALES[scaleName];
+    let mask = maskLength;
 
     //input protect from unknow scale
     if (!scale) {
         throw new Error(`Unknown scale ${scaleName}`);
     }
 
+    //input protect from to long mask
+    if (mask > scale.length) {
+        mask = scale.length;
+        throw new Error(`Mask exceeds selected scale length`)
+    }
+
+    // default mask = scale length
+    if (mask == 0) {
+        mask = scale.length;
+    }
+    
+
     let result = [];
 
-    for (let j = 0; j < scale.length; j++) {
+    for (let j = 0; j < mask; j++) {
 
         for (let i = 0; i < this.length; i++) {
 

src/documentation/patterns.ts

@@ -183,7 +183,75 @@ ${makeExample(
 beat(1)::snd('sine').sustain(0.1).freq([100,100,100,100,200].unique().beat()).out()
 `,
   true
-)}
+  )}
+
+- <ic>scale(scale: string, mask: number)</ic>: extrapolate a custom-masked scale from each list elements. _[0].scale("major", 3)_ returns _[0,2,4]_
+
+${makeExample(
+    "Extrapolate a 3-elements Persian scale from 2 notes",
+    `
+beat(1) :: snd('gtr')
+    .note([0,5].scale("persian", 3).beat() + 50)
+    .out()
+`,
+    true
+  )}
+
+- Currently supported scales :
+| Scale name | Values                 |
+|------------|------------------------|
+|  major | 0, 2, 4, 5, 7, 9, 11
+|  naturalMinor | 0, 2, 3, 5, 7, 8, 10
+|  harmonicMinor | 0, 2, 3, 5, 7, 8, 11
+|  melodicMinor | 0, 2, 3, 5, 7, 9, 11
+|  dorian | 0, 2, 3, 5, 7, 9, 10 
+|  phrygian | 0, 1, 3, 5, 7, 8, 10
+|  lydian | 0, 2, 4, 6, 7, 9, 11
+|  mixolydian | 0, 2, 4, 5, 7, 9, 10
+|  aeolian | 0, 2, 3, 5, 7, 8, 10
+|  locrian | 0, 1, 3, 5, 6, 8, 10
+|  wholeTone | 0, 2, 4, 6, 8, 10
+|  majorPentatonic | 0, 2, 4, 7, 9
+|  minorPentatonic | 0, 3, 5, 7, 10
+|  chromatic | 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
+|  blues | 0, 3, 5, 6, 7, 10
+|  diminished | 0, 2, 3, 5, 6, 8, 9, 11
+|  neapolitanMinor | 0, 1, 3, 5, 7, 8, 11
+|  neapolitanMajor | 0, 1, 3, 5, 7, 9, 11
+|  enigmatic | 0, 1, 4, 6, 8, 10, 11],
+|  doubleHarmonic | 0, 1, 4, 5, 7, 8, 11
+|  octatonic | 0, 2, 3, 5, 6, 8, 9, 11
+|  bebopDominant | 0, 2, 4, 5, 7, 9, 10, 11
+|  bebopMajor | 0, 2, 4, 5, 7, 8, 9, 11
+|  bebopMinor | 0, 2, 3, 5, 7, 8, 9, 11
+|  bebopDorian | 0, 2, 3, 4, 5, 7, 9, 10
+|  harmonicMajor | 0, 2, 4, 5, 7, 8, 11
+|  hungarianMinor | 0, 2, 3, 6, 7, 8, 11
+|  hungarianMajor | 0, 3, 4, 6, 7, 9, 10
+|  oriental | 0, 1, 4, 5, 6, 9, 10
+|  romanianMinor | 0, 2, 3, 6, 7, 9, 10
+|  spanishGypsy | 0, 1, 4, 5, 7, 8, 10
+|  jewish | 0, 1, 4, 5, 7, 8, 10
+|  hindi | 0, 2, 4, 5, 7, 8, 10
+|  japanese | 0, 1, 5, 7, 8
+|  hirajoshi | 0, 2, 3, 7, 8
+|  kumoi | 0, 2, 3, 7, 9
+|  inSen | 0, 1, 5, 7, 10
+|  iwato | 0, 1, 5, 6, 10
+|  yo | 0, 2, 5, 7, 9
+|  minorBlues | 0, 3, 5, 6, 7, 10
+|  algerian | 0, 2, 3, 5, 6, 7, 8, 11
+|  augmented | 0, 3, 4, 7, 8, 11
+|  balinese | 0, 1, 3, 7, 8
+|  byzantine | 0, 1, 4, 5, 7, 8, 11
+|  chinese | 0, 4, 6, 7, 11
+|  egyptian |0, 2, 5, 7, 10
+|  eightToneSpanish | 0, 1, 3, 4, 5, 6, 8, 10
+|  hawaiian | 0, 2, 3, 5, 7, 9, 10
+|  hindustan | 0, 2, 4, 5, 7, 8, 10
+|  persian | 0, 1, 4, 5, 6, 8, 11
+|  eastIndianPurvi | 0, 1, 4, 6, 7, 8, 11
+|  orientalA | 0, 1, 4, 5, 6, 9, 10
 
 - <ic>add()</ic>: add a given amount to every list element.
 - <ic>sub()</ic>: add a given amount to every list element.