amico 2.1.0 → 2.2.0

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # CHANGELOG
 
+## 2.2.0 (2012-08-27)
+
+* Added `clear(id, scope = Amico.default_scope_key)` method to clear all relationships (in either direction) stored for an individual.
+
+Added the following methods for the blocked by relationship:
+
+* `blocked_by?(id, blocked_by_id, scope = Amico.default_scope_key)`
+* `blocked_by(id, page_options = default_paging_options, scope = Amico.default_scope_key)`
+* `blocked_by_count(id, scope = Amico.default_scope_key)`
+* `blocked_by_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)`
+
+Added the following methods for the pending with relationship:
+
+* `pending_with?(id, blocked_by_id, scope = Amico.default_scope_key)`
+* `pending_with(id, page_options = default_paging_options, scope = Amico.default_scope_key)`
+* `pending_with_count(id, scope = Amico.default_scope_key)`
+* `pending_with_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)`
+
+Thanks to [Skip Baney](https://github.com/twelvelabs) for all the work on this release.
+
 ## 2.1.0 (2012-08-20)
 
 * Added `count(id, type, scope = Amico.default_scope_key)` and `page_count(id, type, page_size = Amico.page_size, scope = Amico.default_scope_key)` as convenience methods for retrieving the count or the page count for the various types of relationships.

data/README.md

@@ -26,8 +26,10 @@ Amico.configure do |configuration|
   configuration.following_key = 'following'
   configuration.followers_key = 'followers'
   configuration.blocked_key = 'blocked'
+  configuration.blocked_by_key = 'blocked_by'
   configuration.reciprocated_key = 'reciprocated'
   configuration.pending_key = 'pending'
+  configuration.pending_with_key = 'pending_with'
   configuration.default_scope_key = 'default'
   configuration.pending_follow = false
   configuration.page_size = 25
@@ -46,8 +48,10 @@ Amico.configure do |configuration|
   configuration.following_key = 'following'
   configuration.followers_key = 'followers'
   configuration.blocked_key = 'blocked'
+  configuration.blocked_by_key = 'blocked_by'
   configuration.reciprocated_key = 'reciprocated'
   configuration.pending_key = 'pending'
+  configuration.pending_with_key = 'pending_with'
   configuration.default_scope_key = 'default'
   configuration.pending_follow = false
   configuration.page_size = 25
@@ -98,12 +102,18 @@ Amico.following?(11, 1)
 Amico.blocked?(1, 11)
  => true
 
+Amico.blocked_by?(11, 1)
+ => true
+
 Amico.unblock(1, 11)
  => true
 
 Amico.blocked?(1, 11)
  => false
 
+Amico.blocked_by?(11, 1)
+ => false
+
 Amico.follow(11, 1)
  => nil
 
@@ -129,8 +139,10 @@ Amico.configure do |configuration|
   configuration.following_key = 'following'
   configuration.followers_key = 'followers'
   configuration.blocked_key = 'blocked'
+  configuration.blocked_by_key = 'blocked_by'
   configuration.reciprocated_key = 'reciprocated'
   configuration.pending_key = 'pending'
+  configuration.pending_with_key = 'pending_with'
   configuration.default_scope_key = 'default'
   configuration.pending_follow = true
   configuration.page_size = 25
@@ -145,18 +157,30 @@ Amico.follow(11, 1)
 Amico.pending?(1, 11)
  => true
 
+Amico.pending_with?(11, 1)
+ => true
+
 Amico.pending?(11, 1)
  => true
 
+Amico.pending_with?(1, 11)
+ => true
+
 Amico.accept(1, 11)
  => nil
 
 Amico.pending?(1, 11)
  => false
 
+Amico.pending_with?(11, 1)
+ => false
+
 Amico.pending?(11, 1)
  => true
 
+Amico.pending_with?(1, 11)
+ => true
+
 Amico.following?(1, 11)
  => true
 
@@ -175,9 +199,15 @@ Amico.accept(11, 1)
 Amico.pending?(1, 11)
  => false
 
+Amico.pending_with?(11, 1)
+ => false
+
 Amico.pending?(11, 1)
  => false
 
+Amico.pending_with?(1, 11)
+ => false
+
 Amico.following?(1, 11)
  => true
 
@@ -205,8 +235,10 @@ Amico.configure do |configuration|
   configuration.following_key = 'following'
   configuration.followers_key = 'followers'
   configuration.blocked_key = 'blocked'
+  configuration.blocked_by_key = 'blocked_by'
   configuration.reciprocated_key = 'reciprocated'
   configuration.pending_key = 'pending'
+  configuration.pending_with_key = 'pending_with'
   configuration.default_scope_key = 'default'
   configuration.pending_follow = false
   configuration.page_size = 25
@@ -293,8 +325,10 @@ Amico.configure do |configuration|
   configuration.following_key = 'following'
   configuration.followers_key = 'followers'
   configuration.blocked_key = 'blocked'
+  configuration.blocked_by_key = 'blocked_by'
   configuration.reciprocated_key = 'reciprocated'
   configuration.pending_key = 'pending'
+  configuration.pending_with_key = 'pending_with'
   configuration.default_scope_key = 'default'
   configuration.pending_follow = true
   configuration.page_size = 25
@@ -365,8 +399,10 @@ Amico.configure do |configuration|
   configuration.following_key = 'following'
   configuration.followers_key = 'followers'
   configuration.blocked_key = 'blocked'
+  configuration.blocked_by_key = 'blocked_by'
   configuration.reciprocated_key = 'reciprocated'
   configuration.pending_key = 'pending'
+  configuration.pending_with_key = 'pending_with'
   configuration.default_scope_key = 'user'
   configuration.pending_follow = false
   configuration.page_size = 25
@@ -412,6 +448,25 @@ Amico.all(1, :following)
 `type` can be one of :following, :followers, :blocked, :reciprocated, :pending. Use this with caution
 as there may potentially be a large number of items that could be returned from this call.
 
+You can clear all relationships that have been set for an ID by calling `clear(id, scope)`. You may wish to do this if you allow records to be deleted and you wish to prevent orphaned IDs and inaccurate follower/following counts. Note that this clears *all* relationships in either direction - including blocked and pending. An example:
+
+```ruby
+Amico.follow(11, 1)
+ => nil
+Amico.block(12, 1)
+ => nil
+Amico.following(11)
+ => ["1"]
+Amico.blocked(12)
+ => ["1"]
+Amico.clear(1)
+ => nil
+Amico.following(11)
+ => []
+Amico.blocked(12)
+ => []
+```
+
 ## Method Summary
 
 ```ruby
@@ -427,6 +482,8 @@ block(from_id, to_id, scope = Amico.default_scope_key)
 unblock(from_id, to_id, scope = Amico.default_scope_key)
 # Accept a relationship that is pending between two IDs.
 accept(from_id, to_id, scope = Amico.default_scope_key)
+# Clear all relationships (in either direction) for a given ID.
+clear(id, scope = Amico.default_scope_key)
 
 # Retrieval
 
@@ -436,10 +493,14 @@ following(id, page_options = default_paging_options, scope = Amico.default_scope
 followers(id, page_options = default_paging_options, scope = Amico.default_scope_key)
 # Retrieve a page of blocked individuals for a given ID.
 blocked(id, page_options = default_paging_options, scope = Amico.default_scope_key)
+# Retrieve a page of individuals who have blocked a given ID.
+blocked_by(id, page_options = default_paging_options, scope = Amico.default_scope_key)
 # Retrieve a page of individuals that have reciprocated a follow for a given ID.
 reciprocated(id, page_options = default_paging_options, scope = Amico.default_scope_key)
 # Retrieve a page of pending relationships for a given ID.
 pending(id, page_options = default_paging_options, scope = Amico.default_scope_key)
+# Retrieve a page of individuals that are waiting to approve the given ID.
+pending_with(id, page_options = default_paging_options, scope = Amico.default_scope_key)
 
 # Retrieve all of the individuals for a given id, type (e.g. following) and scope.
 all(id, type, scope = Amico.default_scope_key)
@@ -452,10 +513,14 @@ following_count(id, scope = Amico.default_scope_key)
 followers_count(id, scope = Amico.default_scope_key)
 # Count the number of individuals that someone has blocked.
 blocked_count(id, scope = Amico.default_scope_key)
+# Count the number of individuals blocking another.
+blocked_by_count(id, scope = Amico.default_scope_key)
 # Count the number of individuals that have reciprocated a following relationship.
 reciprocated_count(id, scope = Amico.default_scope_key)
 # Count the number of relationships pending for an individual.
 pending_count(id, scope = Amico.default_scope_key)
+# Count the number of relationships an individual has pending with another.
+pending_with_count(id, scope = Amico.default_scope_key)
 
 # Count the number of pages of following relationships for an individual.
 following_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)
@@ -463,10 +528,14 @@ following_page_count(id, page_size = Amico.page_size, scope = Amico.default_scop
 followers_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)
 # Count the number of pages of blocked relationships for an individual.
 blocked_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)
+# Count the number of pages of blocked_by relationships for an individual.
+blocked_by_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)
 # Count the number of pages of reciprocated relationships for an individual.
 reciprocated_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)
 # Count the number of pages of pending relationships for an individual.
 pending_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)
+# Count the number of pages of individuals waiting to approve another individual.
+pending_with_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)
 
 # Checks
 
@@ -476,10 +545,14 @@ following?(id, following_id, scope = Amico.default_scope_key)
 follower?(id, follower_id, scope = Amico.default_scope_key)
 # Check to see if one individual has blocked another individual.
 blocked?(id, blocked_id, scope = Amico.default_scope_key)
+# Check to see if one individual is blocked by another individual.
+blocked_by?(id, blocked_id, scope = Amico.default_scope_key)
 # Check to see if one individual has reciprocated in following another individual.
 reciprocated?(from_id, to_id, scope = Amico.default_scope_key)
 # Check to see if one individual has a pending relationship in following another individual.
 pending?(from_id, to_id, scope = Amico.default_scope_key)
+# Check to see if one individual has a pending relationship with another.
+pending_with?(from_id, to_id, scope = Amico.default_scope_key)
 ```
 
 ## Documentation

data/lib/amico/configuration.rb

@@ -16,12 +16,18 @@ module Amico
     # Key used in Redis for tracking who an individual blocks.
     attr_writer :blocked_key
 
+    # Key used in Redis for tracking who has blocked an individual.
+    attr_writer :blocked_by_key
+
     # Key used in Redis for tracking who has reciprocated a follow for an individual.
     attr_writer :reciprocated_key
 
     # Key used in Redis for tracking pending follow relationships for an individual.
     attr_writer :pending_key
 
+    # Key used in Redis for tracking who an individual is awaiting approval from.
+    attr_writer :pending_with_key
+
     # Key used to indicate whether or not a follow should be pending or not.
     attr_writer :pending_follow
 
@@ -41,8 +47,10 @@ module Amico
     #     configuration.following_key = 'following'
     #     configuration.followers_key = 'followers'
     #     configuration.blocked_key = 'blocked'
+    #     configuration.blocked_by_key = 'blocked_by'
     #     configuration.reciprocated_key = 'reciprocated'
     #     configuration.pending_key = 'pending'
+    #     configuration.pending_with_key = 'pending_with'
     #     configuration.default_scope_key = 'default'
     #     configuration.pending_follow = false
     #     configuration.page_size = 25
@@ -79,6 +87,13 @@ module Amico
       @blocked_key ||= 'blocked'
     end
 
+    # Key used in Redis for tracking who has blocked an individual.
+    # 
+    # @return the key used in Redis for tracking who has blocked an individual or the default of 'blocked_by' if not set.
+    def blocked_by_key
+      @blocked_by_key ||= 'blocked_by'
+    end
+
     # Key used in Redis for tracking who has reciprocated a follow for an individual.
     #
     # @return the key used in Redis for tracking who has reciprocated a follow for an individual or the default of 'reciprocated' if not set.
@@ -93,6 +108,13 @@ module Amico
       @pending_key ||= 'pending'
     end
 
+    # Key used in Redis for tracking who an individual is awaiting approval from.
+    #
+    # @return the key used in Redis for tracking who an individual is awaiting approval from or the default of 'pending_with' if not set.
+    def pending_with_key
+      @pending_with_key ||= 'pending_with'
+    end
+
     # Default key used in Redis for tracking scope for the given relationship calls.
     #
     # @return the default key used in Redis for tracking scope for the given relationship calls.

data/lib/amico/relationships.rb

@@ -20,6 +20,7 @@ module Amico
 		  add_following_followers_reciprocated(from_id, to_id, scope)
 	  else
 		  Amico.redis.zadd("#{Amico.namespace}:#{Amico.pending_key}:#{scope}:#{to_id}", Time.now.to_i, from_id)
+		  Amico.redis.zadd("#{Amico.namespace}:#{Amico.pending_with_key}:#{scope}:#{from_id}", Time.now.to_i, to_id)
 	  end
 	end
 
@@ -44,6 +45,7 @@ module Amico
 		Amico.redis.zrem("#{Amico.namespace}:#{Amico.reciprocated_key}:#{scope}:#{from_id}", to_id)
 		Amico.redis.zrem("#{Amico.namespace}:#{Amico.reciprocated_key}:#{scope}:#{to_id}", from_id)
 		Amico.redis.zrem("#{Amico.namespace}:#{Amico.pending_key}:#{scope}:#{to_id}", from_id)
+		Amico.redis.zrem("#{Amico.namespace}:#{Amico.pending_with_key}:#{scope}:#{from_id}", to_id)
 	  end
 	end  
 
@@ -68,7 +70,9 @@ module Amico
 		Amico.redis.zrem("#{Amico.namespace}:#{Amico.reciprocated_key}:#{scope}:#{from_id}", to_id)
 		Amico.redis.zrem("#{Amico.namespace}:#{Amico.reciprocated_key}:#{scope}:#{to_id}", from_id)
 		Amico.redis.zrem("#{Amico.namespace}:#{Amico.pending_key}:#{scope}:#{from_id}", to_id)
+		Amico.redis.zrem("#{Amico.namespace}:#{Amico.pending_with_key}:#{scope}:#{to_id}", from_id)
 		Amico.redis.zadd("#{Amico.namespace}:#{Amico.blocked_key}:#{scope}:#{from_id}", Time.now.to_i, to_id)
+		Amico.redis.zadd("#{Amico.namespace}:#{Amico.blocked_by_key}:#{scope}:#{to_id}", Time.now.to_i, from_id)
 	  end
 	end
 
@@ -85,7 +89,10 @@ module Amico
 	def unblock(from_id, to_id, scope = Amico.default_scope_key)
 	  return if from_id == to_id
 
-	  Amico.redis.zrem("#{Amico.namespace}:#{Amico.blocked_key}:#{scope}:#{from_id}", to_id)
+		Amico.redis.multi do
+			Amico.redis.zrem("#{Amico.namespace}:#{Amico.blocked_key}:#{scope}:#{from_id}", to_id)
+			Amico.redis.zrem("#{Amico.namespace}:#{Amico.blocked_by_key}:#{scope}:#{to_id}", from_id)
+		end
 	end
 
 	# Accept a relationship that is pending between two IDs.
@@ -107,6 +114,31 @@ module Amico
 	  add_following_followers_reciprocated(from_id, to_id, scope)
 	end
 
+  # Clears all relationships (in either direction) stored for an individual.
+  # Helpful to prevent orphaned associations when deleting users.
+  # 
+  # @param id [String] ID of the individual to clear info for.
+  # @param scope [String] Scope for the call.
+  # 
+  # Examples
+  # 
+  #   Amico.follow(1, 11)
+  #   Amico.followers_count(11)  => 1
+  #   Amico.clear(1)
+  #   Amico.followers_count(11)  => 0
+  def clear(id, scope = Amico.default_scope_key)
+    # no longer following (or followed by) anyone
+    clear_bidirectional_sets_for_id(id, Amico.following_key, Amico.followers_key, scope)
+    clear_bidirectional_sets_for_id(id, Amico.followers_key, Amico.following_key, scope)
+    clear_bidirectional_sets_for_id(id, Amico.reciprocated_key, Amico.reciprocated_key, scope)
+    # no longer blocked by (or blocking) anyone
+    clear_bidirectional_sets_for_id(id, Amico.blocked_by_key, Amico.blocked_key, scope)
+    clear_bidirectional_sets_for_id(id, Amico.blocked_key, Amico.blocked_by_key, scope)
+    # no longer pending with anyone (or have any pending followers)
+    clear_bidirectional_sets_for_id(id, Amico.pending_with_key, Amico.pending_key, scope)
+    clear_bidirectional_sets_for_id(id, Amico.pending_key, Amico.pending_with_key, scope)
+  end
+
 	# Count the number of individuals that someone is following.
 	#
 	# @param id [String] ID of the individual to retrieve following count for.
@@ -152,6 +184,21 @@ module Amico
 	  Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_key}:#{scope}:#{id}")
 	end
 
