# rxjs-loading-state
[](https://app.circleci.com/pipelines/github/tomraithel/rxjs-loading-state)
[](https://www.npmjs.com/package/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](#getting-started)
- [Installation](#installation)
- [TL;DR](#tldr)
- [What is a LoadingStateMachine?](#what-is-a-loading-state)
- [trackLoadingBy operator explained](#trackLoadingBy-operator)
- [API](#api)
- [LoadingStateMachine](#LoadingStateMachine)
- [trackLoadingBy](#trackLoadingBy)
## Getting started
### How to install?
Installation via NPM:
```bash
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:
```ts
// Create a new LoadingStateMachine instance
const machine = new LoadingStateMachine();
// 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!
```typescript
const machine = new LoadingStateMachine();
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.
```typescript
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](#LoadingStateMachine)
- [new LoadingStateMachine()](#new_LoadingStateMachine_new)
- _instance_
- [.data](#LoadingStateMachine+data)
- [.error](#LoadingStateMachine+error)
- [.state](#LoadingStateMachine+state)
- [.asObservable()](#LoadingStateMachine+asObservable) ⇒ Observable<LoadingState>
- [.update(newData)](#LoadingStateMachine+update)
- [.start()](#LoadingStateMachine+start)
- [.succeed(data)](#LoadingStateMachine+succeed)
- [.fail(error)](#LoadingStateMachine+fail)
- [.reset()](#LoadingStateMachine+reset)
- [.isNotStarted()](#LoadingStateMachine+isNotStarted) ⇒ Boolean
- [.isLoading()](#LoadingStateMachine+isLoading) ⇒ Boolean
- [.isError()](#LoadingStateMachine+isError) ⇒ Boolean
- [.isSuccess()](#LoadingStateMachine+isSuccess) ⇒ Boolean
- _static_
- [.asError(error)](#LoadingStateMachine.asError) ⇒ LoadingStateMachine<T>
- [.asSuccess(data)](#LoadingStateMachine.asSuccess) ⇒ LoadingStateMachine<T>
- [.asLoading(data)](#LoadingStateMachine.asLoading) ⇒ 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)
### loadingStateMachine.error
Error of the current state. Depending on the current state, this may be undefined.
**Kind**: instance property of [LoadingStateMachine](#LoadingStateMachine)
### loadingStateMachine.state
The current LoadingState
**Kind**: instance property of [LoadingStateMachine](#LoadingStateMachine)
### loadingStateMachine.asObservable() ⇒ Observable<LoadingState>
Creates a new observable that represents the current state of the machine
**Kind**: instance method of [LoadingStateMachine](#LoadingStateMachine)
**Returns**: Observable<LoadingState> - Observable that emits the machine state
### loadingStateMachine.update(newData)
Update data while in loading state
**Kind**: instance method of [LoadingStateMachine](#LoadingStateMachine)
| Param | Type |
| ------- | -------------- |
| newData | T |
### loadingStateMachine.start()
Starts loading
**Kind**: instance method of [LoadingStateMachine](#LoadingStateMachine)
### loadingStateMachine.succeed(data)
Transition to success state
**Kind**: instance method of [LoadingStateMachine](#LoadingStateMachine)
| Param | Type |
| ----- | -------------- |
| data | T |
### loadingStateMachine.fail(error)
Transition to error state
**Kind**: instance method of [LoadingStateMachine](#LoadingStateMachine)
| Param | Type |
| ----- | ---------------- |
| error | any |
### loadingStateMachine.reset()
Resets machine to not started
**Kind**: instance method of [LoadingStateMachine](#LoadingStateMachine)
### loadingStateMachine.isNotStarted() ⇒ Boolean
**Kind**: instance method of [LoadingStateMachine](#LoadingStateMachine)
**Returns**: Boolean - True if machine if loading has not been started or reset
### loadingStateMachine.isLoading() ⇒ Boolean
**Kind**: instance method of [LoadingStateMachine](#LoadingStateMachine)
**Returns**: Boolean - True if machine is in loading state
### loadingStateMachine.isError() ⇒ Boolean
**Kind**: instance method of [LoadingStateMachine](#LoadingStateMachine)
**Returns**: Boolean - True if machine is in error state
### loadingStateMachine.isSuccess() ⇒ Boolean
**Kind**: instance method of [LoadingStateMachine](#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](#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](#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](#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> |