Observable state

Classes

ObservableState ⇐ Observable

ComputedState ⇐ ObservableState

Functions

computed(computeFn) ⇒ ComputedState

effect(effectFn) ⇒ function

This function sets up an effect that is run when the observable changes

ObservableState ⇐ Observable

Kind: global class
Extends: Observable

• ObservableState ⇐ Observable
  • new ObservableState(initialValue, subscriber, options)
  • .value() ⇒ any
  • .value(newValue)
  • .assign(obj)
  • .set(key, value)
  • .delete(key)
  • .clear()
  • .push(...elements)
  • .pop()
  • .shift()
  • .splice(start, deleteCount, ...items)
  • .unshift(...elements)
  • .reverse()
  • .sort([compareFunction])
  • .fill(value, [start], [end])
  • .copyWithin(target, start, [end])
  • .update(updater)
  • .toStream() ⇒ ObservableStream
  • .complete()

new ObservableState(initialValue, subscriber, options)

This class extends the Observable class and adds methods for updating the value of the observable.

Param	Type	Default	Description
initialValue	any		The initial value of the observable
subscriber	Subscriber		The subscriber to the observable
options	Object		Additional options for the observable
options.last	boolean		Whether the subscriber is the last observer

Example

import { ObservableState } from 'cami-js';
const observable = new ObservableState(10);
console.log(observable.value); // 10

observableState.value() ⇒ any

Kind: instance method of ObservableState
Returns: any - The current value of the observable
Example

const value = observable.value;

observableState.value(newValue)

This method sets a new value for the observable by calling the update method with the new value.

Kind: instance method of ObservableState

Param	Type	Description
newValue	any	The new value to set for the observable

Example

observable.value = 20;

observableState.assign(obj)

Merges properties from the provided object into the observable's value

Kind: instance method of ObservableState

Param	Type	Description
obj	Object	The object whose properties to merge

Example

observable.assign({ key: 'value' });

observableState.set(key, value)

Sets a new value for a specific key in the observable's value. If the key is nested, it should be provided as a string with keys separated by dots.

Kind: instance method of ObservableState
Throws:

• Will throw an error if the observable's value is not an object

Param	Type	Description
key	string	The key to set the new value for
value	any	The new value to set

Example

observable.set('key.subkey', 'new value');

observableState.delete(key)

Deletes a specific key from the observable's value. If the key is nested, it should be provided as a string with keys separated by dots.

Kind: instance method of ObservableState
Throws:

• Will throw an error if the observable's value is not an object

Param	Type	Description
key	string	The key to delete

Example

observable.delete('key.subkey');

observableState.clear()

Removes all key/value pairs from the observable's value

Kind: instance method of ObservableState
Example

observable.clear();

observableState.push(...elements)

Adds one or more elements to the end of the observable's value

Kind: instance method of ObservableState

Param	Type	Description
...elements	any	The elements to add

Example

observable.push(1, 2, 3);

observableState.pop()

Removes the last element from the observable's value

Kind: instance method of ObservableState
Example

observable.pop();

observableState.shift()

Removes the first element from the observable's value

Kind: instance method of ObservableState
Example

observable.shift();

observableState.splice(start, deleteCount, ...items)

Changes the contents of the observable's value by removing, replacing, or adding elements

Kind: instance method of ObservableState

Param	Type	Description
start	number	The index at which to start changing the array
deleteCount	number	The number of elements to remove
...items	any	The elements to add to the array

Example

observable.splice(0, 1, 'newElement');

observableState.unshift(...elements)

Adds one or more elements to the beginning of the observable's value

Kind: instance method of ObservableState

Param	Type	Description
...elements	any	The elements to add

Example

observable.unshift('newElement');

observableState.reverse()

Reverses the order of the elements in the observable's value

Kind: instance method of ObservableState
Example

observable.reverse();

observableState.sort([compareFunction])

Sorts the elements in the observable's value

Kind: instance method of ObservableState

Param	Type	Description
[compareFunction]	function	The function used to determine the order of the elements

Example

observable.sort((a, b) => a - b);

observableState.fill(value, [start], [end])

Changes all elements in the observable's value to a static value

Kind: instance method of ObservableState

