grape-transformations 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 16befd94dc2420bbfb79747c0e0231f00b4594a1
+  data.tar.gz: 03e6b12432f44d2c8cc0276e0cd656453e0bc25d
+SHA512:
+  metadata.gz: 842c56ccc9ffd37e7f4c8a7d440ee06be7ab8358168137a300c5212ad4603a5105bc32891f9ed7b10fb7f3ac331066994f024c410f462d7cf28e34ab6a8abd0f
+  data.tar.gz: 1bb9ed0dbb2697306db84ec13033aebb1082edbf258243e5dd93cffab8bb448c4e42f84ff1ac2c387e0cdb9abbc86954251257b3872e11f5c935c6a2f9f62cd2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Johan Tique, Miguel Diaz
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,3 @@
+= Grape Transformations
+
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,19 @@
+require "bundler/gem_tasks"
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'grape-transformations'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks

data/lib/grape/generators/templates/entity.rb

@@ -0,0 +1,12 @@
+module <%= app_name.classify %>
+  module Entities
+    module <%= entity_name.classify.pluralize %>
+      class Default < Grape::Entity
+        <% fields.each do |field| %>
+          <% attribute, type = field.split(':')%>
+          expose :<%= attribute %>, documentation: { type: '<%= type %>', desc: 'write a description here', example: 'write an example here' }
+        <% end %>
+      end
+    end
+  end
+end

data/lib/grape/generators/templates/grape-transformations.rb

@@ -0,0 +1,4 @@
+# it loads automatically entities that are associated with models in your app
+Grape::Transformations.setup do |config|
+  config.load_entities_from File.join('<%= app_name %>', 'entities')
+end

data/lib/grape/generators/transformations/entity_generator.rb

@@ -0,0 +1,54 @@
+require 'rails/generators/base'
+
+module Grape
+  module Generators
+    module Transformations
+      class EntityGenerator < Rails::Generators::Base
+
+        desc <<-DESC.strip_heredoc
+          Create inherited Grape::Entity entity in your app/api/.../entities folder. this 
+          created entity will have related with grape-transformations naming conventions
+
+          For example:
+
+            rails generate entity user
+
+          This will create a entity class at app/api/.../entities/users/default.rb like this:
+
+            module TestApp
+              module Entities
+                module Users
+                  class Default < Grape::Entity
+                    
+                  end
+                end
+              end
+            end 
+        DESC
+
+        source_root File.expand_path('../../templates', __FILE__)
+
+        argument :entity_name, type: :string, required: true, desc: 'name of entity'
+        argument :fields, :type => :array, required: false, desc: 'field set that you want to expose'
+        
+        def generate_layout
+          @fields ||= []
+          template "entity.rb", "app/api/#{app_name}/entities/#{underscored_entity_name.pluralize}/default.rb"
+        end
+
+        private
+
+        # Returns the app name
+        # @return [String]
+        def app_name
+          Rails.application.config.session_options[:key].sub(/^_/,'').sub(/_session/,'')
+        end
+
+        def underscored_entity_name
+          entity_name.underscore
+        end
+
+      end
+    end
+  end
+end

data/lib/grape/generators/transformations/install_generator.rb

@@ -0,0 +1,29 @@
+require 'rails/generators/base'
+
+module Grape
+  module Generators
+    module Transformations
+      class InstallGenerator < Rails::Generators::Base
+
+        source_root File.expand_path("../../templates", __FILE__)
+
+        def copy_initializer
+          template "grape-transformations.rb", "config/initializers/grape-transformations.rb"
+        end
+
+        def generate_layout
+          create_file "app/api/#{app_name}/entities/.keep"
+        end
+
+        private
+
+        # Returns the app name
+        # @return [String]
+        def app_name
+          Rails.application.config.session_options[:key].sub(/^_/,'').sub(/_session/,'')
+        end
+
+      end
+    end
+  end
+end

data/lib/grape/tasks/grapi_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :transformations do
+#   # Task goes here
+# end

data/lib/grape/transformations/base.rb

