# SuperArray

`SuperArray<T>` is a tiny, typed wrapper around JavaScript’s native `Array`. It extends the built‑in array class and adds a handful of numeric helper methods that are used throughout the project.

## Why it exists

-   The original project needed a few handy numeric helpers (average, max/min, normalisation, etc.) that were used in many places. Instead of scattering those utilities, they live here.
-   It keeps type safety (`<T>`), while still behaving like a regular array (iterable, indexable, `push`, `pop`, …).

## Key features

| Method                                     | What it does                                                                                             |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `abs()`                                    | Returns a new `SuperArray` with the absolute value of each element.                                      |
| `avg()`                                    | Average of all numeric elements (`sum / length`).                                                        |
| `first()`                                  | First element (index 0).                                                                                 |
| `getClamped(index)`                        | Safely fetches an element; if out‑of‑bounds it returns the first or last element instead of `undefined`. |
| `indexOfMax()`                             | Index of the maximum value.                                                                              |
| `last()`                                   | Last element (`this[this.length-1]`).                                                                    |
| `max() / min()`                            | Highest/lowest numeric value in the array.                                                               |
| `normalize()`                              | Scales values to `[0, 1]` based on current min/max.                                                      |
| `shiftArrayMAD(shift, multiply, addArray)` | Applies a moving‑average‑like shift with optional scaling and an additive array.                         |
| `sum()`                                    | Sum of all elements.                                                                                     |
| `toFixed(a)`                               | Returns a new array where each number is rounded to _a_ decimal places.                                  |
| `unique()`                                 | Returns a new `SuperArray` containing only unique values (uses Lodash’s `uniq`).                         |

## Implementation notes

-   The class extends the native `Array`, so all standard array methods (`push`, `map`, `reduce`, etc.) are available.
-   A read‑only flag `_isSuperArray = true` is added for internal checks (e.g., in `shiftArrayMAD`).
-   Most numeric helpers assume the array holds numbers; they cast results to `number` for safety.

## Typical usage

```ts
const arr = new SuperArray(1, -2, 3);
console.log(arr.avg()); // 0.666...
console.log(arr.max()); // 3
console.log(arr.normalize()); // [0, 0.5, 1]
```