+	# Count the number of individuals blocking another.
+	#
+	# @param id [String] ID of the individual to retrieve blocked_by count for.
+	# @param scope [String] Scope for the call.
+	# 
+	# Examples
+	#
+	#   Amico.block(1, 11)
+	#   Amico.blocked_by_count(11)
+	#
+	# @return the count of the number of individuals blocking someone.
+	def blocked_by_count(id, scope = Amico.default_scope_key)
+	  Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_by_key}:#{scope}:#{id}")
+	end
+
 	# Count the number of individuals that have reciprocated a following relationship.
 	#
 	# @param id [String] ID of the individual to retrieve reciprocated following count for.
@@ -184,6 +231,22 @@ module Amico
 	  Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_key}:#{scope}:#{id}")
 	end
 
+	# Count the number of relationships an individual has pending with another.
+	#
+	# @param id [String] ID of the individual to retrieve pending count for.
+	# @param scope [String] Scope for the call.
+	# 
+	# Examples
+	#
+	#   Amico.follow(1, 11)
+	#   Amico.follow(1, 12)
+	#   Amico.pending_count(1) # 2
+	#
+	# @return the count of the number of relationships an individual has pending with another.
+	def pending_with_count(id, scope = Amico.default_scope_key)
+	  Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_with_key}:#{scope}:#{id}")
+	end
+
 	# Check to see if one individual is following another individual.
 	#
 	# @param id [String] ID of the individual checking the following status.
@@ -232,6 +295,22 @@ module Amico
 	  !Amico.redis.zscore("#{Amico.namespace}:#{Amico.blocked_key}:#{scope}:#{id}", blocked_id).nil?
 	end
 
+	# Check to see if one individual is blocked by another individual.
+	#
+	# @param id [String] ID of the individual checking the blocked by status.
+	# @param blocked_id [String] ID of the individual to see if they have blocked id.
+	# @param scope [String] Scope for the call.
+	#
+	# Examples
+	# 
+	#   Amico.block(1, 11)
+	#   Amico.blocked_by?(11, 1)
+	#
+	# @return true if id is blocked by blocked_by_id, false otherwise
+	def blocked_by?(id, blocked_by_id, scope = Amico.default_scope_key)
+	  !Amico.redis.zscore("#{Amico.namespace}:#{Amico.blocked_by_key}:#{scope}:#{id}", blocked_by_id).nil?
+	end
+
 	# Check to see if one individual has reciprocated in following another individual.
 	#
 	# @param from_id [String] ID of the individual checking the reciprocated relationship.
@@ -265,6 +344,22 @@ module Amico
 	  !Amico.redis.zscore("#{Amico.namespace}:#{Amico.pending_key}:#{scope}:#{to_id}", from_id).nil?
 	end
 
