cuatlan-activerecord-hierarchical_query 1.0.1

data/lib/active_record/hierarchical_query/query.rb

@@ -0,0 +1,333 @@
+# coding: utf-8
+
+require 'active_support/core_ext/array/extract_options'
+
+require 'active_record/hierarchical_query/orderings'
+require 'active_record/hierarchical_query/join_builder'
+require 'arel/nodes/postgresql'
+
+module ActiveRecord
+  module HierarchicalQuery
+    class Query
+      # @api private
+      ORDERING_COLUMN_NAME = '__order_column'.freeze
+
+      # @api private
+      attr_reader :klass,
+                  :start_with_value,
+                  :connect_by_value,
+                  :child_scope_value,
+                  :limit_value,
+                  :offset_value,
+                  :order_values,
+                  :nocycle_value,
+                  :distinct_value
+
+      # @api private
+      CHILD_SCOPE_METHODS = :where, :joins, :group, :having
+
+      def initialize(klass)
+        @klass = klass
+
+        # start with :all
+        @start_with_value = klass.__send__(HierarchicalQuery::DELEGATOR_SCOPE)
+        @connect_by_value = nil
+        @child_scope_value = klass.__send__(HierarchicalQuery::DELEGATOR_SCOPE)
+        @limit_value = nil
+        @offset_value = nil
+        @nocycle_value = false
+        @order_values = []
+        @distinct_value = false
+      end
+
+      # Specify root scope of the hierarchy.
+      #
+      # @example When scope given
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.start_with(MyModel.where(parent_id: nil))
+      #              .connect_by(id: :parent_id)
+      #   end
+      #
+      # @example When Hash given
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.start_with(parent_id: nil)
+      #              .connect_by(id: :parent_id)
+      #   end
+      #
+      # @example When String given
+      #    MyModel.join_recursive do |hierarchy|
+      #      hierararchy.start_with('parent_id = ?', 1)
+      #                 .connect_by(id: :parent_id)
+      #    end
+      #
+      # @example When block given
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.start_with { |root| root.where(parent_id: nil) }
+      #              .connect_by(id: :parent_id)
+      #   end
+      #
+      # @example When block with arity=0 given
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.start_with { where(parent_id: nil) }
+      #              .connect_by(id: :parent_id)
+      #   end
+      #
+      # @example Specify columns for root relation (PostgreSQL-specific)
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.start_with { select('ARRAY[id] AS _path') }
+      #              .connect_by(id: :parent_id)
+      #              .select('_path || id', start_with: false) # `start_with: false` tells not to include this expression into START WITH clause
+      #   end
+      #
+      # @param [ActiveRecord::Relation, Hash, String, nil] scope root scope (optional).
+      # @return [ActiveRecord::HierarchicalQuery::Query] self
+      def start_with(scope = nil, *arguments, &block)
+        raise ArgumentError, 'START WITH: scope or block expected, none given' unless scope || block
+
+        case scope
+          when Hash, String
+            @start_with_value = klass.where(scope, *arguments)
+
+          when ActiveRecord::Relation
+            @start_with_value = scope
+
+          else
+            # do nothing if something weird given
+        end
+
+        if block
+          object = @start_with_value || @klass
+
+          @start_with_value = if block.arity == 0
+            object.instance_eval(&block)
+          else
+            block.call(object)
+          end
+        end
+
+        self
+      end
+
+      # Specify relationship between parent rows and child rows of the
+      # hierarchy. It can be specified with Hash where keys are parent columns
+      # names and values are child columns names, or with block (see example below).
+      #
+      # @example Specify relationship with Hash (traverse descendants)
+      #   MyModel.join_recursive do |hierarchy|
+      #     # join child rows with condition `parent.id = child.parent_id`
+      #     hierarchy.connect_by(id: :parent_id)
+      #   end
+      #
+      # @example Specify relationship with block (traverse descendants)
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.connect_by { |parent, child| parent[:id].eq(child[:parent_id]) }
+      #   end
+      #
+      # @param [Hash, nil] conditions (optional) relationship between parent rows and
+      #   child rows map, where keys are parent columns names and values are child columns names.
+      # @yield [parent, child] Yields both parent and child tables.
+      # @yieldparam [Arel::Table] parent parent rows table instance.
+      # @yieldparam [Arel::Table] child child rows table instance.
+      # @yieldreturn [Arel::Nodes::Node] relationship condition expressed as Arel node.
+      # @return [ActiveRecord::HierarchicalQuery::Query] self
+      def connect_by(conditions = nil, &block)
+        # convert hash to block which returns Arel node
+        if conditions
+          block = conditions_to_proc(conditions)
+        end
+
+        raise ArgumentError, 'CONNECT BY: Conditions hash or block expected, none given' unless block
+
+        @connect_by_value = block
+
+        self
+      end
+
+      # Specify which columns should be selected in addition to primary key,
+      # CONNECT BY columns and ORDER SIBLINGS columns.
+      #
+      # @param [Array<Symbol, String, Arel::Attributes::Attribute, Arel::Nodes::Node>] columns
+      # @option columns [true, false] :start_with include given columns to START WITH clause (true by default)
+      # @return [ActiveRecord::HierarchicalQuery::Query] self
+      def select(*columns)
+        options = columns.extract_options!
+
+        columns = columns.flatten.map do |column|
+          column.is_a?(Symbol) ? table[column] : column
+        end
+
+        # TODO: detect if column already present in START WITH clause and skip it
+        if options.fetch(:start_with, true)
+          start_with { |scope| scope.select(columns) }
+        end
+
+        @child_scope_value = @child_scope_value.select(columns)
+
+        self
+      end
+
+      # Generate methods that apply filters to child scope, such as
+      # +where+ or +group+.
+      #
+      # @example Filter child nodes by certain condition
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.where('depth < 5')
+      #   end
+      #
+      # @!method where(*conditions)
+      # @!method joins(*tables)
+      # @!method group(*values)
+      # @!method having(*conditions)
+      CHILD_SCOPE_METHODS.each do |method|
+        define_method(method) do |*args|
+          @child_scope_value = @child_scope_value.public_send(method, *args)
+
+          self
+        end
+      end
+
+      # Specifies a limit for the number of records to retrieve.
+      #
+      # @param [Fixnum] value
+      # @return [ActiveRecord::HierarchicalQuery::Query] self
+      def limit(value)
+        @limit_value = value
+
+        self
+      end
+
+      # Specifies the number of rows to skip before returning row
+      #
+      # @param [Fixnum] value
+      # @return [ActiveRecord::HierarchicalQuery::Query] self
+      def offset(value)
+        @offset_value = value
+
+        self
+      end
+
+      # Specifies hierarchical order of the recursive query results.
+      #
+      # @example
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.connect_by(id: :parent_id)
+      #              .order_siblings(:name)
+      #   end
+      #
+      # @example
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.connect_by(id: :parent_id)
+      #              .order_siblings('name DESC, created_at ASC')
+      #   end
+      #
+      # @param [<Symbol, String, Arel::Nodes::Node, Arel::Attributes::Attribute>] columns
+      # @return [ActiveRecord::HierarchicalQuery::Query] self
+      def order_siblings(*columns)
+        @order_values += columns
+
+        self
+      end
+      alias_method :order, :order_siblings
+
+      # Turn on/off cycles detection. This option can prevent
+      # endless loops if your tree could contain cycles.
+      #
+      # @param [true, false] value
+      # @return [ActiveRecord::HierarchicalQuery::Query] self
+      def nocycle(value = true)
+        @nocycle_value = value
+        self
+      end
+
+      # Returns object representing parent rows table,
+      # so it could be used in complex WHEREs.
+      #
+      # @example
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.connect_by(id: :parent_id)
+      #              .start_with(parent_id: nil) { select(:depth) }
+      #              .select(hierarchy.table[:depth])
+      #              .where(hierarchy.prior[:depth].lteq 1)
+      #   end
+      #
+      # @return [Arel::Table]
+      def prior
+        @recursive_table ||= Arel::Table.new("#{normalized_table_name}__recursive")
+      end
+      alias_method :previous, :prior
+      alias_method :recursive_table, :prior
+
+      # Returns object representing child rows table,
+      # so it could be used in complex WHEREs.
+      #
+      # @example
+      #   MyModel.join_recursive do |hierarchy|
+      #     hierarchy.connect_by(id: :parent_id)
+      #              .start_with(parent_id: nil) { select(:depth) }
+      #              .select(hierarchy.table[:depth])
+      #              .where(hierarchy.prior[:depth].lteq 1)
+      #   end
+      def table
+        @klass.arel_table
+      end
+
+      # Turn on select distinct option in the CTE.
+      #
+      # @return [ActiveRecord::HierarchicalQuery::Query] self
+      def distinct
+        @distinct_value = true
+        self
+      end
+
+      # @return [Arel::Nodes::Node]
+      # @api private
+      def join_conditions
+        connect_by_value.call(recursive_table, table)
+      end
+
+      # @return [ActiveRecord::HierarchicalQuery::Orderings]
+      # @api private
+      def orderings
+        @orderings ||= Orderings.new(order_values, table)
+      end
+
+      # @api private
+      def ordering_column_name
+        ORDERING_COLUMN_NAME
+      end
+
+      # Builds recursive query and joins it to given +relation+.
+      #
+      # @api private
+      # @param [ActiveRecord::Relation] relation
+      # @param [Hash] join_options
+      # @option join_options [#to_s] :as joined table alias
+      # @api private
+      def join_to(relation, join_options = {})
+        raise 'Recursive query requires CONNECT BY clause, please use #connect_by method' unless
+            connect_by_value
+
+        table_alias = join_options.fetch(:as, "#{normalized_table_name}__recursive")
+
+        JoinBuilder.new(self, relation, table_alias, join_options).build
+      end
+
+      private
+      # converts conditions given as a hash to proc
+      def conditions_to_proc(conditions)
+        proc do |parent, child|
+          conditions.map do |parent_expression, child_expression|
+            parent_expression = parent[parent_expression] if parent_expression.is_a?(Symbol)
+            child_expression = child[child_expression] if child_expression.is_a?(Symbol)
+
+            Arel::Nodes::Equality.new(parent_expression, child_expression)
+          end.reduce(:and)
+        end
+      end
+
+      def normalized_table_name
+        table.name.gsub('.', '_')
+      end
+    end # class Builder
+  end # module HierarchicalQuery
+end # module ActiveRecord

data/lib/active_record/hierarchical_query/version.rb

@@ -0,0 +1,5 @@
+module ActiveRecord
+  module HierarchicalQuery
+    VERSION = '1.0.1'
+  end
+end

data/lib/activerecord-hierarchical_query.rb

@@ -0,0 +1 @@
+require 'active_record/hierarchical_query'

data/lib/arel/nodes/postgresql.rb

@@ -0,0 +1,60 @@
+require 'arel/visitors/to_sql'
+
+module Arel
+  module Nodes
+    class PostgresArray < Node
+      include AliasPredication
+      attr_accessor :values
+
+      def initialize(values)
+        self.values = values
+      end
+    end
+
+    class ArrayConcat < Binary
+    end
+
+    class UnionDistinct < Binary
+    end
+  end
+
+  module Visitors
+    class ToSql < ToSql.superclass
+      private
+      ARRAY_OPENING = 'ARRAY['.freeze
+      ARRAY_CLOSING = ']'.freeze
+      ARRAY_CONCAT = '||'.freeze
+
+      if Arel::VERSION < '6.0.0'
+        def visit_Arel_Nodes_PostgresArray o, *a
+          "#{ARRAY_OPENING}#{visit o.values, *a}#{ARRAY_CLOSING}"
+        end
+
+        def visit_Arel_Nodes_ArrayConcat o, *a
+          "#{visit o.left, *a} #{ARRAY_CONCAT} #{visit o.right, *a}"
+        end
+
+        def visit_Arel_Nodes_UnionDistinct o, *a
+          "( #{visit o.left, *a} UNION DISTINCT #{visit o.right, *a} )"
+        end
+      else
+        def visit_Arel_Nodes_PostgresArray o, collector
+          collector << ARRAY_OPENING
+          visit o.values, collector
+          collector << ARRAY_CLOSING
+        end
+
+        def visit_Arel_Nodes_ArrayConcat o, collector
+          visit o.left, collector
+          collector << ARRAY_CONCAT
+          visit o.right, collector
+        end
+
+        def visit_Arel_Nodes_UnionDistinct o, collector
+          collector << "( "
+          infix_value(o, collector, " UNION DISTINCT ") << " )"
+        end
+      end
+    end
+  end
+end

data/spec/active_record/hierarchical_query_spec.rb

@@ -0,0 +1,338 @@
+require 'spec_helper'
+
+describe ActiveRecord::HierarchicalQuery do
+  let(:klass) { Category }
+
+  let(:trait_id) { 'trait' }
+  let!(:root) { klass.create(trait_id: trait_id) }
+  let!(:child_1) { klass.create(parent: root, trait_id: trait_id) }
+  let!(:child_2) { klass.create(parent: child_1, trait_id: trait_id) }
+  let!(:child_3) { klass.create(parent: child_1, trait_id: trait_id) }
+  let!(:child_4) { klass.create(parent: root, trait_id: trait_id) }
+  let!(:child_5) { klass.create(parent: child_4, trait_id: trait_id) }
+
+  describe '#join_recursive' do
+    describe 'UNION clause' do
+      let(:options) { {} }
+      subject { klass.join_recursive(options) { connect_by(id: :parent_id) }.to_sql }
+
+      it 'defaults to UNION ALL' do
+        expect(subject).to include('UNION ALL')
+      end
+
+      context 'specifying DISTINCT union type' do
+        let(:options) { { union_type: :distinct } }
+
+        it 'uses UNION DISTINCT' do
+          expect(subject).to include('UNION DISTINCT')
+          expect(subject).to_not include('UNION ALL')
+        end
+      end
+
+      context 'specifying ALL union type' do
+        let(:options) { { union_type: :all } }
+
+        it 'uses UNION ALL' do
+          expect(subject).to include('UNION ALL')
+          expect(subject).to_not include('UNION DISTINCT')
+        end
+      end
+    end
+
+    describe 'CONNECT BY clause' do
+      it 'throws error if CONNECT BY clause not specified' do
+        expect {
+          klass.join_recursive {}
+        }.to raise_error /CONNECT BY clause/
+      end
+
+      it 'joins parent and child rows by hash map' do
+        expect(
+          klass.join_recursive { connect_by(id: :parent_id) }
+        ).to include root, child_1, child_2, child_3, child_4, child_5
+      end
+
+      it 'joins parent and child rows by block' do
+        expect(
+          klass.join_recursive do
+            connect_by { |parent, child| parent[:id].eq child[:parent_id] }
+          end
+        ).to include root, child_1, child_2, child_3, child_4, child_5
+      end
+    end
+
+    describe 'START WITH clause' do
+      def assert_start_with(&block)
+        expect(
+          klass.join_recursive do |b|
+            b.connect_by(id: :parent_id).instance_eval(&block)
+          end
+        ).to match_array [root, child_1, child_2, child_3, child_4, child_5]
+      end
+
+      it 'filters rows in non-recursive term by hash' do
+        assert_start_with { start_with(parent_id: nil) }
+      end
+
+      it 'filters rows in non-recursive term by block with arity > 0' do
+        assert_start_with { start_with { |root| root.where(parent_id: nil) } }
+      end
+
+      it 'filters rows in non-recursive term by block with arity = 0' do
+        assert_start_with { start_with { where(parent_id: nil) } }
+      end
+
+      it 'filters rows in non-recursive term by scope' do
+        assert_start_with { start_with(klass.where(parent_id: nil)) }
+      end
+    end
+
+    describe 'ORDER SIBLINGS BY clause' do
+      def assert_ordered_by_name_desc(&block)
+        expect(
+          klass.join_recursive do |b|
+            b.connect_by(id: :parent_id).start_with(parent_id: nil).instance_eval(&block)
+          end
+        ).to eq [root, child_4, child_5, child_1, child_3, child_2]
+      end
+
+      def assert_ordered_by_name_asc(&block)
+        expect(
+            klass.join_recursive do |b|
+              b.connect_by(id: :parent_id).start_with(parent_id: nil).instance_eval(&block)
+            end
+        ).to eq [root, child_1, child_2, child_3, child_4, child_5]
+      end
+
+      it 'orders rows by Hash' do
+        assert_ordered_by_name_desc { order_siblings(name: :desc) }
+      end
+
+      it 'orders rows by String' do
+        assert_ordered_by_name_desc { order_siblings('name desc') }
+        assert_ordered_by_name_asc { order_siblings('name asc') }
+      end
+
+      it 'orders rows by Arel::Nodes::Ordering' do
+        assert_ordered_by_name_desc { order_siblings(table[:name].desc) }
+      end
+
+      it 'orders rows by Arel::Nodes::Node' do
+        assert_ordered_by_name_asc { order_siblings(table[:name]) }
+      end
+
+      it 'throws error when something weird given' do
+        expect {
+          klass.join_recursive { connect_by(id: :parent_id).order_siblings(1) }
+        }.to raise_error /ORDER BY SIBLINGS/
+      end
+
+      context 'when one attribute given and this attribute support natural sorting' do
+        let(:relation) do
+          klass.join_recursive do
+            connect_by(id: :parent_id).
+            start_with(parent_id: nil).
+            order_siblings(:position)
+          end
+        end
+
+        it 'orders rows by given attribute' do
+          expect(relation).to eq [root, child_1, child_2, child_3, child_4, child_5]
+          expect(relation.to_sql).not_to match /row_number/i
+        end
+      end
+    end
+
+    describe 'LIMIT and OFFSET clauses' do
+      let(:ordered_nodes) { [root, child_1, child_2, child_3, child_4, child_5] }
+
+      it 'limits all rows' do
+        expect(
+          klass.join_recursive do
+            connect_by(id: :parent_id).
+            start_with(parent_id: nil).
+            limit(2).
+            offset(2)
+          end.size
+        ).to eq 2
+      end
+
+      it 'limits all rows if ordering given' do
+        expect(
+            klass.join_recursive do
+              connect_by(id: :parent_id).
+              start_with(parent_id: nil).
+              order_siblings(:name).
+              limit(2).
+              offset(2)
+            end
+        ).to eq ordered_nodes[2...4]
+      end
+    end
+
+    describe 'WHERE clause' do
+      it 'filters child rows' do
+        expect(
+          klass.join_recursive do
+            connect_by(id: :parent_id).
+            start_with(parent_id: nil).
+            where('depth < ?', 2)
+          end
+        ).to match_array [root, child_1, child_4]
+      end
+
+      it 'allows to use PRIOR relation' do
+        expect(
+          klass.join_recursive do |b|
+            b.connect_by(id: :parent_id)
+             .start_with(parent_id: nil)
+             .select(:depth)
+             .where(b.prior[:depth].lt(1))
+          end
+        ).to match_array [root, child_1, child_4]
+      end
+    end
+
+    describe 'SELECT clause' do
+      it 'adds column to both recursive and non-recursive term' do
+        expect(
+          klass.join_recursive(as: 'categories_r') do
+            connect_by(id: :parent_id).
+            start_with(parent_id: nil).
+            select(:depth)
+          end.where('categories_r.depth = 0')
+        ).to eq [root]
+      end
+    end
+
+    describe 'NOCYCLE clause' do
+      before { klass.where(id: child_4.id).update_all(parent_id: child_5.id) }
+
+      it 'prevents recursive query from endless loops' do
+        expect(
+          klass.join_recursive do |query|
+            query.start_with(id: child_4.id)
+                 .connect_by(id: :parent_id)
+                 .nocycle
+          end
+        ).to match_array [child_4, child_5]
+      end
+    end
+  end
+
+  describe '#join_recursive options' do
+    describe ':as option' do
+      it 'builds a join with specified alias' do
+        expect(
+          klass.join_recursive(as: 'my_table') { connect_by(id: :parent_id) }.to_sql
+        ).to match /my_table/
+      end
+    end
+
+    describe ':foreign_key' do
+      it 'uses described foreign_key when joining table to recursive view' do
+        expect(
+          klass.join_recursive(foreign_key: 'some_column') { connect_by(id: :parent_id) }.to_sql
+        ).to match /categories\"\.\"id\" = \"categories__recursive\"\.\"some_column/
+      end
+    end
+
+    describe ':outer_join_hierarchical' do
+      subject { klass.join_recursive(outer_join_hierarchical: value) { connect_by(id: :parent_id) }.to_sql }
+
+      let(:value) { true }
+      let(:inner_join) {
+        /INNER JOIN \(WITH RECURSIVE \"categories__recursive\"/
+      }
+
+      it 'builds an outer join' do
+        expect(subject).to match /LEFT OUTER JOIN \(WITH RECURSIVE \"categories__recursive\"/
+      end
+
+      context 'value is false' do
+        let(:value) { false }
+
+        it 'builds an inner join' do
+          expect(subject).to match inner_join
+        end
+      end
+
+      context 'value is a string' do
+        let(:value) { 'foo' }
+
+        it 'builds an inner join' do
+          expect(subject).to match inner_join
+        end
+      end
+
+      context 'key is absent' do
+        subject { klass.join_recursive { connect_by(id: :parent_id) }.to_sql }
+
+        it 'builds an inner join' do
+          expect(subject).to match inner_join
+        end
+      end
+    end
+  end
+
+  describe ':distinct query method' do
+    subject { klass.join_recursive { connect_by(id: :parent_id).distinct }.to_sql }
+
+    let(:select) {
+      /SELECT \"categories__recursive\"/
+    }
+
+    it 'selects using a distinct option after joining table to recursive view' do
+      expect(subject).to match /SELECT DISTINCT \"categories__recursive\"/
+    end
+
+    context 'distinct method is absent' do
+      subject { klass.join_recursive { connect_by(id: :parent_id) }.to_sql }
+
+      it 'selects without using a distinct' do
+        expect(subject).to match select
+      end
+    end
+  end
+
+  describe 'Testing bind variables' do
+    let!(:article) { Article.create!(category: child_2, title: 'Alpha') }
+
+    let(:subquery) do
+      klass.join_recursive do |query|
+        query.
+          start_with(trait_id: trait_id, parent_id: child_1.id).
+          connect_by(id: :parent_id).
+          where(trait_id: trait_id)
+      end
+    end
+
+    let(:outer_query) do
+      Article.where(category_id: subquery, title: 'Alpha')
+    end
+
+    subject(:result) { outer_query.to_a }
+
+    it 'returns result without throwing an error' do
+      expect(result).to include(article)
+    end
+  end
+
+  describe 'Models with default scope' do
+    let!(:scoped_root) { ModelWithDefaultScope.create!(name: '9. Root') }
+    let!(:scoped_child_1) { ModelWithDefaultScope.create!(name: '8. Child', parent: scoped_root) }
+    let!(:scoped_child_2) { ModelWithDefaultScope.create!(name: '7. Child', parent: scoped_root) }
+
+    subject(:result) {
+      ModelWithDefaultScope.join_recursive do |query|
+        query
+          .connect_by(id: :parent_id)
+          .start_with(id: scoped_root.id)
+      end
+    }
+
+    it 'applies default scope to outer query without affecting recursive terms' do
+      expect(result).to eq [scoped_child_2, scoped_child_1, scoped_root]
+    end
+  end
+end