acts_as_recursive_tree 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f74110127d12218381c9578cf59546b125dddd7f2f994dcbc8fff16b13f27f9f
-  data.tar.gz: e63babd0dc010e7cded02689cc9fb3ae54f8a9a817de3c00031cbc118e2a652c
+  metadata.gz: 2ce9f3e8c4b5dd8d5e61e04d9234a07920f2063955d134110a40c217950595ea
+  data.tar.gz: baa87fc513a6fd8e49538309b1833e418328b1f7317584fc828d20689cbbd32b
 SHA512:
-  metadata.gz: 3711b930aa6bbb744cdf6ad0e34af98df9065294c0d8d498ec7daafb1ebd8e534acbab8195a5752b47dd1da5650a73e4a2c72d3371d6d2856d885f0cae0d4331
-  data.tar.gz: 3697fb438ee57c0cbb3d652c26278f6bcd016eab1f8c1d1d60cb0b319f74dd1566af889827a1fca7823b201d16a692b32a9411a95a2850e3f582c928f01aa378
+  metadata.gz: 7e21465a62a28f6ca757402689abe0709e131d3104f3334646105af34d594a0704d2aaf54fb72b11cb039fd7436845bec0dd335506ed8f5c48c599f89ae9a502
+  data.tar.gz: 242a7f33a0595155d0fc75eec0f17769ae0d92314db07a6cb5acab96737574498266efb6f2aa8f30af3ef3c9a4b87895cb7ab0ebf75d3d9469173131917a32e1

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+### Version 3.5.0
+- Added :dependent option for setting explicit deletion behaviour (issue #31)
+- Added automatic cycle detection when supported (currently only PostgresSQL 14+) (issue #22)
+
 ### Version 3.4.0
 - Rails 7.1 compatibility
 - Added ar_next to test matrix

data/README.md

@@ -55,18 +55,26 @@ class Node  < ActiveRecord::Base
   recursive_tree
 end
 ```
-That's it. This will assume that your model has a column named `parent_id` which will be used for traversal. If your column is something different, then you can specifiy it in the call to `recursive_tree`:
+That's it. This will assume that your model has a column named `parent_id` which will be used for traversal. If your column is something different, then you can specify it in the call to `recursive_tree`:
 
 ```ruby
 recursive_tree parent_key: :some_other_column
 ```
 
-Some extra special stuff - if your parent relation is also polymorphic, the specify the polymorphic column:
+Some extra special stuff - if your parent relation is also polymorphic, then specify the polymorphic column:
 
 ```ruby
 recursive_tree parent_type_column: :some_other_type_column
 ```
 
+Controlling deletion behaviour:
+
+By default, it is up to the user code to delete all child nodes in a tree when a parent node gets deleted. This can be controlled by the `:dependent` option, which will be set on the `children` association (see [#has_many](https://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#method-i-has_many) in the Rails doc).
+
+```ruby
+recursive_tree dependent: :nullify # or :destroy, etc.
+```
+
 ## Usage
 
 After you set up a model for usage, there are now several methods you can use.
@@ -216,6 +224,15 @@ Instance Methods make no difference of the class from which they are called:
 sub_node_instance.descendants # => returns Node and SubNode instances
 ```
 
+## A note on endless recursion / cycle detection
+
+### Inserting
+As of now it is up to the user code to guarantee there will be no cycles created in the parent/child entries. If not, your DB might run into an endless recursion. Inserting/updating records that will cause a cycle is not prevented by some validation checks, so you have to do this by your own. This might change in a future version.
+
+### Querying
+If you want to make sure to not run into an endless recursion when querying, then there are following options:
+1. Add a maximum depth to the query options. If an cycle is present in your data, the recursion will stop when reaching the max depth and stop further traversing.
+2. When you are on recent version of PostgreSQL (14+) you are lucky. Postgres added the CYCLE detection feature to detect cycles and prevent endless recursion. Our query builder will add this feature if your DB does support this.  
 
 ## Contributing
 

data/lib/acts_as_recursive_tree/acts_macro.rb

@@ -7,13 +7,14 @@ module ActsAsRecursiveTree
     #
     # * <tt>foreign_key</tt> - specifies the column name to use for tracking
     # of the tree (default: +parent_id+)
-    def recursive_tree(parent_key: :parent_id, parent_type_column: nil)
+    def recursive_tree(parent_key: :parent_id, parent_type_column: nil, dependent: nil)
       class_attribute(:_recursive_tree_config, instance_writer: false)
 
       self._recursive_tree_config = Config.new(
         model_class: self,
         parent_key: parent_key.to_sym,
-        parent_type_column: parent_type_column.try(:to_sym)
+        parent_type_column: parent_type_column.try(:to_sym),
+        dependent: dependent
       )
 
       include ActsAsRecursiveTree::Model

data/lib/acts_as_recursive_tree/associations.rb

@@ -16,7 +16,8 @@ module ActsAsRecursiveTree
       has_many :children,
                class_name: base_class.to_s,
                foreign_key: _recursive_tree_config.parent_key,
-               inverse_of: :parent
+               inverse_of: :parent,
+               dependent: _recursive_tree_config.dependent
 
       has_many :self_and_siblings,
                through: :parent,

data/lib/acts_as_recursive_tree/builders/ancestors.rb

@@ -5,7 +5,7 @@ module ActsAsRecursiveTree
     class Ancestors < RelationBuilder
       self.traversal_strategy = ActsAsRecursiveTree::Builders::Strategies::Ancestor
 
-      def get_query_options(_)
+      def get_query_options(&block)
         opts = super
         opts.ensure_ordering!
         opts

data/lib/acts_as_recursive_tree/builders/leaves.rb

@@ -16,7 +16,7 @@ module ActsAsRecursiveTree
         select_manager
       end
 
-      def get_query_options(_)
+      def get_query_options(&_block)
         # do not allow any custom options
         ActsAsRecursiveTree::Options::QueryOptions.new
       end

data/lib/acts_as_recursive_tree/builders/relation_builder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module ActsAsRecursiveTree
   module Builders
     #
@@ -12,40 +14,42 @@ module ActsAsRecursiveTree
 
       class_attribute :traversal_strategy, instance_writer: false
 
-      attr_reader :klass, :ids, :recursive_temp_table, :travers_loc_table, :without_ids
-
-      mattr_reader(:random) { Random.new }
+      attr_reader :klass, :ids, :without_ids
 
       # Delegators for easier accessing config and query options
-      delegate :primary_key, :depth_column, :parent_key, :parent_type_column, to: :@config
+      delegate :primary_key, :depth_column, :parent_key, :parent_type_column, to: :config
       delegate :depth_present?, :depth, :condition, :ensure_ordering, to: :@query_opts
 
       def initialize(klass, ids, exclude_ids: false, &block)
         @klass       = klass
-        @config      = klass._recursive_tree_config
-        @ids         = ActsAsRecursiveTree::Options::Values.create(ids, @config)
+        @ids         = ActsAsRecursiveTree::Options::Values.create(ids, klass._recursive_tree_config)
         @without_ids = exclude_ids
 
-        @query_opts = get_query_options(block)
+        @query_opts = get_query_options(&block)
+
+        # random seed for the temp tables
+        @rand_int = SecureRandom.rand(1_000_000)
+      end
+
+      def recursive_temp_table
+        @recursive_temp_table ||= Arel::Table.new("recursive_#{klass.table_name}_#{@rand_int}_temp")
+      end
+
+      def travers_loc_table
+        @travers_loc_table ||= Arel::Table.new("traverse_#{@rand_int}_loc")
+      end
 
-        rand_int              = random.rand(1_000_000)
-        @recursive_temp_table = Arel::Table.new("recursive_#{klass.table_name}_#{rand_int}_temp")
-        @travers_loc_table    = Arel::Table.new("traverse_#{rand_int}_loc")
+      def config
+        klass._recursive_tree_config
       end
 
       #
       # Constructs a new QueryOptions and yield it to the proc if one is present.
       # Subclasses may override this method to provide sane defaults.
       #
-      # @param proc [Proc] a proc or nil
-      #
       # @return [ActsAsRecursiveTree::Options::QueryOptions] the new QueryOptions instance
-      def get_query_options(proc)
-        opts = ActsAsRecursiveTree::Options::QueryOptions.new
-
-        proc&.call(opts)
-
-        opts
+      def get_query_options(&block)
+        ActsAsRecursiveTree::Options::QueryOptions.from(&block)
       end
 
       def base_table
@@ -71,11 +75,7 @@ module ActsAsRecursiveTree
       end
 
       def create_select_manger(column = nil)
-        projections = if column
-                        travers_loc_table[column]
-                      else
-                        Arel.star
-                      end
+        projections = column ? travers_loc_table[column] : Arel.star
 
         select_mgr = travers_loc_table.project(projections).with(:recursive, build_cte_table)
 
@@ -85,10 +85,24 @@ module ActsAsRecursiveTree
       def build_cte_table
         Arel::Nodes::As.new(
           travers_loc_table,
-          build_base_select.union(build_union_select)
+          add_pg_cycle_detection(
+            build_base_select.union(build_union_select)
+          )
+        )
+      end
+
+      def add_pg_cycle_detection(union_query)
+        return union_query unless config.cycle_detection?
+
+        Arel::Nodes::InfixOperation.new(
+          '',
+          union_query,
+          Arel.sql("CYCLE #{primary_key} SET is_cycle USING path")
         )
       end
 
+      # Builds SQL:
+      # SELECT id, parent_id, 0 AS depth FROM base_table WHERE id = 123
       def build_base_select
         id_node = base_table[primary_key]
 

data/lib/acts_as_recursive_tree/config.rb

@@ -5,13 +5,14 @@ module ActsAsRecursiveTree
   # Stores the configuration of one Model class
   #
   class Config
-    attr_reader :parent_key, :parent_type_column, :depth_column
+    attr_reader :parent_key, :parent_type_column, :depth_column, :dependent
 
-    def initialize(model_class:, parent_key:, parent_type_column:, depth_column: :recursive_depth)
+    def initialize(model_class:, parent_key:, parent_type_column:, depth_column: :recursive_depth, dependent: nil)
       @model_class        = model_class
       @parent_key         = parent_key
       @parent_type_column = parent_type_column
       @depth_column       = depth_column
+      @dependent          = dependent
     end
 
     #
@@ -20,5 +21,15 @@ module ActsAsRecursiveTree
     def primary_key
       @primary_key ||= @model_class.primary_key.to_sym
     end
+
+    #
+    # Checks if SQL cycle detection can be used. This is currently supported only on PostgreSQL 14+.
+    # @return [TrueClass|FalseClass]
+    def cycle_detection?
+      return @cycle_detection if defined?(@cycle_detection)
+
+      @cycle_detection = @model_class.connection.adapter_name == 'PostgreSQL' &&
+                         @model_class.connection.database_version >= 140_000
+    end
   end
 end

data/lib/acts_as_recursive_tree/options/query_options.rb

@@ -5,6 +5,12 @@ module ActsAsRecursiveTree
     class QueryOptions
       STRATEGIES = %i[subselect join].freeze
 
+      def self.from
+        options = new
+        yield(options) if block_given?
+        options
+      end
+
       attr_accessor :condition
       attr_reader :ensure_ordering, :query_strategy
 

data/lib/acts_as_recursive_tree/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActsAsRecursiveTree
-  VERSION = '3.4.0'
+  VERSION = '3.5.0'
 end

data/spec/acts_as_recursive_tree/builders/ancestors_spec.rb

@@ -3,15 +3,15 @@
 require 'spec_helper'
 
 RSpec.describe ActsAsRecursiveTree::Builders::Ancestors do
-  context 'basic' do
+  context 'without additional setup' do
     it_behaves_like 'build recursive query'
     it_behaves_like 'ancestor query'
-    include_context 'context with ordering'
+    include_context 'with ordering'
   end
 
   context 'with options' do
-    include_context 'setup with enforced ordering' do
-      it_behaves_like 'with ordering'
+    include_context 'with enforced ordering setup' do
+      it_behaves_like 'is adding ordering'
     end
   end
 end

data/spec/acts_as_recursive_tree/builders/descendants_spec.rb

@@ -3,16 +3,16 @@
 require 'spec_helper'
 
 RSpec.describe ActsAsRecursiveTree::Builders::Descendants do
-  context 'basic' do
+  context 'without additional setup' do
     it_behaves_like 'build recursive query'
     it_behaves_like 'descendant query'
-    include_context 'context without ordering'
+    include_context 'without ordering'
   end
 
   context 'with options' do
-    include_context 'setup with enforced ordering' do
+    include_context 'with enforced ordering setup' do
       let(:ordering) { true }
-      it_behaves_like 'with ordering'
+      it_behaves_like 'is adding ordering'
     end
   end
 end

data/spec/acts_as_recursive_tree/builders/leaves_spec.rb

@@ -3,16 +3,16 @@
 require 'spec_helper'
 
 RSpec.describe ActsAsRecursiveTree::Builders::Leaves do
-  context 'basic' do
+  context 'without additional setup' do
     it_behaves_like 'build recursive query'
     it_behaves_like 'descendant query'
-    include_context 'context without ordering'
+    include_context 'without ordering'
   end
 
   context 'with options' do
-    include_context 'setup with enforced ordering' do
+    include_context 'with enforced ordering setup' do
       let(:ordering) { true }
-      it_behaves_like 'without ordering'
+      it_behaves_like 'not adding ordering'
     end
   end
 end

data/spec/acts_as_recursive_tree/options/values_spec.rb

@@ -20,13 +20,13 @@ RSpec.describe ActsAsRecursiveTree::Options::Values do
   let(:table) { Arel::Table.new('test_table') }
   let(:attribute) { table['test_attr'] }
 
-  context 'invalid agurment' do
+  context 'with invalid agurment' do
     it 'raises exception' do
       expect { described_class.create(nil) }.to raise_exception(/is not supported/)
     end
   end
 
-  context 'single value' do
+  context 'with single value' do
     let(:single_value) { 3 }
 
     it_behaves_like 'single values' do
@@ -38,8 +38,8 @@ RSpec.describe ActsAsRecursiveTree::Options::Values do
     end
   end
 
-  context 'multi value' do
-    context 'Array' do
+  context 'with multi value' do
+    context 'with Array' do
       subject(:value) { described_class.create(array) }
 
       let(:array) { [1, 2, 3] }
@@ -55,7 +55,7 @@ RSpec.describe ActsAsRecursiveTree::Options::Values do
       end
     end
 
-    context 'Range' do
+    context 'with Range' do
       subject(:value) { described_class.create(range) }
 
       let(:range) { 1..3 }
@@ -71,7 +71,7 @@ RSpec.describe ActsAsRecursiveTree::Options::Values do
       end
     end
 
-    context 'Relation' do
+    context 'with Relation' do
       subject(:value) { described_class.create(relation, double) }
 
       let(:relation) { Node.where(name: 'test') }

data/spec/support/shared_examples/builders.rb

@@ -1,11 +1,13 @@
-RSpec.shared_context 'setup with enforced ordering' do
+# frozen_string_literal: true
+
+RSpec.shared_context 'with enforced ordering setup' do
   let(:ordering) { false }
-  include_context 'base_setup' do
+  include_context 'with base_setup' do
     let(:proc) { ->(config) { config.ensure_ordering! } }
   end
 end
 
-RSpec.shared_context 'base_setup' do
+RSpec.shared_context 'with base_setup' do
   subject(:query) { builder.build.to_sql }
 
   let(:model_id) { 1 }
@@ -32,30 +34,30 @@ RSpec.shared_examples 'basic recursive examples' do
 end
 
 RSpec.shared_examples 'build recursive query' do
-  context 'simple id' do
+  context 'with simple id' do
     context 'with simple class' do
-      include_context 'base_setup' do
+      include_context 'with base_setup' do
         let(:model_class) { Node }
         it_behaves_like 'basic recursive examples'
       end
     end
 
     context 'with class with different parent key' do
-      include_context 'base_setup' do
+      include_context 'with base_setup' do
         let(:model_class) { NodeWithOtherParentKey }
         it_behaves_like 'basic recursive examples'
       end
     end
 
     context 'with Subclass' do
-      include_context 'base_setup' do
+      include_context 'with base_setup' do
         let(:model_class) { Floor }
         it_behaves_like 'basic recursive examples'
       end
     end
 
     context 'with polymorphic parent relation' do
-      include_context 'base_setup' do
+      include_context 'with base_setup' do
         let(:model_class) { NodeWithPolymorphicParent }
         it_behaves_like 'basic recursive examples'
       end
@@ -64,34 +66,34 @@ RSpec.shared_examples 'build recursive query' do
 end
 
 RSpec.shared_examples 'ancestor query' do
-  include_context 'base_setup'
+  include_context 'with base_setup'
 
   it { is_expected.to match(/"#{builder.travers_loc_table.name}"."#{model_class._recursive_tree_config.parent_key}" = "#{model_class.table_name}"."#{model_class.primary_key}"/) }
 end
 
 RSpec.shared_examples 'descendant query' do
-  include_context 'base_setup'
+  include_context 'with base_setup'
 
   it { is_expected.to match(/"#{model_class.table_name}"."#{model_class._recursive_tree_config.parent_key}" = "#{builder.travers_loc_table.name}"."#{model_class.primary_key}"/) }
   it { is_expected.to match(/#{Regexp.escape(builder.travers_loc_table.project(builder.travers_loc_table[model_class.primary_key]).to_sql)}/) }
 end
 
-RSpec.shared_context 'context with ordering' do
-  include_context 'base_setup' do
-    it_behaves_like 'with ordering'
+RSpec.shared_context 'with ordering' do
+  include_context 'with base_setup' do
+    it_behaves_like 'is adding ordering'
   end
 end
 
-RSpec.shared_context 'context without ordering' do
-  include_context 'base_setup' do
-    it_behaves_like 'without ordering'
+RSpec.shared_context 'without ordering' do
+  include_context 'with base_setup' do
+    it_behaves_like 'not adding ordering'
   end
 end
 
-RSpec.shared_examples 'with ordering' do
+RSpec.shared_examples 'is adding ordering' do
   it { is_expected.to match(/ORDER BY #{Regexp.escape(builder.recursive_temp_table[model_class._recursive_tree_config.depth_column].asc.to_sql)}/) }
 end
 
-RSpec.shared_examples 'without ordering' do
+RSpec.shared_examples 'not adding ordering' do
   it { is_expected.not_to match(/ORDER BY/) }
 end

data/spec/support/tree_methods.rb

@@ -3,13 +3,10 @@
 # Helper methods for simple tree creation
 module TreeMethods
   def create_tree(max_level, current_level: 0, node: nil, create_node_info: false, stop_at: -1)
-    node = Node.create!(name: 'root') if node.nil?
+    node ||= Node.create!(name: 'root')
 
     1.upto(max_level - current_level) do |index|
-      child = node.children.create!(
-        name: "child #{index} - level #{current_level}",
-        active: stop_at > current_level
-      )
+      child = node.children.create!(name: "child #{index} - level #{current_level}", active: stop_at > current_level)
 
       child.create_node_info(status: stop_at > current_level ? 'foo' : 'bar') if create_node_info
 
@@ -21,7 +18,6 @@ module TreeMethods
         stop_at: stop_at
       )
     end
-
     node
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acts_as_recursive_tree
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Wolfgang Wedelich-John
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-03-13 00:00:00.000000000 Z
+date: 2023-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord