huginn_datatable 0.1.0

data/lib/huginn/datatable/validator.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Huginn
+  module Datatable
+    # Resolves and validates column references used by datatable filters,
+    # orders and ranges.
+    #
+    # A field is either a plain column ("status"), an association-scoped
+    # column ("pessoa.nome", "company.people.age") or — when the model
+    # declares `huginn_attributes` — a *public* API alias that maps to the
+    # real column.
+    #
+    # Fields are never interpolated into SQL strings: scoped fields are
+    # resolved through `AssociationPath` (direction aware FK/PK linking) and
+    # authorization is enforced against the `allowed_paths` allowlist. When
+    # the model configures `huginn_attributes(strict: true)` only the
+    # declared aliases are accepted, so the schema stays hidden from callers.
+    class Validator
+      FIELD_PATTERN = /\A[a-z_][a-z0-9_]*\z/
+
+      def self.call(model, field)
+        new(model, field)
+      end
+
+      def initialize(model, field)
+        @model = model
+        @strict_denied = false
+        @field = resolve_alias(field)
+        @field = @field.split(".").drop(1).join(".") if own_table_prefix?(@field)
+      end
+
+      def segments
+        @segments ||= @field.split(".")
+      end
+
+      def plain?
+        segments.size == 1
+      end
+
+      def scoped?
+        !plain? && segments.size >= 2
+      end
+
+      def valid?
+        return false if strict_denied?
+        return false unless segments.all? { |segment| segment.match?(FIELD_PATTERN) }
+
+        if plain?
+          model.columns_hash.key?(column)
+        else
+          association_path&.valid? && association_path.target_klass.columns_hash.key?(column)
+        end
+      end
+
+      # Canonical chain of association reflection names (e.g. ["company",
+      # "people"]) used to match the allowlist. Table names and public aliases
+      # are normalized through the reflection.
+      def authorization_path
+        return [] if plain?
+
+        association_path&.association_names || []
+      end
+
+      def arel_attribute
+        return nil unless valid?
+
+        plain? ? model.arel_table[column] : association_path.target_table[column]
+      end
+
+      def column_type
+        return nil unless valid?
+
+        klass = plain? ? model : association_path.target_klass
+        klass.columns_hash[column].type
+      end
+
+      # The AssociationPath for scoped fields (builds filter/order
+      # subqueries), or nil for plain columns.
+      def association_path
+        @association_path ||= (AssociationPath.call(model, @field) if scoped?)
+      end
+
+      # First association name of the chain (backwards compatible alias used
+      # by specs), or nil for plain columns.
+      def association_name
+        return nil if plain?
+
+        association_path&.association_names&.first&.to_sym
+      end
+
+      def correlated_order_expression
+        association_path&.correlated_order_expression
+      end
+
+      def allowlist_key
+        return nil if plain?
+
+        joined = authorization_path.join(".")
+        joined.empty? ? nil : joined
+      end
+
+      private
+
+      attr_reader :model
+
+      # "people.name" addressed via the model's own table_name is a plain
+      # column of the base relation (model.table_name is, actually, "people"
+      # for Person).
+      def own_table_prefix?(field)
+        segments = field.split(".")
+        segments.size >= 2 && segments.first == model.table_name
+      end
+
+      def strict_denied?
+        @strict_denied
+      end
+
+      def column
+        segments.last
+      end
+
+      def resolve_alias(field)
+        mapping = model.respond_to?(:huginn_attribute_mapping) ? model.huginn_attribute_mapping : nil
+        return field.to_s if mapping.blank?
+
+        key = field.to_s
+        return mapping[key] if mapping.key?(key)
+
+        @strict_denied = model.huginn_strict_mapping
+        key
+      end
+    end
+  end
+end

data/lib/huginn/datatable.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Huginn
+  module Datatable
+  end
+end
+
+require_relative "datatable/association_path"
+require_relative "datatable/allowed_paths"
+require_relative "datatable/validator"
+require_relative "datatable/filter_normalizer"
+require_relative "datatable/paginator"
+require_relative "datatable/datatable"

data/lib/huginn/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Huginn
+  class Railtie < Rails::Railtie
+    initializer "huginn.configure" do |app|
+      ActiveSupport.on_load(:active_record) do
+        include Huginn::Datatable if Huginn.configuration.auto_include_datatable?
+        include Huginn::Searchable if Huginn.configuration.auto_include_searchable?
+      end
+    end
+  end
+end

