@bitfiber/rx - Reactive State and Async Workflow Management Library


@bitfiber/rx is a powerful and flexible library built on top of RxJS, designed to manage
reactive state, asynchronous workflows, and events in modern JavaScript applications.
It provides a structured approach to handling complex data flows using emitters, states, groups,
and stores, allowing seamless integration of various reactive sources like emitters, states,
and observables. Emitters and states can be organized into groups and stores, enabling efficient
management and lifecycle control of related reactive sources.

---

Key Components

1. Emitters
Emitters are the core units of communication in the library, broadcasting values or events
to multiple subscribers. They provide a straightforward mechanism for creating and managing
reactive streams, allowing you to easily handle data emissions and manage complex reactive flows.
Emitters can integrate with other reactive sources like emitters, states, and observables.


2. States
States are the primary data containers within the library, responsible for maintaining
and broadcasting data updates to multiple subscribers. Like emitters, states can create
and manage reactive streams to broadcast changes efficiently. They are designed to simplify
state propagation and synchronization across stores or features, ensuring consistency.
States can also integrate seamlessly with other reactive sources like emitters, states,
and observables.


3. Data sources
Data sources serve as external containers for persistent or external data, which can be
synchronized with states. They allow the connection of states to external data sources, ensuring
that state data is always up to date and aligned with external systems or storage.


4. Groups
Groups are collections of store items, including emitters, states, or even other groups,
and are used to implement the functionality of specific features. They help organize related
reactive sources into a cohesive structure, ensuring that all items are properly initialized
and completed as a unit.


5. Stores
Stores are the complete collections of store items and methods that manage the functionality
of an entire module or application. They can contain emitters, states, and groups, providing
an organized structure for managing related reactive sources, ensuring that all items are
properly initialized and completed as a unit.

---

Key Features

1. Integration with RxJS
Since @bitfiber/rx is built on top of RxJS, it integrates smoothly with the RxJS ecosystem.
Emitters and states can easily interact with observables and subjects, and can also create
effects using RxJS operators.


2. Stream Connections
Easily connects multiple emitters, states, and observables to each other.


3. Readable Code Structure
Produces clear, traceable code, making connections between emitters, states, and
observables easy to follow.


4. Automatic Subscription Management
Simplifies handling reactive streams, freeing you from managing manual subscriptions
and completions.


5. Synchronization with Data Sources
States can synchronize with data sources like local storage, cookies, and
other external data sources.


6. Strict Typing
The library leverages TypeScript to enforce strict typing, ensuring robust type checking
at compile time. This reduces the likelihood of runtime errors and enhances code reliability.
TypeScript's powerful type inference also makes it easier to write cleaner, more maintainable code,
providing developers with strong guarantees about the structure and behavior of their reactive
components.


7. Tree Shaking
The modular design of @bitfiber/rx enables tree shaking, allowing developers to optimize
bundle sizes by importing only the required functionalities. This eliminates unused code from
the final build, leading to smaller, more efficient applications, which is particularly useful
for performance-sensitive environments.

---

Installation

``bash

NPM

npm install @bitfiber/rx

YARN

yarn add @bitfiber/rx
`

---

Contributing

We welcome contributions from the community. Before contributing, please take the time to read
our contributing guide to familiarize yourself with our
contribution process.
This guide can help you understand our expectations and save you time in the long run.

---

Support

Have questions, encountered problems, or want to request new features?
Feel free to start a discussion in our community forum.
Your feedback is valuable to us!

---

Found an Issue or Bug?

If you've found a bug or issue, please report it using GitHub Issues.
Your reports help us improve the project for everyone.

---

Code of Conduct

This project adheres to the Code of Conduct to ensure
a welcoming and inclusive community for all participants.
By participating, you are expected to uphold this code.

---

License

This project is released under the Apache 2.0 License.
You can find the full text of the license in the LICENSE
file.
Copyright © 2023-2024 Oleksandr Zmanovskyi. All rights reserved.

---

Table of Contents

$3

* Store
* StoreHooks
* emitter
* Emitter
* state
* State
* changeDefaultComparison
* Comparison
* group
* Group
* namedGroup
* NamedGroup
* asyncGroup
* AsyncGroup
* transmit

$3

* localStorage
* LocalStorage
* localStoragePart
* LocalStoragePart
* sessionStorage
* SessionStorage
* sessionStoragePart
* SessionStoragePart
* memoryStorage
* MemoryStorage
* memoryStoragePart
* MemoryStoragePart
* cookie
* Cookie
* cookiePart
* CookiePart
* CookieParams
* CookieValue
* CookieData
* KeyValueSourcePart
* KeyValueSource
* DataSource

$3

* operator
* completeWith
* startWithDefined

---

Store

---

$3

Extends AbstractItem, implements the StoreHooks interface, and provides functionality
for managing store items such as emitters, states, and groups.

The
Store class handles the initialization and completion of these items, providing lifecycle hooks
that allow custom logic to be executed before and after key events such as store initialization
and completion. This class serves as a base for specific store implementations

@abstract

---

@method initialize(beforeInit?): this
Initializes the store and all of its items, preparing it for use. Optionally, a beforeInit
callback function can be provided, which will be executed before the store is initialized
@param beforeInit?: (store: this) => void - An optional callback function that runs before
the store is initialized
@returns this The current instance of the store, allowing for method chaining

---

@method complete(): void
Completes the store and all of its items, signaling that the store has finished
its operations and is now in a completed state. Once the store is completed,
no further changes or updates will be made to it or its items

---

@method markAsReady(): void
Marks the store as ready, indicating that all store items, such as emitters, states, and groups,
have been defined. This method must be called after all store items are defined!

Example:

`ts
import {switchMap} from 'rxjs';
import {pluck} from '@bitfiber/utils';
import {asyncGroup, emitter, state, Store, transmit} from '@bitfiber/rx';

interface ProductsFilters {
search: string;
page: number;
}