Param	Type	Default	Description
value	any		The value to fill the array with
[start]	number	0	The index to start filling at
[end]	number	this.__value.length	The index to stop filling at

Example

observable.fill('newElement', 0, 2);

observableState.copyWithin(target, start, [end])

Shallow copies part of the observable's value to another location in the same array

Kind: instance method of ObservableState

Param	Type	Default	Description
target	number		The index to copy the elements to
start	number		The start index to begin copying elements from
[end]	number	this.__value.length	The end index to stop copying elements from

Example

observable.copyWithin(0, 1, 2);

observableState.update(updater)

This method adds the updater function to the pending updates queue. It uses a synchronous approach to schedule the updates, ensuring the whole state is consistent at each tick. This is done to batch multiple updates together and avoid unnecessary re-renders.

Kind: instance method of ObservableState

Param	Type	Description
updater	function	The function to update the value

Example

observable.update(value => value + 1);

observableState.toStream() ⇒ ObservableStream

Converts the ObservableState to an ObservableStream.

Kind: instance method of ObservableState
Returns: ObservableStream - The ObservableStream that emits the same values as the ObservableState.
Example

const stream = observable.toStream();

observableState.complete()

Calls the complete method of all observers.

Kind: instance method of ObservableState
Example

observable.complete();

ComputedState ⇐ ObservableState

Kind: global class
Extends: ObservableState

• ComputedState ⇐ ObservableState
  • new ComputedState(computeFn)
  • .value() ⇒ any
  • .dispose()
  • .assign(obj)
  • .set(key, value)
  • .delete(key)
  • .clear()
  • .push(...elements)
  • .pop()
  • .shift()
  • .splice(start, deleteCount, ...items)
  • .unshift(...elements)
  • .reverse()
  • .sort([compareFunction])
  • .fill(value, [start], [end])
  • .copyWithin(target, start, [end])
  • .update(updater)
  • .toStream() ⇒ ObservableStream
  • .complete()

new ComputedState(computeFn)

ComputedState class that extends ObservableState and holds additional methods for computed observables

Param	Type	Description
computeFn	function	The function to compute the value of the observable

Example

const computedState = new ComputedState(() => observable.value * 2);

computedState.value() ⇒ any

Kind: instance method of ComputedState
Overrides: value
Returns: any - The current value of the observable
Example

const value = computedState.value;

computedState.dispose()

Unsubscribes from all dependencies

Kind: instance method of ComputedState
Example

// Assuming `obs` is an instance of ObservableState
obs.dispose(); // This will unsubscribe obs from all its dependencies

computedState.assign(obj)

Merges properties from the provided object into the observable's value

Kind: instance method of ComputedState
Overrides: assign

Param	Type	Description
obj	Object	The object whose properties to merge

Example

observable.assign({ key: 'value' });

computedState.set(key, value)

Sets a new value for a specific key in the observable's value. If the key is nested, it should be provided as a string with keys separated by dots.

Kind: instance method of ComputedState
Overrides: set
Throws:

• Will throw an error if the observable's value is not an object

Param	Type	Description
key	string	The key to set the new value for
value	any	The new value to set

Example

observable.set('key.subkey', 'new value');

computedState.delete(key)

Deletes a specific key from the observable's value. If the key is nested, it should be provided as a string with keys separated by dots.

Kind: instance method of ComputedState
Overrides: delete
Throws:

• Will throw an error if the observable's value is not an object

Param	Type	Description
key	string	The key to delete

Example

observable.delete('key.subkey');

computedState.clear()

Removes all key/value pairs from the observable's value

Kind: instance method of ComputedState
Overrides: clear
Example

observable.clear();

computedState.push(...elements)

Adds one or more elements to the end of the observable's value

Kind: instance method of ComputedState
Overrides: push

Param	Type	Description
...elements	any	The elements to add

Example

observable.push(1, 2, 3);

computedState.pop()

Removes the last element from the observable's value

Kind: instance method of ComputedState
Overrides: pop
Example

observable.pop();

computedState.shift()

Removes the first element from the observable's value

Kind: instance method of ComputedState
Overrides: shift
Example

observable.shift();

computedState.splice(start, deleteCount, ...items)

Changes the contents of the observable's value by removing, replacing, or adding elements

Kind: instance method of ComputedState
Overrides: splice