+	# Check to see if one individual has a pending relationship with another.
+	#
+	# @param from_id [String] ID of the individual checking the pending relationships.
+	# @param to_id [String] ID of the individual to see if they are pending an approval from from_id.
+	# @param scope [String] Scope for the call.
+	#
+	# Examples
+	#
+	#   Amico.follow(1, 11)
+	#   Amico.pending_with?(11, 1) # true
+	#
+	# @return true if the relationship is pending, false otherwise
+	def pending_with?(from_id, to_id, scope = Amico.default_scope_key)
+	  !Amico.redis.zscore("#{Amico.namespace}:#{Amico.pending_with_key}:#{scope}:#{to_id}", from_id).nil?
+	end
+
 	# Retrieve a page of followed individuals for a given ID.
 	#
 	# @param id [String] ID of the individual.
@@ -316,6 +411,23 @@ module Amico
 	  members("#{Amico.namespace}:#{Amico.blocked_key}:#{scope}:#{id}", page_options)
 	end
 
+	# Retrieve a page of individuals who have blocked a given ID.
+	#
+	# @param id [String] ID of the individual.
+	# @param page_options [Hash] Options to be passed for retrieving a page of blocking individuals.
+	# @param scope [String] Scope for the call.
+	#
+	# Examples
+	#
+	#   Amico.block(11, 1)
+	#   Amico.block(12, 1)
+	#   Amico.blocked_by(1, :page => 1)
+	#
+	# @return a page of individuals who have blocked a given ID.
+	def blocked_by(id, page_options = default_paging_options, scope = Amico.default_scope_key)
+	  members("#{Amico.namespace}:#{Amico.blocked_by_key}:#{scope}:#{id}", page_options)
+	end
+
 	# Retrieve a page of individuals that have reciprocated a follow for a given ID.
 	#
 	# @param id [String] ID of the individual.
@@ -343,8 +455,8 @@ module Amico
 	#
 	# Examples
 	#
-	#   Amico.follow(1, 11)
-	#   Amico.follow(2, 11)
+	#   Amico.follow(11, 1)
+	#   Amico.follow(12, 1)
 	#   Amico.pending(1, :page => 1)
 	#
 	# @return a page of pending relationships for a given ID.
