ancestry 4.3.3 → 5.1.0

data/README.md

@@ -37,7 +37,7 @@ materialized path, closure tree table, adjacency lists, nested sets, and adjacen
 - Integrity restoration
 - Most queries use indexes on `id` or `ancestry` column. (e.g.: `LIKE '#{ancestry}/%'`)
 
-Since a Btree index has a limitaton of 2704 characters for the `ancestry` column,
+Since a Btree index has a limitation of 2704 characters for the `ancestry` column,
 the maximum depth of an ancestry tree is 900 items at most. If ids are 4 digits long,
 then the max depth is 540 items.
 
@@ -46,8 +46,10 @@ When using `STI` all classes are returned from the scopes unless you specify oth
 ## Supported Rails versions
 
 - Ancestry 2.x supports Rails 4.1 and earlier
-- Ancestry 3.x supports Rails 5.0 and 4.2
-- Ancestry 4.x only supports rails 5.2 and higher
+- Ancestry 3.x supports Rails 4.2 and 5.0
+- Ancestry 4.x supports Rails 5.2 through 7.0
+- Ancestry 5.0 supports Rails 6.0 and higher  
+  Rails 5.2 with `update_strategy=ruby` is still being tested in 5.0.
 
 # Installation
 
@@ -75,7 +77,7 @@ $ rails g migration add_[ancestry]_to_[table] ancestry:string:index
 class AddAncestryToTable < ActiveRecord::Migration[6.1]
   def change
     change_table(:table) do |t|
-      # postgrel
+      # postgres
       t.string "ancestry", collation: 'C', null: false
       t.index "ancestry"
       # mysql
@@ -86,7 +88,7 @@ class AddAncestryToTable < ActiveRecord::Migration[6.1]
 end
 ```
 
-There are additional options for the columns in [Ancestry Database Columnl](#ancestry-database-column) and
+There are additional options for the columns in [Ancestry Database Column](#ancestry-database-column) and
 an explanation for `opclass` and `collation`.
 
 ```bash
@@ -146,10 +148,10 @@ The yellow nodes are those returned by the method.
 | `child_of?`                   |`descendant_of?`                                     |`indirect_of?`                   |
 |**siblings**                   |**subtree**                                          |**path**                         |
 |![siblings](/img/siblings.png) |![subtree](/img/subtree.png)                         |![path](/img/path.png)           |
-| includes self                 |self..indirects                                      |root..self                       |
+| excludes self                 |self..indirects                                      |root..self                       |
 |`sibling_ids`                  |`subtree_ids`                                        |`path_ids`                       |
 |`has_siblings?`                |                                                     |                                 |
-|`sibling_of?(node)`            |                                                     |                                 |
+|`sibling_of?(node)`            |`in_subtree_of?`                                     |                                 |
 
 When using `STI` all classes are returned from the scopes unless you specify otherwise using `where(:type => "ChildClass")`.
 
@@ -162,34 +164,35 @@ The `has_ancestry` method supports the following options:
     :ancestry_column       Column name to store ancestry
                            'ancestry' (default)
     :ancestry_format       Format for ancestry column (see Ancestry Formats section):
-                           :materialized_path (default)     1/2/3, root nodes ancestry=nil
-                           :materialized_path2 (preferred) /1/2/3/, root nodes ancestry=/
-    :orphan_strategy       Instruct Ancestry what to do with children of a node that is destroyed:
+                           :materialized_path   1/2/3, root nodes ancestry=nil (default)
+                           :materialized_path2  /1/2/3/, root nodes ancestry=/ (preferred)
+    :orphan_strategy       How to handle children of a destroyed node:
                            :destroy   All children are destroyed as well (default)
                            :rootify   The children of the destroyed node become root nodes
                            :restrict  An AncestryException is raised if any children exist
                            :adopt     The orphan subtree is added to the parent of the deleted node
                                       If the deleted node is Root, then rootify the orphan subtree
