with_recursive_tree 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9c1ccdf38306a7ddff768b00b73f3d3ff58bf094f7524e55b63e0502f4d757dd
+  data.tar.gz: 5572ccbc0023f7d7226b41f24ffa8513084dc2e8780075f48904dac3aa510a96
+SHA512:
+  metadata.gz: 0a9003bb5a943e7a4d48abed8db293a292dd21dfae943ab1c4899673920fa1c943b5f949d4caf9351c763b3f62e0a14bbfca0ff3e9dfa8fe7daa8e9f4ea6462e
+  data.tar.gz: 378da103d4c78855cc5c2acef7557e19a27eb2c3f11a4c63d26fa1e29dadff551d433d84060b0f7ef5bd2b711808d97b5c071e80e8f1ff5b61801ddca7a8bd38

data/README.md

@@ -0,0 +1,161 @@
+# with_recursive_tree
+
+Tree structures for ActiveRecord using CTE (Common Table Expressions). Traverse the whole tree with just one query.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "with_recursive_tree"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+## Usage
+
+First, your model needs a reference to the its parent. Tipically, this is a `parent_id` column in your table. Once you have that reference, you can add `with_recursive_tree` to your model:
+
+```ruby
+class Category < ApplicationRecord
+  with_recursive_tree
+end
+```
+
+By doing this, with_recursive_tree will add 2 associations:
+
+* `parent`: the parent of the node
+* `children`: the children of this node
+
+To build these associations, with_recursive_tree will use the `id` and the `parent_id` columns as the primary and foreing keys, respectively. If you want to specify different primary and foreign keys, you can do that by passing the `primary_key` and `foreign_key` options. For example, for a categories table whose primary key is `category_id` and the parent record id is `parent_category_id`, you would set it up as follows:
+
+```ruby
+class Category < ApplicationRecord
+ with_recursive_tree foreign_key: :parent_category_id, primary_key: :category_id
+end
+```
+
+Lastly, you can specify how to sort each node's `children` by passing the `order` option to `with_recursive_tree`. If no `order` option is set, it will default to `id`. This option is useful especially when you need to traverse the tree in a specific order. For example:
+
+```ruby
+class Category < ApplicationRecord
+  with_recursive_tree order: :name
+end
+```
+
+### Class methods
+
+| Method | Description |
+|--------|-------------|
+| `::roots` | Returns all roots (nodes without parent). |
+
+### Instance methods
+
+| Method | Description |
+|--------|-------------|
+| `#ancestors` | Returns all ancestors of the node. |
+| `#descendants` | Returns all descendants of the node (subtree). |
+| `#leaf?` | Returns whether the node is a leaf (has no children). |
+| `#depth` | Returns the depth of the current node. |
+| `#root` | Returns the root node of the current node's tree. |
+| `#root?` | Returns whether the node is a root (has no parent). |
+| `#self_and_ancestors` | Returns the node and all its ancestors. |
+| `#self_and_descendants` | Returns the node and all its descendants (subtree). |
+| `#self_and_siblings` | Returns the current node and all its siblings. |
+| `#siblings` | Returns the current node's siblings. |
+
+### Tree traversing
+
+You can traverse the tree using `#descendants` or `#self_and_descendants` in combination with the `#bfs` (breadth-first search) and `#dfs` (depth-first search, pre-order) scopes.
+
+For example, given the following tree:
+
+![sample tree](/assets/tree.png)
+
+and the following class:
+
+```ruby
+class Node < ApplicationRecord
+  with_recursive_tree order: :name
+end
+```
+
+You can do:
+
+```ruby
+root = Node.roots.first
+
+puts root.self_and_descendants.bfs.map { |node| "#{"-" * node.depth}#{node.name}" }
+```
+
+and you will get:
+
+```
+A
+-B
+-L
+--C
+--H
+--M
+--N
+---D
+---I
+---O
+---P
+---Q
+---R
+----E
+----F
+----G
+----J
+-----K
+```
+
+Similarly, you can do the same with `#dfs`:
+
+```ruby
+puts root.self_and_descendants.dfs.map { |node| "#{"-" * node.depth}#{node.name}" }
+```
+
+and you will get:
+
+```
+A
+-B
+--C
+---D
+----E
+----F
+----G
+--H
+---I
+----J
+-----K
+-L
+--M
+--N
+---O
+---P
+---Q
+---R
+```
+
+## Benchmarks
+
+You can run some [benchmarks](/benchmarks/benchmark.rb) to compare with_recursive_tree agains [acts_as_tree](https://github.com/amerine/acts_as_tree), [ancestry](https://github.com/stefankroes/ancestry/) and [closure_tree](https://github.com/ClosureTree/closure_tree).
+
+Spoiler: benchmarks are always basic cases so you mustn't trust them as if they were the word of god, but they are useful tools for development/testing and setting a baseline performance requirement..
+
+In any case, you must weight the trade-offs between what you need to accomplish and performance.
+
+## Contributing
+
+Fork the repo, add your feature, create a PR.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/lib/with_recursive_tree/version.rb

@@ -0,0 +1,3 @@
+module WithRecursiveTree
+  VERSION = "0.1.0"
+end

data/lib/with_recursive_tree.rb

@@ -0,0 +1,83 @@
+require "active_support/concern"
+
+require "with_recursive_tree/version"
+
+module WithRecursiveTree
+  extend ActiveSupport::Concern
+
+  included do
+    scope :bfs, -> { order :depth }
+    scope :dfs, -> { self }
+  end
+
+  class_methods do
+    def with_recursive_tree(primary_key: :id, foreign_key: :parent_id, order: nil)
+      belongs_to :parent, class_name: name, primary_key: primary_key, foreign_key: foreign_key, inverse_of: :children, optional: true
+
+      has_many :children, -> { order order }, class_name: name, primary_key: primary_key, foreign_key: foreign_key, inverse_of: :parent
+
+      define_singleton_method(:with_recursive_tree_primary_key) { primary_key }
+      define_singleton_method(:with_recursive_tree_foreign_key) { foreign_key }
+      define_singleton_method(:with_recursive_tree_order) { order || primary_key }
+    end
+
+    def roots
+      where with_recursive_tree_foreign_key => nil
+    end
+  end
+
+  def ancestors
+    self_and_ancestors.excluding self
+  end
+
+  def descendants
+    self_and_descendants.excluding self
+  end
+
+  def leaf?
+    children.none?
+  end
+
+  def depth
+    attributes["depth"] || ancestors.count
+  end
+  alias_method :level, :depth
+
+  def root
+    self_and_ancestors.find_by self.class.with_recursive_tree_foreign_key => nil
+  end
+
+  def root?
+    parent.blank?
+  end
+
+  def self_and_ancestors
+    self.class.with(search_tree: self.class.with_recursive(
+      search_tree: [
+        self.class.where(self.class.with_recursive_tree_primary_key => send(self.class.with_recursive_tree_primary_key)),
+        self.class.joins("JOIN search_tree ON #{self.class.table_name}.#{self.class.with_recursive_tree_primary_key} = search_tree.#{self.class.with_recursive_tree_foreign_key}")
+      ]
+    ).select("*").from("search_tree")).from("search_tree AS #{self.class.table_name}")
+  end
+
+  def self_and_descendants
+    self.class.with(search_tree: self.class.with_recursive(
+      search_tree: [
+        self.class.where(self.class.with_recursive_tree_primary_key => send(self.class.with_recursive_tree_primary_key)).select("*, '/' || #{self.class.with_recursive_tree_primary_key} || '/' AS path, 0 AS depth"),
+        Arel.sql(self.class.joins("JOIN search_tree ON #{self.class.table_name}.#{self.class.with_recursive_tree_foreign_key} = search_tree.#{self.class.with_recursive_tree_primary_key}").select("#{self.class.table_name}.*, search_tree.path || #{self.class.table_name}.#{self.class.with_recursive_tree_primary_key} || '/' AS path, depth + 1 AS depth").order(self.class.with_recursive_tree_order).to_sql)
+      ]
+    ).select("*").from("search_tree")).from("search_tree AS #{self.class.table_name}")
+  end
+
+  def self_and_siblings
+    root? ? self.class.roots : parent.children
+  end
+
+  def siblings
+    self_and_siblings.excluding self
+  end
+end
+
+ActiveSupport.on_load :active_record do
+  include WithRecursiveTree
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: with_recursive_tree
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Patricio Mac Adden
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: Tree structures for ActiveRecord
+email:
+- patriciomacadden@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/with_recursive_tree.rb
+- lib/with_recursive_tree/version.rb
+homepage: https://github.com/sinaptia/with_recursive_tree
+licenses: []
+metadata:
+  homepage_uri: https://github.com/sinaptia/with_recursive_tree
+  source_code_uri: https://github.com/sinaptia/with_recursive_tree
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Tree structures for ActiveRecord
+test_files: []