related 0.1 → 0.2

data/CHANGELOG

@@ -1,4 +1,10 @@
 
+*0.2*
+
+* Implemented set operations.
+* Added Related::Follower module.
+* Added pagination support (sorted relationships).
+
 *0.1*
 
 * First public release

data/README.md

@@ -56,12 +56,55 @@ To get the results from a query:
     node.outgoing(:friends).to_a
     node.outgoing(:friends).count (or .size, which is memoized)
 
-You can also do set operations, like union, diff and intersect (not implemented yet):
+You can also do set operations, like union, diff and intersect:
 
     node1.outgoing(:friends).union(node2.outgoing(:friends))
     node1.outgoing(:friends).diff(node2.outgoing(:friends))
     node1.outgoing(:friends).intersect(node2.outgoing(:friends))
 
+Relationships are sorted based on when they were created, which means you can
+paginate them:
+
+    node.outgoing(:friends).relationship.per_page(100).page(1)
+    node.outgoing(:friends).relationship.per_page(100).page(rel)
+
+The second form paginates based on the id of the last relationship on the
+previous page. Useful for cases where explicit page numbers are not
+appropriate.
+
+Pagination only works for relationships. If you want to access nodes directly
+without going through the extra step of iterating through the relationship
+objects you will only get random nodes. Thus you can use .limit (or .per_page)
+like this to get a random selection of nodes:
+
+    node.outgoing(:friends).nodes.limit(5)
+
+Follower
+--------
+
+Related includes a helper module called Related::Follower that you can include
+in your node sub-class to get basic Twitter-like follow functionality:
+
+    class User < Related::Node
+      include Related::Follower
+    end
+
+    user1 = User.create
+    user2 = User.create
+
+    user1.follow!(user2)
+    user1.unfollow!(user2)
+    user2.followers
+    user1.following
+    user1.friends
+    user2.followed_by?(user1)
+    user1.following?(user2)
+    user2.followers_count
+    user1.following_count
+
+The two nodes does not need to be of the same type. You can for example have
+a User following a Page or whatever makes sense in your app.
+
 Development
 -----------
 

data/lib/related/exceptions.rb

@@ -1,4 +1,5 @@
 module Related
   class RelatedException < RuntimeError; end
   class NotFound < RelatedException; end
+  class InvalidQuery < RelatedException; end
 end

data/lib/related/follower.rb

@@ -0,0 +1,43 @@
+module Related
+  module Follower
+    def follow!(user)
+      Related::Relationship.create(:follow, self, user)
+    end
+
+    def unfollow!(user)
+      self.following.relationships.each do |rel|
+        if rel.end_node_id == user.id
+          rel.destroy
+        end
+      end
+    end
+
+    def followers
+      self.incoming(:follow)
+    end
+
+    def following
+      self.outgoing(:follow)
+    end
+
+    def friends
+      self.followers.intersect(self.following)
+    end
+
+    def followed_by?(user)
+      self.followers.include?(user)
+    end
+
+    def following?(user)
+      self.following.include?(user)
+    end
+
+    def followers_count
+      self.followers.size
+    end
+
+    def following_count
+      self.following.size
+    end
+  end
+end

data/lib/related/node.rb

@@ -3,13 +3,13 @@ module Related
     module QueryMethods
       def relationships
         query = self.query
-        query.entity_type = :relationships
+        query.result_type = :relationships
         query
       end
 
       def nodes
         query = self.query
-        query.entity_type = :nodes
+        query.result_type = :nodes
         query
       end
 
@@ -33,6 +33,16 @@ module Related
         query
       end
 
+      def per_page(count)
+        self.limit(count)
+      end
+
+      def page(nr)
+        query = self.query
+        query.page = nr
+        query
+      end
+
       def depth(depth)
         query = self.query
         query.depth = depth
@@ -65,10 +75,13 @@ module Related
     class Query
       include QueryMethods
 
-      attr_writer :entity_type
+      attr_reader :result
+
+      attr_writer :result_type
       attr_writer :relationship_type
       attr_writer :direction
       attr_writer :limit
+      attr_writer :page
       attr_writer :depth
       attr_writer :include_start_node
       attr_writer :destination
@@ -76,7 +89,7 @@ module Related
 
       def initialize(node)
         @node = node
-        @entity_type = :nodes
+        @result_type = :nodes
         @depth = 4
       end
 
@@ -89,28 +102,18 @@ module Related
       end
 
       def to_a
