@jbt/ng-rx/README.md

Configurable ngrx

# @jbt/ng-rx

Configurable ngrx

# State

Configurable wrapper for [ngrx](https:ngrx.io) rxjs redux implementation for angular.

The main idea is to avoid the boilerplate and the coupling ngrx imposes to the app that uses it by providing:
- An entry point of communication with the library: **State**
- A way to set up the redux store by configuration.

# Use

## Set up

1. Import the StateModule from where the state is going to be configured and/or used

```typescript

@NgModule({
    imports: [
        StateModule
    ],
    providers: [{
        provide    : UserStateProvider,
        useFactory : UserStateProviderFactory.createUserStateProvider,
        deps       : [ State ]
    }]
})
export class UserStateModule {}

export class UserStateProviderFactory {

    public static createUserStateProvider(state: State): UserStateProvider {
        return new UserStateProvider(state);
    }
}

```

2. Provide the configuration for the state:


```typescript

export const userStateConfig: StateConfig = {
    state: {
        id: 'app',
        children: [{
            id: 'user',
            initialState: {
                firstName : '',
                lastName : '',
            }
        }]
    }
};

export class UserStateProvider {

    private _state: State;

    constructor(state: State) {

        this._state = state;

        state.configure(userStateConfig);
    }
}
```

## Reducers.

### Add reducer handlers to update the state when an action occurs

We are going to add 2 reducer handlers and configure them to act on the slice of the state we want to.

A reducer handler is a function that receives the current state and the action triggered.
It will be called when the actions we are mapping to them are fired.
The value they return will override the slice of the state.

In the following example:
- `set` handler will be triggered when `SET.USER` action is fired.
- `patch` handler will be triggered when `PATCH.USER` action is fired.

Both will act on `app.user` slice of the state.

There is also a reducers repository which holds the collection of reducer handlers the application uses.
The reducers configured need to be added to the store before the action is triggered, otherwise you'll get a nice message in your console and they will be ignored.

```typescript

export const userStateConfig: StateConfig = {
    state: {
        id: 'app',
        children: [{
            id: 'user',
            initialState: {
                firstName : '',
                lastName : '',
            },
            handlers: {
                'SET.USER': 'set',
                'PATCH.USER': 'patch'
            }
        }]
    }
};

export class UserStateProvider {

    private _state: State;

    constructor(state: State) {

        this._state = state;

        state.addReducerHandlers({
            'set': ( state, action ) => action.payload,
            'patch': ( state, action ) => action.payload,
        });

        state.configure(userStateConfig);
    }
}
```


## Effects

### Add effects so they are fired after the reducers have update the state.

An effect is the mechanism that when a **cause** action is dispatched triggers:
- a **result** action
- a calls to an **effectHandler** that will resolve in an action.

the effect configuration have :
- **causes: string[] :** List of actions that cause the effect
- **type: EFFECT_TYPE :** ACTION | PARALLEL | SEQUENCE.
    - **ACTION :** The effect triggers another action as a result bypssing the payload of the initial one.
    - **PARALLEL :** The effect calls the handlers that will return observables in parallel.
    - **ACTION :** The effect calls the handlers that will return observables in sequence.
- **handlers :** The handlers assigned to that effect


```typescript

export const userStateConfig: StateConfig = {
    state: {
        ...
    },
    effects: [{
        causes: [ 'SET.USER' ],
        type: EFFECT_TYPE.ACTION,
        result: [
            'VOID'
        ]
    },{
        causes: [ 'SET.USER' ],
        type: EFFECT_TYPE.SEQUENCE,
        handlers: [
            'delayed',
            'immediate'
        ]
    }]
};

export class UserStateProvider {

    private _state: State;

    constructor(state: State) {

        this._state = state;

        state.addEffectHandlers({
            'delayed': ( state, action ) => of({ type: 'VOID' }).pipe( delay(1000)),
            'immediate': ( state, action ) => of({ type: 'VOID' }),
        });

        state.configure(userStateConfig);
    }
}
```