Nobody Publish Monsters

    angular-identity-map

    0.2.1 • Public • Published

    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

    Install

    npm i angular-identity-map

    DownloadsWeekly Downloads

    6

    Version

    0.2.1

    License

    MIT

    Last publish

    Collaborators

    • pluff