interface DictItem {
id: number;
name: string;
}

interface Product {
id: number;
name: string;
price: number;
}

interface ProductsState {
dict1: DictItem[];
dict2: DictItem[];
dict3: DictItem[];
products: Product[];
isLoading: boolean;
}

class ProductsStore extends Store {
// Provides the start of the first data loading process
start = emitter();

// Provides the state of the products filters
filters = state({search: '', page: 1})
// Will not emit data immediately upon subscription
.useLazyEmission();

// Provides a group of emitters for managing the loading process of dict1
dict1Req = asyncGroup(dict1Req => {
dict1Req.launch
// Receives new data from the start emitter
.receive(this.start)
// Receives new data from the filters state
.receive(this.filters)
// Performs the effect each time new data is received
.effect(
switchMap(filters => dict1Service.get(filters)
// 'transmit' operator takes either data or an error and transmits it to the success
// or fail emitter of the async group, respectively
.pipe(transmit(dict1Req))),
);
}, []);

// Provides a group of emitters for managing the loading process of dict2
dict2Req = asyncGroup(dict2Req => {
dict2Req.launch
// Receives new data from the start emitter
.receive(this.start)
// Receives new data from the filters state
.receive(this.filters)
// Performs the effect each time new data is received
.effect(
switchMap(filters => dict2Service.get(filters)
// 'transmit' operator takes either data or an error and transmits it to the success
// or fail emitter of the async group, respectively
.pipe(transmit(dict2Req))),
);
}, []);

// Provides a group of emitters for managing the loading process of dict3
dict3Req = asyncGroup<[string[], string[]], DictItem[], Error>(dict3Req => {
dict3Req.launch
// Receives new data from the dict1Req group and dict2Req group
.zip(this.dict1Req.success, this.dict2Req.success, (dict1, dict2) => {
return [pluck(dict1, 'id'), pluck(dict2, 'id')];
})
// Performs the effect each time new data is received
.effect(
switchMap(data => dict3Service.get(data)
// 'transmit' operator takes either data or an error and transmits it to the success
// or fail emitter of the async group, respectively
.pipe(transmit(dict3Req))),
);
}, []);

// Provides a group of emitters for managing the loading process of products
productsReq = asyncGroup((productsReq, {launch}) => {
launch
// Receives new data from the dict3Req group
.receive(this.dict3Req.success, () => this.filters())
// Performs the effect each time new data is received
.effect(
switchMap(filters => productsService.get(filters)
// 'transmit' operator takes either data or an error and transmits it to the success
// or fail emitter of the async group, respectively
.pipe(transmit(productsReq))),
);
}, []);

// Provides the final state of the store data
data = state(
// Will emit initial data to all subscribers upon subscription
{dict1: [], dict2: [], dict3: [], products: [], isLoading: false},
data => data
// Updates the isLoading flag whenever any of the query states change
.select(
this.dict1Req.state,
this.dict2Req.state,
this.dict3Req.state,
this.productsReq.state,
(dict1State, dict2State, dict3State, productsState) => {
return {
...data(),
isLoading: dict1State.inProgress || dict2State.inProgress
|| dict3State.inProgress || productsState.inProgress,
};
},
)
// Updates the store data every time all success data is received from the query success emitters
.zip(
this.dict1Req.success,
this.dict2Req.success,
this.dict3Req.success,
this.productsReq.success,
(dict1, dict2, dict3, products) => {
return {...data(), dict1, dict2, dict3, products};
},
),
);

// Provides the store error handling
error = emitter(error => error
// Receives all errors from all async tasks
.receive(this.dict1Req.fail, this.dict2Req.fail, this.dict3Req.fail, this.productsReq.fail)
// Performs the tap callback each time new error is received
.tap(error => {
// Performs some error handling logic
}));

// Marks the store as ready, indicating that all store items, such as emitters, states,
// and groups, have been defined
#ready = this.markAsReady();
}

// Creates a new store for managing products
const productsStore = new ProductsStore();

// Initializes the store and all items within the store
productsStore.initialize();

productsStore.data
// Performs a tap callback each time data is updated
.tap(data => {
console.log(productsStore.data());
});

// Starts the first data loading process
productsStore.start.emit(productsStore.filters());

setTimeout(() => {
// Changes the filters applied to the products
productsStore.filters.update((state) => ({...state, page: 2}));
}, 150);

setTimeout(() => {
// Completes the store and all items within the store
productsStore.complete();
}, 300);
`

---

$3

Represents optional hooks for Store that can be implemented to perform
actions before and after the store is initialized and completed

beforeStoreInit?(): void
An optional hook that runs before the store is initialized

afterStoreInit?(): void
An optional hook that runs after the store has been initialized

beforeStoreComplete?(): void
An optional hook that runs before the store is completed

afterStoreComplete?(): void
An optional hook that runs after the store has been completed

---

$3

Creates and returns a new Emitter instance in a convenient way that provides functionality
to create streams, handle subscriptions, emit values to subscribers, and integrate with
other reactive sources such as emitters, states, subjects, observables.

You can optionally provide an onInit callback that will be invoked just before
the emitter's initialization, allowing you to perform setup tasks or configure the emitter
before it starts emitting values

@template T - The type of data emitted by this emitter

@param onInit?: (emitter: Emitter) => void - An optional callback function that is called with the
newly created Emitter instance just before its initialization.
This function can be used to set up or configure the emitter

@returns Emitter

Example:

`ts
import {emitter, namedGroup} from '@bitfiber/rx';
import {take, filter, switchMap} from 'rxjs';

// Creates an emitter that emits the IDs
const currentId = emitter(e => e
// Transmits all emitted data to the 'productReq' emitter
.transmit(productReq));

// The observable of the emitter
const currentId$ = currentId.$;

// Creates an emitter that emits the final ID
const lastId = emitter();

