api_presenter 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4779e47afef65722b830ee6c85455f3f9853cf40
-  data.tar.gz: f5b677a9c48fcac592de8b9e7e631f06924e3dd5
+  metadata.gz: eaf8be856cb0170356c5d277cbafaa8fa188e536
+  data.tar.gz: d8bdf073896bd010eb6ae4c82df92bbdc05e99b9
 SHA512:
-  metadata.gz: 5f3a9f458b103dbadea74c3844b129a53a9328af660e0bdca3215183c0ceccd92d97c9bc0a76050e1a0e6fcb13e331dcb9bc09a193d16041db20fa3b4baa181e
-  data.tar.gz: 91e99b5f3919c87cad9997a8d6341dd3cd613894c5f986e2a7b0feb1d47ca7a00c4f8d7bbfef3d5bf832fd3158b12f5415f4d6b4b3c59ac5e4248858862a3249
+  metadata.gz: 21e538cd8234557a3ccd599da45b9d8faf7ee313043b5ffe31e67047475ad7db44f601df1d1b105e83bf48edf1067a40e9ff98d99a59a77ea63101fd646191c0
+  data.tar.gz: 80c528d1d70fd8822922ffd76ba594aee3f0afdbf082d17d93e7d0b856b28574bff5bcca80cc13348387de29893e83a848aaedf9b5eb7dbae5fc57d4ea50307d

data/README.md

@@ -54,7 +54,7 @@ end
 
 When clients request posts (the primary collection), they may want any or all of the above data for those posts.
 
-### Create your Presenter
+### 1. Create your Presenter
 
 ```ruby
 class PostPresenter < ApiPresenter::Base
@@ -78,20 +78,20 @@ end
 
 Presenters can define up to three methods:
 
-* `associations_map` The includable resources for the ActiveRecord model (Post, in this case). Consists of the model name as key and traversla required to preload/load them. In most cases, the value of `associations` will correspond directly to associations on the primary model.
+* `associations_map` The includable resources for the ActiveRecord model (`Post`, in this case). Consists of the model name as key and traversal required to preload/load them. In most cases, the value of `associations` will correspond directly to associations on the primary model.
 * `policy_methods` A list of Pundit policy methods to resolve for the primary collection.
 * `policy_associations` Additional records to preload in order to optimize policies that must traverse asscoiations.
 
-### Enable your controllers
+### 2. Enable your controllers
 
-ApiPresenter provides a controller concern that executes the Presenter. This process analyzes your params, preloads records as needed, and produces a `@presenter` object you can work with.
+Your presentable collection can be an `ActiveRecord::Relation`, an array of records, or even a single record. Just call `present` on it. The preloads will be performed, and the included collections/policies will be available in the `@presenter` instance variable.
 
 ```ruby
 class ApplicationController
   include ApiPresenter::Concerns::Presentable
 end
 
-class PostsCOntroller < ApplicationController
+class PostsController < ApplicationController
   def index
     posts = PostQuery.records(current_user, params)
     present posts
@@ -104,7 +104,7 @@ class PostsCOntroller < ApplicationController
 end
 ```
 
-### Render the result
+### 3. Render the result
 
 How you ultimately render the primary collection and the data produced by ApiPresenter is up to you. `@presenter` has the following properties:
 
@@ -125,6 +125,22 @@ end
 json.partial!("api/shared/included_collections_and_meta", presenter: @presenter)
 ```
 
