redis 4.8.1 → 6.0.0

data/lib/redis/commands/lists.rb

@@ -30,6 +30,84 @@ class Redis
         send_command([:lmove, source, destination, where_source, where_destination])
       end
 
+      # Remove multiple elements from the head/tail of a list, append/prepend
+      # them to another list and return them.
+      #
+      # @example Move a single element (still an array reply)
+      #   redis.lmovem("foo", "bar", "LEFT", "LEFT")
+      #     # => ["s1"]
+      # @example Move up to 3 elements, pushed one-by-one (block order reversed)
+      #   redis.lmovem("foo", "bar", "LEFT", "LEFT", count: 3, order: "OBO")
+      #     # => ["s3", "s2", "s1"]
+      # @example Move exactly 2 elements, preserving their relative order
+      #   redis.lmovem("foo", "bar", "LEFT", "RIGHT", exactly: 2, order: "BULK")
+      #     # => ["s1", "s2"]
+      #
+      # @param [String] source source key
+      # @param [String] destination destination key
+      # @param [String, Symbol] where_source from where to remove elements from the source list
+      #     e.g. 'LEFT' - from head, 'RIGHT' - from tail
+      # @param [String, Symbol] where_destination where to push elements to the destination list
+      #     e.g. 'LEFT' - to head, 'RIGHT' - to tail
+      # @param [Integer] count move up to `count` elements, fewer when the source holds fewer
+      # @param [Integer] exactly move exactly `exactly` elements; when the source holds fewer,
+      #     nothing is moved
+      # @param [String, Symbol] order ordering at the destination, required together with
+      #     `count` or `exactly`:
+      #  - when `'OBO'` - push each element as popped, so the moved block order is reversed
+      #  - when `'BULK'` - preserve the original relative order of the moved elements
+      #
+      # @return [nil, Array<String>] the moved elements in destination order, or nil when
+      #     nothing was moved
+      def lmovem(source, destination, where_source, where_destination, count: nil, exactly: nil, order: nil)
+        where_source, where_destination = _normalize_move_wheres(where_source, where_destination)
+
+        args = [:lmovem, source, destination, where_source, where_destination]
+        args.concat(_movem_amount_args(count, exactly, order))
+
+        send_command(args)
+      end
+
+      # Remove multiple elements from the head/tail of a list, append/prepend
+      # them to another list and return them; or block until the request can
+      # be satisfied or the timeout expires.
+      #
+      # @example Move up to 3 elements as soon as any are available
+      #   redis.blmovem("foo", "bar", "LEFT", "LEFT", timeout: 1, count: 3, order: "BULK")
+      #     # => ["s1", "s2", "s3"]
+      # @example Block until the source holds at least 2 elements
+      #   redis.blmovem("foo", "bar", "LEFT", "RIGHT", timeout: 1, exactly: 2, order: "OBO")
+      #     # => nil on timeout
+      #
+      # @param [String] source source key
+      # @param [String] destination destination key
+      # @param [String, Symbol] where_source from where to remove elements from the source list
+      #     e.g. 'LEFT' - from head, 'RIGHT' - from tail
+      # @param [String, Symbol] where_destination where to push elements to the destination list
+      #     e.g. 'LEFT' - to head, 'RIGHT' - to tail
+      # @param [Float, Integer] timeout seconds to block, 0 blocks indefinitely
+      # @param [Integer] count move up to `count` elements as soon as at least one is available
+      # @param [Integer] exactly move exactly `exactly` elements, blocking until the source
+      #     holds that many
+      # @param [String, Symbol] order ordering at the destination, required together with
+      #     `count` or `exactly`:
+      #  - when `'OBO'` - push each element as popped, so the moved block order is reversed
+      #  - when `'BULK'` - preserve the original relative order of the moved elements
+      #
+      # @return [nil, Array<String>] the moved elements in destination order, or nil when the
+      #     timeout expired and nothing was moved
+      #
+      # @see #lmovem
+      def blmovem(source, destination, where_source, where_destination, timeout: 0, count: nil, exactly: nil,
+                  order: nil)
+        where_source, where_destination = _normalize_move_wheres(where_source, where_destination)
+
+        command = [:blmovem, source, destination, where_source, where_destination, timeout]
+        command.concat(_movem_amount_args(count, exactly, order))
+
+        send_blocking_command(command, timeout)
+      end
+
       # Remove the first/last element in a list and append/prepend it
       # to another list and return it, or block until one is available.
       #