// Creates an emitter that receives transmitted 'currentId' data and performs an effect that calls an API
const productReq = emitter(e => e
// All streams created by this emitter will filter the data
.manage(
filter(id => !!(id % 2)),
)
// Performs a tap callback each time the emitter emits new filtered data
.tap(id => {
console.log(id);
})
// Performs a effect each time the emitter emits new filtered data
.effect(
switchMap(id => productsService.get(api/product${id})),
));

// Creates an emitter that receives used IDs and logs them through an effect
const log = emitter(e => e
// Runs an effect when data is received from the currentId emitter
.receive(currentId, id => A new id ${id} was received)
// Runs an effect when data is received from the lastId emitter
.receive(lastId, id => the last id ${id} was received)
// Performs an effect each time the emitter emits newly received logged data
.effect(
switchMap(log => logService.post(api/log, {log})),
));

// Creates an emitter that performs a tap callback each time data is selected
const result1 = emitter<[number, number]>(e => e
// Runs a tap callback when all data is selected from the currentId and lastId emitters
.select(currentId$, lastId, (currentId, lastId) => [currentId, lastId])
// Performs a tap callback each time the emitter emits new data
.tap(range => {
console.log(range);
}));

// Creates an emitter that performs a tap callback each time data is zipped
const result2 = emitter<[number, number]>(e => e
// Runs a tap callback when all data is zipped from the currentId and lastId emitters
.zip(currentId$, lastId, (currentId, lastId) => [currentId, lastId])
// Performs a tap callback each time the emitter emits new data
.tap(range => {
console.log(range);
}));

// Creates an emitter that emits the timestamp of the last received ID
const lastIdTime = emitter(e => e
// Waits for the first value from the lastId emitter, then completes the stream
.wait(lastId, lastId => new Date().getTime()));

// Groups all emitters and states for mass initialization and completion
const group = namedGroup({currentId, lastId, productReq, log, result1, result2});

// Subscribe to the observable of the emitter
currentId$
.pipe(take(1))
.subscribe(id => {
console.log(id);
});

// Initializes the group and all items within the group
group.initialize();

// Emits data
currentId.emit(1);
currentId.emit(2);

// Accesses the 'lastId' emitter through the group
group.lastId.emit(3);

// Completes the group and all items within the group
group.complete();

`

---

$3

Extends the AbstractEmitter class and provides functionality to create streams,
handle subscriptions, emit values to subscribers, and integrate with other reactive sources
such as emitters, states, subjects, observables.

The Emitter class is typically used when you need a straightforward emitter that can
broadcast values or events to all its subscribers or other reactive sources, such as emitters,
states, subjects

@template T - The type of data emitted by this emitter

---

@property $: Observable
An observable that serves as the source for all emitter streams.
It allows subscribers to listen to and react to emitted values or events

---

@method manage(...operators): this
Defines management operators for all emitter streams.
These operators are applied to the streams managed by this emitter,
allowing you to modify or control their behavior, such as filtering,
mapping, or handling errors, without altering the type of the emitted values

@param ...operators: OperatorFunction[] - One or more RxJS operators to apply to the emitter streams

@returns this the instance of the current emitter, allowing for method chaining

`ts
import {emitter} from '@bitfiber/rx';
import {delay, filter} from 'rxjs';

const launch = emitter(e => e
// All streams created by this emitter will delay and filter the data
.manage(
filter(id => !!(id % 2)),
delay(100),
));

`

---

@method emit(value): this
Emits the specified value to all subscribers currently listening to the emitter.
It is used to trigger reactive updates or actions in response to the emitted value

@param value: T - The value to be emitted to all subscribers

@returns this the instance of the current emitter, allowing for method chaining

`ts
import {emitter} from '@bitfiber/rx';

const launch = emitter();

// Emits a value to its subscribers, linked reactive sources, and triggers its own taps and effects
launch.emit(7);

`

---

@method select(...data): this
Combines values from multiple emitters, states, or observables, applies a reducer function to
these values, and emits the resulting value to all subscribers of this emitter.

The first emission occurs only after all values have been received from the sources,
ensuring that the reducer function operates on a complete set of inputs.
Subsequent emissions occur whenever any of the sources emit a new value,
triggering the reducer function to recompute the result based on the latest values.
Works similarly to the RxJs 'combineLatest' operator

@param ...data: [...EmitterOrObservableTuple, SpreadFn] - A spread of emitters, states,
or observables, followed by a reducer function. The reducer function takes the latest values
from each source as arguments and returns the value to be emitted

@returns this the instance of the current emitter, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';
import {of} from 'rxjs';

type Result = {launchId: number; data: string; count: number};

const launch = emitter();
const data = state(1);
const count$ = of(1);

const result = emitter(e => e
// Selects data from all reactive sources and emits the result to its subscribers.
// Works similarly to the RxJs 'combineLatest' operator
.select(launch, data, count$, (launchId, data, count) => {
launchId, data, count
}));
`

---

@method zip(...data): this
Combines values from multiple emitters, states, or observables, applies a reducer function to
these values, and emits the resulting value to all subscribers of this emitter.

The first emission occurs only after all values have been received from the sources,
ensuring that the reducer function operates on a complete set of inputs.
Subsequent emissions occur only when all sources emit new values,
triggering the reducer function to recompute the result based on the latest values.
Works similarly to the RxJs 'zip' operator

@param ...data: [...EmitterOrObservableTuple, SpreadFn] - A spread of emitters, states,
or observables, followed by a reducer function. The reducer function takes the latest values
from each source as arguments and returns the value to be emitted

@returns this the instance of the current emitter, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';
import {of} from 'rxjs';

type Result = {launchId: number; data: string; count: number};

const launch = emitter();
const data = state(1);
const count$ = of(1);

