protocol-redis 0.2.0 → 0.3.0

data/lib/protocol/redis/methods/geospatial.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# 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:
+# 
+# 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.
+
+module Protocol
+	module Redis
+		module Methods
+			module Geospatial
+				# Add one or more geospatial items in the geospatial index represented using a sorted set. O(log(N)) for each item added, where N is the number of elements in the sorted set.
+				# @see https://redis.io/commands/geoadd
+				# @param key [Key]
+				def geoadd(key, longitude, latitude, member, *arguments)
+					call("GEOADD", longitude, latitude, member, *arguments)
+				end
+				
+				# Returns members of a geospatial index as standard geohash strings. O(log(N)) for each member requested, where N is the number of elements in the sorted set.
+				# @see https://redis.io/commands/geohash
+				# @param key [Key]
+				# @param member [String]
+				def geohash(key, member, *members)
+					call("GEOHASH", key, member, *members)
+				end
+				
+				# Returns longitude and latitude of members of a geospatial index. O(log(N)) for each member requested, where N is the number of elements in the sorted set.
+				# @see https://redis.io/commands/geopos
+				# @param key [Key]
+				# @param member [String]
+				def geopos(key, member, *members)
+					call("GEOPOS", key, member, *members)
+				end
+				
+				# Returns the distance between two members of a geospatial index. O(log(N)).
+				# @see https://redis.io/commands/geodist
+				# @param key [Key]
+				# @param member1 [String]
+				# @param member2 [String]
+				# @param unit [Enum] Distance scale to use, one of "m" (meters), "km" (kilometers), "mi" (miles) or "ft" (feet).
+				def geodist(key, from, to, unit = "m")
+					call("GEODIST", key, from, to, unit)
+				end
+				
+				# Query a sorted set representing a geospatial index to fetch members matching a given maximum distance from a point. O(N+log(M)) where N is the number of elements inside the bounding box of the circular area delimited by center and radius and M is the number of items inside the index.
+				# @see https://redis.io/commands/georadius
+				# @param key [Key]
+				# @param longitude [Double]
+				# @param latitude [Double]
+				# @param radius [Double]
+				# @param unit [Enum]
+				# @param withcoord [Enum]
+				# @param withdist [Enum]
+				# @param withhash [Enum]
+				def georadius(key, longitude, latitude, radius, unit = "m", withcoord: false, withdist: false, withhash: false, count: nil, store: nil, storedist: nil)
+					arguments = [key, longitude, latitude, radius, unit]
+					
+					if withcoord
+						arguments.append("WITHCOORD")
+					end
+					
+					if withdist
+						arguments.append("WITHDIST")
+					end
+					
+					if withhash
+						arguments.append("WITHHASH")
+					end
+					
+					if count
+						arguments.append("COUNT", count)
+					end
+					
+					if store
+						arguments.append("STORE", store)
+					end
+					
+					if storedist
+						arguments.append("STOREDIST", storedist)
+					end
+					
+					call("GEORADIUS", *arguments)
+				end
+				
+				# Query a sorted set representing a geospatial index to fetch members matching a given maximum distance from a member. O(N+log(M)) where N is the number of elements inside the bounding box of the circular area delimited by center and radius and M is the number of items inside the index.
+				# @see https://redis.io/commands/georadiusbymember
+				# @param key [Key]
+				# @param member [String]
+				# @param radius [Double]
+				# @param unit [Enum]
+				# @param withcoord [Enum]
+				# @param withdist [Enum]
+				# @param withhash [Enum]
+				# @param order [Enum]
+				def georadiusbymember(key, member, radius, unit = "m", withcoord: false, withdist: false, withhash: false, count: nil, store: nil, storedist: nil)
+					arguments = [key, member, radius, unit]
+					
+					if withcoord
+						arguments.append("WITHCOORD")
+					end
+					
+					if withdist
+						arguments.append("WITHDIST")
+					end
+					
+					if withhash
+						arguments.append("WITHHASH")
+					end
+					
+					if count
+						arguments.append("COUNT", count)
+					end
+					
+					if store
+						arguments.append("STORE", store)
+					end
+					
+					if storedist
+						arguments.append("STOREDIST", storedist)
+					end
+					
+					call("GEORADIUS", *arguments)
+				end
+			end
+		end
+	end
+end