+### api/posts/show.json.jbuilder
+
+```ruby
+json.post do
+  json.partial!(@post)
+end
+json.partial!("api/shared/included_collections_and_meta", presenter: @presenter)
+```
+
+```ruby
+json.posts(@presenter.collection) do |post|
+  json.partial!(post)
+end
+json.partial!("api/shared/included_collections_and_meta", presenter: @presenter)
+```
+
 ### api/shared/included_collections_and_meta
 
 ```ruby

data/lib/api_presenter.rb

@@ -1,10 +1,4 @@
 require 'pundit'
-require 'api_presenter/parse_include_params'
-require 'api_presenter/version'
-require 'api_presenter/concerns/presentable'
-require 'api_presenter/resolvers/base'
-require 'api_presenter/resolvers/policies_resolver'
-require 'api_presenter/resolvers/included_collections_resolver'
 
 module ApiPresenter
   class Base
@@ -202,3 +196,10 @@ module ApiPresenter
     end
   end
 end
+
+require 'api_presenter/parse_include_params'
+require 'api_presenter/version'
+require 'api_presenter/concerns/presentable'
+require 'api_presenter/resolvers/base'
+require 'api_presenter/resolvers/policies_resolver'
+require 'api_presenter/resolvers/included_collections_resolver'

data/lib/api_presenter/concerns/presentable.rb

@@ -0,0 +1,63 @@
+require 'active_support/concern'
+
+module ApiPresenter
+  module Concerns
+    module Presentable
+      extend ActiveSupport::Concern
+
+      private
+
+      # Instantiates presenter for the given relation, array of records, or single record
+      #
+      # @example Request with included records
+      #   GET /api/posts?include=categories,subCategories,users
+      #
+      # @example Request with policies
+      #   GET /api/posts?policies=true
+      #
+      # @example Request with included records and policies
+      #   GET /api/posts?include=categories,subCategories,users&policies=true
+      #
+      # @example Request with count only
+      #   GET /api/posts?count=true
+      #
+      # @example PostsController
+      #   include ApiPresenter::Concerns::Presentable
+      #
+      #   def index
+      #     posts = Post.page
+      #     present posts
+      #   end
+      #
+      #   def show
+      #     @post = Post.find(params[:id])
+      #     present @post
+      #   end
+      #
+      # @param relation_or_record [ActiveRecord::Relation, Array<ActiveRecord::Base>, ActiveRecord::Base]
+      #
+      def present(relation_or_record)
+        klass, relation = if relation_or_record.is_a?(ActiveRecord::Relation)
+          [relation_or_record.klass, relation_or_record]
+        else
+          record_array = Array.wrap(relation_or_record)
+          [record_array.first.class, record_array]
+        end
+
+        @presenter = presenter_klass(klass).call(
+          current_user: defined?(current_user) ? current_user : nil,
+          relation:     relation,
+          params:       params
+        )
+      end
+
+      # Progressive search for klass's Presenter
+      def presenter_klass(klass)
+        "#{klass.name}Presenter".safe_constantize ||
+        "#{klass.base_class.name}Presenter".safe_constantize ||
+        ApiPresenter::Base
+      end
+
+    end
+  end
+end

data/lib/api_presenter/parse_include_params.rb

@@ -0,0 +1,25 @@
+module ApiPresenter
+
+  # Parses values into array of acceptable association map keys:
+  # * Removes blanks and dups
+  # * Underscores camel-cased keys
+  # * Converts to symbol
+  #
+  # @param values [String, Array<String>, Array<Symbol>] Comma-delimited string or array
+  #
+  # @return [Array<Symbol>]
+  #
+  class ParseIncludeParams
+    def self.call(values)
+      return [] if values.blank?
+
+      array = values.is_a?(Array) ? values.dup : values.split(',')
+      array.select!(&:present?)
+      array.map! { |value| value.try(:underscore) || value }
+      array.uniq!
+      array.map!(&:to_sym)
+
+      array
+    end
+  end
+end

data/lib/api_presenter/resolvers/base.rb

@@ -0,0 +1,16 @@
+require 'active_support/core_ext/module'
+
+module ApiPresenter
+  module Resolvers
+    class Base
+
+      attr_reader :presenter
+
+      delegate :current_user, :relation, to: :presenter
+
+      def initialize(presenter)
+        @presenter = presenter
+      end
+    end
+  end
+end

data/lib/api_presenter/resolvers/included_collections_resolver.rb

@@ -0,0 +1,125 @@
+module ApiPresenter
+  module Resolvers
+    # Handles loading of associated collections and policies, or counts,
+    # for the given collection or single record.
+    class IncludedCollectionsResolver < Resolvers::Base
+
+      attr_reader :resolved_collections
+
+      delegate :associations_map, :included_collection_names, to: :presenter
+
+      # @param presenter [ApiPresenter::Base]
+      def initialize(presenter)
+        super(presenter)
+        preload if relation.is_a?(ActiveRecord::Relation) && resolved_associations_map.any?
+      end
+
+      def call
+        resolve_collections
+        self
+      end
+
+      private
+
+      # ActiveRecord preload of included collections
+      def preload
+        presenter.preload(resolved_associations_map.flat_map {|k,v| v[:associations]})
+      end
+
+      # Whitelists included collections against classes that current_user is permitted to see and any specified conditions
+      #
+      # @param association_keys [Array]
+      #
+      # @return [Hash] Whitelisted copy of `associations_map`
+      #
+      def resolved_associations_map
+        @resolved_associations_map ||= included_collection_names.inject({}) do |hash, included_collection_name|
+          if resolve_collection?(included_collection_name)
+            hash[included_collection_name] = { associations: associations_map[included_collection_name][:associations] }
+          end
+          hash
+        end
+      end
+
+      def resolve_collection?(included_collection_name)
+        associations_map[included_collection_name] &&
+        collection_policy_permits?(included_collection_name) &&
+        collection_condition_permits?(included_collection_name)
+      end
+
+      # Runs policy check to ensure current_user is allowed to view objects of the given type
+      # TODO: configuration to allow pass if no policy defined, with configurable warning log
+      def collection_policy_permits?(included_collection_name)
+        Pundit.policy(current_user, included_collection_name.to_s.classify.constantize).index?
+      end
+
+      # Runs check on included association condition if present.
+      #
+      # Conditions can be either a string, which will be interpolated, or
+      # a symbol, which will execute the corresponding method. Both
+      # options must return a truthy result.
+      #
+      # @example String condition
+      #   def associations_map
+      #     {
+      #       categories: { associations: :category, condition: 'current_user.admin?' }
+      #     }
+      #   }
+      #
+      # @example Method condition
+      #   def associations_map
+      #     {
+      #       categories: { associations: :category, condition: :admin? }
+      #     }
+      #   }
+      #
+      # @return [Boolean]
+      def collection_condition_permits?(included_collection_name)
+        if (condition = associations_map[included_collection_name][:condition])
+          if condition.is_a?(String)
+            presenter.instance_eval(condition)
+          elsif condition.is_a?(Symbol)
+            presenter.send(condition)
+          end
+        else
+          true
+        end
+      end
+
+      # Map requested collections from relation
+      def resolve_collections
+        @resolved_collections = resolved_associations_map.inject({}) do |hash, (k,v)|
+          collection_records = []
+          collection_associations = Array.wrap(v[:associations])
+          collection_associations.each do |association|
+            add_records_from_collection_association(relation, association, collection_records)
+          end
+          collection_records.flatten!
+          collection_records.compact!
+          collection_records.uniq!
+          hash[k] = collection_records
+          hash
+        end
+      end
+
+      # Recursive method that traverses n-nested associations to get at the requested records
+      #
+      # @param current_relation   [ActiveRecord::Relation]  Original relation or nested association, changes during recursion
+      # @param association        [Symbol, Hash]            Source association key or nested hash association
+      # @param collection_records [Array]                   Concatenated included collection records
+      #
+      def add_records_from_collection_association(current_relation, association, collection_records)
+        if association.is_a?(Hash)
+          association.each do |k,v|
+            nested_association = current_relation.flat_map { |record| record.send(k) }.compact.uniq
+            Array.wrap(v).each do |nested_association_association|
+              add_records_from_collection_association(nested_association, nested_association_association, collection_records)
+            end
+          end
+        else
+          collection_records << current_relation.map { |record| record.send(association) }
+        end
+      end
+    end
+  end
+end

data/lib/api_presenter/resolvers/policies_resolver.rb

@@ -0,0 +1,66 @@
+module ApiPresenter
+  module Resolvers
+    class PoliciesResolver < Resolvers::Base
+
+      attr_reader :presenter, :resolved_policies
+
+      delegate :policy_associations, :policy_methods, to: :presenter
+
+      # Optimally resolves designated policies for current_user and supplied records.
+      #
+      # Use where it is desirable for an API response to include permissions (policy)
+      # metadata so that a client can correctly present resource actions.
+      #
+      # Initialize and preload policy associations for the given relation
+      #
+      # @param presenter [ApiPresenter::Base]
+      def initialize(presenter)
+        super(presenter)
+        preload if relation.is_a?(ActiveRecord::Relation) && policy_associations.present?
+      end
+
+      # Resolves policies and combines them into an id-based hash
+      #
+      # @return [PolicyPresenter::Base]
+      #
+      def call
+        resolve_policies
+        self
+      end
+
+      private
+
+      # Preload any associations required to optimize policy methods that traverse models
+      def preload
+        presenter.preload(policy_associations)
+      end
+
+      # Run policies for each record in the relation
+      def resolve_policies
+        @resolved_policies = relation.map do |record|
+          policy_definition = Pundit.policy(current_user, record)
+          record_policies = { :"#{id_attribute}" => record.id }
+          Array.wrap(policy_methods).each do |policy_method|
+            record_policies[policy_method] = policy_definition.send("#{policy_method}?")
+          end
+          record_policies
+        end
+      end
+
+      # @example Post -> "post_id"
+      #
+      # @return [String]
+      #
+      def id_attribute
+        @id_attribute ||= begin
+          klass = if relation.is_a?(ActiveRecord::Relation)
+            relation.klass
+          else
+            relation.first.class
+          end
+          "#{klass.base_class.name.underscore}_id"
+        end
+      end
+    end
+  end
+end

data/lib/api_presenter/version.rb

@@ -1,3 +1,3 @@
 module ApiPresenter
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_presenter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yuval Kordov
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-10-28 00:00:00.000000000 Z
+date: 2016-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -128,6 +128,11 @@ files:
 - bin/console
 - bin/setup
 - lib/api_presenter.rb
+- lib/api_presenter/concerns/presentable.rb
+- lib/api_presenter/parse_include_params.rb
+- lib/api_presenter/resolvers/base.rb
+- lib/api_presenter/resolvers/included_collections_resolver.rb
+- lib/api_presenter/resolvers/policies_resolver.rb
 - lib/api_presenter/version.rb
 homepage: http://github.com/uberllama/api_presenter
 licenses: