warped 0.1.0

data/lib/warped/controllers/filterable.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/enumerable"
+
+module Warped
+  module Controllers
+    # Provides functionality for filtering records from an +ActiveRecord::Relation+ in a controller.
+    #
+    # Example usage:
+    #
+    #   class UsersController < ApplicationController
+    #     include Filterable
+    #
+    #     filterable_by :name, :created_at, 'accounts.kind'
+    #
+    #     def index
+    #       scope = filter(User.joins(:account))
+    #       render json: scope
+    #     end
+    #   end
+    #
+    # Example requests:
+    #   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
+    #
+    # Filters can be combined:
+    #   GET /users?name=John&created_at=2020-01-01
+    #
+    # Renaming filter keys:
+    #
+    # In some cases, you may not want to expose the actual column names to the client.
+    # In such cases, you can rename the filter keys by passing a hash to the +filterable_by+ method.
+    #
+    # Example:
+    #
+    #   class UsersController < ApplicationController
+    #     include Filterable
+    #
+    #     filterable_by :name, :created_at, 'accounts.kind' => 'kind'
+    #
+    #     def index
+    #       scope = filter(User.joins(:account))
+    #       render json: scope
+    #     end
+    #   end
+    #
+    # Example requests:
+    #   GET /users?kind=premium
+    #
+    # Using relations:
+    #
+    # In some cases, you may want to filter records based on a relation.
+    # For example, you may want to filter users based on operands like:
+    # - greater than
+    # - less than
+    # - not equal
+    # @see Warped::Queries::Filter::RELATIONS
+    # To see the full list of operands, check the +Warped::Queries::Filter::RELATIONS+ constant.
+    #
+    # 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
+    #
+    # When the operand relation requires multiple values, like +in+, +not_in+, or +between+,
+    # you can pass an array of values.
+    #
+    # 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
+    module Filterable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :filter_fields, default: []
+        class_attribute :mapped_filter_fields, default: []
+      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
+        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
+      # @return [ActiveRecord::Relation]
+      def filter(scope, filter_conditions: filter_conditions(*filter_fields, *mapped_filter_fields))
+        Warped::Queries::Filter.call(scope, filter_conditions:)
+      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
+
+      private
+
+      def filter_name(filter)
+        filter.is_a?(Array) ? filter.first : filter
+      end
+
+      def filter_mapped_name(filter)
+        filter.is_a?(Array) ? filter.last : filter
+      end
+
+      def filter_value(filter)
+        param_key = filter_mapped_name(filter)
+        params[param_key]
+      end
+
+      def filter_rel_value(filter)
+        param_key = filter_mapped_name(filter)
+        params["#{param_key}.rel"]
+      end
+    end
+  end
+end

data/lib/warped/controllers/pageable.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+module Warped
+  module Controllers
+    # Provides functionality for paginating records from an +ActiveRecord::Relation+ in a controller.
+    #
+    # Example usage:
+    #
+    #   class UsersController < ApplicationController
+    #     include Pageable
+    #
+    #     def index
+    #       scope = paginate(User.all)
+    #       render json: scope, root: :users, meta: page_info
+    #     end
+    #   end
+    #
+    # Example requests:
+    #   GET /users?page=1&per_page=10
+    #   GET /users?page=2&per_page=50
+    #
+    # The +per_page+ parameter is optional. If not provided, the default value will be used.
+    #
+    # The default value can be set at a controller level using the +default_per_page+ class attribute.
+    # Example:
+    #   class UsersController < ApplicationController
+    #     include Pageable
+    #
+    #     self.default_per_page = 50
+    #
+    #     def index
+    #       scope = paginate(User.all)
+    #       render json: scope, root: :users, meta: page_info
+    #     end
+    #   end
+    #
+    # Or by overriding the +default_per_page+ controller instance method.
+    # Example:
+    #   class UsersController < ApplicationController
+    #     include Pageable
+    #
+    #     def index
+    #       scope = paginate(User.all)
+    #       render json: scope, root: :users, meta: page_info
+    #     end
+    #
+    #     private
+    #
+    #     def default_per_page
+    #       50
+    #     end
+    #   end
+    #
+    # The +per_page+ value can also be set at action level, by passing the +per_page+ parameter to
+    # the +paginate+ method.
+    # Example:
+    #   class UsersController < ApplicationController
+    #     include Pageable
+    #
+    #     def index
+    #       scope = paginate(User.all, per_page: 50)
+    #       render json: scope, root: :users, meta: page_info
+    #     end
+    #
+    #     def other_index
+    #       # The default per_page value is used.
+    #       scope = paginate(User.all)
+    #       render json: scope, root: :users, meta: page_info
+    #     end
+    #   end
+    #
+    # The pagination metadata can be accessed by calling the +page_info+ method.
+    # It includes the following keys:
+    # - +total_count+: The total number of records in the collection.
+    # - +total_pages+: The total number of pages.
+    # - +next_page+: The next page number.
+    # - +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
+    # called within the action.
+    module Pageable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :default_per_page, default: Queries::Paginate::DEFAULT_PER_PAGE
+      end
+
+      # Paginates the given scope.
+      #
+      # @param scope [ActiveRecord::Relation] The scope to be paginated.
+      # @param page [String,Integer,nil] The page number.
+      # @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:)
+        paginated_scope
+      end
+
+      # Retrieves the page number from the request parameters.
+      #
+      # @return [String,nil] The page number if present, otherwise nil.
+      def page
+        params[:page]&.to_i || 1
+      end
+
+      # Retrieves the number of records per page from the request parameters or defaults to the
+      # controller's default value.
+      #
+      # @return [String,Integer] The number of records per page.
+      def per_page
+        params[:per_page].presence || self.class.default_per_page
+      end
+
+      # Retrieves pagination metadata.
+      #
+      # @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?
+
+        raise ActionController::BadRequest, "Pagination was not performed"
+      end
+    end
+  end
+end

