@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

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.
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.
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.
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.
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

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.
Stream Connections
Easily connects multiple emitters, states, and observables to each other.
Readable Code Structure
Produces clear, traceable code, making connections between emitters, states, and observables easy to follow.
Automatic Subscription Management
Simplifies handling reactive streams, freeing you from managing manual subscriptions and completions.
Synchronization with Data Sources
States can synchronize with data sources like local storage, cookies, and other external data sources.
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.
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

# 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.

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

Store

`@class Store`

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:

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<ProductsFilters>();

  // Provides the state of the products filters
  filters = state<ProductsFilters>({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<ProductsFilters, DictItem[], Error>(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<ProductsFilters, DictItem[], Error>(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<ProductsFilters, Product[], Error>((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<ProductsState>(
    // 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 => 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);

`@interface StoreHooks`

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

`@function emitter<T>`

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<T>) => 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<T>

Example:

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

// Creates an emitter that emits the IDs
const currentId = emitter<number>(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<number>();

// Creates an emitter that receives transmitted 'currentId' data and performs an effect that calls an API
const productReq = emitter<number>(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<string>(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<number>(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();

`@class Emitter<T>`

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<T> 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<T, T>[] - One or more RxJS operators to apply to the emitter streams

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

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

const launch = emitter<number>(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

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

const launch = emitter<number>();

// 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<I, T>] - 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

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

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

const launch = emitter<number>();
const data = state<string>(1);
const count$ = of(1);

const result = emitter<Result>(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<I, T>] - 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

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

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

const launch = emitter<number>();
const data = state<string>(1);
const count$ = of(1);

const result = emitter<Result>(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<I, T>] - 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

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

const launch = emitter<number>();
const data = state<string>(1);
const count$ = of(1);

const result = emitter<number>(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<T>[] - 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

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

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

const result = emitter<number>(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

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

const source = state<number>(1);

const result = emitter<string>(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<T> | EmitterOrSubject<void>)[] - 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

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

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

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

@method transmit<O>(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<O> - 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

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

const receiver = state<number>(0);

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

@method transmit<O>(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<O> - 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

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

const receiver = emitter<number>();

const source = emitter<string>(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<any, any>[] - 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

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

const launchProductReq = emitter<number>(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<Observer<T>> - a partial observer with lifecycle methods (next, error, complete)

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

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

const log = emitter<number>(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

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

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

`@function state<T>`

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<T>) => 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<T> a new State instance that also acts as the StateGetter function to get the current state value

Example:

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

// Creates a state that stores and emits the IDs
const currentId = state<number>(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<number | null>(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<number>(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<string>(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<number | null>(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();

`@class State<T>`

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<T> 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<T, T>[] - One or more RxJS operators to apply to the state streams