# Immutability

ActiveJS [Units](/activejs/fundamentals/units.md) that store primitive values i.e. [BoolUnit](/activejs/fundamentals/units/boolunit.md), [NumUnit](/activejs/fundamentals/units/numunit.md), and [StringUnit](/activejs/fundamentals/units/stringunit.md) are automatically immutable because these Units deal with primitive values, and primitive values in JavaScript are immutable.

The [Units](/activejs/fundamentals/units.md) that store non-primitive values i.e. [DictUnit](/activejs/fundamentals/units/dictunit.md), [ListUnit](/activejs/fundamentals/units/listunit.md), and [GenericUnit](/activejs/fundamentals/units/genericunit.md) can be made immutable by just setting a configuration flag to `true`.

## Creating an immutable Unit

```typescript
const immutableDict = new DictUnit({immutable: true});
// we're done, it's immutable now
```

## Making all Units immutable

All the Units can be made immutable by default, by setting a flag in the global configuration.

```typescript
Configuration.set({
    UNITS: {immutable: true}
});
// all the Units initialized after this will be immutable,
// if not configured otherwise

const immutableList = new ListUnit(); // immutable

// override global config
const mutableList = new ListUnit({immutable: false}); // mutable
```

## Efficiency and precautions

Immutability brings a lot of benefits, such as predictability, and improving JS frameworks' rendering performance by avoiding the need for dirty checking, etc.

However, if not used correctly, there is a chance that you might run into performance bottlenecks.

Although ActiveJS takes most of these precautions on your behalf and tries to give the best experience and performance without any significant change in development practices and flow. There are still a few things that you might want to be aware of.

**When a Unit is immutable:**

1. Avoid using the static value access as much as you can, since the `value()` method creates a new copy every time you call it. Instead use Observable value, which is shared with all the observers.
2. Don't use the `value()` method directly in an Angular template, otherwise on every change detection there will be a new copy. Instead use the Units with `async` pipe.
3. Prefer using [ListUnit](/activejs/fundamentals/units/listunit.md) and [DictUnit](/activejs/fundamentals/units/dictunit.md) over [GenericUnit](/activejs/fundamentals/units/genericunit.md), and use methods like `set`, `get`, `findByProp`, etc. that do not create a copy on their invocation.
4. When dispatching a value using the `dispatch` method, you can mutate the value provided to the value-producer function, because it's a copy. And if you don't intend to use the current value to create a new value, just pass the new value directly so that the Unit doesn't waste a copy.
5. When you need to invoke a method like `find` which uses a predicate method to loop over stored items, if you can ensure that you won't mutate the value, you can invoke these methods on raw value instead, without creating a copy by using `Unit.rawValue()` e.g:`ListUnit.rawValue().find(item => item.name.startsWith('A'))`

In general, just try to avoid methods that create a new copy, and use alternative methods that do not. You can check this information in the documentation available within the library, or you can refer to [API reference](https://api.activejs.dev).

## Supported data types

It's advised to put only serializable data types in an immutable Unit, non-serializable data types like Map, Set, etc. are not cloned by ActiveJS. They will be left as is and will be shared by reference (i.e. will be mutable).

All the primitive data types like `boolean`, `number`, etc. are supported by default, along with `array` and simple `object` that can be cloned by ActiveJS, and hence can be guaranteed to be immutable.


---

# 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/guides/immutability.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.