data/lib/protocol/redis/methods/hashes.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright, 2019, by Mikael Henriksson. <http://www.mhenrixon.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -22,54 +24,103 @@ module Protocol
 	module Redis
 		module Methods
 			module Hashes
+				# Get the number of fields in a hash. O(1).
+				# @see https://redis.io/commands/hlen
+				# @param key [Key]
 				def hlen(key)
 					return call('HLEN', key)
 				end
 				
+				# Set the string value of a hash field. O(1) for each field/value pair added, so O(N) to add N field/value pairs when the command is called with multiple field/value pairs.
+				# @see https://redis.io/commands/hset
+				# @param key [Key]
 				def hset(key, field, value)
 					return call('HSET', key, field, value)
 				end
 				
+				# Set the value of a hash field, only if the field does not exist. O(1).
+				# @see https://redis.io/commands/hsetnx
+				# @param key [Key]
+				# @param field [String]
+				# @param value [String]
 				def hsetnx(key, field, value)
 					return call('HSETNX', key, field, value)
 				end
 				
+				# Set multiple hash fields to multiple values. O(N) where N is the number of fields being set.
+				# @see https://redis.io/commands/hmset
+				# @param key [Key]
 				def hmset(key, *attrs)
 					return call('HMSET', key, *attrs)
 				end
 				
+				# Get the value of a hash field. O(1).
+				# @see https://redis.io/commands/hget
+				# @param key [Key]
+				# @param field [String]
 				def hget(key, field)
 					return call('HGET', key, field)
 				end
 				
+				# Get the values of all the given hash fields. O(N) where N is the number of fields being requested.
+				# @see https://redis.io/commands/hmget
+				# @param key [Key]
+				# @param field [String]
 				def hmget(key, *fields, &blk)
 					return call('HMGET', key, *fields, &blk)
 				end
 				
+				# Delete one or more hash fields. O(N) where N is the number of fields to be removed.
+				# @see https://redis.io/commands/hdel
+				# @param key [Key]
+				# @param field [String]
 				def hdel(key, *fields)
 					return call('HDEL', key, *fields)
 				end
 				
+				# Determine if a hash field exists. O(1).
+				# @see https://redis.io/commands/hexists
+				# @param key [Key]
+				# @param field [String]
 				def hexists(key, field)
 					return call('HEXISTS', key, field)
 				end
 				
+				# Increment the integer value of a hash field by the given number. O(1).
+				# @see https://redis.io/commands/hincrby
+				# @param key [Key]
+				# @param field [String]
+				# @param increment [Integer]
 				def hincrby(key, field, increment)
 					return call('HINCRBY', key, field, increment)
 				end
 				
+				# Increment the float value of a hash field by the given amount. O(1).
+				# @see https://redis.io/commands/hincrbyfloat
+				# @param key [Key]
+				# @param field [String]
+				# @param increment [Double]
 				def hincrbyfloat(key, field, increment)
 					return call('HINCRBYFLOAT', key, field, increment)
 				end
 				
+				# Get all the fields in a hash. O(N) where N is the size of the hash.
+				# @see https://redis.io/commands/hkeys
+				# @param key [Key]
 				def hkeys(key)
 					return call('HKEYS', key)
 				end
 				
+				# Get all the values in a hash. O(N) where N is the size of the hash.
+				# @see https://redis.io/commands/hvals
+				# @param key [Key]
 				def hvals(key)
 					return call('HVALS', key)
 				end
 				
+				# Get all the fields and values in a hash. O(N) where N is the size of the hash.
+				# @see https://redis.io/commands/hgetall
+				# @param key [Key]
 				def hgetall(key)
 					return call('HGETALL', key)
 				end

data/lib/protocol/redis/methods/lists.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # Copyright, 2018, by Huba Nagy.
 # 
@@ -23,22 +25,45 @@ module Protocol
 	module Redis
 		module Methods
 			module Lists
+				# Remove and get the first element in a list, or block until one is available. O(1).
+				# @see https://redis.io/commands/blpop
+				# @param key [Key]
+				# @param timeout [Integer]
 				def blpop(*keys, timeout: 0)
 					return call('BLPOP', *keys, timeout)
 				end
 				