data/lib/warped/controllers/searchable.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+module Warped
+  module Controllers
+    # Provides functionality for searching records from an +ActiveRecord::Relation+ in a controller.
+    #
+    # Example usage:
+    #   class User < ApplicationRecord
+    #     scope :search, ->(term) { where('name ILIKE ?', "%#{term}%") }
+    #   end
+    #
+    #   class UsersController < ApplicationController
+    #     include Searchable
+    #
+    #     def index
+    #       scope = search(User.all)
+    #       render json: scope
+    #     end
+    #   end
+    #
+    # Example requests:
+    #   GET /users?q=John
+    #   GET /users?q=John%20Doe
+    #
+    # There are cases where the search scope is not called +search+.
+    # In such cases, you can use the +searchable_by+ method to override the search scope.
+    #
+    # Example:
+    #   class User < ApplicationRecord
+    #     scope :search_case_sensitive, ->(term) { where('name LIKE ?', "%#{term}%") }
+    #   end
+    #
+    #   class UsersController < ApplicationController
+    #     include Searchable
+    #
+    #     searchable_by :search_case_sensitive
+    #
+    #     def index
+    #       scope = search(User.all)
+    #       render json: scope
+    #     end
+    #   end
+    #
+    # When only overriding the search scope for a single action, you can pass the scope name as an argument to
+    # the +search+ method.
+    # Example:
+    #   class UsersController < ApplicationController
+    #     include Searchable
+    #
+    #     def index
+    #       # The default search scope name is overridden.
+    #       # runs User.all.search_case_sensitive(search_term)
+    #       scope = search(User.all, model_search_scope: :search_case_sensitive)
+    #       render json: scope
+    #     end
+    #
+    #     def other_index
+    #       # The default search scope name is used.
+    #       # runs User.all.search(search_term)
+    #       scope = search(User.all)
+    #       render json: scope
+    #     end
+    #   end
+    #
+    # In addition, you can override the search term parameter name for the entire controller by implementing
+    # the +search_param+ method.
+    #
+    # Example:
+    #   class UsersController < ApplicationController
+    #     include Searchable
+    #
+    #     def index
+    #       scope = search(User.all)
+    #       render json: scope
+    #     end
+    #
+    #     private
+    #
+    #     def search_param
+    #       :term
+    #     end
+    #   end
+    #
+    # Or you can override the search term parameter name for a single action by passing the parameter name as
+    # an argument to the +search_term+ method.
+    #
+    # Example:
+    #   class UsersController < ApplicationController
+    #     include Searchable
+    #
+    #     def index
+    #       # The default search term parameter name (+q+) is overridden.
+    #       # GET /users?term=John
+    #       scope = search(User.all, search_term: params[:term])
+    #       render json: scope
+    #     end
+    #
+    #     def other_index
+    #       # The default search term parameter name (+q+) is used.
+    #       # GET /other_users?q=John
+    #       scope = search(User.all)
+    #       render json: scope
+    #     end
+    #   end
+    #
+    # Example requests:
+    #   GET /users?term=John
+    #   GET /other_users?q=John%20Doe
+    module Searchable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :model_search_scope, default: :search
+        class_attribute :search_param, default: :q
+      end
+
+      class_methods do
+        # Sets the search scope.
+        #
+        # @param scope [Symbol] The name of the search scope.
+        def searchable_by(scope = model_search_scope, param: :q)
+          self.model_search_scope = scope
+          self.search_param = param
+        end
+      end
+
+      # Searches records based on the provided scope and search term.
+      #
+      # @param scope [ActiveRecord::Relation] The scope to search within.
+      # @param search_term [String] The search term.
+      # @param model_search_scope [Symbol] The name of the search scope.
+      # @return [ActiveRecord::Relation] The result of the search.
+      def search(scope, search_term: self.search_term, model_search_scope: self.model_search_scope)
+        Queries::Search.call(scope, search_term:, model_search_scope:)
+      end
+
+      # Retrieves the search term from the request parameters.
+      #
+      # @return [String, nil] The search term if present, otherwise nil.
+      def search_term
+        params[search_param]&.strip
+      end
+
+      # Returns the name of the parameter used for searching.
+      #
+      # @return [Symbol] The search parameter name.
+      def search_param
+        self.class.search_param
+      end
+
+      # Returns the name of the model's search scope.
+      #
+      # @return [Symbol] The name of the model's search scope.
+      def model_search_scope
+        self.class.model_search_scope
+      end
+    end
+  end
+end

