familia 1.0.0.pre.rc7 → 1.2.0

data/lib/familia/{types → redistype/types}/list.rb

@@ -2,18 +2,21 @@
 
 module Familia
   class List < RedisType
-    def size
+
+    # Returns the number of elements in the list
+    # @return [Integer] number of elements
+    def element_count
       redis.llen rediskey
     end
-    alias length size
+    alias size element_count
 
     def empty?
-      size.zero?
+      element_count.zero?
     end
 
     def push *values
       echo :push, caller(1..1).first if Familia.debug
-      values.flatten.compact.each { |v| redis.rpush rediskey, to_redis(v) }
+      values.flatten.compact.each { |v| redis.rpush rediskey, serialize_value(v) }
       redis.ltrim rediskey, -@opts[:maxlength], -1 if @opts[:maxlength]
       update_expiration
       self
@@ -26,7 +29,7 @@ module Familia
     alias add <<
 
     def unshift *values
-      values.flatten.compact.each { |v| redis.lpush rediskey, to_redis(v) }
+      values.flatten.compact.each { |v| redis.lpush rediskey, serialize_value(v) }
       # TODO: test maxlength
       redis.ltrim rediskey, 0, @opts[:maxlength] - 1 if @opts[:maxlength]
       update_expiration
@@ -35,11 +38,11 @@ module Familia
     alias prepend unshift
 
     def pop
-      from_redis redis.rpop(rediskey)
+      deserialize_value redis.rpop(rediskey)
     end
 
     def shift
-      from_redis redis.lpop(rediskey)
+      deserialize_value redis.lpop(rediskey)
     end
 
     def [](idx, count = nil)
@@ -57,16 +60,18 @@ module Familia
     end
     alias slice []
 
-    def delete(v, count = 0)
-      redis.lrem rediskey, count, to_redis(v)
+    # Removes elements equal to value from the list
+    # @param value The value to remove
+    # @param count [Integer] Number of elements to remove (0 means all)
+    # @return [Integer] The number of removed elements
+    def remove_element(value, count = 0)
+      redis.lrem rediskey, count, serialize_value(value)
     end
-    alias remove delete
-    alias rem delete
-    alias del delete
+    alias remove remove_element
 
     def range(sidx = 0, eidx = -1)
       elements = rangeraw sidx, eidx
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def rangeraw(sidx = 0, eidx = -1)
@@ -119,7 +124,7 @@ module Familia
     end
 
     def at(idx)
-      from_redis redis.lindex(rediskey, idx)
+      deserialize_value redis.lindex(rediskey, idx)
     end
 
     def first

data/lib/familia/{types → redistype/types}/sorted_set.rb

@@ -2,13 +2,15 @@
 
 module Familia
   class SortedSet < RedisType
-    def size
+    # Returns the number of elements in the sorted set
+    # @return [Integer] number of elements
+    def element_count
       redis.zcard rediskey
     end
-    alias length size
+    alias size element_count
 
     def empty?
-      size.zero?
+      element_count.zero?
     end
 
     # Adds a new element to the sorted set with the current timestamp as the
@@ -44,13 +46,13 @@ module Familia
     end
 
     def add(score, val)
-      ret = redis.zadd rediskey, score, to_redis(val)
+      ret = redis.zadd rediskey, score, serialize_value(val)
       update_expiration
       ret
     end
 
     def score(val)
-      ret = redis.zscore rediskey, to_redis(val, strict_values: false)
+      ret = redis.zscore rediskey, serialize_value(val, strict_values: false)
       ret&.to_f
     end
     alias [] score
@@ -63,20 +65,20 @@ module Familia
 
     # rank of member +v+ when ordered lowest to highest (starts at 0)
     def rank(v)
-      ret = redis.zrank rediskey, to_redis(v, strict_values: false)
+      ret = redis.zrank rediskey, serialize_value(v, strict_values: false)
       ret&.to_i
     end
 
     # rank of member +v+ when ordered highest to lowest (starts at 0)
     def revrank(v)
