prato 0.1.0

data/lib/prato/configuration.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Prato
+  class Configuration
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield(config) if block_given?
+        config
+      end
+
+      def with_settings(
+        base = nil,
+        key_transformation: nil,
+        on_invalid_input: nil,
+        parameter_parser: nil,
+        default_page_size: nil,
+        maximum_page_size: nil,
+        default_queryable: nil,
+        default_ruby_column_queryable: nil
+      )
+        copy = (base || config).dup
+        copy.key_transformation = key_transformation if key_transformation
+        copy.on_invalid_input = on_invalid_input if on_invalid_input
+        copy.parameter_parser = parameter_parser if parameter_parser
+        copy.default_page_size = default_page_size if default_page_size
+        copy.maximum_page_size = maximum_page_size if maximum_page_size
+        copy.default_queryable = default_queryable if default_queryable
+        copy.default_ruby_column_queryable = default_ruby_column_queryable if default_ruby_column_queryable
+        copy
+      end
+    end
+
+    attr_accessor :default_page_size,
+                  :maximum_page_size
+
+    attr_reader :key_transformation,
+                :on_invalid_input,
+                :parameter_parser,
+                :default_queryable,
+                :default_ruby_column_queryable
+
+    def initialize
+      @key_transformation = :camelCase
+      @on_invalid_input = :empty
+      @parameter_parser = Prato::Query::DefaultParser.new
+      @default_page_size = 20
+      @maximum_page_size = 100
+      @default_queryable = :all
+      @default_ruby_column_queryable = :none
+    end
+
+    KEY_TRANSFORMATION_OPTIONS = [:camelCase, :snake_case, :none].freeze
+    def key_transformation=(value)
+      raise ArgumentError unless KEY_TRANSFORMATION_OPTIONS.include?(value)
+
+      @key_transformation = value
+    end
+
+    INVALID_INPUT_OPTIONS = [:empty, :raise].freeze
+    def on_invalid_input=(value)
+      raise ArgumentError unless INVALID_INPUT_OPTIONS.include?(value)
+
+      @on_invalid_input = value
+    end
+
+    def parameter_parser=(parser)
+      unless parser.respond_to?(:parse_parameters)
+        raise ArgumentError,
+              "parameter_parser must respond to .parse_parameters. Got #{parser.inspect}"
+      end
+
+      @parameter_parser = parser
+    end
+
+    VALID_QUERYABLE = [:all, :none, :filter, :sort].freeze
+
+    def default_queryable=(value)
+      @default_queryable = validate_queryable!(value, option_name: "default_queryable")
+    end
+
+    def default_ruby_column_queryable=(value)
+      @default_ruby_column_queryable = validate_queryable!(value, option_name: "default_ruby_column_queryable")
+    end
+
+    private
+
+    def validate_queryable!(value, option_name: "queryable")
+      unless VALID_QUERYABLE.include?(value)
+        raise ArgumentError, "#{option_name} must be one of #{VALID_QUERYABLE.map(&:inspect).join(", ")}"
+      end
+
+      value
+    end
+  end
+end

data/lib/prato/internal/active_record_version.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+require "active_record/version"
+module Prato
+  module Internal
+    module ActiveRecordVersion
+      extend self
+
+      LEGACY_CUTOFF = Gem::Version.new("5.2").freeze
+      MINIMUM_AREL_DESC_VERSION = Gem::Version.new("6.0").freeze
+
+      def version
+        @version ||= Gem::Version.new(ActiveRecord::VERSION::STRING)
+      end
+
+      def legacy?
+        version < LEGACY_CUTOFF
+      end
+
+      def supports_arel_desc?
+        version >= MINIMUM_AREL_DESC_VERSION
+      end
+    end
+  end
+end

data/lib/prato/internal/join_helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Prato
+  module Internal
+    module JoinHelper
+      extend self
+
+      def ensure_join(scope, column, left_outer: false)
+        return scope unless column.is_a?(Types::AssociationColumn)
+
+        join_hash = join_hash_for(column.association_path)
+        left_outer ? scope.left_joins(join_hash) : scope.joins(join_hash)
+      end
+
+      def ensure_left_joins(scope, association_paths)
+        return scope if association_paths.empty?
+
+        scope.left_joins(*join_hashes_for(association_paths))
+      end
+
+      private
+
+      def join_hash_for(path)
+        return path.first if path.length == 1
+
+        path.reverse.reduce { |inner, outer| { outer => inner } }
+      end
+
+      def join_hashes_for(paths)
+        result = {}
+
+        paths.each do |path|
+          current = result
+          path.each do |assoc|
+            current[assoc] ||= {}
+            current = current[assoc]
+          end
+        end
+
+        simplify_join_hash(result)
+      end
+
+      def simplify_join_hash(hash)
+        hash.map { |key, value| value.empty? ? key : { key => simplify_join_hash(value) } }
+      end
+    end
+  end
+end