@@ -48,7 +126,7 @@ class Redis
       # @param [String, Symbol] where_destination where to push the element to the source list
       #     e.g. 'LEFT' - to head, 'RIGHT' - to tail
       # @param [Hash] options
-      #   - `:timeout => Numeric`: timeout in seconds, defaults to no timeout
+      #   - `:timeout => [Float, Integer]`: timeout in seconds, defaults to no timeout
       #
       # @return [nil, String] the element, or nil when the source key does not exist or the timeout expired
       #
@@ -99,10 +177,10 @@ class Redis
       #
       # @param [String] key
       # @param [Integer] count number of elements to remove
-      # @return [String, Array<String>] the values of the first elements
+      # @return [nil, String, Array<String>] the values of the first elements
       def lpop(key, count = nil)
         command = [:lpop, key]
-        command << count if count
+        command << Integer(count) if count
         send_command(command)
       end
 
@@ -110,10 +188,10 @@ class Redis
       #
       # @param [String] key
       # @param [Integer] count number of elements to remove
-      # @return [String, Array<String>] the values of the last elements
+      # @return [nil, String, Array<String>] the values of the last elements
       def rpop(key, count = nil)
         command = [:rpop, key]
-        command << count if count
+        command << Integer(count) if count
         send_command(command)
       end
 
@@ -142,7 +220,7 @@ class Redis
       # @param [String, Array<String>] keys one or more keys to perform the
       #   blocking pop on
       # @param [Hash] options
-      #   - `:timeout => Integer`: timeout in seconds, defaults to no timeout
+      #   - `:timeout => [Float, Integer]`: timeout in seconds, defaults to no timeout
       #
       # @return [nil, [String, String]]
       #   - `nil` when the operation timed out
@@ -156,7 +234,7 @@ class Redis
       # @param [String, Array<String>] keys one or more keys to perform the
       #   blocking pop on
       # @param [Hash] options
-      #   - `:timeout => Integer`: timeout in seconds, defaults to no timeout
+      #   - `:timeout => [Float, Integer]`: timeout in seconds, defaults to no timeout
       #
       # @return [nil, [String, String]]
       #   - `nil` when the operation timed out
@@ -173,23 +251,77 @@ class Redis
       # @param [String] source source key
       # @param [String] destination destination key
       # @param [Hash] options
-      #   - `:timeout => Integer`: timeout in seconds, defaults to no timeout
+      #   - `:timeout => [Float, Integer]`: timeout in seconds, defaults to no timeout
       #
       # @return [nil, String]
       #   - `nil` when the operation timed out
       #   - the element was popped and pushed otherwise
-      def brpoplpush(source, destination, deprecated_timeout = 0, timeout: deprecated_timeout)
+      def brpoplpush(source, destination, timeout: 0)
         command = [:brpoplpush, source, destination, timeout]
         send_blocking_command(command, timeout)
       end
 
+      # Pops one or more elements from the first non-empty list key from the list
+      # of provided key names. If lists are empty, blocks until timeout has passed.
+      #
+      # @example Popping a element
+      #   redis.blmpop(1.0, 'list')
+      #   #=> ['list', ['a']]
+      # @example With count option
+      #   redis.blmpop(1.0, 'list', count: 2)
+      #   #=> ['list', ['a', 'b']]
+      #
+      # @params timeout [Float] a float value specifying the maximum number of seconds to block) elapses.
+      #   A timeout of zero can be used to block indefinitely.
+      # @params key [String, Array<String>] one or more keys with lists
+      # @params modifier [String]
+      #  - when `"LEFT"` - the elements popped are those from the left of the list
+      #  - when `"RIGHT"` - the elements popped are those from the right of the list
+      # @params count [Integer] a number of elements to pop
+      #
+      # @return [Array<String, Array<String, Float>>] list of popped elements or nil
+      def blmpop(timeout, *keys, modifier: "LEFT", count: nil)
+        raise ArgumentError, "Pick either LEFT or RIGHT" unless modifier == "LEFT" || modifier == "RIGHT"
+
+        args = [:blmpop, timeout, keys.size, *keys, modifier]
+        args << "COUNT" << Integer(count) if count
+
+        send_blocking_command(args, timeout)
+      end
+
+      # Pops one or more elements from the first non-empty list key from the list
+      # of provided key names.
+      #
+      # @example Popping a element
+      #   redis.lmpop('list')
+      #   #=> ['list', ['a']]
+      # @example With count option
+      #   redis.lmpop('list', count: 2)
+      #   #=> ['list', ['a', 'b']]
+      #
+      # @params key [String, Array<String>] one or more keys with lists
+      # @params modifier [String]
+      #  - when `"LEFT"` - the elements popped are those from the left of the list
+      #  - when `"RIGHT"` - the elements popped are those from the right of the list
+      # @params count [Integer] a number of elements to pop
+      #
+      # @return [Array<String, Array<String, Float>>] list of popped elements or nil
+      def lmpop(*keys, modifier: "LEFT", count: nil)
+        raise ArgumentError, "Pick either LEFT or RIGHT" unless modifier == "LEFT" || modifier == "RIGHT"
+
+        args = [:lmpop, keys.size, *keys, modifier]
+        args << "COUNT" << Integer(count) if count
+
+        send_command(args)
+      end
+
       # Get an element from a list by its index.
       #
       # @param [String] key
       # @param [Integer] index
       # @return [String]
       def lindex(key, index)
