redstruct 0.1.7 → 0.2.0

data/lib/redstruct/set.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'redstruct/struct'
+require 'redstruct/utils/iterable'
+
+module Redstruct
+  # Mapping between Redis and Ruby sets. There is no caching mechanism in play, so most methods actually do access
+  # the underlying redis connection. Also, keep in mind Redis converts all values strings on the DB side
+  class Set < Redstruct::Struct
+    include Redstruct::Utils::Iterable
+
+    # Clears the set by simply removing the key from the DB
+    # @see Redstruct::Struct#delete
+    def clear
+      delete
+    end
+
+    # Returns random items from the set
+    # @param [Integer] count the number of items to return
+    # @return [String, Set] if count is one, then return the item; otherwise returns a set
+    def random(count: 1)
+      list = self.connection.srandmember(@key, count)
+
+      return nil if list.nil?
+      return count == 1 ? list[0] : ::Set.new(list)
+    end
+
+    # Checks if the set is empty by checking if the key actually exists on the underlying redis db
+    # @see Redstruct::Struct#exists?
+    # @return [Boolean] true if it is empty, false otherwise
+    def empty?
+      return !exists?
+    end
+
+    # Checks if the set contains this particular item
+    # @param [#to_s] item the item to check for
+    # @return [Boolean] true if the set contains the item, false otherwise
+    def contain?(item)
+      return coerce_bool(self.connection.sismember(@key, item))
+    end
+    alias include? contain?
+
+    # Adds the given items to the set
+    # @param [Array<#to_s>] items the items to add to the set
+    # @return [Boolean, Integer] when only one item, returns true or false on insertion, otherwise the number of items added
+    def add(*items)
+      return self.connection.sadd(@key, items)
+    end
+    alias << add
+
+    # Pops and returns an item from the set.
+    # NOTE: Since this is a redis set, keep in mind that popping the last element of the set effectively deletes the set
+    # @return [String] popped item
+    def pop
+      return self.connection.spop(@key)
+    end
+
+    # Removes the given items from the set.
+    # @param [Array<#to_s>] items the items to remove from the set
+    # @return [Boolean, Integer] when only one item, returns true or false on deletion, otherwise the number of items removed
+    def remove(*items)
+      return self.connection.srem(@key, items)
+    end
+
+    # @return [Integer] the number of items in the set
+    def size
+      return self.connection.scard(@key).to_i
+    end
+
+    # Computes the difference of the two sets and stores the result in `dest`. If no destination provided, computes
+    # the results in memory.
+    # @param [Redstruct::Set] other set the set to subtract
+    # @param [Redstruct::Set, String] dest if nil, results are computed in memory. if a string, a new Redstruct::Set is
+    # constructed with the string as the key, and results are stored there. if already a Redstruct::Set, results are stored there.
+    # @return [::Set, Integer] if dest was provided, returns the number of elements in the destination; otherwise a standard Ruby set containing the difference
+    def difference(other, dest: nil)
+      destination = coerce_destination(dest)
+      results = if destination.nil?
+        ::Set.new(self.connection.sdiff(@key, other.key))
+      else
+        self.connection.sdiffstore(destination.key, @key, other.key)
+      end
+
+      return results
+    end
+    alias - difference
+
+    # Computes the interesection of the two sets and stores the result in `dest`. If no destination provided, computes
+    # the results in memory.
+    # @param [Redstruct::Set] other set the set to intersect
+    # @param [Redstruct::Set, String] dest if nil, results are computed in memory. if a string, a new Redstruct::Set is
+    # constructed with the string as the key, and results are stored there. if already a Redstruct::Set, results are stored there.
+    # @return [::Set, Integer] if dest was provided, returns the number of elements in the destination; otherwise a standard Ruby set containing the intersection
+    def intersection(other, dest: nil)
+      destination = coerce_destination(dest)
+      results = if destination.nil?
+        ::Set.new(self.connection.sinter(@key, other.key))
+      else
+        self.connection.sinterstore(destination.key, @key, other.key)
+      end
+
+      return results
+    end
+    alias | intersection
+
+    # Computes the union of the two sets and stores the result in `dest`. If no destination provided, computes
+    # the results in memory.
+    # @param [Redstruct::Set] other set the set to add
+    # @param [Redstruct::Set, String] dest if nil, results are computed in memory. if a string, a new Redstruct::Set is
+    #  constructed with the string as the key, and results are stored there. if already a Redstruct::Set, results are stored there.
+    # @return [::Set, Integer] if dest was provided, returns the number of elements in the destination; otherwise a standard Ruby set containing the union
+    def union(other, dest: nil)
+      destination = coerce_destination(dest)
+      results = if destination.nil?
+        ::Set.new(self.connection.sunion(@key, other.key))
+      else
+        self.connection.sunionstore(destination.key, @key, other.key)
+      end
+
+      return results
+    end
+    alias + union
+
+    # Use redis-rb sscan_each method to iterate over particular keys
+    # @return [Enumerator] base enumerator to iterate of the namespaced keys
+    def to_enum(match: '*', count: 10)
+      return self.connection.sscan_each(@key, match: match, count: count)
+    end
+
+    # Returns an array representation of the set. Ordering is random and defined by redis
+    # NOTE: If the set is particularly large, consider using #each
+    # @return [Array<String>] an array of all items contained in the set
+    def to_a
+      return self.connection.smembers(@key)
+    end
+
+    # Loads all members of the set and converts them to a Ruby set.
+    # NOTE: If the set is particularly large, consider using #each
+    # @return [::Set] ruby set of all items stored on redis for this set
+    def to_set
+      return ::Set.new(to_a)
+    end
+
+    def coerce_destination(dest)
+      case dest
+      when ::String
+        @factory.set(dest)
+      when self.class
+        dest
+      end
+    end
+    private :coerce_destination
+  end
+end