-    :cache_depth           Cache the depth of each node (See Depth Cache section)
-                           false (default)
-
-    :depth_cache_column    column name to store depth cache
-                           'ancestry_depth' (default)
-    :primary_key_format    regular expression that matches the format of the primary key
-                           '[0-9]+'           (default) integer ids
-                           '[-A-Fa-f0-9]{36}'           UUIDs
-    :touch                 Instruct Ancestry to touch the ancestors of a node when it changes
-                           false (default) don't invalide nested key-based caches
-    :counter_cache         Whether to create counter cache column accessor.
-                           false (default) don't store a counter cache
-                           true            store counter cache in `children_count`.
-                           String          name of column to store counter cache.
-    :update_strategy       Choose the strategy to update descendants nodes
-                           :ruby (default) All descendants are updated using the ruby algorithm.
-                                           This triggers update callbacks for each descendant node
-                           :sql            All descendants are updated using a single SQL statement.
-                                           This strategy does not trigger update callbacks for the descendants.
-                                           This strategy is available only for PostgreSql implementations
+                           :none      skip this logic. (add your own `before_destroy`)
+    :cache_depth           Cache the depth of each node: (See Depth Cache section)
+                           false   Do not cache depth (default)
+                           true    Cache depth in 'ancestry_depth'
+                           String  Cache depth in the column referenced
+    :primary_key_format    Regular expression that matches the format of the primary key:
+                           '[0-9]+'            integer ids (default)
+                           '[-A-Fa-f0-9]{36}'  UUIDs
+    :touch                 Touch the ancestors of a node when it changes:
+                           false  don't invalid nested key-based caches (default)
+                           true   touch all ancestors of previous and new parents
+    :counter_cache         Create counter cache column accessor:
+                           false  don't store a counter cache (default)
+                           true   store counter cache in `children_count`.
+                           String name of column to store counter cache.
+    :update_strategy       How to update descendants nodes:
+                           :ruby  All descendants are updated using the ruby algorithm. (default)
+                                  This triggers update callbacks for each descendant node
+                           :sql   All descendants are updated using a single SQL statement.
+                                  This strategy does not trigger update callbacks for the descendants.
+                                  This strategy is available only for PostgreSql implementations
 
 Legacy configuration using `acts_as_tree` is still available. Ancestry defers to `acts_as_tree` if that gem is installed.
 
@@ -302,10 +305,10 @@ Sorry, using collation or index operator classes makes this a little complicated
 root of the issue is that in order to use indexes, the ancestry column needs to
 compare strings using ascii rules.
 
-It is well known that `LIKE '/1/2/%'` will use an index because the wildchard (i.e.: `%`)
+It is well known that `LIKE '/1/2/%'` will use an index because the wildcard (i.e.: `%`)
 is on the right hand side of the `LIKE`. While that is true for ascii strings, it is not
 necessarily true for unicode. Since ancestry only uses ascii characters, telling the database
-this constraint will optimize the `LIKE` statemens.
+this constraint will optimize the `LIKE` statements.
 
 ## Collation Sorting
 
@@ -326,7 +329,7 @@ remember to drop existing indexes on the `ancestry` column and recreate them.
 ## ancestry_format materialized_path and nulls
 
 If you are using the legacy `ancestry_format` of `:materialized_path`, then you need to the
-collum to allow `nulls`. Change the column create accordingly: `null: true`.
+column to allow `nulls`. Change the column create accordingly: `null: true`.
 
 Chances are, you can ignore this section as you most likely want to use `:materialized_path2`.
 
@@ -370,11 +373,11 @@ You may be able to alter the database to gain some readability:
 ALTER DATABASE dbname SET bytea_output to 'escape';
 ```
 
-## Mysql Storage options
+## MySQL Storage options
 
 ### ascii field collation
 
-The currently suggested way to create a postgres field is using `'C'` collation:
+The currently suggested way to create a MySQL field is using `'utf8mb4_bin'` collation:
 
 ```ruby
 t.string "ancestry", collation: 'utf8mb4_bin', null: false
@@ -399,7 +402,7 @@ t.index  "ancestry"
 
 ### ascii character set
 
-Mysql supports per column character sets. Using a character set of `ascii` will
+MySQL supports per column character sets. Using a character set of `ascii` will
 set this up.
 
 ```SQL
@@ -422,7 +425,7 @@ You can choose from 2 ancestry formats:
 ```
 
 If you are unsure, choose `:materialized_path2`. It allows a not NULL column,
