rails-surrender 7.0.0 → 8.0.0

data/lib/rails/surrender/selection/selection.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative '../params/list_param'
+require_relative 'page_size'
+require_relative 'selected'
+
+module Rails
+  module Surrender
+    # The records one request renders, picked from a relation by the request's filter, sort and page.
+    class Selection
+      PAGE_DEFAULT = 1
+
+      # `query_params` are the request's. A controller that skips pagination passes `paginate: false`.
+      def initialize(query_params, paginate: true, page_size: Surrender.page_size)
+        @params = query_params.to_h.symbolize_keys
+        @paginate = paginate
+        @page_size = page_size
+      end
+
+      def count?
+        @params.key?(:count)
+      end
+
+      # Only a relation can be filtered, sorted and paged; anything else is selected as it is.
+      def apply(resource)
+        return Selected.new(records: resource) unless resource.is_a?(ActiveRecord::Relation)
+
+        selected = sorted(filtered(resource))
+        return Selected.new(records: selected, sort: sort) unless paged?
+
+        # Surrender's page size limit is the only one, so Kaminari's own limits mustn't shrink the page it reports.
+        size = @page_size.for(positive_whole_number(:per))
+        paged = selected.page(positive_whole_number(:page) || PAGE_DEFAULT).per(size, max_per_page: size)
+        Selected.new(records: paged, unpaged: selected, sort: sort, per: size)
+      end
+
+      private
+
+      def filtered(relation)
+        Params::ListParam.parse(@params[:filter], param: :filter).reduce(relation) do |filtered, term|
+          raise Error, I18n.t('surrender.error.query_string.incorrect_format', param: :filter) unless term.is_a?(Hash)
+
+          term.reduce(filtered) { |narrowed, (name, value)| narrowed.surrender_filter(name, value) }
+        end
+      end
+
+      def sorted(relation)
+        sort ? relation.surrender_sort(sort) : relation
+      end
+
+      # A blank sort, as API explorers send for an empty field, means no sort rather than a sort on nothing.
+      def sort
+        @params[:sort].presence
+      end
+
+      # A count response counts the whole selection, so it is never paged.
+      def paged?
+        @paginate && !count?
+      end
+
+      def positive_whole_number(param)
+        value = @params[param]
+        return if value.nil?
+        return value.to_i if value.to_s.match?(/\A[1-9]\d*\z/)
+
+        raise Error, I18n.t('surrender.error.query_string.pagination.invalid', param: param, value: value)
+      end
+    end
+  end
+end

