{"id":16227260,"url":"https://github.com/johnpapa/angular-ngrx-data","last_synced_at":"2025-05-15T15:07:36.673Z","repository":{"id":37773870,"uuid":"112114114","full_name":"johnpapa/angular-ngrx-data","owner":"johnpapa","description":"Angular with ngRx and experimental ngrx-data helper","archived":false,"fork":false,"pushed_at":"2023-01-12T04:26:25.000Z","size":5041,"stargazers_count":970,"open_issues_count":55,"forks_count":131,"subscribers_count":66,"default_branch":"master","last_synced_at":"2025-05-08T01:38:24.622Z","etag":null,"topics":["angular","ngrx","rxjs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnpapa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-26T20:27:00.000Z","updated_at":"2025-03-23T00:58:23.000Z","dependencies_parsed_at":"2023-02-09T10:02:40.620Z","dependency_job_id":null,"html_url":"https://github.com/johnpapa/angular-ngrx-data","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnpapa%2Fangular-ngrx-data","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnpapa%2Fangular-ngrx-data/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnpapa%2Fangular-ngrx-data/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnpapa%2Fangular-ngrx-data/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnpapa","download_url":"https://codeload.github.com/johnpapa/angular-ngrx-data/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254364270,"owners_count":22058878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","ngrx","rxjs"],"created_at":"2024-10-10T12:52:07.172Z","updated_at":"2025-05-15T15:07:31.650Z","avatar_url":"https://github.com/johnpapa.png","language":"TypeScript","readme":"# Angular ngrx-data\n\n\u003e **This repository is now merged with @ngrx into @ngrx/data. You can find the [ngrx/data docs here](https://ngrx.io/guide/data) and the [github repository with ngrx/data in it here](https://github.com/ngrx/platform)**\n\n**Please read the note above**\n\n[![prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://prettier.io/)\n\n## Zero Ngrx Boilerplate\n\n**You may never write an action, reducer, selector, effect, or HTTP dataservice again.**\n\n[_NgRx_](https://github.com/ngrx/platform/blob/master/README.md) helps Angular applications manage shared state in a \"reactive\" style, following the [redux](https://redux.js.org) pattern.\n\nBut to use it properly requires _both_ a deep understanding of redux/ngrx _and_ a lot of _boilerplate code_.\n\n_Ngrx-data_ is an _ngrx_ extension that offers a gentle introduction to _ngrx/redux_ without the boilerplate.\n\n\u003e **Try it!** See the [Quick Start](https://github.com/johnpapa/ngrx-data-lab/blob/master/README.md) for instructions on adding NgRx and ngrx-data to your app.\n\n\u003ca id=\"why\"\u003e\u003c/a\u003e\n\n## Why use _ngrx-data_?\n\nMany applications have substantial _domain models_ with 10s or 100s of [entity types](docs/faq.md/#entity)\nsuch as _Customer_, _Order_, _LineItem_, _Product_, and _User_.\n\nIn plain _ngrx_, to create, retrieve, update, and delete (CRUD) data for every entity type is an overwhelming task. You're writing _actions_, _action-creators_, _reducers_, _effects_, _dispatchers_, and _selectors_ as well as the HTTP GET, PUT, POST, and DELETE methods _for each entity type_.\n\nIn even a small model, this is a ton of repetitive code to create, maintain, and test.\n\nThe _ngrx-data_ library is _one_ way to stay on the _ngrx_ path while radically reducing the \"boilerplate\" necessary to manage entities with _ngrx_.\n\n## It's still _NgRx_\n\n**This is a _library for ngrx_, not an ngrx alternative.**\n\nIt's easy to combine standard ngrx with ngrx-data.\nIt's easy to take control when you need it and hand control back to ngrx-data when you're done.\n\nEvery entity has its own actions. Every operation takes its unique journey through the store, reducers, effects, and selectors. You just let _ngrx-data_ create these for you.\n\nYou 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.\nYou can make your own calls to the server and update the cached entity collections with the results using ngrx-data _cache-only_ actions.\n\nYou can see the _ngrx machinery_ at work with the [_redux developer tools_](#redux-dev-tools). You can listen to the flow of actions directly. You can _intercept and override anything_ ... but you only have to intervene where you want to add custom logic.\n\n### Learn about it\n\nFor a hands-on experience, try the [QuickStart](https://github.com/johnpapa/ngrx-data-lab/blob/master/README.md)\nin the tutorial git repo, **[ngrx-data-lab](https://github.com/johnpapa/ngrx-data-lab/)**,\nwhich guides you on the few, simple steps necessary to migrate from a typical service-based Angular app, to an app that manages state with _ngrx-data_.\n\n_This_ **ngrx-data repository** has the main documentation and its own sample app.\n\nThe sample app in the `src/client/app/` folder presents an editor for viewing and changing _Heroes_ and _Villains_.\n\nThe following _reduced_ extract from that demo illustrates the essential mechanics of configuring and using _ngrx-data_.\n\nYou begin with a description of the entity model in a few lines of metadata.\n\n```javascript\n// Metadata for the entity model\nexport const entityMetadata: EntityMetadataMap = {\n  Hero: {},\n  Villain: {}\n};\n\n// Help ngrx-data pluralize entity type names\n// because the plural of \"Hero\" is not \"Heros\"\nexport const pluralNames = {\n  Hero: 'Heroes' // the plural of Hero\n};\n```\n\nYou register the metadata and plurals with the `ngrx-data` module.\n\n```javascript\n@NgModule({\n  imports: [\n    NgrxDataModule.forRoot({\n      entityMetadata: entityMetadata,\n      pluralNames: pluralNames\n    })\n  ]\n})\nexport class EntityStoreModule {}\n```\n\nYour component accesses each entity data through an `EntityCollectionService` which you can acquire from the _ngrx_data_ `EntityServices`.\n\nIn the following example,\nthe `HeroesComponent` injects `EntityServices` and asks it for an `EntityCollectionService`\nregistered under the `Hero` entity name.\n\nThe component uses that service to read and save _Hero_ entity data\nin a reactive, immutable style, _without reference to any of the ngrx artifacts_.\n\n```javascript\nimport { EntityCollectionService, EntityServices } from 'ngrx-data';\nimport { Hero } from '../../core';\n\n@Component({\n  selector: 'app-heroes',\n  templateUrl: './heroes.component.html',\n  changeDetection: ChangeDetectionStrategy.OnPush\n})\nexport class HeroesComponent implements OnInit {\n  heroes$: Observable\u003cHero[]\u003e;\n  heroesService: EntityCollectionService\u003cHero\u003e;\n\n  constructor(entityServices: EntityServices) {\n    this.heroesService = entityServices.getEntityCollectionService('Hero');\n    this.heroes$ = this.heroesService.entities$;\n  }\n\n  ngOnInit() {\n    this.getHeroes();\n  }\n\n  getHeroes() {\n    this.heroesService.getAll();\n  }\n\n  addHero(hero: Hero) {\n    this.heroesService.add(hero);\n  }\n\n  deleteHero(hero: Hero) {\n    this.heroesService.delete(hero.id);\n  }\n\n  updateHero(hero: Hero) {\n    this.heroesService.update(hero);\n  }\n}\n```\n\nAs you explore _ngrx-data_ and its documentation,\nyou'll learn many extension points and customizations that\ntailor the developer experience to your application needs.\n\n## QuickStart\n\nTry the [Quick Start](https://github.com/johnpapa/ngrx-data-lab/blob/master/README.md) to experience NgRx and ngrx-data in your app.\n\n\u003ca id=\"explore\"\u003e\u003c/a\u003e\n\n## Explore this repository\n\nThis repository contains the _ngrx-data_ source code and a\ndemonstration application (the \"demo app\") that exercises many of the library features.\n\nThe key folders in this repository are:\n\n* docs --\u003e the docs for the library and the demo\n* lib ---\u003e the ngrx-data library source code that we publish to npm\n* src/app ---\u003e the demo app source\n* server ---\u003e a node server for remote data access\n\n\u003ca id=\"docs-list\"\u003e\u003c/a\u003e\n\n### Learn more in the docs\n\n* [Quick Start](https://github.com/johnpapa/ngrx-data-lab/blob/master/README.md)\n* [Architecture](docs/architecture.md)\n* [Entity Metadata](docs/entity-metadata.md)\n* [Entity Collection](docs/entity-collection.md)\n* [Entity Collection Service](docs/entity-collection-service.md)\n* [Entity Services](docs/entity-services.md)\n* [Entity DataService](docs/entity-dataservice.md)\n* [Entity Actions](docs/entity-actions.md)\n* [Entity Reducer](docs/entity-reducer.md)\n* [Entity Change Tracker](docs/entity-change-tracker.md)\n* [Saving multiple-entities at once](docs/save-entities.md)\n* [Extension Points](docs/extension-points.md)\n* [Limitations](docs/limitations.md)\n* [FAQ: Frequently Asked Questions](docs/faq.md)\n\n### Install and run\n\nThe demo app is based on the Angular CLI. You may want to install the CLI globally if you have not already done so.\n\n```bash\nnpm install -g @angular/cli\n```\n\nThen follow these steps:\n\n1.  Clone this repository\n\n    ```bash\n    git clone https://github.com/johnpapa/angular-ngrx-data.git\n    cd angular-ngrx-data\n    ```\n\n2.  Install the npm packages\n\n    ```bash\n    npm install\n    ```\n\n3.  Build the `ngrx-data` library\n\n    ```bash\n    npm run build-setup\n    ```\n\n4.  Serve the CLI-based demo app\n\n    ```bash\n    ng serve -o\n    ```\n\nRefer to the [troubleshooting](#installation) section if you run into installation issues.\n\n## Run the library tests\n\nThe _ngrx-data_ library ships with unit and E2E (end-to-end) tests to validate functionality and guard against regressions.\n\nThese tests also demonstrate features of the library that are not covered in the demo app. They're worth reading to discover more advanced techniques.\n\nRun this CLI command to execute the **unit tests** for the library.\n\n```bash\nng test\n```\n\nRun the sample app **E2E (end-to-end) tests**.\n\n```bash\nnpm run e2e\n```\n\nWe welcome [PRs](https://github.com/johnpapa/angular-ngrx-data/pulls) that add to the tests as well as those that fix bugs and documentation.\n\nBe sure to run these tests before submitting a PR for review.\n\n\u003ca id=\"redux-dev-tools\"\u003e\u003c/a\u003e\n\n## Monitor the app with Redux DevTools\n\nThe demo app is [configured for monitoring](https://github.com/ngrx/platform/tree/master/docs/store-devtools) with the [Redux DevTools](https://github.com/zalmoxisus/redux-devtools-extension).\n\nFollow these instructions to [install them in your browser](https://github.com/zalmoxisus/redux-devtools-extension) and learn how to use them.\n\n## Debug the library in browser dev tools\n\nWhen running _tests_, open the browser dev tools, go to the \"Sources\" tab, and look for the library files by name.\n\n\u003e In chrome, type [Command-P] and letters of the file name.\n\nWhen _running the app_ (e.g., with `ng serve`), the browser dev tools give you TWO choices for a given TypeScript source file, both claiming to be from `.ts`.\n\nThe one you want for library and app files ends in `/lib/src/file-name.ts` and `/src/client/app/path/file-name.ts` respectively.\n\n\u003e Hope to solve the _two file_ problem.\n\n## Build the app against the source\n\nThe demo app is setup to build and run against the ngPackagr artifacts in `dist/ngrx-data`,\nthe same artifacts delivered in the npm package.\n\n\u003e Re-build the library `npm run build-lib` or `npm run build-setup` or `npm run build-all`\n\u003e to update these artifacts.\n\nThis approach, while safe, can be inconvenient when you're evolving the library code because\n\"Go to definition\" takes you to the `d.ts` files in `dist/ngrx-data` rather than\nthe source files in `lib/src`.\n\nIf you want to \"Go to definition\" to take you to the source files,\nmake the following **\\*temporary changes** to the TypeScript configuration.\n\n1.  **_Replace_** the paths target in the root `tsconfig.json` so that the IDE (e.g., VS Code) looks for `ngrx-data` in `src/lib`.\n\n    ```bash\n      \"paths\": {\n        \"ngrx-data\": [\"lib/src\"]\n      },\n    ```\n\n2.  **_Replace_** _that same setting_ in the config at `src/tsconfig.json`.\n\n3.  **_Replace_** _that same setting_ in `src/client/tsconfig.app.json`.\n    Now `ng build` references `src/lib` when it builds the demo app.\n\n\u003e **Remember to _restore the `tsconfig` settings_ when you're done. Do not commit those changes!**\n\n## Use a real database\n\nThe demo app queries and saves mock entity data to an in-memory database with the help of the\n[Angular In-memory Web API](https://github.com/angular/in-memory-web-api).\n\nThe \"Remote Data\" toggle switch in the header switches\nto the remote database.\n\nThe app fails when you switch to the remote database.\n\n\u003e Notice how the app detects errors and pops up a toast message with the failed _ngrx_ `Action.type`.\n\u003e\n\u003e The error details are in the browser's console log.\n\nYou must first set up a database and launch a web api server that talks to it.\n\nThe `src/server` folder has code for a local node web api server, configured for the demo app.\n\n\u003e TODO:\n\u003e Explain how to build and run the server.\n\u003e Explain how to build and serve the mongo db\n\n## Bad/surplus _npm scripts_\n\nWe know there are a great many npm script commands in `package.json`, many (most?) of which don't work.\n\nThey're on our list for future cleanup.\nPlease don't create issues for them\n(although PRs that fix them are welcome).\n\n\u003c!--\n\n\u003eTODO: Fix the broken server-oriented commands in package.json\n\n### Create a MongoDb\n\n1. Create a [CosmosDB instance](https://docs.microsoft.com/azure/cosmos-db/tutorial-develop-mongodb-nodejs-part4?WT.mc_id=angularngrxdata-github-jopapa)\n\n### Build and launch the node server\n\n1. Build the Angular app and launch the node server\n\n```bash\n???\n```\n\n1. Open the browser to \u003chttp://localhost:3001\u003e\n\n### Docker\n\n* Install and run [Docker](https://www.docker.com/community-edition)\n\n#### Environment file\n\nCreate an empty file named `.env` in the root of the app. We'll fill this in later.\n\n#### Docker Compose with Debugging\n\nCreate the Docker image and run it locally. This commands uses `docker-compose` to build the image\nand run the container.\n\nThis opens port `9229` for debugging.\n\n```bash\nnpm run docker-debug\nopen http://localhost:3001\n```\n\nOpen VS Code, launch the `Docker: Attach to Node` debugging profile\n\n### Optional Database\n\n```bash\nNODE_ENV=development\n\nPORT=3001\nPUBLICWEB=./publicweb\n\nCOSMOSDB_ACCOUNT=your_cosmos_account\nCOSMOSDB_DB=your_cosmos_db\nCOSMOSDB_KEY=your_cosmos_key\nCOSMOSDB_PORT=10255\n```\n\nOut of the box you can run the demo with an in memory data service instead of a live database. If you wish to use a database, you can set up a local mongo server or a remote CosmosDB/MongoDB server in the cloud.\n\n1. Configure Cosmos DB server settings\n\n   Copy the contents from `.env.example` into `.env`. Replace the values with your specific configuration. Don't worry, this file is in the `.gitignore` so it won't get pushed to github.\n\n   ```javascript\n   NODE_ENV=development\n\n   PORT=3001\n   PUBLICWEB=./publicweb\n\n   COSMOSDB_ACCOUNT=your_cosmos_account\n   COSMOSDB_DB=your_cosmos_db\n   COSMOSDB_KEY=your_cosmos_key\n   COSMOSDB_PORT=10255\n   ```\n--\u003e\n\n## Troubleshooting\n\n### Installation\n\n1.  If you are on Windows and run into this error during `npm install`: _\"snyk couldn't patch the specified vulnerabilities because gnu's patch is not available\"_, refer to this [issue](https://github.com/linnovate/mean/issues/1711) for the fix. In short, your `Git` installation is not correct or `C:\\Program Files\\Git\\usr\\bin` (typically) is not added to your system environment variable `%PATH%`.\n\n## Problems or Suggestions\n\n[Open an issue here](https://github.com/johnpapa/angular-ngrx-data/issues)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnpapa%2Fangular-ngrx-data","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnpapa%2Fangular-ngrx-data","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnpapa%2Fangular-ngrx-data/lists"}