redux-orm-angular

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
• Usage
  • Setup redux-orm and ORM.instance
  • Import selectData
  • Query the Redux ORM
• Example
• License
• Sponsor

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

Setup redux-orm and ORM.instance

The first step to use this package is to install and configure redux-orm in your project. See redux-orm documentation for more information.

After initiating an ORM instance and registering models, you need to store that instance on the ORM class:

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

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

ORM.instance = orm; // Add this line to your project

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

Warning: Do not skip this step as it is required for the helper function to work correctly. An exception will be thrown if ORM.instance 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());
    }
}

License

MIT. See LICENSE.

Sponsor

redux-orm-angular is developed and maintained by Didomi, an end-to-end solution for managing data privacy and user consent.