-        send_command([:lindex, key, index])
+        send_command([:lindex, key, Integer(index)])
       end
 
       # Insert an element before or after another element in a list.
@@ -211,7 +343,7 @@ class Redis
       # @param [Integer] stop stop index
       # @return [Array<String>]
       def lrange(key, start, stop)
-        send_command([:lrange, key, start, stop])
+        send_command([:lrange, key, Integer(start), Integer(stop)])
       end
 
       # Remove elements from a list.
@@ -224,7 +356,7 @@ class Redis
       # @param [String] value
       # @return [Integer] the number of removed elements
       def lrem(key, count, value)
-        send_command([:lrem, key, count, value])
+        send_command([:lrem, key, Integer(count), value])
       end
 
       # Set the value of an element in a list by its index.
@@ -234,7 +366,7 @@ class Redis
       # @param [String] value
       # @return [String] `OK`
       def lset(key, index, value)
-        send_command([:lset, key, index, value])
+        send_command([:lset, key, Integer(index), value])
       end
 
       # Trim a list to the specified range.
@@ -244,7 +376,7 @@ class Redis
       # @param [Integer] stop stop index
       # @return [String] `OK`
       def ltrim(key, start, stop)
-        send_command([:ltrim, key, start, stop])
+        send_command([:ltrim, key, Integer(start), Integer(stop)])
       end
 
       private
@@ -253,24 +385,34 @@ class Redis
         timeout = if args.last.is_a?(Hash)
           options = args.pop
           options[:timeout]
-        elsif args.last.respond_to?(:to_int)
-          last_arg = args.pop
-          ::Redis.deprecate!(
-            "Passing the timeout as a positional argument is deprecated, it should be passed as a keyword argument:\n" \
-            "  redis.#{cmd}(#{args.map(&:inspect).join(', ')}, timeout: #{last_arg.to_int})" \
-            "(called from: #{caller(2, 1).first})"
-          )
-          last_arg.to_int
         end
 
         timeout ||= 0
+        unless timeout.is_a?(Integer) || timeout.is_a?(Float)
+          raise ArgumentError, "timeout must be an Integer or Float, got: #{timeout.class}"
+        end
 
-        keys = args.flatten
-
-        command = [cmd, keys, timeout]
+        args.flatten!(1)
+        command = [cmd].concat(args)
+        command << timeout
         send_blocking_command(command, timeout, &blk)
       end
 
+      def _movem_amount_args(count, exactly, order)
+        raise ArgumentError, "Pick either count or exactly, not both" if count && exactly
+
+        if count || exactly
+          order = order.to_s.upcase
+          raise ArgumentError, "order must be 'OBO' or 'BULK'" if order != "OBO" && order != "BULK"
+
+          [count ? "COUNT" : "EXACTLY", Integer(count || exactly), order]
+        elsif order
+          raise ArgumentError, "order requires count or exactly"
+        else
+          []
+        end
+      end
+
       def _normalize_move_wheres(where_source, where_destination)
         where_source      = where_source.to_s.upcase
         where_destination = where_destination.to_s.upcase