https://github.com/trackableentities/trackable-entities-js
Base classes that track change state when properties are updated and objects are added or removed objects from collections.
https://github.com/trackableentities/trackable-entities-js
angular change-tracking map observables proxies set
Last synced: 12 months ago
JSON representation
Base classes that track change state when properties are updated and objects are added or removed objects from collections.
- Host: GitHub
- URL: https://github.com/trackableentities/trackable-entities-js
- Owner: TrackableEntities
- License: mit
- Created: 2017-09-13T23:16:51.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2023-02-27T16:42:09.000Z (about 3 years ago)
- Last Synced: 2024-04-25T13:40:56.791Z (almost 2 years ago)
- Topics: angular, change-tracking, map, observables, proxies, set
- Language: TypeScript
- Homepage:
- Size: 4.31 MB
- Stars: 11
- Watchers: 2
- Forks: 2
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# trackable-entities-js
Base classes that track change state when properties are updated and objects are added or removed objects from collections.
[](https://travis-ci.org/TrackableEntities/trackable-entities-js)
[](https://badge.fury.io/js/trackable-entities)
Docs:
Sample application:
> Note: You must change the TypeScript compiler target to "es2015" in **ts.config.json**.
> - Apps using trackable-entities can support most modern browsers (Chrome, Firefox, Safari, Edge, etc), but they will not be able to support legacy browsers (Internet Explorer).
## Setup
Install **trackable-entities** as a runtime dependency from npm.
```
npm i --save trackable-entities
```
## Usage
To track property changes on an object, create a class that extends `TrackableEntity`. Then add a `constructor` that returns `super.proxify(this)`. For example:
```js
export class Product extends TrackableEntity {
productId: number;
productName: string;
unitPrice: number;
constructor() {
super();
return super.proxify(this);
}
}
```
Then set the `tracking` property to `true`. Modifying property values will change the `trackingState` from `Unchanged` to `Modified` and will populate the `modifiedProperties` collection with the names of properties that were changed, so that partial updates (PATCH) may be performed by an API that knows how to apply changes to a persistence store such as a database.
```js
// Product extends TrackableEntity
product = new Product(1, 'Bacon', 1);
// Turn on change tracking
product.tracking = true;
// Modify a property
product.productName = 'Peas';
// Tracking state is set to Modified
expect(product.trackingState).toEqual(TrackingState.Modified);
// Name of modified properties are tracked
expect(product.modifiedProperties.has('productName')).toBeTruthy();
```
There are two collections that support change tracking: `TrackableSet` which extends `Set`, and `TrackableMap` which extends `Map`. When items are added their `trackingState` is set to `Added`, and when items are deleted their `trackingState` is set to `Deleted`.
```js
// Create a new TrackableSet of products
const products = [
new Product(1, 'Bacon', 1),
new Product(2, 'Lettuce', 2),
new Product(3, 'Tomatoes', 3),
];
const trackableProducts = new TrackableSet(...products);
// Turn on change tracking
product.tracking = true;
// Add an entity
const addedProduct = new Product(4, 'Carrots', 4);
trackableProducts.add(addedProduct);
// Tracking state is set to Added
expect(addedProduct.trackingState).toEqual(TrackingState.Added);
// Remove an entity
const removedProduct = new Product(4, 'Carrots', 4);
trackableProducts.delete(removedProduct);
// Tracking state is set to Added
expect(removedProduct.trackingState).toEqual(TrackingState.Deleted);
```
## Persistence
Once the tracking state of entities have been set, you can pass them to a Web API where they can be persisted to a data store. [Trackable Entities](http://trackableentities.github.io) has a server-side [NuGet package](https://www.nuget.org/packages/TrackableEntities.EF.6) for persisting changes to a relational data store using [Entity Framework](https://docs.microsoft.com/en-us/ef/). The current version supports the full .NET Framework with EF 6, and a future version will support [.NET Core](https://www.microsoft.com/net/core) and EF Core as a [NetStandard](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) library.
## Roadmap
We are currently developing the full API for **trackable-entities**. See the project [roadmap](https://github.com/TrackableEntities/trackable-entities-js/wiki/Roadmap) for more information.
## Contributing
If you'd like to help with this project, please contact @tonysneed via email (tony@tonysneed.com) or twitter (@tonysneed).