Repository files navigation

This repository is now merged with @ngrx into @ngrx/data. You can find thengrx/data docs here and thegithub repository with ngrx/data in it here

Please read the note above

You may never write an action, reducer, selector, effect, or HTTP dataservice again.

NgRx helps Angular applications manage shared state in a "reactive" style, following theredux pattern.

But to use it properly requiresboth a deep understanding of redux/ngrxand a lot ofboilerplate code.

Ngrx-data is anngrx extension that offers a gentle introduction tongrx/redux without the boilerplate.

Try it! See theQuick Start for instructions on adding NgRx and ngrx-data to your app.

Many applications have substantialdomain models with 10s or 100s ofentity typessuch asCustomer,Order,LineItem,Product, andUser.

In plainngrx, to create, retrieve, update, and delete (CRUD) data for every entity type is an overwhelming task. You're writingactions,action-creators,reducers,effects,dispatchers, andselectors as well as the HTTP GET, PUT, POST, and DELETE methodsfor each entity type.

In even a small model, this is a ton of repetitive code to create, maintain, and test.

Thengrx-data library isone way to stay on thengrx path while radically reducing the "boilerplate" necessary to manage entities withngrx.

This is alibrary for ngrx, not an ngrx alternative.

It's easy to combine standard ngrx with ngrx-data.It's easy to take control when you need it and hand control back to ngrx-data when you're done.

Every entity has its own actions. Every operation takes its unique journey through the store, reducers, effects, and selectors. You just letngrx-data create these for you.

You can add custom store properties, actions, reducers, selectors, and effects. You can override any ngrx-data behavior for an individual entity type or for all entities.You can make your own calls to the server and update the cached entity collections with the results using ngrx-datacache-only actions.

You can see thengrx machinery at work with theredux developer tools. You can listen to the flow of actions directly. You canintercept and override anything ... but you only have to intervene where you want to add custom logic.

For a hands-on experience, try theQuickStartin the tutorial git repo,ngrx-data-lab,which guides you on the few, simple steps necessary to migrate from a typical service-based Angular app, to an app that manages state withngrx-data.

Thisngrx-data repository has the main documentation and its own sample app.

The sample app in thesrc/client/app/ folder presents an editor for viewing and changingHeroes andVillains.

The followingreduced extract from that demo illustrates the essential mechanics of configuring and usingngrx-data.

You begin with a description of the entity model in a few lines of metadata.

// Metadata for the entity modelexportconstentityMetadata:EntityMetadataMap={Hero:{},Villain:{}};// Help ngrx-data pluralize entity type names// because the plural of "Hero" is not "Heros"exportconstpluralNames={Hero:'Heroes'// the plural of Hero};

You register the metadata and plurals with thengrx-data module.

@NgModule({imports:[NgrxDataModule.forRoot({entityMetadata:entityMetadata,pluralNames:pluralNames})]})exportclassEntityStoreModule{}

Your component accesses each entity data through anEntityCollectionService which you can acquire from thengrx_dataEntityServices.

In the following example,theHeroesComponent injectsEntityServices and asks it for anEntityCollectionServiceregistered under theHero entity name.

The component uses that service to read and saveHero entity datain a reactive, immutable style,without reference to any of the ngrx artifacts.

import{EntityCollectionService,EntityServices}from'ngrx-data';import{Hero}from'../../core';@Component({selector:'app-heroes',templateUrl:'./heroes.component.html',changeDetection:ChangeDetectionStrategy.OnPush})exportclassHeroesComponentimplementsOnInit{heroes$:Observable<Hero[]>;heroesService:EntityCollectionService<Hero>;constructor(entityServices:EntityServices){this.heroesService=entityServices.getEntityCollectionService('Hero');this.heroes$=this.heroesService.entities$;}ngOnInit(){this.getHeroes();}getHeroes(){this.heroesService.getAll();}addHero(hero:Hero){this.heroesService.add(hero);}deleteHero(hero:Hero){this.heroesService.delete(hero.id);}updateHero(hero:Hero){this.heroesService.update(hero);}}

As you explorengrx-data and its documentation,you'll learn many extension points and customizations thattailor the developer experience to your application needs.