Param	Type	Description
start	number	The index at which to start changing the array
deleteCount	number	The number of elements to remove
...items	any	The elements to add to the array

Example

observable.splice(0, 1, 'newElement');

computedState.unshift(...elements)

Adds one or more elements to the beginning of the observable's value

Kind: instance method of ComputedState
Overrides: unshift

Param	Type	Description
...elements	any	The elements to add

Example

observable.unshift('newElement');

computedState.reverse()

Reverses the order of the elements in the observable's value

Kind: instance method of ComputedState
Overrides: reverse
Example

observable.reverse();

computedState.sort([compareFunction])

Sorts the elements in the observable's value

Kind: instance method of ComputedState
Overrides: sort

Param	Type	Description
[compareFunction]	function	The function used to determine the order of the elements

Example

observable.sort((a, b) => a - b);

computedState.fill(value, [start], [end])

Changes all elements in the observable's value to a static value

Kind: instance method of ComputedState
Overrides: fill

Param	Type	Default	Description
value	any		The value to fill the array with
[start]	number	0	The index to start filling at
[end]	number	this.__value.length	The index to stop filling at

Example

observable.fill('newElement', 0, 2);

computedState.copyWithin(target, start, [end])

Shallow copies part of the observable's value to another location in the same array

Kind: instance method of ComputedState
Overrides: copyWithin

Param	Type	Default	Description
target	number		The index to copy the elements to
start	number		The start index to begin copying elements from
[end]	number	this.__value.length	The end index to stop copying elements from

Example

observable.copyWithin(0, 1, 2);

computedState.update(updater)

This method adds the updater function to the pending updates queue. It uses a synchronous approach to schedule the updates, ensuring the whole state is consistent at each tick. This is done to batch multiple updates together and avoid unnecessary re-renders.

Kind: instance method of ComputedState
Overrides: update

Param	Type	Description
updater	function	The function to update the value

Example

observable.update(value => value + 1);

computedState.toStream() ⇒ ObservableStream

Converts the ObservableState to an ObservableStream.

Kind: instance method of ComputedState
Overrides: toStream
Returns: ObservableStream - The ObservableStream that emits the same values as the ObservableState.
Example

const stream = observable.toStream();

computedState.complete()

Calls the complete method of all observers.

Kind: instance method of ComputedState
Overrides: complete
Example

observable.complete();

computed(computeFn) ⇒ ComputedState

Kind: global function
Returns: ComputedState - A new instance of ComputedState

Param	Type	Description
computeFn	function	The function to compute the value of the observable

Example

// Assuming `computeFn` is a function that computes the value of the observable
const computedValue = computed(computeFn);

effect(effectFn) ⇒ function

This function sets up an effect that is run when the observable changes

Kind: global function
Returns: function - A function that when called, unsubscribes from all dependencies and runs cleanup function

Param	Type	Description
effectFn	function	The function to call for the effect

Example

// Assuming `effectFn` is a function that is called when the observable changes
const effectFunction = effect(effectFn);

• effect(effectFn) ⇒ function
  • ~tracker
  • ~_runEffect()
  • ~dispose() ⇒ void

effect~tracker

The tracker object is used to keep track of dependencies for the effect function. It provides a method to add a dependency (an observable) to the dependencies set. If the observable is not already a dependency, it is added to the set and a subscription is created to run the effect function whenever the observable's value changes. This mechanism allows the effect function to respond to state changes in its dependencies.

Kind: inner constant of effect

effect~_runEffect()

The _runEffect function is responsible for running the effect function and managing its dependencies. Before the effect function is run, any cleanup from the previous run is performed and the current tracker is set to this tracker. This allows the effect function to add dependencies via the tracker while it is running. After the effect function has run, the current tracker is set back to null to prevent further dependencies from being added outside of the effect function. The effect function is expected to return a cleanup function, which is saved for the next run. The cleanup function, initially empty, is replaced by the one returned from effectFn (run by the observable) before each new run and on effect disposal.

Kind: inner method of effect

effect~dispose() ⇒ void

Unsubscribes from all dependencies and runs cleanup function

Kind: inner method of effect
Example

// Assuming `dispose` is the function returned by `effect`
dispose(); // This will unsubscribe from all dependencies and run cleanup function