Redux-orm-angular NPM

redux-orm-angular

Helpers for integrating angular-redux and redux-orm.

angular-redux provides bindings for using Redux with Angular 2+ applications. redux-orm is a simple ORM to manage entities in the Redux store.

This package enables querying entities from redux-orm directly from Angular components. You can subscribe to an observable on any query supported by redux-orm and do things like:

import { selectData } from 'redux-orm-angular';

@Component(...)
export class MyNgComponent {
    @select(selectData(MyItem).all().filter(item => item.price > 10).orderBy('price')) items: Observable<Array<MyItem>>;
}

Table of Contents

Installation

npm install --save redux-orm-angular

The package has peer dependencies on redux-orm only. Your app will require redux and @angular-redux/store to leverage this package.

Usage

Configuration

Setup redux-orm

The first step to use this package is to install and configure redux-orm in your project with a reducer indicating where the DB state should be stored. See redux-orm documentation for more information. We also assume that redux and angular-redux/store are setup, and that you have a Redux store available.

Set ORM.angularConfig

This package relies on configuration properties indicating what redux-orm instance to use and what slice of the state hosts the ORM database.

The configuration is provided as an angularConfig static property set on the ORM class exported by redux-orm:

angularConfig.instance: the redux-orm instance to use.
angularConfig.stateKey: the key in the Redux state that holds the ORM database and that your reducer is acting on. The database should be instantiated by your code separately with an empty DB state.

After initiating an ORM instance and registering models, you need to add the configuration to the ORM class:

import { ORM } from 'redux-orm';
import { MyModel } from './models';

const orm = new ORM();
orm.register(Post);

ORM.angularConfig = {
    instance: orm,
    stateKey: 'data',
}; // Add this object to your project

That instance of the ORM is used by the selectData function to create a session on the stateKey from the state and query the ORM.

Warning: Do not skip this step as it is required for the helper function to work correctly. Exceptions will be thrown if it ORM.angularConfig is not set correctly.

Import `selectData`

This package exports a helper function called selectData that can be given as a parameter to angular-redux @select decorator or select function.

Import this function in the components that need it:

import { selectData } from 'redux-orm-angular';

Note: There is nothing to import or register in your NgModule and the function will be used as is.

Query the Redux ORM

The @select decorator (and the select function) from angular-redux allow you to query the Redux store and get an observable on any property of the store. Whenever that property gets updated, the observable emits a new value and your component/view get the updated value. This is particularly powerful when used with Angular's async pipe to keep your views up to date with the Redux state of the app.

The selectData function provided by this package enables the same mechanism on the Redux ORM: you can query the ORM for data, get an observable back and the observable will emit new values whenever the ORM entities get updated (by other components/reducers, by data coming back from your server, etc.).

Redux ORM queries look like:

session.MyModel.all(); // Get all the instances of the model MyModel
session.MyModel.all().filter(item => item.price > 10).count(); // Count the number of items with price > 10
session.MyModel.get({ name: 'test' }); // Get instance with name === 'test'
session.MyModel.hasId(10); // Check if there is an instance with id === 10

selectData mimicks the syntax of redux-orm. You need to call the function with the model that you want to query as a parameter and you can then build your queries the same way as you would build them with redux-orm. The selectData function must be passed to the @select decorator or to the select function from angular-redux. See the documentation for more information on how to use them. The structure of calling selectData is the following:

@select(selectData(MyModel).standardORMQuery...)

The previous queries with @select and selectData in an Angular component would be:

@select(selectData(MyModel).all()) items: Observable<Array<MyModel>>; // Get all the instances of the model MyModel
@select(selectData(MyModel).all().filter(item => item.price > 10).count()) filteredItemsCount: Observable<number>; // Count the number of items with price > 10
@select(selectData(MyModel).get({ name: 'test' })) item: Observable<MyModel>; // Get instance with name === 'test'
@select(selectData(MyModel).hasId(10)) itemExists: Observable<boolean>; // Check if there is an instance with id === 10
}

Important: selectData(MyModel) has the same interface as session.MyModel (from redux-orm) for all the read functions (all, get, hasId, withId) and should be used in the same way.

selectData(MyModel).all() also has the same interface as session.MyModel.all() (from redux-orm) for all the read functions (at, count, exclude, exists, filter, first, last, orderBy, toModelArray, toRefArray).

Functions that transform data (upsert, delete, etc.) are not available on selectData as there would not be any good use for them.

Example

Here is a complete example of an Angular component using selectData:

import { select, NgRedux } from '@angular-redux/store';
import { selectData } from 'redux-orm-angular';
import { Observable } from 'rxjs/Observable';
import { MyItem } from './item'; // A redux-orm model

@Component({
  selector: 'app',
  template: `
Total number of items: {{ totalNumberOfItems | async }}
<ul>
  <li *ngFor="let item of (items | async)">
    {{ item.id }}
  </li>
</ul>
`
})
export class MyNgComponent {
    @select(selectData(MyItem).all().filter(item => item.price > 10).orderBy('price')) items: Observable<Array<MyItem>>;

    totalNumberOfItems: Observable<number>;

    constructor(private ngRedux: NgRedux<any>) {}

    ngOnInit() {
        this.totalNumberOfitems = this.ngRedux.select(selectData(MyItem).all().count());
    }
}