datagrid 1.8.1 → 2.0.0.pre.alpha

data/lib/datagrid/configuration.rb

@@ -1,14 +1,27 @@
-module Datagrid
-
-  def self.configuration
-    @configuration ||= Configuration.new
-  end
+# frozen_string_literal: true
 
-  def self.configure
-    yield(configuration)
-  end
-
-  # Datagrid configuration object
+module Datagrid
+  # ## Configuration
+  #
+  # Datagrid provides several configuration options.
+  #
+  # Here is the API reference and a description of the available options:
+  #
+  # ``` ruby
+  # Datagrid.configure do |config|
+  #   # Defines date formats that can be used to parse dates.
+  #   # Note: Multiple formats can be specified. The first format is used to format dates as strings,
+  #   # while other formats are used only for parsing dates from strings (e.g., if your app supports multiple formats).
+  #   config.date_formats = ["%m/%d/%Y", "%Y-%m-%d"]
+  #
+  #   # Defines timestamp formats that can be used to parse timestamps.
+  #   # Note: Multiple formats can be specified. The first format is used to format timestamps as strings,
+  #   # while other formats are used only for parsing timestamps from strings (e.g., if your app supports multiple formats).
+  #   config.datetime_formats = ["%m/%d/%Y %h:%M", "%Y-%m-%d %h:%M:%s"]
+  # end
+  # ```
+  #
+  # These options can be set globally in your application to customize Datagrid’s behavior.
   class Configuration
     # @return [Array<String>] Date parsing formats
     attr_accessor :date_formats

data/lib/datagrid/core.rb

@@ -1,48 +1,77 @@
+# frozen_string_literal: true
+
 require "datagrid/drivers"
 require "active_support/core_ext/class/attribute"
+require "active_model/attribute_assignment"
 
 module Datagrid
+  # Simple example of using Datagrid scope as the assets source to be queried from the database.
+  #
+  # In most cases, the scope is a model class with some default ORM scopes, like `order` or `includes`:
+  #
+  # The scope is also used to:
+  # - Choose an ORM driver (e.g., Mongoid, ActiveRecord, etc.).
+  # - Association preloading
+  # - Columns Providing default order
+  #
+  # You can set the scope at class level or instance level.
+  # Both having appropriate use cases
+  #
+  # @example Defining a scope in a grid class
+  #   class ProjectsGrid
+  #     include Datagrid
+  #     scope { Project.includes(:category) }
+  #   end
+  #
+  # @example Setting a scope at the instance level
+  #   grid = ProjectsGrid.new(grid_params) do |scope|
+  #     scope.where(owner_id: current_user.id)
+  #   end
+  #
+  #   grid.assets # => SELECT * FROM projects WHERE projects.owner_id = ? AND [other filtering conditions]
+  #
+  # @example Retrieving and redefining the scope
+  #   grid.scope # => SELECT * FROM projects WHERE projects.user_id = ?
+  #   grid.redefined_scope? # => true
+  #
+  #   # Reset scope to default class value
+  #   grid.reset_scope
+  #   grid.assets # => SELECT * FROM projects
+  #   grid.redefined_scope? # => false
+  #
+  #   # Overwriting the scope (ignoring previously defined)
+  #   grid.scope { current_user.projects }
+  #   grid.redefined_scope? # => true
   module Core
+    include ::ActiveModel::AttributeAssignment
 
     # @!visibility private
     def self.included(base)
       base.extend ClassMethods
       base.class_eval do
         class_attribute :scope_value
-
-        class_attribute :datagrid_attributes, instance_writer: false
-        self.datagrid_attributes = []
-
+        class_attribute :datagrid_attributes, instance_writer: false, default: []
         class_attribute :dynamic_block, instance_writer: false
-        class_attribute :forbidden_attributes_protection, instance_writer: false
-        self.forbidden_attributes_protection = false
-        if defined?(::ActiveModel::AttributeAssignment)
-          include ::ActiveModel::AttributeAssignment
-        end
+        class_attribute :forbidden_attributes_protection, instance_writer: false, default: false
       end
-      base.include InstanceMethods
     end
 
     module ClassMethods
-
       # @!visibility private
       def datagrid_attribute(name, &block)
-        unless datagrid_attributes.include?(name)
-          block ||= lambda do |value|
-            value
-          end
-          datagrid_attributes << name
-          define_method name do
-            instance_variable_get("@#{name}")
-          end
+        return if datagrid_attributes.include?(name)
 
-          define_method :"#{name}=" do |value|
-            instance_variable_set("@#{name}", instance_exec(value, &block))
-          end
+        datagrid_attributes << name
+        define_method name do
+          instance_variable_get("@#{name}")
+        end
+
+        define_method :"#{name}=" do |value|
+          instance_variable_set("@#{name}", block ? instance_exec(value, &block) : value)
         end
       end
 
-      # Defines a scope at class level
+      # Defines a relation scope of database models to be filtered
       # @return [void]
       # @example
       #   scope { User }
@@ -115,163 +144,168 @@ module Datagrid
           end
       end
 
-      protected
-
+      # @!visibility private
       def check_scope_defined!(message = nil)
         message ||= "#{self}.scope is not defined"
         raise(Datagrid::ConfigurationError, message) unless scope_value
       end
 
+      protected
+
+      # @!visibility private
       def inherited(child_class)
-        super(child_class)
-        child_class.datagrid_attributes = self.datagrid_attributes.clone
+        super
+        child_class.datagrid_attributes = datagrid_attributes.clone
       end
-
     end
 
-    module InstanceMethods
+    # @param [Hash{String, Symbol => Object}] attributes a hash of attributes to initialize the object
+    # @yield [block] an optional block that is passed to the scope method for further customization
+    # @return [void] Initializes a new instance with optional attributes and an optional block.
+    def initialize(attributes = nil, &block)
+      super()
 
-      def initialize(attributes = nil, &block)
-        super()
+      self.attributes = attributes if attributes
 
-        if attributes
-          self.attributes = attributes
-        end
+      instance_eval(&dynamic_block) if dynamic_block
+      return unless block_given?
 
-        instance_eval(&dynamic_block) if dynamic_block
-        if block_given?
-          self.scope(&block)
-        end
-      end
+      scope(&block)
+    end
 
-      # @return [Hash<Symbol, Object>] grid attributes including filter values and ordering values
-      def attributes
-        result = {}
-        self.datagrid_attributes.each do |name|
-          result[name] = self[name]
-        end
-        result
+    # @return [Hash{Symbol => Object}] grid attributes including filter values and ordering values
+    # @example
+    #   class UsersGrid < ApplicationGrid
+    #     scope { User }
+    #     filter(:first_name, :string)
+    #     filter(:last_name, :string)
+    #   end
+    #
+    #   grid = UsersGrid.new(first_name: 'John', last_name: 'Smith')
+    #   grid.attributes # => {first_name: 'John', last_name: 'Smith', order: nil, descending: nil}
+    def attributes
+      result = {}
+      datagrid_attributes.each do |name|
+        result[name] = self[name]
       end
+      result
+    end
 
-      # @return [Object] Any datagrid attribute value
-      def [](attribute)
-        self.send(attribute)
-      end
+    # @param [String, Symbol] attribute attribute name
+    # @return [Object] Any datagrid attribute value
+    def [](attribute)
+      public_send(attribute)
+    end
 
-      # Assigns any datagrid attribute
-      # @param attribute [Symbol, String] Datagrid attribute name
-      # @param value [Object] Datagrid attribute value
-      # @return [void]
-      def []=(attribute, value)
-        self.send(:"#{attribute}=", value)
-      end
+    # Assigns any datagrid attribute
+    # @param attribute [Symbol, String] Datagrid attribute name
+    # @param value [Object] Datagrid attribute value
+    # @return [void]
+    def []=(attribute, value)
+      public_send(:"#{attribute}=", value)
+    end
 
-      # @return [Object] a scope relation (e.g ActiveRecord::Relation) with all applied filters
-      def assets
-        scope
-      end
+    # @return [Object] a scope relation (e.g ActiveRecord::Relation) with all applied filters
+    def assets
+      scope
+    end
 
