redis 5.4.1 → 6.0.0

data/lib/redis/commands/hashes.rb

@@ -220,13 +220,20 @@ class Redis
       # @param [Hash] options
       #   - `:match => String`: only return keys matching the pattern
       #   - `:count => Integer`: return count keys at most per iteration
+      #   - `:novalues => Boolean`: whether or not to include values in the output (default: false)
       #
-      # @return [String, Array<[String, String]>] the next cursor and all found keys
+      # @return [String, Array<[String, String]>, Array<String>] the next cursor and all found keys
+      #   - when `:novalues` is false: [cursor, [[field1, value1], [field2, value2], ...]]
+      #   - when `:novalues` is true: [cursor, [field1, field2, ...]]
       #
       # See the [Redis Server HSCAN documentation](https://redis.io/docs/latest/commands/hscan/) for further details
       def hscan(key, cursor, **options)
         _scan(:hscan, cursor, [key], **options) do |reply|
-          [reply[0], reply[1].each_slice(2).to_a]
+          if options[:novalues]
+            reply
+          else
+            [reply[0], reply[1].each_slice(2).to_a]
+          end
         end
       end
 
@@ -239,6 +246,7 @@ class Redis
       # @param [Hash] options
       #   - `:match => String`: only return keys matching the pattern
       #   - `:count => Integer`: return count keys at most per iteration
+      #   - `:novalues => Boolean`: whether or not to include values in the output (default: false)
       #
       # @return [Enumerator] an enumerator for all found keys
       #
@@ -253,6 +261,162 @@ class Redis
           break if cursor == "0"
         end
       end
+
+      # Sets the time to live in seconds for one or more fields.
+      #
+      # @example
+      #   redis.hset("hash", "f1", "v1")
+      #   redis.hexpire("hash", 10, "f1", "f2") # => [1, -2]
+      #
+      # @param [String] key
+      # @param [Integer] ttl
+      # @param [Array<String>] fields
+      # @return [Array<Integer>] Feedback on if the fields have been updated.
+      #
+      # See https://redis.io/docs/latest/commands/hexpire/#return-information for array reply.
+      def hexpire(key, ttl, *fields)
+        send_command([:hexpire, key, ttl, 'FIELDS', fields.length, *fields])
+      end
+
+      # Returns the time to live in seconds for one or more fields.
+      #
+      # @example
+      #   redis.hset("hash", "f1", "v1", "f2", "v2")
+      #   redis.hexpire("hash", 10, "f1") # => [1]
+      #   redis.httl("hash", "f1", "f2", "f3") # => [10, -1, -2]
+      #
+      # @param [String] key
+      # @param [Array<String>] fields
+      # @return [Array<Integer>] Feedback on the TTL of the fields.
+      #
+      # See https://redis.io/docs/latest/commands/httl/#return-information for array reply.
+      def httl(key, *fields)
+        send_command([:httl, key, 'FIELDS', fields.length, *fields])
+      end
+
+      # Sets the time to live in milliseconds for one or more fields.
+      #
+      # @example
+      #   redis.hset("hash", "f1", "v1")
+      #   redis.hpexpire("hash", 500, "f1", "f2") # => [1, -2]
+      #   redis.hpexpire("hash", 500, "f1", "f2", nx: true) # => [0, -2]
+      #
+      # @param [String] key
+      # @param [Integer] ttl
+      # @param [Hash] options
+      #   - `:nx => true`: Set expiry only when the key has no expiry.
+      #   - `:xx => true`: Set expiry only when the key has an existing expiry.
+      #   - `:gt => true`: Set expiry only when the new expiry is greater than current one.
+      #   - `:lt => true`: Set expiry only when the new expiry is less than current one.
+      # @param [Array<String>] fields
+      # @return [Array<Integer>] Feedback on if the fields have been updated.
+      #
+      # See https://redis.io/docs/latest/commands/hpexpire/#return-information for array reply.
+      def hpexpire(key, ttl, *fields, nx: nil, xx: nil, gt: nil, lt: nil)
+        args = [:hpexpire, key, ttl]
+        args << "NX" if nx
+        args << "XX" if xx
+        args << "GT" if gt
+        args << "LT" if lt
+        args.concat(['FIELDS', fields.length, *fields])
+
+        send_command(args)
+      end
+
+      # Returns the time to live in milliseconds for one or more fields.
+      #
+      # @example
+      #   redis.hset("hash", "f1", "v1", "f2", "v2")
+      #   redis.hpexpire("hash", 500, "f1") # => [1]
+      #   redis.hpttl("hash", "f1", "f2", "f3") # => [500, -1, -2]
+      #
+      # @param [String] key
+      # @param [Array<String>] fields
+      # @return [Array<Integer>] Feedback on the TTL of the fields.
+      #
+      # See https://redis.io/docs/latest/commands/hpttl/#return-information for array reply.
+      def hpttl(key, *fields)
+        send_command([:hpttl, key, 'FIELDS', fields.length, *fields])
+      end
+
+      # Register an ordered list of hash field names under +fieldset_name+ for
+      # use by subsequent #himport_set calls on the same connection.
+      #
+      # Fieldsets are server-side session state scoped to the current physical
+      # connection: they vanish on disconnect or RESET and are invisible to
+      # other connections. See the README "Bulk hash ingestion (HIMPORT)"
+      # section for connection-scoping guidance. Re-preparing an existing
+      # +fieldset_name+ silently replaces it. Field order is preserved as
+      # given; it defines the positional pairing used by #himport_set.
+      #
+      # @note HIMPORT support is experimental: the client API may change in a
+      #   future minor release without a major version bump.
+      #
+      # @example
+      #   redis.himport_prepare("shared", ["name", "email", "age"])
+      #     # => "OK"
+      #
+      # @param [String] fieldset_name name used by later SET and DISCARD calls
+      # @param [String, Array<String>] fields one or more field names
+      # @return [String] `"OK"`
+      # @api experimental
+      def himport_prepare(fieldset_name, *fields)
+        fields.flatten!(1)
+        raise ArgumentError, "fields must not be empty" if fields.empty?
+
+        send_command([:himport, "PREPARE", fieldset_name].concat(fields))
+      end
+
+      # Create or fully replace the hash at +key+ using the field list
+      # registered under +fieldset_name+ on this connection. Values pair
+      # positionally with the fields given to #himport_prepare; the value
+      # count must equal the field count.
+      #
+      # The fieldset must exist on the executing connection, otherwise the
+      # server replies with a "no such fieldset" error.
+      #
+      # @note HIMPORT support is experimental: the client API may change in a
+      #   future minor release without a major version bump.
+      #
+      # @example
+      #   redis.himport_set("shared:1", "shared", ["alice", "alice@example.com", "25"])
+      #     # => "OK"
+      #
+      # @param [String] key hash key to create or overwrite
+      # @param [String] fieldset_name fieldset previously prepared on this connection
+      # @param [String, Array<String>] values one or more values, order preserved
+      # @return [String] `"OK"`
+      # @api experimental
+      def himport_set(key, fieldset_name, *values)
+        values.flatten!(1)
+        raise ArgumentError, "values must not be empty" if values.empty?
+
+        send_command([:himport, "SET", key, fieldset_name].concat(values))
+      end
+
+      # Remove +fieldset_name+ from this connection's session. Keys already
+      # written through the fieldset are not affected.
+      #
+      # @note HIMPORT support is experimental: the client API may change in a
+      #   future minor release without a major version bump.
+      #
+      # @param [String] fieldset_name
+      # @return [Integer] `1` if the fieldset was removed, `0` if it did not exist
+      # @api experimental
+      def himport_discard(fieldset_name)
+        send_command([:himport, "DISCARD", fieldset_name])
+      end
+
+      # Remove all fieldsets from this connection's session.
+      #
+      # @note HIMPORT support is experimental: the client API may change in a
+      #   future minor release without a major version bump.
+      #
+      # @return [Integer] number of fieldsets removed
+      # @api experimental
+      def himport_discard_all
+        send_command([:himport, "DISCARDALL"])
+      end
     end
   end
 end

data/lib/redis/commands/keys.rb

@@ -261,6 +261,9 @@ class Redis
       # @param [String, Array<String>] keys
       # @return [Integer] number of keys that were unlinked
       def unlink(*keys)
+        keys.flatten!(1)
+        return 0 if keys.empty?
+
         send_command([:unlink] + keys)
       end
 
@@ -444,13 +447,14 @@ class Redis
 
       private
 
-      def _scan(command, cursor, args, match: nil, count: nil, type: nil, &block)
+      def _scan(command, cursor, args, match: nil, count: nil, type: nil, novalues: false, &block)
         # SSCAN/ZSCAN/HSCAN already prepend the key to +args+.
 
         args << cursor
         args << "MATCH" << match if match
         args << "COUNT" << Integer(count) if count
         args << "TYPE" << type if type
+        args << "NOVALUES" if novalues
 
         send_command([command] + args, &block)
       end

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.
       #
@@ -320,6 +398,21 @@ class Redis
         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