closure_tree 6.4.0 → 7.2.0

data/Gemfile

@@ -1,15 +1,3 @@
 source 'https://rubygems.org'
 
-platforms :ruby, :rbx do
-  gem 'mysql2'
-  gem 'pg'
-  gem 'sqlite3'
-end
-
-platforms :jruby do
-  gem 'activerecord-jdbcmysql-adapter'
-  gem 'activerecord-jdbcpostgresql-adapter'
-  gem 'activerecord-jdbcsqlite3-adapter'
-end
-
 gemspec

data/README.md

@@ -6,10 +6,8 @@ Common applications include modeling hierarchical data, like tags, threaded comm
 and tracking user referrals.
 
 [![Join the chat at https://gitter.im/closure_tree/Lobby](https://badges.gitter.im/closure_tree/Lobby.svg)](https://gitter.im/closure_tree/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![Build Status](https://api.travis-ci.org/mceachen/closure_tree.svg?branch=master)](http://travis-ci.org/mceachen/closure_tree)
+[![Build Status](https://api.travis-ci.org/ClosureTree/closure_tree.svg?branch=master)](http://travis-ci.org/ClosureTree/closure_tree)
 [![Gem Version](https://badge.fury.io/rb/closure_tree.svg)](https://badge.fury.io/rb/closure_tree)
-[![Codacy Badge](https://api.codacy.com/project/badge/Grade/fa5a8ae2193d42adb30b4256732a757d)](https://www.codacy.com/app/matthew-github/closure_tree)
-[![Dependency Status](https://gemnasium.com/badges/github.com/mceachen/closure_tree.svg)](https://gemnasium.com/github.com/mceachen/closure_tree)
 
 Dramatically more performant than
 [ancestry](https://github.com/stefankroes/ancestry) and
@@ -26,9 +24,8 @@ closure_tree has some great features:
 * __Best-in-class mutation performance__:
   * 2 SQL INSERTs on node creation
   * 3 SQL INSERT/UPDATEs on node reparenting
-* __Support for [concurrency](#concurrency)__ (using [with_advisory_lock](https://github.com/mceachen/with_advisory_lock))
-* __Support for ActiveRecord 4.2 and 5.0__
-* __Support for Ruby 2.2 and 2.3__
+* __Support for [concurrency](#concurrency)__ (using [with_advisory_lock](https://github.com/ClosureTree/with_advisory_lock))
+* __Tested against ActiveRecord 4.2, 5.0, 5.1, 5.2 and 6.0 with  Ruby 2.5 and 2.6__
 * Support for reparenting children (and all their descendants)
 * Support for [single-table inheritance (STI)](#sti) within the hierarchy
 * ```find_or_create_by_path``` for [building out heterogeneous hierarchies quickly and conveniently](#find_or_create_by_path)
@@ -56,7 +53,7 @@ for a description of different tree storage algorithms.
 
 ## Installation
 
-Note that closure_tree only supports ActiveRecord 4.1 and later, and has test coverage for MySQL, PostgreSQL, and SQLite.
+Note that closure_tree only supports ActiveRecord 4.2 and later, and has test coverage for MySQL, PostgreSQL, and SQLite.
 
 1.  Add `gem 'closure_tree'` to your Gemfile
 
@@ -74,7 +71,7 @@ Note that closure_tree only supports ActiveRecord 4.1 and later, and has test co
     end
     ```
 
-    Make sure you check out the [large number options](#available-options) that `has_closure_tree` accepts.
+    Make sure you check out the [large number of options](#available-options) that `has_closure_tree` accepts.
 
     **IMPORTANT: Make sure you add `has_closure_tree` _after_ `attr_accessible` and
     `self.table_name =` lines in your model.**
@@ -88,7 +85,7 @@ Note that closure_tree only supports ActiveRecord 4.1 and later, and has test co
     ```ruby
     class AddParentIdToTag < ActiveRecord::Migration
       def change
-        add_column :tag, :parent_id, :integer
+        add_column :tags, :parent_id, :integer
       end
     end
     ```
@@ -254,7 +251,7 @@ b.hash_tree(:limit_depth => 2)
 Without this option, ```hash_tree``` will load the entire contents of that table into RAM. Your
 server may not be happy trying to do this.
 
-HT: [ancestry](https://github.com/stefankroes/ancestry#arrangement) and [elhoyos](https://github.com/mceachen/closure_tree/issues/11)
+HT: [ancestry](https://github.com/stefankroes/ancestry#arrangement) and [elhoyos](https://github.com/ClosureTree/closure_tree/issues/11)
 
 ### Eager loading
 
@@ -305,13 +302,13 @@ File.open("example.dot", "w") { |f| f.write(Tag.root.to_dot_digraph) }
 ```
 Then, in a shell, ```dot -Tpng example.dot > example.png```, which produces:
 
-![Example tree](https://raw.github.com/mceachen/closure_tree/master/img/example.png)
+![Example tree](https://raw.github.com/ClosureTree/closure_tree/master/img/example.png)
 
 If you want to customize the label value, override the ```#to_digraph_label``` instance method in your model.
 
 Just for kicks, this is the test tree I used for proving that preordered tree traversal was correct:
 
-![Preordered test tree](https://raw.github.com/mceachen/closure_tree/master/img/preorder.png)
+![Preordered test tree](https://raw.github.com/ClosureTree/closure_tree/master/img/preorder.png)
 
 ### Available options
 
@@ -341,20 +338,24 @@ When you include ```has_closure_tree``` in your model, you can provide a hash to
 * ```Tag.find_or_create_by_path(path, attributes)``` returns the node whose name path is ```path```, and will create the node if it doesn't exist already.See (#find_or_create_by_path).
 * ```Tag.find_all_by_generation(generation_level)``` returns the descendant nodes who are ```generation_level``` away from a root. ```Tag.find_all_by_generation(0)``` is equivalent to ```Tag.roots```.
 * ```Tag.with_ancestor(ancestors)``` scopes to all descendants whose ancestor is in the given list.
-
+* ```Tag.lowest_common_ancestor(descendants)``` finds the lowest common ancestor of the descendants.
 ### Instance methods
 
 * ```tag.root``` returns the root for this node
 * ```tag.root?``` returns true if this is a root node
+* ```tag.root_of?(node)``` returns true if current node is root of another one
 * ```tag.child?``` returns true if this is a child node. It has a parent.
 * ```tag.leaf?``` returns true if this is a leaf node. It has no children.
 * ```tag.leaves``` is scoped to all leaf nodes in self_and_descendants.
 * ```tag.depth``` returns the depth, or "generation", for this node in the tree. A root node will have a value of 0.
 * ```tag.parent``` returns the node's immediate parent. Root nodes will return nil.
+* ```tag.parent_of?(node)``` returns true if current node is parent of another one
 * ```tag.children``` is a ```has_many``` of immediate children (just those nodes whose parent is the current node).
 * ```tag.child_ids``` is an array of the IDs of the children.
+* ```tag.child_of?(node)``` returns true if current node is child of another one
 * ```tag.ancestors``` is a ordered scope of [ parent, grandparent, great grandparent, … ]. Note that the size of this array will always equal ```tag.depth```.
 * ```tag.ancestor_ids``` is an array of the IDs of the ancestors.
+* ```tag.ancestor_of?(node)``` returns true if current node is ancestor of another one
 * ```tag.self_and_ancestors``` returns a scope containing self, parent, grandparent, great grandparent, etc.
 * ```tag.self_and_ancestors_ids``` returns IDs containing self, parent, grandparent, great grandparent, etc.
 * ```tag.siblings``` returns a scope containing all nodes with the same parent as ```tag```, excluding self.
@@ -362,8 +363,10 @@ When you include ```has_closure_tree``` in your model, you can provide a hash to
 * ```tag.self_and_siblings``` returns a scope containing all nodes with the same parent as ```tag```, including self.
 * ```tag.descendants``` returns a scope of all children, childrens' children, etc., excluding self ordered by depth.
 * ```tag.descendant_ids``` returns an array of the IDs of the descendants.
+* ```tag.descendant_of?(node)``` returns true if current node is descendant of another one
 * ```tag.self_and_descendants``` returns a scope of self, all children, childrens' children, etc., ordered by depth.
 * ```tag.self_and_descendant_ids``` returns IDs of self, all children, childrens' children, etc., ordered by depth.
+* ```tag.family_of?``` returns true if current node and another one have a same root.
 * ```tag.hash_tree``` returns an [ordered, nested hash](#nested-hashes) that can be depth-limited.
 * ```tag.find_by_path(path)``` returns the node whose name path *from ```tag```* is ```path```. See (#find_or_create_by_path).
 * ```tag.find_or_create_by_path(path)``` returns the node whose name path *from ```tag```* is ```path```, and will create the node if it doesn't exist already.See (#find_or_create_by_path).
@@ -389,6 +392,18 @@ class WhereTag < Tag ; end
 class WhatTag < Tag ; end
 ```
 
+Note that if you call `rebuild!` on any of the subclasses, the complete Tag hierarchy will be emptied, thus taking the hiearchies of all other subclasses with it (issue #275). However, only the hierarchies for the class `rebuild!` was called on will be rebuilt, leaving the other subclasses without hierarchy entries.
+
+You can work around that by overloading the `rebuild!` class method in all your STI subclasses and call the super classes `rebuild!` method:
+```ruby
+class WhatTag < Tag
+  def self.rebuild!
+    Tag.rebuild!
+  end
+end
+```
+This way, the complete hierarchy including all subclasses will be rebuilt.
+
 ## Deterministic ordering
 
 By default, children will be ordered by your database engine, which may not be what you want.
@@ -411,7 +426,7 @@ and in your model:
 
 ```ruby
 class OrderedTag < ActiveRecord::Base
-  has_closure_tree order: 'sort_order'
+  has_closure_tree order: 'sort_order', numeric_order: true
 end
 ```
 
@@ -477,6 +492,25 @@ root.reload.children.pluck(:name)
 => ["b", "c", "a"]
 ```
 
+### Ordering Roots
+
+With numeric ordering, root nodes are, by default, assigned order values globally across the whole database
+table. So for instance if you have 5 nodes with no parent, they will be ordered 0 through 4 by default.
+If your model represents many separate trees and you have a lot of records, this can cause performance
+problems, and doesn't really make much sense.
+
+You can disable this default behavior by passing `dont_order_roots: true` as an option to your delcaration:
+
+```
+has_closure_tree order: 'sort_order', numeric_order: true, dont_order_roots: true
+```
+
+In this case, calling `prepend_sibling` and `append_sibling` on a root node or calling
+`roots_and_descendants_preordered` on the model will raise a `RootOrderingDisabledError`.
+
+The `dont_order_roots` option will be ignored unless `numeric_order` is set to true.
+
+
 ## Concurrency
 
 Several methods, especially ```#rebuild``` and ```#find_or_create_by_path```, cannot run concurrently correctly.
@@ -484,7 +518,7 @@ Several methods, especially ```#rebuild``` and ```#find_or_create_by_path```, ca
 
 Database row-level locks work correctly with PostgreSQL, but MySQL's row-level locking is broken, and
 erroneously reports deadlocks where there are none. To work around this, and have a consistent implementation
-for both MySQL and PostgreSQL, [with_advisory_lock](https://github.com/mceachen/with_advisory_lock)
+for both MySQL and PostgreSQL, [with_advisory_lock](https://github.com/ClosureTree/with_advisory_lock)
 is used automatically to ensure correctness.
 
 If you are already managing concurrency elsewhere in your application, and want to disable the use
@@ -499,6 +533,15 @@ end
 Note that you *will eventually have data corruption* if you disable advisory locks, write to your
 database with multiple threads, and don't provide an alternative mutex.
 
+## I18n
+
+You can customize error messages using [I18n](http://guides.rubyonrails.org/i18n.html):
+
+```yaml
+en-US:
+  closure_tree:
+    loop_error: Your descendant cannot be your parent!
+```
 
 ## FAQ
 
@@ -508,7 +551,7 @@ Yup! [Ilya Bodrov](https://github.com/bodrovis) wrote [Nested Comments with Rail
 
 ### Does this work well with ```#default_scope```?
 
-**No.** Please see [issue 86](https://github.com/mceachen/closure_tree/issues/86) for details.
+**No.** Please see [issue 86](https://github.com/ClosureTree/closure_tree/issues/86) for details.
 
 ### Can I update parentage with `update_attribute`?
 
@@ -517,7 +560,7 @@ hierarchy table.
 
 ### Can I assign a parent to multiple children with  ```#update_all```?
 
-**No.** Please see [issue 197](https://github.com/mceachen/closure_tree/issues/197) for details.
+**No.** Please see [issue 197](https://github.com/ClosureTree/closure_tree/issues/197) for details.
 
 ### Does this gem support multiple parents?
 
@@ -576,11 +619,11 @@ bundle install
 
 ### Object destroy fails with MySQL v5.7+
 
-A bug was introduced in MySQL's query optimizer. [See the workaround here](https://github.com/mceachen/closure_tree/issues/206).
+A bug was introduced in MySQL's query optimizer. [See the workaround here](https://github.com/ClosureTree/closure_tree/issues/206).
 
 ### Hierarchy maintenance errors from MySQL v5.7.9-v5.7.10
 
-Upgrade to MySQL 5.7.12 or later if you see [this issue](https://github.com/mceachen/closure_tree/issues/190):
+Upgrade to MySQL 5.7.12 or later if you see [this issue](https://github.com/ClosureTree/closure_tree/issues/190):
 
     Mysql2::Error: You can't specify target table '*_hierarchies' for update in FROM clause
 
@@ -617,10 +660,10 @@ end
 
 ## Testing
 
-Closure tree is [tested under every valid combination](http://travis-ci.org/#!/mceachen/closure_tree) of
+Closure tree is [tested under every valid combination](http://travis-ci.org/#!/ClosureTree/closure_tree) of
 
-* Ruby 2.0, 2.2, 2.3.1
-* ActiveRecord 4.1, 4.2, and 5.0
+* Ruby 2.5, 2.6 and 2.7
+* ActiveRecord 4.2, 5.x and 6.0
 * PostgreSQL, MySQL, and SQLite. Concurrency tests are only run with MySQL and PostgreSQL.
 
 Assuming you're using [rbenv](https://github.com/sstephenson/rbenv), you can use ```tests.sh``` to
@@ -628,12 +671,12 @@ run the test matrix locally.
 
 ## Change log
 
-See the [change log](https://github.com/mceachen/closure_tree/blob/master/CHANGELOG.md).
+See the [change log](https://github.com/ClosureTree/closure_tree/blob/master/CHANGELOG.md).
 
 ## Thanks to
 
 * The 45+ engineers around the world that have contributed their time and code to this gem
-  (see the [changelog](https://github.com/mceachen/closure_tree/blob/master/CHANGELOG.md)!)
+  (see the [changelog](https://github.com/ClosureTree/closure_tree/blob/master/CHANGELOG.md)!)
 * https://github.com/collectiveidea/awesome_nested_set
 * https://github.com/patshaughnessy/class_factory
 * JetBrains, which provides an [open-source license](http://www.jetbrains.com/ruby/buy/buy.jsp#openSource) to

data/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-leap-day

data/closure_tree.gemspec

@@ -12,20 +12,23 @@ Gem::Specification.new do |gem|
   gem.description = gem.summary
   gem.license     = 'MIT'
 
-  gem.files       = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  gem.files         = `git ls-files`.split($/).reject do |f|
+    f.match(%r{^(spec|img|gemfiles)})
+  end
+
   gem.test_files  = gem.files.grep(%r{^spec/})
   gem.required_ruby_version = '>= 2.0.0'
 
-  gem.add_runtime_dependency 'activerecord', '>= 4.1.0'
-  gem.add_runtime_dependency 'with_advisory_lock', '>= 3.0.0'
+  gem.add_runtime_dependency 'activerecord', '>= 4.2.10'
+  gem.add_runtime_dependency 'with_advisory_lock', '>= 4.0.0'
 
+  gem.add_development_dependency 'appraisal'
+  gem.add_development_dependency 'database_cleaner'
+  gem.add_development_dependency 'generator_spec'
+  gem.add_development_dependency 'parallel'
   gem.add_development_dependency 'rspec-instafail'
   gem.add_development_dependency 'rspec-rails'
-  gem.add_development_dependency 'database_cleaner'
-  gem.add_development_dependency 'appraisal'
   gem.add_development_dependency 'timecop'
-  gem.add_development_dependency 'parallel'
-  # gem.add_development_dependency 'ammeter', '1.1.2' # See https://github.com/mceachen/closure_tree/issues/181
   # gem.add_development_dependency 'byebug'
   # gem.add_development_dependency 'ruby-prof' # <- don't need this normally.
 end

data/lib/closure_tree/finders.rb

@@ -34,14 +34,14 @@ module ClosureTree
     end
 
     def find_all_by_generation(generation_level)
-      s = _ct.base_class.joins(<<-SQL.strip_heredoc)
+      s = _ct.base_class.joins(<<-SQL.squish)
         INNER JOIN (
           SELECT descendant_id
           FROM #{_ct.quoted_hierarchy_table_name}
           WHERE ancestor_id = #{_ct.quote(self.id)}
           GROUP BY descendant_id
           HAVING MAX(#{_ct.quoted_hierarchy_table_name}.generations) = #{generation_level.to_i}
-        ) AS descendants ON (#{_ct.quoted_table_name}.#{_ct.base_class.primary_key} = descendants.descendant_id)
+        ) #{ _ct.t_alias_keyword } descendants ON (#{_ct.quoted_table_name}.#{_ct.base_class.primary_key} = descendants.descendant_id)
       SQL
       _ct.scope_with_order(s)
     end
@@ -70,13 +70,13 @@ module ClosureTree
       end
 
       def leaves
-        s = joins(<<-SQL.strip_heredoc)
+        s = joins(<<-SQL.squish)
           INNER JOIN (
             SELECT ancestor_id
             FROM #{_ct.quoted_hierarchy_table_name}
             GROUP BY ancestor_id
             HAVING MAX(#{_ct.quoted_hierarchy_table_name}.generations) = 0
-          ) AS leaves ON (#{_ct.quoted_table_name}.#{primary_key} = leaves.ancestor_id)
+          ) #{ _ct.t_alias_keyword } leaves ON (#{_ct.quoted_table_name}.#{primary_key} = leaves.ancestor_id)
         SQL
         _ct.scope_with_order(s.readonly(false))
       end
@@ -90,19 +90,41 @@ module ClosureTree
         _ct.scope_with_order(scope)
       end
 
+      def with_descendant(*descendants)
+        descendant_ids = descendants.map { |ea| ea.is_a?(ActiveRecord::Base) ? ea._ct_id : ea }
+        scope = descendant_ids.blank? ? all : joins(:descendant_hierarchies).
+          where("#{_ct.hierarchy_table_name}.descendant_id" => descendant_ids).
+          where("#{_ct.hierarchy_table_name}.generations > 0").
+          readonly(false)
+        _ct.scope_with_order(scope)
+      end
+
+      def lowest_common_ancestor(*descendants)
+        descendants = descendants.first if descendants.length == 1 && descendants.first.respond_to?(:each)
+        ancestor_id = hierarchy_class
+          .where(descendant_id: descendants)
+          .group(:ancestor_id)
+          .having("COUNT(ancestor_id) = #{descendants.count}")
+          .order(Arel.sql('MIN(generations) ASC'))
+          .limit(1)
+          .pluck(:ancestor_id).first
+
+        find_by(primary_key => ancestor_id) if ancestor_id
+      end
+
       def find_all_by_generation(generation_level)
-        s = joins(<<-SQL.strip_heredoc)
+        s = joins(<<-SQL.squish)
           INNER JOIN (
             SELECT #{primary_key} as root_id
             FROM #{_ct.quoted_table_name}
             WHERE #{_ct.quoted_parent_column_name} IS NULL
-          ) AS roots ON (1 = 1)
+          ) #{ _ct.t_alias_keyword }  roots ON (1 = 1)
           INNER JOIN (
             SELECT ancestor_id, descendant_id
             FROM #{_ct.quoted_hierarchy_table_name}
             GROUP BY ancestor_id, descendant_id
             HAVING MAX(generations) = #{generation_level.to_i}
-          ) AS descendants ON (
+          ) #{ _ct.t_alias_keyword }  descendants ON (
             #{_ct.quoted_table_name}.#{primary_key} = descendants.descendant_id
             AND roots.root_id = descendants.ancestor_id
           )
@@ -112,6 +134,7 @@ module ClosureTree
 
       # Find the node whose +ancestry_path+ is +path+
       def find_by_path(path, attributes = {}, parent_id = nil)
+        return nil if path.blank?
         path = _ct.build_ancestry_attr_path(path, attributes)
         if path.size > _ct.max_join_tables
           return _ct.find_by_large_path(path, attributes, parent_id)
@@ -120,8 +143,8 @@ module ClosureTree
         last_joined_table = _ct.table_name
         path.reverse.each_with_index do |ea, idx|
           next_joined_table = "p#{idx}"
-          scope = scope.joins(<<-SQL.strip_heredoc)
-            INNER JOIN #{_ct.quoted_table_name} AS #{next_joined_table}
+          scope = scope.joins(<<-SQL.squish)
+            INNER JOIN #{_ct.quoted_table_name} #{ _ct.t_alias_keyword } #{next_joined_table}
               ON #{next_joined_table}.#{_ct.quoted_id_column_name} =
  #{connection.quote_table_name(last_joined_table)}.#{_ct.quoted_parent_column_name}
           SQL

data/lib/closure_tree/has_closure_tree.rb

@@ -8,6 +8,8 @@ module ClosureTree
         :hierarchy_table_name,
         :name_column,
         :order,
+        :dont_order_roots,
+        :numeric_order,
         :touch,
         :with_advisory_lock
       )
@@ -29,6 +31,8 @@ module ClosureTree
 
       include ClosureTree::DeterministicOrdering if _ct.order_option?
       include ClosureTree::NumericDeterministicOrdering if _ct.order_is_numeric?
+
+      connection_pool.release_connection
     rescue StandardError => e
       raise e unless ClosureTree.configuration.database_less
     end

data/lib/closure_tree/has_closure_tree_root.rb

@@ -1,15 +1,11 @@
 module ClosureTree
   class MultipleRootError < StandardError; end
+  class RootOrderingDisabledError < StandardError; end
 
   module HasClosureTreeRoot
 
     def has_closure_tree_root(assoc_name, options = {})
-      options.assert_valid_keys(
-        :class_name,
-        :foreign_key
-      )
-
-      options[:class_name] ||= assoc_name.to_s.sub(/\Aroot_/, "").classify
+       options[:class_name] ||= assoc_name.to_s.sub(/\Aroot_/, "").classify
       options[:foreign_key] ||= self.name.underscore << "_id"
 
       has_one assoc_name, -> { where(parent: nil) }, options
@@ -81,6 +77,8 @@ module ClosureTree
 
         @closure_tree_roots[assoc_name][assoc_map] = root
       end
+
+      connection_pool.release_connection
     end
   end
 end

data/lib/closure_tree/hash_tree_support.rb

@@ -4,17 +4,17 @@ module ClosureTree
         # Deepest generation, within limit, for each descendant
         # NOTE: Postgres requires HAVING clauses to always contains aggregate functions (!!)
         having_clause = limit_depth ? "HAVING MAX(generations) <= #{limit_depth - 1}" : ''
-        generation_depth = <<-SQL.strip_heredoc
+        generation_depth = <<-SQL.squish
           INNER JOIN (
             SELECT descendant_id, MAX(generations) as depth
             FROM #{quoted_hierarchy_table_name}
             GROUP BY descendant_id
             #{having_clause}
-          ) AS generation_depth
+          ) #{ t_alias_keyword } generation_depth
             ON #{quoted_table_name}.#{model_class.primary_key} = generation_depth.descendant_id
         SQL
         scope_with_order(scope.joins(generation_depth), 'generation_depth.depth')
-      end
+    end
 
     def hash_tree(tree_scope, limit_depth = nil)
       limited_scope = limit_depth ? tree_scope.where("#{quoted_hierarchy_table_name}.generations <= #{limit_depth - 1}") : tree_scope
@@ -33,4 +33,4 @@ module ClosureTree
       tree
     end
   end
-end
+end