active_queryable 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85318f4379a335f5d2398c1b85ab19ddb63cfbfa6955882c4dcd9e7a24a5168f
-  data.tar.gz: d9dbb94f9c174af1a34b680152b8add196cf1ddf1a38a895fc0f32370855a985
+  metadata.gz: ca76d46d098d260a1f59a1fd6e50d59cbab69eb95ba87f25470ccb08aa3050f2
+  data.tar.gz: 9562f2b4d7a4cce6ba1ba6bb070c6e6d9cf031d6205bf1006e5b5c1f21566ed4
 SHA512:
-  metadata.gz: f64dda266de6dd21f1c6a21fae9bfba014a72a16f7acf6c560f6feea3771b4663db82b11b97c97fc751379963aa2b0b29b26a6a34339d2f8dade38576ee5868b
-  data.tar.gz: 89bad17c363651ddbc6c75ca6eeda418d436682c9376a1c9670e81bbc959e491b5a3b0acc1345cf71879ea01ad5ccf623fc8624a00e698c34a8131e1f1730c63
+  metadata.gz: 5ec24780124afa2fd02e2d6bdf9a4f54f6dd980c8852adc43c4ae37144f887d54eccbdebf5e8d50765b3cc3e051762f4c1e62f7006a3a5385d5ed6962e3ce22f
+  data.tar.gz: aaf987e005a9f87b39ae00f63adaf7791a11b0facc962ae2f9b70e541e74f7b0281e1d71e6428ba71b97c7ba924dd20cf08b126e960430f9ecf8ef88d0ec9d0d

data/lib/active_queryable/version.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
 module ActiveQueryable
-	VERSION = '0.2.0'
+  # @return [String] the version of the gem
+  VERSION = '0.3.1'
 end

data/lib/active_queryable.rb

@@ -1,41 +1,110 @@
 # frozen_string_literal: true
 
 require 'active_support/concern'
+require 'active_record'
 require 'kaminari/activerecord'
 
+# A light and simple gem for sorting / filtering / paginating a model in Rails.
 module ActiveQueryable
-	extend ActiveSupport::Concern
+  extend ActiveSupport::Concern
 
-  QUERYABLE_VALID_PARAMS = [:filter, :sort, :page, :per].freeze
+  # @private
+  QUERYABLE_VALID_PARAMS = %i[filter sort page per].freeze
 
   included do
     class_attribute :_queryable_default_order
     class_attribute :_queryable_default_page
     class_attribute :_queryable_default_per
     class_attribute :_queryable_filter_keys
-	end
+    class_attribute :_queryable_expandable_filter_keys
+  end
 
-	module Initializer
+  # @private
+  module Initializer
+    # Enables ActiveQueryable for the model
+    # @example
+    #   class User < ApplicationRecord
+    #     as_queryable
+    #   end
+    #
+    # @!parse include ActiveQueryable
+    # @return [void]
     def as_queryable
-			send :include, ActiveQueryable
-		end
-	end
+      send :include, ActiveQueryable
+    end
+  end
 
+  # Extension methods for ActiveRecord::Base
+  # @!method query_by(params)
+  #   Runs a query with the given params
+  #   @example
+  #     User.query_by(sort: '-name', filter: { name: 'John' })
+  #   @param params [Hash,ActionController::Parameters]
+  #   @option params [String] :sort
+  #   @option params [Hash] :filter
+  #   @option params [String] :page
+  #   @option params [String] :per
+  #   @option params [Hash] :page
+  #   @return [ActiveRecord::Relation]
+  # @!method of_not(ids)
+  #   @example
+  #     User.of_not([1, 2, 3]) # => equivalent of: User.where.not(id: [1, 2, 3])
+  #   Returns a scope with the given ids excluded
+  #   @param ids [Array<Integer,String>]
+  #   @return [ActiveRecord::Relation]
   module ClassMethods