data/lib/redstruct/sorted_set/slice.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Redstruct
+  class SortedSet
+    # Utility class to allow operations on portions of the set only
+    # TODO: Support #length property (using LIMIT offset count) of the different
+    # range commands, so a slice could be defined as starting at offset X and
+    # having length Y, instead of just starting at X and finishing at Y.
+    class Slice < Redstruct::Factory::Object
+      # @return [String] the key for the underlying sorted set
+      attr_reader :key
+
+      # @return [String, Float] the lower bound of the slice
+      attr_reader :lower
+
+      # @return [String, Float] the upper bound of the slice
+      attr_reader :upper
+
+      # @return [Boolean] if true, then assumes the slice is lexicographically sorted
+      attr_reader :lex
+
+      # @return [Boolean] if true, assumes the range bounds are exclusive
+      attr_reader :exclusive
+
+      # @param [String, Float] lower lower bound for the slice operation
+      # @param [String, Float] upper upper bound for the slice operation
+      # @param [Boolean] lex if true, uses lexicographic operations
+      # @param [Boolean] exclusive if true, assumes bounds are exclusive
+      def initialize(set, lower: nil, upper: nil, lex: false, exclusive: false)
+        super(factory: set.factory)
+
+        @key = set.key
+        @lex = lex
+        @exclusive = exclusive
+
+        lower ||= -Float::INFINITY
+        upper ||= Float::INFINITY
+
+        if @lex
+          @lower = parse_lex_bound(lower)
+          @upper = parse_lex_bound(upper)
+        else
+          @lower = parse_bound(lower)
+          @upper = parse_bound(upper)
+        end
+      end
+
+      # @return [Array<String>] returns an array of values for the given bounds
+      def to_a
+        if @lex
+          self.connection.zrangebylex(@key, @lower, @upper)
+        else
+          self.connection.zrangebyscore(@key, @lower, @upper)
+        end
+      end
+
+      # @return [Array<String>] returns an array of values reversed
+      def reverse
+        if @lex
+          self.connection.zrevrangebylex(@key, @lower, @upper)
+        else
+          self.connection.zrevrangebyscore(@key, @lower, @upper)
+        end
+      end
+
+      # @return [Integer] the number of elements removed
+      def remove
+        if @lex
+          self.connection.zremrangebylex(@key, @lower, @upper)
+        else
+          self.connection.zremrangebyscore(@key, @lower, @upper)
+        end
+      end
+
+      # @return [Integer] number of elements in the slice
+      def size
+        if @lex
+          self.connection.zlexcount(@key, @lower, @upper)
+        else
+          self.connection.zcount(@key, @lower, @upper)
+        end
+      end
+
+      # TODO: consider using SortedSet, some other data structure, or nothing
+      # @return [::Set] an unordered set representation of the slice
+      def to_set
+        ::Set.new(to_a)
+      end
+
+      def inspectable_attributes
+        { lower: @lower, upper: @upper, lex: @lex, exclusive: @exclusive, key: @key }
+      end
+
+      private
+
+      # ( is exclusive, [ is inclusive
+      def parse_lex_bound(bound)
+        case bound
+        when -Float::INFINITY then '-'
+        when Float::INFINITY then '+'
+        else prefix(bound, inclusion: '[', exclusion: '(')
+        end
+      end
+
+      # ( is exclusive
+      def parse_bound(bound)
+        case bound
+        when -Float::INFINITY then '-inf'
+        when Float::INFINITY then '+inf'
+        when String then prefix(bound, exclusion: '(')
+        else prefix(bound.to_f, exclusion: '(')
+        end
+      end
+
+      def prefix(value, inclusion: '', exclusion: '')
+        prefix = @exclusive ? exclusion : inclusion
+        prefixed = value
+        prefixed = "#{prefix}#{value}" unless prefix.empty? || prefixed.to_s.start_with?(prefix)
+
+        return prefixed
+      end
+    end
+  end
+end