@@ -352,6 +464,23 @@ module Amico
 	  members("#{Amico.namespace}:#{Amico.pending_key}:#{scope}:#{id}", page_options)
 	end
 
+	# Retrieve a page of individuals that are waiting to approve the given ID.
+	#
+	# @param id [String] ID of the individual.
+	# @param page_options [Hash] Options to be passed for retrieving a page of pending relationships.
+	# @param scope [String] Scope for the call.
+	#
+	# Examples
+	#
+	#   Amico.follow(1, 11)
+	#   Amico.follow(1, 12)
+	#   Amico.pending_with(1, :page => 1)
+	#
+	# @return a page of individuals that are waiting to approve the given ID.
+	def pending_with(id, page_options = default_paging_options, scope = Amico.default_scope_key)
+	  members("#{Amico.namespace}:#{Amico.pending_with_key}:#{scope}:#{id}", page_options)
+	end
+
 	# Count the number of pages of following relationships for an individual.
 	#
 	# @param id [String] ID of the individual.
@@ -403,6 +532,23 @@ module Amico
 	  total_pages("#{Amico.namespace}:#{Amico.blocked_key}:#{scope}:#{id}", page_size)
 	end
 
+	# Count the number of pages of blocked_by relationships for an individual.
+	#
+	# @param id [String] ID of the individual.
+	# @param page_size [int] Page size (default: Amico.page_size).
+	# @param scope [String] Scope for the call.
+	#
+	# Examples
+	#
+	#   Amico.block(11, 1)
+	#   Amico.block(12, 1)
+	#   Amico.blocked_by_page_count(1)
+	#    
+	# @return the number of pages of blocked_by relationships for an individual.
+	def blocked_by_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)
+	  total_pages("#{Amico.namespace}:#{Amico.blocked_by_key}:#{scope}:#{id}", page_size)
+	end
+
 	# Count the number of pages of reciprocated relationships for an individual.
 	#
 	# @param id [String] ID of the individual.
@@ -439,14 +585,30 @@ module Amico
 	  total_pages("#{Amico.namespace}:#{Amico.pending_key}:#{scope}:#{id}", page_size)
 	end
 
+	# Count the number of pages of individuals waiting to approve another individual.
+	#
+	# @param id [String] ID of the individual.
+	# @param page_size [int] Page size (default: Amico.page_size).
+	# @param scope [String] Scope for the call.
+	#
+	# Examples
+	#
+	#   Amico.follow(1, 11)
+	#   Amico.follow(1, 12)
+	#   Amico.pending_with_page_count(1) # 1
+	#    
+	# @return the number of pages of individuals waiting to approve another individual.
+	def pending_with_page_count(id, page_size = Amico.page_size, scope = Amico.default_scope_key)
+	  total_pages("#{Amico.namespace}:#{Amico.pending_with_key}:#{scope}:#{id}", page_size)
+	end
+
 	# Retrieve all of the individuals for a given id, type (e.g. following) and scope
 	#
 	# @param id [String] ID of the individual.
-	# @param type [Symbol] One of :following, :followers, :blocked, :reciprocated, :pending.
+	# @param type [Symbol] One of :following, :followers, :reciprocated, :blocked, :blocked_by, :pending, :pending_with.
 	# @param scope [String] Scope for the call.
 	def all(id, type, scope = Amico.default_scope_key)
-	  valid_types = [:following, :followers, :blocked, :reciprocated, :pending]
-	  raise "Must be one of #{valid_types.to_s}" if !valid_types.include?(type)
+    validate_relationship_type(type)
 	  count = self.send("#{type.to_s}_count".to_sym, id, scope)
 	  count > 0 ? self.send("#{type}", id, {:page_size => count}, scope) : []
 	end
@@ -454,28 +616,41 @@ module Amico
   # Retrieve a count of all of a given type of relationship for the specified id.
   #
   # @param id [String] ID of the individual.
-  # @param type [Symbol] One of :following, :followers, :blocked, :reciprocated, :pending.
+	# @param type [Symbol] One of :following, :followers, :reciprocated, :blocked, :blocked_by, :pending, :pending_with.
   # @param scope [String] Scope for the call.
   #
   # @return Count of all of a given type of relationship for the specified id.
 	def count(id, type, scope = Amico.default_scope_key)
+    validate_relationship_type(type)
     self.send("#{type.to_s}_count".to_sym, id, scope)
 	end
 
   # Retrieve a page count of a given type of relationship for the specified id.
   #
   # @param id [String] ID of the individual.
-  # @param type [Symbol] One of :following, :followers, :blocked, :reciprocated, :pending.
+	# @param type [Symbol] One of :following, :followers, :reciprocated, :blocked, :blocked_by, :pending, :pending_with.
   # @param page_size [int] Page size (default: Amico.page_size).
   # @param scope [String] Scope for the call.
   #
   # @return Page count of a given type of relationship for the specified id.
   def page_count(id, type, page_size = Amico.page_size, scope = Amico.default_scope_key)
+    validate_relationship_type(type)
     self.send("#{type.to_s}_page_count".to_sym, id, page_size, scope)
   end
 
 	private
 
+  # Valid relationtionships that can be used in #all, #count, #page_count, etc...
+  VALID_RELATIONSHIPS = [:following, :followers, :reciprocated, :blocked, :blocked_by, :pending, :pending_with]
+
+  # Ensure that a relationship type is valid.
+  # 
+  # @param type [Symbol] One of :following, :followers, :reciprocated, :blocked, :blocked_by, :pending, :pending_with.
+  # @raise [StandardError] if the type is not included in VALID_RELATIONSHIPS
+  def validate_relationship_type(type)
+    raise "Must be one of #{VALID_RELATIONSHIPS.to_s}" if !VALID_RELATIONSHIPS.include?(type)
+  end
+
 	# Default paging options.
 	#
 	# @return a hash of the default paging options.