data/lib/huginn/searchable/fuzzy.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Huginn
+  module Searchable
+    # Builds an Arel predicate for a single searchable column.
+    #
+    # Strategy chain (driven by Huginn.configuration.search_strategy):
+    #
+    #   :pg_trgm   -> trigram similarity OR unaccent+ILIKE (best for typos)
+    #   :unaccent  -> unaccent + ILIKE (case/accents insensitive)
+    #   :simple    -> plain LIKE
+    module Fuzzy
+      # Gentle helpers to wrap a node in UNACCENT(...).
+      module Unaccentable
+        private
+
+        def unaccent(node)
+          Arel::Nodes::NamedFunction.new("UNACCENT", [node])
+        end
+      end
+
+      class Simple
+        def initialize(column, value)
+          @column = column
+          @value = value
+        end
+
+        def predicate
+          @column.matches("%#{escape_like(@value)}%")
+        end
+
+        private
+
+        def escape_like(value)
+          value.to_s.gsub(/[\\%_]/) { |char| "\\#{char}" }
+        end
+      end
+
+      class Unaccent
+        include Unaccentable
+
+        def initialize(column, value)
+          @column = column
+          @value = value
+        end
+
+        def predicate
+          Arel::Nodes::InfixOperation.new(
+            "ILIKE",
+            unaccent(@column),
+            unaccent(Arel::Nodes.build_quoted("%#{escape_like(@value)}%", @column))
+          )
+        end
+
+        private
+
+        def escape_like(value)
+          value.to_s.gsub(/[\\%_]/) { |char| "\\#{char}" }
+        end
+      end
+
+      class Trigram
+        include Unaccentable
+
+        def initialize(column, value, threshold)
+          @column = column
+          @value = value
+          @threshold = threshold
+        end
+
+        def predicate
+          similarity = Arel::Nodes::NamedFunction.new("similarity", [
+            unaccent(@column),
+            unaccent(Arel::Nodes.build_quoted(@value, @column))
+          ])
+          threshold = Arel::Nodes.build_quoted(@threshold)
+          Arel::Nodes::InfixOperation.new(">", similarity, threshold).or(fallback)
+        end
+
+        private
+
+        def fallback
+          Unaccent.new(@column, @value).predicate
+        end
+      end
+    end
+  end
+end

data/lib/huginn/searchable/query.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Huginn
+  module Searchable
+    # Builds a tolerant full-text search relation over a model's searchable
+    # columns, optionally crossing associations through left_joins.
+    #
+    # All matched columns are fused into a single Arel OR predicate, so the
+    # whole search stays one query regardless of how many columns (or
+    # associations) are involved.
+    class Query
+      def self.call(model, value, options = {})
+        new(model, value, options).call
+      end
+
+      def initialize(model, value, options = {})
+        @model = model
+        @value = value.to_s
+        @options = options
+        @distinct = options.fetch(:distinct, true)
+      end
+
+      def call
+        relation = @model.all
+        return apply_distinct(relation) if @value.strip.empty?
+
+        resolution = resolve_columns
+        return apply_distinct(relation) if resolution.fetch(:attrs).empty?
+
+        joins = resolution.fetch(:joins)
+        relation = relation.left_joins(*joins) if joins.any?
+
+        predicate = resolution.fetch(:attrs).map { |attr| fuzzy_predicate(attr) }.reduce(&:or)
+        apply_distinct(relation.where(predicate))
+      end
+
+      private
+
+      def resolve_columns
+        columns = @model.searchable_columns_config_resolved
+        joins = []
+        attrs = []
+
+        Array(columns[:columns]).map(&:to_s).reject(&:blank?).each do |field|
+          if field.include?(".")
+            name, col = field.split(".", 2)
+            push_association(joins, attrs, name, col)
+          else
+            attrs << @model.arel_table[field] if @model.columns_hash.key?(field)
+          end
+        end
+
+        columns[:associations].each do |name, cols|
+          Array(cols).each { |col| push_association(joins, attrs, name.to_s, col.to_s) }
+        end
+
+        { joins: joins.uniq, attrs: attrs }
+      end
+
+      def push_association(joins, attrs, name, col)
+        association = @model.reflect_on_association(name.to_sym)
+        return unless association
+
+        table = association.klass.arel_table
+        attrs << table[col] if association.klass.columns_hash.key?(col)
+        joins << name.to_sym unless joins.include?(name.to_sym)
+      end
+
+      def fuzzy_predicate(attr)
+        case strategy
+        when :pg_trgm
+          if pg_trgm_available?
+            Fuzzy::Trigram.new(attr, @value, Huginn.configuration.fuzzy_threshold).predicate
+          else
+            fallback_fuzzy(attr)
+          end
+        when :unaccent
+          Fuzzy::Unaccent.new(attr, @value).predicate
+        else
+          Fuzzy::Simple.new(attr, @value).predicate
+        end
+      end
+
+      # Even with :pg_trgm configured, degrade gracefully to accent/case
+      # insensitive matching when the extension is not installed.
+      def fallback_fuzzy(attr)
+        if unaccent_available?
+          Fuzzy::Unaccent.new(attr, @value).predicate
+        else
+          Fuzzy::Simple.new(attr, @value).predicate
+        end
+      end
+
+      def strategy
+        Huginn.configuration.search_strategy
+      end
+
+      def pg_trgm_available?
+        return false unless postgresql?
+        @pg_trgm_available ||= extension_installed?("pg_trgm")
+      end
+
+      def unaccent_available?
+        return false unless postgresql?
+        @unaccent_available ||= extension_installed?("unaccent")
+      end
+
+      def extension_installed?(name)
+        @model.connection
+              .select_all(sanitize_extension_query(name))
+              .any?
+      end
+
+      def sanitize_extension_query(name)
+        ActiveRecord::Base.sanitize_sql_array(
+          ["SELECT 1 AS one FROM pg_extension WHERE extname = ?", name]
+        )
+      end
+
+      def postgresql?
+        @model.connection.adapter_name.downcase.include?("postgres")
+      end
+
+      def apply_distinct(relation)
+        @distinct ? relation.distinct : relation
+      end
+    end
+  end
+end

