AsyncSystem

An AsyncSystem is a systematic combination of four Units, one each for every aspect of an asynchronous task or API, e.g.: XHR, fetch or a third party abstraction like Angular's HttpClient.

The four aspects of an async API are query, response, error, and pending-status. For each of these aspects, we have a Unit, wrapped inside the AsyncSystem.

AsyncSystem employs three GenericUnits for query, response, and error, namely queryUnit, dataUnit, and errorUnit, respectively; and a BoolUnit for the pending-status, named pendingUnit.

A BoolUnit is used for the pending-status because it can only be in two states, true or false

GenericUnit is used for the other three aspects because it's the most permissive of all the Units, and it saves us from creating multiple variations with different kinds of Units. However, you can substitute the GenericUnits with a different kind of Unit if you want and create your own custom AsyncSystem, very easily.

The below diagram shows where and how AsyncSystem helps with an asynchronous API call to the server, and how the data flow looks like, and how the AsyncSystem shares the API call's state with multiple parts of the App.

It might seem like a lot, but not everything is happening at the same time. When you break it down it's not difficult to understand.

  • The data flow starts with a dispatch to the queryUnit, which triggers an API call from the API Service.

  • The API Service contains the logic of listening to the queryUnit, making the actual API call, and then submitting its result back to the AsyncSystem, appropriately.

  • On a successful response, the API Service dispatches the response received, to the dataUnit.

  • On an error response, the API Service dispatches the error to the errorUnit.

  • The pendingUnit is updated automatically by the AsyncSystem, it's given a true value when queryUnit emits, and a false value when dataUnit or errorUnit emits a value.

That's pretty much it, this is how an AsyncSystem works.

There are other automatic things that an AsyncSystem can do apart from updating the value of pendingUnit. Such as, it can clear the errorUnit's value when dataUnit emits a value. It can freeze the queryUnit while the pendingUnit has a true value, etc.

See API reference for more details.

This is how the usage of AsyncSystem would look like in Angular and React apps.

Angular

import {Injectable} from '@angular/core';
import {HttpErrorResponse} from '@angular/common/http';
import {AsyncSystem} from '@activejs/core';

@Injectable({providedIn: 'root'})
export class UserState {

  // initialize an AsyncSystem and declare the typings such that
  // query would be a number,
  // data would be a string,
  // error would be an HttpErrorResponse object
  readonly userSystem = new AsyncSystem<number, string, HttpErrorResponse>();
  
  // extract the Units for ease of access, or don't if you prefer
  readonly userQuery = this.userSystem.queryUnit;
  readonly userData = this.userSystem.dataUnit;
  readonly userError = this.userSystem.errorUnit;
  readonly userPending = this.userSystem.pendingUnit;
}

See this Typeahead example to for real-life usage.

React

This is how a typical usage would look like, using the React Hooks, and a custom Hook for using ActiveJS Units and Observables called useObservable.

import {AsyncSystem} from '@activejs/core';

// initialize an AsyncSystem and declare the typings such that
// query would be a number,
// data would be a string,
// error would be an HttpErrorResponse object
export const userSystem = new AsyncSystem<string, string, any>();

// extract the Units for ease of access, or don't if you prefer
export const userQueryUnit = userSystem.queryUnit;
export const userDataUnit = userSystem.dataUnit;
export const userErrorUnit = userSystem.errorUnit;
export const userPendingUnit = userSystem.pendingUnit;

See this Typeahead example to for real-life usage.

Configuration Options

The configuration options can be passed at the time of instantiation. All the configuration options are optional. Most of the options can also be set globally. See Configuration for more details.

Last updated