hari 0.0.3 → 0.0.4

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    MDFjMThhM2VkNGMwNTRlYTMzNDM2Y2UyN2E5MDZhOTYxZDViZWI3MQ==
-  data.tar.gz: !binary |-
-    NTM0ZDBmNmJkYjMwOGZiNGRiZWE0MDg3NjYzZjIzZjBlNWY3YWI2Nw==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    MTA3OTM4MTkxN2E3MWM0YjRkNjBkYjNhNzc1OWIxMjZhMzU2NTJlYmZlNjRl
-    NmZmOTZkZjY3Yzk4ZTY3Zjk3NzRiMjJkMjdlMTNjNDgyZGFiZGQ1ZGY2YmQw
-    ZmZiN2JkZmEzYzkwZDI3Y2M4YzQ1NDlmZTExOTM0ODY0N2NlMDQ=
-  data.tar.gz: !binary |-
-    ZDBlNjJiYTg3NWRiMzU5YTkzNDRiNzRlOGE3MDFhYzI3ZDI0YWI4M2UzZDkx
-    NjljYTE1ODUwZjlkODIxZjc5Y2E4N2Q1ZjU0OGYxMTM4MDgxYzRlMTZiZDEw
-    ZWY2ZDIyNmIwYjU5NjRjMDI5ZjQyYWM5MTZhZDQ2YmJiZWQxNDg=
+SHA1:
+  metadata.gz: 6bec03d308713945bce8a8b110c663beb57450f7
+  data.tar.gz: 4679c39080577b390539c16921264c6d69ce0b50
+SHA512:
+  metadata.gz: 8d1b9c6f45f02be08c99b3f01286031d7c94a64a91d9f14c904acfd9934e0c3c9fa986cdf05a77b8af93d4e37ba25d2d8837d59fc1082cf112c315229a306ab3
+  data.tar.gz: 984b40a10bc769cb874b6879bfd10de44b970225480ed2d73285d6536ef5aed4f148d114721e160c7a79fc6ecd73646fc7e9f42edfe72c47a740579d35c9f139

data/LICENSE

@@ -1,18 +1,20 @@
-Copyright (c) 2013, Clubjudge
-All rights reserved.
+The MIT License (MIT)
 
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+Copyright (c) 2013 ClubJudge B.V.
 
- - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the docume
-   ntation and/or other materials provided with the distribution.
- - Neither the name of the Clubjudge nor the names of its contributors may be used to endorse or promote products derived from this
-   software without specific prior written permission.
+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:
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUD
-ING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN N
-O EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR C
-ONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR P
-ROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
- TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBI
- LITY OF SUCH DAMAGE.
+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

