rails-surrender 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 06b60d3e2d458b2bc4d683990a6542e73291f3a3b97be987a0bd069732a885d8
+  data.tar.gz: 56a20555312a69afbd2f8e27dfa5f52d1e76adc8033dd1b0fd994dd20e0d2f27
+SHA512:
+  metadata.gz: 1bf619637f8644ba084faf242a70b8f71a44e210b2f52477988b651bca5598eb7aa860b3d203b749039d6da2483e5e84bc6ee277a84ef52350a17e0de83efe58
+  data.tar.gz: 12eef2b6c7587faedb212037ea786d4a056650be3faf3583b9e73625e1cb5b58a8d11de069c1248604e3bac320bffd123b4237ec059cf9ef68e4d4e777a3b05f

data/lib/rails/surrender/config/initializers/active_record_associations_patch.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+#
+# ActiveRecord::Associations.class_eval do
+#   # patching to prevent AssociationNotFoundError.
+#   # if there is no association just return nil instead
+#   def association(name) # :nodoc:
+#     super
+#   rescue AssociationNotFoundError
+#     return nil
+#   end
+# end
+#
+# ActiveRecord::Relation.class_eval do
+#   def eager_loading?
+#     false
+#   end
+# end

data/lib/rails/surrender/config/initializers/active_record_preloader_patch.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+#
+# ActiveRecord::Associations::Preloader.class_eval do
+#   # patching to ignore nil response from association method (also patched)
+#
+#   # if there is no association just return nil instead
+#   def grouped_records(association, records)
+#     h = {}
+#     records.each do |record|
+#       next unless record
+#
+#       assoc = record.association(association)
+#       next if assoc.nil?
+#
+#       klasses = h[assoc.reflection] ||= {}
+#       (klasses[assoc.klass] ||= []) << record
+#     end
+#     h
+#   end
+# end

data/lib/rails/surrender/config/locales/en.yml

@@ -0,0 +1,12 @@
+---
+en:
+  surrender:
+    error:
+      query_string:
+        incorrect_format: "The %{param} parameter was improperly formatted."
+        filter:
+          not_available: "%{param} is not a valid filter parameter."
+        include:
+          not_available: "%{param} is not a valid include parameter."
+        sort:
+          invalid_column: "%{param} is not a valid sort parameter."

data/lib/rails/surrender/controller_additions.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative 'helpers/query_param_parser'
+require_relative 'helpers/filter_builder'
+require_relative 'helpers/pagination_builder'
+require_relative 'helpers/sort_builder'
+
+module Rails
+  module Surrender
+    # Additions to the Rails ActionController to allow surrender's rendering.
+    module ControllerAdditions
+      def initialize(*args)
+        @will_paginate = true
+        super
+      end
+
+      def surrender(resource, status: 200, reload: true, include: [], exclude: [])
+        resource = filter resource if parsed_query_params.filter?
+
+        if parsed_query_params.sort?
+          resource = sort resource
+          response.headers['X-Sort'] = parsed_query_params.sort.request
+        end
+
+        if paginate?(resource)
+          resource = paginate resource
+          response.headers['X-Pagination'] = pagination_headers(resource)
+        end
+
+        surrender_response = if parsed_query_params.count?
+                               Render::Count.new(resource).parse
+                             elsif parsed_query_params.ids?
+                               Render::Ids.new(resource).parse
+                             else
+                               config = Render::Configuration.new(
+                                 resource_class: resource_class(resource),
+                                 reload_resource: reload,
+                                 user_exclude: parsed_query_params.exclude,
+                                 user_include: parsed_query_params.include,
+                                 ctrl_exclude: exclude,
+                                 ctrl_include: include
+                               )
+
+                               Render::Resource.new(resource: resource,
+                                                    ability: ability,
+                                                    config: config).parse
+                             end
+
+        # Allows the calling method to decorate the response data before returning the result
+        surrender_response.data = yield surrender_response.data if block_given?
+
+        render(json: surrender_response.json_data, status: status)
+      end
+
+      private
+
+      def ability
+        return current_ability if respond_to?(:current_ability)
+
+        DefaultAbility.new
+      end
+
+      def resource_class(resource)
+        resource.try(:klass) || resource.class
+      end
+
+      def skip_pagination
+        @will_paginate = false
+      end
+
+      def filter(resource)
+        FilterBuilder.new(resource: resource, filter: parsed_query_params.filter).build!
+      end
+
+      def paginate?(resource)
+        pagination(resource).paginatable? && @will_paginate
+      end
+
+      def paginate(resource)
+        pagination(resource).build!
+      end
+
+      def pagination(resource)
+        PaginationBuilder.new(resource: resource, pagination: parsed_query_params.pagination)
+      end
+
+      def pagination_headers(resource)
+        {
+          total: resource.total_count,
+          page_total: resource.count,
+          page: resource.current_page,
+          previous_page: resource.prev_page,
+          next_page: resource.next_page,
+          last_page: resource.total_pages,
+          per_page: parsed_query_params.pagination.per,
+          offset: resource.offset_value
+        }.to_json
+      end
+
+      def sort(resource)
+        SortBuilder.new(resource: resource, sort: parsed_query_params.sort).build!
+      end
+
+      def parsed_query_params
+        @parsed_query_params ||= QueryParamParser.new(request.query_parameters.symbolize_keys)
+      end
+    end
+  end
+end