const result = emitter(e => e
// Selects data from all reactive sources and emits the result to its subscribers.
// Works similarly to the RxJs 'zip' operator
.zip(launch, data, count$, (launchId, data, count) => {
launchId, data, count
}));
`

---

wait(...data): this
Waits for the first values from multiple emitters, states, or observables, applies a reducer
function to these values, emits the resulting value to all subscribers of this emitter,
and completes the stream

@param ...data: [...EmitterOrObservableTuple, SpreadFn] - A spread of emitters, states,
or observables, followed by a reducer function. The reducer function takes the first values from
each source as arguments and returns the value to be emitted

@returns this the instance of the current emitter, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';
import {of} from 'rxjs';

const launch = emitter();
const data = state(1);
const count$ = of(1);

const result = emitter(e => e
// Waits the first values from all reactive sources, emits the reducer function value to
// the emitter subscribers, and completes the stream
.wait(launch, data, count$, (launch, data, count) => count));
`

---

@method receive(...inputs): this
Receives values from one or more emitters, states, or observables
and emits them to all subscribers of this emitter.

This method allows the current emitter to listen to external sources and relay their
emitted values to its own subscribers, effectively linking multiple data streams together

@param ...inputs: EmitterOrObservable[] - One or more emitters, states,
or observables that provide values to be emitted by this emitter

@returns the instance of the current emitter, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';
import {of} from 'rxjs';

const source1 = emitter();
const source2 = state(1);
const source3$ = of(1);

const result = emitter(e => e
// Receives data from each reactive source separately and emits a value to its subscribers
// immediately, without waiting for other sources to emit
.receive(source1, source2, source3$));
`

@method receive(input, reducer): this
Receives a value from an emitter, state, or observable, applies a reducer function to convert
this value to the emitter's type, and emits the result to all subscribers of this emitter.

This method allows the current emitter to listen to external source and relay the transformed
emitted value to its own subscribers, effectively linking data streams together

@param input: EmitterOrObservable - an emitter, state or observable
that provide values to be emitted by this emitter

@param reducer: (value: I) => T - A function that converts the received value from its original type
to the type expected by this emitter, allowing for customization of the emitted value

@returns the instance of the current emitter, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';

const source = state(1);

const result = emitter(e => e
// Receives data from a reactive source, converts the value, and emits the result to its subscribers
.receive(source, value => String(value)));
`

---

@method transmit(...outputs): this
Transmits values from the current emitter to one or more other emitters, states, or subjects.
It enables the propagation of data or events across multiple sources, effectively creating
a network of interconnected reactive sources

@param ...outputs: (EmitterOrSubject | EmitterOrSubject)[] - One or more emitters, states,
or subjects that will receive the transmitted values from this emitter

@returns the instance of the current emitter, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';
import {Subject} from 'rxjs';

const receiver1 = emitter();
const receiver2 = state(0);
const receiver3 = new Subject();

const source = emitter(e => e
// Transmits every emitted value to all reactive sources for further processing or handling
.transmit(receiver1, receiver2, receiver3));
`

@method transmit(output, reducer): this
Transmits values from the current emitter to a state. By using a reducer function,
the emitted values can be transformed or customized to match the expected format of the state

@param output: AbstractState - A state that will receive the transmitted values from this emitter

@param reducer: (value: T, state: O) => O - A function that converts or transforms the emitted value
from the emitter type to the type expected by the state

@returns the instance of the current emitter, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';

const receiver = state(0);

const source = emitter(e => e
// Transmits every emitted value to a state for further processing or handling
.transmit(receiver, (value, state) => state + Number(value)));
`

@method transmit(output, reducer): this
Transmits values from the current emitter to another emitter or subject.
By using a reducer function, the emitted values can be transformed or customized to match
the expected format of the target emitter or subject

@param output: EmitterOrSubject - An emitter or subject that will receive the transmitted values
from this emitter

@param reducer: (value: T) => O - A function that converts or transforms the emitted value from
the current emitter's type to the type expected by the receiving emitter or subject

@returns the instance of the current emitter, allowing for method chaining

`ts
import {emitter} from '@bitfiber/rx';

const receiver = emitter();

const source = emitter(e => e
// Transmits every emitted value to another emitter for further processing or handling
.transmit(receiver, value => Number(value)));
`

---

@method effect(...operators): this
Creates a new stream with a side effect, similar to the RxJS pipe method.

This method allows you to apply a sequence of RxJS operators to the emitter's stream,
performing actions or side effects whenever the emitter emits a value. This can be
particularly useful for tasks like logging, debugging, or triggering external operations
in response to emitted values

@param ...operators: OperatorFunction[] - A sequence of RxJS operators that define
the side effects to be applied to the emitted values

@returns the instance of the current emitter, allowing for method chaining

`ts
import {emitter} from '@bitfiber/rx';
import {switchMap} from 'rxjs';

const launchProductReq = emitter(e => e
// Performs a effect each time the emitter emits new value
.effect(
switchMap(id => productsService.get(api/product${id})),
));
`

---

@method tap(observer): this
Creates a new stream with a side effect, similar to the RxJS tap operator.

This method allows you to perform actions or side effects whenever the emitter emits a value,
without altering the value itself. It is useful for tasks like logging, debugging,
or triggering external operations in response to emitted values

@param observer: Partial> - a partial observer with lifecycle
methods (next, error, complete)

@returns the instance of the current emitter, allowing for method chaining

`ts
import {emitter} from '@bitfiber/rx';
import {switchMap} from 'rxjs';

const log = emitter(e => e
// Performs a tap callback each time the emitter emits new data
.tap({
next: id => console.log(id),
error: error => console.log(error),
}));
`

@method tap(next): this
Creates a new stream with a side effect, similar to the RxJS tap operator.

This method allows you to perform actions or side effects whenever the emitter emits a value,
without altering the value itself. It is useful for tasks like logging, debugging,
or triggering external operations in response to emitted values

@param next: (value: T) => void - a function that takes the emitted value and performs a side effect

@returns the instance of the current emitter, allowing for method chaining