data/lib/warped/controllers/sortable.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+module Warped
+  module Controllers
+    # Provides functionality for sorting records from an +ActiveRecord::Relation+ in a controller.
+    #
+    # Example usage:
+    #
+    #   class UsersController < ApplicationController
+    #     include Sortable
+    #
+    #     sortable_by :name, :created_at, 'accounts.kind'
+    #
+    #     def index
+    #       scope = sort(User.joins(:account))
+    #       render json: scope
+    #     end
+    #   end
+    #
+    # Example requests:
+    #   GET /users?sort_key=name
+    #   GET /users?sort_key=name&sort_direction=asc_nulls_first
+    #   GET /users?sort_key=created_at&sort_direction=asc
+    #
+    # Renaming sort keys:
+    #
+    # In some cases, you may not want to expose the actual column names to the client.
+    # In such cases, you can rename the sort keys by passing a hash to the +sortable_by+ method.
+    #
+    # Example:
+    #
+    #   class UsersController < ApplicationController
+    #     include Sortable
+    #
+    #     sortable_by :name, :created_at, 'accounts.referrals_count' => 'referrals'
+    #
+    #     def index
+    #       scope = sort(User.joins(:account))
+    #       render json: scope
+    #     end
+    #   end
+    #
+    # Example requests:
+    #   GET /users?sort_key=referrals&sort_direction=asc
+    #
+    # The +sort_key+ and +sort_direction+ parameters are optional. If not provided, the default sort key and direction
+    # will be used.
+    #
+    # The default sort key and sort direction can be set at a controller level using the +default_sort_direction+ and
+    # +default_sort_key+ class attributes.
+    module Sortable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :sort_fields, default: []
+        class_attribute :mapped_sort_fields, default: {}
+        class_attribute :default_sort_key, default: :id
+        class_attribute :default_sort_direction, default: :desc
+      end
+
+      class_methods do
+        # @param keys [Array<Symbol,String>]
+        # @param mapped_keys [Hash<Symbol,String>]
+        def sortable_by(*keys, **mapped_keys)
+          self.sort_fields = keys.map(&:to_s)
+          self.mapped_sort_fields = mapped_keys.with_indifferent_access
+        end
+      end
+
+      # @param scope [ActiveRecord::Relation] The scope to sort.
+      # @param sort_key [String, Symbol] The sort key.
+      # @param sort_direction [String, Symbol] The sort direction.
+      # @return [ActiveRecord::Relation]
+      def sort(scope, sort_key: self.sort_key, sort_direction: self.sort_direction)
+        return scope unless sort_key && sort_direction
+
+        validate_sort_key!
+
+        Queries::Sort.call(scope, sort_key:, sort_direction:)
+      end
+
+      protected
+
+      # @return [Symbol] The sort direction.
+      def sort_direction
+        @sort_direction ||= params[:sort_direction] || default_sort_direction
+      end
+
+      def sort_key
+        @sort_key ||= mapped_sort_fields.key(params[:sort_key]).presence ||
+                      params[:sort_key] ||
+                      default_sort_key
+      end
+
+      private
+
+      def validate_sort_key!
+        return if valid_sort_key?
+
+        possible_values = sort_fields + mapped_sort_fields.values
+        message = "Invalid sort key: #{sort_key}, must be one of #{possible_values}"
+        raise ActionController::BadRequest, message
+      end
+
+      def valid_sort_key?
+        sort_key == default_sort_key ||
+          sort_fields.include?(sort_key) ||
+          mapped_sort_fields[sort_key].present?
+      end
+    end
+  end
+end