Try theQuick Start to experience NgRx and ngrx-data in your app.

This repository contains thengrx-data source code and ademonstration application (the "demo app") that exercises many of the library features.

The key folders in this repository are:

• docs --> the docs for the library and the demo
• lib ---> the ngrx-data library source code that we publish to npm
• src/app ---> the demo app source
• server ---> a node server for remote data access

• Quick Start
• Architecture
• Entity Metadata
• Entity Collection
• Entity Collection Service
• Entity Services
• Entity DataService
• Entity Actions
• Entity Reducer
• Entity Change Tracker
• Saving multiple-entities at once
• Extension Points
• Limitations
• FAQ: Frequently Asked Questions

The demo app is based on the Angular CLI. You may want to install the CLI globally if you have not already done so.

npm install -g @angular/cli

Then follow these steps:

1. Clone this repository

   git clone https://github.com/johnpapa/angular-ngrx-data.gitcd angular-ngrx-data

2. Install the npm packages

   npm install

3. Build thengrx-data library

   npm run build-setup

4. Serve the CLI-based demo app

   ng serve -o

Refer to thetroubleshooting section if you run into installation issues.

Thengrx-data library ships with unit and E2E (end-to-end) tests to validate functionality and guard against regressions.

These tests also demonstrate features of the library that are not covered in the demo app. They're worth reading to discover more advanced techniques.

Run this CLI command to execute theunit tests for the library.

ngtest

Run the sample appE2E (end-to-end) tests.

npm run e2e

We welcomePRs that add to the tests as well as those that fix bugs and documentation.

Be sure to run these tests before submitting a PR for review.

The demo app isconfigured for monitoring with theRedux DevTools.

Follow these instructions toinstall them in your browser and learn how to use them.

When runningtests, open the browser dev tools, go to the "Sources" tab, and look for the library files by name.

In chrome, type [Command-P] and letters of the file name.

Whenrunning the app (e.g., withng serve), the browser dev tools give you TWO choices for a given TypeScript source file, both claiming to be from.ts.

The one you want for library and app files ends in/lib/src/file-name.ts and/src/client/app/path/file-name.ts respectively.

Hope to solve thetwo file problem.

The demo app is setup to build and run against the ngPackagr artifacts indist/ngrx-data,the same artifacts delivered in the npm package.

Re-build the librarynpm run build-lib ornpm run build-setup ornpm run build-allto update these artifacts.

This approach, while safe, can be inconvenient when you're evolving the library code because"Go to definition" takes you to thed.ts files indist/ngrx-data rather thanthe source files inlib/src.

If you want to "Go to definition" to take you to the source files,make the following*temporary changes to the TypeScript configuration.

1. Replace the paths target in the roottsconfig.json so that the IDE (e.g., VS Code) looks forngrx-data insrc/lib.

   "paths": {"ngrx-data": ["lib/src"]  },

2. Replacethat same setting in the config atsrc/tsconfig.json.

3. Replacethat same setting insrc/client/tsconfig.app.json.Nowng build referencessrc/lib when it builds the demo app.

Remember torestore thetsconfig settings when you're done. Do not commit those changes!

The demo app queries and saves mock entity data to an in-memory database with the help of theAngular In-memory Web API.

The "Remote Data" toggle switch in the header switchesto the remote database.

The app fails when you switch to the remote database.

Notice how the app detects errors and pops up a toast message with the failedngrxAction.type.

The error details are in the browser's console log.

You must first set up a database and launch a web api server that talks to it.

Thesrc/server folder has code for a local node web api server, configured for the demo app.

TODO:Explain how to build and run the server.Explain how to build and serve the mongo db

We know there are a great many npm script commands inpackage.json, many (most?) of which don't work.

They're on our list for future cleanup.Please don't create issues for them(although PRs that fix them are welcome).

1. If you are on Windows and run into this error duringnpm install:"snyk couldn't patch the specified vulnerabilities because gnu's patch is not available", refer to thisissue for the fix. In short, yourGit installation is not correct orC:\Program Files\Git\usr\bin (typically) is not added to your system environment variable%PATH%.

Open an issue here