datagrid 1.8.2 → 2.0.0

data/lib/datagrid/configuration.rb

@@ -1,14 +1,43 @@
-module Datagrid
+# frozen_string_literal: true
 
+module Datagrid
+  # @return [Configuration] current Datagrid configuration
   def self.configuration
     @configuration ||= Configuration.new
   end
 
-  def self.configure
-    yield(configuration)
+  # @yield block to configure
+  # @yieldparam [Configuration] configuration
+  # @yieldreturn [void]
+  # @return [void] configure datagrid
+  # @see Datagrid::Configuration
+  def self.configure(&block)
+    block.call(configuration)
   end
 
-  # Datagrid configuration object
+  # ## 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,8 +1,47 @@
+# 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
 
@@ -18,25 +57,21 @@ module Datagrid
     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 }
@@ -109,57 +144,57 @@ 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
 
+    # @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()
 
-      if attributes
-        self.attributes = attributes
-      end
+      self.attributes = attributes if attributes
 
       instance_eval(&dynamic_block) if dynamic_block
-      if block_given?
-        self.scope(&block)
-      end
-    end
+      return unless block_given?
 
+      scope(&block)
+    end
 
-    # @return [Hash<Symbol, Object>] grid attributes including filter values and ordering values
+    # @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 = {}
-      self.datagrid_attributes.each do |name|
+      datagrid_attributes.each do |name|
         result[name] = self[name]
       end
       result
     end
 
-    # Updates datagrid attributes with a passed hash argument
-    # @param attributes [Hash<Symbol, Object>]
-    # @example
-    #   grid = MyGrid.new
-    #   grid.attributes = {first_name: 'John', last_name: 'Smith'}
-    #   grid.first_name # => 'John'
-    #   grid.last_name # => 'Smith'
-    def attributes=(attributes)
-      super(attributes)
-    end
-
+    # @param [String, Symbol] attribute attribute name
     # @return [Object] Any datagrid attribute value
     def [](attribute)
-      self.public_send(attribute)
+      public_send(attribute)
     end
 
     # Assigns any datagrid attribute
@@ -167,7 +202,7 @@ module Datagrid
     # @param value [Object] Datagrid attribute value
     # @return [void]
     def []=(attribute, value)
-      self.public_send(:"#{attribute}=", value)
+      public_send(:"#{attribute}=", value)
     end
 
     # @return [Object] a scope relation (e.g ActiveRecord::Relation) with all applied filters
@@ -175,7 +210,7 @@ module Datagrid
       scope
     end
 
-    # Returns serializable query arguments skipping all nil values
+    # @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}
@@ -187,7 +222,7 @@ module Datagrid
       attributes
     end
 
-    # @return [Hash<Symbol, Hash<Symbol, Object>>] query parameters to link this grid from a page
+    # @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)
@@ -196,7 +231,7 @@ module Datagrid
       { param_name.to_sym => as_query.merge(attributes) }
     end
 
-    # Redefines scope at instance level
+    # @return [void] redefines scope at instance level
     # @example
     #   class MyGrid
     #     scope { Article.order('created_at desc') }
@@ -224,12 +259,11 @@ module Datagrid
 
     # @!visibility private
     def original_scope
-      check_scope_defined!
+      self.class.check_scope_defined!
       scope_value.call
     end
 
-    # Resets current instance scope to default scope defined in a class
-    # @return [void]
+    # @return [void] Resets current instance scope to default scope defined in a class
     def reset_scope
       self.scope_value = self.class.scope_value
     end
@@ -244,11 +278,6 @@ module Datagrid
       self.class.driver
     end
 
-    # @!visibility private
-    def check_scope_defined!(message = nil)
-      self.class.send :check_scope_defined!, message
-    end
-
     # @return [String] a datagrid attributes and their values in inspection form
     def inspect
       attrs = attributes.map do |key, value|
