()
useEffect(() => {
const subscription = unit.subscribe(setValue);
return () => subscription.unsubscribe();
}, [])
return {
value,
dispatch: bind(unit.dispatch, unit),
resetValue: bind(unit.resetValue, unit)
}
}
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
import { useState, useEffect } from 'react'
import { UnitBase } from '@activejs/core'
export const useUnit = (unit) => {
const [value, setValue] = useState()
useEffect(() => {
const subscription = unit.subscribe(setValue)
return () => subscription.unsubscribe()
}, []);
const dispatch = v => unit.dispatch(v)
const resetValue = () => unit.resetValue()
return {value, dispatch, resetValue}
}
```
{% endtab %}
{% endtabs %}
### Examples:
* See [this](https://docs.activejs.dev/integrations/react#2-counter-using-useunit-hook) for basic usage.
# Configuration
ActiveJS tries to give as many configuration options as possible to allow some degree of customization and personalization. While not requiring any configuration by choosing the most sensible defaults.
Configuration can be done on many levels, it can be done per instance and it can also be done globally.
## Inline / per-instance configuration
```typescript
// Unit configuration
const aUnit = new GenericUnit({cacheSize: 10, immutable: true, persistent: true})
// Action configuration
const anAction = new Action({initialValue: 'START'})
// AsyncSystem configuration
const anAsyncSystem = new AsyncSystem({
freezeQueryWhilePending: true,
// it overrides AsyncSystem's member Units' config
// it applies to all three GenericUnits and one BoolUnit
UNITS: {cacheSize: 3},
// it overrides common UNITS config above, applies to dataUnit only
DATA_UNIT: {cacheSize: 4}
})
```
## Global configuration
ActiveJS exposes a global class called [Configuration](https://api.activejs.dev/classes/configuration), through which you can set and reset global config that overrides default configuration. Which can still be overridden by inline config.
To set the global config you can use the `set` method, it accepts a configuration object of type [GlobalConfig](https://api.activejs.dev/interfaces/globalconfig).
```typescript
Configuration.set({
// it overrides default Action config
ACTION: {replay: true},
// it overrides default Unit config, for all Unit types
UNITS: {cacheSize: 1},
// it overrides global UNITS config above, for GenericUnits
GENERIC_UNIT: {cacheSize: 2},
ASYNC_SYSTEM: {
// it overrides global UNITS, GENERIC_UNIT, and BOOL_UNIT config
// it applies to AsyncSystem's three GenericUnits and one BoolUnit
UNITS: {cacheSize: 3},
// it overrides global ASYNC_SYSTEM.UNITS config above, for dataUnit
DATA_UNIT: {cacheSize: 4}
}
});
```
## Hierarchy of configuration
The more specific a configuration the higher precedence it has.
Given the global config type interface [GlobalConfig](https://api.activejs.dev/interfaces/globalconfig).\
This is how the precedence order works, going from lowest to highest precedence.
| Units | AsyncSystem | Action | Cluster |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------- | -------------------------- |
| **Default config** | **Default config** | **Default config** | **Default config** |
| GlobalConfig > **UNITS** | GlobalConfig > **ASYNC\_SYSTEM** | GlobalConfig > **ACTION** | GlobalConfig > **CLUSTER** |
| Type-specific Unit config e.g.
GlobalConfig > DICT\_UNIT
| **Inline config** | **Inline config** | **Inline config** |
| GlobalConfig > ASYNC\_SYSTEM > **UNITS** | | | |
| Unit specific config e.g.
GlobalConfig > ASYNC\_SYSTEM > UNITS > DATA\_UNIT
or
GlobalConfig > ASYNC\_SYSTEM > UNITS > QUERY\_UNIT
| | | |
| **Inline config** | | | |
## Notes
* In a Single Page App, you should set global configuration only once, and override it in the inline config if needed. Otherwise, it can become very difficult to keep track of which instances are using what configuration, depending on their time of creation.
* If you do need to change global configuration multiple times, just keep in mind that calling `Configuration.set` second time doesn't merge the new configuration with the old one it simply rewrites it. However, the defaults are not affected by this behavior, they have to be overridden specifically every time.
# Nesting
As we know, ActiveJS doesn't have a single store, it has **storage** [Units](/activejs/fundamentals/units), hence instead of creating slices, we create groups.
When you need to combine multiple storage Units (or even other ActiveJS constructs) you can do that using the [Cluster](/activejs/fundamentals/cluster), to build a nested data structure, instead of storing deeply nested values in the Units.
### Combining Multiple Units to create a Meaningful Cluster
To do proper nesting and to make sure that you use ActiveJS Units as intended, you should try to keep the values of the Units flat, *i.e.: as less nested as possible.*
This would allow you to have clear and granular control over the state of your App. Updating and accessing the stored values would be much easier and efficient as well. For example:
```typescript
// instead of doing this
const store = new DictUnit({initialValue: {
token: 'auth-token',
userProfile: {...},
userPreferences: {...}
}})
// do this
const tokenUnit = new StringUnit({initialValue: 'auth-token'})
const userProfileUnit = new DictUnit({initialValue: {...}})
const userPreferencesUnit = new DictUnit({initialValue: {...}})
const userDataCluster = new Cluster({
tokenUnit, userProfileUnit, userPreferencesUnit // using shorthand notation
})
```
### Accessing and Observing not so nested values of the Unit
Even if you followed the above advice and kept your Units flat you might still want to create an even finer chunk of the information. For that purpose, you can create a [Selection](/activejs/utilities/selection) from a Unit's value.
# Events
Every fundamental ActiveJS construct has a number of built-in Observable events. You can listen to these events by subscribing to the `events$` Observable, a property of every fundamental construct.
[Units](/activejs/fundamentals/units), [Systems](/activejs/fundamentals/systems), [Action](/activejs/fundamentals/action), and [Cluster](/activejs/fundamentals/cluster) have a common `EventReplay` event, it is triggered on a successful manual replay when you call the `replay()` method.
[Units](/activejs/fundamentals/units) have many Units specific events that let you tap into all the action that's happening on a Unit.\
Every Unit has some common events like `EventUnitDispatch`, `EventUnitDispatchFail` and`EventUnitFreeze` etc.
[ListUnit](/activejs/fundamentals/units/listunit) and [DictUnit](/activejs/fundamentals/units/dictunit) have even more events specific to them, like `EventDictUnitSet`, `EventListUnitPush` or `EventListUnitPop` etc.
See [API reference](https://api.activejs.dev/index.html#baseevents) for more details.
## Listening to events
```typescript
const theAction = new Action(); // can also be a Unit, System or Cluster
theAction.events$.subscribe(event => {
// Action, AsyncSystem and Cluster only have one event
// so filtering is optional
if(event instanceof EventReplay) {
console.log('hey, you got replayed');
}
});
// dispatch a value
theAction.dispatch('order order');
// this won't trigger any event, only Units emit an event on dispatch
// replay the value
theAction.replay(); // it'll trigger the EventReplay event
```
# Typings
ActiveJS is strictly typed, it does its best to infer and enforce as many typings as possible. \
However, where it can't infer a type, it uses generics so that you can pass a type.
For example, [Units](/activejs/fundamentals/units), [Systems](/activejs/fundamentals/systems), and [Action](/activejs/fundamentals/action) accept a type for their value.\
[Cluster](/activejs/fundamentals/cluster) doesn't need to be passed types, as it can infer the types from the provided members automatically.
## Units
[BoolUnit](/activejs/fundamentals/units/boolunit), [NumUnit](/activejs/fundamentals/units/numunit), and [StringUnit](/activejs/fundamentals/units/stringunit) don't accept a type because it's already implied as `boolean`, `number`, and `string`, respectively.
[ListUnit](/activejs/fundamentals/units/listunit)'s value already has an `array` type, but it can't know about the type of items that the array is going to contain. You can pass it at the time of instantiation.
```typescript
// a ListUnit whose value type would be string[]
const namesList = new ListUnit();
namesList.push('Mr. Anderson'); // works
namesList.dispatch(['Trinity', 'Morpheus']) // works
namesList.push(737); // linting error, invalid value
namesList.dispatch([737]) // linting error, invalid value
```
[DictUnit](/activejs/fundamentals/units/dictunit)'s value already has an `object` literal type, but it doesn't know the type of key-value pairs it's going to hold. You can pass it at the time of instantiation.
```typescript
// a DictUnit whose value type would be {[key in 'a' | 'b' | 'c']: number}
const someDict = new DictUnit<{[key in 'a' | 'b' | 'c']: number}>();
someDict.set('a', 1993) // works
someDict.dispatch({a: 1, b: 2, c: 3}) // works
someDict.set('b', 'not a number') // linting error, invalid value
someDict.set('d', 1993) // linting error, invalid key
someDict.dispatch({a: 1, b: 2}) // linting error, property 'c' is missing
```
[GenericUnit](/activejs/fundamentals/units/dictunit)'s value has an `any` type, it allows all types of values and leaves the typings to the developer. You can pass it at the time of instantiation.
```typescript
// a GenericUnit whose value type would be string | number | boolean
const primitivesUnit = new GenericUnit();
primitivesUnit.dispatch(42); // works
primitivesUnit.dispatch('HanuMan'); // works
primitivesUnit.dispatch(true); // works
primitivesUnit.dispatch(['you and I']) // linting error, invalid value
primitivesUnit.dispatch({youAreMine: true}) // linting error, invalid value
```
## Systems
[AsyncSystem](/activejs/fundamentals/systems/asyncsystem) doesn't have a value of its own, it derives value from its member Units, 3 of them are GenericUnits and 1 is BoolUnit. The three GenericUnits can be supplied types through AsyncSystem's generics.
```typescript
type UserQuery = number; // type for queryUnit's value
type UserData = string; // type for dataUnit's value
type UserError = {status: number, message: string}; // type for errorUnit's value
// pass the types to AsyncSystem
const userSystem = new AsyncSystem();
userSystem.queryUnit.dispatch(666) // works
userSystem.dataUnit.dispatch('evil string') // works
userSystem.errorUnit.dispatch({status: 418, message: "I'm a teapot"}) // works
userSystem.queryUnit.dispatch('not a number') // linting error, invalid value
userSystem.dataUnit.dispatch(420) // linting error, invalid value
userSystem.errorUnit.dispatch("I'm a teapot") // linting error, invalid value
```
[Custom AsyncSystem](/activejs/fundamentals/systems/custom-asyncsystem) doesn't need to be passed types explicitly, since it doesn't create Units itself, they are provided externally, and it can infer the types from the provided Units.
## Action
[Action](/activejs/fundamentals/action) has `any` as its default value type, it can be restricted by passing a specific type through generics.
```typescript
// an Action that will allow strings
const heroAction = new Action();
heroAction.dispatch('fight injustice') // works
heroAction.dispatch('defeat bullies') // works
heroAction.dispatch(['catch', 22]) // liniting error, invalid value
```
# Caching
By default all ActiveJS [Units](/activejs/fundamentals/units) cache 2 values, and can be configured with minimum `1` or maximum `Infinity` for as many values as possible.
The cache is maintained in an `array`, at the last index we have the latest value, and at 0 index we have the first value. So the cache might look like this `[initialValue, v1, v2, ... , lastDispatchedValue]`. When the length becomes more than the `cacheSize`, values are removed from the start.
The way cache-navigation methods work is that, when you call one of them, let's say `goBack`, the Unit will emit the previous value from the cache, without modifying the cached values, so that the cached values would still be the same and in the same order. Only that the `cacheIndex` would now be `cacheIndex - 1`
Now if you dispatch a new value, this new value will be inserted directly after the current `cacheIndex` and all the values coming after that will be removed from the cache. So that the new value would become the last value in the cache. That's exactly how browser history works, we can open links after links, then we can go back and we can go forward, but as soon as we open a new link, that link becomes the last point in history, and now we can only go back.
However, if you don't want that to happen you can do an in-place cache replace by passing `{replaceCache: true}` flag to the dispatch method. It'll replace the value in cache at the current `cacheIndex`, just like we'd do `History.replaceState()` in case of browser history.
```typescript
const unit = new StringUnit({initialValue: 'a'});
// cache is ['a']
unit.goBack(); // won't work, returns false
unit.goForward(); // won't work, returns false
unit.dispatch('b'); // cache becomes ['a', 'b']
console.log(unit.value()) // logs 'b'
unit.goBack(); // cache is still ['a', 'b']
console.log(unit.value()) // logs 'a'
unit.goForward(); // cache is still ['a', 'b']
console.log(unit.value()) // logs 'b'
unit.jumoToStart(); // cache is still ['a', 'b']
console.log(unit.value()) // logs 'a'
unit.dispatch('d', {replaceCache: true}) // now the cache becomes ['d', 'b']
// 'a' is gone, instead of 'b'
console.log(unit.value()) // logs 'd'
unit.jump(1) // cache is still ['d', 'b']
console.log(unit.value()) // logs 'b'
// we can also access all the cached values
console.log(unit.cachedValues()) // logs ['d', 'b']
// or check the current cache index
console.log(unit.cacheIndex) // logs 0
// or check the count of cached values
console.log(unit.cachedValuesCount) // logs 2
```
## Cache navigation and immutability
When you use cache navigation with Units that store non-primitive values i.e. [DictUnit](/activejs/fundamentals/units/dictunit), [ListUnit](/activejs/fundamentals/units/listunit), and [GenericUnit](/activejs/fundamentals/units/genericunit), you will need to make sure to not mutate the value, otherwise cached value will also get mutated and `goBack`, `goForward` or other cache-navigation methods wouldn't work as expected, because the cached values would have been mutated, which is not what you expect.
To mitigate this problem you can simply make the Unit immutable, which will ensure that the cached values stay unaffected. See [Immutability](/activejs/guides/immutability) for how immutability works in ActiveJS Units.
Otherwise, you have to ensure that every time you dispatch a value it shouldn't have any reference to the Unit's current value, and when you access the Unit's value, you should make sure to not mutate this value in any way.
# Persistence
ActiveJS [Units](/activejs/fundamentals/units) can be made persistent by setting a configuration flag to `true`. By default, persistent Units use [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) for the persistence. You can change it to any storage API that implements [`Storage`](https://developer.mozilla.org/en-US/docs/Web/API/Storage) interface. e.g.: [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
## Creating a persistent Unit
All that it takes to make a Unit persistent is a flag, and a unique `id`. The `id` is required to identify the Unit and its stored value.
```typescript
// this will throw an error, id is required
const preferencesUnit = new DictUnit({persistent: true});
// this will work
const preferencesUnit = new DictUnit({id: 'preferences', persistent: true});
// update Unit's value
preferencesUnit.set('side', 'dark');
// value in the LocalStorage would become {"side": "dark"}
// refresh the browser window
// check value
console.log(preferencesUnit.value()) // logs {"side": "dark"}
```
Voila! we're done. No manual saving, no manual retrieving.
## Initial value vs persisted value
When you provide an initial value to a persistent Unit, at first instance it gets saved to the persistent storage immediately, but when you refresh the browser window or open a new one, on the second instance the stored value takes precedence over the provided initial value.
```typescript
const preferencesUnit = new DictUnit({
id: 'preferences',
persistent: true,
initialValue: {earth: 'flat'}
});
// value in the LocalStorage would become {"earth": "flat"}
// set a new preference, which dispatches and saves a new value
preferencesUnit.set('earth', 'oblate ellipsoid');
// now LocalStorage has {"earth": "oblate ellipsoid"}
// now, refresh the browser window
// check value
console.log(preferencesUnit.value()) // logs {"earth": "oblate ellipsoid"}
// the initial value gets ignored
```
## Clearing the persisted value
Persisted value can be cleared in two ways, per Unit, or every Unit in a Storage instance.
* To clear the persisted value of a Unit, you can use `Unit.clearPersistedValue()`
* To clear all Units' persisted values from the default storage, you can use the global function `clearPersistentStorage()`.
* If you want to clear a particular storage you can pass it to the `clearPersistentStorage()` function.\
**e.g**. `clearPersistentStorage(window.sessionStorage)`
```typescript
// taking the Unit from above example, and starting from where we left
console.log(preferencesUnit.value()) // logs {"earth": "oblate ellipsoid"}
// clear the persisted value
preferencesUnit.clearPersistedValue();
// or clearPersistentStorage()
// or clearPersistentStorage(localStorage)
// check value
console.log(preferencesUnit.value()) // logs {"earth": "oblate ellipsoid"}
// because only the persisted value is removed, the Unit's value stays intact
// now, refresh the browser window
// check value
console.log(preferencesUnit.value()) // logs {"earth": "flat"}
// the initial value is used, because we cleared the persisted value
```
## Changing the persistence storage
All Units use the `localStorage` for persistence by default, but it can be changed to `sessionStorage` as well, and you can either change it globally or for a specific Unit.
### Changing storage for one Unit
```typescript
const unit = new DictUnit({
id: 'session-token',
persistent: true,
// this is how we can change the storage for a Unit
storage: window.sessionStorage
// it overrides the default/global storage configuration
});
```
### Changing default storage for every Unit
You can change the default Storage API used by ActiveJS Units through the global [Configuration](/activejs/guides/configuration).
```typescript
// set it in global configuration
Configuration.set({storage: window.sessionStorage})
// now all the persistent Units will use SessionStorage
// and the global clearPersistentStorage() will also operate on SessionStorage
```
{% hint style="danger" %}
Be advised that you should only change it once and that too before initializing any persistent Unit.\
Otherwise, some persistent Units will save their values in `LocalStorage` and try to restore it from `SessionStorage`. Also, the global function`clearPersistentStorage()` won't be able to clear persisted values from the other storage, you'll have to manually provide the non-current storage you want to clean up.
{% endhint %}
## Supported data types
It's advised to put only serializable data types in a persistent Unit, otherwise, the information will be lost in serialization done to save it in the LocalStorage. Non-serializable data types like Date, Map, Set, etc. are not supported.
All the data types that support `JSON.stringify` and `JSON.parse` can be used as values.
**Note:** `Date` object works with `JSON.stringify`, however it can't be parsed back to a `Date` object.\
When using the persisted value of the Unit, you'll only get a `string` representation of `Date`, not a `Date` `object`.
# Immutability
ActiveJS [Units](/activejs/fundamentals/units) that store primitive values i.e. [BoolUnit](/activejs/fundamentals/units/boolunit), [NumUnit](/activejs/fundamentals/units/numunit), and [StringUnit](/activejs/fundamentals/units/stringunit) are automatically immutable because these Units deal with primitive values, and primitive values in JavaScript are immutable.
The [Units](/activejs/fundamentals/units) that store non-primitive values i.e. [DictUnit](/activejs/fundamentals/units/dictunit), [ListUnit](/activejs/fundamentals/units/listunit), and [GenericUnit](/activejs/fundamentals/units/genericunit) 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) and [DictUnit](/activejs/fundamentals/units/dictunit) over [GenericUnit](/activejs/fundamentals/units/genericunit), 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.
# Freeze and Mute
Every ActiveJS [Unit](/activejs/fundamentals/units) comes with built-in capability to get frozen and muted, to stop the new data from getting dispatched, and to stop emitting any new data being dispatched, respectively.
In simple terms, freezing a Unit stops any incoming changes towards it, and muting the Unit stops any outgoing changes or events.
To understand it better let's look at them separately:
## Freeze / Unfreeze
If you know about [Object.freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze), then that's not what it is, but the end result is almost the same and the rationale is also very similar.
```typescript
const unit = new ListUnit(); // or any other Unit
// freeze
unit.freeze();
unit.dispatch([1, 2]); // would not work
// unfreeze
unit.unfreeze();
unit.dispatch([1, 2]); // would work
```
To freeze a Unit you just have to call `Unit.freeze()` and the Unit would stop responding to any call to `dispatch` method or any other method that will cause the Unit's value to change or make the Unit emit a value. This behavior can be useful when you're waiting for an event or task to complete and don't want the Unit to accept any values in that period, e.g.: when a form is being submitted.
When a Unit is frozen the following write-operations stop working:
* **All Units**: `dispatch`, `replay`, `goBack`, `goForward`, `jump`; and any other method that will cause the value to change or be emitted.
* **ListUnit:** `push`, `pop`, `set`, `splice`, `sort`, `reverse`; and any other method that will cause the value to change.
* **DictUnit:** `set`, `assign`, `delete`; and any other method that will cause the value to change.
But all the read-operations will keep working as usual, such as:
* **All Units:** accessing the `value`, `subscribing` to the Unit; or any other read-only operation
* **ListUnit:** methods such as `get`, `find`, `includes`, `slice`; or any other read-only operation
* **DictUnit:** methods such as `get`, `has`; or any other read-only operation
## Mute / Unmute
Muting a Unit is similar to muting a chat group in an instant messaging app, the conversation might still be ongoing it's just that you're not being notified anymore.
Similarly, when a Unit is muted, it still allows all the mutations and write operations as usual, unlike **freeze.** But it stops broadcasting those changes, what it means is that subscribers won't be notified if the value got changed or replayed. It also stops emitting events.
You can use this feature to disconnect a Unit from e.g.: triggering rendering updates or any other linked task, while still keeping the Unit up to date with any new data being dispatched to it, so that you can reconnect it later without losing any data updates.
```typescript
const unit = new ListUnit(); // or any other Unit
// mute
unit.mute();
// unmute
unit.unmute();
```
When a Unit is muted:
* Subscribing to the Unit will still provide an immediate value, but it'll be the value that was emitted just before the Unit got muted. Moreover, no new values will be provided until the Unit becomes unmuted.
* `createStream` will create a Stream but it'll do the same thing as above, only one value will be provided.
* Subscribing to the events will work but there won't be any events until the Unit becomes unmuted.
* `emitCount` will not change.
When a Unit gets unmuted after being muted:
* If the value changed while the Unit was muted, then on calling unmute, the latest value will be broadcasted immediately, to bring all the subscribers in sync with the Unit.
* If there was no change in value, there won't be an immediate emission.
# Development Environment
To help with development, and prevent some sneaky bugs that can be hard to debug, ActiveJS provides a few checks that you can enable in a development environment. You can configure them like this.
```typescript
Configuration.set({
checkUniqueId: true, // default is false
checkImmutability: true, // default is false
checkSerializability: true // default is false
})
```
ActiveJS provides the following checks:
* **`checkImmutability`** Enables immutability violation checks for all the ActiveJS constructs, it blocks any attempts of state mutation and throws an error with information about where the violation occurred.
* **`checkUniqueId`** Enables unique id checks across all the ActiveJS constructs, such that if any of the two ActiveJS instances have the same id, it'll throw an error.
* **`checkSerializability`** Enables serializability checks for Units and Actions, it'll throw an error if a non-serializable value is passed to an Action or Unit.
See [API reference](https://api.activejs.dev/interfaces/environmentconfig) for more details.
### Notes
* You should only use these checks in a development environment to avoid causing unwarranted errors in a production deployment.
* To automate this process you can use an environment variable provided by the framework of your choice, that identifies the development environment, and enable ActiveJS' production mode to disable all the checks.\
e.g.: in Angular it'd look like this
```typescript
// in the app.module.ts
if (environment.production) {
Configuration.enableProdMode();
}
```
# General Guidelines
ActiveJS doesn't concern itself with how or where it gets used, it's intended to be immersed in your development workflow and practices. It's just an improvement over already existing native data structures, and more powerful than a simple Observable or Subject.
The whole point of ActiveJS is to provide a non-intrusive and non-disruptive State Management solution that just fits in, without drawing too much attention to itself.
However, for the sake of having an official guideline, and to avoid some problems that we've identified, which you might run into at some point, you can follow this guideline.
## Don't mutate the state
To get predictable and reliable [cache navigation](/activejs/guides/caching), otherwise, you would get unexpected results.
To avoid view-rendering problems in your framework of choice. You might be expecting your framework to detect a change and render it, but since you mutated the value, the framework can't know whether there's a change or not.
To make things more predictable in general, since you can be sure that once you dispatch a value to a Unit, it's not going to change until you dispatch a new value again. Which can help avoid a lot of bugs.
{% hint style="info" %}
A simple solution to avoid mutating the state is to make your Units immutable. See [Immutability](/activejs/guides/immutability).
{% endhint %}
## Don't put non-serializable values in Units
For [persistent](/activejs/guides/persistence) Units, you should always make sure that the value of the Unit is serializable, otherwise, the information will be lost in serialization, which is done for storing the value into LocalStorage.
ActiveJS Units can only clone simple serializable objects, so if you're relying on [immutable](/activejs/guides/immutability) Units to provide a clone, that won't happen for non-serializable objects.
It's generally a good idea to not use non-serializable objects like Date, Map, Set, DOM-Element, etc. in your state for predictability and simplicity. However, if you are not using persistence, immutability or cache-navigation, in rare cases it's probably okay to do so, and ActiveJS shouldn't have a problem with it.
## Keep shared things in a separate file
To avoid cyclic dependencies while still having the freedom to pull in data from different files and services, you must put the shared [Units](/activejs/fundamentals/units), [Actions](/activejs/fundamentals/action), [Streams](/activejs/utilities/stream), [Systems](/activejs/fundamentals/systems), or [Clusters](/activejs/fundamentals/cluster) in a dedicated, shared file or service.
Keeping the [Streams](/activejs/utilities/stream) in a separate file alone will help avoid most of the possibilities of having a cyclic dependency. Since the Streams tend to interact with a lot of other instances of Units, Action, or Systems; keeping them in separate files will ensure that you don't import something into a file that has a Stream, which is importing something from the said file.
Try to keep the related [Units](/activejs/fundamentals/units), [Actions](/activejs/fundamentals/action), [Systems](/activejs/fundamentals/systems), or [Clusters](/activejs/fundamentals/cluster) as close as possible, to avoid fragmentation that's hard to keep track of. Keep the related [Streams](/activejs/utilities/stream) together as well, but as pointed out earlier, try to keep them away from [Units](/activejs/fundamentals/units), [Actions](/activejs/fundamentals/action), [Systems](/activejs/fundamentals/systems), or [Clusters](/activejs/fundamentals/cluster).
## Keep the streams simple
[Streams](/activejs/utilities/stream) are supposed to make complex things easy, but if a Stream starts to have too many dependencies or unrelated side-effects embedded into it, then it has the potential of making the Streams incomprehensible and hard to debug.
When you create a Stream on [AsyncSystem](/activejs/fundamentals/systems/asyncsystem) to populate its data, you should try to not have other unrelated side-effects in that Stream, try to keep it as simple as possible. If you need to have side-effects, you can create new Streams on [AsyncSystem](/activejs/fundamentals/systems/asyncsystem)'s Units e.g.: `dataUnit`, `errorUnit`
# Examples
1. [Counter (Vanilla JS)](https://stackblitz.com/edit/rxjs-daesrs?file=index.ts)
2. [Counter (React Hooks)](https://stackblitz.com/edit/react-ts-deakuh?file=index.tsx)
3. [Counter (React + useUnit Hook)](https://stackblitz.com/edit/react-ts-bf5mxu?file=index.tsx)
4. [TodoMVC (Angular)](https://activejs.dev/#/examples/todomvc)
5. [Typeahead (Angular)](https://activejs.dev/#/examples/typeahead)
6. [Typeahead (React + RxJS)](https://stackblitz.com/edit/react-ts-spn9ze?file=index.tsx)
7. [Typeahead (RxJS)](https://stackblitz.com/edit/typescript-r6zjrg?file=index.ts)
8. [Shared State (React)](https://stackblitz.com/edit/react-ts-aj1f8t?file=index.tsx)
# Articles
{% embed url="" %}
{% embed url="" %}
{% embed url="" %}