`ts
import {emitter} from '@bitfiber/rx';
import {switchMap} from 'rxjs';

const log = emitter(e => e
// Performs a tap callback each time the emitter emits new data
.tap(id => console.log(id)));
`

---

$3

Creates an instance that combines the functionality of both the State class
and the StateGetter function, initialized with the provided initialValue.
Optionally, you can provide an onInit callback function, which is called just before
the initialization process, allowing you to perform setup tasks or configure the state before
it starts emitting values

@template T - The type of the state value

@param initialValue: T - The initial value of the state

@param onInit?: (state: StateType) => void - An optional callback function
that is executed just before the initialization of the state, allowing you to perform setup tasks
or configure the state before it starts emitting values

@returns StateType a new State instance that also acts as the StateGetter function
to get the current state value

Example:

`ts
import {state, namedGroup} from '@bitfiber/rx';
import {take, filter, switchMap} from 'rxjs';

// Creates a state that stores and emits the IDs
const currentId = state(1, s => s
// Uses a custom function for comparing values. By default, the 'equals' function is used
.compareBy((a, b) => a === b)
// Transmits all emitted data to the 'productReq' emitter
.transmit(productReq));

// The observable of the state
const currentId$ = currentId.$;

// Creates a state that stores and emits the final ID
const lastId = state(null, s => s
// Uses '===' for comparing values. By default, the 'equals' function is used
.compareBy('strict')
// Forces the state not to emit a value at the time of subscription
.useLazyEmission());

// Creates a state that receives transmitted 'currentId' data and performs an effect that calls an API
const productReq = state(0, s => s
// All streams created by this state will filter the data
.manage(
filter(id => !!(id % 2)),
)
// Performs a tap callback each time the state emits new filtered data
.tap(id => {
console.log(id);
})
// Performs a effect each time the state emits new filtered data
.effect(
switchMap(id => productsService.get(api/product${id})),
));

// Creates a state that receives used IDs and logs them through an effect
const log = state(0, s => s
// Runs an effect when data is received from the currentId state
.receive(currentId, id => A new id ${id} was received)
// Runs an effect when data is received from the lastId state
.receive(lastId, id => the last id ${id} was received)
// Performs an effect each time the state emits newly received logged data
.effect(
switchMap(log => logService.post(api/log, {log})),
));

// Creates a state that performs a tap callback each time data is selected
const result1 = state<[number, number]>([0, 0], s => s
// Runs a tap callback when all data is selected from the currentId and lastId states
.select(currentId$, lastId, (currentId, lastId) => [currentId, lastId])
// Performs a tap callback each time the state emits new data
.tap(range => {
console.log(range);
}));

// Creates a state that performs a tap callback each time data is selected
const result2 = state<[number, number]>([0, 0], s => s
// Runs a tap callback when all data is selected from the currentId and lastId states
.zip(currentId$, lastId, (currentId, lastId) => [currentId, lastId])
// Performs a tap callback each time the state emits new data
.tap(range => {
console.log(range);
}));

// Creates a state that records the timestamp of the last received ID
const lastIdTime = state(null, s => s
// Waits for the first value from the lastId state, then completes the stream
.wait(lastId, lastId => new Date().getTime()));

// Groups all emitters and states for mass initialization and completion
const group = namedGroup({currentId, lastId, productReq, log, result1, result2});

// Initializes the group and all items within the group
group.initialize();

// Subscribes to the observable of the state
currentId$
.pipe(take(1))
.subscribe(id => console.log(id));

// Sets the state value and emits the new value to subscribers
currentId.set(2);

// Updates the state value and emits the new value to subscribers
currentId.update(state => state + 1);

// Accesses the 'lastId' state through the group and sets data
group.lastId.set(4);

// Gets the current state value in two ways
const id1 = currentId();
const id2 = currentId.get();

// Completes the group and all items within the group
group.complete();

`

---

$3

Represents a concrete state in a reactive store, extending the functionality of AbstractState.
This class encapsulates the logic for updating, resetting and maintaining a state,
reacting to changes, and notifying subscribers whenever the state is updated.
It can also be connected to external data sources to synchronize its value with external data,
ensuring consistency across different parts of an application

@template T - The type of data managed and emitted by the state

---

@property $: Observable
An observable that serves as the source for all state streams.
It allows subscribers to reactively observe changes or updates to the state, allowing them to
respond dynamically as new values are emitted

---

@method manage(...operators): this
Defines management operators for all state streams.
These operators are applied to the streams managed by this state,
allowing you to modify or control their behavior, such as filtering,
mapping, or handling errors, without altering the type of the emitted values

@param ...operators: OperatorFunction[] - One or more RxJS operators to apply to the state streams

@returns this the instance of the current state, allowing for method chaining

`ts
import {state} from '@bitfiber/rx';
import {delay, filter} from 'rxjs';

const data = state(0, s => s
// All streams created by this state will delay and filter the data
.manage(
filter(id => !!(id % 2)),
delay(100),
));

`

---

@method get(): T
Returns the current value of the state.
This method is useful for accessing the state at any point in time,
allowing other store items or consumers to retrieve the latest value

`ts
import {state} from '@bitfiber/rx';

const data = state(10);

// Returns the current value
data.get(); // Output: 10

`

---

@method set(value): this
Updates the state to the provided value immediately, but the emission of this
new value to subscribers will be performed asynchronously. This means that if multiple
synchronous updates are made in quick succession, only the last update will be emitted,
optimizing the emission process to prevent unnecessary updates

@param value: T - The new value to set as the current state

@returns this the instance of the current state, allowing for method chaining

`ts
import {state} from '@bitfiber/rx';

const data = state(0);

// Sets a new state value and emits the updated state to its subscribers
data.set(7);

`

---

@method update(updater): this
Updates the current state using an updater function that takes the current state value as its
argument and returns the new state value. The state is updated immediately, but the emission
of this new value to subscribers will occur asynchronously. This means that if multiple
synchronous updates are made in quick succession, only the last update will be emitted,
optimizing the emission process to prevent unnecessary updates