+				# Remove and get the last element in a list, or block until one is available. O(1).
+				# @see https://redis.io/commands/brpop
+				# @param key [Key]
+				# @param timeout [Integer]
 				def brpop(*keys, timeout: 0)
 					return call('BRPOP', *keys, timeout)
 				end
 				
+				# Pop an element from a list, push it to another list and return it; or block until one is available. O(1).
+				# @see https://redis.io/commands/brpoplpush
+				# @param source [Key]
+				# @param destination [Key]
+				# @param timeout [Integer]
 				def brpoplpush(source, destination, timeout)
 					return call('BRPOPLPUSH', source, destination, timeout)
 				end
 				
+				# Get an element from a list by its index. O(N) where N is the number of elements to traverse to get to the element at index. This makes asking for the first or the last element of the list O(1).
+				# @see https://redis.io/commands/lindex
+				# @param key [Key]
+				# @param index [Integer]
 				def lindex(key, index)
 					return call('LINDEX', key, index)
 				end
 				
+				# Insert an element before or after another element in a list. O(N) where N is the number of elements to traverse before seeing the value pivot. This means that inserting somewhere on the left end on the list (head) can be considered O(1) and inserting somewhere on the right end (tail) is O(N).
+				# @see https://redis.io/commands/linsert
+				# @param key [Key]
+				# @param where [Enum]
+				# @param pivot [String]
+				# @param element [String]
 				def linsert(key, position=:before, index, value)
 					if position == :before
 						offset = 'BEFORE'
@@ -49,14 +74,24 @@ module Protocol
 					return call('LINSERT', key, offset, index, value)
 				end
 				
+				# Get the length of a list. O(1).
+				# @see https://redis.io/commands/llen
+				# @param key [Key]
 				def llen(key)
 					return call('LLEN', key)
 				end
 				
+				# Remove and get the first element in a list. O(1).
+				# @see https://redis.io/commands/lpop
+				# @param key [Key]
 				def lpop(key)
 					return call('LPOP', key)
 				end
 				
+				# Prepend one or multiple elements to a list. O(1) for each element added, so O(N) to add N elements when the command is called with multiple arguments.
+				# @see https://redis.io/commands/lpush
+				# @param key [Key]
+				# @param element [String]
 				def lpush(key, value, *values)
 					case value
 					when Array
@@ -68,36 +103,71 @@ module Protocol
 					return call('LPUSH', key, *values)
 				end
 				
+				# Prepend an element to a list, only if the list exists. O(1) for each element added, so O(N) to add N elements when the command is called with multiple arguments.
+				# @see https://redis.io/commands/lpushx
+				# @param key [Key]
+				# @param element [String]
 				def lpushx(key, value)
 					return call('LPUSHX', key, value)
 				end
 				
+				# Get a range of elements from a list. O(S+N) where S is the distance of start offset from HEAD for small lists, from nearest end (HEAD or TAIL) for large lists; and N is the number of elements in the specified range.
+				# @see https://redis.io/commands/lrange
+				# @param key [Key]
+				# @param start [Integer]
+				# @param stop [Integer]
 				def lrange(key, start, stop)
 					return call('LRANGE', key, start, stop)
 				end
 				
+				# Remove elements from a list. O(N+M) where N is the length of the list and M is the number of elements removed.
+				# @see https://redis.io/commands/lrem
+				# @param key [Key]
+				# @param count [Integer]
+				# @param element [String]
 				def lrem(key, count, value)
 					return call('LREM', key, count)
 				end
 				
+				# Set the value of an element in a list by its index. O(N) where N is the length of the list. Setting either the first or the last element of the list is O(1).
+				# @see https://redis.io/commands/lset
+				# @param key [Key]
+				# @param index [Integer]
+				# @param element [String]
 				def lset(key, index, values)
 					return call('LSET', key, index, values)
 				end
 				
+				# Trim a list to the specified range. O(N) where N is the number of elements to be removed by the operation.
+				# @see https://redis.io/commands/ltrim
+				# @param key [Key]
+				# @param start [Integer]
+				# @param stop [Integer]
 				def ltrim(key, start, stop)
 					return call('LTRIM', key, start, stop)
 				end
 				
