# ListUnit

**ListUnit** is a type of [Unit](https://docs.activejs.dev/activejs/fundamentals/units) that only accepts `array` data type as its value. It ensures that at any point of time the value would always be an `array`.

It's based on [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array). It implements all the [Array.prototype](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) methods available in the environment/browser, including polyfills. \
e.g.: `push`, `pop`, `join` and `toString`
 etc. to make working with the stored value a bit easier, when you call these methods they are called on the stored `array` value instead of ListUnit instance.

It also borrows some static methods from [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) like `values` and `entries`, and implements them as instance members `objectValues` and `objectEntries`, respectively. 

See [API reference](https://api.activejs.dev/classes/listunit) for more details.

|                 |         |
| --------------- | ------- |
| Default value   | `[]`    |
| Value data type | `array` |

### ListUnit vs `array`

ListUnit can not be used as a drop-in replacement for an `array`. You can not directly assign or access properties like `unit[index] = v` instead, you have to use `unit.set(index, v)` and `unit.get(index)`, respectively. See the below comparisons for more clarity.

Apart from that, all the non-mutating methods like `map`, `find`, `findIndex`, etc. work similar to as they would on an array. However mutating-methods have some differences, for one, every mutating method makes the Unit emit a new array instead of mutating the current value. 

Also, `forEach` method has been replaced with `forEvery`, because the extended `Observable` class already has a `forEach` method that is intended for something else entirely. See [API reference](http://localhost:8080/globals.html) for more details.

```typescript
// initialization
const arr = ['🐠']; // an array literal
const unit = new ListUnit({initialValue: ['🐠']}); // value is ['🐠']

arr === unit // false

arr instanceof Array // true
unit instanceof Array // false
Array.isArray(unit) // false

// setting an item
arr[1] = '🐞'
unit.set(1) = '🐞' // this is reactive, creates and dispatches a new array

// pushing an item
arr.push('🐊')
unit.push('🐊') // this is reactive, creates and dispatches a new array

// accessing an item at index 0
arr[0]
unit.get(0)
// or 
unit.first()

// removing an item at index 1
arr.splice(1, 1)
unit.splice(1, 1)
// or
unit.remove(1)
```