active_queryable 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bf4db93e62b6ef9584ed59ac624d983debc4a7792dc4debc252fe4958c0e3ac
-  data.tar.gz: 38bd3b1e7b4e9138be78e1cfed968b9dc499894c5d6aa5d1710bf5d1aa032d26
+  metadata.gz: ca76d46d098d260a1f59a1fd6e50d59cbab69eb95ba87f25470ccb08aa3050f2
+  data.tar.gz: 9562f2b4d7a4cce6ba1ba6bb070c6e6d9cf031d6205bf1006e5b5c1f21566ed4
 SHA512:
-  metadata.gz: fe31f1bacbd161809ede6ad71b12793f1515a4b189b59006b5558ef7d4b9cdd5c43bb905bd2e932d8d087f15e014efce399c7ce13631277265522e9fb3c6a589
-  data.tar.gz: 4f0b563933703484579689cee4fbabe5445ad021115c73bc863f76f9db3ee61df511fa29bd9041aabb81ffbfa1020215005a916cf6de0cc6e4905573c209d2f6
+  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.3.0'
+  # @return [String] the version of the gem
+  VERSION = '0.3.1'
 end

data/lib/active_queryable.rb

@@ -1,12 +1,15 @@
 # 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
@@ -14,34 +17,94 @@ module ActiveQueryable
     class_attribute :_queryable_default_per
     class_attribute :_queryable_filter_keys
     class_attribute :_queryable_expandable_filter_keys
-	end
+  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] || [])).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))
+      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)
@@ -51,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])
 
@@ -67,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)
@@ -83,16 +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?
 
-      filters = (((self._queryable_filter_keys || []) | (self._queryable_expandable_filter_keys || [])) + ['not']).map(&:to_sym)
+      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(*filters)
     end
 
+    # @param params [String,nil]
+    # @return [Hash]
     def queryable_parse_order_params(params)
       return nil unless params.is_a? String
 
@@ -102,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
 
@@ -116,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
@@ -132,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_queryable
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Mònade