@@ -1,22 +1,142 @@
 [![Build Status](https://travis-ci.org/Clubjudge/hari.png?branch=master)](https://travis-ci.org/Clubjudge/hari)
 
-## hari
+# Hari
 
-Hari is a library to persist and get nodes and its relations in Redis, using different data structures depending on your need.
+## Mile-high view
 
-    Hari(user: 23).out(:follow).out(:activity).limit(25)
+**Hari** is a tool to abstract complex relationships between **Ruby** objects onto **Redis** data structures. It allows for expressive querying of those relationships as well, in an easy way. It is mostly geared towards typical social networking concepts like news feeds, activity logs, friends of friends, mutual friends, and so on.
 
-The query above will return the top `25` activities from all nodes user `23` follows.
+## Basic concepts
 
-### Relations
+Hari embraces normal objects, and allows 2 major modes of operation: abstraction of Redis operations, and actual relationship creation and querying.
+
+## Abstraction of Redis operations (lists, sets, sorted sets, etc)
+
+Imagine this `User` model class:
+
+```ruby
+class User
+
+  attr_reader :id
+
+  def initialize(id)
+    @id = id
+  end
+
+end
+```
+
+You can create a **set** to store the user relation with his friends:
+
+```ruby
+user = User.new(20)
+
+Hari(user).set(:friends_ids) << 10   # REDIS: SADD hari:user#20:friends_ids 10
+```
+
+Then it's possible, for instance, to query the mutual friends between users:
+
+```ruby
+Hari(user: 20).set(:friends_ids) & Hari(user: 30).set(:friends_ids)
+
+=> ["10", "25", "40"]
+```
+
+By now, you're probably wandering what the `Hari()` method does. It accepts an object like `user` as a parameter, or an identification of this object like `"user#20"`, or even `{user: 30}` and returns a `Hari::Node` representation of the object referenced so you can call all operations available in Hari.
+
+### [Lists](https://github.com/Clubjudge/hari/wiki/Lists), [Sets](https://github.com/Clubjudge/hari/wiki/Sets) and [Sorted Sets](https://github.com/Clubjudge/hari/wiki/Sorted-Sets) operations are available in the Wiki.
+
+## Relationships
+
+Hari uses the power of Redis data structures to create relations between objects, allowing you to traverse nodes and its relations like a graph.
+
+```ruby
+# this gets the last 20 comments from the entities the user#1 follows
+Hari(user: 1).out(:follow).out(:comments).limit(20)
+```
 
 Creating a relation can be as simple as:
 
-    Hari.relation! :follow, user, event
+```ruby
+Hari.relation! :follow, user, artist
+```
+
+To remove a relation, do:
+
+```ruby
+Hari.remove_relation! :follow, user, artist
+```
+
+Let's mount some queries:
+
+```ruby
+# artist followers
+Hari(artist).in(:follow)
+
+# entities that user follow
+Hari(user).out(:follow)
+
+# just the last 10 followers of artist
+Hari(artist).in(:follow).limit(10)
+
+# paginates from a score (timestamp.to_f),
+# bringing the next 10 followers up from a last timestamp,
+# (useful for pooling streams)
+Hari(artist).in(:follow).limit(10).from(1375977470.382)
+
+# paginates from a score down,
+# bringing the previous 10 followers from a last timestamp
+Hari(artist).in(:follow).limit(10).from(1375977470.382, :down)
+
+# chaining relations between nodes
+# last 10 entities to be followed by who user follows
+Hari(user).out(:follow).out(:follow).limit(10)
+
+# All users following artist
+Hari(artist).in(:follow).type(:user)
+```
+
+All the calls above return a lazy query expression. The ruby code still didn't fetch the Redis backend, it's mounting a composable query.
+
+Below there are some of the methods that make the query come to an end:
+
+```ruby
+# how many followers
+Hari(artist).in(:follow).count
+=> 2001
+
+# returns all followers nodes ids
+Hari(artist).in(:follow).nodes_ids!
+=> ['artist#20', 'user#30', 'user#33']
+
+
+# returns all followers instances of Hari::Node
+# depends that you have the nodes persisted for each object
+# this is the default implementation when you do .to_a
+Hari(artist).in(:follow).nodes!
+
+tiesto_followers   = Hari(artist: 21).in(:follow).type(:user)
+daftpunk_followers = Hari(artist: 42).in(:follow).type(:user)
+
+# count of common users following two artists
+tiesto_followers.intersect_count(daft_punk_followers)
+=> 6
+
+# actual users ids following two artists
+tiesto_followers.intersect(daft_punk_followers)
+=> [17, 29, 3, 173, 919, 11]
+
+# paginating through them (start + stop)
+tiesto_followers.intersect(daft_punk_followers, 2, 5)
+=> [3, 173, 919]
+
+user_friends = Hari(user).out(:follow).type(:user)
 
-    # where user / event are:
+# bringing all followers of artist, but user's friends first
+tiesto_followers.sort_by user_friends
+=> [883, 317, 211, 157, 163, 103, 47, 53, 7]
 
-    - objects with #id method (node representation will be class#id, like user#23)
-    - strings with node_type#node_id
-    - hash like { node_type => node_id }
-    - a Hari::Node instance
+# paginating through them (offset + count)
+tiesto_followers.sort_by user_friends, 3, 5
+=> [157, 163, 103, 47, 53]
+```

data/lib/hari/entity/property.rb

@@ -1,8 +1,7 @@
-require 'hari/entity/property/builder'
-
 module Hari
   class Entity
     class Property
+      autoload :Builder, 'hari/entity/property/builder'
 
       attr_accessor :name, :serializer, :options
 

data/lib/hari/entity/serialization.rb

@@ -1,16 +1,16 @@
-require 'hari/entity/serialization/boolean'
-require 'hari/entity/serialization/date'
-require 'hari/entity/serialization/datetime'
-require 'hari/entity/serialization/float'
-require 'hari/entity/serialization/integer'
-require 'hari/entity/serialization/string'
-require 'hari/entity/serialization/time'
-
 module Hari
   class Entity
     module Serialization
       extend ActiveSupport::Concern
 
+      autoload :Boolean,  'hari/entity/serialization/boolean'
+      autoload :Date,     'hari/entity/serialization/date'
+      autoload :DateTime, 'hari/entity/serialization/datetime'
+      autoload :Float,    'hari/entity/serialization/float'
+      autoload :Integer,  'hari/entity/serialization/integer'
+      autoload :String,   'hari/entity/serialization/string'
+      autoload :Time,     'hari/entity/serialization/time'
+
       def to_json
         hash = self.class.properties.inject({}) do |buffer, prop|
           buffer.merge prop.name => prop.serialize(send(prop.name))

data/lib/hari/entity.rb

@@ -7,6 +7,11 @@ module Hari
     extend  ActiveModel::Naming
     extend  ActiveModel::Callbacks
     include ActiveModel::Validations
+
+    autoload :Property,      'hari/entity/property'
+    autoload :Repository,    'hari/entity/property'
+    autoload :Serialization, 'hari/entity/property'
+
     extend  Property::Builder
     include Repository
     include Serialization

data/lib/hari/keys/key.rb

@@ -0,0 +1,48 @@
+module Hari
+  module Keys
+    class Key
+
+      attr_reader :node, :name
+
+      def initialize(node = nil)
+        @node = node
+      end
+
+      def key
+        @key ||= begin
+          prefix = node ? "#{Hari.node_key(node)}:" : ''
+          prefix + name.to_s
+        end
+      end
+
+      def delete!
+        Hari.redis.del key
+      end
+
+      def exists?
+        Hari.redis.exists key
+      end
+
+      def expire(milliseconds)
+        Hari.redis.pexpire key, milliseconds
+      end
+
+      def expire_at(timestamp)
+        Hari.redis.expireat key, ::Time.parse(timestamp).to_s
+      end
+
+      def persist
+        Hari.redis.persist key
+      end
+
+      def type
+        Hari.redis.type key
+      end
+
+      def ttl
+        Hari.redis.ttl key
+      end
+
+    end
+  end
+end

data/lib/hari/keys/list.rb

@@ -0,0 +1,132 @@
+module Hari
+  module Keys
+    class List < Key
+
+      def list(name)
+        @name = name
+        self
+      end
+
+      def list!(name)
+        @name = name
+        range
+      end
+
+      def [](*args)
+        arg = args.first
+
+        if args.size == 2
+          range *args
+        elsif arg.kind_of? Integer
+          at arg
+        elsif arg.kind_of? Range
+          range arg.first, arg.last
+        end
+      end
+
+      def first
+        self[0]
+      end
+
+      def last
+        self[-1]
+      end
+
+      def []=(index, member)
+        Hari.redis.lset key, index, member
+      end
+
+      def range(start = 0, stop = -1)
+        Hari.redis.lrange key, start, stop
+      end
+
+      alias :members :range
+      alias :to_a    :range
+
+      def from(index)
+        range index
+      end
+
+      def to(index)
+        range 0, index
+      end
+
+      def at(index)
+        Hari.redis.lindex key, index
+      end
+
+      alias :index :at
+
+      def trim(start, stop)
+        Hari.redis.ltrim key, start, stop
+      end
+
+      def count
+        Hari.redis.llen key
+      end
+
+      alias :size :count
+      alias :length :count
+
+      def empty?
+        count == 0
+      end
+
+      def one?
+        count == 1
+      end
+
+      def many?
+        count > 1
+      end
+
+      def include?(member)
+        range.include? member
+      end
+
+      alias :member? :include?
+
+      def push(*members)
+        Hari.redis.rpush key, members
+      end
+
+      alias :rpush :push
+      alias :add   :push
+
+      def lpush(*members)
+        Hari.redis.lpush key, members
+      end
+
+      def <<(member)
+        push member
+      end
+
+      def insert_before(pivot, member)
+        Hari.redis.linsert key, :before, pivot, member
+      end
+
+      def insert_after(pivot, member)
+        Hari.redis.linsert key, :after, pivot, member
+      end
+
+      alias :insert :insert_after
+
+      def delete(member, count = 0)
+        Hari.redis.lrem key, count, member
+      end
+
+      def pop
+        Hari.redis.rpop key
+      end
+
+      alias :rpop :pop
+
+      def shift
+        Hari.redis.lpop key
+      end
+
+      alias :lpop :shift
+
+    end
+  end
+end

data/lib/hari/keys/set.rb

@@ -0,0 +1,101 @@
+module Hari
+  module Keys
+    class Set < Key
+
+      def set(name)
+        @name = name
+        self
+      end
+
+      def set!(name)
+        @name = name
+        members
+      end
+
+      def members
+        Hari.redis.smembers key
+      end
+
+      def rand(count = 1)
+        Hari.redis.srandmember key, count
+      end
+
+      def count
+        Hari.redis.scard key
+      end
+
+      alias :size :count
+      alias :length :count
+
+      def empty?
+        count == 0
+      end
+
+      def one?
+        count == 1
+      end
+
+      def many?
+        count > 1
+      end
+
+      def include?(member)
+        Hari.redis.sismember key, member
+      end
+
+      alias :member? :include?
+
+      def add(*members)
+        Hari.redis.sadd key, members
+      end
+
+      def <<(member)
+        add member
+      end
+
+      def delete(*members)
+        Hari.redis.srem key, members
+      end
+
+      def pop
+        Hari.redis.spop key
+      end
+
+      def intersect(*set_queries)
+        Hari.redis.sinter key, set_query_keys(set_queries)
+      end
+
+      def &(other_set_query)
+        intersect other_set_query
+      end
+
+      def diff(*set_queries)
+        Hari.redis.sdiff key, set_query_keys(set_queries)
+      end
+
+      def -(other_set_query)
+        diff other_set_query
+      end
+
+      private
+
+      def set_query_keys(set_queries)
+        keys = set_queries.map do |query|
+          ensure_set_query! query
+          query.key
+        end
+
+        fail 'no query keys' if keys.empty?
+
+        keys
+      end
+
+      def ensure_set_query!(query)
+        unless query.kind_of?(Hari::Keys::Set)
+          fail 'not a set query'
+        end
+      end
+
+    end
+  end
+end

data/lib/hari/keys/sorted_set.rb

@@ -0,0 +1,115 @@
+module Hari
+  module Keys
+    class SortedSet < Key
+
+      def sorted_set(name)
+        @name = name
+        self
+      end
+
+      def sorted_set!(name)
+        @name = name
+        members
+      end
+
+      def range(start = 0, stop = -1, options = {})
+        return revrange(start, stop, options) if options[:desc]
+
+        Hari.redis.zrange key, start, stop, options.slice(:with_scores)
+      end
+
+      alias :members :range
+
+      def range_with_scores
+        range 0, -1, with_scores: true
+      end
+
+      def revrange(start = 0, stop = -1, options = {})
+        Hari.redis.zrevrange key, start, stop, options.slice(:with_scores)
+      end
+
+      alias :reverse_range :revrange
+      alias :desc_range    :revrange
+
+      def revrange_with_scores
+        revrange 0, -1, with_scores: true
+      end
+
+      def range_by_score(min, max, options = {})
+        return revrange_by_score(min, max, options) if options[:desc]
+
+        Hari.redis.zrangebyscore key, min, max, options.slice(:with_scores, :limit)
+      end
+
+      def revrange_by_score(min, max, options = {})
+        Hari.redis.zrevrangebyscore key, max, min, options.slice(:with_scores, :limit)
+      end
+
+      def rank(member, options = {})
+        return revrank(member, options) if options[:desc]
+
+        Hari.redis.zrank key, member
+      end
+
+      alias :ranking  :rank
+      alias :position :rank
+
+      def revrank(member)
+        Hari.redis.zrevrank key, member
+      end
+
+      alias :reverse_ranking  :revrank
+      alias :reverse_position :revrank
+
+      def count
+        Hari.redis.zcard key
+      end
+
+      alias :size :count
+      alias :length :count
+
+      def empty?
+        count == 0
+      end
+
+      def one?
+        count == 1
+      end
+
+      def many?
+        count > 1
+      end
+
+      def include?(member)
+        score(member).present?
+      end
+
+      alias :member? :include?
+
+      def score(member)
+        Hari.redis.zscore key, member
+      end
+
+      def add(*score_members)
+        Hari.redis.zadd key, score_members.to_a.flatten
+      end
+
+      def <<(*score_members)
+        add score_members
+      end
+
+      def delete(*members)
+        Hari.redis.zrem key, members
+      end
+
+      def trim_by_rank(start, stop)
+        Hari.redis.zremrangebyrank key, start, stop
+      end
+
+      def trim_by_score(min, max)
+        Hari.redis.zremrangebyscore key, min, max
+      end
+
+    end
+  end
+end