closure_tree 6.3.0 → 6.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 06cbb37da1e1592760ad47995f099a8f69be5d81
-  data.tar.gz: a9e2ece8d7e792b0cb97378c9885b9201e654bbb
+  metadata.gz: c6312f8ac4880ea36a31ef47a6c1d851307ee5b9
+  data.tar.gz: 431fe393f396890c009da5f4a74e402db077a4a8
 SHA512:
-  metadata.gz: 1ca685fbfaf26efad13f7633039553940d7655fe73d83e2c5e0d2b3b00f2905de07b648026e8d093b59c43082f14e7e3bbc87c963c3933dff46b12c54311673b
-  data.tar.gz: 0bed535b6c550b3b6fa09aa40de17d82c022e8997914e98cf4ba1ba436a9d6f453a41e549831a10e50a8836365acccf9e5201105b44a8cbfdf297445e267f5a5
+  metadata.gz: 4e54d08cac5aebf07217e42beb28c35fd6f2487751481f9828537097f401f73b106756a6c511ad4b5cd2adec9235fa1319e77f85093be6b9e88313e44219f604
+  data.tar.gz: 0c98c0c6fc5f27aed4a9d1ebe7e2012356ef0d305fee0a06a941322c9509d78dcf9739a72d135a0414ed1a49c7ded4f9f308e00e9f8a86b015829ea9b498d3b6

data/.travis.yml

@@ -2,14 +2,14 @@ cache: bundler
 sudo: false
 language: ruby
 rvm:
-  - 2.3.1
-  - 2.2.5
+  - 2.4.0
+  - 2.3.3
+  - 2.2.6
 # these haven't been passing for a while:
 #  - jruby-head
 #  - rbx
 
 gemfile:
-  - gemfiles/activerecord_4.1.gemfile
   - gemfiles/activerecord_4.2.gemfile
   - gemfiles/activerecord_5.0_foreigner.gemfile
   - gemfiles/activerecord_5.0.gemfile

data/Appraisals