-      ret = redis.zrevrank rediskey, to_redis(v, strict_values: false)
+      ret = redis.zrevrank rediskey, serialize_value(v, strict_values: false)
       ret&.to_i
     end
 
     def members(count = -1, opts = {})
       count -= 1 if count.positive?
       elements = membersraw count, opts
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
     alias to_a members
     alias all members
@@ -89,7 +91,7 @@ module Familia
     def revmembers(count = -1, opts = {})
       count -= 1 if count.positive?
       elements = revmembersraw count, opts
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def revmembersraw(count = -1, opts = {})
@@ -132,7 +134,7 @@ module Familia
     def range(sidx, eidx, opts = {})
       echo :range, caller(1..1).first if Familia.debug
       elements = rangeraw(sidx, eidx, opts)
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def rangeraw(sidx, eidx, opts = {})
@@ -149,7 +151,7 @@ module Familia
     def revrange(sidx, eidx, opts = {})
       echo :revrange, caller(1..1).first if Familia.debug
       elements = revrangeraw(sidx, eidx, opts)
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def revrangeraw(sidx, eidx, opts = {})
@@ -160,7 +162,7 @@ module Familia
     def rangebyscore(sscore, escore, opts = {})
       echo :rangebyscore, caller(1..1).first if Familia.debug
       elements = rangebyscoreraw(sscore, escore, opts)
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def rangebyscoreraw(sscore, escore, opts = {})
@@ -172,7 +174,7 @@ module Familia
     def revrangebyscore(sscore, escore, opts = {})
       echo :revrangebyscore, caller(1..1).first if Familia.debug
       elements = revrangebyscoreraw(sscore, escore, opts)
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def revrangebyscoreraw(sscore, escore, opts = {})
@@ -201,18 +203,19 @@ module Familia
     alias decr decrement
     alias decrby decrement
 
-    def delete(val)
-      Familia.trace :DELETE, redis, "#{val}<#{val.class}>", caller(1..1) if Familia.debug?
+    # Removes a member from the sorted set
+    # @param value The value to remove from the sorted set
+    # @return [Integer] The number of members that were removed (0 or 1)
+    def remove_element(value)
+      Familia.trace :REMOVE_ELEMENT, redis, "#{value}<#{value.class}>", caller(1..1) if Familia.debug?
       # We use `strict_values: false` here to allow for the deletion of values
       # that are in the sorted set. If it's a horreum object, the value is
       # the identifier and not a serialized version of the object. So either
       # the value exists in the sorted set or it doesn't -- we don't need to
       # raise an error if it's not found.
-      redis.zrem rediskey, to_redis(val, strict_values: false)
+      redis.zrem rediskey, serialize_value(value, strict_values: false)
     end
-    alias remove delete
-    alias rem delete
-    alias del delete
+    alias remove remove_element # deprecated
 
     def at(idx)
       range(idx, idx).first

data/lib/familia/{types → redistype/types}/string.rb

@@ -4,19 +4,21 @@ module Familia
   class String < RedisType
     def init; end
 
-    def size
+    # Returns the number of elements in the list
+    # @return [Integer] number of elements
+    def char_count
       to_s.size
     end
-    alias length size
+    alias size char_count
 
     def empty?
-      size.zero?
+      char_count.zero?
     end
 
     def value
       echo :value, caller(0..0) if Familia.debug
       redis.setnx rediskey, @opts[:default] if @opts[:default]
-      from_redis redis.get(rediskey)
+      deserialize_value redis.get(rediskey)
     end
     alias content value
     alias get value
@@ -30,7 +32,7 @@ module Familia
     end
 
     def value=(val)
-      ret = redis.set(rediskey, to_redis(val))
+      ret = redis.set(rediskey, serialize_value(val))
       update_expiration
       ret
     end
@@ -38,7 +40,7 @@ module Familia
     alias set value=
 
     def setnx(val)
-      ret = redis.setnx(rediskey, to_redis(val))
+      ret = redis.setnx(rediskey, serialize_value(val))
       update_expiration
       ret
     end

data/lib/familia/{types → redistype/types}/unsorted_set.rb

@@ -2,17 +2,20 @@
 
 module Familia
   class Set < RedisType
-    def size
+
+    # Returns the number of elements in the unsorted set
+    # @return [Integer] number of elements
+    def element_count
       redis.scard rediskey
     end
