Freeze and Mute

Every ActiveJS Unit 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, then that's not what it is, but the end result is almost the same and the rationale is also very similar.

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.

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.