xylem 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1f36a0a448ea0f87bbb5bb18b7ebb4f090e8a724
+  data.tar.gz: 74c92b1a1d23c3524480c3c97521f5f1bf3395b7
+SHA512:
+  metadata.gz: 25b9ac95f3a6c51d2abc5195269a7f6bab89376dffb32034db0a9aad18cf52974083ac5666515cdd0ebb6d93b77f68c80d1253ff256a4900e271ab99f6aec9b3
+  data.tar.gz: 9406bb0aec116ecee01b8f7dfdd3c5e3f190580eba20afb2f8e3a2a0fe57b81b4a23aa1d2d68889ed92fdd7adf6f2e982d55cf9429d223bfb7f9c9e57ad962c1

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.vagrant/
+/.yardoc
+/Gemfile.lock
+/gemfiles/*.gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.travis.yml

@@ -0,0 +1,35 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.3.0
+  - 2.2.4
+  - 2.1.8
+  - 2.0.0
+  - 1.9.3
+gemfile:
+  - gemfiles/ar_4.0.gemfile
+  - gemfiles/ar_4.1.gemfile
+  - gemfiles/ar_4.2.gemfile
+  - gemfiles/ar_5beta.gemfile
+before_script:
+  - psql -c 'create database xylem_test;' -U postgres
+addons:
+  apt:
+    sources:
+    - debian-sid
+    packages:
+    - sqlite3
+env:
+  matrix:
+    - DB=sqlite
+    - DB=postgres
+  global:
+    secure: "PSK+NqEOpz6P3lDxQ/dIYg6F2FQrdtrkiE72hbL2S0uJ+BJMGp/Uw3h23ihUmlJAPqjNjtxyoslKYLiCiUje/6ID7DhxL8q2Yerqtf0mnMnHrX2mmSkrXrLva9RkMEbpXlHUVT7eZyEZKaw/3ZL917XPo2/M/dX8e0zwtUjhfOEejzXvWuW53A+B155ghpKnB9krbI71CXzK9fsPGR9fi4Mb7+eyZ24Qi3snrRADz9gQbpCG6rLs1j0E052NnLCttkMYU0d5+K9VI+eyDnWboiPThDY/iCw7arTkE6HPjnPbtZp2/GyiOQMpGxV8pzBrtAiy167wUzzhdhtKhLUvl0RUKyRY811N9EJAXEoXydf+r/SHCYNNrTaKKf/dMuTJT1YKFiqthlFS3lFT4f3JduRoPT0YsvPliAWDSdIG1XOINg5DnrNtVgKdwfLjb4klUK4MAw2cwF2M0iKbaNaj9AAduMctRxJyfY91+uCMOnnj4KXNXDzcUjLqXyZPd2qPBWf9wU1lL7mll/B2UDHuAaKqVDe18yut4LeszN0JFClZdGNlSdYXfj/1+C5b80hd5f8ckzlZ5ZYkksOTPDcByev1uvkDThSixru+LI8kYyTENgRAptMSHrUFmGn4XINELOvJi9dsjq9nhSC3DP30dCcddQalcxcSZQI8EeWOVb4="
+matrix:
+  exclude:
+  - rvm: 1.9.3
+    gemfile: gemfiles/ar_5beta.gemfile
+  - rvm: 2.0.0
+    gemfile: gemfiles/ar_5beta.gemfile
+  - rvm: 2.1.8
+    gemfile: gemfiles/ar_5beta.gemfile

data/Appraisals

@@ -0,0 +1,15 @@
+appraise 'ar-4.0' do
+  gem 'activerecord', '~> 4.0'
+end
+
+appraise 'ar-4.1' do
+  gem 'activerecord', '~> 4.1'
+end
+
+appraise 'ar-4.2' do
+  gem 'activerecord', '~> 4.2'
+end
+
+appraise 'ar-5beta' do
+  gem 'activerecord', '5.0.0.beta1'
+end

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem 'codeclimate-test-reporter', group: :test, require: nil
+gem 'appraisal'
+gemspec

data/README.md

@@ -0,0 +1,179 @@
+# Xylem
+[![Build Status](https://travis-ci.org/oesgalha/xylem.svg)](https://travis-ci.org/oesgalha/xylem)
+[![Code Climate](https://codeclimate.com/github/oesgalha/xylem/badges/gpa.svg)](https://codeclimate.com/github/oesgalha/xylem)
+[![Test Coverage](https://codeclimate.com/github/oesgalha/xylem/badges/coverage.svg)](https://codeclimate.com/github/oesgalha/xylem/coverage)
+[![Dependency Status](https://gemnasium.com/oesgalha/xylem.svg)](https://gemnasium.com/oesgalha/xylem)
+
+Xylem provides a simple way to store and retrieve hierarchical data in ActiveRecord.
+
+## What
+
+Xylem uses the Adjacency List approach to store hierarchical data, and use [recursive CTEs](https://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL#Common_table_expression) to query through it.
+
+That means that the storage strategy is simple: in order to map an ActiveRecord Model to a tree-like structure with parents and children, it's needed to add only one column to the table which contains a node's parent id. If the node is a root node that column will have a null value (or `nil`). With that, the insertion and removal of nodes is a simple process and thus it should be simple to recover a tree in a corrupted state and guarantee data consistency.
+
+Also queries that traverse the tree (such as get ancestors or descendants of a node) are made in one single recursive SQL statement.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'xylem', github: 'oesgalha/xylem'
+```
+
+And then execute:
+
+    $ bundle
+
+Now add a `parent_id` column to your ActiveRecord::Base model.
+Let's suppose that you want to add the tree behavior to a model called `Menu` with a database table called `menus`.
+
+You could invoke the rails generator tool like this:
+```
+rails g migration add_parent_to_menus parent:references
+```
+
+Or you could create the migration by hand, with something like that:
+```ruby
+class AddParentToMenus < ActiveRecord::Migration
+  def change
+    add_reference :menus, :parent, index: true, foreign_key: true
+  end
+end
+```
+
+Some notes regarding migration:
+* Add an index is optional, but recommended for performance sake.
+* Add a foreign key is optional, but it's recommended to guarantee data consistency
+* The `foreign_key: true` option is available in [rails 4.2.1](https://github.com/rails/rails/blob/v4.2.1/activerecord/CHANGELOG.md) or newer
+
+Now you need to enable the tree behavior in or model by adding the `acts_as_tree` directive in it.
+Let's suppose again that you're dealing with a model called `Menu`, you should add the following:
+
+```ruby
+class Menu < ActiveRecord::Base
+  acts_as_tree
+end
+```
+
+And you are ready to go! Check the config options in the Usage section below.
+
+## Usage
+
+### acts_as_tree options
+
+* :counter_cache => The name of the column that will cache the node children count. In order to use this, you need to create an integer column with the same name (ex: `counter_cache: :children_count`).
+* :touch => If `true`, when you updated or destroy a node, it's ancestors will be touched: `updated_at` column is updated with the current time. (the default value is `false`)
+* :dependent => Controls what happens with the children of a deleted node. Choose one of the following options (the default value is :destroy)
+  * :destroy children are also destroyed.
+  * :delete_all delete children direct in the database (this will skip callbacks)
+  * :nullify set the children's parent_id to NULL (nil), therefore turning them into new roots (this will also skip callbacks)
+  * :restrict_with_exception an exception is raised if there is an attempt to destroy a record with children
+  * :restrict_with_error a validation error is added to the record if there is an attempt to destroy it and it has children
+
+### Class methods
+
+Xylem adds the following class methods to a class with the `acts_as_tree` directive:
+
+* `root`: returns the first root of the tree
+* `roots`: returns all the roots from the tree
+* `leaves`: returns all the leaves from the tree
+
+### Instance methods
+
+Xylem adds the following class methods to a class with the `acts_as_tree` directive:
+
+* `ancestors`: returns the ancestors from root to the parent of the node. Ordered from the root to the parent.
+* `self_and_ancestors` returns the ancestors from the root to the node itself. Ordered from the root to the node.
+* `descendants` returns all the descendants of the given node. Ordered by depth from the closer to the node to the more distant ones.
+* `self_and_descendants` returns the node and all it's descendants. Ordered by depth with the node first and the descendants later.
+* `root` returns the current node root.
+* `siblings` returns the siblings from the node, excluding itself.
+* `self_and_siblings` returns the node and it's siblings.
+* `children` returns the direct children of the node.
+* `self_and_children` returns the node and it's direct children.
+* `parent` returns the node parent.
+* `root?` returns true if the current node is a root, false otherwise.
+* `leaf?` returns true if the current node is a leaf, false otherwise.
+
+### Examples
+
+```ruby
+class Menu < ActiveRecord::Base
+  acts_as_tree
+end
+
+root = Menu.create!(name: 'root menu')
+child1 = root.children.create!('option 1')
+child2 = Menu.create!(name: 'option 2', parent: root)
+subchild = Menu.create!(name: 'suboption 1', parent: child2)
+
+Menu.roots                  # => [ root ]
+Menu.leaves                 # => [ child1, subchild ]
+
+root.root?                  # => true
+child1.leaf?                # => true
+
+child2.self_and_descendants # => [ child2, subchild ]
+
+child1.root                 # => root
+child1.self_and_ancestors   # => [ root, child1 ]
+
+child1.self_and_siblings    # => [ child1, child2 ]
+```
+
+## Dependencies
+
+* ActiveRecord 4+
+
+This gem relies on the `Recursive CTE` feature which was introduced to SQL in the 1999 revision.
+So you need a database management system that implements it. This gem is tested against PostgreSQL and SQLite, those started to support the recursive CTE in the following versions:
+* PostgreSQL 8.4+
+* SQLite 3.8.3+
+
+It seems that MySQL still has no support to it. If you use MySQL you can look for other gems to help you deal with models organized in trees, check the Alternatives section bellow.
+
+This gem is tested against ruby 1.9.3 and newer only.
+
+## Alternatives
+
+There are other gems that allow you to treat models like trees, with different approaches.
+Here are some other gems you could use to achieve the same objective:
+
+* [acts_as_tree](https://github.com/amerine/acts_as_tree)
+* [awesome_nested_set](https://github.com/collectiveidea/awesome_nested_set)
+* [ancestry](https://github.com/stefankroes/ancestry)
+
+## Contributing
+
+1. Fork it ( https://github.com/oesgalha/xylem/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+Copyright (c) 2015-2016 Oscar Esgalha
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+
+task :test do
+  $LOAD_PATH.unshift('lib', 'test')
+  require './test/xylem_tests.rb'
+end
+
+task default: :test

data/Vagrantfile

@@ -0,0 +1,15 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Vagrantfile API/syntax version. Don't touch unless you know what you're doing!
+VAGRANTFILE_API_VERSION = "2"
+
+Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
+  config.vm.box = 'ubuntu/trusty64'
+  config.vm.network :private_network, ip: "192.168.33.78"
+  config.vm.synced_folder '.', '/vagrant', nfs: true
+  config.ssh.forward_agent = true
+  config.vm.define "xylem_develop" do |xylem_develop|
+  end
+  config.vm.provision :shell, path: 'bootstrap.sh', keep_color: true
+end

data/bench/acts_as_tree.json

@@ -0,0 +1,32 @@
+[
+  {
+    "name": "insertion",
+    "ips": 412.7091261183738,
+    "stddev": 51
+  },
+  {
+    "name": "parent",
+    "ips": 633.857043437574,
+    "stddev": 85
+  },
+  {
+    "name": "children",
+    "ips": 8.660125142509473,
+    "stddev": 2
+  },
+  {
+    "name": "roots",
+    "ips": 1029.8556860775493,
+    "stddev": 136
+  },
+  {
+    "name": "ancestors",
+    "ips": 251.68388495529973,
+    "stddev": 33
+  },
+  {
+    "name": "descendants",
+    "ips": 0.19643176694334188,
+    "stddev": 0
+  }
+]

data/bench/ancestry.json

@@ -0,0 +1,32 @@
+[
+  {
+    "name": "insertion",
+    "ips": 529.3829399001362,
+    "stddev": 68
+  },
+  {
+    "name": "parent",
+    "ips": 798.8413756182359,
+    "stddev": 112
+  },
+  {
+    "name": "children",
+    "ips": 19.534339432833036,
+    "stddev": 2
+  },
+  {
+    "name": "roots",
+    "ips": 1306.76576446662,
+    "stddev": 254
+  },
+  {
+    "name": "ancestors",
+    "ips": 501.12099359692917,
+    "stddev": 112
+  },
+  {
+    "name": "descendants",
+    "ips": 14.539749441549349,
+    "stddev": 2
+  }
+]

data/bench/awesome_nested_set.json

@@ -0,0 +1,32 @@
+[
+  {
+    "name": "insertion",
+    "ips": 7.721853007625269,
+    "stddev": 2
+  },
+  {
+    "name": "parent",
+    "ips": 569.4524509694182,
+    "stddev": 191
+  },
+  {
+    "name": "children",
+    "ips": 154.39379306573127,
+    "stddev": 34
+  },
+  {
+    "name": "roots",
+    "ips": 820.8230612972056,
+    "stddev": 119
+  },
+  {
+    "name": "ancestors",
+    "ips": 346.3686578783685,
+    "stddev": 70
+  },
+  {
+    "name": "descendants",
+    "ips": 52.86002694684352,
+    "stddev": 7
+  }
+]

data/bench/benchmark.rb

@@ -0,0 +1,85 @@
+require 'bundler/inline'
+
+BENCH_GEM = ENV['BENCH_GEM']
+
+unless ['xylem', 'acts_as_tree', 'awesome_nested_set', 'ancestry'].include?(BENCH_GEM)
+  fail 'Please provide a environment variable BENCH_GEM with one o the following values: [xylem, acts_as_tree, awesome_nested_set, ancestry]'
+end
+
+gemfile(true) do
+  source 'https://rubygems.org'
+  gem 'activerecord', require: 'active_record'
+  gem 'pg'
+  gem 'benchmark-ips'
+
+  case BENCH_GEM
+  when 'xylem'
+    gem 'xylem', path: '..'
+  when 'acts_as_tree'
+    gem 'acts_as_tree'
+  when 'awesome_nested_set'
+    gem 'activesupport', require: 'active_support/core_ext/module/delegation'
+    gem 'awesome_nested_set'
+  when 'ancestry'
+    gem 'ancestry'
+  end
+end
+
+ActiveRecord::Base.establish_connection(adapter: 'postgresql', database: 'xylem_test', username: 'postgres')
+ActiveRecord::Base.connection.execute('DROP SCHEMA public CASCADE; CREATE SCHEMA public;')
+
+ActiveRecord::Base.send(:include, ActsAsTree) if BENCH_GEM == 'acts_as_tree'
+
+class Comment < ActiveRecord::Base
+  acts_as_tree        if ['xylem', 'acts_as_tree'].include?(BENCH_GEM)
+  acts_as_nested_set  if BENCH_GEM == 'awesome_nested_set'
+  has_ancestry        if BENCH_GEM == 'ancestry'
+
+  connection.create_table table_name, force: true do |t|
+    t.string :payload
+    t.integer :parent_id, index: true   if BENCH_GEM != 'ancestry'
+    t.integer :lft, index: true         if BENCH_GEM == 'awesome_nested_set'
+    t.integer :rgt, index: true         if BENCH_GEM == 'awesome_nested_set'
+    t.string :ancestry, index: true     if BENCH_GEM == 'ancestry'
+  end
+end
+
+def recursive_child(par, depth)
+  unless depth == 0
+    5.times do
+      recursive_child(Comment.create!(payload: SecureRandom.hex(128), parent: par), depth - 1)
+    end
+  end
+end
+
+puts 'INSERTING TEST DATA...'
+
+recursive_child(nil, 5)
+
+@comment1 = Comment.roots.first
+@comment11 = @comment1.children.sample
+@comment111 = @comment11.children.sample
+@comment1111 = @comment111.children.sample
+@comment11111 = @comment1111.children.sample
+
+Benchmark.ips do |x|
+  x.report('insertion') do |times|
+    times.times { Comment.create!(parent: @comment111) }
+  end
+  x.report('parent') do |times|
+    times.times { @comment11111.reload.parent }
+  end
+  x.report('children') do |times|
+    times.times { @comment111.reload.children.to_a }
+  end
+  x.report('roots') do |times|
+    times.times { Comment.roots.to_a }
+  end
+  x.report('ancestors') do |times|
+    times.times { @comment11111.reload.ancestors.to_a }
+  end
+  x.report('descendants') do |times|
+    times.times { @comment1.reload.descendants.to_a }
+  end
+  x.json!("#{ENV['BENCH_GEM']}.json")
+end

data/bench/xylem.json

@@ -0,0 +1,32 @@
+[
+  {
+    "name": "insertion",
+    "ips": 600.964555391788,
+    "stddev": 34
+  },
+  {
+    "name": "parent",
+    "ips": 1070.2536522884402,
+    "stddev": 120
+  },
+  {
+    "name": "children",
+    "ips": 11.90851991649796,
+    "stddev": 2
+  },
+  {
+    "name": "roots",
+    "ips": 1713.3724759018537,
+    "stddev": 210
+  },
+  {
+    "name": "ancestors",
+    "ips": 511.49023662770406,
+    "stddev": 61
+  },
+  {
+    "name": "descendants",
+    "ips": 12.000439734178782,
+    "stddev": 2
+  }
+]

data/bootstrap.sh

@@ -0,0 +1,32 @@
+# Shell file taken at: https://github.com/rails/rails-dev-box
+function install {
+    echo installing $1
+    shift
+    apt-get -y install "$@" >/dev/null 2>&1
+}
+
+echo updating package information
+apt-add-repository -y ppa:brightbox/ruby-ng >/dev/null 2>&1
+apt-get -y update >/dev/null 2>&1
+
+install 'development tools' build-essential
+
+install Ruby ruby2.2 ruby2.2-dev
+update-alternatives --set ruby /usr/bin/ruby2.2 >/dev/null 2>&1
+update-alternatives --set gem /usr/bin/gem2.2 >/dev/null 2>&1
+
+echo installing Bundler
+gem install bundler -N >/dev/null 2>&1
+
+install Git git
+install SQLite sqlite3 libsqlite3-dev
+
+install PostgreSQL postgresql postgresql-contrib libpq-dev
+sudo -u postgres createdb -O postgres xylem_test
+
+install 'Nokogiri dependencies' libxml2 libxml2-dev libxslt1-dev
+
+# Needed for docs generation.
+update-locale LANG=en_US.UTF-8 LANGUAGE=en_US.UTF-8 LC_ALL=en_US.UTF-8
+
+echo 'ready to roll out'

data/gemfiles/ar_4.0.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "codeclimate-test-reporter", :group => :test, :require => nil
+gem "appraisal"
+gem "activerecord", "~> 4.0"
+
+gemspec :path => "../"

data/gemfiles/ar_4.1.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "codeclimate-test-reporter", :group => :test, :require => nil
+gem "appraisal"
+gem "activerecord", "~> 4.1"
+
+gemspec :path => "../"

data/gemfiles/ar_4.2.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "codeclimate-test-reporter", :group => :test, :require => nil
+gem "appraisal"
+gem "activerecord", "~> 4.2"
+
+gemspec :path => "../"

data/gemfiles/ar_5beta.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "codeclimate-test-reporter", :group => :test, :require => nil
+gem "appraisal"
+gem "activerecord", "5.0.0.beta1"
+
+gemspec :path => "../"

data/lib/xylem/version.rb

@@ -0,0 +1,3 @@
+module Xylem
+  VERSION = '0.0.1'
+end

data/lib/xylem.rb

@@ -0,0 +1,96 @@
+require 'active_record'
+
+module Xylem
+  module InstanceMethods
+    def ancestors
+      _xylem_query(:id, parent_id, :id, :parent_id, :desc)
+    end
+
+    def self_and_ancestors
+      _xylem_query(:id, id, :id, :parent_id, :desc)
+    end
+
+    def descendants
+      _xylem_query(:parent_id, id, :parent_id, :id, :asc)
+    end
+
+    def self_and_descendants
+      _xylem_query(:id, id, :parent_id, :id, :asc)
+    end
+
+    def root
+      ancestors.first
+    end
+
+    def siblings
+      self.class.where(parent_id: parent_id).where.not(id: id)
+    end
+
+    def self_and_siblings
+      self.class.where(parent_id: parent_id)
+    end
+
+    def self_and_children
+      [self] + children
+    end
+
+    def root?
+      parent.nil?
+    end
+
+    def leaf?
+      children.size == 0
+    end
+
+    private
+
+    def _xylem_query(where_col, where_val, join_lft_col, join_rgt_col, order_stmt)
+      rcte = Arel::Table.new(:recusive_cte)
+      table = self.class.arel_table
+      i_select = table.project([table[Arel.star], Arel::Nodes::As.new(1, Arel::Nodes::SqlLiteral.new('level'))]).where(table[where_col].eq(where_val))
+      r_select = table.project([table[Arel.star], Arel::Nodes::SqlLiteral.new('level + 1')]).join(rcte).on(table[join_lft_col].eq(rcte[join_rgt_col]))
+      as_stmt = Arel::Nodes::As.new(rcte, i_select.union(:all, r_select))
+      self.class.from(Arel::Nodes::TableAlias.new(rcte.project(Arel.star).with(:recursive, as_stmt), self.class.table_name).to_sql).order(level: order_stmt)
+    end
+  end
+
+  module ClassMethods
+    def root
+      roots.first
+    end
+
+    def roots
+      where(parent: nil)
+    end
+
+    def leaves
+      t = arel_table
+      where(t[:id].not_in(t.project([t[:parent_id]]).where(t[:parent_id].not_eq(nil)).distinct))
+    end
+  end
+end
+
+class ActiveRecord::Base
+  def self.acts_as_tree(options = {})
+    config = {
+      counter_cache: options[:counter_cache] || nil,
+      dependent: options[:destroy] || :destroy,
+      touch: options[:touch] || false
+    }
+
+    has_many :children,
+      class_name: name,
+      foreign_key: :parent_id,
+      dependent: config[:dependent],
+      inverse_of: :parent
+
+    belongs_to :parent,
+      class_name: name,
+      counter_cache: config[:counter_cache],
+      touch: config[:touch],
+      inverse_of: :children
+
+    extend  Xylem::ClassMethods
+    include Xylem::InstanceMethods
+  end
+end

data/test/xylem_tests.rb

@@ -0,0 +1,226 @@
+require 'codeclimate-test-reporter'
+CodeClimate::TestReporter.start
+require 'minitest/autorun'
+require 'minitest/pride'
+
+require 'xylem'
+
+case ENV['DB']
+when 'sqlite'
+  ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+when 'postgres'
+  ActiveRecord::Base.establish_connection(adapter: 'postgresql', database: 'xylem_test', username: 'postgres')
+  ActiveRecord::Base.connection.execute('DROP SCHEMA public CASCADE; CREATE SCHEMA public;')
+else
+  fail 'Please provide a environment varible DB with either "postgres" or "sqlite" to define the tested database'
+end
+
+class Category < ActiveRecord::Base
+  acts_as_tree
+  connection.create_table table_name, force: true do |t|
+    t.integer :parent_id
+  end
+end
+
+class Menu < ActiveRecord::Base
+  acts_as_tree
+  default_scope { where(draft: false) }
+  connection.create_table table_name, force: true do |t|
+    t.integer :parent_id
+    t.boolean :draft, default: false
+  end
+end
+
+class PlainModel < ActiveRecord::Base
+  connection.create_table table_name, force: true do |t|
+    t.string :name
+  end
+end
+
+class XylemTestCase < MiniTest::Test
+  def setup
+    @product = Category.create!
+    @service = Category.create!
+    @physical = Category.create!(parent_id: @product.id)
+    @digital = Category.create!(parent_id: @product.id)
+    @training = Category.create!(parent_id: @service.id)
+    @consultancy = Category.create!(parent_id: @service.id)
+    @hosting = Category.create!(parent_id: @service.id)
+    @daily_training = Category.create!(parent_id: @training.id)
+    @weekly_training = Category.create!(parent_id: @training.id)
+
+    @gibberish = Menu.create!(draft: true)
+    @main = Menu.create!
+    @option1 = Menu.create!(parent: @main)
+    @option2 = Menu.create!(parent: @main, draft: true)
+    @option3 = Menu.create!(parent: @main)
+    @suboption11 = Menu.create!(parent: @option1)
+    @suboption12 = Menu.create!(parent: @option1)
+    @suboption21 = Menu.create!(parent: @option2, draft: true)
+  end
+
+  def teardown
+    ar_connection = ActiveRecord::Base.connection
+    ar_connection.tables.each { |t| ar_connection.execute "DELETE FROM #{t}" }
+  end
+end
+
+class ClassMethodsTest < XylemTestCase
+  def test_root
+    assert_equal @product, Category.root
+  end
+
+  def test_scoped_root
+    assert_equal @main, Menu.root
+  end
+
+  def test_roots
+    assert_equal [@product, @service], Category.roots
+  end
+
+  def test_scoped_roots
+    assert_equal [@main], Menu.roots
+  end
+
+  def test_leaves
+    assert_equal [@physical, @digital, @consultancy, @hosting, @daily_training, @weekly_training], Category.leaves
+  end
+
+  def test_scoped_leaves
+    assert_equal [@option3, @suboption11, @suboption12], Menu.leaves
+  end
+
+  def test_plain_model
+    refute_respond_to PlainModel, :root
+    refute_respond_to PlainModel, :roots
+    refute_respond_to PlainModel, :leaves
+  end
+end
+
+class InstanceMethodsTest < XylemTestCase
+  def test_ancestors
+    assert_equal [@service, @training], @weekly_training.ancestors
+    assert_equal [@product], @digital.ancestors
+    assert_empty @product.ancestors
+    assert_empty @service.ancestors
+  end
+
+  def test_scoped_ancestors
+    assert_equal [@main, @option1], @suboption12.ancestors
+    assert_empty @main.ancestors
+    assert_empty @gibberish.ancestors
+  end
+
+  def test_self_and_ancestors
+    assert_equal [@service, @training, @weekly_training], @weekly_training.self_and_ancestors
+    assert_equal [@product, @digital], @digital.self_and_ancestors
+    assert_equal [@product], @product.self_and_ancestors
+    assert_equal [@service], @service.self_and_ancestors
+  end
+
+  def test_scoped_self_and_ancestors
+    assert_equal [@main, @option1, @suboption12], @suboption12.self_and_ancestors
+    assert_equal [@main], @main.self_and_ancestors
+    assert_empty @gibberish.self_and_ancestors
+  end
+
+  def test_descendants
+    assert_equal [@physical, @digital], @product.descendants
+    assert_equal [@training, @consultancy, @hosting, @daily_training, @weekly_training], @service.descendants
+    assert_equal [@daily_training, @weekly_training], @training.descendants
+    assert_empty @physical.descendants
+    assert_empty @consultancy.descendants
+  end
+
+  def test_scoped_descendants
+    assert_equal [@option1, @option3, @suboption11, @suboption12], @main.descendants
+    assert_equal [@suboption11, @suboption12], @option1.descendants
+    assert_empty @gibberish.descendants
+    assert_empty @suboption11.descendants
+    assert_empty @suboption21.descendants
+  end
+
+  def test_self_and_descendants
+    assert_equal [@physical, @digital], @product.descendants
+    assert_equal [@training, @consultancy, @hosting, @daily_training, @weekly_training], @service.descendants
+    assert_equal [@daily_training, @weekly_training], @training.descendants
+    assert_empty @physical.descendants
+    assert_empty @consultancy.descendants
+  end
+
+  def test_scoped_self_and_descendants
+    assert_equal [@main, @option1, @option3, @suboption11, @suboption12], @main.self_and_descendants
+    assert_equal [@option1, @suboption11, @suboption12], @option1.self_and_descendants
+    assert_equal [@suboption11], @suboption11.self_and_descendants
+    assert_empty @gibberish.self_and_descendants
+  end
+
+  def test_root
+    assert_equal @service, @weekly_training.root
+    assert_equal @product, @digital.root
+    refute @product.root
+  end
+
+  def test_scoped_root
+    assert_equal @main, @suboption11.root
+    assert_equal @main, @option3.root
+    refute @main.root
+  end
+
+  def test_siblings
+    assert_equal [@digital], @physical.siblings
+    assert_equal [@training, @hosting], @consultancy.siblings
+  end
+
+  def test_scoped_siblings
+    assert_equal [@option3], @option1.siblings
+    assert_equal [@suboption11], @suboption12.siblings
+  end
+
+  def test_self_and_siblings
+    assert_equal [@physical, @digital], @physical.self_and_siblings
+    assert_equal [@training, @consultancy, @hosting], @consultancy.self_and_siblings
+  end
+
+  def test_scoped_self_and_siblings
+    assert_equal [@option1, @option3], @option1.self_and_siblings
+    assert_equal [@suboption11, @suboption12], @suboption12.self_and_siblings
+  end
+
+  def test_children
+    assert_equal [@physical, @digital], @product.children
+    assert_equal [@daily_training, @weekly_training], @training.children
+  end
+
+  def test_scoped_children
+    assert_equal [@option1, @option3], @main.children
+    assert_equal [@suboption11, @suboption12], @option1.children
+  end
+
+  def test_self_and_children
+    assert_equal [@product, @physical, @digital], @product.self_and_children
+    assert_equal [@training, @daily_training, @weekly_training], @training.self_and_children
+  end
+
+  def test_scoped_self_and_children
+    assert_equal [@product, @physical, @digital], @product.self_and_children
+    assert_equal [@training, @daily_training, @weekly_training], @training.self_and_children
+  end
+
+  def test_root?
+    assert @product.root?
+    assert @main.root?
+    refute @physical.root?
+    refute @option3.root?
+  end
+
+  def test_leaf?
+    assert @daily_training.leaf?
+    assert @consultancy.leaf?
+    assert @suboption12.leaf?
+    assert @option3.leaf?
+    refute @service.leaf?
+    refute @training.leaf?
+    refute @option1.leaf?
+  end
+end

data/xylem.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'xylem/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'xylem'
+  spec.version       = Xylem::VERSION
+  spec.authors       = ['Oscar Esgalha']
+  spec.email         = ['oscaresgalha@gmail.com']
+  spec.summary       = %q{Xylem uses the Adjacency List approach to store and query through hierarchical data with ActiveRecord.}
+  spec.description   = %q{Xylem provides a simple way to store and retrieve hierarchical data through ActiveRecord.}
+  spec.homepage      = 'https://github.com/oesgalha/xylem'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'activerecord', '>= 4.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'minitest', '~> 5.6'
+  spec.add_development_dependency 'pg', '>= 0.11'
+  spec.add_development_dependency 'sqlite3'
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: xylem
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Oscar Esgalha
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-01-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.6'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Xylem provides a simple way to store and retrieve hierarchical data through
+  ActiveRecord.
+email:
+- oscaresgalha@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Appraisals
+- Gemfile
+- README.md
+- Rakefile
+- Vagrantfile
+- bench/acts_as_tree.json
+- bench/ancestry.json
+- bench/awesome_nested_set.json
+- bench/benchmark.rb
+- bench/xylem.json
+- bootstrap.sh
+- gemfiles/ar_4.0.gemfile
+- gemfiles/ar_4.1.gemfile
+- gemfiles/ar_4.2.gemfile
+- gemfiles/ar_5beta.gemfile
+- lib/xylem.rb
+- lib/xylem/version.rb
+- test/xylem_tests.rb
+- xylem.gemspec
+homepage: https://github.com/oesgalha/xylem
+licenses:
+- MIT
+metadata: {}
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Xylem uses the Adjacency List approach to store and query through hierarchical
+  data with ActiveRecord.
+test_files:
+- test/xylem_tests.rb