data/lib/prato/internal/join_helper_legacy.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+# Rails 5.0 and 5.1ºs joins work in a different way, so we need to handle them...manually
+module Prato
+  module Internal
+    module JoinHelper
+      extend self
+
+      def ensure_join(scope, column, left_outer: false)
+        return scope unless column.is_a?(Types::AssociationColumn)
+
+        join_hash = join_hash_for(column.association_path)
+        left_outer ? scope.left_joins(join_hash) : scope.joins(join_hash)
+      end
+
+      def ensure_left_joins(scope, association_paths)
+        return scope if association_paths.empty?
+
+        scope = freeze_existing_joins(scope)
+
+        association_paths.uniq.sort_by(&:length).each do |path|
+          next if join_path_resolved?(scope, path)
+
+          prefix_length = deepest_joined_prefix_length(scope, path)
+          next if prefix_length == path.length
+
+          parent_path = path[0...prefix_length]
+          parent_table = parent_path.empty? ? scope.model.arel_table : SqlSupport.table_for(scope, parent_path)
+          parent_model = model_for_path(scope.model, parent_path)
+          suffix = path[prefix_length..-1]
+
+          scope = append_left_join_suffix(scope, parent_table, parent_model, suffix)
+        end
+
+        scope
+      end
+
+      private
+
+      # Freeze pre-existing association joins into concrete join nodes before
+      # adding suffix joins so Rails 5 cannot rename earlier aliases.
+      def freeze_existing_joins(scope)
+        frozen_scope = scope.spawn
+        frozen_scope.joins_values = scope.arel.join_sources.dup
+        frozen_scope.left_outer_joins_values = []
+        frozen_scope.bind_values = scope.arel.bind_values.dup
+        frozen_scope
+      end
+
+      def append_left_join_suffix(scope, parent_table, parent_model, suffix)
+        node = build_join_node(parent_model, suffix)
+        alias_tracker = build_alias_tracker(scope)
+
+        assign_tables!(node, parent_table, alias_tracker)
+
+        collect_join_infos(node, parent_table, parent_model).each do |info|
+          scope = scope.joins(*info.joins)
+          scope.bind_values += info.binds
+        end
+
+        scope
+      end
+
+      def join_path_resolved?(scope, path)
+        SqlSupport.table_for(scope, path)
+        true
+      rescue ArgumentError
+        false
+      end
+
+      def deepest_joined_prefix_length(scope, path)
+        path.length.downto(0).find { |length| join_path_resolved?(scope, path[0...length]) } || 0
+      end
+
+      def model_for_path(base_model, path)
+        path.reduce(base_model) do |model, assoc_name|
+          reflection = model.reflect_on_association(assoc_name)
+          raise ArgumentError, "Unknown association '#{assoc_name}' on #{model}" unless reflection
+
+          reflection.klass
+        end
+      end
+
+      def build_join_node(model, path)
+        reflection = model.reflect_on_association(path.first)
+        raise ArgumentError, "Unknown association '#{path.first}' on #{model}" unless reflection
+
+        children = path.length > 1 ? [build_join_node(reflection.klass, path[1..-1])] : []
+        ActiveRecord::Associations::JoinDependency::JoinAssociation.new(reflection, children)
+      end
+
+      def assign_tables!(node, parent_table, alias_tracker)
+        node.tables = node.reflection.chain.map do |reflection|
+          aliased_table_for(
+            alias_tracker,
+            reflection,
+            table_alias_name(reflection, parent_table.table_name, reflection != node.reflection)
+          )
+        end
+
+        node.children.each { |child| assign_tables!(child, node.table, alias_tracker) }
+      end
+
+      def build_alias_tracker(scope)
+        method = ActiveRecord::Associations::AliasTracker.method(:create_with_joins)
+
+        if method.parameters.length == 3
+          method.call(scope.model.connection, scope.model.table_name, scope.joins_values)
+        else
+          method.call(scope.model.connection, scope.model.table_name, scope.joins_values, scope.model.type_caster)
+        end
+      end
+
+      def aliased_table_for(alias_tracker, reflection, aliased_name)
+        method = alias_tracker.method(:aliased_table_for)
+
+        if method.parameters.length == 3
+          method.call(reflection.table_name, aliased_name, reflection.klass.type_caster)
+        else
+          method.call(reflection.table_name, aliased_name)
+        end
+      end
+
+      def collect_join_infos(node, parent_table, parent_model)
+        infos = [build_join_info(node, parent_table, parent_model)]
+
+        node.children.each do |child|
+          infos.concat(collect_join_infos(child, node.table, node.base_klass))
+        end
+
+        infos
+      end
+
+      def build_join_info(node, parent_table, parent_model)
+        method = node.method(:join_constraints)
+
+        if method.parameters.length == 5
+          method.call(
+            parent_table,
+            parent_model,
+            Arel::Nodes::OuterJoin,
+            node.tables,
+            node.reflection.chain
+          )
+        else
+          method.call(
+            parent_table,
+            parent_model,
+            node,
+            Arel::Nodes::OuterJoin,
+            node.tables,
+            node.reflection.scope_chain,
+            node.reflection.chain
+          )
+        end
+      end
+
+      def table_alias_name(reflection, parent_table_name, join)
+        name = "#{reflection.plural_name}_#{parent_table_name}"
+        name << "_join" if join
+        name
+      end
+
+      def join_hash_for(path)
+        return path.first if path.length == 1
+
+        path.reverse.reduce { |inner, outer| { outer => inner } }
+      end
+    end
+  end
+end