@@ -493,6 +668,7 @@ module Amico
 		Amico.redis.zadd("#{Amico.namespace}:#{Amico.following_key}:#{scope}:#{from_id}", Time.now.to_i, to_id)
 		Amico.redis.zadd("#{Amico.namespace}:#{Amico.followers_key}:#{scope}:#{to_id}", Time.now.to_i, from_id)
 		Amico.redis.zrem("#{Amico.namespace}:#{Amico.pending_key}:#{scope}:#{to_id}", from_id)
+		Amico.redis.zrem("#{Amico.namespace}:#{Amico.pending_with_key}:#{scope}:#{from_id}", to_id)
 	  end
 
 	  if reciprocated?(from_id, to_id)
@@ -503,6 +679,20 @@ module Amico
 	  end      
 	end
 
+	# Removes references to an individual in sets that are named with other individual's keys.
+	# Assumes two set keys that are used together such as followers/following, blocked/blocked_by, etc...
+	#
+	# @param id [String] The ID of the individual to clear info for.
+	# @param source_set_key [String] The key identifying the souce set to iterate over.
+	# @param related_set_key [String] The key identifying the sets that the idividual needs to be removed from.
+  # @param scope [String] Scope for the call.
+  def clear_bidirectional_sets_for_id(id, source_set_key, related_set_key, scope = Amico.default_scope_key)
+    Amico.redis.zrange("#{Amico.namespace}:#{source_set_key}:#{scope}:#{id}", 0, -1).each do |related_id|
+      Amico.redis.zrem("#{Amico.namespace}:#{related_set_key}:#{scope}:#{related_id}", id)
+    end
+    Amico.redis.del("#{Amico.namespace}:#{source_set_key}:#{scope}:#{id}")
+  end
+
 	# Count the total number of pages for a given key in a Redis sorted set.
 	#
 	# @param key [String] Redis key.

data/lib/amico/version.rb

@@ -1,3 +1,3 @@
 module Amico
-  VERSION = '2.1.0'
+  VERSION = '2.2.0'
 end

data/spec/amico/configuration_spec.rb

@@ -8,8 +8,10 @@ describe Amico::Configuration do
         configuration.following_key.should eql('following')
         configuration.followers_key.should eql('followers')
         configuration.blocked_key.should eql('blocked')
+        configuration.blocked_by_key.should eql('blocked_by')
         configuration.reciprocated_key.should eql('reciprocated')
         configuration.pending_key.should eql('pending')
+        configuration.pending_with_key.should eql('pending_with')
         configuration.default_scope_key.should eql('default')
         configuration.pending_follow.should be_false
         configuration.page_size.should be(25)

data/spec/amico/relationships_spec.rb

@@ -46,8 +46,9 @@ describe Amico::Relationships do
       Amico.follow(11, 1)
       Amico.block(1, 11)
 
-      Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:11").should be(0) 
-      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_key}:#{Amico.default_scope_key}:1").should be(1) 
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:11").should be(0)
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_key}:#{Amico.default_scope_key}:1").should be(1)
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_by_key}:#{Amico.default_scope_key}:11").should be(1)
       Amico.redis.zcard("#{Amico.namespace}:#{Amico.reciprocated_key}:#{Amico.default_scope_key}:1").should be(0)
       Amico.redis.zcard("#{Amico.namespace}:#{Amico.reciprocated_key}:#{Amico.default_scope_key}:11").should be(0)
     end
@@ -55,20 +56,21 @@ describe Amico::Relationships do
     it 'should allow you to block someone who is not following you' do
       Amico.block(1, 11)
 
-      Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:11").should be(0) 
-      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_key}:#{Amico.default_scope_key}:1").should be(1) 
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:11").should be(0)
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_key}:#{Amico.default_scope_key}:1").should be(1)
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_by_key}:#{Amico.default_scope_key}:11").should be(1)
     end
 
     it 'should not allow someone you have blocked to follow you' do
       Amico.block(1, 11)
 
-      Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:11").should be(0) 
-      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_key}:#{Amico.default_scope_key}:1").should be(1) 
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:11").should be(0)
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_key}:#{Amico.default_scope_key}:1").should be(1)
 
       Amico.follow(11, 1)
 
-      Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:11").should be(0) 
-      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_key}:#{Amico.default_scope_key}:1").should be(1) 
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:11").should be(0)
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_key}:#{Amico.default_scope_key}:1").should be(1)
     end
 
     it 'should not allow you to block yourself' do
@@ -81,8 +83,10 @@ describe Amico::Relationships do
     it 'should allow you to unblock someone you have blocked' do
       Amico.block(1, 11)
       Amico.blocked?(1, 11).should be_true
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_by_key}:#{Amico.default_scope_key}:11").should be(1)
       Amico.unblock(1, 11)
-      Amico.blocked?(1, 11).should be_false      
+      Amico.blocked?(1, 11).should be_false
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_by_key}:#{Amico.default_scope_key}:11").should be(0)
     end
   end
 
@@ -116,6 +120,13 @@ describe Amico::Relationships do
     end
   end
 
+  describe '#blocked_by?' do
+    it 'should return that someone is blocking you' do
+      Amico.block(1, 11)
+      Amico.blocked_by?(11, 1).should be_true
+    end
+  end
+
   describe '#reciprocated?' do
     it 'should return true if both individuals are following each other' do
       Amico.follow(1, 11)
