warped 0.1.0 → 1.0.0

data/lib/warped/api/filter/factory.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Warped
+  module Filter
+    class Factory
+      TYPES = %i[string integer float decimal date time date_time boolean].freeze
+
+      def self.build(kind, *args, **kwargs)
+        new(kind).build(*args, **kwargs)
+      end
+
+      def initialize(kind = nil)
+        @kind = kind
+        validate_kind!
+      end
+
+      def build(*args, **kwargs)
+        filter_class.new(*args, **kwargs)
+      end
+
+      private
+
+      attr_reader :kind
+
+      def validate_kind!
+        return if kind.nil?
+
+        raise ArgumentError, "#{kind} is not a valid filter type" unless TYPES.include?(kind)
+      end
+
+      def filter_class
+        return Base if kind.nil?
+
+        Filter.const_get(kind.to_s.camelize)
+      end
+    end
+  end
+end

data/lib/warped/api/filter/integer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+module Warped
+  module Filter
+    class Integer < Base
+      RELATIONS = %w[eq neq gt gte lt lte between in not_in is_null is_not_null].freeze
+
+      def cast(value)
+        return if value.blank?
+
+        casted_value = case value
+                       when ::Integer
+                         value
+                       when ::String
+                         value.to_i if value.match?(/\A-?\d+\z/)
+                       when ::Float, ::BigDecimal
+                         value.to_i
+                       end
+
+        check_casted_value!(casted_value)
+      end
+
+      def html_type
+        "number"
+      end
+
+      private
+
+      def check_casted_value!(value)
+        raise ValueError, "#{value} cannot be casted to #{kind}" if value.nil? && strict
+
+        value
+      end
+    end
+  end
+end

data/lib/warped/api/filter/string.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+module Warped
+  module Filter
+    class String < Base
+      RELATIONS = Queries::Filter::RELATIONS
+
+      def cast(value)
+        return if value.blank?
+
+        value.to_s
+      rescue StandardError
+        raise ValueError, "#{value} cannot be casted to #{kind}" if strict
+
+        nil
+      end
+
+      def html_type
+        "text"
+      end
+    end
+  end
+end

data/lib/warped/api/filter/time.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+module Warped
+  module Filter
+    class Time < Base
+      RELATIONS = %w[eq neq gt gte lt lte between is_null is_not_null].freeze
+
+      def cast(value)
+        return if value.blank?
+
+        ::Time.parse(value)
+      rescue StandardError
+        raise ValueError, "#{value} cannot be casted to #{kind}" if strict
+
+        nil
+      end
+
+      def html_type
+        "time"
+      end
+    end
+  end
+end

data/lib/warped/api/filter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+
+module Warped
+  module Filter
+    class ValueError < StandardError; end
+    class RelationError < StandardError; end
+
+    class << self
+      delegate :build, to: Factory
+    end
+  end
+end

data/lib/warped/api/sort/value.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+
+module Warped
+  class Sort
+    class Value
+      attr_reader :sort
+
+      delegate :name, :alias_name, :parameter_name, to: :sort
+
+      # @param sort [Warped::Sort] The sort object
+      # @param direction [String] The sort direction.
+      def initialize(sort, direction)
+        @sort = sort
+        @direction = direction
+      end
+
+      # @return [String] The sort direction.
+      def direction
+        sort.direction!(@direction)
+      end
+
+      # @return [String] The opposite sort direction.
+      def opposite_direction
+        sort.opposite_direction(direction)
+      end
+
+      # @return [Boolean] Whether the sort is ascending.
+      def asc?
+        %w[asc asc_nulls_first asc_nulls_last].include?(direction)
+      end
+
+      # @return [Boolean] Whether the sort is descending.
+      def desc?
+        %w[desc desc_nulls_first desc_nulls_last].include?(direction)
+      end
+    end
+  end
+end