@@ -0,0 +1,67 @@
+require 'active_support/concern'
+
+module Grape
+  module Transformations
+    module Base
+      extend ::ActiveSupport::Concern
+
+      module ClassMethods
+
+        # Defines the target model associated to current transformations
+        # @param [Class], Class as a reference of model, bear in mind that you 
+        # need to prefix the scope resolution operator at the beginning in order
+        # to point to the right model
+        # example:
+        #     target_model ::User
+        def target_model(klass)
+          @grape_transformations_target_class = klass
+        end
+
+        # Defines the endpoints that will use with the existing transformations
+        # @param [Proc], all code related with transformable endpoints definition
+        def define_endpoints(&block)
+          @grape_transformations_endpoints = block.to_proc
+        end
+
+        # Defines the endpoints that will use with the existing transformations
+        # @param [Proc], all code related with non transformable endpoints definition
+        def define_non_transformable_endpoints(&block)
+          @grape_transformations_non_transformable_endpoints = block.to_proc
+        end
+
+        # Invokes the block associated with transformable endpoints
+        # @param [Hash], options hash that contains entity transformation definition
+        def add_endpoints_with(options = {})
+          return unless @grape_transformations_endpoints.is_a? Proc
+          entity = options[:entity] || entity_for_transformation(:default)
+          @grape_transformations_endpoints.call(entity)
+        end
+
+        # Invokes the block associated with non transformable endpoints
+        def add_non_transformable_endpoints
+          return unless @grape_transformations_non_transformable_endpoints.is_a? Proc
+          @grape_transformations_non_transformable_endpoints.call
+        end
+
+        # Abstracts entity_for_transformation grape_transformations method using the grape_transformations_target_class variable
+        def entity_for_transformation(transformation)
+          Grape::Transformations.entity_for_transformation(@grape_transformations_target_class, transformation)
+        end
+
+        # Invokes both transformable and non-transformable body endpoints
+        def add_endpoints
+          # transformable endpoints
+          Grape::Transformations.transformations_for(@grape_transformations_target_class).each do |transformation|
+            entity = entity_for_transformation transformation
+            namespace transformation do
+              add_endpoints_with entity: entity
+            end
+          end
+          # normal api
+          add_endpoints_with entity: entity_for_transformation(:default) if Grape::Transformations.simbolized_entities_for(@grape_transformations_target_class).include? :default
+          add_non_transformable_endpoints
+        end
+      end
+    end
+  end
+end

data/lib/grape/transformations/engine.rb

@@ -0,0 +1,14 @@
+# Rails Engine
+
+module Grape
+  module Transformations
+    class Engine < ::Rails::Engine
+      # config.generators do |g|
+      #   g.test_framework      :rspec,        :fixture => false
+      #   g.fixture_replacement :factory_girl, :dir => 'spec/factories'
+      #   g.assets false
+      #   g.helper false
+      # end
+    end
+  end
+end

data/lib/grape/transformations/loader.rb

@@ -0,0 +1,86 @@
+module Grape
+  module Transformations
+    module Loader
+      # extend ActiveSupport::Autoload # TODO: Make entities autoloadable so that
+      # code is live reloaded in development mode
+
+      # Return a class by its name, id it is not valid
+      # it returns nil
+      # @param [String], full class name
+      # @return [Object]
+      def self.class_by_name(name)
+        name.safe_constantize
+      end
+
+      # Loads all valid entities located in relative_path_to_entities dir, it
+      # verifies if entity is valid and if it is associated with valid class.
+      # When this process is accomplished is saved a hash with classname as a
+      # key and its associated entity as a value (using Rails.cache)
+      # @param root_api_path [String], path to api dir
+      # @param relative_path_to_entities [String], relative path to entities
+      def self.load_entities(root_api_path, relative_path_to_entities)
+        available_entities = {}
+        path_to_entities = File.join(root_api_path, relative_path_to_entities)
+        api_entities_namespace = relative_path_to_entities.split('/').map { |module_name| module_name.gsub(' ','_').camelcase }.join('::')
+        Dir.glob(File.join(path_to_entities, '**', '*.rb')).each do |filename|
+          relative_path = filename.sub("#{path_to_entities}/", '')
+          class_hierarchy = relative_path.split("/").map {|filename| filename.gsub(' ','_').camelcase.sub('.rb','')}
+          class_name = class_hierarchy.join('::')
+          entity_name = "#{api_entities_namespace}::#{class_name}"
+          klass = class_by_name class_name
+          entity = class_by_name entity_name
+
+          # If there is a one to one match from Entities::..::Entity to ..::Klass, use it
+          if entity && klass
+            available_entities[class_name] = entity_name
+          else
+            # If not, try to find a "Default" transformation entity class
+            # namespaced in the pluralized klass
+
+            # An entity has to exist
+            if entity
+              # example: ['Admin', 'Billing', 'Addresses'], 'Default' = ['Admin', 'Billing', 'Addresses', 'Default']
+              *transformation_hierarchy, transformation_name = class_hierarchy
+
+              if transformation_name == 'Default'
+
+                # example: ['Admin', 'Billing'], 'Addresses' = ['Admin', 'Billing', 'Addresses']
+                *class_name_hierarchy, pluralized_transformable_class_name = transformation_hierarchy
+                # example: 'Address' = "Addresses".singularize
+                transformable_class_name = pluralized_transformable_class_name.singularize
+                # example: Admin::Billing::Address
+
+                class_name_hierarchy << transformable_class_name
+                class_name = class_name_hierarchy.join('::')
+                klass = class_by_name class_name
+                # example: Admin::Billing::Address
+
+                # a matching class was found
+                if klass
+                  available_entities[class_name] = entity_name
+                else
+                  # The entity is just an entity, no matching class... however seems like
+                  # conventions were not properly followed
+                end
+
+              else
+                # No one to one match or Default transformation found, no entity used
+              end
+            else
+              puts "[WARN] - Conventions not followed? - Entity #{entity_name} was not found at #{filename}, please check"
+            end
+          end
+
+        end
+        register_entities available_entities
+      end
+
+      private
+      # Saves entities in cache by using Rails.cache approach
+      def self.register_entities(available_entities)
+        Rails.cache.delete(:registered_entities) # make sure it is clean
+        Rails.cache.fetch(:registered_entities){ available_entities }
+      end
+    end
+  end
+end

