related 0.3.1 → 0.4.0

data/CHANGELOG

@@ -1,4 +1,10 @@
 
+*0.4*
+
+* Related.root
+* Custom relationship weights
+* More compact key format
+
 *0.3*
 
 * ActiveModel support

data/README.md

@@ -112,6 +112,26 @@ like this to get a random selection of nodes:
 node.outgoing(:friends).nodes.limit(5)
 ```
 
+The root node
+-------------
+
+Related provides a special kind of node called the "root" node. It's always
+accessible using the `Related.root` helper and you can create a relationship
+between any node and the root node, which is useful if you want to easily
+access a set of nodes without knowing the IDs of those nodes.
+
+```ruby
+Related::Relationship.create(:example, Related.root, node)
+Related.root.outgoing(:example)
+```
+
+You can even add attributes to the root node if you want.
+
+```ruby
+Related.root.name = 'The root'
+Related.root.save
+```
+
 Properties
 ----------
 
@@ -161,6 +181,42 @@ node.outgoing(:attending).options(
 )
 ```
 
+Weight
+------
+
+All relationships have an associated weight on its incoming and outgoing
+links. By default the weight is set to the time when the relationship was
+created. That makes the result from a query that fetches relationships always
+sorted so that newer relationships appear first, which is nice. If you create
+a custom Related::Relationship sub-class you can define how the weight is
+generated for a relationship.
+
+```ruby
+class Comment < Related::Relationship
+  property :created_at, Time
+  property :points, Integer
+  weight do |direction|
+    if direction == :in
+      self.created_at
+    elsif direction == :out
+      self.points
+    end
+  end
+end
+```
+
+The weight is always an integer and is sorted in descending order.
+
+The weight for the links get updated every time the relationship is saved. So
+if you update the points for a Comment in the example above, the weight is
+automatically updated. You can access the weight and rank (0 based position)
+of a relationship like this:
+
+```ruby
+comment.weight(:out)
+comment.rank(:in)
+```
+
 ActiveModel
 -----------
 

data/lib/related/exceptions.rb

@@ -2,5 +2,12 @@ module Related
   class RelatedException < RuntimeError; end
   class NotFound < RelatedException; end
   class InvalidQuery < RelatedException; end
-  class ValidationsFailed < RelatedException; end
+  class ValidationsFailed < RelatedException
+    attr_reader :object
+    def initialize(object)
+      @object = object
+      errors = @object.errors.full_messages.to_sentence
+      super(errors)
+    end
+  end
 end

data/lib/related/helpers.rb

@@ -11,5 +11,10 @@ module Related
       ).gsub('/','x').gsub('+','y').gsub('=','').strip
     end
 
+    # Returns the root node for the graph
+    def root
+      @root ||= Related::Root.new
+    end
+
   end
 end

data/lib/related/node.rb

@@ -46,6 +46,7 @@ module Related
       def page(nr)
         query = self.query
         query.page = nr
+        query.result_type = :relationships
         query
       end
 
@@ -176,7 +177,7 @@ module Related
           @page && @page.to_i != 1 ? (@page.to_i * @limit.to_i) - @limit.to_i : 0
         else
           rel = @page.is_a?(String) ? Related::Relationship.find(@page) : @page
-          rel.rank + 1
+          rel.rank(@direction) + 1
         end
       end
 
@@ -186,9 +187,9 @@ module Related
 
       def key(node=nil)
         if @result_type == :nodes
-          "#{node ? node.to_s : @node.to_s}:nodes:#{@relationship_type}:#{@direction}"
+          "#{node ? node.to_s : @node.to_s}:n:#{@relationship_type}:#{@direction}"
         else
-          "#{node ? node.to_s : @node.to_s}:rel:#{@relationship_type}:#{@direction}"
+          "#{node ? node.to_s : @node.to_s}:r:#{@relationship_type}:#{@direction}"
         end
       end
 

data/lib/related/relationship.rb

@@ -18,8 +18,16 @@ module Related
       @end_node ||= Related::Node.find(end_node_id)
     end
 
-    def rank
-      Related.redis.zrevrank("#{self.start_node_id}:rel:#{self.label}:out", self.id)
+    def rank(direction)
+      Related.redis.zrevrank(r_key(direction), self.id)
+    end
+
+    def weight(direction)
+      Related.redis.zscore(r_key(direction), self.id).to_i
+    end
+
+    def self.weight(&block)
+      @weight = block
     end
 
     def self.create(label, node1, node2, attributes = {})
@@ -32,26 +40,58 @@ module Related
 
   private
 