+				# Remove and get the last element in a list. O(1).
+				# @see https://redis.io/commands/rpop
+				# @param key [Key]
 				def rpop(key)
 					return call('RPOP', key)
 				end
 				
+				# Remove the last element in a list, prepend it to another list and return it. O(1).
+				# @see https://redis.io/commands/rpoplpush
+				# @param source [Key]
+				# @param destination [Key]
 				def rpoplpush(source, destination=nil)
 					destination = source if destination.nil?
 					
 					return call('RPOPLPUSH', source, destination)
 				end
 				
+				# Append one or multiple elements to a list. O(1) for each element added, so O(N) to add N elements when the command is called with multiple arguments.
+				# @see https://redis.io/commands/rpush
+				# @param key [Key]
+				# @param element [String]
 				def rpush(key, value, *values)
 					case value
 					when Array
@@ -109,6 +179,10 @@ module Protocol
 					return call('RPUSH', key, *values)
 				end
 				
+				# Append an element to a list, only if the list exists. O(1) for each element added, so O(N) to add N elements when the command is called with multiple arguments.
+				# @see https://redis.io/commands/rpushx
+				# @param key [Key]
+				# @param element [String]
 				def rpushx(key, value)
 					return call('RPUSHX', key, value)
 				end

data/lib/protocol/redis/methods/server.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # Copyright, 2018, by Huba Nagy.
 # 
@@ -23,8 +25,9 @@ module Protocol
 	module Redis
 		module Methods
 			module Server
-				# Get info from server.
-				# @return [Hash] the server metadata.
+				# Get information and statistics about the server.
+				# @see https://redis.io/commands/info
+				# @param section [String]
 				def info
 					metadata = {}
 					
@@ -39,8 +42,11 @@ module Protocol
 					return metadata
 				end
 				
+				# Remove all keys from the current database.
+				# @see https://redis.io/commands/flushdb
+				# @param async [Enum]
 				def flushdb!
-					call 'FLUSHDB'
+					return call('FLUSHDB')
 				end
 			end
 		end

data/lib/protocol/redis/methods/strings.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # Copyright, 2018, by Huba Nagy.
 # 
@@ -23,68 +25,127 @@ module Protocol
 	module Redis
 		module Methods
 			module Strings
+				# Append a value to a key. O(1). The amortized time complexity is O(1) assuming the appended value is small and the already present value is of any size, since the dynamic string library used by Redis will double the free space available on every reallocation.
+				# @see https://redis.io/commands/append
+				# @param key [Key]
+				# @param value [String]
 				def append(key, value)
 					return call('APPEND', key, value)
 				end
 
+				# Count set bits in a string. O(N).
+				# @see https://redis.io/commands/bitcount
+				# @param key [Key]
 				def bitcount(key, *range)
 					return call('BITCOUNT', key, *range)
 				end
 
+				# Decrement the integer value of a key by one. O(1).
+				# @see https://redis.io/commands/decr
+				# @param key [Key]
 				def decr(key)
 					return call('DECR', key)
 				end
 
+				# Decrement the integer value of a key by the given number. O(1).
+				# @see https://redis.io/commands/decrby
+				# @param key [Key]
+				# @param decrement [Integer]
 				def decrby(key, decrement)
 					return call('DECRBY', key, decrement)
 				end
 
+				# Get the value of a key. O(1).
+				# @see https://redis.io/commands/get
+				# @param key [Key]
 				def get(key)
 					return call('GET', key)
 				end
 
+				# Returns the bit value at offset in the string value stored at key. O(1).
+				# @see https://redis.io/commands/getbit
+				# @param key [Key]
+				# @param offset [Integer]
 				def getbit(key, offset)
 					return call('GETBIT', key, offset)
 				end
 
+				# Get a substring of the string stored at a key. O(N) where N is the length of the returned string. The complexity is ultimately determined by the returned length, but because creating a substring from an existing string is very cheap, it can be considered O(1) for small strings.
+				# @see https://redis.io/commands/getrange
+				# @param key [Key]
+				# @param start [Integer]
+				# @param end [Integer]
 				def getrange(key, start_index, end_index)
 					return call('GETRANGE', key, start_index, end_index)
 				end
 
