Merge pull request #42 from pixelhandler/transform-attributes

Add transform methods for [de]serializing resource attributes

Author: pixelhandler

README.md

@@ -102,18 +102,17 @@ a specific specification for an API server without the need for an abstraction.
 
 **Does this implement all of the JSON API specification?**
 
-**Not yet**. The happy path for reading, creating, updating/patching, deleting
+**Most of it**. The happy path for reading, creating, updating/patching, deleting
 is ready, as well as patching relationships. No extension support has been worked
 on, e.g. [JSON Patch]. I would like to do that one day.
 
 **Is this lightweight? Relative to what?**
 
 **Yes**. With a server that follows the JSON API specification - it just works.
-This is a simple solution compared with starting from scratch using AJAX, or
-adapting Ember Data to work with the URLs. This solution provides a basic,
-timed caching solution to minimize requests, and leaves a more advanced caching
-strategy to the developer via a mixin. It does provide a `store` object that
-caches deserialized resources.
+This is a simple solution compared with starting from scratch using AJAX. This
+solution provides a basic, (timed) caching solution to minimize requests, and
+leaves a more advanced caching strategy to the developer via a mixin. It does
+provide a `store` object that caches deserialized resources.
 
 **Are included resources supported (side-loading)?**
 
@@ -259,11 +258,11 @@ Here is the blueprint for a `resource` (model) prototype:
 
 ```javascript
 import Ember from 'ember';
-import Resource from 'ember-jsonapi-resources/models/resource';
+import Resource from './resource';
 import { attr, hasOne, hasMany } from 'ember-jsonapi-resources/models/resource';
 
 export default Resource.extend({
-  type: '<%= entity %>',
+  type: '<%= resource %>',
   service: Ember.inject.service('<%= resource %>'),
 
   /*
@@ -281,7 +280,17 @@ export default Resource.extend({
 });
 ```
 
-The commented out code is an example of how to setup the relationships.
+The commented out code includes an example of how to setup the relationships
+and define your attributes. `attr()` can be used for any valid type, or you can
+specify a type, e.g. `attr('string')` or `attr('date')`. An attribute that is
+defined as a `'date'` type has a built in transform method to serialize and
+deserialize the date value. Typically the JSON value for a Date object is
+communicated in ISO format, e.g. "2015-08-25T22:05:37.393Z". The application
+serializer has methods for [de]serializing the date values between client and
+server. You can add your own transform methods based on the type of the
+attribute or based on the name of the attribute, the transform methods based on
+the name of the attribute will be called instead of any transform methods based
+on the type of the attribute.
 
 The relationships are async using promise proxy objects. So when a template accesses 
 the `resource`'s relationship a request is made for the relation.