@@ -139,7 +150,7 @@ describe Amico::Relationships do
 
     it 'should page correctly' do
       add_reciprocal_followers
-      
+
       Amico.following(1, :page => 1, :page_size => 5).size.should be(5)
       Amico.following(1, :page => 1, :page_size => 10).size.should be(10)
       Amico.following(1, :page => 1, :page_size => 26).size.should be(25)
@@ -180,6 +191,15 @@ describe Amico::Relationships do
     end
   end
 
+  describe '#blocked_by' do
+    it 'should return the correct list' do
+      Amico.block(11, 1)
+      Amico.block(12, 1)
+      Amico.blocked_by(1).should eql(["12", "11"])
+      Amico.blocked_by(1, :page => 5).should eql(["12", "11"])
+    end
+  end
+
   describe '#reciprocated' do
     it 'should return the correct list' do
       Amico.follow(1, 11)
@@ -218,6 +238,13 @@ describe Amico::Relationships do
     end
   end
 
+  describe '#blocked_by_count' do
+    it 'should return the correct count' do
+      Amico.block(1, 11)
+      Amico.blocked_by_count(11).should be(1)
+    end
+  end
+
   describe '#reciprocated_count' do
     it 'should return the correct count' do
       Amico.follow(1, 11)
@@ -259,6 +286,16 @@ describe Amico::Relationships do
     end
   end
 
+  describe '#blocked_by_page_count' do
+    it 'should return the correct count' do
+      add_reciprocal_followers(26, true)
+
+      Amico.blocked_by_page_count(1).should be(1)
+      Amico.blocked_by_page_count(1, 10).should be(3)
+      Amico.blocked_by_page_count(1, 5).should be(5)
+    end
+  end
+
   describe '#reciprocated_page_count' do
     it 'should return the correct count' do
       add_reciprocal_followers
@@ -285,6 +322,7 @@ describe Amico::Relationships do
         Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:1").should be(0)
         Amico.redis.zcard("#{Amico.namespace}:#{Amico.followers_key}:#{Amico.default_scope_key}:11").should be(0)
         Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_key}:#{Amico.default_scope_key}:11").should be(1)
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_with_key}:#{Amico.default_scope_key}:1").should be(1)
       end
 
       it 'should remove the pending relationship if you have a pending follow, but you unfollow' do
@@ -293,21 +331,25 @@ describe Amico::Relationships do
         Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:1").should be(0)
         Amico.redis.zcard("#{Amico.namespace}:#{Amico.followers_key}:#{Amico.default_scope_key}:11").should be(0)
         Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_key}:#{Amico.default_scope_key}:11").should be(1)
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_with_key}:#{Amico.default_scope_key}:1").should be(1)
 
         Amico.unfollow(1, 11)
 
         Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{Amico.default_scope_key}:1").should be(0)
         Amico.redis.zcard("#{Amico.namespace}:#{Amico.followers_key}:#{Amico.default_scope_key}:11").should be(0)
         Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_key}:#{Amico.default_scope_key}:11").should be(0)
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_with_key}:#{Amico.default_scope_key}:1").should be(0)
       end
 
       it 'should remove the pending relationship and add to following and followers if #accept is called' do
         Amico.follow(1, 11)
         Amico.pending?(1, 11).should be_true
+        Amico.pending_with?(11, 1).should be_true
 
         Amico.accept(1, 11)
 
         Amico.pending?(1, 11).should be_false
+        Amico.pending_with?(11, 1).should be_false
         Amico.following?(1, 11).should be_true
         Amico.following?(11, 1).should be_false
         Amico.follower?(11, 1).should be_true
@@ -345,8 +387,10 @@ describe Amico::Relationships do
       it 'should remove the pending relationship if you block someone' do
         Amico.follow(11, 1)
         Amico.pending?(11, 1).should be_true
+        Amico.pending_with?(1, 11).should be_true
         Amico.block(1, 11)
         Amico.pending?(11, 1).should be_false
+        Amico.pending_with?(1, 11).should be_false
         Amico.blocked?(1, 11).should be_true
       end
     end
@@ -368,6 +412,23 @@ describe Amico::Relationships do
       end
     end
 
+    describe '#pending_with' do
+      it 'should return the correct list' do
+        Amico.follow(1, 11)
+        Amico.follow(11, 1)
+        Amico.pending_with(1).should eql(["11"])
+        Amico.pending_with(11).should eql(["1"])
+      end
+
+      it 'should page correctly' do
+        add_reciprocal_followers
+
+        Amico.pending_with(1, :page => 1, :page_size => 5).size.should be(5)
+        Amico.pending_with(1, :page => 1, :page_size => 10).size.should be(10)
+        Amico.pending_with(1, :page => 1, :page_size => 26).size.should be(25)
+      end
+    end
+
     describe '#pending_count' do
       it 'should return the correct count' do
         Amico.follow(1, 11)
@@ -379,6 +440,17 @@ describe Amico::Relationships do
       end
     end
 
+    describe '#pending_with_count' do
+      it 'should return the correct count' do
+        Amico.follow(1, 11)
+        Amico.follow(11, 1)
+        Amico.follow(1, 12)
+        Amico.follow(12, 1)
+        Amico.follow(1, 13)
+        Amico.pending_with_count(1).should be(3)
+      end
+    end
+
     describe '#pending_page_count' do
       it 'should return the correct count' do
         add_reciprocal_followers
@@ -388,6 +460,16 @@ describe Amico::Relationships do
         Amico.pending_page_count(1, 5).should be(5)
       end
     end