data/lib/rails/surrender/selection/sorting.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Rails
+  module Surrender
+    class Selection
+      # Orders a model's records by a request's sort, such as `title`, `-pages` or `author.name`. A leading - sorts
+      # descending; a leading + or none sorts ascending.
+      module Sorting
+        extend ActiveSupport::Concern
+
+        SORT_PREFIX = 'sort_by_'
+
+        # Resolves a request's sort against the model.
+        module ClassMethods
+          # A sort_by_ scope the model defines wins over its columns, as filter_by_ scopes the model defines win over
+          # generated ones. Each scope takes the direction, 'ASC' or 'DESC'.
+          def surrender_sort(sort)
+            name = sort.strip.delete_prefix('-').delete_prefix('+')
+            direction = sort.strip.start_with?('-') ? :desc : :asc
+            scope = :"#{SORT_PREFIX}#{name.tr('.', '_')}"
+
+            return public_send(scope, direction.to_s.upcase) if respond_to?(scope)
+            return order(name => direction) if attribute_names.include?(name)
+
+            surrender_sort_by_association(name, direction) ||
+              raise(Error, I18n.t('surrender.error.query_string.sort.invalid_column', param: sort))
+          end
+
+          # The sorts a request may name: the model's columns, the columns of its singular associations, and the sorts
+          # it defines.
+          def surrender_sort_names
+            associated = reflect_on_all_associations.select { |reflection| surrender_sortable?(reflection) }
+                                                    .flat_map do |reflection|
+              reflection.klass.attribute_names.map { |attribute| "#{reflection.name}.#{attribute}" }
+            end
+            defined = methods.grep(/\A#{SORT_PREFIX}/o).map { |scope| scope.to_s.delete_prefix(SORT_PREFIX) }.sort
+            (attribute_names + associated + defined).uniq
+          end
+
+          private
+
+          # `author.name` sorts by the name of each record's author.
+          def surrender_sort_by_association(name, direction)
+            association, attribute = name.split('.', 2)
+            reflection = attribute && reflect_on_association(association)
+            return unless reflection && surrender_sortable?(reflection)
+            return unless reflection.klass.attribute_names.include?(attribute)
+
+            joins(reflection.name).order(reflection.klass.arel_table[attribute].public_send(direction))
+          end
+
+          # Joining an association that holds many records would repeat each record once per associated one. Nothing
+          # can name a polymorphic association's class before records load.
+          def surrender_sortable?(reflection)
+            !reflection.collection? && !reflection.polymorphic?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/surrender/version.rb

@@ -2,6 +2,6 @@
 
 module Rails
   module Surrender
-    VERSION = '7.0.0'
+    VERSION = '8.0.0'
   end
 end

data/lib/rails/surrender.rb

@@ -3,6 +3,14 @@
 module Rails
   # Base namespace for the entire project
   module Surrender
+    class << self
+      # The page size the app configures with config.surrender.default_per_page and max_per_page, set at boot.
+      attr_writer :page_size
+
+      def page_size
+        @page_size ||= Selection::PageSize.new
+      end
+    end
   end
 end
 
@@ -12,20 +20,13 @@ require 'oj'
 require 'rails/surrender/default_ability'
 require 'rails/surrender/controller_additions'
 require 'rails/surrender/exceptions'
+require 'rails/surrender/fields/field_tree'
+require 'rails/surrender/menu/menu'
 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/selection/filtering'
+require 'rails/surrender/selection/selection'
+require 'rails/surrender/selection/sorting'
 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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-surrender
 version: !ruby/object:Gem::Version
-  version: 7.0.0
+  version: 8.0.0
 platform: ruby
 authors:
 - Shawn McBride
@@ -13,117 +13,141 @@ dependencies:
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: kaminari
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: oj
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.13.10
+        version: '3.13'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.13.10
+        version: '3.13'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Lets API clients shape JSON responses with query parameters for include,
+  exclude, filter, sort, pagination, counts and id lists, while eager loading to avoid
+  N+1 queries.
 email: smmcbride@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.md
 - 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/fields/asks.rb
+- lib/rails/surrender/fields/attribute.rb
+- lib/rails/surrender/fields/expand.rb
+- lib/rails/surrender/fields/field_tree.rb
+- lib/rails/surrender/fields/id_list.rb
+- lib/rails/surrender/fields/node.rb
+- lib/rails/surrender/menu/field.rb
+- lib/rails/surrender/menu/filter.rb
+- lib/rails/surrender/menu/menu.rb
 - lib/rails/surrender/model_additions.rb
-- lib/rails/surrender/model_filter_scopes.rb
+- lib/rails/surrender/params/list_param.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/selection/filtering.rb
+- lib/rails/surrender/selection/page_size.rb
+- lib/rails/surrender/selection/selected.rb
+- lib/rails/surrender/selection/selection.rb
+- lib/rails/surrender/selection/sorting.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
+- GPL-3.0-only
 metadata:
+  changelog_uri: https://github.com/smmcbride/rails-surrender/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/smmcbride/rails-surrender
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

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

@@ -1,17 +0,0 @@
-# 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

@@ -1,20 +0,0 @@
-# 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/helpers/filter_builder.rb

@@ -1,50 +0,0 @@
-# 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

@@ -1,25 +0,0 @@
-# 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

@@ -1,98 +0,0 @@
-# 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

@@ -1,56 +0,0 @@
-# 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