Add optional validation toggle (#45)

Provide a checks: false option to skip validation checks for performance-
critical paths, propagate the setting to children, and add dedicated tests
plus documentation warnings about the risk.

Author: evolve75

API-CHANGES.md

@@ -30,6 +30,12 @@ smooth transition to the new APIs.
   `to_hash`) to improve interoperability with frameworks such as Rails
   (see #104).
 
+* Added per-tree validation toggles via `checks: false` on `Tree::TreeNode.new`
+  to allow disabling guard checks in performance-critical code paths. This is
+  potentially dangerous and can lead to unexpected behavior if invalid data
+  enters the tree. Only disable checks with clear performance benchmark data
+  supporting the risk (see #45).
+
 ## Release 2.2.0 Changes
 
 * [Tree::TreeNode#add][add] now raises `ArgumentError` when attempting to add

History.md

@@ -22,6 +22,11 @@
 * Accept hash-like inputs (`to_hash`) in hash conversion to support Rails
   `HashWithIndifferentAccess` data (see #104).
 
+* Add a per-tree `checks: false` option to skip validation checks when
+  performance matters. This is risky and can yield unexpected behavior if
+  invalid data is introduced. Only disable checks with benchmark data that
+  justifies the risk (see #45).
+
 ### 2.2.1pre / 2026-02-07
 
 * Simplified development dependency constraints while maintaining Ruby 2.7+

lib/tree.rb

@@ -255,6 +255,11 @@ def validate_acyclic!
     #   String (Integer names may cause *surprises*)
     #
     # @param [Object] content Content of the node.
+    # @param [Hash, nil] options Optional settings such as { checks: false } to
+    #   disable validation checks for performance-critical usage. Disabling
+    #   checks is risky and can lead to unexpected behavior if invalid data is
+    #   added to the tree. Only disable checks with benchmark data that justifies
+    #   the risk.
     #
     # @raise [ArgumentError] Raised if the node name is empty.
     #
@@ -264,8 +269,11 @@ def validate_acyclic!
     #   _zero-based_ indexing convention.
     #
     # @see #[]
-    def initialize(name, content = nil)
-      raise ArgumentError, 'Node name HAS to be provided!' if name.nil?
+    def initialize(name, content = nil, options = nil)
+      options = {} unless options.is_a?(Hash)
+      @checks_enabled = options.fetch(:checks, true)
+
+      raise ArgumentError, 'Node name HAS to be provided!' if checks_enabled? && name.nil?
 
       name = name.to_s if name.is_a?(Integer)
       @name = name
@@ -287,7 +295,7 @@ def detached_copy
         rescue TypeError
           @content
         end
-      self.class.new(@name, cloned_content)
+      self.class.new(@name, cloned_content, { checks: @checks_enabled })
     end
 
     # Returns a copy of entire (sub-)tree from this node.
@@ -394,7 +402,7 @@ def to_s
     # @see #add
     # @see #initialize
     def [](name_or_index)
-      raise ArgumentError, 'Name_or_index needs to be provided!' if name_or_index.nil?
+      raise ArgumentError, 'Name_or_index needs to be provided!' if checks_enabled? && name_or_index.nil?
 
       case name_or_index
       in Integer
@@ -447,6 +455,14 @@ def cmp(other, policy: :each)
       comparator.call
     end
 
+    # Returns +true+ when validation checks are enabled for this tree.
+    def checks_enabled?
+      @checks_enabled != false
+    end
+
+    attr_writer :checks_enabled
+    protected :checks_enabled=
+
     private
 
     def comparable_node?(other)

lib/tree/utils/structure_methods.rb

@@ -143,6 +143,8 @@ def freeze_tree!
       end
 
       def validate_add_child!(child)
+        return unless checks_enabled?
+
         raise ArgumentError, 'Attempting to add a nil node' unless child
         raise ArgumentError, 'Attempting add node to itself' if equal?(child)
         raise ArgumentError, 'Attempting add root as a child' if child.equal?(root)
@@ -153,12 +155,22 @@ def validate_add_child!(child)
       end
 
       def ensure_unique_child_name!(child)
+        return unless checks_enabled?
+
         return unless @children_hash.include?(child.name)
 
         raise "Child #{child.name} already added!"
       end
 
       def insert_child_at!(child, at_index)
+        unless checks_enabled?
+          max = @children.size
+          min = -(max + 1)
+          at_index = max if at_index > max
+          at_index = min if at_index < min
+          return @children.insert(at_index, child)
+        end
+
         return @children.insert(at_index, child) if insertion_range.include?(at_index)
 
         message = [
@@ -172,6 +184,7 @@ def insert_child_at!(child, at_index)
 
       def attach_child!(child)
         @children_hash[child.name] = child
+        child.send(:checks_enabled=, checks_enabled?) if child.respond_to?(:checks_enabled=, true)
         child.parent = self
         invalidate_size_cache_upwards!
         child

test/test_tree_checks.rb

@@ -0,0 +1,79 @@
+# test_tree_checks.rb - This file is part of the RubyTree package.
+#
+# Copyright (c) 2026 Anupam Sengupta. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# - Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# - Redistributions in binary form must reproduce the above copyright notice, this
+#   list of conditions and the following disclaimer in the documentation and/or
+#   other materials provided with the distribution.
+#
+# - Neither the name of the organization nor the names of its contributors may
+#   be used to endorse or promote products derived from this software without
+#   specific prior written permission.
+#
+#   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# frozen_string_literal: true
+
+require 'test/unit'
+require_relative '../lib/tree/tree_deps'
+
+module TestTree
+  class TestTreeChecks < Test::Unit::TestCase
+    def test_checks_disabled_skips_validation
+      root = Tree::TreeNode.new('root', nil, { checks: false })
+      child1 = Tree::TreeNode.new('dup', nil, { checks: false })
+      child2 = Tree::TreeNode.new('dup', nil, { checks: false })
+
+      root.add(child1)
+      assert_nothing_raised { root.add(child2) }
+      assert_equal(2, root.children.size)
+      assert_nil(root[nil])
+    end
+
+    def test_checks_enabled_validation_guards
+      root = Tree::TreeNode.new('root')
+      child1 = Tree::TreeNode.new('dup')
+      child2 = Tree::TreeNode.new('dup')
+
+      root.add(child1)
+      assert_raise(RuntimeError) { root.add(child2) }
+      assert_raise(ArgumentError) { root[nil] }
+    end
+
+    def test_checks_disabled_allows_out_of_range_insert
+      root = Tree::TreeNode.new('root', nil, { checks: false })
+      child1 = Tree::TreeNode.new('child1', nil, { checks: false })
+      child2 = Tree::TreeNode.new('child2', nil, { checks: false })
+
+      root.add(child1, 999)
+      root.add(child2, -999)
+      assert_equal(2, root.children.size)
+    end
+
+    def test_checks_setting_propagates_to_children
+      root = Tree::TreeNode.new('root', nil, { checks: false })
+      child = Tree::TreeNode.new('child')
+
+      root.add(child)
+      assert_equal(false, child.checks_enabled?)
+
+      dup = Tree::TreeNode.new('child')
+      assert_nothing_raised { root.add(dup) }
+    end
+  end
+end