-faster descenant queries, has one less `OR` statement in the queries, and
+faster descendant queries, has one less `OR` statement in the queries, and
 the path can be formed easily in a database query for added benefits.
 
 There is more discussion in [Internals](#internals) or [Migrating ancestry format](#migrate-ancestry-format)
@@ -459,7 +462,7 @@ Model.check_ancestry_integrity!
 ```
 
 It is time to run your code. Most tree methods should work fine with ancestry
-and hopefully your tests only require a few minor tweaks to get up and runnnig.
+and hopefully your tests only require a few minor tweaks to get up and running.
 
 Once you are happy with how your app is running, remove the old `parent_id` column:
 
@@ -488,7 +491,7 @@ To add depth_caching to an existing model:
 ## Add column
 
 ```ruby
-class AddDepthCachToTable < ActiveRecord::Migration[6.1]
+class AddDepthCacheToTable < ActiveRecord::Migration[6.1]
   def change
     change_table(:table) do |t|
       t.integer "ancestry_depth", default: 0
@@ -503,7 +506,7 @@ end
 # app/models/[model.rb]
 
 class [Model] < ActiveRecord::Base
-   has_ancestry depth_cache: true
+   has_ancestry cache_depth: true
 end
 ```
 
@@ -516,6 +519,19 @@ Some use migrations, but that can make the migration suite fragile. The command
 Model.rebuild_depth_cache!
 ```
 
+## Depth Constraints
+
+You can use standard Rails validations on your depth cache column to restrict the depth of your tree. For example, to ensure no nodes are deeper than 2:
+
+```ruby
+class TreeNode < ActiveRecord::Base
+  has_ancestry cache_depth: true
+  validates :ancestry_depth, numericality: { less_than_or_equal_to: 2 }
+end
+```
+
+Ancestry will automatically validate not just the node itself, but also ensure that moving a subtree does not cause any of its descendants to exceed the maximum depth.
+
 # Running Tests
 
 ```bash

data/lib/ancestry/class_methods.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module Ancestry
   module ClassMethods
     # Fetch tree node if necessary
-    def to_node object
-      if object.is_a?(self.ancestry_base_class)
+    def to_node(object)
+      if object.is_a?(ancestry_base_class)
         object
       else
         unscoped_where { |scope| scope.find(object.try(primary_key) || object) }
@@ -10,55 +12,57 @@ module Ancestry
     end
 
     # Scope on relative depth options
-    def scope_depth depth_options, depth
-      depth_options.inject(self.ancestry_base_class) do |scope, option|
+    def scope_depth(depth_options, depth)
+      depth_options.inject(ancestry_base_class) do |scope, option|
         scope_name, relative_depth = option
         if [:before_depth, :to_depth, :at_depth, :from_depth, :after_depth].include? scope_name
           scope.send scope_name, depth + relative_depth
         else
-          raise Ancestry::AncestryException.new(I18n.t("ancestry.unknown_depth_option", scope_name: scope_name))
+          raise Ancestry::AncestryException, I18n.t("ancestry.unknown_depth_option", scope_name: scope_name)
         end
       end
     end
 
-    # Orphan strategy writer
-    def orphan_strategy= orphan_strategy
-      # Check value of orphan strategy, only rootify, adopt, restrict or destroy is allowed
-      if [:rootify, :adopt, :restrict, :destroy].include? orphan_strategy
-        class_variable_set :@@orphan_strategy, orphan_strategy
-      else
-        raise Ancestry::AncestryException.new(I18n.t("ancestry.invalid_orphan_strategy"))
-      end
-    end
-
-
     # these methods arrange an entire subtree into nested hashes for easy navigation after database retrieval
     # the arrange method also works on a scoped class
     # the arrange method takes ActiveRecord find options
     # To order your hashes pass the order to the arrange method instead of to the scope
 
     # Get all nodes and sort them into an empty hash
-    def arrange options = {}
+    def arrange(options = {})
       if (order = options.delete(:order))
-        arrange_nodes self.ancestry_base_class.order(order).where(options)
+        arrange_nodes(ancestry_base_class.order(order).where(options))
       else
-        arrange_nodes self.ancestry_base_class.where(options)
+        arrange_nodes(ancestry_base_class.where(options))
       end
     end
 
     # arranges array of nodes to a hierarchical hash
     #
     # @param nodes [Array[Node]] nodes to be arranged
+    # @param orphan_strategy [Symbol]  :rootify or :destroy (default: :rootify)
     # @returns Hash{Node => {Node => {}, Node => {}}}
     # If a node's parent is not included, the node will be included as if it is a top level node
-    def arrange_nodes(nodes)
+    def arrange_nodes(nodes, orphan_strategy: :rootify)
       node_ids = Set.new(nodes.map(&:id))
       index = Hash.new { |h, k| h[k] = {} }
 
       nodes.each_with_object({}) do |node, arranged|
-        children = index[node.id]
-        index[node.parent_id][node] = children
-        arranged[node] = children unless node_ids.include?(node.parent_id)
+        index[node.parent_id][node] = children = index[node.id]
+        if node.parent_id.nil?
+          arranged[node] = children
+        elsif !node_ids.include?(node.parent_id)
+          case orphan_strategy
+          when :destroy
+             # All children are destroyed as well (default)
+          when :adopt
+            raise ArgumentError, "Not Implemented"
+          when :rootify
+            arranged[node] = children
+          when :restrict
+            raise Ancestry::AncestryException, I18n.t("ancestry.cannot_delete_descendants")
+          end
+        end
       end
     end
 
@@ -74,10 +78,10 @@ module Ancestry
       nodes
     end
 
-     # Arrangement to nested array for serialization
-     # You can also supply your own serialization logic using blocks
-     # also allows you to pass the order just as you can pass it to the arrange method
-    def arrange_serializable options={}, nodes=nil, &block
+    # Arrangement to nested array for serialization
+    # You can also supply your own serialization logic using blocks
+    # also allows you to pass the order just as you can pass it to the arrange method
+    def arrange_serializable(options = {}, nodes = nil, &block)
       nodes = arrange(options) if nodes.nil?
       nodes.map do |parent, children|
         if block_given?
@@ -89,13 +93,13 @@ module Ancestry
     end
 
     def tree_view(column, data = nil)
-      data = arrange unless data
+      data ||= arrange
       data.each do |parent, children|
         if parent.depth == 0
           puts parent[column]
         else
           num = parent.depth - 1
-          indent = "   "*num
+          indent = "   " * num
           puts " #{"|" if parent.depth > 1}#{indent}|_ #{parent[column]}"
         end
         tree_view(column, children) if children
@@ -105,12 +109,16 @@ module Ancestry
     # Pseudo-preordered array of nodes.  Children will always follow parents,
     # This is deterministic unless the parents are missing *and* a sort block is specified
     def sort_by_ancestry(nodes, &block)
+      _sort_by_ancestry(nodes, ancestry_column, &block)
+    end
+
+    def _sort_by_ancestry(nodes, column, &block)
       arranged = nodes if nodes.is_a?(Hash)
 
       unless arranged
         presorted_nodes = nodes.sort do |a, b|
-          rank = (a.public_send(ancestry_column) || ' ') <=> (b.public_send(ancestry_column) || ' ')
-          rank = yield(a, b) if rank == 0 && block_given?
+          rank = (a.public_send(column) || ' ') <=> (b.public_send(column) || ' ')
+          rank = block.call(a, b) if rank == 0 && block
           rank
         end
 
@@ -124,48 +132,47 @@ module Ancestry
     # compromised tree integrity is unlikely without explicitly setting cyclic parents or invalid ancestry and circumventing validation
     # just in case, raise an AncestryIntegrityException if issues are detected
     # specify :report => :list to return an array of exceptions or :report => :echo to echo any error messages
-    def check_ancestry_integrity! options = {}
+    def check_ancestry_integrity!(options = {})
+      _check_ancestry_integrity!(ancestry_column, options)
+    end
+
+    def _check_ancestry_integrity!(column, options = {})
       parents = {}
       exceptions = [] if options[:report] == :list
 
       unscoped_where do |scope|
         # For each node ...
         scope.find_each do |node|
-          begin
-            # ... check validity of ancestry column
-            if !node.sane_ancestor_ids?
-              raise Ancestry::AncestryIntegrityException.new(I18n.t("ancestry.invalid_ancestry_column",
-                                                                    :node_id => node.id,
-                                                                    :ancestry_column => "#{node.read_attribute node.ancestry_column}"
-                                                                    ))
-            end
-            # ... check that all ancestors exist
-            node.ancestor_ids.each do |ancestor_id|
-              unless exists? ancestor_id
-                raise Ancestry::AncestryIntegrityException.new(I18n.t("ancestry.reference_nonexistent_node",
-                                                                      :node_id => node.id,
-                                                                      :ancestor_id => ancestor_id
-                                                                      ))
-              end
-            end
-            # ... check that all node parents are consistent with values observed earlier
-            node.path_ids.zip([nil] + node.path_ids).each do |node_id, parent_id|
-              parents[node_id] = parent_id unless parents.has_key? node_id
-              unless parents[node_id] == parent_id
-                raise Ancestry::AncestryIntegrityException.new(I18n.t("ancestry.conflicting_parent_id",
-                                                                      :node_id => node_id,
-                                                                      :parent_id => parent_id || 'nil',
-                                                                      :expected => parents[node_id] || 'nil'
-                                                                      ))
-              end
+          # ... check validity of ancestry column
+          if !node.sane_ancestor_ids?
+            raise Ancestry::AncestryIntegrityException, I18n.t("ancestry.invalid_ancestry_column",
+                                                               :node_id => node.id,
+                                                               :ancestry_column => node.read_attribute(column))
+          end
+          # ... check that all ancestors exist
+          node.ancestor_ids.each do |ancestor_id|
+            unless exists?(ancestor_id)
+              raise Ancestry::AncestryIntegrityException, I18n.t("ancestry.reference_nonexistent_node",
+                                                                 :node_id => node.id,
+                                                                 :ancestor_id => ancestor_id)
             end
-          rescue Ancestry::AncestryIntegrityException => integrity_exception
-            case options[:report]
-              when :list then exceptions << integrity_exception
-              when :echo then puts integrity_exception
-              else raise integrity_exception
+          end
+          # ... check that all node parents are consistent with values observed earlier
+          node.path_ids.zip([nil] + node.path_ids).each do |node_id, parent_id|
+            parents[node_id] = parent_id unless parents.key?(node_id)
+            unless parents[node_id] == parent_id
+              raise Ancestry::AncestryIntegrityException, I18n.t("ancestry.conflicting_parent_id",
+                                                                 :node_id => node_id,
+                                                                 :parent_id => parent_id || 'nil',
+                                                                 :expected => parents[node_id] || 'nil')
             end
           end
+        rescue Ancestry::AncestryIntegrityException => e
+          case options[:report]
+          when :list then exceptions << e
+          when :echo then puts e
+          else raise e
+          end
         end
       end
       exceptions if options[:report] == :list
@@ -175,7 +182,7 @@ module Ancestry
     def restore_ancestry_integrity!
       parent_ids = {}
       # Wrap the whole thing in a transaction ...
-      self.ancestry_base_class.transaction do
+      ancestry_base_class.transaction do
         unscoped_where do |scope|
           # For each node ...
           scope.find_each do |node|
@@ -212,7 +219,7 @@ module Ancestry
     end
 
     # Build ancestry from parent ids for migration purposes
-    def build_ancestry_from_parent_ids! column=:parent_id, parent_id = nil, ancestor_ids = []
+    def build_ancestry_from_parent_ids!(column = :parent_id, parent_id = nil, ancestor_ids = [])
       unscoped_where do |scope|
         scope.where(column => parent_id).find_each do |node|
           node.without_ancestry_callbacks do
@@ -225,9 +232,9 @@ module Ancestry
 
     # Rebuild depth cache if it got corrupted or if depth caching was just turned on
     def rebuild_depth_cache!
-      raise Ancestry::AncestryException.new(I18n.t("ancestry.cannot_rebuild_depth_cache")) unless respond_to? :depth_cache_column
+      raise(Ancestry::AncestryException, I18n.t("ancestry.cannot_rebuild_depth_cache")) unless respond_to?(:depth_cache_column)
 
-      self.ancestry_base_class.transaction do
+      ancestry_base_class.transaction do
         unscoped_where do |scope|
           scope.find_each do |node|
             node.update_attribute depth_cache_column, node.depth
@@ -236,8 +243,37 @@ module Ancestry
       end
     end
 
+    # NOTE: this is temporarily kept separate from rebuild_depth_cache!
+    # this will become the implementation of rebuild_depth_cache!
+    def rebuild_depth_cache_sql!
+      update_all("#{depth_cache_column} = #{ancestry_depth_sql}")
+    end
+
+    def rebuild_counter_cache!
+      if %w(mysql mysql2).include?(connection.adapter_name.downcase)
+        connection.execute %{
+          UPDATE #{table_name} AS dest
+          LEFT JOIN (
+            SELECT #{table_name}.#{primary_key}, COUNT(*) AS child_count
+            FROM #{table_name}
+            JOIN #{table_name} children ON children.#{ancestry_column} = (#{child_ancestry_sql})
+            GROUP BY #{table_name}.#{primary_key}
+          ) src USING(#{primary_key})
+          SET dest.#{counter_cache_column} = COALESCE(src.child_count, 0)
+        }
+      else
+        update_all %{
+          #{counter_cache_column} = (
+            SELECT COUNT(*)
+            FROM #{table_name} children
+            WHERE children.#{ancestry_column} = (#{child_ancestry_sql})
+          )
+        }
+      end
+    end
+
     def unscoped_where
-      yield self.ancestry_base_class.default_scoped.unscope(:where)
+      yield ancestry_base_class.default_scoped.unscope(:where)
     end
 
     ANCESTRY_UNCAST_TYPES = [:string, :uuid, :text].freeze

data/lib/ancestry/exceptions.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Ancestry
   class AncestryException < RuntimeError
   end
 
   class AncestryIntegrityException < AncestryException
   end
-end
+end