dagable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e1ce980aa13e26cc4f39e22e4af897ac32921a3e7a815da5294c129ce233da1
+  data.tar.gz: 0c2e385b11f1f9e1fef43667d07c82947e5bc36f12651741b544bb6fe1fccf56
+SHA512:
+  metadata.gz: 2c0c364e091d5301f9fdc8d9fa19d7c40721c8cb808d402a84d5b4e60c2d82dbb9c6a50977b7e3fb7a5f306dd3f71facf0a4f8ded7979361d00b5c9c17dda91d
+  data.tar.gz: b2464c035a6ef4c969592182d1e71c25552144eed8083a953b079897d97d039fbeebd413c47ff8430081353eb4a474685cdb19f4db8fb3ac3cd310a10a1db125

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leandro Maduro
+
+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/README.md

@@ -0,0 +1,232 @@
+# Dagable
+
+Dagable provides **directed acyclic graph (DAG)** composition for ActiveRecord models using a dedicated **ancestry table**. It materializes all transitive paths so that traversal queries are single JOINs instead of recursive CTEs.
+
+## Features
+
+- **Pre-computed ancestry** — all transitive paths are materialized in an ancestry table, so traversal queries are single JOINs instead of recursive CTEs
+- **Cycle detection** — raises `Dagable::Errors::CyclicAssociation` before any invalid edge is persisted (self-referential, direct, and transitive cycles)
+- **ActiveRecord::Relation returns** — all traversal methods (`self_and_successors`, `self_and_predecessors`, `successors`, `predecessors`) return chainable relations
+- **Domain-agnostic** — no knowledge of your application domain; works with any ActiveRecord model
+- **Pure ActiveRecord** — only requires ActiveRecord, not Rails
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'dagable'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install dagable
+```
+
+## Setup
+
+### 1. Create the database tables
+
+Dagable requires two supporting tables per model: an **edges** table for direct relationships and an **ancestries** table for all transitive paths.
+
+```ruby
+class CreateCategoryDag < ActiveRecord::Migration[8.1]
+  include Dagable::MigrationHelpers
+
+  def change
+    create_table :categories do |t|
+      t.string :name, null: false
+      t.timestamps
+    end
+
+    create_dagable_tables(:categories)
+  end
+end
+```
+
+`create_dagable_tables(:categories)` creates:
+
+| Table | Columns | Indexes |
+|-------|---------|---------|
+| `categories_edges` | `parent_id`, `child_id` | Unique composite `[parent_id, child_id]` |
+| `categories_ancestries` | `predecessor_id`, `successor_id`, `depth` | Unique composite `[predecessor_id, successor_id]`, individual on `predecessor_id` and `successor_id` |
+
+Both tables include foreign keys back to the source table.
+
+### 2. Activate the model
+
+```ruby
+class Category < ActiveRecord::Base
+  extend Dagable::Model
+
+  dagable
+end
+```
+
+Calling `dagable` will:
+
+1. Define `Category::Edge` and `Category::Ancestry` (dynamic ActiveRecord classes)
+2. Set up `has_many` associations for edges and ancestry connections
+3. Include traversal and edge management instance methods
+4. Register an `after_create` callback for self-referential ancestry rows
+
+## Usage
+
+### Adding edges
+
+```ruby
+electronics = Category.create!(name: "Electronics")
+phones      = Category.create!(name: "Phones")
+smartphones = Category.create!(name: "Smartphones")
+
+electronics.add_child(phones)
+phones.add_child(smartphones)
+
+# Or equivalently:
+smartphones.add_parent(phones)
+```
+
+### Traversal
+
+All traversal methods return `ActiveRecord::Relation`, so you can chain scopes, pluck, count, etc.
+
+```ruby
+electronics.self_and_successors
+# => [Electronics, Phones, Smartphones]
+
+electronics.successors
+# => [Phones, Smartphones]
+
+smartphones.self_and_predecessors
+# => [Electronics, Phones, Smartphones]
+
+smartphones.predecessors
+# => [Electronics, Phones]
+```
+
+### Direct relationships
+
+Access direct parents/children via the edge associations:
+
+```ruby
+electronics.children
+# => [Phones]
+
+phones.parents
+# => [Electronics]
+
+phones.children
+# => [Smartphones]
+```
+
+### Removing edges
+
+```ruby
+phones.remove_child(smartphones)
+
+# Or equivalently:
+smartphones.remove_parent(phones)
+```
+
+After removal, the ancestry table is automatically rebuilt to reflect the new graph state.
+
+### Cycle detection
+
+Dagable prevents cycles at edge-creation time:
+
+```ruby
+electronics = Category.create!(name: "Electronics")
+phones      = Category.create!(name: "Phones")
+accessories = Category.create!(name: "Accessories")
+
+electronics.add_child(phones)
+phones.add_child(accessories)
+
+accessories.add_child(electronics)
+# => raises Dagable::Errors::CyclicAssociation
+
+electronics.add_child(electronics)
+# => raises Dagable::Errors::CyclicAssociation
+```
+
+Valid DAG structures like diamonds (multiple paths converging) are allowed:
+
+```ruby
+electronics = Category.create!(name: "Electronics")
+phones      = Category.create!(name: "Phones")
+computers   = Category.create!(name: "Computers")
+chargers    = Category.create!(name: "Chargers")
+
+electronics.add_child(phones)
+electronics.add_child(computers)
+phones.add_child(chargers)
+computers.add_child(chargers)  # diamond — this is fine
+```
+
+### Seeding in migrations
+
+Use `Dagable::Migrations::Helper` to create records with edges in a single transaction:
+
+```ruby
+Dagable::Migrations::Helper.create_dagable_item(
+  Category,
+  { name: "Electronics" },
+  children: [phones, laptops],
+)
+```
+
+## Architecture
+
+### How the ancestry table works
+
+The ancestry table stores every reachable pair `(predecessor, successor)` with a `depth`:
+
+| predecessor_id | successor_id | depth |
+|----------------|--------------|-------|
+| Electronics | Electronics | 0 |
+| Phones | Phones | 0 |
+| Smartphones | Smartphones | 0 |
+| Electronics | Phones | 1 |
+| Phones | Smartphones | 1 |
+| Electronics | Smartphones | 2 |
+
+- **Depth 0** — self-referential row (every node has one)
+- **Depth 1** — direct parent-child relationship
+- **Depth N** — transitive relationship N edges apart
+
+This allows traversal queries to be simple JOINs:
+
+```sql
+-- self_and_successors for Electronics
+SELECT categories.*
+FROM categories
+INNER JOIN categories_ancestries ON categories_ancestries.successor_id = categories.id
+WHERE categories_ancestries.predecessor_id = electronics.id
+```
+
+### Key design decisions
+
+- **Two tables per model**: edges store direct relationships; ancestries store all transitive paths. This separation makes edge removal clean (delete edge, rebuild ancestries from remaining edges).
+- **Self-referential ancestry rows**: every node has a depth-0 row pointing to itself. This simplifies JOIN-based traversal by ensuring `self_and_successors` naturally includes the node itself.
+- **`link_ancestries` on Edge**: when an edge is created, the Edge computes the cross product of the parent's predecessors with the child's successors and bulk-inserts ancestry rows for each pair. This is idempotent (existing rows are skipped via `INSERT ... ON CONFLICT DO NOTHING`).
+- **Rebuild on removal**: when an edge is removed or a node is destroyed, all non-self ancestry rows are deleted and rebuilt from the remaining edges. This is the safest approach for correctness.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+Tests run against an in-memory SQLite database — no external database required.
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](LICENSE).

data/lib/dagable/ancestry.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Dagable
+  # Abstract base class for ancestry records. Each dagable
+  # model gets a concrete subclass (e.g. +Category::Ancestry+) backed by
+  # +{table}_ancestries+.
+  #
+  # Each row represents a path between a predecessor and successor with a
+  # given depth:
+  #
+  # - +depth 0+ — self-referential row (every node has one)
+  # - +depth 1+ — direct parent-child relationship
+  # - +depth N+ — transitive relationship N edges apart
+  class Ancestry < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/dagable/associations.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Dagable
+  # A dynamic module that, when included into an ActiveRecord model, declares
+  # all +has_many+ associations needed for the DAG. Constructed with the class
+  # names of the concrete Edge and Ancestry subclasses.
+  #
+  # == Declared associations
+  #
+  # Edge associations (direct relationships):
+  # - +parent_edges+ / +parents+ — direct parent records via the edge table
+  # - +child_edges+  / +children+ — direct child records via the edge table
+  #
+  # Ancestry associations (raw ancestry table rows):
+  # - +predecessor_connections+ — ancestry rows where this node is the successor
+  # - +successor_connections+   — ancestry rows where this node is the predecessor
+  #
+  # Traversal methods (+predecessors+, +successors+, +self_and_predecessors+,
+  # +self_and_successors+) are provided by +Dagable::InstanceMethods+ instead
+  # of +has_many :through+ to correctly exclude self-referential rows.
+  class Associations < Module
+    attr_reader :edge_class, :ancestry_class
+
+    def initialize(edge_class, ancestry_class)
+      super()
+
+      @edge_class = edge_class
+      @ancestry_class = ancestry_class
+    end
+
+    def included(base)
+      base.has_many :parent_edges, class_name: edge_class, foreign_key: :child_id, dependent: :destroy,
+                                   inverse_of: :child
+      base.has_many :parents, through: :parent_edges
+
+      base.has_many :child_edges, class_name: edge_class, foreign_key: :parent_id, dependent: :destroy,
+                                  inverse_of: :parent
+      base.has_many :children, through: :child_edges
+
+      base.has_many :predecessor_connections,
+                    class_name: ancestry_class,
+                    foreign_key: :successor_id,
+                    dependent: :destroy,
+                    inverse_of: :successor
+
+      base.has_many :successor_connections,
+                    class_name: ancestry_class,
+                    foreign_key: :predecessor_id,
+                    dependent: :destroy,
+                    inverse_of: :predecessor
+    end
+  end
+end

data/lib/dagable/edge.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dagable
+  # Abstract base class for direct edge records. Each dagable model gets a
+  # concrete subclass (e.g. +Category::Edge+) backed by +{table}_edges+.
+  #
+  # An edge represents a single direct parent-child relationship. When an edge
+  # is created, +link_ancestries+ must be called to update the transitive
+  # paths in the ancestry table.
+  class Edge < ActiveRecord::Base
+    self.abstract_class = true
+
+    # Materializes all transitive ancestry rows implied by this edge.
+    #
+    # For an edge (parent -> child), this computes the cross product of all
+    # predecessors of the parent with all successors of the child, and inserts
+    # an ancestry row for each pair. The depth is calculated as the sum of the
+    # predecessor's depth to the parent + the child's depth to the successor + 1.
+    #
+    # This is safe to call multiple times — existing ancestry rows are skipped
+    # via +INSERT ... ON CONFLICT DO NOTHING+.
+    def link_ancestries
+      ancestry_class = self.class.module_parent.const_get("Ancestry")
+      records = ancestry_records(ancestry_class)
+
+      ancestry_class.insert_all(records, unique_by: %i[predecessor_id successor_id]) if records.any?
+    end
+
+    private
+
+    # Builds the ancestry rows implied by this edge as a cross product.
+    #
+    # For an edge P -> C, every predecessor of P must be linked to every
+    # successor of C (including P and C themselves, via their depth-0 rows).
+    #
+    # == Example
+    #
+    # Given the chain A → B and a new edge B → C:
+    #
+    #   predecessor_rows (ancestry rows ending at B):
+    #     { predecessor_id: A, successor_id: B, depth: 1 }
+    #     { predecessor_id: B, successor_id: B, depth: 0 }  ← self-row
+    #
+    #   successor_rows (ancestry rows starting at C):
+    #     { predecessor_id: C, successor_id: C, depth: 0 }  ← self-row
+    #
+    #   cross product produces:
+    #     { predecessor_id: A, successor_id: C, depth: 1 + 0 + 1 = 2 }
+    #     { predecessor_id: B, successor_id: C, depth: 0 + 0 + 1 = 1 }
+    #
+    # @param ancestry_class [Class] the concrete Ancestry subclass
+    # @return [Array<Hash>] attribute hashes ready for +insert_all+
+    def ancestry_records(ancestry_class)
+      predecessor_rows = ancestry_class.where(successor_id: parent_id).to_a
+      successor_rows = ancestry_class.where(predecessor_id: child_id).to_a
+
+      predecessor_rows.flat_map do |pred|
+        successor_rows.map do |succ|
+          { predecessor_id: pred.predecessor_id, successor_id: succ.successor_id, depth: pred.depth + succ.depth + 1 }
+        end
+      end
+    end
+  end
+end

data/lib/dagable/errors/cyclic_association.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Dagable
+  module Errors
+    # Raised when adding an edge would introduce a cycle into the DAG.
+    # This includes self-referential edges (A -> A), direct cycles (A -> B -> A),
+    # and transitive cycles (A -> B -> C -> A).
+    class CyclicAssociation < StandardError
+      ERROR_MESSAGE = "Cyclic association detected between %<parent>s and %<child>s"
+
+      def initialize(parent, child)
+        super(format(ERROR_MESSAGE, parent: "#{parent.class}##{parent.id}", child: "#{child.class}##{child.id}"))
+      end
+    end
+  end
+end

data/lib/dagable/instance_methods.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Dagable
+  # Instance methods mixed into every dagable model. Provides the public API
+  # for managing edges and traversing the DAG.
+  module InstanceMethods
+    # Adds +parent+ as a direct parent of this node. Creates the edge record
+    # and updates the ancestry table with all implied transitive paths.
+    #
+    # @param parent [ActiveRecord::Base] the node to add as parent
+    # @raise [Dagable::Errors::CyclicAssociation] if adding this edge would
+    #   create a cycle (including self-referential edges)
+    def add_parent(parent)
+      ActiveRecord::Base.transaction do
+        raise Errors::CyclicAssociation.new(parent, self) if self_and_successors.exists?(id: parent.id)
+
+        edge = parent_edges.find_or_create_by!(parent_id: parent.id)
+        edge.link_ancestries
+      end
+    end
+
+    # Adds +child+ as a direct child of this node. Creates the edge record
+    # and updates the ancestry table with all implied transitive paths.
+    #
+    # @param child [ActiveRecord::Base] the node to add as child
+    # @raise [Dagable::Errors::CyclicAssociation] if adding this edge would
+    #   create a cycle (including self-referential edges)
+    def add_child(child)
+      ActiveRecord::Base.transaction do
+        raise Errors::CyclicAssociation.new(self, child) if self_and_predecessors.exists?(id: child.id)
+
+        edge = child_edges.find_or_create_by!(child_id: child.id)
+        edge.link_ancestries
+      end
+    end
+
+    # Removes +child+ as a direct child of this node. Deletes the edge record
+    # and rebuilds the ancestry table for the entire graph.
+    #
+    # @param child [ActiveRecord::Base] the child node to disconnect
+    def remove_child(child)
+      ActiveRecord::Base.transaction do
+        child_edges.where(child_id: child.id).delete_all
+        rebuild_ancestries
+      end
+    end
+
+    # Removes +parent+ as a direct parent of this node. Deletes the edge
+    # record and rebuilds the ancestry table for the entire graph.
+    #
+    # @param parent [ActiveRecord::Base] the parent node to disconnect
+    def remove_parent(parent)
+      ActiveRecord::Base.transaction do
+        parent_edges.where(parent_id: parent.id).delete_all
+        rebuild_ancestries
+      end
+    end
+
+    # Returns this node and all its transitive descendants as an
+    # +ActiveRecord::Relation+ via a single ancestry table JOIN.
+    #
+    # @return [ActiveRecord::Relation]
+    def self_and_successors
+      ancestry_table = ancestry_class.table_name
+      model_table = self.class.table_name
+
+      self.class
+          .joins("INNER JOIN #{ancestry_table} ON #{ancestry_table}.successor_id = #{model_table}.id")
+          .where("#{ancestry_table}.predecessor_id = ?", id)
+    end
+
+    # Returns this node and all its transitive ancestors as an
+    # +ActiveRecord::Relation+ via a single ancestry table JOIN.
+    #
+    # @return [ActiveRecord::Relation]
+    def self_and_predecessors
+      ancestry_table = ancestry_class.table_name
+      model_table = self.class.table_name
+
+      self.class
+          .joins("INNER JOIN #{ancestry_table} ON #{ancestry_table}.predecessor_id = #{model_table}.id")
+          .where("#{ancestry_table}.successor_id = ?", id)
+    end
+
+    # Returns all transitive descendants (excluding self) as an
+    # +ActiveRecord::Relation+.
+    #
+    # @return [ActiveRecord::Relation]
+    def successors
+      ancestry_table = ancestry_class.table_name
+      model_table = self.class.table_name
+
+      self.class
+          .joins("INNER JOIN #{ancestry_table} ON #{ancestry_table}.successor_id = #{model_table}.id")
+          .where("#{ancestry_table}.predecessor_id = ? AND #{ancestry_table}.depth > 0", id)
+    end
+
+    # Returns all transitive ancestors (excluding self) as an
+    # +ActiveRecord::Relation+.
+    #
+    # @return [ActiveRecord::Relation]
+    def predecessors
+      ancestry_table = ancestry_class.table_name
+      model_table = self.class.table_name
+
+      self.class
+          .joins("INNER JOIN #{ancestry_table} ON #{ancestry_table}.predecessor_id = #{model_table}.id")
+          .where("#{ancestry_table}.successor_id = ? AND #{ancestry_table}.depth > 0", id)
+    end
+
+    private
+
+    def edge_class = self.class.const_get("Edge")
+
+    def ancestry_class = self.class.const_get("Ancestry")
+
+    # Callback: inserts the self-referential ancestry row (depth 0) for this
+    # node. Every node must have one for the JOIN-based traversal to work.
+    def create_self_ancestry_row
+      ancestry_class.find_or_create_by!(
+        predecessor_id: id,
+        successor_id: id
+      ) { |row| row.depth = 0 }
+    end
+
+    # Rebuilds the entire ancestry table from direct edges. Deletes all
+    # non-self rows and replays +link_ancestries+ on every edge.
+    def rebuild_ancestries
+      ancestry = ancestry_class
+      ancestry.where.not(depth: 0).delete_all
+      edge_class.find_each(&:link_ancestries)
+    end
+  end
+end

data/lib/dagable/migration_helpers.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Dagable
+  # Schema helpers for creating the two supporting tables that every dagable
+  # model requires. Include this module in your migration class.
+  #
+  # == Usage
+  #
+  #   class CreateCategoryDag < ActiveRecord::Migration[8.1]
+  #     include Dagable::MigrationHelpers
+  #
+  #     def change
+  #       create_dagable_tables(:categories)
+  #     end
+  #   end
+  #
+  # This creates:
+  # - +categories_edges+ with +parent_id+ and +child_id+ columns, a unique
+  #   composite index, and foreign keys back to the source table
+  # - +categories_ancestries+ with +predecessor_id+, +successor_id+, and
+  #   +depth+ columns, a unique composite index, individual indexes on each
+  #   foreign key, and foreign keys back to the source table
+  module MigrationHelpers
+    # Creates the edge and ancestry tables for the given +source_table_name+.
+    #
+    # @param source_table_name [Symbol, String] the table name of the dagable
+    #   model (e.g. +:categories+)
+    def create_dagable_tables(source_table_name)
+      create_dagable_edges_table(source_table_name)
+      create_dagable_ancestries_table(source_table_name)
+    end
+
+    private
+
+    def create_dagable_edges_table(source_table_name)
+      edges_table = "#{source_table_name}_edges"
+
+      create_table edges_table do |t|
+        t.bigint :parent_id, null: false
+        t.bigint :child_id, null: false
+      end
+
+      add_index edges_table, %i[parent_id child_id], unique: true
+      add_foreign_key edges_table, source_table_name, column: :parent_id
+      add_foreign_key edges_table, source_table_name, column: :child_id
+    end
+
+    def create_dagable_ancestries_table(source_table_name)
+      ancestries_table = "#{source_table_name}_ancestries"
+
+      create_table ancestries_table do |t|
+        t.bigint :predecessor_id, null: false
+        t.bigint :successor_id, null: false
+        t.integer :depth, null: false, default: 0
+      end
+
+      add_index ancestries_table, %i[predecessor_id successor_id], unique: true
+      add_index ancestries_table, :predecessor_id
+      add_index ancestries_table, :successor_id
+      add_foreign_key ancestries_table, source_table_name, column: :predecessor_id
+      add_foreign_key ancestries_table, source_table_name, column: :successor_id
+    end
+  end
+end

data/lib/dagable/migrations/helper.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Dagable
+  module Migrations
+    # Convenience methods for seeding dagable records inside migrations or
+    # seed files. Wraps creation and edge wiring in a single transaction.
+    #
+    # == Usage
+    #
+    #   Dagable::Migrations::Helper.create_dagable_item(
+    #     Category,
+    #     { name: "Electronics" },
+    #     children: [phones, laptops],
+    #   )
+    module Helper
+      module_function
+
+      # Creates a dagable record and wires up parent/child edges in one
+      # transaction.
+      #
+      # @param model [Class] the dagable ActiveRecord model class
+      # @param attributes [Hash] attributes to pass to +model.create!+
+      # @param parents [Array] parent nodes or IDs to attach
+      # @param children [Array] child nodes or IDs to attach
+      # @return [ActiveRecord::Base] the created record
+      def create_dagable_item(model, attributes, parents: [], children: [])
+        ActiveRecord::Base.transaction do
+          item = model.create!(attributes)
+
+          Array(parents).each { |parent| item.add_parent(retrieve_item(model, parent)) }
+          Array(children).each { |child| item.add_child(retrieve_item(model, child)) }
+
+          item
+        end
+      end
+
+      # Resolves a reference to a dagable record. Accepts either a model
+      # instance or an integer ID.
+      #
+      # @param model [Class] the dagable ActiveRecord model class
+      # @param reference [ActiveRecord::Base, Integer] the record or its ID
+      # @return [ActiveRecord::Base]
+      # @raise [ArgumentError] if the reference type is unsupported
+      def retrieve_item(model, reference)
+        case reference
+        when model then reference
+        when Integer then model.find(reference)
+        else raise ArgumentError, "Invalid dagable item reference"
+        end
+      end
+    end
+  end
+end

data/lib/dagable/model.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Dagable
+  # Provides the +dagable+ class method that activates DAG behaviour on an
+  # ActiveRecord model. Extend this module in your model, then call +dagable+
+  # to set up edge and ancestry classes, associations, and instance methods.
+  #
+  # == Usage
+  #
+  #   class Category < ActiveRecord::Base
+  #     extend Dagable::Model
+  #
+  #     dagable
+  #   end
+  #
+  # Calling +dagable+ will:
+  #
+  # 1. Define +Category::Edge+ (subclass of +Dagable::Edge+) backed by
+  #    +categories_edges+
+  # 2. Define +Category::Ancestry+ (subclass of +Dagable::Ancestry+) backed by
+  #    +categories_ancestries+
+  # 3. Include +Dagable::Associations+ setting up +has_many+ relationships for
+  #    edges and ancestry connections
+  # 4. Include +Dagable::InstanceMethods+ providing +add_child+, +add_parent+,
+  #    traversal methods, etc.
+  # 5. Register an +after_create+ callback to insert the self-referential
+  #    ancestry row (depth 0) for every new record
+  module Model
+    def dagable
+      const_set("Edge", edge_class_definition)
+      const_set("Ancestry", ancestry_class_definition)
+
+      include Dagable::Associations.new(const_get("Edge").name, const_get("Ancestry").name)
+      include Dagable::InstanceMethods
+
+      after_create :create_self_ancestry_row
+      after_destroy :rebuild_ancestries
+    end
+
+    private
+
+    def edge_class_definition
+      klass_name = name
+      table = "#{table_name}_edges"
+
+      Class.new(Dagable::Edge) do
+        self.table_name = table
+
+        belongs_to :parent, class_name: klass_name, inverse_of: :child_edges
+        belongs_to :child, class_name: klass_name, inverse_of: :parent_edges
+      end
+    end
+
+    def ancestry_class_definition
+      klass_name = name
+      table = "#{table_name}_ancestries"
+
+      Class.new(Dagable::Ancestry) do
+        self.table_name = table
+
+        belongs_to :predecessor, class_name: klass_name, inverse_of: :successor_connections
+        belongs_to :successor, class_name: klass_name, inverse_of: :predecessor_connections
+      end
+    end
+  end
+end

data/lib/dagable/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Dagable
+  VERSION = "0.1.0"
+end

data/lib/dagable.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require_relative "dagable/version"
+require_relative "dagable/errors/cyclic_association"
+require_relative "dagable/edge"
+require_relative "dagable/ancestry"
+require_relative "dagable/associations"
+require_relative "dagable/instance_methods"
+require_relative "dagable/model"
+require_relative "dagable/migration_helpers"
+require_relative "dagable/migrations/helper"
+
+# Dagable provides directed acyclic graph (DAG) composition for ActiveRecord
+# models using a dedicated ancestry table. It materializes all transitive
+# paths so that traversal queries are single JOINs instead of recursive CTEs.
+#
+# == Quick start
+#
+#   class Category < ActiveRecord::Base
+#     extend Dagable::Model
+#
+#     dagable
+#   end
+#
+# This gives the model +add_child+, +add_parent+, +remove_child+,
+# +remove_parent+, and traversal methods (+self_and_successors+,
+# +self_and_predecessors+, +successors+, +predecessors+).
+#
+# == Database tables
+#
+# Each dagable model requires two supporting tables that can be created with
+# +Dagable::MigrationHelpers#create_dagable_tables+:
+#
+# - +{table}_edges+ — stores direct parent-child relationships
+# - +{table}_ancestries+ — stores all transitive paths with depth
+module Dagable; end

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: dagable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leandro Maduro
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+description: Provides reusable directed acyclic graph (DAG) composition via a dedicated
+  ancestry table for any ActiveRecord model.
+email:
+- leandromaduro1@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/dagable.rb
+- lib/dagable/ancestry.rb
+- lib/dagable/associations.rb
+- lib/dagable/edge.rb
+- lib/dagable/errors/cyclic_association.rb
+- lib/dagable/instance_methods.rb
+- lib/dagable/migration_helpers.rb
+- lib/dagable/migrations/helper.rb
+- lib/dagable/model.rb
+- lib/dagable/version.rb
+homepage: https://github.com/leandro-maduro/dagable
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: DAG infrastructure for ActiveRecord models
+test_files: []