data/lib/warped/api/sort.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+module Warped
+  class Sort
+    class DirectionError < StandardError; end
+
+    SORT_DIRECTIONS = %w[asc desc].freeze
+    NULLS_SORT_DIRECTION = %w[asc_nulls_first asc_nulls_last desc_nulls_first desc_nulls_last].freeze
+
+    attr_accessor :name, :alias_name
+
+    # @return [Array<String>] The valid sort directions.
+    def self.directions
+      @directions ||= SORT_DIRECTIONS + NULLS_SORT_DIRECTION
+    end
+
+    # @param name [String] The name of the sort.
+    # @param alias_name [String] The alias name of the sort, used for renaming the sort key in the URL params
+    def initialize(name, alias_name: nil)
+      raise ArgumentError, "name cannot be nil" if name.nil?
+
+      @name = name.to_s
+      @alias_name = alias_name&.to_s
+    end
+
+    # @return [String] The name to use in the URL params.
+    def parameter_name
+      alias_name.presence || name
+    end
+
+    # @param direction [String] The sort direction.
+    # @return [String] The sort direction.
+    # @raise [DirectionError] If the direction is invalid.
+    def direction!(direction)
+      raise DirectionError, "Invalid direction: #{direction}" unless valid_direction?(direction.to_s)
+
+      direction.to_s
+    end
+
+    # @param direction [String] The sort direction.
+    # @return [String] The opposite sort direction.
+    def opposite_direction(direction)
+      opposite_directions[direction]
+    end
+
+    private
+
+    def valid_direction?(relation)
+      self.class.directions.include?(relation.to_s)
+    end
+
+    def opposite_directions
+      @opposite_directions ||= {
+        "asc" => "desc",
+        "desc" => "asc",
+        "asc_nulls_first" => "desc_nulls_last",
+        "asc_nulls_last" => "desc_nulls_first",
+        "desc_nulls_first" => "asc_nulls_last",
+        "desc_nulls_last" => "asc_nulls_first"
+      }.freeze
+    end
+  end
+end

data/lib/warped/controllers/filterable/ui.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Warped
+  module Controllers
+    module Filterable
+      module Ui
+        extend ActiveSupport::Concern
+        include Filterable
+
+        included do
+          helper_method :filters, :filtered?, :filter_url_params, :filterable_by
+        end
+
+        # @see Filterable#filter
+        def filter(...)
+          @filtered = true
+
+          super
+        end
+
+        # @return [Boolean] Whether the current action is filtered.
+        def filtered?
+          @filtered ||= false
+        end
+
+        # @return [Hash] The filters for the current action.
+        def filter_url_params(**options)
+          url_params = {}
+          current_action_filter_values.each_with_object(url_params) do |filter_value, hsh|
+            if filter_value.value.is_a?(Array)
+              filter_value.value.each { |value| hsh["#{filter_value.parameter_name}[]"] = value }
+            else
+              hsh[filter_value.parameter_name] = filter_value.value
+            end
+
+            hsh["#{filter_value.parameter_name}.rel"] = filter_value.relation
+          end
+
+          url_params.merge!(options)
+        end
+      end
+    end
+  end
+end

data/lib/warped/controllers/filterable.rb

@@ -3,6 +3,8 @@
 require "active_support/concern"
 require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/enumerable"
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/object/blank"
 
 module Warped
   module Controllers
@@ -25,7 +27,7 @@ module Warped
     #   GET /users?name=John
     #   GET /users?created_at=2020-01-01
     #   GET /users?accounts.kind=premium
-    #   GET /users?accounts.kind=premium&accounts.kind.rel=not_eq
+    #   GET /users?accounts.kind=premium&accounts.kind.rel=neq
     #
     # Filters can be combined:
     #   GET /users?name=John&created_at=2020-01-01
@@ -40,7 +42,7 @@ module Warped
     #   class UsersController < ApplicationController
     #     include Filterable
     #
-    #     filterable_by :name, :created_at, 'accounts.kind' => 'kind'
+    #     filterable_by :name, :created_at, 'accounts.kind' => { alias_name: 'kind' }
     #
     #     def index
     #       scope = filter(User.joins(:account))