+    # Configures the model to be queryable
+    # @example
+    #   class User < ApplicationRecord
+    #     as_queryable
+    #     queryable order: { name: :asc }, page: 1, per: 25, filter: %i[name email]
+    #   end
+    #
+    # @param options [Hash]
+    # @option options [Hash<Symbol,Symbol>] :order { id: :asc }
+    # @option options [Integer] :page 1
+    # @option options [Integer] :per 25
+    # @option options [Array<Symbol,String>] :filter []
+    # @return [void]
     def queryable(options)
-      self._queryable_default_order = options[:order] || { id: :asc }
-      self._queryable_default_page = options[:page] || 1
-      self._queryable_default_per = options[:per] || 25
-      self._queryable_filter_keys = ((options[:filter] || []) + ['not']).map(&:to_sym)
+      queryable_configure_options(options)
 
       scope :query_by, ->(params) { queryable_scope(params) }
       scope :of_not, ->(ids) { where.not(id: ids) }
     end
 
+    # A method to expand the filterable keys, useful to allow class inheritance
+    # @example
+    #   class BaseItem < ApplicationRecord
+    #     as_queryable
+    #     queryable order: { name: :asc }, page: 1, per: 25, filter: %i[name email]
+    #   end
+    #   class AdvancedItem < BaseItem
+    #     expand_queryable filter: %i[phone]
+    #   end
+    #
+    #
+    # @param options [Hash]
+    # @option options [Array<Symbol,String>] :filter []
+    # @return [void]
+    def expand_queryable(options)
+      self._queryable_expandable_filter_keys ||= []
+      self._queryable_expandable_filter_keys += ((options[:filter] || [])).map(&:to_sym)
+    end
+
+    # @param params [Hash,ActionController::Parameters]
+    # @option params [String] :sort
+    # @option params [Hash] :filter
+    # @option params [String] :page
+    # @option params [String] :per
+    # @option params [Hash] :page
+    # @return [ActiveRecord::Relation]
     def queryable_scope(params)
       params = params.to_unsafe_h if params.respond_to? :to_unsafe_h
       params = params.with_indifferent_access if params.respond_to?(:with_indifferent_access)
-      params.each_key { |k| QUERYABLE_VALID_PARAMS.include?(k.to_sym) || Rails.logger.error("Invalid key #{k} in queryable") }
+      params.each_key do |k|
+        QUERYABLE_VALID_PARAMS.include?(k.to_sym) || Rails.logger.error("Invalid key #{k} in queryable")
+      end
 
       order_params = queryable_validate_order_params(params[:sort])
       query = queryable_parse_order_scope(order_params, self)
@@ -45,6 +114,26 @@ module ActiveQueryable
 
     private
 
+    # @option options [Hash<Symbol,Symbol>] :order { id: :asc }
+    # @option options [Integer] :page 1
+    # @option options [Integer] :per 25
+    # @option options [Array<Symbol,String>] :filter []
+    # @return [void]
+    def queryable_configure_options(options)
+      self._queryable_default_order = options[:order] || { id: :asc }
+      self._queryable_default_page = options[:page] || 1
+      self._queryable_default_per = options[:per] || 25
+      self._queryable_filter_keys = (((options[:filter] || [])).map(&:to_sym))
+    end
+
+    # @param params [Hash,ActionController::Parameters]
+    # @option params [String] :sort
+    # @option params [Hash] :filter
+    # @option params [String] :page
+    # @option params [String] :per
+    # @option params [Hash] :page
+    # @param query [ActiveRecord::Relation]
+    # @return [ActiveRecord::Relation]
     def queryable_filtered_scope(params, query)
       filter_params = queryable_validate_filter_params(params[:filter])
 
@@ -61,10 +150,17 @@ module ActiveQueryable
       scope
     end
 
+    # @param params [String,nil]
+    # @return [Hash]
     def queryable_validate_order_params(params)
       queryable_parse_order_params(params) || _queryable_default_order
     end
 
+    # @param params [Hash,ActionController::Parameters]
+    # @option params [String] :page
+    # @option params [String] :per
+    # @option params [Hash] :page
+    # @return [Hash]
     def queryable_validate_page_params(params)
       page_params = {}
       if params[:page].respond_to?(:dig)
@@ -77,15 +173,20 @@ module ActiveQueryable
       page_params
     end
 