data/lib/warped/controllers/tabulatable.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+module Warped
+  module Controllers
+    # Provides functionality for filtering, sorting, searching, and paginating records
+    # from an +ActiveRecord::Relation+ in a controller.
+    #
+    # Example usage:
+    #
+    #   class UsersController < ApplicationController
+    #     include Tabulatable
+    #
+    #     tabulatable_by :name, :email, :age, 'posts.created_at', 'posts.id' => 'post_id'
+    #
+    #     def index
+    #       users = User.left_joins(:posts).group(:id)
+    #       users = tabulate(users)
+    #       render json: users, meta: tabulate_info
+    #     end
+    #   end
+    #
+    # There are cases where not all fields should be filterable or sortable.
+    # In such cases, you can use the `filterable_by` and `sortable_by` methods to
+    # override the tabulate fields.
+    #
+    # Example:
+    #
+    #   class PostsController < ApplicationController
+    #     include Tabulatable
+    #
+    #     tabulatable_by :title, :content, :created_at, user: 'users.name'
+    #     filterable_by :created_at, user: 'users.name'
+    #
+    #     def index
+    #       posts = Post.left_joins(:user).group(:id)
+    #       posts = tabulate(posts)
+    #       render json: posts, meta: tabulate_info
+    #     end
+    #   end
+    module Tabulatable
+      extend ActiveSupport::Concern
+
+      included do
+        include Filterable
+        include Sortable
+        include Searchable
+        include Pageable
+
+        class_attribute :tabulate_fields, default: []
+        class_attribute :mapped_tabulate_fields, default: []
+      end
+
+      class_methods do
+        def tabulatable_by(*keys, **mapped_keys)
+          self.tabulate_fields = keys
+          self.mapped_tabulate_fields = mapped_keys.to_a
+
+          filterable_by(*keys, **mapped_keys) if filter_fields.empty? && mapped_filter_fields.empty?
+          sortable_by(*keys, **mapped_keys) if sort_fields.empty? && mapped_sort_fields.empty?
+        end
+      end
+
+      # @param scope [ActiveRecord::Relation]
+      # @return [ActiveRecord::Relation]
+      # @see Filterable#filter
+      # @see Sortable#sort
+      # @see Searchable#search
+      # @see Pageable#paginate
+      def tabulate(scope)
+        scope = filter(scope)
+        scope = search(scope)
+        scope = sort(scope)
+        paginate(scope)
+      end
+
+      # @return [Hash]
+      def tabulate_info
+        {
+          filters: filter_conditions(*filter_fields, *mapped_filter_fields),
+          sorts: sort_conditions(*sort_fields, *mapped_sort_fields),
+          search_term:,
+          search_param:,
+          page_info:
+        }
+      end
+    end
+  end
+end

data/lib/warped/jobs/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "active_support/core_ext/string/inflections"
+
+module Warped
+  module Jobs
+    ##
+    # Base class for all jobs in the application.
+    # This class is used to provide a common interface for all jobs used by Warped
+    # and to allow for easy configuration of the parent class.
+    # By default, the parent class is set to +ActiveJob::Base+.
+    # @see Warped
+    #
+    # @example Change the parent class for Warped::Jobs::Base
+    #   Warped.configure do |config|
+    #     config.base_job_parent_class = "ApplicationJob"
+    #   end
+    #
+    class Base < Warped.base_job_parent_class.constantize
+    end
+  end
+end