+
+    describe '#pending_with_page_count' do
+      it 'should return the correct count' do
+        add_reciprocal_followers
+
+        Amico.pending_with_page_count(1).should be(1)
+        Amico.pending_with_page_count(1, 10).should be(3)
+        Amico.pending_with_page_count(1, 5).should be(5)
+      end
+    end
   end
 
   describe 'scope' do
@@ -407,7 +489,7 @@ describe Amico::Relationships do
 
   describe '#all' do
     it 'should raise an exception if passing an invalid type' do
-      lambda {Amico.all(1, :unknown)}.should raise_error      
+      lambda {Amico.all(1, :unknown)}.should raise_error
     end
 
     it 'should return the correct list when calling all for various types' do
@@ -445,6 +527,9 @@ describe Amico::Relationships do
 
       blocked_list = Amico.all(1, :blocked)
       blocked_list.length.should be(4)
+
+      blocked_by_list = Amico.all(1, :blocked_by)
+      blocked_by_list.length.should be(4)
     end
   end
 
@@ -486,44 +571,87 @@ describe Amico::Relationships do
     it 'should return the correct count for the various types of relationships' do
       add_reciprocal_followers(5)
 
-      Amico.count(1, :following).should == 4
-      Amico.count(1, :followers).should == 4
-      Amico.count(1, :reciprocated).should == 4
+      Amico.count(1, :following).should eql(4)
+      Amico.count(1, :followers).should eql(4)
+      Amico.count(1, :reciprocated).should eql(4)
 
       Amico.redis.flushdb
       add_reciprocal_followers(5, true)
 
-      Amico.count(1, :blocked).should == 4
+      Amico.count(1, :blocked).should eql(4)
+      Amico.count(1, :blocked_by).should eql(4)
 
       Amico.redis.flushdb
       Amico.pending_follow = true
       add_reciprocal_followers(5)
 
-      Amico.count(1, :pending).should == 4
+      Amico.count(1, :pending).should eql(4)
     end
   end
 
   describe '#page_count' do
-    it 'should return the correct page count for the various types of relationships' do    
+    it 'should return the correct page count for the various types of relationships' do
       add_reciprocal_followers(5)
 
-      Amico.page_count(1, :following).should == 1
-      Amico.page_count(1, :followers).should == 1
-      Amico.page_count(1, :reciprocated).should == 1
+      Amico.page_count(1, :following).should eql(1)
+      Amico.page_count(1, :followers).should eql(1)
+      Amico.page_count(1, :reciprocated).should eql(1)
 
       Amico.redis.flushdb
       add_reciprocal_followers(5, true)
 
-      Amico.page_count(1, :blocked).should == 1
+      Amico.page_count(1, :blocked).should eql(1)
+      Amico.page_count(1, :blocked_by).should eql(1)
 
       Amico.redis.flushdb
       Amico.pending_follow = true
       add_reciprocal_followers(5)
 
-      Amico.page_count(1, :pending).should == 1
+      Amico.page_count(1, :pending).should eql(1)
     end
   end
 
+
+
+  describe '#clear' do
+    it 'should remove follower/following relationships' do
+      Amico.follow(1, 11)
+      Amico.follow(11, 1)
+      
+      Amico.following_count(1).should be(1)
+      Amico.followers_count(1).should be(1)
+      Amico.reciprocated_count(1).should be(1)
+      Amico.following_count(11).should be(1)
+      Amico.followers_count(11).should be(1)
+      Amico.reciprocated_count(11).should be(1)
+      
+      Amico.clear(1)
+      
+      Amico.following_count(1).should be(0)
+      Amico.followers_count(1).should be(0)
+      Amico.reciprocated_count(1).should be(0)
+      Amico.following_count(11).should be(0)
+      Amico.followers_count(11).should be(0)
+      Amico.reciprocated_count(11).should be(0)
+    end
+    it 'should clear pending/pending_with relationships' do
+      Amico.pending_follow = true
+      Amico.follow(1, 11)
+      Amico.pending_count(11).should be(1)
+      Amico.clear(1)
+      Amico.pending_count(11).should be(0)
+    end
+    it 'should clear blocked/blocked_by relationships' do
+      Amico.block(1, 11)
+      Amico.blocked_count(1).should be(1)
+      Amico.blocked_by_count(11).should be(1)
+      Amico.clear(11)
+      Amico.blocked_count(1).should be(0)
+      Amico.blocked_by_count(11).should be(0)
+    end
+  end
+
+
   private
 
   def add_reciprocal_followers(count = 26, block_relationship = false)

data/spec/amico/version_spec.rb

@@ -2,6 +2,6 @@ require 'spec_helper'
 
 describe 'Amico::VERSION' do
   it 'should be the correct version' do
-    Amico::VERSION.should == '2.1.0'
+    Amico::VERSION.should == '2.2.0'
   end
 end

data/spec/spec_helper.rb

@@ -15,8 +15,10 @@ RSpec.configure do |config|
       configuration.following_key = 'following'
       configuration.followers_key = 'followers'
       configuration.blocked_key = 'blocked'
+      configuration.blocked_by_key = 'blocked_by'
       configuration.reciprocated_key = 'reciprocated'
       configuration.pending_key = 'pending'
+      configuration.pending_with_key = 'pending_with'
       configuration.default_scope_key = 'default'
       configuration.pending_follow = false
       configuration.page_size = 25

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amico
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-20 00:00:00.000000000 Z
+date: 2012-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -95,12 +95,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1949101995631561364
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1949101995631561364
 requirements: []
 rubyforge_project: amico
 rubygems_version: 1.8.24