@@ -263,15 +292,21 @@ module Datagrid
         scope == other.scope
     end
 
-    # Resets loaded assets and column values cache
-    # @return [void]
+    # @return [void] Resets loaded assets and column values cache
     def reset
       assets.reset
     end
 
     protected
+
     def sanitize_for_mass_assignment(attributes)
-      forbidden_attributes_protection ? super(attributes) : attributes
+      if forbidden_attributes_protection
+        super
+      elsif defined?(ActionController::Parameters) && attributes.is_a?(ActionController::Parameters)
+        attributes.to_unsafe_h
+      else
+        attributes
+      end
     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,19 +1,20 @@
+# frozen_string_literal: true
+
 module Datagrid
   module Drivers
     # @!visibility private
     class AbstractDriver
-
-      TIMESTAMP_CLASSES = [DateTime, Time, ActiveSupport::TimeWithZone]
+      TIMESTAMP_CLASSES = [DateTime, Time, ActiveSupport::TimeWithZone].freeze
 
       class_attribute :subclasses, default: []
 
       def self.inherited(base)
-        super(base)
-        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
@@ -54,7 +55,7 @@ module Datagrid
         raise NotImplementedError
       end
 
-      def has_column?(scope, column_name)
+      def scope_has_column?(scope, column_name)
         raise NotImplementedError
       end
 
@@ -62,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
 
@@ -83,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
@@ -114,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

data/lib/datagrid/drivers/array.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
+
 module Datagrid
   module Drivers
     # @!visibility private
     class Array < AbstractDriver
-
       def self.match?(scope)
         !Datagrid::Drivers::ActiveRecord.match?(scope) && (
           scope.is_a?(::Array) || scope.is_a?(Enumerator) ||
@@ -16,15 +17,16 @@ module Datagrid
 
       def where(scope, attribute, value)
         scope.select do |object|
-          object.public_send(attribute) == value
+          get(object, attribute) == value
         end
       end
 
       def asc(scope, order)
         return scope unless order
         return scope if order.empty?
+
         scope.sort_by do |object|
-          object.public_send(order)
+          get(object, order)
         end
       end
 
@@ -32,7 +34,7 @@ module Datagrid
         asc(scope, order).reverse
       end
 
-      def default_order(scope, column_name)
+      def default_order(_scope, column_name)
         column_name
       end
 
@@ -42,36 +44,36 @@ module Datagrid
 
       def greater_equal(scope, field, value)
         scope.select do |object|
-          object.public_send(field) >= value
+          get(object, field) >= value
         end
       end
 
       def less_equal(scope, field, value)
         scope.select do |object|
-          object.public_send(field) <= value
+          get(object, field) <= value
         end
       end
 
-      def has_column?(scope, column_name)
+      def scope_has_column?(scope, column_name)
         scope.any? && scope.first.respond_to?(column_name)
       end
 
-      def is_timestamp?(scope, column_name)
-        has_column?(scope, column_name) &&
-          timestamp_class?(scope.first.public_send(column_name).class)
+      def timestamp_column?(scope, column_name)
+        scope_has_column?(scope, column_name) &&
+          timestamp_class?(get(scope.first, column_name).class)
       end
 
       def contains(scope, field, value)
         scope.select do |object|
-          object.public_send(field).to_s.include?(value)
+          get(object, field).to_s.include?(value)
         end
       end
 
-      def column_names(scope)
+      def column_names(_scope)
         []
       end
 
-      def batch_each(scope, batch_size, &block)
+      def batch_each(scope, _batch_size, &block)
         scope.each(&block)
       end
 
@@ -79,9 +81,15 @@ module Datagrid
         asset
       end
 
-      def can_preload?(scope, association)
+      def can_preload?(_scope, _association)
         false
       end
+
+      protected
+
+      def get(object, property)
+        object.is_a?(Hash) ? object[property] : object.public_send(property)
+      end
     end
   end
 end