Add array utility tests (and support upsampling in resample)

See contained diff. 

The upsampling is important for Voice Messages, but is being done here because it's easier to add all the tests at once.

This also introduces a new Object utility - that will be tested on its own commit.

src/utils/arrays.ts

@@ -1,5 +1,5 @@
 /*
-Copyright 2020 The Matrix.org Foundation C.I.C.
+Copyright 2020, 2021 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -15,23 +15,47 @@ limitations under the License.
 */
 
 /**
- * Quickly resample an array to have less data points. This isn't a perfect representation,
- * though this does work best if given a large array to downsample to a much smaller array.
- * @param {number[]} input The input array to downsample.
+ * Quickly resample an array to have less/more data points. If an input which is larger
+ * than the desired size is provided, it will be downsampled. Similarly, if the input
+ * is smaller than the desired size then it will be upsampled.
+ * @param {number[]} input The input array to resample.
  * @param {number} points The number of samples to end up with.
- * @returns {number[]} The downsampled array.
+ * @returns {number[]} The resampled array.
  */
 export function arrayFastResample(input: number[], points: number): number[] {
-    // Heavily inpired by matrix-media-repo (used with permission)
+    if (input.length === points) return input; // short-circuit a complicated call
+
+    // Heavily inspired by matrix-media-repo (used with permission)
     // https://github.com/turt2live/matrix-media-repo/blob/abe72c87d2e29/util/util_audio/fastsample.go#L10
-    const everyNth = Math.round(input.length / points);
-    const samples: number[] = [];
-    for (let i = 0; i < input.length; i += everyNth) {
-        samples.push(input[i]);
+    let samples: number[] = [];
+    if (input.length > points) {
+        // Danger: this loop can cause out of memory conditions if the input is too small.
+        const everyNth = Math.round(input.length / points);
+        for (let i = 0; i < input.length; i += everyNth) {
+            samples.push(input[i]);
+        }
+    } else {
+        // Smaller inputs mean we have to spread the values over the desired length. We
+        // end up overshooting the target length in doing this, so we'll resample down
+        // before returning. This recursion is risky, but mathematically should not go
+        // further than 1 level deep.
+        const spreadFactor = Math.ceil(points / input.length);
+        for (const val of input) {
+            samples.push(...arraySeed(val, spreadFactor));
+        }
+        samples = arrayFastResample(samples, points);
     }
+
+    // Sanity fill, just in case
     while (samples.length < points) {
         samples.push(input[input.length - 1]);
     }
+
+    // Sanity trim, just in case
+    if (samples.length > points) {
+        samples = samples.slice(0, points);
+    }
+
     return samples;
 }
 
@@ -178,6 +202,13 @@ export class GroupedArray<K, T> {
     constructor(private val: Map<K, T[]>) {
     }
 
+    /**
+     * The value of this group, after all applicable alterations.
+     */
+    public get value(): Map<K, T[]> {
+        return this.val;
+    }
+
     /**
      * Orders the grouping into an array using the provided key order.
      * @param keyOrder The key order.