@@ -64,9 +66,9 @@ module Warped
     # To use the operands, you must pass a parameter appended with `.rel`, and the value of a valid operand.
     #
     # Example requests:
-    #   GET /users?created_at=2020-01-01&created_at.rel=>
-    #   GET /users?created_at=2020-01-01&created_at.rel=<
-    #   GET /users?created_at=2020-01-01&created_at.rel=not_eq
+    #   GET /users?created_at=2020-01-01&created_at.rel=gt
+    #   GET /users?created_at=2020-01-01&created_at.rel=lt
+    #   GET /users?created_at=2020-01-01&created_at.rel=neq
     #
     # When the operand relation requires multiple values, like +in+, +not_in+, or +between+,
     # you can pass an array of values.
@@ -74,67 +76,102 @@ module Warped
     # Example requests:
     #   GET /users?created_at[]=2020-01-01&created_at[]=2020-01-03&created_at.rel=in
     #   GET /users?created_at[]=2020-01-01&created_at[]=2020-01-03&created_at.rel=between
+    #
+    # Setting types and casting:
+    # By default, the filter values are cast to strings. If you want to cast the values to a specific type,
+    # and validate that the values are of the correct type, you can pass the kind of the filter to
+    # the +filterable_by+ method.
+    #
+    # Example:
+    #
+    #   class UsersController < ApplicationController
+    #     include Filterable
+    #
+    #     filterable_by :name, :created_at, 'accounts.active' => { kind: :integer, alias_name: 'active' }
+    #
+    #     def index
+    #       scope = filter(User.joins(:account))
+    #       render json: scope
+    #     end
+    #   end
+    #
+    # Example requests:
+    #   GET /users?active=1
+    #
+    # The +kind+ parameter will be cast to an integer.
+    # If the value is not an integer, an error will be raised, and the response will be a 400 Bad Request.
+    #
+    # In order to change the error message, you can rescue from the +Filter::ValueError+ exception, or
+    # override the +render_invalid_filter_value+ method.
+    #
+    #   def render_invalid_filter_value(exception)
+    #     render action_name, status: :bad_request
+    #   end
+    #
     module Filterable
       extend ActiveSupport::Concern
 
       included do
-        class_attribute :filter_fields, default: []
-        class_attribute :mapped_filter_fields, default: []
+        class_attribute :filters, default: []
+        class_attribute :strict_filtering, default: false
+
+        helper_method :current_action_filters, :current_action_filter_values
       end
 
       class_methods do
         # @param keys [Array<Symbol,String,Hash>]
         # @param mapped_keys [Hash<Symbol,String>]
-        def filterable_by(*keys, **mapped_keys)
-          self.filter_fields = keys
-          self.mapped_filter_fields = mapped_keys.to_a
+        def filterable_by(*keys, strict: nil, **mapped_keys)
+          self.strict_filtering = strict unless strict.nil?
+
+          self.filters = keys.map do |field|
+            Warped::Filter.build(nil, field, strict:)
+          end
+
+          complex_filters = mapped_keys.with_indifferent_access
+
+          self.filters += complex_filters.map do |field_name, opts|
+            kind = opts[:kind]
+            alias_name = opts[:alias_name]
+
+            Warped::Filter.build(kind, field_name, alias_name:, strict:)
+          end
         end
       end
 
       # @param scope [ActiveRecord::Relation]
-      # @param filter_conditions [Array<Hash>]
-      # @option filter_conditions [Symbol,String] :field
-      # @option filter_conditions [String,Integer,Array<String,Integer>] :value
-      # @option filter_conditions [String] :relation
+      # @param filter_conditions [Array<Warped::Filter::Base>|nil]
       # @return [ActiveRecord::Relation]
-      def filter(scope, filter_conditions: filter_conditions(*filter_fields, *mapped_filter_fields))
-        Warped::Queries::Filter.call(scope, filter_conditions:)
+      def filter(scope, filter_conditions: nil)
+        action_filters = filter_conditions.presence || filters
+        @current_action_filters = action_filters
+        @current_action_filter_values = parse_filter_params
+
+        Warped::Queries::Filter.call(scope, filter_conditions: current_action_filter_values.map(&:to_h))
       end
 