-    alias length size
+    alias size element_count
 
     def empty?
-      size.zero?
+      element_count.zero?
     end
 
     def add *values
-      values.flatten.compact.each { |v| redis.sadd? rediskey, to_redis(v) }
+      values.flatten.compact.each { |v| redis.sadd? rediskey, serialize_value(v) }
       update_expiration
       self
     end
@@ -24,7 +27,7 @@ module Familia
     def members
       echo :members, caller(1..1).first if Familia.debug
       elements = membersraw
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
     alias all members
     alias to_a members
@@ -66,16 +69,17 @@ module Familia
     end
 
     def member?(val)
-      redis.sismember rediskey, to_redis(val)
+      redis.sismember rediskey, serialize_value(val)
     end
     alias include? member?
 
-    def delete(val)
-      redis.srem rediskey, to_redis(val)
+    # Removes a member from the set
+    # @param value The value to remove from the set
+    # @return [Integer] The number of members that were removed (0 or 1)
+    def remove_element(value)
+      redis.srem rediskey, serialize_value(value)
     end
-    alias remove delete
-    alias rem delete
-    alias del delete
+    alias remove remove_element # deprecated
 
     def intersection *setkeys
       # TODO
@@ -90,7 +94,7 @@ module Familia
     end
 
     def random
-      from_redis randomraw
+      deserialize_value randomraw
     end
 
     def randomraw

data/lib/familia/redistype.rb

@@ -16,17 +16,19 @@ module Familia
     extend Familia::Features
 
     @registered_types = {}
-    @valid_options = %i[class parent ttl default db key redis suffix]
+    @valid_options = %i[class parent ttl default db key redis suffix prefix]
     @db = nil
 
     feature :expiration
     feature :quantization
 
     class << self
-      attr_reader :registered_types, :valid_options
+      attr_reader :registered_types, :valid_options, :has_relations
       attr_accessor :parent
       attr_writer :db, :uri
+    end
 
+    module ClassMethods
       # To be called inside every class that inherits RedisType
       # +methname+ is the term used for the class and instance methods
       # that are created for the given +klass+ (e.g. set, list, etc)
@@ -58,7 +60,12 @@ module Familia
       def valid_keys_only(opts)
         opts.select { |k, _| RedisType.valid_options.include? k }
       end
+
+      def has_relations?
+        @has_relations ||= false
+      end
     end
+    extend ClassMethods
 
     attr_reader :keystring, :parent, :opts
     attr_writer :dump_method, :load_method
@@ -89,8 +96,11 @@ module Familia
     # :key => a hardcoded key to use instead of the deriving the from
     # the name and parent (e.g. a derived key: customer:custid:secret_counter).
     #
-    # Uses the redis connection of the parent or the value of
-    # opts[:redis] or Familia.redis (in that order).
+    # :suffix => the suffix to use for the key (e.g. 'scores' in customer:custid:scores).
+    # :prefix => the prefix to use for the key (e.g. 'customer' in customer:custid:scores).
+    #
+    # Connection precendence: uses the redis connection of the parent or the
+    # value of opts[:redis] or Familia.redis (in that order).
     def initialize(keystring, opts = {})
       #Familia.ld " [initializing] #{self.class} #{opts}"
       @keystring = keystring
@@ -210,9 +220,9 @@ module Familia
     include Serialization
   end
 
-  require_relative 'types/list'
-  require_relative 'types/unsorted_set'
-  require_relative 'types/sorted_set'
-  require_relative 'types/hashkey'
-  require_relative 'types/string'
+  require_relative 'redistype/types/list'
+  require_relative 'redistype/types/unsorted_set'
+  require_relative 'redistype/types/sorted_set'
+  require_relative 'redistype/types/hashkey'
+  require_relative 'redistype/types/string'
 end

data/lib/familia.rb

@@ -1,6 +1,7 @@
 # rubocop:disable all
 # frozen_string_literal: true
 
+require 'json'
 require 'redis'
 require 'uri/redis'
 
@@ -35,9 +36,13 @@ module Familia
   @members = []
 
   class << self
