angular-identity-map

angular-identity-map

An identity map pattern implementation for AngularJS applications.

Requirements

AngularJS v1.0+ traverse

Getting started

with bower

Just include "angular-identity-map" to your dependencies list and run bower install

with npm

npm install angular-identity-map

manually

Download angular-identity-map.js and include it on your page along with AngularJS Add identity-map to your module dependencies

angular.module('myApp', ['identity-map']);

Usage

Pre-requirements

All objects you want to map must have id attribute and class_name attribute in order to retrieve object identification pair. This pair (class_name, id) MUST be unique. Both these behaviors can be customized. See Configuration chapter below.

All you need is .map

var myAppModule = angular.module("MyApp", ["identity-map"]);
 
myAppModule.controller("myController", function($scope, IdentityMap) {
  $scope.phoneList = [
    {id: 1, class_name: 'Phone', name: 'Emergency', value: '911'}
  ];
  IdentityMap.map($scope.phoneList);
  
  //Let's assume you somehow retrieved new phone list e.g. by using Restangular
   newPhoneList = [
     {id: 1, class_name: 'Phone', name: 'Emergency', value: 'call-911'},
     {id: 2, class_name: 'Phone', name: 'Mommy', value: '12345'}
   ];
   IdentityMap.map(newPhoneList); 
   $scope.phoneList[0].value; // "call-911"
   //However your $scope.phoneList still has 1 item, while newPhoneList has 2 items. 
   //Remember, IdentityMap stores objects only.
}

You can see and play around with live demo!

Others methods for those, who want to dig deeply into identity map

There are several methods available such as .get, .set, .detach, .clear etc. Check out the source code for more information.

Configuration

identity-map stores and retrieves object using object type and object id. By default object id is retrieved by calling id attribute on an object. Object type retrieved by calling class_name attribute on an object. These functions are configurable in service provider: Example:

app.config(function(IdentityMapProvider) {
  //retrieves object type for mapping from object constructor name.
  IdentityMapProvider.setEntityTypeFn(function(entity) { 
    return entity.constructor.name; 
  });
  //retrieves object id for mapping by calling "getGlobalId" function.
  IdentityMapProvider.setEntityFn(function(type, entity) { 
      return entity.getGlobalId(); 
    });  
});

Please pay attention to couple requirements for these functions:

1. Any pair of (entityType, entityId) values MUST represent one and only one entity object.
2. Both functions accept one param which is guaranteed to be an object. If entity param is not a mappable object both functions MUST return undefined.

More examples can be found in spec/IdentityMap_spec.coffee

Integration with Restangular

"identity-map" can be integrated with Restangular easily. You just need to add simple response interceptor to Restangular stack:

angular.module('myApp', ['restangular', 'identity-map']).run(
function (Restangular, IdentityMap) {
  Restangular.addResponseInterceptor(
    function (data, operation, what, url, response, deffered) {
      return IdentityMap.map(data);
    }
  );
});

Starting from now any Restangular response with "mappable" objects will be mapped automatically.

Development

Code quality is ensured with CoffeeScript, CoffeeLint, and Karma.

npm install -g grunt-cli
npm install && bower install
grunt

Live Reloading

grunt karma:unit:start watch

Build

grunt dist

TODO

See issues list

Contribute

1. Fork
2. Code
3. Submit PR

License

MIT