-      # Updates datagrid attributes with a passed hash argument
-      def attributes=(attributes)
-        if respond_to?(:assign_attributes)
-          if !forbidden_attributes_protection && attributes.respond_to?(:permit!)
-            attributes.permit!
-          end
-          assign_attributes(attributes)
-        else
-          attributes.each do |name, value|
-            self[name] = value
-          end
-          self
-        end
+    # @return [Hash{Symbol => Object}] serializable query arguments skipping all nil values
+    # @example
+    #   grid = ProductsGrid.new(category: 'dresses', available: true)
+    #   grid.as_query # => {category: 'dresses', available: true}
+    def as_query
+      attributes = self.attributes.clone
+      attributes.each do |key, value|
+        attributes.delete(key) if value.nil?
       end
+      attributes
+    end
 
-      # Returns serializable query arguments skipping all nil values
-      # @example
-      #   grid = ProductsGrid.new(category: 'dresses', available: true)
-      #   grid.as_query # => {category: 'dresses', available: true}
-      def as_query
-        attributes = self.attributes.clone
-        attributes.each do |key, value|
-          attributes.delete(key) if value.nil?
-        end
-        attributes
-      end
+    # @return [Hash{Symbol => Hash{Symbol => Object}}] query parameters to link this grid from a page
+    # @example
+    #   grid = ProductsGrid.new(category: 'dresses', available: true)
+    #   Rails.application.routes.url_helpers.products_path(grid.query_params)
+    #     # => "/products?products_grid[category]=dresses&products_grid[available]=true"
+    def query_params(attributes = {})
+      { param_name.to_sym => as_query.merge(attributes) }
+    end
 
-      # @return [Hash<Symbol, Hash<Symbol, Object>>] query parameters to link this grid from a page
-      # @example
-      #   grid = ProductsGrid.new(category: 'dresses', available: true)
-      #   Rails.application.routes.url_helpers.products_path(grid.query_params)
-      #     # => "/products?products_grid[category]=dresses&products_grid[available]=true"
-      def query_params(attributes = {})
-        { param_name.to_sym => as_query.merge(attributes) }
+    # @return [void] redefines scope at instance level
+    # @example
+    #   class MyGrid
+    #     scope { Article.order('created_at desc') }
+    #   end
+    #
+    #   grid = MyGrid.new
+    #   grid.scope do |scope|
+    #     scope.where(author_id: current_user.id)
+    #   end
+    #   grid.assets
+    #       # => SELECT * FROM articles WHERE author_id = ?
+    #       #    ORDER BY created_at desc
+    def scope(&block)
+      if block_given?
+        current_scope = scope
+        self.scope_value = proc {
+          Datagrid::Utils.apply_args(current_scope, &block)
+        }
+        self
+      else
+        scope = original_scope
+        driver.to_scope(scope)
       end
+    end
 
-      # Redefines scope at instance level
-      # @example
-      #   class MyGrid
-      #     scope { Article.order('created_at desc') }
-      #   end
-      #
-      #   grid = MyGrid.new
-      #   grid.scope do |scope|
-      #     scope.where(author_id: current_user.id)
-      #   end
-      #   grid.assets
-      #       # => SELECT * FROM articles WHERE author_id = ?
-      #       #    ORDER BY created_at desc
-      def scope(&block)
-        if block_given?
-          current_scope = scope
-          self.scope_value = proc {
-            Datagrid::Utils.apply_args(current_scope, &block)
-          }
-          self
-        else
-          scope = original_scope
-          driver.to_scope(scope)
-        end
-      end
+    # @!visibility private
+    def original_scope
+      self.class.check_scope_defined!
+      scope_value.call
+    end
 
-      # @!visibility private
-      def original_scope
-        check_scope_defined!
-        scope_value.call
-      end
+    # @return [void] Resets current instance scope to default scope defined in a class
+    def reset_scope
+      self.scope_value = self.class.scope_value
+    end
 
-      # Resets current instance scope to default scope defined in a class
-      # @return [void]
-      def reset_scope
-        self.scope_value = self.class.scope_value
-      end
+    # @return [Boolean] true if the scope was redefined for this instance of grid object
+    def redefined_scope?
+      self.class.scope_value != scope_value
+    end
 
-      # @return [Boolean] true if the scope was redefined for this instance of grid object
-      def redefined_scope?
-        self.class.scope_value != scope_value
-      end
+    # @!visibility private
+    def driver
+      self.class.driver
+    end
 