@@ -1,10 +1,3 @@
-appraise 'activerecord-4.1' do
-  gem 'activerecord', '~> 4.1.0'
-  gem 'foreigner'
-  platforms :ruby, :rbx do
-    gem 'mysql2', '~> 0.3.20'
-  end
-end
 
 appraise 'activerecord-4.2' do
   gem 'activerecord', '~> 4.2.0'

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+### 6.4.0
+
+* Merged [PR 236](https://github.com/mceachen/closure_tree/pull/236) which adds documentation for `has_closure_tree_root`.
+* Added ruby 2.4 and dropped Rails 4.1 from the build matrix.
+
 ### 6.3.0
 
 * `prepend_child` [handles invalid children properly now](https://github.com/mceachen/closure_tree/issues/249).

data/README.md

@@ -27,7 +27,7 @@ closure_tree has some great features:
   * 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.1, 4.2 and 5.0__
+* __Support for ActiveRecord 4.2 and 5.0__
 * __Support for Ruby 2.2 and 2.3__
 * Support for reparenting children (and all their descendants)
 * Support for [single-table inheritance (STI)](#sti) within the hierarchy
@@ -58,7 +58,7 @@ for a description of different tree storage algorithms.
 
 Note that closure_tree only supports ActiveRecord 4.1 and later, and has test coverage for MySQL, PostgreSQL, and SQLite.
 
-1.  Add `gem 'closure_tree'` to your Gemfile 
+1.  Add `gem 'closure_tree'` to your Gemfile
 
 2.  Run `bundle install`
 
@@ -75,7 +75,7 @@ Note that closure_tree only supports ActiveRecord 4.1 and later, and has test co
     ```
 
     Make sure you check out the [large number 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.**
 
@@ -115,9 +115,9 @@ NOTE: Run `rails g closure_tree:config` to create an initializer with extra
 
 ## Warning
 
-As stated above, using multiple hierarchy gems (like `ancestry` or `nested set`) on the same model 
+As stated above, using multiple hierarchy gems (like `ancestry` or `nested set`) on the same model
 will most likely result in pain, suffering, hair loss, tooth decay, heel-related ailments, and gingivitis.
-Assume things will break. 
+Assume things will break.
 
 ## Usage
 
@@ -169,7 +169,7 @@ child1.ancestry_path
 
 You can `find` as well as `find_or_create` by "ancestry paths".
 
-If you provide an array of strings to these methods, they reference the `name` column in your 
+If you provide an array of strings to these methods, they reference the `name` column in your
 model, which can be overridden with the `:name_column` option provided to `has_closure_tree`.
 
 ```ruby
@@ -256,6 +256,45 @@ 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)
 
+### Eager loading
+
+Since most of closure_tree's methods (e.g. `children`) return regular `ActiveRecord` scopes, you can use the `includes` method for eager loading, e.g.
+
+```ruby
+comment.children.includes(:author)
+```
+
+However, note that the above approach only eager loads the requested associations for the immediate children of `comment`. If you want to walk through the entire tree, you may still end up making many queries and loading duplicate copies of objects.
+
+In some cases, a viable alternative is the following:
+
+```ruby
+comment.self_and_descendants.includes(:author)
+```
+
+This would load authors for `comment` and all its descendants in a constant number of queries. However, the return value is an array of `Comment`s, and the tree structure is thus lost, which makes it difficult to walk the tree using elegant recursive algorithms.
+
+A third option is to use `has_closure_tree_root` on the model that is composed by the closure_tree model (e.g. a `Post` may be composed by a tree of `Comment`s). So in `post.rb`, you would do:
+
+```ruby
+# app/models/post.rb
+has_closure_tree_root :root_comment
+```
+
+This gives you a plain `has_one` association (`root_comment`) to the root `Comment` (i.e. that with null `parent_id`).
+
+It also gives you a method called `root_comment_including_tree`, which you can invoke as follows:
+
+```ruby
+a_post.root_comment_including_tree(:author)
+```
+
+The result of this call will be the root `Comment` with all descendants _and_ associations loaded in a constant number of queries. Inverse associations are also setup on all nodes, so as you walk the tree, calling `children` or `parent` on any node will _not_ trigger any further queries and no duplicate copies of objects are loaded into memory.
+
+The class and foreign key of `root_comment` are assumed to be `Comment` and `post_id`, respectively. These can be overridden in the usual way.
+
+The same caveat stated above with `hash_tree` also applies here: this method will load the entire tree into memory. If the tree is very large, this may be a bad idea, in which case using the eager loading methods above may be preferred.
+
 ### Graph visualization
 
 ```to_dot_digraph``` is suitable for passing into [Graphviz](http://www.graphviz.org/).
@@ -473,7 +512,7 @@ Yup! [Ilya Bodrov](https://github.com/bodrovis) wrote [Nested Comments with Rail
 
 ### Can I update parentage with `update_attribute`?
 
-**No.** `update_attribute` skips the validation hook that is required for maintaining the 
+**No.** `update_attribute` skips the validation hook that is required for maintaining the
 hierarchy table.
 
 ### Can I assign a parent to multiple children with  ```#update_all```?

data/gemfiles/activerecord_4.2.gemfile

@@ -5,7 +5,7 @@ source "https://rubygems.org"
 gem "activerecord", "~> 4.2.0"
 
 platforms :ruby, :rbx do
-  gem "mysql2", "~> 0.3.20"
+  gem "mysql2"
   gem "pg"
   gem "sqlite3"
 end

data/lib/closure_tree/has_closure_tree_root.rb

@@ -15,18 +15,16 @@ module ClosureTree
       has_one assoc_name, -> { where(parent: nil) }, options
 
       # Fetches the association, eager loading all children and given associations
-      define_method("#{assoc_name}_including_tree") do |assoc_map_or_reload = nil, assoc_map = nil|
+      define_method("#{assoc_name}_including_tree") do |*args|
         reload = false
-        if assoc_map_or_reload.is_a?(::Hash)
-          assoc_map = assoc_map_or_reload
-        else
-          reload = assoc_map_or_reload
-        end
+        reload = args.shift if args && (args.first == true || args.first == false)
+        assoc_map = args
+        assoc_map = [nil] if assoc_map.blank?
 
+        # Memoize
+        @closure_tree_roots ||= {}
+        @closure_tree_roots[assoc_name] ||= {}
         unless reload
-          # Memoize
-          @closure_tree_roots ||= {}
-          @closure_tree_roots[assoc_name] ||= {}
           if @closure_tree_roots[assoc_name].has_key?(assoc_map)
             return @closure_tree_roots[assoc_name][assoc_map]
           end
@@ -52,7 +50,7 @@ module ClosureTree
 
         # Fetch all descendants in constant number of queries.
         # This is the last query-triggering statement in the method.
-        temp_root.self_and_descendants.includes(assoc_map).each do |node|
+        temp_root.self_and_descendants.includes(*assoc_map).each do |node|
           id_hash[node.id] = node
           parent_node = id_hash[node[parent_col_id]]
 

data/lib/closure_tree/version.rb

@@ -1,3 +1,3 @@
 module ClosureTree
-  VERSION = Gem::Version.new('6.3.0')
+  VERSION = Gem::Version.new('6.4.0')
 end

data/spec/db/schema.rb

@@ -71,6 +71,7 @@ ActiveRecord::Schema.define(:version => 0) do
   create_table "contracts" do |t|
     t.integer "user_id", :null => false
     t.integer "contract_type_id"
+    t.string "title"
   end
 
   create_table "contract_types" do |t|

data/spec/has_closure_tree_root_spec.rb

@@ -26,18 +26,36 @@ describe "has_closure_tree_root" do
     user3.children << user5
     user3.children << user6
 
-    user1.contracts.create!(contract_type: ct1)
-    user2.contracts.create!(contract_type: ct1)
-    user3.contracts.create!(contract_type: ct1)
-    user3.contracts.create!(contract_type: ct2)
-    user4.contracts.create!(contract_type: ct2)
-    user5.contracts.create!(contract_type: ct1)
-    user6.contracts.create!(contract_type: ct2)
+    user1.contracts.create!(title: "Contract 1", contract_type: ct1)
+    user2.contracts.create!(title: "Contract 2", contract_type: ct1)
+    user3.contracts.create!(title: "Contract 3", contract_type: ct1)
+    user3.contracts.create!(title: "Contract 4", contract_type: ct2)
+    user4.contracts.create!(title: "Contract 5", contract_type: ct2)
+    user5.contracts.create!(title: "Contract 6", contract_type: ct1)
+    user6.contracts.create!(title: "Contract 7", contract_type: ct2)
   end
 
   context "with basic config" do
     let!(:group) { Group.create!(name: "TheGroup") }
 
+    it "loads all nodes in a constant number of queries" do
+      expect do
+        root = group_reloaded.root_user_including_tree
+        expect(root.children[0].email).to eq "2@example.com"
+        expect(root.children[0].parent.children[1].email).to eq "3@example.com"
+      end.to_not exceed_query_limit(2)
+    end
+
+    it "loads all nodes plus single association in a constant number of queries" do
+      expect do
+        root = group_reloaded.root_user_including_tree(:contracts)
+        expect(root.children[0].email).to eq "2@example.com"
+        expect(root.children[0].parent.children[1].email).to eq "3@example.com"
+        expect(root.children[0].children[0].contracts[0].user.
+          parent.parent.children[1].children[1].contracts[0].title).to eq "Contract 7"
+      end.to_not exceed_query_limit(3)
+    end
+
     it "loads all nodes and associations in a constant number of queries" do
       expect do
         root = group_reloaded.root_user_including_tree(contracts: :contract_type)
@@ -66,6 +84,10 @@ describe "has_closure_tree_root" do
         to eq "1@example.com"
     end
 
+    it "works if true passed on first call" do
+      expect(group_reloaded.root_user_including_tree(true).email).to eq "1@example.com"
+    end
+
     it "eager loads inverse association to group" do
       expect do
         root = group_reloaded.root_user_including_tree

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: closure_tree
 version: !ruby/object:Gem::Version
-  version: 6.3.0
+  version: 6.4.0
 platform: ruby
 authors:
 - Matthew McEachen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-08 00:00:00.000000000 Z
+date: 2017-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -140,7 +140,6 @@ files:
 - README.md
 - Rakefile
 - closure_tree.gemspec
-- gemfiles/activerecord_4.1.gemfile
 - gemfiles/activerecord_4.2.gemfile
 - gemfiles/activerecord_5.0.gemfile
 - gemfiles/activerecord_5.0_foreigner.gemfile

data/gemfiles/activerecord_4.1.gemfile

@@ -1,20 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "activerecord", "~> 4.1.0"
-gem "foreigner"
-
-platforms :ruby, :rbx do
-  gem "mysql2", "~> 0.3.20"
-  gem "pg"
-  gem "sqlite3"
-end
-
-platforms :jruby do
-  gem "activerecord-jdbcmysql-adapter"
-  gem "activerecord-jdbcpostgresql-adapter"
-  gem "activerecord-jdbcsqlite3-adapter"
-end
-
-gemspec :path => "../"