-    attr_accessor :debug
+    attr_writer :debug
     attr_reader :members
 
+    def debug
+      @debug ||= ENV['FAMILIA_DEBUG'].to_s.match?(/^(true|1)$/i)
+    end
+
     def included(member)
       raise Problem, "#{member} should subclass Familia::Horreum"
     end

data/try/10_familia_try.rb

@@ -21,7 +21,7 @@ Familia::Horreum::ClassMethods.public_method_defined? :list
 Familia::Horreum::ClassMethods.public_method_defined? :lists
 #=> true
 
-## A Familia object knows its redistype relativess
+## A Familia object knows its redistype relatives
 Bone.redis_types.is_a?(Hash) && Bone.redis_types.has_key?(:owners)
 #=> true
 

data/try/20_redis_type_try.rb

@@ -46,7 +46,7 @@ p [@limiter1.counter.parent.ttl, @limiter2.counter.parent.ttl]
 ##=> "v1:limiter:requests:counter:1302468600"
 
 ## Increment counter
-@limiter1.counter.clear
+@limiter1.counter.delete!
 @limiter1.counter.increment
 #=> 1
 

data/try/21_redis_type_zset_try.rb

@@ -65,4 +65,4 @@ require_relative './test_helpers'
 @a.metrics.members
 #=> ['metric2']
 
-@a.metrics.clear
+@a.metrics.delete!

data/try/22_redis_type_set_try.rb

@@ -31,4 +31,4 @@ ret.class
 #=> 3
 
 
-@a.tags.clear
+@a.tags.delete!

data/try/23_redis_type_list_try.rb

@@ -31,11 +31,11 @@ ret.class
 #=> ['value1','value2','value3']
 
 ## Familia::List#delete
-@a.owners.delete 'value3'
+@a.owners.remove 'value3'
 #=> 1
 
 ## Familia::List#size
 @a.owners.size
 #=> 2
 
-@a.owners.clear
+@a.owners.delete!

data/try/24_redis_type_string_try.rb

@@ -22,8 +22,8 @@ require_relative './test_helpers'
 #=> 'DECENT!'
 
 ## Familia::String#destroy!
-@a.value.clear
-#=> 1
+@a.value.delete!
+#=> true
 
 ## Familia::String.new
 @ret = Familia::String.new 'arbitrary:key'
@@ -63,4 +63,4 @@ require_relative './test_helpers'
 #=> '1050bytes'
 
 
-@ret.clear
+@ret.delete!

data/try/25_redis_type_hash_try.rb

@@ -50,4 +50,4 @@ require_relative './test_helpers'
 #=> ['1', '40', '3']
 
 
-@a.props.clear
+@a.props.delete!

data/try/26_redis_bool_try.rb

@@ -39,5 +39,5 @@ end
 #=> "true"
 
 ## Clear the hash key
-@hashkey.clear
-#=> 1
+@hashkey.delete!
+#=> true

data/try/27_redis_horreum_try.rb

@@ -36,8 +36,8 @@ Familia.debug = false
 #=> @identifier
 
 ## Remove the key
-@hashkey.clear
-#=> 1
+@hashkey.delete!
+#=> true
 
 ## Horreum objects can update and save their fields (1 of 2)
 @customer.name = 'John Doe'

data/try/28_redis_horreum_serialization_try.rb