data/lib/redstruct/sorted_set.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'redstruct/struct'
+require 'redstruct/utils/iterable'
+
+module Redstruct
+  # Mapping between Redis and Ruby sorted sets (with scores). There is no caching mechanism in play, so most methods actually do access
+  # the underlying redis connection. Also, keep in mind Redis converts all values strings on the DB side
+  class SortedSet < Redstruct::Struct
+    include Redstruct::Utils::Iterable
+
+    # @param [Boolean] lex if true, assumes the set is lexicographically sorted
+    def initialize(lex: false, **options)
+      super(**options)
+      @lex = lex
+    end
+
+    # @return [Boolean] true if this is a lexicographically sorted set
+    def lexicographic?
+      return @lex
+    end
+
+    # @param [Array<#to_s>] values the object to add to the set
+    # @param [Boolean] exists if true, only update elements that exist (do not add new ones)
+    # @param [Boolean] overwrite if false, do not update existing elements
+    # @return [Integer] the number of elements that have changed (includes new ones)
+    def add(*values, exists: false, overwrite: true)
+      options = { xx: exists, nx: !overwrite, ch: true }
+
+      if @lex
+        values = values.map do |pair|
+          member = pair.is_a?(Array) ? pair.last : pair
+          [0.0, member]
+        end
+      end
+
+      return self.connection.zadd(@key, values, options)
+    end
+
+    # @param [#to_s] member the member of the set whose score to increment
+    # @param [#to_f] by the amount to increment the score by
+    # @return [Float] the new score of the member
+    def increment(member, by: 1.0)
+      raise NotImplementedError, 'cannot increment the score of items in a lexicographically ordered set' if @lex
+      return self.connection.zincrby(@key, by.to_f, member.to_s).to_f
+    end
+
+    # @param [#to_s] member the member of the set whose score to decrement
+    # @param [#to_f] by the amount to decrement the score by
+    # @return [Float] the new score of the member
+    def decrement(member, by: 1.0)
+      return increment(member, by: -by.to_f)
+    end
+
+    # Removes all items from the set. Does this by simply deleting the key
+    # @see Redstruct::Struct#delete
+    def clear
+      delete
+    end
+
+    # Returns the number of items in the set. If you want to specify within a
+    # range, first get the slice and query its size.
+    # @return [Integer] the number of items in the set
+    def size
+      return self.connection.zcard(@key)
+    end
+
+    # Returns a slice or partial selection of the set.
+    # @see Redstruct::SortedSet::Slice#initialize
+    # @return [Redstruct::SortedSet::Slice] a newly created slice for this set
+    def slice(**options)
+      defaults = {
+        lower: nil,
+        upper: nil,
+        exclusive: false,
+        lex: @lex
+      }
+
+      self.class::Slice.new(self, **defaults.merge(options))
+    end
+
+    # Checks if the set contains any items.
+    # @return [Boolean] true if the key exists (meaning it contains at least 1 item), false otherwise
+    def empty?
+      return !exists?
+    end
+
+    # Relies on the score method, since it is O(1), whereas the index method is
+    # O(logn)
+    # @param [#to_s] item the item to check for
+    # @return [Boolean] true if the item is in the set, false otherwise
+    def contain?(item)
+      return coerce_bool(score(item))
+    end
+    alias include? contain?
+
+    # Returns the index of the item in the set, sorted ascending by score
+    # @param [#to_s] item the item to check for
+    # @return [Integer, nil] the index of the item, or nil if not found
+    def index(item)
+      return self.connection.zrank(@key, item)
+    end
+
+    # Returns the index of the item in the set, sorted descending by score
+    # @param [#to_s] item the item to check for
+    # @return [Integer, nil] the index of the item, or nil if not found
+    def rindex(item)
+      return self.connection.zrevrank(@key, item)
+    end
+
+    # Returns the score of the given item.
+    # @param [#to_s] item the item to check for
+    # @return [Float, nil] the score of the item, or nil if not found
+    def score(item)
+      return self.connection.zscore(@key, item)
+    end
+
+    # Removes the items from the set.
+    # @param [Array<#to_s>] items the items to remove from the set
+    # @return [Integer] the amount of items removed from the set
+    def remove(*items)
+      return self.connection.zrem(@key, items)
+    end
+
+    # Returns an array representation of the set, sorted by score ascending
+    # NOTE: It pulls the whole set into memory, so use each if that's a concern,
+    # or use slices with pre-determined ranges.
+    # @return [Array<Redstruct::Utils::ScoredValue>] all the items in the set, sorted by score ascending
+    def to_a
+      return slice.to_a
+    end
+
+    # TODO: Consider using ::SortedSet or some other data structure
+    # @return [::Set] an unordered set representation
+    def to_set
+      return slice.to_set
+    end
+
+    # Use redis-rb zscan_each method to iterate over particular keys
+    # @return [Enumerator] base enumerator to iterate of the namespaced keys
+    def to_enum(match: '*', count: 10, with_scores: false)
+      enumerator = self.connection.zscan_each(@key, match: match, count: count)
+      return enumerator if with_scores
+      return Enumerator.new do |yielder|
+        loop do
+          item, = enumerator.next
+          yielder << item
+        end
+      end
+    end
+  end
+end