+    def r_key(direction)
+      if direction.to_sym == :out
+        "#{self.start_node_id}:r:#{self.label}:out"
+      elsif direction.to_sym == :in
+        "#{self.end_node_id}:r:#{self.label}:in"
+      end
+    end
+
+    def n_key(direction)
+      if direction.to_sym == :out
+        "#{self.start_node_id}:n:#{self.label}:out"
+      elsif direction.to_sym == :in
+        "#{self.end_node_id}:n:#{self.label}:in"
+      end
+    end
+
+    def self.weight_for(relationship, direction)
+      if @weight
+        relationship.instance_exec(direction, &@weight).to_i
+      else
+        Time.parse(relationship.created_at).to_i
+      end
+    end
+
     def create
       Related.redis.multi do
         super
-        score = Time.now.to_i
-        Related.redis.zadd("#{self.start_node_id}:rel:#{self.label}:out", score, self.id)
-        Related.redis.zadd("#{self.end_node_id}:rel:#{self.label}:in", score, self.id)
+        Related.redis.zadd(r_key(:out), self.class.weight_for(self, :out), self.id)
+        Related.redis.zadd(r_key(:in), self.class.weight_for(self, :in), self.id)
+        Related.redis.sadd(n_key(:out), self.end_node_id)
+        Related.redis.sadd(n_key(:in), self.start_node_id)
+      end
+      self
+    end
 
-        Related.redis.sadd("#{self.start_node_id}:nodes:#{self.label}:out", self.end_node_id)
-        Related.redis.sadd("#{self.end_node_id}:nodes:#{self.label}:in", self.start_node_id)
+    def update
+      Related.redis.multi do
+        super
+        Related.redis.zadd(r_key(:out), self.class.weight_for(self, :out), self.id)
+        Related.redis.zadd(r_key(:in), self.class.weight_for(self, :in), self.id)
+        Related.redis.sadd(n_key(:out), self.end_node_id)
+        Related.redis.sadd(n_key(:in), self.start_node_id)
       end
       self
     end
 
     def delete
       Related.redis.multi do
-        Related.redis.zrem("#{self.start_node_id}:rel:#{self.label}:out", self.id)
-        Related.redis.zrem("#{self.end_node_id}:rel:#{self.label}:in", self.id)
-
-        Related.redis.srem("#{self.start_node_id}:nodes:#{self.label}:out", self.end_node_id)
-        Related.redis.srem("#{self.end_node_id}:nodes:#{self.label}:in", self.start_node_id)
+        Related.redis.zrem(r_key(:out), self.id)
+        Related.redis.zrem(r_key(:in), self.id)
+        Related.redis.srem(n_key(:out), self.end_node_id)
+        Related.redis.srem(n_key(:in), self.start_node_id)
         super
       end
       self

data/lib/related/root.rb

@@ -0,0 +1,10 @@
+module Related
+  class Root < Related::Node
+
+    def initialize(attributes = {})
+      @id = 'root'
+      super(attributes)
+    end
+
+  end
+end

data/lib/related/version.rb

@@ -1,3 +1,3 @@
 module Related
-  Version = VERSION = '0.3.1'
+  Version = VERSION = '0.4.0'
 end

data/lib/related.rb

@@ -8,6 +8,7 @@ require 'related/exceptions'
 require 'related/entity'
 require 'related/node'
 require 'related/relationship'
+require 'related/root'
 
 module Related
   include Helpers

data/test/active_model_test.rb

@@ -85,6 +85,11 @@ class ActiveModelTest < ActiveModel::TestCase
     assert_raises Related::ValidationsFailed do
       like.save
     end
+    begin
+      like.save
+    rescue Related::ValidationsFailed => e
+      assert_equal like, e.object
+    end
     like.how_much = 1.0
     assert_equal true, like.valid?
     assert_nothing_raised do

data/test/model_test.rb

@@ -12,6 +12,12 @@ class ModelTest < ActiveModel::TestCase
     end
   end
 
+  class Like < Related::Relationship
+    weight do |dir|
+      dir == :in ? in_score : out_score
+    end
+  end
+
   def setup
     Related.redis.flushall
   end
@@ -46,4 +52,30 @@ class ModelTest < ActiveModel::TestCase
     assert_equal Event, nodes.first.class
   end
 