@@ -310,6 +319,8 @@ var ENV = {
 };
 ```
 
+`MODEL_FACTORY_INJECTIONS` may be already set to `true` in the app/app.js file.
+
 Also, once you've generated a `resource` you can assign the URL.
 
 See this example: [tests/dummy/app/adapters/post.js](tests/dummy/app/adapters/post.js)
@@ -342,7 +353,9 @@ as needed to act as if the API server is running on your same domain.
 
 #### Authorization
 
-EJR by default will pick-up credentials saved on `localStorage['AuthorizationHeader']`. If you'd like to change this, for instance to make it work with `ember-simple-auth`, there's a [configurable mixin available](https://github.com/pixelhandler/ember-jsonapi-resources/wiki/Authorization).
+By default credentials stored at `localStorage['AuthorizationHeader']` will be used.
+If you'd like to change this, for instance to make it work with `ember-simple-auth`,
+there's a [configurable mixin available](https://github.com/pixelhandler/ember-jsonapi-resources/wiki/Authorization).
 
 #### Example JSON API 1.0 Document
 

addon/adapters/application.js

@@ -231,6 +231,7 @@ export default Ember.Object.extend(Ember.Evented, {
           return resp.json().then(function(json) {
             if (isUpdate) {
               _this.cacheUpdate({ meta: json.meta, data: json.data, headers: resp.headers });
+              json.data = _this.serializer.transformAttributes(json.data);
               resolve(json.data);
             } else {
               const resource = _this.serializer.deserialize(json);

addon/mixins/transforms.js

@@ -0,0 +1,27 @@
+/**
+  @module ember-jsonapi-resources
+  @submodule transforms
+**/
+
+import Ember from 'ember';
+import { dateTransform } from 'ember-jsonapi-resources/utils/transforms';
+
+export default Ember.Mixin.create({
+  /**
+    @method serializeDateAttribute
+    @param {Date|String} date
+    @return {String|Null} date value as ISO String for JSON payload, or null
+  */
+  serializeDateAttribute(date) {
+    return dateTransform.serialize(date);
+  },
+
+  /**
+    @method deserializeDateAttribute
+    @param {String} date usually in ISO format, must be a valid argument for Date
+    @return {Date|Null} date value from JSON payload, or null
+  */
+  deserializeDateAttribute(date) {
+    return dateTransform.deserialize(date);
+  }
+});

addon/serializers/application.js

@@ -35,7 +35,8 @@ export default Ember.Object.extend({
     @return {Object}
   */
   serializeResource(resource) {
-    const json = resource.getProperties('type', 'attributes', 'relationships');
+    let json = resource.getProperties('type', 'attributes', 'relationships');
+    json = this.transformAttributes(json, 'serialize');
     for (let relationship in json.relationships) {
       if (json.relationships.hasOwnProperty(relationship)) {
         delete json.relationships[relationship].links;
@@ -57,13 +58,15 @@ export default Ember.Object.extend({
   serializeChanged(resource) {
     let json = resource.getProperties('id', 'type', 'changedAttributes');
     if (Ember.isEmpty(Object.keys(json.changedAttributes))) { return null; }
-    return {
+    let serialized = {
       data: {
         type: json.type,
         id: json.id,
         attributes: json.changedAttributes
       }
     };
+    serialized.data = this.transformAttributes(serialized.data, 'serialize');
+    return serialized;
   },
 
   /**
@@ -105,6 +108,7 @@ export default Ember.Object.extend({
     @return {Resource}
   */
   deserializeResource(json) {
+    json = this.transformAttributes(json);
     return this._createResourceInstance(json);
   },
 
@@ -127,6 +131,47 @@ export default Ember.Object.extend({
     }
   },
 
+  /**
+    Transform attributes, serialize or deserialize by specified method or
+    per type of attribute, e.g. date.
+
+    Your serializer may define a specific method for a type of attribute,
+    i.e. `serializeDateAttribute` and/or `deserializeDateAttribute`. Likewise,
+    your serializer may define a specific method for the name of an attribute,
+    like `serializeUpdatedAtAttribute` and `deserializeUpdatedAtAttribute`.
+
+    During transformation a method based on the name of the attribute takes
+    priority over a transform method based on the type of attribute, e.g. date.
+
+    @method transformAttributes
+    @param {Object} json with attributes hash of resource properties to be transformed
+    @param {String} [operation='deserialize'] perform a serialize or deserialize
+      operation, the default operation is to deserialize when not passed
+    @return {Object} json
+  */
+  transformAttributes(json, operation = 'deserialize') {
+    assertTranformOperation(operation);
+    let transformMethod, factory, meta;
+    for (let attr in json.attributes) {
+      transformMethod = [operation, Ember.String.capitalize(attr), 'Attribute'].join('');
+      if (typeof this[transformMethod] === 'function') {
+        json.attributes[attr] = this[transformMethod](json.attributes[attr]);
+      } else {
+        try {
+          factory = this._lookupFactory(json.type);
+          meta = factory.metaForProperty(attr);
+          transformMethod = [operation, Ember.String.capitalize(meta.type), 'Attribute'].join('');
+          if (typeof this[transformMethod] === 'function') {
+            json.attributes[attr] = this[transformMethod](json.attributes[attr]);
+          }
+        } catch (e) {
+          continue; // metaForProperty has an assertion that may throw
+        }
+      }
+    }
+    return json;
+  },
+
   /**
     Create a Resource from a JSON API Resource Object
 
@@ -151,7 +196,22 @@ export default Ember.Object.extend({
         delete resource[prop];
       }
     }
-    let factoryName = 'model:' + json.type;
-    return this.container.lookupFactory(factoryName).create(resource);
+    return this._lookupFactory(json.type).create(resource);
+  },
+
+  /**
+    @private
+    @method _lookupFactory
+    @param {String} type
+    @return {Function} factory for creating resource instances
+  */
+  _lookupFactory(type) {
+    return this.container.lookupFactory('model:' + type);
   }
 });
+
+const tranformOperations = ['serialize', 'deserialize'];
+
+function assertTranformOperation(operation) {
+  Ember.assert(`${operation} is not a valid transform operation`, tranformOperations.indexOf(operation) > -1);
+}

addon/utils/transforms.js

@@ -0,0 +1,45 @@
+/**
+  @module ember-jsonapi-resources
+  @submodule utils
+**/
+
+import { isBlank, isType } from 'ember-jsonapi-resources/utils/is';
+
+/**
+  @class TransformDateAttribute
+*/
+class TransformDateAttribute {
+
+  /**
+    @method serialize
+    @param {Date|String} date
+    @return {String|Null} date value as ISO String for JSON payload, or null
+  */
+  serialize(date) {
+    if (isBlank(date) || date === '') {
+      date = null;
+    } else if (isType('date', date)) {
+      date = date.toISOString();
+    } else if (isType('string', date)) {
+      date = new Date(date);
+    }
+    return (date) ? date : null;
+  }
+
+  /**
+    @method serialize
+    @param {String} date usually in ISO format, must be a valid argument for Date
+    @return {Date|Null} date value from JSON payload, or null
+  */
+  deserialize(date) {
+    if (isBlank(date)) {
+      date = null;
+    } else if (isType('string', date) || isType('number', date)) {
+      date = new Date(date);
+    }
+    return (date) ? date : null;
+  }
+
+}
+
+export let dateTransform = new TransformDateAttribute();

app/mixins/transforms.js

@@ -0,0 +1 @@
+export { default } from 'ember-jsonapi-resources/mixins/transforms';

app/serializers/application.js

@@ -1 +1,10 @@
-export { default } from 'ember-jsonapi-resources/serializers/application';
+import TransformsMixin from '../mixins/transforms';
+import ApplicationSerializer from 'ember-jsonapi-resources/serializers/application';
+
+/**
+  Serializer for a JSON API resource, combines the addon ApplicationSerializer and TransformsMixin
+
+  @class ApplicationSerializer
+  @uses TransformsMixin
+*/
+export default ApplicationSerializer.extend(TransformsMixin);

fixtures/api/posts/1.json

@@ -10,7 +10,9 @@
       "slug": "practical-deploy-an-ember-app-with-ember-cli-deploy-on-digitalocean",
       "excerpt": "The notes below demonstrate how to setup a chat application, built with [Ember CLI], that uses a backend service from [Firebase].",
       "date": "2015-04-25",
-      "body": "## Lightning-Approach Workflow\n\nThis approach is the default setup when using ember-cli-deploy and uses a Redis\nstore for the versions of your index.html file that you deploy."
+      "body": "## Lightning-Approach Workflow\n\nThis approach is the default setup when using ember-cli-deploy and uses a Redis\nstore for the versions of your index.html file that you deploy.",
+      "created-at": "2015-04-25T00:00:00.000Z",
+      "updated-at": "2015-04-25T00:00:00.000Z"
     },
     "relationships": {
       "author": {

tests/dummy/app/adapters/post.js

@@ -1,7 +1,8 @@
 import ApplicationAdapter from './application';
 import config from '../config/environment';
+import AuthorizationMixin from '../mixins/authorization';
 
-export default ApplicationAdapter.extend({
+export default ApplicationAdapter.extend(AuthorizationMixin, {
   type: 'post',
 
   url: config.APP.API_PATH + '/posts',

tests/dummy/app/models/author.js

@@ -6,8 +6,8 @@ export default Resource.extend({
   type: 'author',
   service: Ember.inject.service('authors'),
 
-  name: attr(),
-  email: attr(),
+  name: attr('string'),
+  email: attr('string'),
 
   posts: hasMany('posts')
 });