data/lib/grape/transformations/version.rb

@@ -0,0 +1,5 @@
+module Grape
+  module Transformations
+    VERSION = "0.0.1"
+  end
+end

data/lib/grape/transformations.rb

@@ -0,0 +1,112 @@
+require 'grape/transformations/version'
+require 'grape/transformations/loader'
+require 'grape/transformations/base'
+require 'grape/transformations/engine' if defined?(Rails)
+require 'grape'
+require 'rails'
+
+module Grape
+  module Transformations
+    # Sets default api location ../app/api
+    mattr_accessor :root_api_path
+
+    # relative_path_to_entities
+    mattr_accessor :relative_path_to_entities
+
+    # Uses Loader.load_entities method in order to load all valid entities located
+    # in relative path_to_entities
+    def self.load_entities_from(relative_path_to_entities)
+      self.root_api_path ||= File.join(Rails.root, 'app', 'api')
+      self.relative_path_to_entities = relative_path_to_entities
+      Loader.load_entities root_api_path, relative_path_to_entities
+    end
+
+    # defines wrapped accessor to grape-transformations configurator
+    def self.setup
+      yield self
+    end
+
+    # returns entities registered from rails cache
+    def self.registered_entities
+      Rails.cache.fetch(:registered_entities)
+    end
+
+    # returns the appropite class for a class name or class
+    def self.registered_entity_for(klass)
+      registered_entities[normalized_class_name(klass)]
+    end
+
+    # @return [Class] the entity class for a given transformation
+    # example:
+    # entity_for_transformation(User, :full)
+    # #=> MyApp::Entities::Users::Full
+    def self.entity_for_transformation(klass, transformation)
+      entity_hierarchy = root_entity_namespace_hierarchy << normalized_class_name(klass).pluralize
+      entity_hierarchy << transformation.to_s.camelize
+      entity_hierarchy.join('::').constantize
+    end
+
+    # @return [Array] the top level module entity namespace wrapping
+    # example: ['MyApp', 'Entities']
+    def self.root_entity_namespace_hierarchy
+      File.split(relative_path_to_entities).map{|namespace| namespace.camelize}
+    end
+
+    # @return [String] the top level module namespacing to begin looking entities within
+    # example: "MyApp::Entities"
+    def self.root_entity_namespace
+      root_entity_namespace_hierarchy.join('::')
+    end
+
+    # @return [String] the absolute path to entities directory
+    def self.full_path_to_entities
+      File.join(root_api_path, relative_path_to_entities)
+    end
+
+    # @return [Array] all transformations listed as symbols (excludes :default)
+    def self.transformations_for(klass)
+      simbolized_entities_for(klass) - [:default] 
+    end
+
+    def self.simbolized_entities_for(klass)
+      class_name = normalized_class_name(klass)
+      entities_directory = File.join(full_path_to_entities, class_name.pluralize.underscore)
+      entity_files = Dir[File.join(entities_directory, '*')]
+      entity_files.map{|filename| File.split(filename).last.sub('.rb', '').to_sym}
+    end
+
+    # @return [Array] all entity classes including "Default" that relate to a given class
+    def self.all_entities_for(klass)
+      (transformations_for(klass) + [:default]).map{|transformation| entity_for_transformation(klass, transformation)}
+    end
+
+    # @return [Array] all entity classes except for "Default" that relate to a given class
+    def self.all_transformation_entities_for(klass)
+      all_entities_for(klass) - [entity_for_transformation(klass, :default)]
+    end
+
+    # return the class_name given a Class or :class or "class"...or anything like it
+    def self.normalized_class_name(klass)
+      klass.to_s.classify
+    end
+
+    # Monkey patch for Grape::Endpoint#present so that it
+    # autoloads a default entity when presenting a given class instance
+    ::Grape::Endpoint.send(:define_method, :present_with_autoload) do |instance, options = {}|
+      is_instance_a_set = false
+      is_instance_a_set = if defined? Mongoid
+        instance.kind_of?(Mongoid::Criteria)
+      elsif defined? ActiveRecord
+        instance.kind_of?(ActiveRecord::Relation)
+      end
+      is_instance_a_set ||= instance.kind_of?(Array)
+      klass = is_instance_a_set ? instance.first.class : instance.class
+      entity = Grape::Transformations.registered_entity_for klass
+      options[:with] = entity.constantize if options[:with].nil? && entity
+      present_without_autoload instance, options
+    end
+
+    ::Grape::Endpoint.alias_method_chain(:present, :autoload)
+
+  end
+end