-      # @param fields [Array<Symbol,String>]
       # @return [Array<Hash>]
-      def filter_conditions(*fields)
-        fields.filter_map do |filter_opt|
-          field = filter_name(filter_opt)
-
-          next if filter_value(filter_opt).blank? && %w[is_null is_not_null].exclude?(filter_rel_value(filter_opt))
-
-          {
-            field:,
-            value: filter_value(filter_opt),
-            relation: filter_rel_value(filter_opt).presence || (filter_value(filter_opt).is_a?(Array) ? "in" : "=")
-          }
-        end
-      end
+      def parse_filter_params
+        current_action_filters.filter_map do |filter|
+          raw_value = params[filter.parameter_name]
+          raw_relation = params["#{filter.parameter_name}.rel"]
 
-      private
+          filter_value = filter.class::Value.new(filter, raw_relation.presence || "eq", raw_value.presence)
 
-      def filter_name(filter)
-        filter.is_a?(Array) ? filter.first : filter
-      end
+          next if filter_value.empty?
 
-      def filter_mapped_name(filter)
-        filter.is_a?(Array) ? filter.last : filter
+          filter_value
+        end
       end
 
-      def filter_value(filter)
-        param_key = filter_mapped_name(filter)
-        params[param_key]
+      # @return [Array<Warped::Filter::Base>]
+      def current_action_filters
+        @current_action_filters ||= []
       end
 
-      def filter_rel_value(filter)
-        param_key = filter_mapped_name(filter)
-        params["#{param_key}.rel"]
+      # @return [Array<Warped::Filter::Base::Value>]
+      def current_action_filter_values
+        @current_action_filter_values ||= []
       end
     end
   end

data/lib/warped/controllers/pageable/ui.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Warped
+  module Controllers
+    module Pageable
+      module Ui
+        extend ActiveSupport::Concern
+
+        include Pageable
+
+        included do
+          helper_method :pagination, :paginated?, :paginate_url_params
+        end
+
+        # @return [Hash] The paginate_url_params
+        def paginate_url_params(**options)
+          url_params = { page:, per_page: }
+          url_params.merge!(options)
+        end
+
+        # @see Pageable#pagination
+        # @return [Hash]
+        def pagination
+          super.tap do |hsh|
+            hsh[:series] = series(hsh[:page], hsh[:total_pages])
+          end
+        end
+
+        # @see Pageable#paginate
+        def paginate(...)
+          @paginated = true
+
+          super
+        end
+
+        # @return [Boolean] Whether the current action is paginated.
+        def paginated?
+          @paginated ||= false
+        end
+
+        private
+
+        # @param page [Integer]
+        # @param total_pages [Integer]
+        # @return [Array]
+        #   the series method returns an array of page numbers and :gap symbols
+        #   the current page is a string, the others are integers
+        #   series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+        def series(page, total_pages)
+          current_page = [page, total_pages].min
+          return [] if total_pages.zero?
+          return ["1"] if total_pages == 1
+
+          if total_pages <= 9
+            (1..(current_page - 1)).to_a + [current_page.to_s] + ((current_page + 1)..total_pages).to_a
+          elsif current_page <= 5
+            [*(1..6).to_a.map { |i| i == page ? i.to_s : i }, :gap, total_pages]
+          elsif current_page >= total_pages - 4
+            [1, :gap, *(total_pages - 5..total_pages).to_a.map { |i| i == current_page ? i.to_s : i }]
+          else
+            [1, :gap, current_page - 2, current_page - 1, current_page.to_s, current_page + 1, current_page + 2, :gap,
+             total_pages]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/warped/controllers/pageable.rb

@@ -14,7 +14,7 @@ module Warped
     #
     #     def index
     #       scope = paginate(User.all)