data/lib/rails/surrender/default_ability.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    # If cancancan is not installed, this class will be instantiated to allow all models to render.
+    class DefaultAbility
+      def can?(*)
+        true
+      end
+    end
+  end
+end

data/lib/rails/surrender/exceptions.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    # Surrender's main error class.
+    class Error < StandardError
+    end
+  end
+end

data/lib/rails/surrender/helpers/filter_builder.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    # apply filtering directives to the given resource, based on the given filter controls
+    class FilterBuilder
+      attr_reader :resource, :filter
+
+      def initialize(resource:, filter:)
+        @resource = resource
+        @filter = filter
+      end
+
+      def build!
+        return resource unless resource.is_a?(ActiveRecord::Relation)
+
+        filter.each do |term|
+          scope, value = term.first
+
+          send_filter_for(scope, value)
+        end
+
+        resource
+      end
+
+      private
+
+      def send_filter_for(scope, value)
+        if resource.respond_to?(filter_method(scope))
+          # filter exists on model?
+          @resource = @resource.send(filter_method(scope), value)
+        elsif resource.respond_to?(filter_method_id(scope))
+          # resolved it by appending _id?
+          @resource = @resource.send(filter_method_id(scope), value)
+        else
+          raise Error, I18n.t('surrender.error.query_string.filter.not_available', param: scope)
+        end
+      end
+
+      # prepend filter_by so that only filter_by scope methods are reachable.
+      def filter_method(scope)
+        "filter_by_#{scope}".gsub('.', '_').to_sym
+      end
+
+      def filter_method_id(scope)
+        "#{filter_method(scope)}_id".to_sym
+      end
+    end
+  end
+end

data/lib/rails/surrender/helpers/pagination_builder.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    # apply pagination directives to the given resource, based on the given pagination controls
+    class PaginationBuilder
+      attr_reader :resource, :pagination
+
+      def initialize(resource:, pagination:)
+        @resource = resource
+        @pagination = pagination
+      end
+
+      def build!
+        return resource unless paginatable?
+
+        resource.page(pagination.page).per(pagination.per)
+      end
+
+      def paginatable?
+        resource.respond_to?(:page)
+      end
+    end
+  end
+end