@@ -0,0 +1,159 @@
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+Familia.debug = false
+
+@identifier = 'tryouts-28@onetimesecret.com'
+@customer = Customer.new @identifier
+
+## Basic save functionality works
+@customer.name = 'John Doe'
+@customer.save
+#=> true
+
+## to_h returns field hash with all Customer fields
+@customer.to_h.class
+#=> Hash
+
+## to_h includes the fields we set (using symbol keys)
+@customer.to_h[:name]
+#=> "John Doe"
+
+## to_h includes the key field (using symbol keys)
+@customer.to_h[:key]
+#=> "tryouts-28@onetimesecret.com"
+
+## to_a returns field array in definition order
+@customer.to_a.class
+#=> Array
+
+## to_a includes values in field order (name should be at index 5)
+@customer.to_a[5]
+#=> "John Doe"
+
+## batch_update can update multiple fields atomically, to_h
+@result = @customer.batch_update(name: 'Jane Smith', email: 'jane@example.com')
+@result.to_h
+#=> {:success=>true, :results=>[0, 0]}
+
+## batch_update returns successful result, successful?
+@result.successful?
+#=> true
+
+## batch_update returns successful result, tuple
+@result.tuple
+#=> [true, [0, 0]]
+
+## batch_update returns successful result, to_a
+@result.to_a
+#=> [true, [0, 0]]
+
+## batch_update updates object fields in memory, confirm fields changed
+[@customer.name, @customer.email]
+#=> ["Jane Smith", "jane@example.com"]
+
+## batch_update persists to Redis
+@customer.refresh!
+[@customer.name, @customer.email]
+#=> ["Jane Smith", "jane@example.com"]
+
+## batch_update with update_expiration: false works
+@customer.batch_update(name: 'Bob Jones', update_expiration: false)
+@customer.refresh!
+@customer.name
+#=> "Bob Jones"
+
+## apply_fields updates object in memory only (1 of 2)
+@customer.apply_fields(name: 'Memory Only', email: 'memory@test.com')
+[@customer.name, @customer.email]
+#=> ["Memory Only", "memory@test.com"]
+
+## apply_fields doesn't persist to Redis (2 of 2)
+@customer.refresh!
+[@customer.name, @customer.email]
+#=> ["Bob Jones", "jane@example.com"]
+
+## serialize_value handles strings
+@customer.serialize_value("test string")
+#=> "test string"
+
+## serialize_value handles numbers
+@customer.serialize_value(42)
+#=> "42"
+
+## serialize_value handles hashes as JSON
+@customer.serialize_value({key: 'value', num: 123})
+#=> "{\"key\":\"value\",\"num\":123}"
+
+## serialize_value handles arrays as JSON
+@customer.serialize_value([1, 2, 'three'])
+#=> "[1,2,\"three\"]"
+
+## deserialize_value handles JSON strings back to objects
+@customer.deserialize_value('{"key":"value","num":123}')
+#=> {:key=>"value", :num=>123}
+
+## deserialize_value handles JSON arrays
+@customer.deserialize_value('[1,2,"three"]')
+#=> [1, 2, "three"]
+
+## deserialize_value handles plain strings
+@customer.deserialize_value('plain string')
+#=> "plain string"
+
+## transaction method works with block
+result = @customer.transaction do |conn|
+  conn.hset @customer.rediskey, 'temp_field', 'temp_value'
+  conn.hset @customer.rediskey, 'another_field', 'another_value'
+end
+result.size
+#=> 2
+
+## refresh! reloads from Redis
+@customer.refresh!
+@customer.hget('temp_field')
+#=> "temp_value"
+
+## Empty batch_update still works
+result = @customer.batch_update()
+result.successful?
+#=> true
+
+## destroy! removes object from Redis (1 of 2)
+@customer.destroy!
+#=> true
+
+## After destroy!, Redis key no longer exists (2 of 2)
+@customer.exists?
+#=> false
+
+## destroy! removes object from Redis, not the in-memory object (2 of 2)
+@customer.refresh!
+@customer.name
+#=> "Bob Jones"
+
+## clear_fields! removes the in-memory object fields
+@customer.clear_fields!
+@customer.name
+#=> nil
+
+## Fresh customer for testing new field creation
+@fresh_customer = Customer.new 'fresh-customer@test.com'
+@fresh_customer.class
+#=> Customer
+
+## batch_update with new fields returns [1, 1] for new field creation
+@fresh_customer.remove_field('role')
+@fresh_customer.remove_field('planid')
+@fresh_result = @fresh_customer.batch_update(role: 'admin', planid: 'premium')
+@fresh_result.to_h
+#=> {:success=>true, :results=>[1, 1]}
+
+## Fresh customer fields are set correctly
+[@fresh_customer.role, @fresh_customer.planid]
+#=> ["admin", "premium"]
+
+## Fresh customer changes persist to Redis
+@fresh_customer.refresh!
+[@fresh_customer.role, @fresh_customer.planid]
+#=> ["admin", "premium"]