+  def test_custom_weight
+    node1 = Related::Node.create
+    node2 = Related::Node.create
+    like = Like.create(:like, node1, node2, :in_score => 42, :out_score => 10)
+    assert_equal 42, like.weight(:in)
+    assert_equal 10, like.weight(:out)
+    like.in_score = 50
+    like.save
+    assert_equal 50, like.weight(:in)
+    assert_equal 10, like.weight(:out)
+  end
+
+  def test_weight_sorting
+    node1 = Related::Node.create
+    node2 = Related::Node.create
+    node3 = Related::Node.create
+    rel1 = Like.create(:like, node1, node2, :in_score => 1, :out_score => 1)
+    rel2 = Like.create(:like, node1, node3, :in_score => 2, :out_score => 2)
+    rel3 = Like.create(:like, node2, node1, :in_score => 1, :out_score => 1)
+    rel4 = Like.create(:like, node3, node1, :in_score => 2, :out_score => 2)
+    assert_equal [rel2,rel1], node1.outgoing(:like).relationships.options(:model => lambda { Like }).to_a
+    assert_equal [rel4,rel3], node1.incoming(:like).relationships.options(:model => lambda { Like }).to_a
+    assert_equal [rel1], node1.outgoing(:like).relationships.options(:model => lambda { Like }).per_page(2).page(rel2).to_a
+    assert_equal [rel3], node1.incoming(:like).relationships.options(:model => lambda { Like }).per_page(2).page(rel4).to_a
+  end
+
 end

data/test/related_test.rb

@@ -102,9 +102,9 @@ class RelatedTest < Test::Unit::TestCase
   def test_can_create_a_relationship_with_attributes
     node1 = Related::Node.create(:name => 'One')
     node2 = Related::Node.create(:name => 'Two')
-    rel = Related::Relationship.create(:friends, node1, node2, :weight => 2.5)
+    rel = Related::Relationship.create(:friends, node1, node2, :score => 2.5)
     rel = Related::Relationship.find(rel.id)
-    assert_equal '2.5', rel.weight
+    assert_equal '2.5', rel.score
   end
 
   def test_can_delete_a_relationship
@@ -141,6 +141,7 @@ class RelatedTest < Test::Unit::TestCase
     node3 = Related::Node.create
     node4 = Related::Node.create
     node5 = Related::Node.create
+    node6 = Related::Node.create
     rel1 = Related::Relationship.create(:friends, node1, node2, :name => 'rel1')
     sleep(1)
     rel2 = Related::Relationship.create(:friends, node1, node3, :name => 'rel2')
@@ -149,12 +150,12 @@ class RelatedTest < Test::Unit::TestCase
     sleep(1)
     rel4 = Related::Relationship.create(:friends, node1, node5, :name => 'rel4')
     sleep(1)
-    rel5 = Related::Relationship.create(:friends, node1, node5, :name => 'rel5')
-    assert_equal [rel5,rel4,rel3], node1.outgoing(:friends).relationships.per_page(3).page(1).to_a
-    assert_equal [rel2,rel1], node1.outgoing(:friends).relationships.per_page(3).page(2).to_a
-    assert_equal [rel5,rel4,rel3], node1.outgoing(:friends).relationships.per_page(3).page(nil).to_a
-    assert_equal [rel4,rel3,rel2], node1.outgoing(:friends).relationships.per_page(3).page(rel5).to_a
-    assert_equal [rel2,rel1], node1.outgoing(:friends).relationships.per_page(3).page(rel3).to_a
+    rel5 = Related::Relationship.create(:friends, node1, node6, :name => 'rel5')
+    assert_equal [rel5,rel4,rel3], node1.outgoing(:friends).per_page(3).page(1).to_a
+    assert_equal [rel2,rel1], node1.outgoing(:friends).per_page(3).page(2).to_a
+    assert_equal [rel5,rel4,rel3], node1.outgoing(:friends).per_page(3).page(nil).to_a
+    assert_equal [rel4,rel3,rel2], node1.outgoing(:friends).per_page(3).page(rel5).to_a
+    assert_equal [rel2,rel1], node1.outgoing(:friends).per_page(3).page(rel3).to_a
   end
 
   def test_can_count_the_number_of_related_nodes
@@ -285,4 +286,13 @@ class RelatedTest < Test::Unit::TestCase
     end
   end
 
+  def test_root
+    assert_kind_of Related::Node, Related.root
+    node = Related::Node.create
+    rel = Related::Relationship.create(:friend, Related.root, node)
+    assert_equal [node], Related.root.outgoing(:friend).to_a
+    Related.root.name = 'Test'
+    Related.root.save
+  end
+
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: related
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 15
   prerelease: false
   segments: 
   - 0
-  - 3
-  - 1
-  version: 0.3.1
+  - 4
+  - 0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Niklas Holmgren
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-10 00:00:00 +02:00
+date: 2011-10-11 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -84,6 +84,7 @@ files:
 - lib/related/helpers.rb
 - lib/related/node.rb
 - lib/related/relationship.rb
+- lib/related/root.rb
 - lib/related/version.rb
 - lib/related.rb
 - test/active_model_test.rb