data/lib/prato/internal/lazy_loader_cache.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Prato
+  module Internal
+    class LazyLoaderCache < Hash
+      def initialize(records)
+        super(records)
+
+        @records = records
+      end
+
+      def [](key)
+        value = super
+
+        if value.is_a?(Proc)
+          result = value.call(@records, self)
+          self[key] = result # memoize the result
+          result
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/prato/internal/pipeline/filtering.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module Prato
+  module Internal
+    module Pipeline
+      module Filtering
+        extend self
+
+        def filter_query(query_state, spec, raw_filters)
+          return query_state if raw_filters.nil?
+
+          sql_filters, ruby_filters = classify_filters(spec, Array(raw_filters))
+
+          filtered_query_1 = apply_sql_filters(query_state, spec, sql_filters)
+          filtered_query_2 = apply_ruby_filters(filtered_query_1, spec, ruby_filters)
+
+          filtered_query_2
+        end
+
+        private
+
+        def classify_filters(spec, filters)
+          flatten_ands(filters).partition { |f| all_sql?(spec, f) }
+        end
+
+        def flatten_ands(filters)
+          filters.flat_map do |f|
+            case f
+            when Query::AndFilter then flatten_ands(f.filters)
+            else [f]
+            end
+          end
+        end
+
+        def all_sql?(spec, filter)
+          case filter
+          when Query::Filter
+            !spec.columns[filter.field].is_a?(Types::RubyColumn)
+          when Query::AndFilter, Query::OrFilter
+            filter.filters.all? { |f| all_sql?(spec, f) }
+          end
+        end
+
+        def apply_sql_filters(query_state, spec, filters)
+          filters.reduce(query_state) do |qs, filter|
+            normalized = normalize_sql_filter_tree(spec, filter)
+            apply_sql_filter(qs, spec, normalized)
+          end
+        end
+
+        # We normalize some SQL filters so that the SQL statements are simpler
+        def normalize_sql_filter_tree(spec, filter)
+          case filter
+          when Query::Filter
+            normalize_sql_leaf_filter(spec, filter)
+          when Query::AndFilter
+            Query::AndFilter.new(filter.filters.map { |f| normalize_sql_filter_tree(spec, f) })
+          when Query::OrFilter
+            Query::OrFilter.new(filter.filters.map { |f| normalize_sql_filter_tree(spec, f) })
+          end
+        end
+
+        NIL_ARRAY = [nil].freeze
+        NEGATIVE_ASSC_OPS = %i[not_eq not_in not_contains not_icontains].freeze
+        def normalize_sql_leaf_filter(spec, filter)
+          operator = filter.operator
+          value = filter.value
+
+          # Rule 1: nil values → presence operators
+          if operator == :eq && value.nil?
+            return Query::Filter.new(filter.field, :not_present, nil)
+          end
+          if operator == :not_eq && value.nil?
+            return Query::Filter.new(filter.field, :present, nil)
+          end
+
+          if operator == :in && value == [nil]
+            return Query::Filter.new(filter.field, :not_present, nil)
+          end
+
+          if operator == :not_in && value == [nil]
+            return Query::Filter.new(filter.field, :present, nil)
+          end
+
+          # Rule 2: negative operators on association columns (non-nil values) → OrFilter with not_present
+          if NEGATIVE_ASSC_OPS.include?(operator) && !value.nil? && spec.columns[filter.field].is_a?(Types::AssociationColumn)
+            return Query::OrFilter.new([
+              filter,
+              Query::Filter.new(filter.field, :not_present, nil)
+            ])
+          end
+
+          filter
+        end
+
+        def apply_sql_filter(query_state, spec, filter)
+          case filter
+          when Query::Filter
+            column = spec.columns[filter.field]
+            scope = ensure_joins(query_state.dataset, column, filter.operator)
+
+            if custom_filter?(column)
+              result = column.filter.call(scope, filter.operator, filter.value)
+              return query_state.with_dataset(result) unless result.nil?
+            end
+
+            condition = build_operator_condition(column.sql_node_for(scope), filter.operator, filter.value)
+            query_state.with_dataset(scope.where(condition))
+          when Query::AndFilter
+            filter.filters.reduce(query_state) { |qs, child| apply_sql_filter(qs, spec, child) }
+          when Query::OrFilter
+            scope = ensure_left_joins_for_filters(query_state.dataset, spec, filter.filters)
+            condition = build_sql_condition(scope, spec, filter)
+            query_state.with_dataset(scope.where(condition))
+          end
+        end
+
+        def build_sql_condition(scope, spec, filter)
+          case filter
+          when Query::Filter
+            column = spec.columns[filter.field]
+
+            if custom_filter?(column)
+              result = column.filter.call(scope, filter.operator, filter.value)
+              return result.where_clause.ast unless result.nil?
+            end
+
+            build_operator_condition(column.sql_node_for(scope), filter.operator, filter.value)
+          when Query::AndFilter
+            filter.filters.map { |child| build_sql_condition(scope, spec, child) }
+                          .reduce { |a, b| a.and(b) }
+          when Query::OrFilter
+            filter.filters.map { |child| build_sql_condition(scope, spec, child) }
+                          .reduce { |a, b| a.or(b) }
+          end
+        end
+
+        def build_operator_condition(arel_node, operator, value)
+          case operator
+          when :eq          then arel_node.eq(value)
+          when :not_eq      then arel_node.not_eq(value)
+          when :lt          then arel_node.lt(value)
+          when :lte         then arel_node.lteq(value)
+          when :gt          then arel_node.gt(value)
+          when :gte         then arel_node.gteq(value)
+          when :present     then arel_node.not_eq(nil)
+          when :not_present then arel_node.eq(nil)
+          when :in          then arel_node.in(Array(value))
+          when :not_in      then arel_node.not_in(Array(value))
+          when :contains      then arel_node.matches(like_pattern(value))
+          when :not_contains  then arel_node.does_not_match(like_pattern(value))
+          when :icontains     then arel_node.matches(like_pattern(value), nil, false)
+          when :not_icontains then arel_node.does_not_match(like_pattern(value), nil, false)
+          when :between                 then arel_node.gteq(value[0]).and(arel_node.lteq(value[1]))
+          when :not_between             then arel_node.lt(value[0]).or(arel_node.gt(value[1]))
+          when :between_exclusive       then arel_node.gt(value[0]).and(arel_node.lt(value[1]))
+          when :not_between_exclusive   then arel_node.lteq(value[0]).or(arel_node.gteq(value[1]))
+          else
+            raise ArgumentError, "Unknown filter operator: #{operator.inspect}"
+          end
+        end
+
+        def ensure_joins(scope, column, operator)
+          Internal::JoinHelper.ensure_join(scope, column, left_outer: operator == :not_present)
+        end
+
+        def ensure_left_joins_for_filters(scope, spec, filters)
+          filters.each do |filter|
+            case filter
+            when Query::Filter
+              column = spec.columns[filter.field]
+              scope = Internal::JoinHelper.ensure_join(scope, column, left_outer: true)
+            when Query::AndFilter, Query::OrFilter
+              scope = ensure_left_joins_for_filters(scope, spec, filter.filters)
+            end
+          end
+          scope
+        end
+
+        ###################################################################
+        # RUBY FILTERS
+        ###################################################################
+
+        def apply_ruby_filters(query_state, spec, filters)
+          return query_state if filters.empty?
+
+          records, ruby_data = query_state.materialized_dataset(spec)
+
+          filtered = records.select do |record|
+            filters.all? { |f| evaluate_ruby_filter(record, ruby_data, spec, f) }
+          end
+
+          query_state.with_dataset(filtered)
+        end
+
+        def evaluate_ruby_filter(record, ruby_data, spec, filter)
+          case filter
+          when Query::Filter
+            column = spec.columns[filter.field]
+            actual = column.extract_value(record, ruby_data)
+
+            if custom_filter?(column)
+              result = column.filter.call(actual, filter.operator, filter.value)
+              return result unless result.nil?
+            end
+
+            compare_value(actual, filter.operator, filter.value)
+          when Query::AndFilter
+            filter.filters.all? { |child| evaluate_ruby_filter(record, ruby_data, spec, child) }
+          when Query::OrFilter
+            filter.filters.any? { |child| evaluate_ruby_filter(record, ruby_data, spec, child) }
+          end
+        end
+
+        def compare_value(actual, operator, expected)
+          case operator
+          when :eq            then actual == expected
+          when :not_eq        then actual != expected
+          when :lt            then !actual.nil? && actual < expected
+          when :lte           then !actual.nil? && actual <= expected
+          when :gt            then !actual.nil? && actual > expected
+          when :gte           then !actual.nil? && actual >= expected
+          when :present       then !actual.nil?
+          when :not_present   then actual.nil?
+          when :in            then Array(expected).include?(actual)
+          when :not_in        then !Array(expected).include?(actual)
+          when :contains      then actual.to_s.include?(expected.to_s)
+          when :not_contains  then !actual.to_s.include?(expected.to_s)
+          when :icontains     then icontains_match?(actual, expected)
+          when :not_icontains then !icontains_match?(actual, expected)
+          when :between       then !actual.nil? && actual >= expected[0] && actual <= expected[1]
+          when :not_between   then !actual.nil? && (actual < expected[0] || actual > expected[1])
+          when :between_exclusive     then !actual.nil? && actual > expected[0] && actual < expected[1]
+          when :not_between_exclusive then !actual.nil? && (actual <= expected[0] || actual >= expected[1])
+          else
+            raise ArgumentError, "Unknown filter operator: #{operator.inspect}"
+          end
+        end
+
+        def filter_fields(filters)
+          filters.flat_map do |filter|
+            case filter
+            when Query::Filter
+              [filter.field]
+            when Query::AndFilter, Query::OrFilter
+              filter_fields(filter.filters)
+            else
+              []
+            end
+          end
+        end
+
+        def custom_filter?(column)
+          column.filter.is_a?(Proc)
+        end
+
+        if ActiveRecordVersion.legacy?
+          def sanitize_like(value)
+            ActiveRecord::Base.send(:sanitize_sql_like, value.to_s)
+          end
+        else
+          def sanitize_like(value)
+            ActiveRecord::Base.sanitize_sql_like(value.to_s)
+          end
+        end
+
+        def like_pattern(value)
+          "%#{sanitize_like(value)}%"
+        end
+
+        def icontains_match?(actual, expected)
+          actual.to_s.downcase.include?(expected.to_s.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/prato/internal/pipeline/pagination.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Prato
+  module Internal
+    module Pipeline
+      module Pagination
+        extend self
+
+        def paginate_query(query_state, config, raw_page, raw_per_page)
+          page = raw_page || 1
+          per_page = raw_per_page || config.default_page_size
+          if per_page > config.maximum_page_size
+            per_page = config.maximum_page_size
+          end
+
+          dataset = query_state.dataset
+          offset = (page - 1) * per_page
+
+          paginated_dataset = if query_state.unmaterialized?
+                                dataset.offset(offset).limit(per_page)
+                              else
+                                dataset.slice(offset, per_page) || []
+                              end
+
+          query_state.with_dataset(paginated_dataset)
+        end
+      end
+    end
+  end
+end