rxjs-loading-state

rxjs-loading-state eliminates manual state management for loading and error states by transforming Observables into a LoadingState.

Table of contents:

• Getting Started
  • Installation
  • TL;DR
  • What is a LoadingStateMachine?
  • trackLoadingBy operator explained
• API
  • LoadingStateMachine
  • trackLoadingBy

Getting started

How to install?

Installation via NPM:

npm install rxjs-loading-state --save

TL;DR

You create a LoadingStateMachine object and connect it to your observable. This object now reflects the loading state of your Observable:

// Create a new LoadingStateMachine instance
const machine = new LoadingStateMachine<number>();

// Create an Observable that finishes after 1000ms and track it by the machine
const loadData$ = of(42).pipe(delay(1000), trackLoadingBy(machine));

// As long as no one is subscribed, loading state is in "notStarted" state
console.log(machine.state); // "notStarted"

// After subscription, loading state transitions to "loading" state
loadData$.subscribe();
console.log(machine.state); // "loading"

// After 2s the Observable is completed and loadingState transitioned to "success"
setTimeout(() => {
  console.log(machine.state); // "success"
}, 2000);

What is a LoadingStateMachine?

The LoadingStateMachine is a small state-machine that consists of four states it can be in:

Type	Description
LoadingStateName.NotStarted	Loading has not been started yet.
LoadingStateName.Loading	Data is getting loaded. Could be the first load or a reload.
LoadingStateName.Error	An error occurred during loading.
LoadingStateName.Success	Data has successfully been loaded.

Transition between these steps can be performed with event methods. This state-chart gives an overview, which event can be called in which state.

Note: If an event is triggered in an invalid state, the state machine rises an exception!

const machine = new LoadingStateMachine<string>();

machine.start();
console.log(machine.state); // "loading"
console.log(machine.data); // undefined

machine.succeed("my-data");
console.log(machine.state); // "success"
console.log(machine.data); // "my-data"

machine.succeed("boo"); // throws IllegalStateTransitionError: Transition from success to success not allowed

The trackLoadingBy explained

Although you can manually trigger state changes on a LoadingStateMachine, there is a better way to do it.

The trackLoadingBy operator connects your state machine to an existing Observable. As soon as a subscription to this Observable starts, the LoadingStateMachine instance gets updated automatically and can be used in your view template.

const machine = new LoadingStateMachine();
fetchData().pipe(trackLoadingBy(machine)).subscribe();

// later in your render-loop or template
function render() {
  if (machine.isLoading()) {
    return "loading...";
  }

  if (machine.isError()) {
    return "error: " + machine.error.message;
  }

  if (machine.isSuccess()) {
    return "data fetched: " + machine.data;
  }
}

API

LoadingStateMachine

Kind: global class

• LoadingStateMachine
  • new LoadingStateMachine()
  • instance
    • .data
    • .error
    • .state
    • .asObservable() ⇒ Observable<LoadingState>
    • .update(newData)
    • .start()
    • .succeed(data)
    • .fail(error)
    • .reset()
    • .isNotStarted() ⇒ Boolean
    • .isLoading() ⇒ Boolean
    • .isError() ⇒ Boolean
    • .isSuccess() ⇒ Boolean
  • static
    • .asError(error) ⇒ LoadingStateMachine<T>
    • .asSuccess(data) ⇒ LoadingStateMachine<T>
    • .asLoading(data) ⇒ LoadingStateMachine<T>

new LoadingStateMachine()

Handles transitions between different loading state and holds the context data that is related to the current state.

loadingStateMachine.data

Data of the current state. Depending on the current state, this may be undefined.

Kind: instance property of LoadingStateMachine

loadingStateMachine.error

Error of the current state. Depending on the current state, this may be undefined.

Kind: instance property of LoadingStateMachine

loadingStateMachine.state

The current LoadingState

Kind: instance property of LoadingStateMachine

loadingStateMachine.asObservable() ⇒ Observable<LoadingState>

Creates a new observable that represents the current state of the machine

Kind: instance method of LoadingStateMachine
Returns: Observable<LoadingState> - Observable that emits the machine state

loadingStateMachine.update(newData)

Update data while in loading state

Kind: instance method of LoadingStateMachine

Param	Type
newData	T

loadingStateMachine.start()

Starts loading

Kind: instance method of LoadingStateMachine

loadingStateMachine.succeed(data)

Transition to success state

Kind: instance method of LoadingStateMachine

Param	Type
data	T

loadingStateMachine.fail(error)

Transition to error state

Kind: instance method of LoadingStateMachine

Param	Type
error	any

loadingStateMachine.reset()

Resets machine to not started

Kind: instance method of LoadingStateMachine

loadingStateMachine.isNotStarted() ⇒ Boolean

Kind: instance method of LoadingStateMachine
Returns: Boolean - True if machine if loading has not been started or reset

loadingStateMachine.isLoading() ⇒ Boolean

Kind: instance method of LoadingStateMachine
Returns: Boolean - True if machine is in loading state

loadingStateMachine.isError() ⇒ Boolean

Kind: instance method of LoadingStateMachine
Returns: Boolean - True if machine is in error state

loadingStateMachine.isSuccess() ⇒ Boolean

Kind: instance method of LoadingStateMachine
Returns: Boolean - True if machine is in success state

LoadingStateMachine.asError(error) ⇒ LoadingStateMachine<T>

Factory to create a new machine in error state

Kind: static method of LoadingStateMachine
Returns: LoadingStateMachine<T> - The new LoadingStateMachine

Param	Type
error	any

LoadingStateMachine.asSuccess(data) ⇒ LoadingStateMachine<T>

Factory to create a new machine in success state

Kind: static method of LoadingStateMachine
Returns: LoadingStateMachine<T> - The new LoadingStateMachine

Param	Type
data	T

LoadingStateMachine.asLoading(data) ⇒ LoadingStateMachine<T>

Factory to create a new machine in loading state

Kind: static method of LoadingStateMachine
Returns: LoadingStateMachine<T> - The new LoadingStateMachine

Param	Type
data	T | undefined

---

trackLoadingBy(loadingStateMachine)

Tracks an observable, by emitting loading events to the passed in state machine

Kind: global function

Param	Type
loadingStateMachine	LoadingStateMachine<Data>