@param updater: (state: T) => T - A function that takes the current state value as its argument
and returns the new state value

@returns this the instance of the current state, allowing for method chaining

`ts
import {state} from '@bitfiber/rx';

const data = state(0);

// Updates the current state and emits the updated state to its subscribers
data.update(state => state + 1);

`

---

@method reset(): this
Resets the state to its original value that was set during initialization.
This is useful for reverting the state back to its starting condition, discarding any changes
that have occurred since the state was first established

@returns this the instance of the current state, allowing for method chaining

`ts
import {state} from '@bitfiber/rx';

const data = state(10);

data.set(20);

// Resets the current state to initial value '10'
data.reset();

`

---

@method compareBy(comparison): this
Sets a custom comparison strategy that will be used to determine if the state has changed.
This comparison can be one of the predefined comparison types ('equals' or 'strict')
or a custom comparison function

@param comparison: Comparison - The comparison method to use for evaluating state changes

@returns this the instance of the current state, allowing for method chaining

`ts
import {state, changeDefaultComparison} from '@bitfiber/rx';

const data1 = state(10, s => s
// Uses the equals function from the package '@bitfiber/utils' for comparing values
// this comparison is by default
.compareBy('equals'));

const data2 = state(10, s => s
// Uses '===' for comparing values
.compareBy('strict'));

const data3 = state(10, s => s
// Uses a custom function for comparing values
.compareBy((a, b) => Number(a) === Number(b)));

// By default, uses the equals function for comparing values.
// To set a different comparison type for all states by default, use this function
changeDefaultComparison('strict');

`

---

@method connect(source): this
Connects the state to an external data source DataSource, which provides the data
that the state will manage and emit. By connecting to a data source, the state can synchronize
with external data, ensuring it remains consistent with the source. This is useful in scenarios
where the state needs to reflect or react to data from an external provider.

Once connected, the state automatically updates from the data source whenever the source changes,
and conversely, updates the data source whenever the state value is changed. This bidirectional
synchronization ensures that both the state and the data source remain in sync

@param source: DataSource - The external data source to connect to the state

@returns this the instance of the current state, allowing for method chaining

`ts
import {state, localStoragePart} from '@bitfiber/rx';

const theme = state<'dark' | 'light'>('dark', s => s
// Connects the state with the local storage data stored under the key 'theme'.
// Now, if you change the state, local storage will also be updated.
// Conversely, if the local storage changes, the state will be updated.
// Ensures two-way synchronization between the state and the 'theme' data in local storage
.connect(localStoragePart('theme')));
`

---

@method useLazyEmission(): this
Enables lazy emission for the state, meaning that the state will defer emitting its initial value
to subscribers until an explicit trigger occurs. This can be useful in scenarios where you want
more control over when the state emits its value, rather than emitting immediately

@returns this the instance of the current state, allowing for method chaining

`ts
import {state} from '@bitfiber/rx';

const data = state(0, s => s
// Forces the state not to emit a value at the time of subscription
.useLazyEmission());
`

---

@method useLazyEmissionOnce(): this
Enables one-time lazy emission for the next created stream.

Once the useLazyEmissionOnce method is called, the state will defer emitting its initial value
until an explicit trigger occurs. This lazy emission behavior will apply only once for the next
stream that is created. After this initial deferred emission, subsequent streams will emit values
immediately as changes occur.

This method can be called multiple times before creating streams, allowing you to control
when the lazy emission behavior is applied.

By default, one-time lazy emission is disabled, meaning that streams will emit their initial
values immediately upon creation unless this behavior is explicitly overridden

@returns this the instance of the current state, allowing for method chaining

`ts
import {state} from '@bitfiber/rx';

const data = state(0, s => s
// Forces the next stream not to emit a value at the time of subscription
.useLazyEmissionOnce()
// Will not emit a value at the time of subscription
.effect()
// Will emit a value at the time of subscription
.transmit());
`

---

@method select(...data): this
Combines values from multiple emitters, states, or observables, applies a reducer function to
these values, and emits the resulting value to all subscribers of this state.

The first emission occurs only after all values have been received from the sources,
ensuring that the reducer function operates on a complete set of inputs.
Subsequent emissions occur whenever any of the sources emit a new value,
triggering the reducer function to recompute the result based on the latest values.
Works similarly to the RxJs 'combineLatest' operator

@param ...data: [...EmitterOrObservableTuple, SpreadFn] - A spread of emitters, states,
or observables, followed by a reducer function. The reducer function takes the latest values
from each source as arguments and returns the value to be emitted

@returns this the instance of the current state, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';
import {of} from 'rxjs';

type Result = {launchId: number; data: string; count: number};

const launch = emitter();
const data = state(1);
const count$ = of(1);

const result = state({launchId: 0, data: '', count: 0}, s => s
// Selects data from all reactive sources and emits the result to its subscribers.
// Works similarly to the RxJs 'combineLatest' operator
.select(launch, data, count$, (launchId, data, count) => {
launchId, data, count
}));
`

---

@method zip(...data): this
Combines values from multiple emitters, states, or observables, applies a reducer function to
these values, and emits the resulting value to all subscribers of this state.

The first emission occurs only after all values have been received from the sources,
ensuring that the reducer function operates on a complete set of inputs.
Subsequent emissions occur only when all sources emit new values,
triggering the reducer function to recompute the result based on the latest values.
Works similarly to the RxJs 'zip' operator

@param ...data: [...EmitterOrObservableTuple, SpreadFn] - A spread of emitters, states,
or observables, followed by a reducer function. The reducer function takes the latest values
from each source as arguments and returns the value to be emitted

@returns this the instance of the current state, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';
import {of} from 'rxjs';

type Result = {launchId: number; data: string; count: number};

const launch = emitter();
const data = state(1);
const count$ = of(1);

const result = state({launchId: 0, data: '', count: 0}, s => s
// Selects data from all reactive sources and emits the result to its subscribers.
// Works similarly to the RxJs 'zip' operator
.zip(launch, data, count$, (launchId, data, count) => {
launchId, data, count
}));
`