-        res = []
-        if @destination
-          res = self.send(@search_algorithm, [@node.id])
-          res.shift unless @include_start_node
-          return Related::Node.find(res)
+        perform_query unless @result
+        if @result_type == :nodes
+          Related::Node.find(@result)
         else
-          if @limit
-            res = (1..@limit.to_i).map { Related.redis.srandmember(key) }
-          else
-            res = Related.redis.smembers(key)
-          end
-        end
-        res = Relationship.find(res)
-        if @entity_type == :nodes
-          res = Related::Node.find(res.map {|rel| @direction == :in ? rel.start_node_id : rel.end_node_id })
-          res.unshift(@node) if @include_start_node
+          Related::Relationship.find(@result)
         end
-        res
       end
 
       def count
-        @count = Related.redis.scard(key)
+        @count = @result_type == :nodes ?
+          Related.redis.scard(key) :
+          Related.redis.zcard(key)
         @limit && @count > @limit ? @limit : @count
       end
 
@@ -118,24 +121,96 @@ module Related
         @count || count
       end
 
+      def include?(entity)
+        if @destination
+          self.to_a.include?(entity)
+        else
+          if entity.is_a?(Related::Node)
+            @result_type = :nodes
+            Related.redis.sismember(key, entity.to_s)
+          elsif entity.is_a?(Related::Relationship)
+            @result_type = :relationships
+            Related.redis.sismember(key, entity.to_s)
+          end
+        end
+      end
+
+      def union(query)
+        @result_type = :nodes
+        @result = Related.redis.sunion(key, query.key)
+        self
+      end
+
+      def diff(query)
+        @result_type = :nodes
+        @result = Related.redis.sdiff(key, query.key)
+        self
+      end
+
+      def intersect(query)
+        @result_type = :nodes
+        @result = Related.redis.sinter(key, query.key)
+        self
+      end
+
     protected
 
-      def key
-        "#{@node.id}:rel:#{@relationship_type}:#{@direction}"
+      def page_start
+        if @page.nil? || @page.to_i.to_s == @page.to_s
+          @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
+        end
+      end
+
+      def page_end
+        page_start + @limit.to_i - 1
+      end
+
+      def key(node=nil)
+        if @result_type == :nodes
+          "#{node ? node.to_s : @node.to_s}:nodes:#{@relationship_type}:#{@direction}"
+        else
+          "#{node ? node.to_s : @node.to_s}:rel:#{@relationship_type}:#{@direction}"
+        end
       end
 
       def query
         self
       end
 
+      def perform_query
+        @result = []
+        if @destination
+          @result_type = :nodes
+          @result = self.send(@search_algorithm, [@node.id])
+          @result.shift unless @include_start_node
+          @result
+        else
+          if @result_type == :nodes
+            if @limit
+              @result = (1..@limit.to_i).map { Related.redis.srandmember(key) }
+            else
+              @result = Related.redis.smembers(key)
+            end
+          else
+            if @limit
+              @result = Related.redis.zrange(key, page_start, page_end)
+            else
+              @result = Related.redis.zrange(key, 0, -1)
+            end
+          end
+        end
+      end
+
       def depth_first(nodes, depth = 0)
         return [] if depth > @depth
         nodes.each do |node|
-          key = "#{node}:nodes:#{@relationship_type}:#{@direction}"
-          if Related.redis.sismember(key, @destination.id)
+          if Related.redis.sismember(key(node), @destination.id)
             return [node, @destination.id]
           else
-            res = depth_first(Related.redis.smembers(key), depth+1)
+            res = depth_first(Related.redis.smembers(key(node)), depth+1)
             return [node] + res unless res.empty?
           end
         end
@@ -146,11 +221,10 @@ module Related
         return [] if depth > @depth
         shortest_path = []
         nodes.each do |node|
-          key = "#{node}:nodes:#{@relationship_type}:#{@direction}"
-          if Related.redis.sismember(key, @destination.id)
+          if Related.redis.sismember(key(node), @destination.id)
             return [node, @destination.id]
           else
-            res = dijkstra(Related.redis.smembers(key), depth+1)
+            res = dijkstra(Related.redis.smembers(key(node)), depth+1)
             if res.size > 0
               res = [node] + res
               if res.size < shortest_path.size || shortest_path.size == 0

data/lib/related/relationship.rb

@@ -16,9 +16,13 @@ module Related
       @end_node ||= Related::Node.find(end_node_id)
     end
 
-    def self.create(type, node1, node2, attributes = {})
+    def rank
+      Related.redis.zrank("#{self.start_node_id}:rel:#{self.label}:out", self.id)
+    end
+
+    def self.create(label, node1, node2, attributes = {})
       self.new(attributes.merge(
-        :type => type,
+        :label => label,
         :start_node_id => node1.to_s,
         :end_node_id => node2.to_s
       )).save