+    # @param filter_params [Hash,ActionController::Parameters,nil]
+    # @return [Hash]
     def queryable_validate_filter_params(filter_params)
       return nil if filter_params.nil?
 
-      unpermitted = filter_params.except(*_queryable_filter_keys)
+      filters = (((_queryable_filter_keys || []) | (self._queryable_expandable_filter_keys || [])) + ['not']).map(&:to_sym)
+      unpermitted = filter_params.except(*filters)
       Rails.logger.warn("Unpermitted queryable parameters: #{unpermitted.keys.join(', ')}") if unpermitted.present?
 
-      filter_params.slice(*_queryable_filter_keys)
+      filter_params.slice(*filters)
     end
 
+    # @param params [String,nil]
+    # @return [Hash]
     def queryable_parse_order_params(params)
       return nil unless params.is_a? String
 
@@ -95,6 +196,9 @@ module ActiveQueryable
       end.to_h
     end
 
+    # @param params [Hash,ActionController::Parameters,nil]
+    # @param query [ActiveRecord::Relation]
+    # @return [ActiveRecord::Relation]
     def queryable_parse_order_scope(params, query)
       return query unless params
 
@@ -109,13 +213,15 @@ module ActiveQueryable
       end || query
     end
 
+    # @param params [Hash,ActionController::Parameters,nil]
+    # @param query [ActiveRecord::Relation]
+    # @return [ActiveRecord::Relation]
     def queryable_parse_filter_scope(params, query)
       return query unless params
 
       params.inject(query) do |current_query, (k, v)|
         scope = "of_#{k}"
 
-
         if current_query.respond_to?(scope, true)
           current_query.public_send(scope, v)
         else
@@ -125,4 +231,7 @@ module ActiveQueryable
     end
   end
 end
-ActiveRecord::Base.send :extend, ActiveQueryable::Initializer
+
+# rubocop:disable Lint/SendWithMixinArgument
+ActiveRecord::Base.send(:extend, ActiveQueryable::Initializer)
+# rubocop:enable Lint/SendWithMixinArgument

data/spec/active_queryable/filters_spec.rb

@@ -3,8 +3,9 @@ require 'spec_helper'
 describe 'Filters' do
   context 'default filters' do
     it 'applies column name-based filters' do
-      query = Person.query_by(filter: { name: 'john doe' }, per: 'all')
+      query = Person.query_by(filter: { name: 'john doe', email: 'e@mail.com' }, per: 'all')
       expect(query.to_sql).to include('"people"."name" = \'john doe\'')
+      expect(query.to_sql).to include('"people"."email" = \'e@mail.com\'')
       expect(query).to include(Person.first)
     end
 

data/spec/support/schema.rb

@@ -5,9 +5,16 @@ ActiveRecord::Base.establish_connection(
   database: ':memory:'
 )
 
-class Person < ActiveRecord::Base
+class Common < ActiveRecord::Base
+  self.abstract_class = true
+
   as_queryable
-  queryable order: { name: :asc }, filter: ['name', 'article_title']
+  queryable order: { name: :asc }, filter: ['name']
+end
+
+class Person < Common
+  expand_queryable filter: ['email']
+  expand_queryable filter: ['article_title']
 
   has_many :articles
 
@@ -16,6 +23,7 @@ class Person < ActiveRecord::Base
 
 end
 
+
 class Article < ActiveRecord::Base
   as_queryable
   queryable order: { title: :asc }, filter: ['title']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_queryable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Mònade
@@ -19,7 +19,7 @@ dependencies:
         version: '5'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '5'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '8'
 - !ruby/object:Gem::Dependency
   name: kaminari-activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -99,21 +99,21 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.2.33
 signing_key: 
 specification_version: 4
 summary: Gem to make easier model's filtering, sorting and pagination
 test_files:
-- spec/spec_helper.rb
+- spec/active_queryable/filters_spec.rb
 - spec/active_queryable/ordering_spec.rb
 - spec/active_queryable/pagination_spec.rb
-- spec/active_queryable/filters_spec.rb
-- spec/support/schema.rb
+- spec/spec_helper.rb
 - spec/support/match_queries.rb
+- spec/support/schema.rb