data/lib/huginn/searchable/searchable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Huginn
+  module Searchable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :searchable_columns_config, default: nil
+    end
+
+    class_methods do
+      # Declares which columns (own or association-scoped) are searched.
+      #
+      #   searchable_columns :name, :document
+      #   searchable_columns :name, person: [:name, :email]
+      #   searchable_columns "person.name"
+      #
+      # When nothing is declared, every :string/:text column of the model is
+      # searched automatically. Columns may be association-scoped ("person.name")
+      # or declared via keyword arguments; scoped columns are reached through a
+      # left_join.
+      def searchable_columns(*columns, **associations)
+        self.searchable_columns_config = {
+          columns: columns.flatten.compact.map(&:to_s),
+          associations: associations
+        }
+        searchable_columns_config
+      end
+
+      # Tolerant full-text search (pg_trgm / unaccent / LIKE chain).
+      #
+      # @param value [String] the raw search term from the frontend
+      # @param options [Hash] :distinct (default true), :columns override
+      def search(value, options = {})
+        Searchable::Query.call(self, value, options)
+      end
+
+      def searchable_columns_config_resolved
+        config = searchable_columns_config || {}
+        {
+          columns: config[:columns].presence || default_searchable_columns,
+          associations: config[:associations] || {}
+        }
+      end
+
+      private
+
+      def default_searchable_columns
+        columns_hash.each_with_object([]) do |(name, column), acc|
+          acc << name if %i[string text].include?(column.type)
+        end
+      end
+    end
+  end
+end

data/lib/huginn/searchable.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Huginn
+  module Searchable
+  end
+end
+
+require_relative "searchable/fuzzy"
+require_relative "searchable/query"
+require_relative "searchable/searchable"

data/lib/huginn/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Huginn
+  VERSION = "0.1.0"
+end

data/lib/huginn.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/concern"
+require "active_support/notifications"
+require "active_record"
+
+require "logger"
+
+module Huginn
+  NAMESPACE = "huginn"
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def instrument(event, payload = {})
+      ActiveSupport::Notifications.instrument("#{event}.#{NAMESPACE}", payload) do
+        yield if block_given?
+      end
+    end
+
+    def logger
+      @logger ||= if defined?(Rails) && Rails.respond_to?(:logger)
+                    Rails.logger
+                  else
+                    ::Logger.new($stdout)
+                  end
+    end
+  end
+end
+
+require_relative "huginn/version"
+require_relative "huginn/configuration"
+require_relative "huginn/datatable"
+require_relative "huginn/searchable"
+require_relative "huginn/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,182 @@
+--- !ruby/object:Gem::Specification
+name: huginn_datatable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kayky Marcelo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: pagy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Huginn is the raven of Odin that represents thought and remembrance.
+  It offers a lightweight, highly performant query layer for ActiveRecord datatables:
+  filtered/ordered eager-loaded pagination with an enxuto count and a PostgreSQL fuzzy-search
+  builder (pg_trgm, unaccent, ILIKE).'
+email:
+- kaykymarcelo2411@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- README.pt-BR.md
+- lib/huginn.rb
+- lib/huginn/configuration.rb
+- lib/huginn/datatable.rb
+- lib/huginn/datatable/allowed_paths.rb
+- lib/huginn/datatable/association_path.rb
+- lib/huginn/datatable/datatable.rb
+- lib/huginn/datatable/filter_normalizer.rb
+- lib/huginn/datatable/paginator.rb
+- lib/huginn/datatable/validator.rb
+- lib/huginn/railtie.rb
+- lib/huginn/searchable.rb
+- lib/huginn/searchable/fuzzy.rb
+- lib/huginn/searchable/query.rb
+- lib/huginn/searchable/searchable.rb
+- lib/huginn/version.rb
+- logo.png
+homepage: https://github.com/KaykyM2411/huginn
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/KaykyM2411/huginn
+  source_code_uri: https://github.com/KaykyM2411/huginn
+  changelog_uri: https://github.com/KaykyM2411/huginn/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Performant and elegant ActiveRecord datatables/data-grids with tolerant search
+test_files: []