@@ -29,22 +33,23 @@ module Related
     def create
       Related.redis.multi do
         super
-        Related.redis.sadd("#{self.start_node_id}:rel:#{type}:out", self.id)
-        Related.redis.sadd("#{self.end_node_id}:rel:#{type}:in", self.id)
+        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.sadd("#{self.start_node_id}:nodes:#{type}:out", self.end_node_id)
-        Related.redis.sadd("#{self.end_node_id}:nodes:#{type}:in", self.start_node_id)
+        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)
       end
       self
     end
 
     def delete
       Related.redis.multi do
-        Related.redis.srem("#{self.start_node_id}:rel:#{type}:out", self.id)
-        Related.redis.srem("#{self.end_node_id}:rel:#{type}:in", self.id)
+        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:#{type}:out", self.end_node_id)
-        Related.redis.srem("#{self.end_node_id}:nodes:#{type}:in", self.start_node_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)
         super
       end
       self

data/lib/related/version.rb

@@ -1,3 +1,3 @@
 module Related
-  Version = VERSION = '0.1'
+  Version = VERSION = '0.2'
 end

data/test/follower_test.rb

@@ -0,0 +1,43 @@
+require File.expand_path('test/test_helper')
+require 'related/follower'
+
+class User < Related::Node
+  include Related::Follower
+end
+
+class FollowerTest < Test::Unit::TestCase
+
+  def setup
+    Related.redis.flushall
+    @user1 = User.create
+    @user2 = User.create
+  end
+
+  def test_can_follow
+    @user1.follow!(@user2)
+    assert @user1.following?(@user2)
+    assert @user2.followed_by?(@user1)
+  end
+
+  def test_can_unfollow
+    @user1.follow!(@user2)
+    @user1.unfollow!(@user2)
+    assert_equal false, @user1.following?(@user2)
+  end
+
+  def test_can_count_followers_and_following
+    @user1.follow!(@user2)
+    assert_equal 1, @user1.following_count
+    assert_equal 0, @user1.followers_count
+    assert_equal 0, @user2.following_count
+    assert_equal 1, @user2.followers_count
+  end
+
+  def test_can_compute_friends
+    @user1.follow!(@user2)
+    @user2.follow!(@user1)
+    assert_equal [@user2], @user1.friends.to_a
+    assert_equal [@user1], @user2.friends.to_a
+  end
+
+end

data/test/related_test.rb

@@ -131,7 +131,29 @@ class RelatedTest < Test::Unit::TestCase
     Related::Relationship.create(:friends, node1, node3)
     Related::Relationship.create(:friends, node1, node4)
     Related::Relationship.create(:friends, node1, node5)
-    assert_equal 3, node1.outgoing(:friends).limit(3).to_a.size
+    assert_equal 3, node1.outgoing(:friends).nodes.limit(3).to_a.size
+    assert_equal 3, node1.outgoing(:friends).relationships.limit(3).to_a.size
+  end
+
+  def test_can_paginate_the_results_from_a_query
+    node1 = Related::Node.create
+    node2 = Related::Node.create
+    node3 = Related::Node.create
+    node4 = Related::Node.create
+    node5 = Related::Node.create
+    rel1 = Related::Relationship.create(:friends, node1, node2)
+    sleep(1)
+    rel2 = Related::Relationship.create(:friends, node1, node3)
+    sleep(1)
+    rel3 = Related::Relationship.create(:friends, node1, node4)
+    sleep(1)
+    rel4 = Related::Relationship.create(:friends, node1, node5)
+    sleep(1)
+    rel5 = Related::Relationship.create(:friends, node1, node5)
+    assert_equal [rel1,rel2,rel3], node1.outgoing(:friends).relationships.per_page(3).page(1).to_a
+    assert_equal [rel4,rel5], node1.outgoing(:friends).relationships.per_page(3).page(2).to_a
+    assert_equal [rel2,rel3,rel4], node1.outgoing(:friends).relationships.per_page(3).page(rel1).to_a
+    assert_equal [rel4,rel5], node1.outgoing(:friends).relationships.per_page(3).page(rel3).to_a
   end
 
   def test_can_count_the_number_of_related_nodes
@@ -144,10 +166,14 @@ class RelatedTest < Test::Unit::TestCase
     rel1 = Related::Relationship.create(:friends, node1, node3)
     rel1 = Related::Relationship.create(:friends, node1, node4)
     rel1 = Related::Relationship.create(:friends, node1, node5)