---

wait(...data): this
Waits for the first values from multiple emitters, states, or observables, applies a reducer
function to these values, emits the resulting value to all subscribers of this state,
and completes the stream

@param ...data: [...EmitterOrObservableTuple, SpreadFn] - A spread of emitters, states,
or observables, followed by a reducer function. The reducer function takes the first values from
each source as arguments and returns the value to be emitted

@returns this the instance of the current emitter, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';
import {of} from 'rxjs';

const launch = emitter();
const data = state(1);
const count$ = of(1);

const result = state(0, s => s
// Waits the first values from all reactive sources, emits the reducer function value to
// the state subscribers, and completes the stream
.wait(launch, data, count$, (launch, data, count) => count));
`

---

@method receive(...inputs): this
Receives values from one or more emitters, states, or observables
and emits them to all subscribers of this state.

This method allows this state to listen to external sources and relay their
emitted values to its own subscribers, effectively linking multiple data streams together

@param ...inputs: EmitterOrObservable[] - One or more emitters, states,
or observables that provide values to be emitted by this state

@returns the instance of the current state, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';
import {of} from 'rxjs';

const source1 = emitter();
const source2 = state(1);
const source3$ = of(1);

const result = state(0, s => s
// Receives data from each reactive source separately and emits a value to its subscribers
// immediately, without waiting for other sources to emit
.receive(source1, source2, source3$));
`

@method receive(input, reducer): this
Receives a value from an emitter, state, or observable, applies a reducer function to convert
this value to the state's type, and emits the result to all subscribers of this state.

This method allows this state to listen to external source and relay the transformed
emitted value to its own subscribers, effectively linking data streams together

@param input: EmitterOrObservable - an emitter, state or observable that provide values
to be emitted by this state

@param reducer: (value: I, state: T) => T - A function that converts or transforms
the received value from the input type to the type expected by this state.
This function takes the value emitted by the input and this state value as parameters,
and returns the new state value

@returns the instance of the current state, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';

const source = state(1);

const result = state('', s => s
// Receives data from a reactive source, converts the value, and emits the result to its subscribers
.receive(source, value => String(value)));
`

---

@method transmit(...outputs): this
Transmits values from the current state to one or more other emitters, states, or subjects.
It enables the propagation of data or events across multiple sources, effectively creating
a network of interconnected reactive sources

@param ...outputs: (EmitterOrSubject | EmitterOrSubject)[] - One or more emitters, states,
or subjects that will receive the transmitted values from this state

@returns the instance of the current state, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';
import {Subject} from 'rxjs';

const receiver1 = emitter();
const receiver2 = state(0);
const receiver3 = new Subject();

const source = state(0, s => s
// Transmits every emitted value to all reactive sources for further processing or handling
.transmit(receiver1, receiver2, receiver3));
`

@method transmit(output, reducer): this
Transmits values from the current state to another state. By using a reducer function,
the emitted values can be transformed or customized to match the expected format of another state

@param output: AbstractState - A state that will receive the transmitted values from this state

@param reducer: (value: T, state: O) => O - A function that converts or transforms the emitted value
from this state type to the type expected by another state

@returns the instance of the current state, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';

const receiver = state(0);

const source = state(0, s => s
// Transmits every emitted value to another state for further processing or handling
.transmit(receiver, (value, state) => state + Number(value)));
`

@method transmit(output, reducer): this
Transmits values from the current state to another emitter or subject.
By using a reducer function, the emitted values can be transformed or customized to match
the expected format of the target emitter or subject

@param output: EmitterOrSubject - An emitter or subject that will receive the transmitted values
from this state

@param reducer: (value: T) => O - A function that converts or transforms the emitted value from
the current state's type to the type expected by the receiving emitter or subject

@returns the instance of the current state, allowing for method chaining

`ts
import {emitter, state} from '@bitfiber/rx';

const receiver = emitter();

const source = state(0, s => s
// Transmits every emitted value to another emitter for further processing or handling
.transmit(receiver, value => Number(value)));
`

---

@method effect(...operators): this
Creates a new stream with a side effect, similar to the RxJS pipe method.

This method allows you to apply a sequence of RxJS operators to the state's stream,
performing actions or side effects whenever the state emits a value. This can be
particularly useful for tasks like logging, debugging, or triggering external operations
in response to emitted values

@param ...operators: OperatorFunction[] - A sequence of RxJS operators that define
the side effects to be applied to the emitted values

@returns the instance of the current state, allowing for method chaining

`ts
import {state} from '@bitfiber/rx';
import {switchMap, of} from 'rxjs';

const openDialog = state(false, s => s
// Performs a effect each time the emitter emits new value
.effect(
switchMap(isOpened => !isOpened ? dialog.open() : of(false)),
));
`

---

@method tap(observer): this
Creates a new stream with a side effect, similar to the RxJS tap operator.

This method allows you to perform actions or side effects whenever the state emits a value,
without altering the value itself. It is useful for tasks like logging, debugging,
or triggering external operations in response to emitted values

@param observer: Partial> - a partial observer with lifecycle
methods (next, error, complete)

@returns the instance of the current state, allowing for method chaining

`ts
import {state} from '@bitfiber/rx';
import {switchMap} from 'rxjs';

const log = state(0, s => s
// Performs a tap callback each time the state emits new data
.tap({
next: id => console.log(id),
error: error => console.log(error),
}));
`

@method tap(next): this
Creates a new stream with a side effect, similar to the RxJS tap operator.

This method allows you to perform actions or side effects whenever the state emits a value,
without altering the value itself. It is useful for tasks like logging, debugging,
or triggering external operations in response to emitted values

@param next: (value: T) => void - a function that takes the emitted value and performs a side effect

@returns the instance of the current state, allowing for method chaining

`ts
import {state} from '@bitfiber/rx';
import {switchMap} from 'rxjs';

