Adds Entity class for lightweight representation building.

Author: Michael Bleigh

lib/grape.rb

@@ -2,11 +2,12 @@
 require 'rack/builder'
 
 module Grape
-  autoload :API, 'grape/api'
-  autoload :Endpoint, 'grape/endpoint'
+  autoload :API,             'grape/api'
+  autoload :Endpoint,        'grape/endpoint'
   autoload :MiddlewareStack, 'grape/middleware_stack'
-  autoload :Client, 'grape/client'
-  autoload :Route, 'grape/route'
+  autoload :Client,          'grape/client'
+  autoload :Route,           'grape/route'
+  autoload :Entity,          'grape/entity'
 
   module Middleware
     autoload :Base,      'grape/middleware/base'

lib/grape/entity.rb

@@ -0,0 +1,153 @@
+require 'hashie'
+
+module Grape
+  # An Entity is a lightweight structure that allows you to easily 
+  # represent data from your application in a consistent and abstracted
+  # way in your API.
+  #
+  # @example Entity Definition
+  #
+  #   module API
+  #     module Entities
+  #       class User < Grape::Endpoint
+  #         expose :name, :screen_name, :location
+  #         expose :latest_status, :using => API::Status, :as => :status, :unless => {:collection => true}
+  #         expose :email, :if => {:type => :full}
+  #         expose :new_attribute, :if => {:version => 'v2'}
+  #       end
+  #     end
+  #   end
+  #
+  # Entities are not independent structures, rather, they create 
+  # **representations** of other Ruby objects using a number of methods
+  # that are convenient for use in an API. Once you've defined an Entity,
+  # you can use it in your API like this:
+  #
+  # @example Usage in the API Layer
+  #
+  #   module API
+  #     class Users < Grape::API
+  #       version 'v2'
+  #
+  #       get '/users' do
+  #         @users = User.all
+  #         type = current_user.admin? ? :full : :default
+  #         present @users, :with => API::Entities::User, :type => type
+  #       end
+  #     end
+  #   end
+  class Entity
+    attr_reader :object, :options
+
+    # This method is the primary means by which you will declare what attributes
+    # should be exposed by the entity.
+    #
+    # @option options :as Declare an alias for the representation of this attribute.
+    # @option options :if When passed a Hash, the attribute will only be exposed if the
+    #   runtime options match all the conditions passed in. When passed a lambda, the
+    #   lambda will execute with two arguments: the object being represented and the
+    #   options passed into the representation call. Return true if you want the attribute
+    #   to be exposed.
+    # @option options :unless When passed a Hash, the attribute will be exposed if the
+    #   runtime options fail to match any of the conditions passed in. If passed a lambda,
+    #   it will yield the object being represented and the options passed to the
+    #   representation call. Return true to prevent exposure, false to allow it.
+    # @option options :using This option allows you to map an attribute to another Grape
+    #   Entity. Pass it a Grape::Entity class and the attribute in question will 
+    #   automatically be transformed into a representation that will receive the same
+    #   options as the parent entity when called. Note that arrays are fine here and
+    #   will automatically be detected and handled appropriately.
+    def self.expose(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+
+      if options[:as] && args.size > 1
+        raise ArgumentError, "You may not use the :as option on multi-attribute exposures."
+      end
+
+      args.each do |attribute|
+        exposures[attribute.to_sym] = options
+      end
+    end
+
+    # Returns a hash of exposures that have been declared for this Entity. The keys
+    # are symbolized references to methods on the containing object, the values are
+    # the options that were passed into expose.
+    def self.exposures
+      (@exposures ||= {})
+    end
+
+    # This convenience method allows you to instantiate one or more entities by
+    # passing either a singular or collection of objects. Each object will be
+    # initialized with the same options. If an array of objects is passed in,
+    # an array of entities will be returned. If a single object is passed in,
+    # a single entity will be returned.
+    #
+    # @param objects [Object or Array] One or more objects to be represented.
+    # @param options [Hash] Options that will be passed through to each entity
+    #   representation.
+    def self.represent(objects, options = {})
+      if objects.is_a?(Array)
+        objects.map{|o| self.new(o, {:collection => true}.merge(options))}
+      else
+        self.new(objects, options)
+      end
+    end
+
+    def initialize(object, options = {})
+      @object, @options = object, options
+    end
+
+    def exposures
+      self.class.exposures
+    end
+
+    # The serializable hash is the Entity's primary output. It is the transformed
+    # hash for the given data model and is used as the basis for serialization to
+    # JSON and other formats.
+    #
+    # @param options [Hash] Any options you pass in here will be known to the entity
+    #   representation, this is where you can trigger things from conditional options
+    #   etc.
+    def serializable_hash(options = {})
+      exposures.inject({}) do |output, (attribute, exposure_options)|
+        output[key_for(attribute)] = value_for(attribute) if conditions_met?(exposure_options, options)
+        output
+      end
+    end
+
+    alias :as_json :serializable_hash
+
+    protected
+
+    def key_for(attribute)
+      exposures[attribute.to_sym][:as] || attribute.to_sym
+    end
+
+    def value_for(attribute)
+      exposure_options = exposures[attribute.to_sym]
+
+      if exposure_options[:using]
+        exposure_options[:using].represent(object.send(attribute))
+      else
+        object.send(attribute)
+      end
+    end
+
+    def conditions_met?(exposure_options, options)
+      if_condition = exposure_options[:if]
+      unless_condition = exposure_options[:unless]
+
+      case if_condition
+        when Hash; if_condition.each_pair{|k,v| return false if options[k.to_sym] != v }
+        when Proc; return false unless if_condition.call(object, options)
+      end
+
+      case unless_condition
+        when Hash; unless_condition.each_pair{|k,v| return false if options[k.to_sym] == v}
+        when Proc; return false if unless_condition.call(object, options)
+      end
+
+      true
+    end
+  end
+end

spec/grape/entity_spec.rb

@@ -0,0 +1,152 @@
+require 'spec_helper'
+
+describe Grape::Entity do
+  let(:fresh_class){ Class.new(Grape::Entity) }
+
+  context 'class methods' do
+    subject{ fresh_class }
+
+    describe '.expose' do
+      context 'multiple attributes' do
+        it 'should be able to add multiple exposed attributes with a single call' do
+          subject.expose :name, :email, :location
+          subject.exposures.size.should == 3
+        end
+
+        it 'should set the same options for all exposures passed' do
+          subject.expose :name, :email, :location, :foo => :bar
+          subject.exposures.values.each{|v| v.should == {:foo => :bar}}
+        end
+      end
+
+      context 'option validation' do
+        it 'should make sure that :as only works on single attribute calls' do
+          expect{ subject.expose :name, :email, :as => :foo }.to raise_error(ArgumentError)
+          expect{ subject.expose :name, :as => :foo }.not_to raise_error
+        end
+      end
+    end
+
+    describe '.represent' do
+      it 'should return a single entity if called with one object' do
+        subject.represent(Object.new).should be_kind_of(subject)
+      end
+
+      it 'should return multiple entities if called with a collection' do
+        representation = subject.represent(4.times.map{Object.new})
+        representation.should be_kind_of(Array)
+        representation.size.should == 4
+        representation.reject{|r| r.kind_of?(subject)}.should be_empty
+      end
+
+      it 'should add the :collection => true option if called with a collection' do
+        representation = subject.represent(4.times.map{Object.new})
+        representation.each{|r| r.options[:collection].should be_true}
+      end
+    end
+
+    describe '#initialize' do
+      it 'should take an object and an optional options hash' do
+        expect{ subject.new(Object.new) }.not_to raise_error
+        expect{ subject.new }.to raise_error(ArgumentError)
+        expect{ subject.new(Object.new, {}) }.not_to raise_error
+      end
+
+      it 'should have attribute readers for the object and options' do
+        entity = subject.new('abc', {})
+        entity.object.should == 'abc'
+        entity.options.should == {}
+      end
+    end
+  end
+
+  context 'instance methods' do
+    let(:model){ mock(attributes) }
+    let(:attributes){ {
+      :name => 'Bob Bobson', 
+      :email => '[email protected]',
+      :friends => [
+        mock(:name => "Friend 1", :email => '[email protected]', :friends => []), 
+        mock(:name => "Friend 2", :email => '[email protected]', :friends => [])
+      ]
+    } }
+    subject{ fresh_class.new(model) }
+
+    describe '#serializable_hash' do
+    end
+
+    describe '#value_for' do
+      before do
+        fresh_class.class_eval do
+          expose :name, :email
+          expose :friends, :using => self
+        end
+      end
+
+      it 'should pass through bare expose attributes' do
+        subject.send(:value_for, :name).should == attributes[:name]
+      end
+
+      it 'should instantiate a representation if that is called for' do
+        rep = subject.send(:value_for, :friends)
+        rep.reject{|r| r.is_a?(fresh_class)}.should be_empty
+        rep.first.serializable_hash[:name].should == 'Friend 1'
+        rep.last.serializable_hash[:name].should == 'Friend 2'
+      end
+    end
+
+    describe '#key_for' do
+      it 'should return the attribute if no :as is set' do
+        fresh_class.expose :name
+        subject.send(:key_for, :name).should == :name
+      end
+
+      it 'should return a symbolized version of the attribute' do
+        fresh_class.expose :name
+        subject.send(:key_for, 'name').should == :name
+      end
+
+      it 'should return the :as alias if one exists' do
+        fresh_class.expose :name, :as => :nombre
+        subject.send(:key_for, 'name').should == :nombre
+      end
+    end
+
+    describe '#conditions_met?' do
+      it 'should only pass through hash :if exposure if all attributes match' do
+        exposure_options = {:if => {:condition1 => true, :condition2 => true}}
+
+        subject.send(:conditions_met?, exposure_options, {}).should be_false
+        subject.send(:conditions_met?, exposure_options, :condition1 => true).should be_false
+        subject.send(:conditions_met?, exposure_options, :condition1 => true, :condition2 => true).should be_true
+        subject.send(:conditions_met?, exposure_options, :condition1 => false, :condition2 => true).should be_false
+        subject.send(:conditions_met?, exposure_options, :condition1 => true, :condition2 => true, :other => true).should be_true
+      end
+
+      it 'should only pass through proc :if exposure if it returns truthy value' do
+        exposure_options = {:if => lambda{|obj,opts| opts[:true]}}
+
+        subject.send(:conditions_met?, exposure_options, :true => false).should be_false
+        subject.send(:conditions_met?, exposure_options, :true => true).should be_true
+      end
+
+      it 'should only pass through hash :unless exposure if any attributes do not match' do
+        exposure_options = {:unless => {:condition1 => true, :condition2 => true}}
+
+        subject.send(:conditions_met?, exposure_options, {}).should be_true
+        subject.send(:conditions_met?, exposure_options, :condition1 => true).should be_false
+        subject.send(:conditions_met?, exposure_options, :condition1 => true, :condition2 => true).should be_false
+        subject.send(:conditions_met?, exposure_options, :condition1 => false, :condition2 => true).should be_false
+        subject.send(:conditions_met?, exposure_options, :condition1 => true, :condition2 => true, :other => true).should be_false
+        subject.send(:conditions_met?, exposure_options, :condition1 => false, :condition2 => false).should be_true
+      end
+
+      it 'should only pass through proc :unless exposure if it returns falsy value' do
+        exposure_options = {:unless => lambda{|object,options| options[:true] == true}}
+
+        subject.send(:conditions_met?, exposure_options, :true => false).should be_true
+        subject.send(:conditions_met?, exposure_options, :true => true).should be_false
+      end
+    end
+  end
+end