data/lib/redstruct/string.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'redstruct/struct'
+require 'redstruct/utils/scriptable'
+
+module Redstruct
+  # Manipulation of redis strings
+  class String < Redstruct::Struct
+    include Redstruct::Utils::Scriptable
+
+    # @return [String, nil] the string value stored in the database
+    def get
+      return self.connection.get(@key)
+    end
+
+    # @param [#to_s] value the object to store
+    # @param [Integer] expiry the expiry time in seconds; if nil, will never expire
+    # @param [Boolean] nx Not Exists: if true, will not set the key if it already existed
+    # @param [Boolean] xx Already Exists: if true, will set the key only if it already existed
+    # @return [Boolean] true if set, false otherwise
+    def set(value, expiry: nil, nx: false, xx: false)
+      options = { nx: nx, xx: xx }
+      options[:ex] = expiry.to_i unless expiry.nil?
+
+      coerce_bool(self.connection.set(@key, value, options))
+    end
+
+    # @param [String] value The value to compare with
+    # @return [Boolean] True if deleted, false otherwise
+    def delete_if_equals(value)
+      coerce_bool(delete_if_equals_script(keys: @key, argv: value))
+    end
+
+    # @param [#to_s] value The object to store
+    # @return [String] The old value before setting it
+    def getset(value)
+      self.connection.getset(@key, value)
+    end
+
+    # @return [Integer] The length of the string
+    def length
+      self.connection.strlen(@key)
+    end
+
+    # @param [Integer] start Starting index of the slice
+    # @param [Integer] length Length of the slice; negative numbers start counting from the right (-1 = end)
+    # @return [Array<String>] The requested slice from <start> with length <length>
+    def slice(start = 0, length = -1)
+      length = start + length if length >= 0
+      return self.connection.getrange(@key, start, length)
+    end
+
+    # Deletes the key (keys[1]) iff the value is equal to argv[1].
+    # @param [Array<(::String)>] keys The key to delete
+    # @param [Array<(::String)>] argv The value to compare with
+    # @return [Integer] 1 if deleted, 0 otherwise
+    defscript :delete_if_equals_script, <<~LUA
+      local deleted = false
+      if redis.call("get", KEYS[1]) == ARGV[1] then
+        deleted = redis.call("del", KEYS[1])
+      end
+
+      return deleted
+    LUA
+  end
+end

