# ListUnit

**ListUnit** is a type of [Unit](/activejs/fundamentals/units.md) 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)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.activejs.dev/activejs/fundamentals/units/listunit.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.