const log = state(0, s => s
// Performs a tap callback each time the state emits new data
.tap(id => console.log(id)));
`

---


@function changeDefaultComparison

Changes the default comparison method that will be used for all states.
This can be one of the predefined comparison types: 'equals' for deep comparison,
'strict' for strict equality, or a custom comparison function

@param comparison: Comparison - The comparison method to be set as the default

`ts
import {changeDefaultComparison} from '@bitfiber/rx';

changeDefaultComparison('strict');
`

---

$3

Represents a comparison operation, which can be a predefined comparison type or a custom function.

The Comparison type allows for different ways to compare two values:

* 'equals': A deep comparison using the equals function from the package '@bitfiber/utils',
* 'strict': A strict equality comparison, using strict equality (===),
* ((a: any, b: any) => boolean): A custom comparison function that takes two arguments and
returns a boolean indicating whether the values are considered equal based on the provided logic

---

$3

Creates a new Group instance that collects all subsequently created group items such as
emitters, states, and groups until group.markAsReady() is called

@returns Group

Example:

`ts
import {state, emitter, group, asyncGroup} from '@bitfiber/rx';

// Collects all subsequently created emitters, states, and groups for
// mass initialization and completion
const someGroup = group();

// The emitter, state, and group will be added in 'someGroup'
const someState = state('initialValue1');
const someEmitter = emitter();
const reqGroup = asyncGroup();

// Marks the group as ready, indicating that all group items, such as emitters, states,
// and groups, have been defined
someGroup.markAsReady();

// Initializes the group and all items within the group
someGroup.initialize();

// Completes the group and all items within the group
someGroup.complete();

`

---

$3

Represents a group that collects all subsequently created group items such as emitters, states,
and groups until group.markAsReady() is called

---

@method initialize(): this
Initiates the group and all its items.

In most cases, this method will be called automatically by a group or store managing
the group, so you generally don't need to call it manually unless you have a specific
reason to do so

@returns the instance of the current group, allowing for method chaining

Example:

`ts
import {group} from '@bitfiber/rx';

// Collects all subsequently created emitters, states, and groups for
// mass initialization and completion
const someGroup = group();

// Initializes the group and all items within the group
someGroup.initialize();

`

---

@method complete(): void
Completes the group and all its items,
signaling to all item subscribers that no more values will be emitted.

Once the group is completed, Its items will no longer emit any values, and any subsequent
subscriptions will immediately receive an error.

In most cases, this method will be called automatically by a group or store managing
the group, so you generally don't need to call it manually unless you have a specific
reason to do so

Example:

`ts
import {group} from '@bitfiber/rx';

// Collects all subsequently created emitters, states, and groups for
// mass initialization and completion
const someGroup = group();

// Completes the group and all items within the group
group.complete();

`

---

@method markAsReady(): void
Marks the group as ready, indicating that all group items, such as emitters, states, and groups,
have been defined. This method must be called after all group items are defined!

Example:

`ts
import {group} from '@bitfiber/rx';

// Collects all subsequently created emitters, states, and groups for
// mass initialization and completion
const someGroup = group();

// The state will be added in 'someGroup'
const someState = state('initialValue1');

// Marks the store as ready, indicating that all store items, such as emitters, states,
// and groups, have been defined
someGroup.markAsReady();

`

---

$3

Creates a new NamedGroup instance with the store items from the provided index,
where each item is accessible by its unique key.

This function also allows for an optional onInit callback, which can be used to perform
additional setup or configuration just before the group initialization

@template I - The type of the index used to access the StoreItem instances in the group

@param index: I - An index that contains StoreItem instances and other data,
each associated with a unique key

@param onInit?: (group: NamedGroup>, sameGroup: NamedGroup>) => void -
An optional callback function that is executed just before initialization

@returns NamedGroup>

Example:

`ts
import {state, emitter, namedGroup} from '@bitfiber/rx';

// Groups all emitters and states for mass initialization and completion
const group = namedGroup({launch: emitter(), data: state(0)}, ({launch}) => {
launch
// Performs an effect each time the launch emits new data
.effect(
switchMap(page => productsService.get(api/products?page=${page})),
);
});

// Initializes the group and all items within the group
group.initialize();

// Accesses the 'launch' emitter through the group and emits a new data
group.launch.emit(1);

// Completes the group and all items within the group
group.complete();

`

---

$3

Represents a named group that incorporates store items from the provided index and can manage
these items, each accessible by a unique key

@template I - Extends Index that contains StoreItem instances and other data,
each associated with a unique key

---

@method initialize(): this
Initiates the group and all its items.

In most cases, this method will be called automatically by a group or store managing
the group, so you generally don't need to call it manually unless you have a specific
reason to do so

@returns the instance of the current group, allowing for method chaining

Example:

`ts
import {state, emitter, namedGroup} from '@bitfiber/rx';

// Groups all emitters and states for mass initialization and completion
const group = namedGroup({launch: emitter(), data: state(0)});

// Initializes the group and all items within the group
group.initialize();

`

---

@method complete(): void
Completes the group and all its items,
signaling to all item subscribers that no more values will be emitted.

Once the group is completed, Its items will no longer emit any values, and any subsequent
subscriptions will immediately receive an error.

In most cases, this method will be called automatically by a group or store managing
the group, so you generally don't need to call it manually unless you have a specific
reason to do so

Example:

`ts
import {state, emitter, namedGroup} from '@bitfiber/rx';

// Groups all emitters and states for mass initialization and completion
const group = namedGroup({launch: emitter(), data: state(0)});

// Completes the group and all items within the group
group.complete();

`

---

$3

Creates a new AsyncGroup` instance that manages the lifecycle o