data/lib/redstruct/struct.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'redstruct/factory/object'
+require 'redstruct/utils/coercion'
+
+module Redstruct
+  # Base class for all redis structures which have a particular value for a given key
+  class Struct < Redstruct::Factory::Object
+    include Redstruct::Utils::Coercion
+
+    # @return [String] the key used to identify the struct on redis
+    attr_reader :key
+
+    # @param [String] key the key used to identify the struct on redis, already namespaced
+    def initialize(key:, **options)
+      super(**options)
+      @key = key
+    end
+
+    # @return [Boolean] Returns true if it exists in redis, false otherwise
+    def exists?
+      return self.connection.exists(@key)
+    end
+
+    # @return [Boolean] false if nothing was deleted in the DB, true if it was
+    def delete
+      return coerce_bool(self.connection.del(@key))
+    end
+
+    # Sets the key to expire after ttl seconds
+    # @param [#to_f] ttl the time to live in seconds (where 0.001 = 1ms)
+    # @return [Boolean] true if expired, false otherwise
+    def expire(ttl)
+      ttl = (ttl.to_f * 1000).floor
+      return coerce_bool(self.connection.pexpire(@key, ttl))
+    end
+
+    # Sets the key to expire at the given timestamp.
+    # @param [#to_f] time time or unix timestamp at which the key should expire; once converted to float, assumes 1.0 is one second, 0.001 is 1 ms
+    # @return [Boolean] true if expired, false otherwise
+    def expire_at(time)
+      time = (time.to_f * 1000).floor
+      return coerce_bool(self.connection.pexpireat(@key, time))
+    end
+
+    # Removes the expiry time from a key
+    # @return [Boolean] true if persisted, false otherwise
+    def persist
+      coerce_bool(self.connection.persist(@key))
+    end
+
+    # @return [String] the underlying redis type
+    def type
+      self.connection.type(@key)
+    end
+
+    # Returns the time to live of the key
+    # @return [Float] time to live in seconds as a float where 0.001 == 1 ms
+    def ttl
+      return self.connection.pttl(@key) / 1000.0
+    end
+
+    # Returns a serialized representation of the key, which can be used to store a value externally, and restored to
+    # redis using #restore
+    # NOTE: This does not capture the TTL of the struct. If there arises a need for this, we can always modify it,
+    # but for now this is a pure proxy of the redis dump command
+    # @return [String, nil] nil if the struct does not exist, otherwise serialized representation
+    def dump
+      return self.connection.dump(@key)
+    end
+
+    # Restores the struct to its serialized value as given
+    # @param [String] serialized serialized representation of the value
+    # @param [#to_f] ttl the time to live for the struct; defaults to 0 (meaning no expiry). 0.001 == 1ms
+    # @raise [Redis::CommandError] raised if the serialized value is incompatible or the key already exists
+    # @return [Boolean] true if restored, false otherwise
+    def restore(serialized, ttl: 0)
+      ttl = (ttl.to_f * 1000).floor
+      return self.connection.restore(@key, ttl, serialized)
+    end
+
+    # # @!visibility private
+    def inspectable_attributes
+      super.merge(key: @key)
+    end
+  end
+end

data/lib/redstruct/utils/coercion.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Redstruct
   module Utils
     # Coercion utilities to map Redis replies to Ruby types, or vice-versa
@@ -9,10 +11,12 @@ module Redstruct
       # @param [Object] value The value to coerce
       # @return [Array] The coerced value
       def coerce_array(value)
-        return [] if value.nil?
-        return value if value.is_a?(Array)
-        return value.to_a if value.respond_to?(:to_a)
-        return [value]
+        case value
+        when nil then []
+        when Array then value
+        else
+          value.respond_to?(:to_a) ? value.to_a : [value]
+        end
       end
       module_function :coerce_array
 
@@ -22,10 +26,12 @@ module Redstruct
       # @param [Object] value The object to coerce into a bool
       # @return [Boolean] Coerced value
       def coerce_bool(value)
-        return false if value.nil?
-        return false if value.to_i == 0
-
-        return true
+        case value
+        when nil, false then false
+        when Numeric then !value.zero?
+        else
+          true
+        end
       end
       module_function :coerce_bool
     end

data/lib/redstruct/utils/inspectable.rb

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
+
 module Redstruct
   module Utils
+    # Adds helper methods for calling #inspect on a custom object
     module Inspectable
+      # Generates a human readable list of attributes when inspecting a custom object
+      # @return [String]
       def inspect
         attributes = inspectable_attributes.map do |key, value|
           "#{key}: <#{value.inspect}>"
@@ -8,14 +13,13 @@ module Redstruct
 
         return "#{self.class.name}: #{attributes.join(', ')}"
       end
+      alias to_s inspect
 
+      # To be overloaded by the including class
+      # @return [Hash<String, #inspect>] list of attributes that can be seen
       def inspectable_attributes
         {}
       end
-
-      def to_s
-        return inspect
-      end
     end
   end
 end