-    #       render json: scope, root: :users, meta: page_info
+    #       render json: scope, root: :users, meta: pagination
     #     end
     #   end
     #
@@ -33,7 +33,7 @@ module Warped
     #
     #     def index
     #       scope = paginate(User.all)
-    #       render json: scope, root: :users, meta: page_info
+    #       render json: scope, root: :users, meta: pagination
     #     end
     #   end
     #
@@ -44,7 +44,7 @@ module Warped
     #
     #     def index
     #       scope = paginate(User.all)
-    #       render json: scope, root: :users, meta: page_info
+    #       render json: scope, root: :users, meta: pagination
     #     end
     #
     #     private
@@ -62,17 +62,17 @@ module Warped
     #
     #     def index
     #       scope = paginate(User.all, per_page: 50)
-    #       render json: scope, root: :users, meta: page_info
+    #       render json: scope, root: :users, meta: pagination
     #     end
     #
     #     def other_index
     #       # The default per_page value is used.
     #       scope = paginate(User.all)
-    #       render json: scope, root: :users, meta: page_info
+    #       render json: scope, root: :users, meta: pagination
     #     end
     #   end
     #
-    # The pagination metadata can be accessed by calling the +page_info+ method.
+    # The pagination metadata can be accessed by calling the +pagination+ method.
     # It includes the following keys:
     # - +total_count+: The total number of records in the collection.
     # - +total_pages+: The total number of pages.
@@ -80,7 +80,7 @@ module Warped
     # - +prev_page+: The previous page number.
     # - +page+: The current page number.
     # - +per_page+: The number of records per page.
-    # *Warning*: The +page_info+ method will raise an +ArgumentError+ if the method +paginate+ was not
+    # *Warning*: The +pagination+ method will raise an +ArgumentError+ if the method +paginate+ was not
     # called within the action.
     module Pageable
       extend ActiveSupport::Concern
@@ -96,7 +96,7 @@ module Warped
       # @param per_page [String,Integer,nil] The number of records per page.
       # @return [ActiveRecord::Relation] The paginated scope.
       def paginate(scope, page: self.page, per_page: self.per_page)
-        @page_info, paginated_scope = Queries::Paginate.call(scope, page:, per_page:)
+        @pagination, paginated_scope = Queries::Paginate.call(scope, page:, per_page:)
         paginated_scope
       end
 
@@ -112,7 +112,7 @@ module Warped
       #
       # @return [String,Integer] The number of records per page.
       def per_page
-        params[:per_page].presence || self.class.default_per_page
+        params[:per_page].presence || default_per_page
       end
 
       # Retrieves pagination metadata.
@@ -120,8 +120,8 @@ module Warped
       # @return [Hash] Metadata about the pagination.
       # @raise [ArgumentError] If pagination was not performed.
       # @see Warped::Queries::Paginate#metadata
-      def page_info
-        return @page_info if @page_info.present?
+      def pagination
+        return @pagination if @pagination.present?
 
         raise ActionController::BadRequest, "Pagination was not performed"
       end

data/lib/warped/controllers/searchable/ui.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Warped
+  module Controllers
+    module Searchable
+      module Ui
+        extend ActiveSupport::Concern
+
+        include Searchable
+
+        included do
+          helper_method :searched?, :search_url_params
+        end
+
+        # @see Searchable#search
+        def search(...)
+          @searched = true
+
+          super
+        end
+
+        # @return [Boolean] Whether the current action is searched.
+        def searched?
+          @searched ||= false
+        end
+
+        # @return [Hash] The search_url_params
+        def search_url_params(**options)
+          url_params = { search_param => search_term }
+          url_params.merge!(options)
+        end
+      end
+    end
+  end
+end

data/lib/warped/controllers/searchable.rb

@@ -115,6 +115,8 @@ module Warped
       included do
         class_attribute :model_search_scope, default: :search
         class_attribute :search_param, default: :q
+
+        helper_method :search_term, :search_param, :model_search_scope
       end
 
       class_methods do