data/lib/rails/surrender/helpers/query_param_parser.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    # parse the requests query_params for surrender's controls and validate the formatting
+    class QueryParamParser
+      attr_reader :query_params
+
+      COUNT_PARAM = :count
+      EXCLUDE_PARAM = :exclude
+      FILTER_PARAM = :filter
+      IDS_PARAM = :ids
+      INCLUDE_PARAM = :include
+      SORT_PARAM = :sort
+      PAGE_PARAM = :page
+      PER_PARAM = :per
+
+      PER_PAGE_DEFAULT = 50
+      PAGE_DEFAULT = 1
+
+      Sort = Struct.new(:request, :direction, :association, :attribute, :scope_method, keyword_init: true)
+      Pagination = Struct.new(:page, :per, keyword_init: true)
+
+      def initialize(query_params)
+        @query_params = query_params
+      end
+
+      def include
+        @include ||= parse_yml(query_params[INCLUDE_PARAM], :include)
+      end
+
+      def exclude
+        @exclude ||= parse_yml(query_params[EXCLUDE_PARAM], :exclude)
+      end
+
+      def sort?
+        query_params.key? SORT_PARAM
+      end
+
+      def sort
+        @sort ||= begin
+          sort = String.new(query_params[SORT_PARAM] || '')
+
+          direction_flag = ['+', '-'].include?(sort[0, 1]) ? sort.slice!(0) : '+'
+          direction = direction_flag == '-' ? 'DESC' : 'ASC'
+
+          scope_method = "sort_by_#{sort}".gsub('.', '_').to_sym
+          association, attribute = sort_attributes(sort)
+
+          Sort.new(request: query_params[SORT_PARAM], direction: direction, attribute: attribute,
+                   association: association, scope_method: scope_method)
+        end
+      end
+
+      def filter?
+        filter.present?
+      end
+
+      def filter
+        @filter ||= parse_yml(query_params[FILTER_PARAM], :filter)
+      end
+
+      def ids?
+        query_params.key?(IDS_PARAM)
+      end
+
+      def count?
+        query_params.key?(COUNT_PARAM)
+      end
+
+      def paginate?
+        query_params.key? PAGE_PARAM
+      end
+
+      def pagination
+        @pagination ||= Pagination.new(
+          page: query_params[PAGE_PARAM]&.to_i || PAGE_DEFAULT,
+          per: query_params[PER_PARAM]&.to_i || PER_PAGE_DEFAULT
+        )
+      end
+
+      private
+
+      def sort_attributes(sort)
+        return sort.split('.') if sort.include? '.'
+
+        ['', sort]
+      end
+
+      def parse_yml(query_string, action)
+        query_string ||= '' # empty string in case nil is passed
+        Psych.safe_load("[#{query_string.gsub(/(,|:)/, '\1 ')}]")
+      rescue StandardError
+        raise Error, I18n.t('surrender.error.query_string.incorrect_format', param: action)
+      end
+    end
+  end
+end

data/lib/rails/surrender/helpers/sort_builder.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    # apply sort directives to the given resource, based on the given sort controls
+    class SortBuilder
+      attr_reader :resource, :sort
+
+      def initialize(resource:, sort:)
+        @resource = resource
+        @sort = sort
+      end
+
+      def build!
+        return resource unless resource.is_a? ActiveRecord::Relation
+
+        return resource_attribute_order if resource_has_attribute?
+
+        return scope_method_order if resource_has_scope_method?
+
+        return association_attribute_order if resource_has_association_with_attribute?
+
+        raise Error, I18n.t('surrender.error.query_string.sort.invalid_column', param: sort.request)
+      end
+
+      private
+
+      def resource_has_attribute?
+        resource.klass.attribute_names.include?(sort.attribute)
+      end
+
+      def resource_attribute_order
+        resource.order(sort.attribute => sort.direction)
+      end
+
+      def resource_has_scope_method?
+        resource.respond_to?(sort.scope_method)
+      end
+
+      def scope_method_order
+        resource.send(sort.scope_method, sort.direction)
+      end
+
+      def resource_has_association_with_attribute?
+        resource.reflections.keys.include?(sort.association) &&
+          resource.reflect_on_association(sort.association).klass.attribute_names.include?(sort.attribute)
+      end
+
+      def association_attribute_order
+        table_name = resource.reflect_on_association(sort.association).klass.table_name
+        resource.joins(sort.association.to_sym)
+                .order("#{table_name}.#{sort.attribute} #{sort.direction}")
+      end
+    end
+  end
+end