+				# Set the string value of a key and return its old value. O(1).
+				# @see https://redis.io/commands/getset
+				# @param key [Key]
+				# @param value [String]
 				def getset(key, value)
 					return call('GETSET', key, value)
 				end
 
+				# Increment the integer value of a key by one. O(1).
+				# @see https://redis.io/commands/incr
+				# @param key [Key]
 				def incr(key)
 					return call('INCR', key)
 				end
 
+				# Increment the integer value of a key by the given amount. O(1).
+				# @see https://redis.io/commands/incrby
+				# @param key [Key]
+				# @param increment [Integer]
 				def incrby(key, increment)
 					return call('INCRBY', key, increment)
 				end
 
+				# Increment the float value of a key by the given amount. O(1).
+				# @see https://redis.io/commands/incrbyfloat
+				# @param key [Key]
+				# @param increment [Double]
 				def incrbyfloat(key, increment)
 					return call('INCRBYFLOAT', key, increment)
 				end
 
+				# Get the values of all the given keys. O(N) where N is the number of keys to retrieve.
+				# @see https://redis.io/commands/mget
+				# @param key [Key]
 				def mget(key, *keys)
 					return call('MGET', key, *keys)
 				end
 
+				# Set multiple keys to multiple values. O(N) where N is the number of keys to set.
+				# @see https://redis.io/commands/mset
 				def mset(pairs)
 					flattened_pairs = pairs.keys.zip(pairs.values).flatten
 					return call('MSET', *flattened_pairs)
 				end
 
+				# Set multiple keys to multiple values, only if none of the keys exist. O(N) where N is the number of keys to set.
+				# @see https://redis.io/commands/msetnx
 				def msetnx(pairs)
 					flattened_pairs = pairs.keys.zip(pairs.values).flatten
 					return call('MSETNX', *flattened_pairs)
 				end
 
+				# Set the value and expiration in milliseconds of a key. O(1).
+				# @see https://redis.io/commands/psetex
+				# @param key [Key]
+				# @param milliseconds [Integer]
+				# @param value [String]
 				def psetex(key, milliseconds, value)
 					return set key, value, milliseconds: milliseconds
 				end
 
+				# Set the string value of a key. O(1).
+				# @see https://redis.io/commands/set
+				# @param key [Key]
+				# @param value [String]
+				# @param expiration [Enum]
+				# @param condition [Enum]
 				def set(key, value, **options)
 					arguments = []
 
@@ -107,22 +168,44 @@ module Protocol
 					return call('SET', key, value, *arguments)
 				end
 
+				# Sets or clears the bit at offset in the string value stored at key. O(1).
+				# @see https://redis.io/commands/setbit
+				# @param key [Key]
+				# @param offset [Integer]
+				# @param value [Integer]
 				def setbit(key, offset, value)
 					return call('SETBIT', key, offset, value)
 				end
 
+				# Set the value and expiration of a key. O(1).
+				# @see https://redis.io/commands/setex
+				# @param key [Key]
+				# @param seconds [Integer]
+				# @param value [String]
 				def setex(key, seconds, value)
 					return set key, value, seconds: seconds
 				end
 
+				# Set the value of a key, only if the key does not exist. O(1).
+				# @see https://redis.io/commands/setnx
+				# @param key [Key]
+				# @param value [String]
 				def setnx(key, value)
 					return set key, value, condition: :nx
 				end
 
+				# Overwrite part of a string at key starting at the specified offset. O(1), not counting the time taken to copy the new string in place. Usually, this string is very small so the amortized complexity is O(1). Otherwise, complexity is O(M) with M being the length of the value argument.
+				# @see https://redis.io/commands/setrange
+				# @param key [Key]
+				# @param offset [Integer]
+				# @param value [String]
 				def setrange(key, offset, value)
 					return call('SETRANGE', key, offset, value)
 				end
 
+				# Get the length of the value stored in a key. O(1).
+				# @see https://redis.io/commands/strlen
+				# @param key [Key]
 				def strlen(key)
 					return call('STRLEN', key)
 				end