-      # @!visibility private
-      def driver
-        self.class.driver
-      end
+    # @return [String] a datagrid attributes and their values in inspection form
+    def inspect
+      attrs = attributes.map do |key, value|
+        "#{key}: #{value.inspect}"
+      end.join(", ")
+      "#<#{self.class} #{attrs}>"
+    end
 
-      # @!visibility private
-      def check_scope_defined!(message = nil)
-        self.class.send :check_scope_defined!, message
-      end
+    def ==(other)
+      self.class == other.class &&
+        attributes == other.attributes &&
+        scope == other.scope
+    end
 
-      # @return [String] a datagrid attributes and their values in inspection form
-      def inspect
-        attrs = attributes.map do |key, value|
-          "#{key}: #{value.inspect}"
-        end.join(", ")
-        "#<#{self.class} #{attrs}>"
-      end
+    # @return [void] Resets loaded assets and column values cache
+    def reset
+      assets.reset
+    end
 
-      def ==(other)
-        self.class == other.class &&
-          attributes == other.attributes &&
-          scope == other.scope
+    protected
+
+    def sanitize_for_mass_assignment(attributes)
+      if forbidden_attributes_protection
+        super
+      elsif defined?(ActionController::Parameters) && attributes.is_a?(ActionController::Parameters)
+        attributes.to_unsafe_h
+      else
+        attributes
       end
     end
   end

data/lib/datagrid/deprecated_object.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Datagrid
+  # @!visibility private
+  class DeprecatedObject < BasicObject
+    def initialize(real_object, &block)
+      @real_object = real_object
+      @block = block
+    end
+
+    def method_missing(method_name, ...)
+      @block.call
+      @real_object.public_send(method_name, ...)
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @real_object.respond_to?(method_name, include_private)
+    end
+  end
+end

data/lib/datagrid/drivers/abstract_driver.rb

@@ -1,20 +1,20 @@
+# frozen_string_literal: true
+
 module Datagrid
   module Drivers
     # @!visibility private
     class AbstractDriver
+      TIMESTAMP_CLASSES = [DateTime, Time, ActiveSupport::TimeWithZone].freeze
 
-      TIMESTAMP_CLASSES = [DateTime, Time, ActiveSupport::TimeWithZone]
-
-      class_attribute :subclasses
+      class_attribute :subclasses, default: []
 
       def self.inherited(base)
-        super(base)
-        self.subclasses ||= []
-        self.subclasses << base
+        super
+        subclasses << base
       end
 
       def self.guess_driver(scope)
-        self.subclasses.find do |driver_class|
+        subclasses.find do |driver_class|
           driver_class.match?(scope)
         end || raise(Datagrid::ConfigurationError, "ORM Driver not found for scope: #{scope.inspect}.")
       end
@@ -55,7 +55,7 @@ module Datagrid
         raise NotImplementedError
       end
 
-      def has_column?(scope, column_name)
+      def scope_has_column?(scope, column_name)
         raise NotImplementedError
       end
 
@@ -63,7 +63,7 @@ module Datagrid
         raise NotImplementedError
       end
 
-      def is_timestamp?(scope, field)
+      def timestamp_column?(scope, field)
         normalized_column_type(scope, field) == :timestamp
       end
 
@@ -84,28 +84,15 @@ module Datagrid
       end
 
       def append_column_queries(assets, columns)
-        if columns.present?
-          raise NotImplementedError
-        else
-          assets
-        end
+        raise NotImplementedError if columns.present?
+
+        assets
       end
 
       def default_cache_key(asset)
         raise NotImplementedError
       end
 
-      def where_by_timestamp_gotcha(scope, name, value)
-        value = Datagrid::Utils.format_date_as_timestamp(value)
-        if value.first
-          scope = greater_equal(scope, name, value.first)
-        end
-        if value.last
-          scope = less_equal(scope, name, value.last)
-        end
-        scope
-      end
-
       def default_preload(scope, value)
         raise NotImplementedError
       end
@@ -115,6 +102,7 @@ module Datagrid
       end
 
       protected
+
       def timestamp_class?(klass)
         TIMESTAMP_CLASSES.include?(klass)
       end