data/lib/rails/surrender/model_additions.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    # Aad methods to the model class to describe how the model renders.
+    module ModelAdditions
+      def self.included(base)
+        attr_accessor :surrender_attributes
+        attr_accessor :surrender_expands
+        attr_accessor :surrender_available_attributes
+        attr_accessor :surrender_available_expands
+
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def surrenders(*args)
+          directives = args.extract_options!
+
+          # Run through the various lists of attributes and assign them to the rendering context
+          # If the superclass has attributes then consume those as well.
+          %w[attributes expands available_attributes available_expands].each do |directive|
+            surrender_directive = "surrender_#{directive}"
+            list = []
+            if superclass.instance_variable_defined?("@#{surrender_directive}")
+              list << superclass.instance_variable_get("@#{surrender_directive}")
+            end
+            list << directives[directive.to_sym] if directives.key?(directive.to_sym)
+            instance_variable_set("@#{surrender_directive}", list.flatten.uniq)
+          end
+        end
+
+        def surrender_attributes
+          @surrender_attributes ||= %i[id created_at]
+        end
+
+        def surrender_available_attributes
+          @surrender_available_attributes ||= []
+        end
+
+        def surrender_expands
+          @surrender_expands ||= []
+        end
+
+        def surrender_available_expands
+          @surrender_available_expands ||= []
+        end
+
+        def surrender_callable_attributes
+          @surrender_callable_attributes ||= (surrender_attributes + surrender_available_attributes).flatten
+        end
+
+        def surrender_callable_expands
+          @surrender_callable_expands ||= (surrender_expands + surrender_available_expands).flatten
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/model_filter_scopes.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Add filter_by_date_(to/from/before/after) methods for all *_at columns
+module Rails
+  module Surrender
+    # apply filter scopes to the model
+    module ModelFilterScopes
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def inherited(child)
+          super
+
+          # Bad things happen if you ask table_exists? to ApplicationRecord while it's loading!
+          # TODO: Add configuration in case ApplicationRecord is _not_ the primary abstract class
+          return if child.name == 'ApplicationRecord'
+
+          return unless child.table_exists?
+
+          child.instance_eval do
+            # scope to filter by every column name
+            apply_surrender_column_name_scopes(child)
+
+            # scope to filter by date or time column names
+            apply_surrender_column_datetime_scopes(child)
+          rescue StandardError
+            # TODO: why are tests failing here!!!
+          end
+        end
+
+        def apply_surrender_column_name_scopes(child)
+          child.column_names.each do |column|
+            scope "filter_by_#{column}".to_sym, ->(val) { where({ column.to_sym => val }) }
+          end
+        end
+
+        def apply_surrender_column_datetime_scopes(child)
+          with_surrender_datetime_columns(child) do |column|
+            base = column.split(/_at$/).first
+
+            scope "filter_by_#{base}_to".to_sym, ->(time) { where("#{child.table_name}.#{column} <= ?", time) }
+            scope "filter_by_#{base}_from".to_sym, ->(time) { where("#{child.table_name}.#{column} >= ?", time) }
+            scope "filter_by_#{base}_before".to_sym, ->(time) { where("#{child.table_name}.#{column} < ?", time) }
+            scope "filter_by_#{base}_after".to_sym, ->(time) { where("#{child.table_name}.#{column} > ?", time) }
+          end
+        end
+
+        def with_surrender_datetime_columns(child, &block)
+          child.columns.select { |c| c.type.in? %i[date datetime] }.map(&:name).each(&block)
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    class Railtie < ::Rails::Railtie
+      config.after_initialize do
+        ActionController::Base.class_eval do
+          include Rails::Surrender::ControllerAdditions
+        end
+
+        ActionController::API.class_eval do
+          include Rails::Surrender::ControllerAdditions
+        end
+
+        ActiveRecord::Base.class_eval do
+          include Rails::Surrender::ModelAdditions
+          include Rails::Surrender::ModelFilterScopes
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/render/configuration/inclusion_mapper_logic.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    module Render
+      # Container for config structure when rendering or generating the inclusion object.
+      class Configuration
+        module InclusionMapperLogic
+          def expanding_elements
+            list = resource_class_surrender_attributes_that_expand +
+                   resource_class_surrender_expands +
+                   resource_class_subclass_surrender_attributes_that_expand +
+                   resource_class_subclass_surrender_expands +
+                   user_included_joins_required +
+                   ctrl_included_joins_required
+                   .flatten.uniq
+            list
+              .map { |e| element_from(e) }
+              .reject do |element|
+              element.klass.in?(history) ||
+                element.name.in?(local_user_excludes) ||
+                (element.name.in?(local_ctrl_excludes) && !element.name.in?(local_user_includes))
+            end
+          end
+
+          private
+
+          def resource_class_surrender_attributes_that_expand
+            resource_class.surrender_attributes
+                          .select { |attr| attr.match /_ids$/ }
+                          .map { |attr| attr.to_s.sub('_ids', '').pluralize }
+                          .select { |include| attribute_type(include).in? %i[expand associate] }
+          end
+
+          def resource_class_surrender_expands
+            resource_class.surrender_expands
+          end
+
+          def resource_class_subclass_surrender_attributes_that_expand
+            resource_class.subclasses.map do |subclass|
+              subclass.surrender_attributes
+                      .select { |attr| attr.match /_ids$/ }
+                      .map { |attr| attr.to_s.sub('_ids', '').pluralize }
+                      .select { |include| attribute_type(include, resource_class: sc).in? %i[expand associate] }
+            end
+          end
+
+          def resource_class_subclass_surrender_expands
+            resource_class.subclasses.map(&:surrender_expands)
+          end
+
+          def user_included_joins_required
+            top_level_keys_from(user_include).select { |include| attribute_type(include).in? %i[expand associate] }
+          end
+
+          def ctrl_included_joins_required
+            top_level_keys_from(ctrl_include).select { |include| attribute_type(include).in? %i[expand associate] }
+          end
+
+          def element_from(item)
+            item_name = resource_class.reflections.key?(item.to_s) ? item.to_s : item.to_s.sub('_ids', '').pluralize
+            item_klass = resource_class.reflections[item_name].klass
+            Element.new name: item_name, klass: item_klass, continue: (item.to_s == item_name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/render/configuration/instance_logic.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    module Render
+      # Container for config structure when rendering or generating the inclusion object.
+      class Configuration
+        module InstanceLogic
+          def nested_user_includes
+            next_level_asks_from(user_include)
+          end
+
+          def nested_ctrl_includes
+            next_level_asks_from(ctrl_include)
+          end
+
+          def nested_user_excludes
+            next_level_asks_from(user_exclude)
+          end
+
+          def nested_ctrl_excludes
+            next_level_asks_from(ctrl_exclude)
+          end
+
+          def locally_included_attributes
+            [].push(resource_class.surrender_attributes)
+              .push(ctrl_included_attributes)
+              .push(user_included_attributes_to_render)
+              .flatten.uniq
+              .reject { |attr| exclude_locally?(attr) }
+          end
+
+          def locally_included_expands
+            [].push(user_included_local_expansions_to_render)
+              .push(ctrl_included_expansions)
+              .push(resource_class.surrender_expands)
+              .flatten.uniq
+              .each_with_object({}) { |key, result| result[key.to_sym] = [] }
+              .deep_merge(nested_user_includes)
+              .deep_merge(nested_ctrl_includes)
+          end
+
+          def exclude_locally?(key)
+            local_excludes.include?(key) && !local_user_includes.include?(key)
+          end
+
+          private
+
+          def local_excludes
+            local_ctrl_excludes.dup.push(local_user_excludes).flatten.uniq
+          end
+
+          def user_included_attributes
+            top_level_keys_from(user_include).select { |include| attribute_type(include).in? %i[include associate] }
+          end
+
+          def user_included_attributes_to_render
+            attrs = user_included_attributes
+            unavailable_attrs = (attrs - resource_class.surrender_callable_attributes)
+            return attrs if unavailable_attrs.empty?
+
+            raise Error, I18n.t('surrender.error.query_string.include.not_available', param: unavailable_attrs)
+          end
+
+          def user_included_expansions
+            local_user_includes.select { |i| attribute_type(i) == :expand }
+          end
+
+          def user_included_local_expansions_to_render
+            expansions = user_included_expansions
+            unavailable_expansions = (expansions - resource_class.surrender_callable_expands)
+            return expansions if unavailable_expansions.empty?
+
+            raise Error, I18n.t('surrender.error.query_string.include.not_available', param: unavailable_expansions)
+          end
+
+          def ctrl_included_attributes
+            top_level_keys_from(ctrl_include).select { |include| attribute_type(include).in? %i[include associate] }
+          end
+
+          def ctrl_included_expansions
+            local_ctrl_includes.select { |i| attribute_type(i) == :expand }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/render/configuration.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'configuration/inclusion_mapper_logic'
+require_relative 'configuration/instance_logic'
+
+module Rails
+  module Surrender
+    module Render
+      # Container for config structure when rendering or generating the inclusion object.
+      class Configuration
+        include InclusionMapperLogic
+        include InstanceLogic
+
+        attr_accessor :resource_class,
+                      :reload_resource,
+                      :user_exclude,
+                      :user_include,
+                      :ctrl_exclude,
+                      :ctrl_include,
+                      :history
+
+        alias reload_resource? reload_resource
+
+        Element = Struct.new(:name, :klass, :continue, keyword_init: true)
+
+        def initialize(
+          resource_class: nil,
+          reload_resource: false,
+          user_exclude: [],
+          user_include: [],
+          ctrl_exclude: [],
+          ctrl_include: [],
+          history: []
+        )
+          @resource_class = resource_class
+          @reload_resource = reload_resource
+          @user_exclude = user_exclude.compact
+          @user_include = user_include
+          @ctrl_exclude = ctrl_exclude.compact
+          @ctrl_include = ctrl_include
+          @history = history
+
+          validate_user_includes!
+        end
+
+        private
+
+        def validate_user_includes!
+          return if invalid_local_user_includes.empty?
+
+          raise Error, I18n.t('surrender.error.query_string.include.not_available', param: invalid_local_user_includes)
+        end
+
+        def invalid_local_user_includes
+          local_user_includes.select { |include| attribute_type(include) == :none }
+        end
+
+        def local_ctrl_excludes
+          top_level_keys_from(ctrl_exclude)
+        end
+
+        def local_ctrl_includes
+          top_level_keys_from(ctrl_include)
+        end
+
+        def local_user_excludes
+          top_level_keys_from(user_exclude)
+        end
+
+        def local_user_includes
+          top_level_keys_from(user_include)
+        end
+
+        def attribute_type(attr, klass: resource_class)
+          return :expand if klass.reflections.keys.include?(attr.to_s)
+          return :associate if klass.reflections.keys.include?(attr.to_s.sub('_ids', '').pluralize)
+          return :include if klass.attribute_names.include?(attr.to_s)
+          return :include if klass.instance_methods.include?(attr)
+
+          :none
+        end
+
+        def top_level_keys_from(list)
+          list.map { |x| x.is_a?(Hash) ? x.keys : x }.flatten.map(&:to_sym).uniq
+        end
+
+        def next_level_asks_from(list)
+          list.select { |x| x.is_a? Hash }.reduce({}, :merge).symbolize_keys
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/render/count.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    module Render
+      # Rendering a count of resources.
+      class Count
+        attr_reader :resource
+
+        def initialize(resource)
+          @resource = resource
+        end
+
+        def parse
+          count = resource.respond_to?(:count) ? resource.count : 1
+          Response.new(data: { count: count })
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/render/ids.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    module Render
+      # Rendering the IDs of the requested resources.
+      class Ids
+        attr_reader :resource
+
+        def initialize(resource)
+          @resource = resource
+        end
+
+        def parse
+          ids = resource.respond_to?(:ids) ? resource.ids : [resource.id]
+          Response.new(data: { ids: ids })
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/render/resource/collection.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    module Render
+      class Resource
+        # Renders a collection resource
+        class Collection
+          attr_reader :resource, :config, :ability
+
+          def initialize(resource:, config:, ability:)
+            @resource = resource
+            @config = config
+            @ability = ability
+          end
+
+          def render
+            return nil if resource.nil?
+
+            resource.map { |data| Instance.new(resource: data, config: config, ability: ability).render }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/render/resource/inclusion_mapper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    module Render
+      class Resource
+        # Builds a complete map of the resources needed to fulfill the request, for supplying to ActiveRecord.includes
+        class InclusionMapper
+          attr_reader :resource_class, :config
+
+          Element = Struct.new(:name, :klass, keyword_init: true)
+          # InclusionMapper is designed to recursively crawl through the model rendering structure and build a hash
+          # that ActiveRecord can use to eager load ALL of the data we're going to render, to prevent N+1 queries
+          def initialize(resource_class:, config:)
+            @resource_class = resource_class
+            @config = config
+          end
+
+          def parse
+            config.history.push resource_class
+            includes = []
+
+            config.expanding_elements.each do |element|
+              item_config = Configuration.new(
+                resource_class: element.klass,
+                user_include: config.nested_user_includes[element.name] || [],
+                ctrl_include: config.nested_ctrl_includes[element.name] || [],
+                user_exclude: config.nested_user_excludes[element.name] || [],
+                ctrl_exclude: config.nested_ctrl_excludes[element.name] || [],
+                history: config.history.dup.push(element.klass)
+              )
+
+              nested = if element.continue
+                         InclusionMapper.new(resource_class: element.klass, config: item_config).parse
+                       else
+                         []
+                       end
+
+              includes << (nested.size.zero? ? element.name : { element.name => nested })
+            end
+
+            includes.sort_by { |x| x.is_a?(Symbol) ? 0 : 1 }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/render/resource/instance.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    module Render
+      class Resource
+        # Renders an instance resource
+        class Instance
+          attr_reader :resource, :config, :ability
+
+          def initialize(resource:, config:, ability:)
+            @resource = resource
+            @config = config
+            @ability = ability
+          end
+
+          def render
+            config.history.push history_class
+
+            result = {}
+            config.locally_included_attributes.each { |attr| result[attr.to_sym] = resource.send(attr) }
+
+            config.locally_included_expands.each_key do |key|
+              next if config.exclude_locally?(key)
+
+              nested_resource_class = nested_class_for(resource, key)
+              next if config.history.include? nested_resource_class
+
+              nested_config = nested_config_for(nested_resource_class, key)
+
+              if resource.class.reflections[key.to_s].try(:collection?)
+                collection = resource.send(key.to_sym).select { |i| ability.can? :read, i }
+                result[key] = Collection.new(resource: collection, config: nested_config, ability: ability).render
+              else
+                instance = resource.send(key)
+                next if config.history.include? instance.class
+
+                if ability.can?(:read, instance)
+                  result[key] = Instance.new(resource: instance, config: nested_config, ability: ability).render
+                elsif instance.nil?
+                  result[key] = nil # represent an associated element as null if it's missing
+                end
+              end
+            end
+            result
+          end
+
+          private
+
+          def nested_class_for(resource, key)
+            resource.class.reflections[key.to_s].klass
+          rescue NoMethodError
+            resource.send(key).class
+          end
+
+          def nested_config_for(nested_resource_class, key)
+            Configuration.new(
+              resource_class: nested_resource_class,
+              user_include: config.nested_user_includes[key]  || [],
+              ctrl_include: config.nested_ctrl_includes[key]  || [],
+              user_exclude: config.nested_user_excludes[key]  || [],
+              ctrl_exclude: config.nested_ctrl_excludes[key]  || [],
+              history: config.history
+            )
+          end
+
+          # get to the root subclass for sti models and store that as history
+          def history_class
+            resource.class.superclass until resource.class.superclass.in? [ActiveRecord::Base, ApplicationRecord]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/render/resource.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'resource/inclusion_mapper'
+require_relative 'resource/collection'
+require_relative 'resource/instance'
+
+module Rails
+  module Surrender
+    module Render
+      # Rendering a resource, and it's various nested components, according to the given config params.
+      class Resource
+        attr_reader :resource, :ability, :config
+
+        def initialize(resource:, ability:, config:)
+          @resource = resource
+          @ability = ability
+          @config  = config
+        end
+
+        def parse
+          data = case resource
+                 when nil? then {}
+                 when Hash || Array then resource
+                 when ActiveRecord::Relation then collection_data
+                 else instance_data
+                 end
+          Response.new(data: data)
+        end
+
+        private
+
+        def collection_data
+          includes = InclusionMapper.new(resource_class: resource.klass, config: config).parse
+          data = @resource.includes(includes)
+          Collection.new(resource: data, config: config, ability: ability).render
+        end
+
+        def instance_data
+          # Reloading the instance here allows us to take advantage of the eager loading
+          # capabilities of ActiveRecord with our 'includes' hash to prevent N+1 queries.
+          # This can save a TON of response time when the data sets begin to get large.
+          data = if config.reload_resource?
+                   includes = InclusionMapper.new(resource_class: resource.class, config: config).parse
+                   @resource = resource.class.includes(includes).find_by_id(resource.id)
+                 else
+                   resource
+                 end
+
+          Instance.new(resource: data, config: config, ability: ability).render
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    # Generate a Response object from the given data
+    class Response
+      attr_accessor :data
+
+      def initialize(data:)
+        @data = data
+      end
+
+      def json_data
+        ::Oj.dump(data, mode: :compat)
+      end
+    end
+  end
+end

data/lib/rails/surrender/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    VERSION = '0.1.0'
+  end
+end

data/lib/rails/surrender.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Rails
+  # Base namespace for the entire project
+  module Surrender
+  end
+end
+
+require 'kaminari'
+require 'oj'
+
+require 'rails/surrender/default_ability'
+require 'rails/surrender/controller_additions'
+require 'rails/surrender/exceptions'
+require 'rails/surrender/model_additions'
+require 'rails/surrender/model_filter_scopes'
+require 'rails/surrender/railtie'
+require 'rails/surrender/render/ids'
+require 'rails/surrender/render/configuration'
+require 'rails/surrender/render/count'
+require 'rails/surrender/render/resource'
+require 'rails/surrender/response'
+require 'rails/surrender/version'
+
+# Load Surrender specific error messages
+locale_path = Dir.glob("#{__dir__}/surrender/config/locales/*.{rb,yml}")
+I18n.load_path += locale_path unless I18n.load_path.include?(locale_path)
+
+# ActiveRecord Patches required for proper functionality
+require 'rails/surrender/config/initializers/active_record_associations_patch'
+require 'rails/surrender/config/initializers/active_record_preloader_patch'

data/test/surrender_test.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class SurrenderTest < ActiveSupport::TestCase
+  test 'truth' do
+    assert_kind_of Module, Surrender
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Configure Rails Environment
+ENV['RAILS_ENV'] = 'test'
+
+require File.expand_path('../test/dummy/config/environment.rb', __dir__)
+ActiveRecord::Migrator.migrations_paths = [File.expand_path('../test/dummy/db/migrate', __dir__)]
+require 'rails/test_help'
+
+# Filter out Minitest backtrace while allowing backtrace from other libraries
+# to be shown.
+Minitest.backtrace_filter = Minitest::BacktraceFilter.new
+
+# Load support files
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
+
+# Load fixtures from the engine
+if ActiveSupport::TestCase.respond_to?(:fixture_path=)
+  ActiveSupport::TestCase.fixture_path = File.expand_path('fixtures', __dir__)
+  ActiveSupport::TestCase.fixtures :all
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: rails-surrender
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shawn McBride
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kaminari
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.13.10
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.13.10
+description:
+email: smmcbride@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/rails/surrender.rb
+- lib/rails/surrender/config/initializers/active_record_associations_patch.rb
+- lib/rails/surrender/config/initializers/active_record_preloader_patch.rb
+- lib/rails/surrender/config/locales/en.yml
+- lib/rails/surrender/controller_additions.rb
+- lib/rails/surrender/default_ability.rb
+- lib/rails/surrender/exceptions.rb
+- lib/rails/surrender/helpers/filter_builder.rb
+- lib/rails/surrender/helpers/pagination_builder.rb
+- lib/rails/surrender/helpers/query_param_parser.rb
+- lib/rails/surrender/helpers/sort_builder.rb
+- lib/rails/surrender/model_additions.rb
+- lib/rails/surrender/model_filter_scopes.rb
+- lib/rails/surrender/railtie.rb
+- lib/rails/surrender/render/configuration.rb
+- lib/rails/surrender/render/configuration/inclusion_mapper_logic.rb
+- lib/rails/surrender/render/configuration/instance_logic.rb
+- lib/rails/surrender/render/count.rb
+- lib/rails/surrender/render/ids.rb
+- lib/rails/surrender/render/resource.rb
+- lib/rails/surrender/render/resource/collection.rb
+- lib/rails/surrender/render/resource/inclusion_mapper.rb
+- lib/rails/surrender/render/resource/instance.rb
+- lib/rails/surrender/response.rb
+- lib/rails/surrender/version.rb
+- test/surrender_test.rb
+- test/test_helper.rb
+homepage: https://github.com/smmcbride/rails-surrender
+licenses:
+- GPL-3.0
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: JSON rendering for Rails API
+test_files: []