-    assert_equal 4, node1.outgoing(:friends).count
-    assert_equal 4, node1.outgoing(:friends).size
-    assert_equal 3, node1.outgoing(:friends).limit(3).count
-    assert_equal 4, node1.outgoing(:friends).limit(5).count
+    assert_equal 4, node1.outgoing(:friends).nodes.count
+    assert_equal 4, node1.outgoing(:friends).nodes.size
+    assert_equal 3, node1.outgoing(:friends).nodes.limit(3).count
+    assert_equal 4, node1.outgoing(:friends).nodes.limit(5).count
+    assert_equal 4, node1.outgoing(:friends).relationships.count
+    assert_equal 4, node1.outgoing(:friends).relationships.size
+    assert_equal 3, node1.outgoing(:friends).relationships.limit(3).count
+    assert_equal 4, node1.outgoing(:friends).relationships.limit(5).count
   end
 
   def test_can_find_path_between_two_nodes
@@ -200,4 +226,43 @@ class RelatedTest < Test::Unit::TestCase
     assert_equal [node1,node2,node5,node8], node1.shortest_path_to(node8).outgoing(:friends).depth(5).include_start_node.to_a
   end
 
+  def test_can_union
+    node1 = Related::Node.create
+    node2 = Related::Node.create
+    node3 = Related::Node.create
+    node4 = Related::Node.create
+    Related::Relationship.create(:friends, node1, node3)
+    Related::Relationship.create(:friends, node2, node4)
+    Related::Relationship.create(:friends, node2, node3)
+    nodes = node1.outgoing(:friends).union(node2.outgoing(:friends)).to_a
+    assert_equal 2, nodes.size
+    assert nodes.include?(node3)
+    assert nodes.include?(node4)
+  end
+  
+  def test_can_diff
+    node1 = Related::Node.create
+    node2 = Related::Node.create
+    node3 = Related::Node.create
+    node4 = Related::Node.create
+    Related::Relationship.create(:friends, node1, node3)
+    Related::Relationship.create(:friends, node2, node4)
+    Related::Relationship.create(:friends, node2, node3)
+    nodes = node2.outgoing(:friends).diff(node1.outgoing(:friends)).to_a
+    assert_equal 1, nodes.size
+    assert nodes.include?(node4)
+  end
+
+  def test_can_intersect
+    node1 = Related::Node.create
+    node2 = Related::Node.create
+    Related::Relationship.create(:friends, node1, node2)
+    Related::Relationship.create(:friends, node2, node1)
+    assert_equal [node2], node1.outgoing(:friends).intersect(node1.incoming(:friends)).to_a
+    assert_equal [node1], node2.outgoing(:friends).intersect(node2.incoming(:friends)).to_a
+    node3 = Related::Node.create
+    Related::Relationship.create(:friends, node1, node3)
+    assert_equal [node1], node2.incoming(:friends).intersect(node3.incoming(:friends)).to_a
+  end
+
 end

data/test/test_helper.rb

@@ -2,6 +2,7 @@
 dir = File.dirname(File.expand_path(__FILE__))
 $LOAD_PATH.unshift dir + '/../lib'
 
+require 'rubygems'
 require 'test/unit'
 require 'related'
 

metadata

@@ -1,11 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: related
 version: !ruby/object:Gem::Version 
+  hash: 15
   prerelease: false
   segments: 
   - 0
-  - 1
-  version: "0.1"
+  - 2
+  version: "0.2"
 platform: ruby
 authors: 
 - Niklas Holmgren
@@ -13,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-09 00:00:00 +02:00
+date: 2011-09-14 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -24,6 +25,7 @@ dependencies:
     requirements: 
     - - ">"
       - !ruby/object:Gem::Version 
+        hash: 15
         segments: 
         - 2
         - 0
@@ -39,6 +41,7 @@ dependencies:
     requirements: 
     - - ">"
       - !ruby/object:Gem::Version 
+        hash: 63
         segments: 
         - 0
         - 8
@@ -62,11 +65,13 @@ files:
 - CHANGELOG
 - lib/related/entity.rb
 - lib/related/exceptions.rb
+- lib/related/follower.rb
 - lib/related/helpers.rb
 - lib/related/node.rb
 - lib/related/relationship.rb
 - lib/related/version.rb
 - lib/related.rb
+- test/follower_test.rb
 - test/performance_test.rb
 - test/redis-test.conf
 - test/related_test.rb
@@ -85,6 +90,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -93,6 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"