dagraph 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 55db1fe8fe777780fc058b9e709f1574f9f264f68fae09861bba8e4d90a9ea83
+  data.tar.gz: bc31712c6329ad2b96ab7643b49676bb34a2ca3e9cee59bee683d24228baafe7
+SHA512:
+  metadata.gz: a8410f16caec145acdd86980699494fb3c5843b1030a84da99d8f9092d6428f974df2543f31a342e3fae697011cfbff43752e36a3909bd28faf971dc5aff3ffe
+  data.tar.gz: 9da67d338b071d33f651f88fd34b491c83c5dbc0bddfa9a224c82006d7d04b3dfbe0a5a569da191981cb3368b2c298f8d64c85354e564ba821f68a5eabe32e50

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-05-31
+
+- Initial release
+
+## [1.0.0] - 2025-05-12
+
+- First stable release
+- Handle children and parents
+- Improve generator
+- Add support for multiple graphs in the same model
+- Handle weights for each edges

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in dagraph.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"
+
+gem "appraisal"
+gem "database_cleaner"
+gem "sqlite3"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Guillaume Dott
+
+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,85 @@
+# Dagraph
+
+Dagraph is a gem which allows you to represent DAG hierarchy using your ActiveRecord models.
+With a directed acyclic graph, you can represent hierarchical data where children may have multiple parents.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add dagraph
+
+To add a DAG to a model, you can use the generator:
+
+```
+bin/rails generate dagraph:model {MODEL_NAME}
+```
+
+It will add the required line to your model, create the file for the edges model and the required migration.
+
+## Usage
+
+After setting up a DAG in one of your model, the following methods are available to use the DAG:
+
+| Method name | Description |
+| ----------- | ----------- |
+| Model.roots | Get all objects without a parent |
+| Model.leaves | Get all objects without a child |
+| Model#parents | Get all parents (direct or not) attached to your object |
+| Model#children | Get all children (direct or not) attached to your object |
+| Model#parent\_edges | Get all parent edges attached to your object, this method return instances from your edge class |
+| Model#child\_edges | Get all children edges attached to your object, this method return instances from your edge class |
+| Model#direct\_parents | Get all direct parents attached to your object |
+| Model#direct\_children | Get all direct children attached to your object |
+| Model#direct\_parent\_edges | Get all direct parent edges attached to your object, this method return instances from your edge class |
+| Model#direct\_child\_edges | Get all direct children edges attached to your object, this method return instances from your edge class |
+| Model#parent\_of?(node) | Check if your object is a parent of the node |
+| Model#child\_of?(node) | Check if your object is a child of the node |
+| Model#direct\_parent\_of?(node) | Check if your object is a direct parent of the node |
+| Model#direct\_child\_of?(node) | Check if your object is a direct child of the node |
+| Model#childdren\_at\_depth(depth) | Get all children of your object at a specific depth |
+| Model#root? | Check if your object is at the root of your tree (it has no parent) |
+| Model#child? | Check if your object is not at the root of your tree (it has one or more parents) |
+| Model#leaf? | Check if your object is a leaf in your tree (it has no child) |
+
+You can add parents or children to your objects by using the `direct_parents` and `direct_children` associations:
+```ruby
+# Define all parents for your model
+model.direct_parents = [node]
+
+# Add one parent to your model
+model.direct_parents << node
+
+# Remove one parent for your model
+model.direct_parents.destroy(node)
+
+# Define all children for your model
+model.direct_children = [node]
+
+# Add one parent to your model
+model.direct_children << node
+
+# Remove one child for your model
+model.direct_children.destroy(node)
+
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Useful links about DAG
+
+https://www.codeproject.com/Articles/22824/A-Model-to-Represent-Directed-Acyclic-Graphs-DAG-o#Figure2
+https://arxiv.org/pdf/2211.11159
+https://www.baeldung.com/cs/dag-applications
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/gdott9/dagraph.
+
+## 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,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+task default: :test

data/lib/dagraph/edge_model.rb

@@ -0,0 +1,155 @@
+require 'active_support/concern'
+require 'active_support/core_ext/array/access'
+
+module Dagraph
+  module EdgeModel
+    extend ActiveSupport::Concern
+
+    included do
+      belongs_to :entry_edge, class_name: model_name.to_s, optional: true
+      belongs_to :direct_edge, class_name: model_name.to_s, optional: true
+      belongs_to :exit_edge, class_name: model_name.to_s, optional: true
+
+      belongs_to :parent, class_name: _dagraph.nodes_class_name
+      belongs_to :child, class_name: _dagraph.nodes_class_name
+
+      scope :direct, -> { where hops: 0 }
+      scope :implicit, -> { where.not hops: 0 }
+
+      attr_readonly :entry_edge_id, :direct_edge_id, :exit_edge_id,
+        :parent_id, :child_id, :hops, :source
+
+      after_create :add_implicit_edges!
+      after_save :calculate_implicit_edges_weight!
+
+      before_destroy :check_readonly
+      before_destroy :destroy_implicit_edges!
+      after_destroy :calculate_direct_edges_weight!
+
+      validate :_dagraph_cycle_detection
+    end
+
+    def direct?
+      hops.zero?
+    end
+
+    def implicit?
+      !direct?
+    end
+
+    def readonly?
+      implicit?
+    end
+
+    def dependent_implicit_edges
+      edges_list = self.class.where(direct_edge: self).pluck(:id)
+      loop do
+        new_edges_list = self.class.where.not(id: edges_list)
+          .and(
+            self.class.where(entry_edge_id: edges_list).or(self.class.where(exit_edge_id: edges_list))
+          )
+        edges_list += new_edges_list
+        break if new_edges_list.empty?
+      end
+
+      self.class.where(id: edges_list.excluding(id))
+    end
+
+    private
+
+    def check_readonly
+      _raise_readonly_record_error if readonly?
+    end
+
+    def direct_edges
+      @direct_edges ||= self.class.direct.where(child: child, source: source)
+    end
+
+    def add_implicit_edges!
+      return unless direct?
+
+      self.class.with_advisory_lock("dagraph_#{self.class.table_name}") do
+        self.class.where(id: id).update_all(entry_edge_id: id, direct_edge_id: id, exit_edge_id: id)
+
+        direct_edges_count = direct_edges.count
+        if direct_edges_count > 1
+          update_column :weight, weight / direct_edges_count
+          direct_edges.where.not(id: self).each do |edge|
+            edge.update! weight: edge.weight * (direct_edges_count - 1) / direct_edges_count
+          end
+        end
+
+        source_condition = source ? "= ?" : "IS NULL"
+        select = self.class.sanitize_sql_array(
+          [
+            "x.id, :id, :id, x.parent_id, :child_id, x.hops + 1, x.weight * :weight / 100, x.source",
+            id: id, child_id: child_id, weight: weight
+          ]
+        )
+        where = self.class.sanitize_sql_for_conditions(
+          ["x.child_id = ? AND x.source #{source_condition}", parent_id, source].compact
+        )
+        self.class.connection.exec_insert insert_query(select, where)
+
+        select = self.class.sanitize_sql_array(
+          [
+            ":id, :id, x.id, :parent_id, x.child_id, x.hops + 1, x.weight * :weight / 100, x.source",
+            id: id, parent_id: parent_id, weight: weight
+          ]
+        )
+        where = self.class.sanitize_sql_for_conditions(
+          ["x.parent_id = ? AND x.source #{source_condition}", child_id, source].compact
+        )
+        self.class.connection.exec_insert insert_query(select, where)
+
+        select = self.class.sanitize_sql_array(
+          [
+            "x.id, :id, y.id, x.parent_id, y.child_id, x.hops + y.hops + 2, x.weight * y.weight * :weight / 10000, x.source",
+            id: id, weight: weight
+          ]
+        )
+        where = self.class.sanitize_sql_for_conditions(
+          ["x.child_id = ? AND y.parent_id = ? AND x.source #{source_condition} AND y.source #{source_condition}", parent_id, child_id, source, source].compact
+        )
+        self.class.connection.exec_insert insert_query(select, where, cross_join: true)
+      end
+    end
+
+    def insert_query(select, where, cross_join: false)
+      <<-SQL.squish
+        INSERT INTO #{self.class.quoted_table_name}
+          (entry_edge_id, direct_edge_id, exit_edge_id, parent_id, child_id, hops, weight, source)
+          SELECT #{select}
+          FROM #{self.class.quoted_table_name} x
+          #{cross_join ? "CROSS JOIN #{self.class.quoted_table_name} y" : ''}
+          WHERE #{where}
+      SQL
+    end
+
+    def destroy_implicit_edges!
+      return unless direct?
+
+      dependent_implicit_edges.delete_all
+    end
+
+    def calculate_implicit_edges_weight!
+      return unless direct? && weight_previously_changed?
+
+      dependent_implicit_edges.update_all(
+        self.class.sanitize_sql_array(["weight = weight * ? / ?", weight, weight_previously_was])
+      )
+    end
+
+    def calculate_direct_edges_weight!
+      direct_edges.each do |edge|
+        edge.update! weight: edge.weight + weight / direct_edges.size
+      end
+    end
+
+    def _dagraph_cycle_detection
+      if parent == child || child.parent_of?(parent)
+        errors.add :base, :cycle_detected, message: 'You cannot add a parent as a child'
+      end
+    end
+  end
+end

data/lib/dagraph/has_directed_acyclic_graph.rb

@@ -0,0 +1,19 @@
+module Dagraph
+  module HasDirectedAcyclicGraph
+    def has_directed_acyclic_graph(options = {})
+      class_attribute :_dagraph
+      self._dagraph = Dagraph::NodeConfig.new(self, **options)
+      include Dagraph::NodeModel
+
+      _dagraph.edges_class.is_directed_acyclic_graph_edge _dagraph
+    end
+    alias_method :has_dag, :has_directed_acyclic_graph
+
+    def is_directed_acyclic_graph_edge(node_config)
+      class_attribute :_dagraph
+      self._dagraph = node_config
+
+      include Dagraph::EdgeModel
+    end
+  end
+end

data/lib/dagraph/node_config.rb

@@ -0,0 +1,24 @@
+module Dagraph
+  class NodeConfig
+    def initialize(model_class, **options)
+      @model_class = model_class
+      @options = options
+    end
+
+    def nodes_class_name
+      @model_class.to_s
+    end
+
+    def nodes_class
+      @model_class
+    end
+
+    def edges_class_name
+      "#{@model_class}Edge"
+    end
+
+    def edges_class
+      edges_class_name.constantize
+    end
+  end
+end

data/lib/dagraph/node_model.rb

@@ -0,0 +1,93 @@
+require 'active_support/concern'
+
+module Dagraph
+  module NodeModel
+    extend ActiveSupport::Concern
+
+    included do
+      scope :roots, -> { where.not id: _dagraph.edges_class.select(:child_id) }
+      scope :leaves, -> { where.not id: _dagraph.edges_class.select(:parent_id) }
+
+      has_many :parent_edges, class_name: _dagraph.edges_class_name, foreign_key: :child_id
+      has_many :parents, -> { distinct }, class_name: model_name.to_s, through: :parent_edges
+      has_many :child_edges, class_name: _dagraph.edges_class_name, foreign_key: :parent_id
+      has_many :children, -> { distinct }, class_name: model_name.to_s, through: :child_edges
+
+      has_many :roots, -> { distinct.roots }, class_name: model_name.to_s, through: :parent_edges, source: :parent
+      has_many :leaves, -> { distinct.leaves }, class_name: model_name.to_s, through: :child_edges, source: :child
+
+      has_many :direct_parent_edges, -> { direct }, class_name: _dagraph.edges_class_name, foreign_key: :child_id, inverse_of: :child, dependent: :destroy
+      has_many :direct_parents, -> { distinct }, class_name: model_name.to_s, through: :direct_parent_edges, source: :parent, dependent: :destroy
+      has_many :direct_child_edges, -> { direct }, class_name: _dagraph.edges_class_name, foreign_key: :parent_id, inverse_of: :parent, dependent: :destroy
+      has_many :direct_children, -> { distinct }, class_name: model_name.to_s, through: :direct_child_edges, source: :child, dependent: :destroy
+    end
+
+    def parents_to_hash(depth: nil)
+      graph_to_hash parents, :direct_children, depth: depth
+    end
+
+    def children_to_hash(depth: nil)
+      graph_to_hash children, :direct_parents, depth: depth
+    end
+
+    def children_at_depth(depth)
+      self.class.where id: child_edges.where(hops: depth - 1).select(:child_id)
+    end
+
+    def self_and_children
+      self.class.where(id: self).or(self.class.where(id: children))
+    end
+
+    def parent_of?(node)
+      return false if node.nil?
+      children.include?(node)
+    end
+
+    def child_of?(node)
+      return false if node.nil?
+      node.parent_of?(self)
+    end
+
+    def direct_parent_of?(node)
+      return false if node.nil?
+      direct_children.include?(node)
+    end
+
+    def direct_child_of?(node)
+      return false if node.nil?
+      node.direct_parent_of?(self)
+    end
+
+    def root?
+      parent_edges.empty?
+    end
+
+    def child?
+      !root?
+    end
+
+    def leaf?
+      child_edges.empty?
+    end
+
+    private
+
+    def graph_to_hash(nodes, association, depth: nil)
+      hash = {self => {}}
+      ids = {self => hash[self]}
+
+      nodes = nodes.where(self.class._dagraph.edges_class.table_name => {hops: ..depth - 1}) if depth.present? && depth > 0
+
+      nodes.includes(association).each do |node|
+        ids[node] = {} unless ids.key?(node)
+
+        node.send(association).each do |parent_node|
+          ids[parent_node] = {} unless ids.key?(parent_node)
+          ids[parent_node][node] = ids[node]
+        end
+      end
+
+      hash
+    end
+  end
+end

data/lib/dagraph/version.rb

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

data/lib/dagraph.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "dagraph/version"
+
+require 'active_support'
+require 'with_advisory_lock'
+
+require_relative "dagraph/has_directed_acyclic_graph"
+require_relative "dagraph/node_config"
+require_relative "dagraph/node_model"
+require_relative "dagraph/edge_model"
+
+ActiveSupport.on_load :active_record do
+  ActiveRecord::Base.send :extend, Dagraph::HasDirectedAcyclicGraph
+end

data/lib/generators/dagraph/model_generator.rb

@@ -0,0 +1,53 @@
+require 'rails/generators/active_record'
+
+module Dagraph
+  module Generators # :nodoc:
+    class ModelGenerator < Rails::Generators::NamedBase # :nodoc:
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def self.next_migration_number(number)
+        ActiveRecord::Generators::Base.next_migration_number(number)
+      end
+
+      def add_dag_line_to_node_model
+        inject_into_class "app/models/#{klass.model_name.singular}.rb", klass.to_s do
+          "  has_directed_acyclic_graph\n"
+        end
+      end
+      def create_edge_model_file
+        create_file "app/models/#{dagraph.edges_class_name.underscore}.rb", <<~RUBY
+          class #{dagraph.edges_class_name} < ApplicationRecord
+          end
+        RUBY
+      end
+
+      def create_migration_file
+        migration_template 'create_edges.rb.erb', "db/migrate/create_#{migration_name}.rb"
+      end
+
+      private
+
+      def migration_name
+        dagraph.edges_class_name.underscore.pluralize
+      end
+
+      def migration_class_name
+        "Create#{migration_name.camelize}"
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      def klass
+        @klass ||= class_name.camelize.constantize
+      end
+
+      def dagraph
+        @dagraph ||= Dagraph::NodeConfig.new(klass)
+      end
+    end
+  end
+end

data/lib/generators/dagraph/templates/create_edges.rb.erb

@@ -0,0 +1,14 @@
+class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= migration_name %>, force: true do |t|
+      t.references :entry_edge, null: true, foreign_key: {to_table: :<%= migration_name %>}
+      t.references :direct_edge, null: true, foreign_key: {to_table: :<%= migration_name %>}
+      t.references :exit_edge, null: true, foreign_key: {to_table: :<%= migration_name %>}
+      t.references :parent, null: false, foreign_key: {to_table: :<%= klass.table_name %>}
+      t.references :child, null: false, foreign_key: {to_table: :<%= klass.table_name %>}
+      t.integer :hops, index: true, null: false, default: 0
+      t.float :weight, null: false, default: 100
+      t.string :source, index: true, null: false, default: 'default'
+    end
+  end
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: dagraph
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Guillaume Dott
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-05-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 9.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 9.0.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 9.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 9.0.0
+- !ruby/object:Gem::Dependency
+  name: with_advisory_lock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+description: |
+  Dagraph is a gem which allows you to represent DAG hierarchy using your ActiveRecord models.
+  With a directed acyclic graph, you can represent hierarchical data where children may have multiple parents.
+email:
+- guillaume+github@dott.fr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- dagger.png
+- lib/dagraph.rb
+- lib/dagraph/edge_model.rb
+- lib/dagraph/has_directed_acyclic_graph.rb
+- lib/dagraph/node_config.rb
+- lib/dagraph/node_model.rb
+- lib/dagraph/version.rb
+- lib/generators/dagraph/model_generator.rb
+- lib/generators/dagraph/templates/create_edges.rb.erb
+homepage: https://github.com/gdott9/dagraph
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/gdott9/dagraph
+  changelog_uri: https://github.com/gdott9/dagraph/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Add support for directed acyclic graphs (DAG) to your ActiveRecord model
+test_files: []