prato 0.1.0

data/lib/prato/internal/specification_builder.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+module Prato
+  module Internal
+    class SpecificationBuilder
+      attr_reader :draft_columns, :ruby_loaders
+
+      def initialize
+        @config = Prato::Configuration.config
+        @draft_columns = []
+        @ruby_loaders = nil
+      end
+
+      AGGREGATE_FUNCTIONS = [:count, :sum, :avg, :min, :max].freeze
+      COMMON_RESERVED_KEYWORDS = [:queryable].freeze
+      RESERVED_COLUMN_SYMBOLS = ([:format, :expression, :filter] + COMMON_RESERVED_KEYWORDS + AGGREGATE_FUNCTIONS).freeze
+      RESERVED_RUBY_COLUMN_SYMBOLS = ([:key, :filter, :includes] + COMMON_RESERVED_KEYWORDS).freeze
+
+      def inner_column(*args, **kwargs)
+        draft = build_draft(args, kwargs)
+        @draft_columns << draft
+      end
+
+      def inner_query_column(*args, **kwargs)
+        draft = build_draft(args, kwargs, query_only: true)
+        @draft_columns << draft
+      end
+
+      def inner_ruby_column(*args, **kwargs, &block)
+        name_map, options = extract_name_and_options(args, kwargs, RESERVED_RUBY_COLUMN_SYMBOLS)
+        display_name, loader_id = parse_name_map(name_map)
+
+        key = parse_accessor(options[:key])
+        queryable = resolve_queryable_option!(options, VALID_COLUMN_QUERYABLE)
+        validate_filter_option!(options[:filter])
+        column = ::Prato::Types::RubyColumn.new(loader_id, key: key, filter: options[:filter], includes: options[:includes])
+
+        @draft_columns << DraftColumn.new(display_name, loader_id, column, queryable: queryable)
+        inner_ruby_loader(loader_id, &block) if block_given?
+      end
+
+      def inner_section(id, &block)
+        section = SectionBuilder.new
+
+        raise ArgumentError, "No block given to section" unless block_given?
+
+        section.instance_exec(&block)
+
+        section.spec.draft_columns.each do |nested_draft|
+          new_output_path = [id] + nested_draft.output_paths
+
+          draft = DraftColumn.new(
+            nested_draft.override_name,
+            nested_draft.accessor_name,
+            nested_draft.column,
+            queryable: nested_draft.queryable,
+            query_only: nested_draft.query_only,
+            output_paths: new_output_path
+          )
+
+          @draft_columns << draft
+        end
+        return if section.spec.ruby_loaders.nil?
+
+        @ruby_loaders ||= {}
+        @ruby_loaders.merge!(section.spec.ruby_loaders)
+      end
+
+      def inner_ruby_loader(id, includes: nil, &block)
+        @ruby_loaders ||= {}
+        @ruby_loaders[id] = {
+          block: block,
+          includes: includes
+        }
+      end
+
+      def inner_config(config)
+        @config = config
+      end
+
+      def build(base_model)
+        columns = {}
+        visible_fields = []
+        filterable_fields = Set.new
+        sortable_fields = Set.new
+        output_paths = {}
+        field_lookup = {}
+
+        @draft_columns.each do |draft|
+          column_output_path = draft.output_paths.map do |path|
+            transform_key_part(path, @config.key_transformation)
+          end
+          internal_column_name = Query::FieldResolver.join(draft.output_paths)
+
+          if columns.key?(internal_column_name)
+            raise ArgumentError,
+                  "Column '#{draft.name}' (internal id: #{internal_column_name}) has already been defined."
+          end
+
+          column = draft.column
+
+          if column.is_a?(Types::DirectColumn) ||
+             column.is_a?(Types::AssociationColumn) ||
+             column.is_a?(Types::ExpressionColumn) ||
+             column.is_a?(Types::AggregateColumn)
+            column.resolve_arel!(base_model, internal_column_name)
+          end
+
+          filterable = resolve_capability(:filter, draft)
+          sortable = resolve_capability(:sort, draft)
+
+          columns[internal_column_name] = column
+          visible_fields << internal_column_name unless draft.query_only
+          filterable_fields << internal_column_name if filterable
+          sortable_fields << internal_column_name if sortable
+          output_paths[internal_column_name] = column_output_path.map(&:to_sym)
+          field_lookup[column_output_path.map(&:to_s)] = internal_column_name
+        end
+
+        Specification.new(
+          columns: columns,
+          visible_fields: visible_fields,
+          filterable_fields: filterable_fields,
+          sortable_fields: sortable_fields,
+          output_paths: output_paths,
+          field_lookup: field_lookup,
+          ruby_loaders: @ruby_loaders,
+          config: @config
+        )
+      end
+
+      private
+
+      def resolve_capability(capability, draft)
+        return true if capability == :filter && !draft.column.filter.nil?
+
+        queryable = resolve_queryable(draft)
+
+        queryable == :all || queryable == capability
+      end
+
+      def resolve_queryable(draft)
+        return draft.queryable if draft.queryable
+        return :all if draft.query_only
+
+        if draft.column.is_a?(Types::RubyColumn)
+          @config.default_ruby_column_queryable
+        else
+          @config.default_queryable
+        end
+      end
+
+      def validate_ruby_loader!(draft, loaders)
+        column = draft.column
+        return unless column.is_a?(Prato::Types::RubyColumn)
+
+        loader_name = column.loader
+
+        raise ArgumentError, "Ruby column '#{draft.name || column.key}' is missing a loader." if loader_name.nil?
+        raise ArgumentError, "No ruby loader registered for '#{loader_name}'." if loaders.nil?
+
+        loader = loaders[loader_name]
+        raise ArgumentError, "No ruby loader registered for '#{loader_name}'." unless loaders.key?(loader_name)
+        return if loader.is_a?(Hash) && loader[:block].respond_to?(:call)
+
+        raise ArgumentError, "Ruby loader '#{loader_name}' must respond to #call."
+      end
+
+      VALID_COLUMN_QUERYABLE = [:all, :none, :filter, :sort].freeze
+      VALID_QUERY_COLUMN_QUERYABLE = [:all, :filter, :sort].freeze
+
+      def build_draft(args, kwargs, query_only: false)
+        queryable_options = {}
+        queryable_options[:queryable] = kwargs.delete(:queryable) if kwargs.key?(:queryable)
+        queryable = resolve_queryable_option!(queryable_options,
+                                              query_only ? VALID_QUERY_COLUMN_QUERYABLE : VALID_COLUMN_QUERYABLE)
+
+        name_map, options = extract_name_and_options(args, kwargs, RESERVED_COLUMN_SYMBOLS)
+        aggregate_function, aggregate_accessor = extract_aggregate(options)
+        override_name, accessor = parse_name_map(name_map)
+        accessor = parse_accessor(accessor)
+        validate_filter_option!(options[:filter])
+
+        if aggregate_function
+          column = ::Prato::Types::AggregateColumn.new(aggregate_function, aggregate_accessor,
+                                                       format: options[:format], filter: options[:filter])
+          DraftColumn.new(accessor, nil, column, queryable: queryable, query_only: query_only)
+        elsif options[:expression]
+          column = ::Prato::Types::ExpressionColumn.new(options[:expression], format: options[:format], filter: options[:filter])
+          DraftColumn.new(override_name, accessor, column, queryable: queryable, query_only: query_only)
+        elsif accessor.is_a?(Array) && accessor.length > 1
+          column = ::Prato::Types::AssociationColumn.new(accessor, format: options[:format], filter: options[:filter])
+          DraftColumn.new(override_name, accessor, column, queryable: queryable, query_only: query_only)
+        else
+          column = ::Prato::Types::DirectColumn.new(accessor, format: options[:format], filter: options[:filter])
+          DraftColumn.new(override_name, accessor, column, queryable: queryable, query_only: query_only)
+        end
+      end
+
+      def validate_filter_option!(filter)
+        return if filter.nil? || filter.is_a?(Proc)
+        return if filter.is_a?(Array) && filter.all? { |operator| operator.is_a?(Symbol) }
+
+        raise ArgumentError, "filter must be nil, an Array of symbols, or a Proc"
+      end
+
+      def resolve_queryable_option!(options, valid)
+        return nil unless options.key?(:queryable)
+
+        queryable = options[:queryable]
+        raise ArgumentError, "queryable: must be a Symbol, got #{queryable.class}" unless queryable.is_a?(Symbol)
+
+        unless valid.include?(queryable)
+          raise ArgumentError, "queryable: must be one of #{valid.map(&:inspect).join(", ")}, got #{queryable.inspect}"
+        end
+
+        queryable
+      end
+
+      def extract_name_and_options(args, kwargs, reserved)
+        if args.any?
+          [args, kwargs]
+        else
+          option_keys = kwargs.keys & reserved
+          options = kwargs.slice(*option_keys)
+          name_map = kwargs.except(*reserved)
+          [name_map, options]
+        end
+      end
+
+      def extract_aggregate(kwargs)
+        AGGREGATE_FUNCTIONS.each do |func|
+          value = kwargs.delete(func)
+          return [func, value] if value
+        end
+        nil
+      end
+
+      def parse_name_map(name_map)
+        case name_map
+        when Symbol
+          [nil, name_map]
+        when Array
+          if name_map.size == 1 && name_map.first.is_a?(Hash)
+            parse_name_map(name_map.first)
+          elsif name_map.size == 2
+            [name_map.first, name_map.second]
+          else
+            [nil, name_map.first]
+          end
+        when Hash
+          entry = name_map.first
+          [entry.first, entry.second]
+        else
+          raise ArgumentError, "name_map must be a Symbol or Array"
+        end
+      end
+
+      def parse_accessor(value)
+        case value
+        when Symbol
+          value
+        when Hash
+          flatten_hash_to_array(value)
+        else
+          value
+        end
+      end
+
+      def flatten_hash_to_array(hash)
+        return [] if hash.empty?
+
+        key, value = hash.first
+        case value
+        when Symbol
+          [key, value]
+        when Hash
+          [key] + flatten_hash_to_array(value)
+        else
+          [key]
+        end
+      end
+
+      def transform_key_part(part, transformation)
+        return part if part.is_a?(String)
+
+        case transformation
+        when :camelCase then to_camel_case(part)
+        when :snake_case then to_snake_case(part)
+        when :none then part
+        end
+      end
+
+      def to_snake_case(value)
+        s = value.to_s.dup
+        s.gsub!(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        s.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+        s.tr!("-", "_")
+        s.tr!(" ", "_")
+        s.downcase!
+        s
+      end
+
+      def to_camel_case(value)
+        parts = to_snake_case(value).split("_")
+        parts.first + parts.drop(1).map(&:capitalize).join
+      end
+
+      private_constant :RESERVED_COLUMN_SYMBOLS
+      private_constant :RESERVED_RUBY_COLUMN_SYMBOLS
+      private_constant :COMMON_RESERVED_KEYWORDS
+      private_constant :AGGREGATE_FUNCTIONS
+      private_constant :VALID_COLUMN_QUERYABLE
+      private_constant :VALID_QUERY_COLUMN_QUERYABLE
+    end
+
+    class DraftColumn
+      attr_reader :override_name, :accessor_name, :column, :queryable, :query_only, :output_paths
+
+      def initialize(override_name, accessor_name, column, queryable: nil, query_only: false,
+                     output_paths: [])
+        @override_name = override_name
+        @accessor_name = accessor_name
+        @column = column
+        @queryable = queryable
+        @query_only = query_only
+        @output_paths = output_paths.empty? ? [name] : output_paths
+      end
+
+      def name
+        @override_name || @accessor_name
+      end
+    end
+
+    class SectionBuilder
+      attr_reader :spec
+
+      def initialize
+        @spec = SpecificationBuilder.new
+      end
+
+      def column(*args, **kwargs)
+        @spec.inner_column(*args, **kwargs)
+        self
+      end
+
+      def ruby_column(*args, **kwargs, &block)
+        @spec.inner_ruby_column(*args, **kwargs, &block)
+        self
+      end
+
+      def section(id, &block)
+        @spec.inner_section(id, &block)
+        self
+      end
+    end
+
+    private_constant :DraftColumn
+    private_constant :SectionBuilder
+  end
+end

data/lib/prato/internal/sql_support.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Prato
+  module Internal
+    module SqlSupport
+      extend self
+
+      def table_for(scope, association_path)
+        return scope.model.arel_table if association_path.empty?
+
+        expanded = expand_through_associations(scope.model, association_path)
+        join_sources = scope.arel.join_sources
+
+        table = walk_join_path(scope.model, scope.model.arel_table, expanded, join_sources)
+
+        unless table
+          raise ArgumentError,
+                "Unable to resolve table alias for association path #{association_path.inspect}"
+        end
+
+        table
+      end
+
+      private
+
+      def expand_through_associations(model, path)
+        expanded = []
+        current_model = model
+
+        path.each do |assoc_name|
+          reflection = current_model.reflect_on_association(assoc_name)
+          raise ArgumentError, "Unknown association '#{assoc_name}' on #{current_model}" unless reflection
+
+          expand_reflection(reflection, expanded)
+          current_model = reflection.klass
+        end
+
+        expanded
+      end
+
+      def expand_reflection(reflection, result)
+        if reflection.through_reflection?
+          expand_reflection(reflection.through_reflection, result)
+          expand_reflection(reflection.source_reflection, result)
+        else
+          result << reflection.name
+        end
+      end
+
+      def walk_join_path(model, parent_table, path, join_sources)
+        return parent_table if path.empty?
+
+        assoc_name, *rest = path
+        reflection = model.reflect_on_association(assoc_name)
+        return nil unless reflection
+
+        fk = reflection.foreign_key.to_s
+        target_table_name = reflection.klass.table_name
+        parent_id = table_identifier(parent_table)
+
+        join_sources.each do |join|
+          joined_table = join.left
+          next unless base_table_name(joined_table) == target_table_name
+          next unless on_has_fk?(join.right.expr, fk)
+          next unless on_references?(join.right.expr, parent_id)
+
+          result = walk_join_path(reflection.klass, joined_table, rest, join_sources)
+          return result if result
+        end
+
+        nil
+      end
+
+      def base_table_name(table)
+        case table
+        when Arel::Nodes::TableAlias then table.left.name
+        when Arel::Table then table.name
+        end
+      end
+
+      def table_identifier(table)
+        case table
+        when Arel::Nodes::TableAlias then table.right.to_s
+        when Arel::Table then table.name
+        end
+      end
+
+      def on_has_fk?(expr, fk)
+        each_equality(expr).any? do |eq|
+          attr_named?(eq.left, fk) || attr_named?(eq.right, fk)
+        end
+      end
+
+      def on_references?(expr, parent_id)
+        each_equality(expr).any? do |eq|
+          attr_from_table?(eq.left, parent_id) || attr_from_table?(eq.right, parent_id)
+        end
+      end
+
+      def attr_named?(node, name)
+        node.respond_to?(:name) && node.name.to_s == name
+      end
+
+      def attr_from_table?(node, table_id)
+        node.respond_to?(:relation) && table_identifier(node.relation) == table_id
+      end
+
+      def each_equality(expr, &block)
+        return enum_for(:each_equality, expr) unless block
+
+        case expr
+        when Arel::Nodes::Equality then yield expr
+        when Arel::Nodes::And then expr.children.each { |c| each_equality(c, &block) }
+        end
+      end
+    end
+  end
+end

data/lib/prato/query/and_filter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Prato
+  module Query
+    class AndFilter
+      attr_reader :filters
+
+      def initialize(filters)
+        @filters = filters
+      end
+    end
+  end
+end

data/lib/prato/query/default_parser.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Prato
+  module Query
+    class DefaultParser
+      def parse_parameters(input, field_lookup)
+        page = extract_page(input)
+        per_page = extract_per_page(input)
+        filters = extract_filters(input)
+        sorts = extract_sorts(input)
+        fields = extract_fields(input)
+
+        Prato::Query::Parameters.new(
+          page: parse_page(page),
+          per_page: parse_per_page(per_page),
+          filters: parse_filters(filters, field_lookup),
+          sorts: parse_sorts(sorts, field_lookup),
+          fields: parse_fields(fields, field_lookup)
+        )
+      end
+
+      def extract_page(input)
+        hash_access(input, "page")
+      end
+
+      def parse_page(raw_value)
+        safe_parse_integer(raw_value)
+      end
+
+      def extract_per_page(input)
+        hash_access(input, "per_page")
+      end
+
+      def parse_per_page(raw_value)
+        safe_parse_integer(raw_value)
+      end
+
+      def extract_filters(input)
+        hash_access(input, "filters")
+      end
+
+      def parse_filters(input, field_lookup)
+        return nil if input.nil?
+
+        entries = normalize_entries_to_hash(input)
+        filters = parse_filter_entries(entries, field_lookup)
+        filters.nil? || filters.empty? ? nil : filters
+      end
+
+      def parse_filter_entries(entries, field_lookup, depth = 0)
+        raise ArgumentError, "Filter nesting too deep (maximum depth: 10)" if depth == 10
+
+        Array.wrap(entries).map do |entry|
+          if hash_access(entry, "or")
+            nested = parse_filter_entries(hash_access(entry, "or"), field_lookup, depth + 1)
+            next if nested.nil? || nested.empty?
+
+            Prato::Query::OrFilter.new(nested)
+          elsif hash_access(entry, "and")
+            nested = parse_filter_entries(hash_access(entry, "and"), field_lookup, depth + 1)
+            next if nested.nil? || nested.empty?
+
+            Prato::Query::AndFilter.new(nested)
+          else
+            field = hash_access(entry, "field")
+            operator = hash_access(entry, "operator")
+            value = hash_access(entry, "value")
+
+            Prato::Query::Filter.new(
+              parse_field(field, field_lookup),
+              operator.to_sym,
+              value
+            )
+          end
+        end.compact
+      end
+
+      def extract_sorts(input)
+        hash_access(input, "sorts")
+      end
+
+      def parse_sorts(input, field_lookup)
+        return nil if input.nil?
+
+        entries = normalize_entries_to_hash(input)
+
+        Array.wrap(entries).map do |entry|
+          field = hash_access(entry, "field")
+          order = hash_access(entry, "order")
+          is_desc = %w[desc descending].include?(order)
+
+          Prato::Query::Sort.new(parse_field(field, field_lookup), is_desc)
+        end
+      end
+
+      def extract_fields(input)
+        hash_access(input, "fields")
+      end
+
+      def parse_fields(input, field_lookup)
+        return nil if input.nil?
+
+        entries = normalize_entries_to_hash(input)
+
+        Array.wrap(entries).map do |entry|
+          parse_field(entry, field_lookup)
+        end
+      end
+
+      def parse_field(field, field_resolver)
+        fields = field.split(".")
+        field_resolver.call(fields)
+      end
+
+      def safe_parse_integer(number)
+        return nil if number.nil?
+
+        begin
+          Integer(number)
+        rescue ArgumentError
+          nil
+        end
+      end
+
+      def normalize_entries_to_hash(input)
+        case input
+        when String
+          JSON.parse(input)
+        when Array, Hash
+          input
+        else
+          raise ArgumentError, "Invalid filters type: #{input.class}"
+        end
+      end
+
+      def hash_access(entry, key)
+        value = entry[key]
+        if value.nil?
+           entry[key.to_sym]
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/prato/query/field_resolver.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Prato
+  module Query
+    # Module that handles converting user input fields into internal fields.
+    module FieldResolver
+      extend self
+
+      SEPARATOR = "___".freeze
+
+      def join(parts)
+        parts = Array(parts)
+        parts.length == 1 ? parts.first.to_sym : parts.map(&:to_s).join(SEPARATOR).to_sym
+      end
+
+      def resolve_context(field_lookup)
+        ->(fields) do
+          field_lookup[fields]
+        end
+      end
+    end
+  end
+end

data/lib/prato/query/filter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Prato
+  module Query
+    class Filter
+      attr_reader :field, :operator, :value
+
+      def initialize(field, operator, value)
+        @field = field
+        @operator = operator
+        @value = value
+      end
+    end
+  end
+end

data/lib/prato/query/or_filter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Prato
+  module Query
+    class OrFilter
+      attr_reader :filters
+
+      def initialize(filters)
+        @filters = filters
+      end
+    end
+  end
+end