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

@bitfiber/ng/rx is an Angular-specific extension of @bitfiber/rx built on top of RxJS, designed to manage reactive state, asynchronous workflows, and events in Angular 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

NgStore
Extends the base store for improved integration with Angular’s service lifecycle.
Signal State
Manages reactive data that can be used like Angular signals.
Async Signal Group
Manages asynchronous workflows and stores their state in the signal state.
Route Group
Provides reactive management of route params, query params, and fragments.
Route Filters Group
Manages route-based filters as the signal state, ensuring synchronization with the route.
Form Source
Integrates Angular form controls with states, ensuring seamless synchronization between form data and state.

Key Features

Integration with RxJS
Since @bitfiber/ng/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.
Signal Integration
Designed specifically for Angular, @bitfiber/ng/rx integrates with Angular's signals. Signal states can be used within Angular’s reactive constructs like effect, computed, and other areas where signals are commonly used, ensuring seamless reactivity with the UI.
Route Management
The Route Group and Route Filters Group provide reactive management of route params and filters.
Form Synchronization
The Form Source feature synchronizes Angular forms with state, ensuring that form controls remain in sync with application state.
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/ng 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/ng

# YARN
yarn add @bitfiber/ng

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.

Store

`@class NgStore`

Extends Store (@bitfiber/rx) and provides functionality for managing store items such as emitters, states, and groups within an Angular context.

The NgStore class manages the lifecycle of store items, including their initialization and completion. It provides lifecycle hooks StoreHooks (@bitfiber/rx) 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 creating specific store implementations in Angular applications

@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. This method is called automatically when the associated component or service is destroyed

@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!

@method unregisterOnDestroy(): this
Cancels the registration of automatically completing the store when the associated component or service is destroyed
@returns this The current instance of the store, allowing for method chaining

Example:

import {computed, inject, Injectable} from '@angular/core';
import {switchMap} from 'rxjs';
import {pluck} from '@bitfiber/utils';
import {emitter, transmit} from '@bitfiber/rx';
import {asyncSignalGroup, routeFiltersGroup, signalState, NgStore} from '@bitfiber/ng/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[];
}

// Products store service
@Injectable()
class ProductsStore extends NgStore {
  // Provides the start of the first data loading process
  start = emitter<ProductsFilters>();

  // Provides the filters state that is synchronized with the route and the filters form
  routeFilters = routeFiltersGroup<ProductsFilters>({
    initialQueryParams: {search: '', page: 1},
  }, ({filters}) => {
    filters
      // Will not emit data immediately upon subscription
      .useLazyEmission();
  })

  // Provides a group of emitters for managing the loading process of `dict1`
  dict1Req = asyncSignalGroup<ProductsFilters, DictItem[], Error>(dict1Req => {
    dict1Req.launch
      // Receives new data from the `start` emitter
      .receive(this.start)
      // Receives new data from the `filters` emitter
      .receive(this.routeFilters.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 = asyncSignalGroup<ProductsFilters, DictItem[], Error>(dict2Req => {
    dict2Req.launch
      // Receives new data from the `start` emitter
      .receive(this.start)
      // Receives new data from the `filters` emitter
      .receive(this.routeFilters.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 = asyncSignalGroup<[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 = asyncSignalGroup<ProductsFilters, Product[], Error>((productsReq, {launch}) => {
    launch
      // Receives new data from the `dict3Req` group
      .receive(this.dict3Req.success, () => this.routeFilters.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))),
      );
  }, []);

  // Updates the `isLoading` signal flag whenever any of the query states change
  isLoading = computed(() =>
    this.dict1Req.state().inProgress
    || this.dict2Req.state().inProgress
    || this.dict3Req.state().inProgress
    || this.productsReq.state().inProgress);

  // Provides the final state of the store data
  data = signalState<ProductsState>(
    // Will emit initial data to all subscribers upon subscription
    {dict1: [], dict2: [], dict3: [], products: []},
    data => data
      // Updates the store data when all success data is received from the success emitters,
      // and continues to update after subsequent changes
      .select(
        this.dict1Req.success,
        this.dict2Req.success,
        this.dict3Req.success,
        this.productsReq.success,
        (dict1, dict2, dict3, products) => {
          return {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();
}

// Component of the products page
@Component({
  selector: 'bf-products',
  standalone: true,
  templateUrl: './products.component.html',
  imports: [
    ReactiveFormsModule,
  ],
  providers: [
    ProductsStore,
  ],
})
export class ProductsComponent {
  readonly store = inject(ProductsStore).initialize();
  readonly form = store.routeFilters.form;
}

<!-- products.component.html -->
@if (!store.isLoading()) {
  <div
    class="bf-filters"
    [formGroup]="form"
  >
    <input formControlName="search"/>
    <pagenator formControlName="page"/>
  </div>

  @for (product of store.data().products; track product.id) {
    <div class="bf-product">
      {{product.name}} - {{product.price}}
    </div>
  }
} @else {
  Data is loading...
}

`@function signalState<T>`

Creates the signal state that combines the functionality of both the SignalState class and the Signal interface, initialized with the provided initialValue.

This state can behave like a 'State' or as an Angular signal. It can be used in Angular's effect or computed functions and in other places where you would normally use a signal.

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

Example:

import {computed} from '@angular/core';
import {take, filter, switchMap} from 'rxjs';
import {namedGroup} from '@bitfiber/rx';
import {signalState} from '@bitfiber/ng/rx';

// Creates a state that stores and emits the IDs
const currentId = signalState<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 = signalState<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 = signalState<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 = signalState<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 = signalState<[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 = signalState<[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 = signalState<number | null>(null, s => s
  // Waits for the first value from the `lastId` state, then completes the stream
  .wait(lastId, lastId => new Date().getTime()));

// Demonstrates the usage of signal states within Angular's `computed` function
const results = computed(() => result1().concat(result2()));

// 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 SignalState<T>`

Represents a signal 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.

This state can behave like a 'State' or as an Angular signal. It can be used in Angular's effect or computed functions and in other places where you would normally use a signal.

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