data/lib/datagrid/drivers/active_record.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 module Datagrid
   module Drivers
     # @!visibility private
     class ActiveRecord < AbstractDriver
-
       def self.match?(scope)
         return false unless defined?(::ActiveRecord)
+
         if scope.is_a?(Class)
           scope.ancestors.include?(::ActiveRecord::Base)
         else
@@ -14,6 +16,7 @@ module Datagrid
 
       def to_scope(scope)
         return scope if scope.is_a?(::ActiveRecord::Relation)
+
         # Model class or Active record association
         # ActiveRecord association class hides itself under an Array
         # We can only reveal it by checking if it respond to some specific
@@ -29,10 +32,8 @@ module Datagrid
 
       def append_column_queries(assets, columns)
         if columns.present?
-          if assets.select_values.empty?
-            assets = assets.select(Arel.respond_to?(:star) ? assets.klass.arel_table[Arel.star] : "#{assets.quoted_table_name}.*")
-          end
-          columns = columns.map {|c| "#{c.query} AS #{c.name}"}
+          assets = assets.select(assets.klass.arel_table[Arel.star]) if assets.select_values.empty?
+          columns = columns.map { |c| "#{c.query} AS #{c.name}" }
           assets = assets.select(*columns)
         end
         assets
@@ -61,7 +62,7 @@ module Datagrid
       end
 
       def default_order(scope, column_name)
-        has_column?(scope, column_name) ? prefix_table_name(scope, column_name) : nil
+        scope_has_column?(scope, column_name) ? prefix_table_name(scope, column_name) : nil
       end
 
       def greater_equal(scope, field, value)
@@ -72,7 +73,7 @@ module Datagrid
         scope.where(["#{prefix_table_name(scope, field)} <= ?", value])
       end
 
-      def has_column?(scope, column_name)
+      def scope_has_column?(scope, column_name)
         scope.column_names.include?(column_name.to_s)
       rescue ::ActiveRecord::StatementInvalid
         false
@@ -88,15 +89,16 @@ module Datagrid
       end
 
       def normalized_column_type(scope, field)
-        return nil unless has_column?(scope, field)
+        return nil unless scope_has_column?(scope, field)
+
         builtin_type = scope.columns_hash[field.to_s].type
         {
-          [:string, :text, :time, :binary] => :string,
-          [:integer, :primary_key] => :integer,
-          [:float, :decimal] => :float,
+          %i[string text time binary] => :string,
+          %i[integer primary_key] => :integer,
+          %i[float decimal] => :float,
           [:date] => :date,
-          [:datetime, :timestamp] => :timestamp,
-          [:boolean] => :boolean
+          %i[datetime timestamp] => :timestamp,
+          [:boolean] => :boolean,
         }.each do |keys, value|
           return value if keys.include?(builtin_type)
         end
@@ -106,6 +108,7 @@ module Datagrid
         if scope.limit_value
           raise Datagrid::ConfigurationError, "ActiveRecord can not use batches in combination with SQL limit"
         end
+
         options = batch_size ? { batch_size: batch_size } : {}
         scope.find_each(**options, &block)
       end
@@ -119,28 +122,23 @@ module Datagrid
       end
 
       def can_preload?(scope, association)
-        !! scope.klass.reflect_on_association(association)
+        !!scope.klass.reflect_on_association(association)
       end
 
       protected
 
       def prefix_table_name(scope, field)
-        has_column?(scope, field) ?  [scope.table_name, field].join(".") : field
+        scope_has_column?(scope, field) ? [scope.table_name, field].join(".") : field
       end
 
       def contains_predicate
-        defined?(::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter) &&
-          ::ActiveRecord::Base.connection.is_a?(::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter) ?
-          'ilike' : 'like'
+        if defined?(::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter) &&
+           ::ActiveRecord::Base.connection.is_a?(::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter)
+          "ilike"
+        else
+          "like"
+        end
       end
     end
   end
 end
-
-if defined?(ActiveRecord::Base)
-  ActiveRecord::Base.class_eval do
-    def self.datagrid_where_by_timestamp(column, value)
-      Datagrid::Drivers::ActiveRecord.new.where_by_timestamp_gotcha(self, column, value)
-    end
-  end
-end