RedisClient

public protocol RedisClient

An object capable of sending commands and receiving responses.

let client = ...
let result = client.send(command: "GET", arguments: ["my_key"])
// result == EventLoopFuture<RESPValue>

For the full list of available commands, see https://redis.io/commands

  • The NIO.EventLoop that this client operates on.

    Declaration

    Swift

    var eventLoop: EventLoop { get }
  • Sends the given command to Redis.

    Declaration

    Swift

    func send<CommandResult>(_ command: RedisCommand<CommandResult>) -> EventLoopFuture<CommandResult>

    Parameters

    command

    The command to send to Redis for execution.

    Return Value

    A NIO.EventLoopFuture that will resolve when the Redis command receives a response.

    If a RedisError is returned, the future will be failed instead.

  • Temporarily overrides the default logger for command logs to the provided instance.

    Declaration

    Swift

    func logging(to logger: Logger) -> RedisClient

    Parameters

    logger

    The Logging.Logger instance to use for command logs.

    Return Value

    A RedisClient with the temporary override for command logging.

  • Subscribes the client to the specified Redis channels, invoking the provided message receiver each time a message is published.

    See SUBSCRIBE

    Important

    This will establish the client in a “PubSub mode” where only a specific list of commands are allowed to be executed.

    Commands issued with this client outside of that list will resolve with failures.

    See the PubSub specification

    Default Implementation

    Declaration

    Swift

    func subscribe(
        to channels: [RedisChannelName],
        messageReceiver receiver: @escaping RedisSubscriptionMessageReceiver,
        onSubscribe subscribeHandler: RedisSubscriptionChangeHandler?,
        onUnsubscribe unsubscribeHandler: RedisSubscriptionChangeHandler?
    ) -> EventLoopFuture<Void>

    Parameters

    channels

    The names of channels to subscribe to.

    receiver

    A closure which will be invoked each time a channel with a name in channels publishes a message.

    subscribeHandler

    An optional closure to be invoked when the subscription becomes active.

    unsubscribeHandler

    An optional closure to be invoked when the subscription becomes inactive.

    Return Value

    A notification NIO.EventLoopFuture that resolves once the subscription has been registered with Redis.

  • Subscribes the client to the specified Redis channel name patterns, invoking the provided message receiver each time a message is published to a matching channel.

    Note

    If the client is also subscribed to a channel directly by name which also matches a pattern, both subscription message receivers will be invoked.

    See PSUBSCRIBE

    Important

    This will establish the client in a “PubSub mode” where only a specific list of commands are allowed to be executed.

    Commands issues with this client outside of that list will resolve with failures.

    See the PubSub specification

    Default Implementation

    Declaration

    Swift

    func psubscribe(
        to patterns: [String],
        messageReceiver receiver: @escaping RedisSubscriptionMessageReceiver,
        onSubscribe subscribeHandler: RedisSubscriptionChangeHandler?,
        onUnsubscribe unsubscribeHandler: RedisSubscriptionChangeHandler?
    ) -> EventLoopFuture<Void>

    Parameters

    patterns

    A list of glob patterns used for matching against PubSub channel names to subscribe to.

    receiver

    A closure which will be invoked each time a channel with a name matching the specified pattern(s) publishes a message.

    subscribeHandler

    An optional closure to be invoked when the subscription becomes active.

    unsubscribeHandler

    An optional closure to be invoked when the subscription becomes inactive.

    Return Value

    A notification NIO.EventLoopFuture that resolves once the subscription has been registered with Redis.

  • unsubscribe(from:) Default implementation

    Unsubscribes the client from a specific Redis channel from receiving any future published messages.

    See UNSUBSCRIBE

    Note

    If the channel was not subscribed to with subscribe(to:messageReceiver:onSubscribe:onUnsubscribe:), then this method has no effect.

    Important

    If no more subscriptions (pattern or channel) are active on the client, the client will be taken out of its “PubSub mode”.

    It will then be allowed to use any command like normal.

    See the PubSub specification

    Default Implementation

    Declaration

    Swift

    func unsubscribe(from channels: [RedisChannelName]) -> EventLoopFuture<Void>

    Parameters

    channels

    A list of channel names to be unsubscribed from.

    Return Value

    A notification NIO.EventLoopFuture that resolves once the subscription(s) have been removed from Redis.

  • punsubscribe(from:) Default implementation

    Unsubscribes the client from a pattern of Redis channel names from receiving any future published messages.

    See PUNSUBSCRIBE

    Note

    This method does not unsubscribe subscriptions made with subscribe(to:messageReceiver:onSubscribe:onUnsubscribe:).

    Important

    If no more subscriptions (pattern or channel) are active on the client, the client will be taken out of its “PubSub mode”.

    It will then be allowed to use any command like normal.

    See the PubSub specification

    Default Implementation

    Declaration

    Swift

    func punsubscribe(from patterns: [String]) -> EventLoopFuture<Void>

    Parameters

    patterns

    A list of glob patterns to be unsubscribed from.

    Return Value

    A notification NIO.EventLoopFuture that resolves once the subscription(s) have been removed from Redis.

  • ping(with:) Extension method

    Pings the server, which will respond with a message.

    See RedisCommand.ping(with:)

    Declaration

    Swift

    public func ping(with message: String? = nil) -> EventLoopFuture<String>

    Parameters

    message

    The optional message that the server should respond with instead of the default.

    Return Value

    A NIO.EventLoopFuture that resolves the given message or Redis’ default response of PONG.

  • authorize(with:) Extension method

    Requests the client to authenticate with Redis to allow other commands to be executed.

    See RedisCommand.auth(with:)

    Declaration

    Swift

    public func authorize(with password: String) -> EventLoopFuture<Void>

    Parameters

    password

    The password to authenticate with.

    Return Value

    A NIO.EventLoopFuture that resolves if the password as accepted, otherwise it fails.

  • select(database:) Extension method

    Selects the Redis logical database having the given zero-based numeric index.

    See RedisCommand.select(database:)

    Note

    New connections always use the database 0.

    Declaration

    Swift

    public func select(database index: Int) -> EventLoopFuture<Void>

    Parameters

    index

    The 0-based index of the database that the connection sending this command will execute later commands against.

    Return Value

    A NIO.EventLoopFuture resolving once the operation has succeeded.

  • Incrementally iterates over all fields in a hash.

    See RedisCommand.hscan(_:startingFrom:matching:count:)

    Declaration

    Swift

    public func scanHashFields(
        in key: RedisKey,
        startingFrom position: Int = 0,
        matching match: String? = nil,
        count: Int? = nil
    ) -> EventLoopFuture<(Int, [RedisHashFieldKey: RESPValue])>

    Parameters

    key

    The key of the hash.

    position

    The position to start the scan from.

    match

    A glob-style pattern to filter values to be selected from the result set.

    count

    The number of elements to advance by. Redis default is 10.

    valueType

    The type to cast all values to.

    Return Value

    A NIO.EventLoopFuture that resolves a cursor position for additional scans, with a limited collection of fields and their associated values that were iterated over.

  • delete(_:) Extension method

    Deletes the given keys. Any key that does not exist is ignored.

    See RedisCommand.del(keys:)

    Declaration

    Swift

    public func delete(_ keys: RedisKey...) -> EventLoopFuture<Int>

    Parameters

    keys

    The list of keys to delete from the database.

    Return Value

    A NIO.EventLoopFuture that resolves the number of keys that were deleted from the database.

  • delete(_:) Extension method

    Deletes the given keys. Any key that does not exist is ignored.

    See RedisCommand.del(keys:)

    Declaration

    Swift

    public func delete(_ keys: [RedisKey]) -> EventLoopFuture<Int>

    Parameters

    keys

    The list of keys to delete from the database.

    Return Value

    A NIO.EventLoopFuture that resolves the number of keys that were deleted from the database.

  • expire(_:after:) Extension method

    Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.

    See RedisCommand.expire(_:after:)

    Declaration

    Swift

    public func expire(_ key: RedisKey, after timeout: TimeAmount) -> EventLoopFuture<Bool>

    Parameters

    key

    The key to set the expiration on.

    timeout

    The time from now the key will expire at.

    Return Value

    A NIO.EventLoopFuture that resolves true if the expiration was set and false if it wasn’t.

  • Incrementally iterates over all keys in the currently selected database.

    See RedisCommand.scan(startingFrom:matching:count:)

    Declaration

    Swift

    public func scanKeys(
        startingFrom position: Int = 0,
        matching match: String? = nil,
        count: Int? = nil
    ) -> EventLoopFuture<(Int, [RedisKey])>

    Parameters

    position

    The cursor position to start from.

    match

    A glob-style pattern to filter values to be selected from the result set.

    count

    The number of elements to advance by. Redis default is 10.

    Return Value

    A cursor position for additional invocations with a limited collection of keys found in the database.

  • publish(_:to:) Extension method

    Publishes the provided message to a specific Redis channel.

    See RedisCommand.publish(_:to:)

    Declaration

    Swift

    @discardableResult
    @inlinable
    public func publish<Message: RESPValueConvertible>(
        _ message: Message,
        to channel: RedisChannelName
    ) -> EventLoopFuture<Int>

    Parameters

    message

    The “message” value to publish on the channel.

    channel

    The name of the channel to publish the message to.

    Return Value

    The number of subscribed clients that received the message.

  • swapDatabase(_:with:) Extension method

    Swaps the data of two Redis databases by their index IDs.

    See RedisCommand.swapdb(_:with:)

    Declaration

    Swift

    public func swapDatabase(_ first: Int, with second: Int) -> EventLoopFuture<Bool>

    Parameters

    first

    The index of the first database.

    second

    The index of the second database.

    Return Value

    A NIO.EventLoopFuture that resolves true if the command succeed or false if it didn’t.

  • Incrementally iterates over allv alues in a set.

    See RedisCommand.sscan(_:startingFrom:matching:count:)

    Declaration

    Swift

    public func scanSetValues(
        in key: RedisKey,
        startingFrom position: Int = 0,
        matching match: String? = nil,
        count: Int? = nil
    ) -> EventLoopFuture<(Int, [RESPValue])>

    Parameters

    key

    The key of the set.

    position

    The position to start the scan from.

    count

    The number of elements to advance by. Redis default is 10.

    match

    A glob-style pattern to filter values to be selected from the result set.

    Return Value

    A NIO.EventLoopFuture that resolves a cursor position for additional scans, with a limited collection of values that were iterated over.

  • Incrementally iterates over all elements in a sorted set.

    See RedisCommand.zscan(_:startingFrom:matching:count:)

    Declaration

    Swift

    public func scanSortedSetValues(
        in key: RedisKey,
        startingFrom position: Int = 0,
        matching match: String? = nil,
        count: Int? = nil
    ) -> EventLoopFuture<(Int, [(RESPValue, Double)])>

    Parameters

    key

    The key identifying the sorted set.

    position

    The position to start the scan from.

    match

    A glob-style pattern to filter values to be selected from the result set.

    count

    The number of elements to advance by. Redis default is 10.

    Return Value

    A NIO.EventLoopFuture that resolves a cursor position for additional scans, with a limited collection of elements with their scores found in the Sorted Set.

  • get(_:) Extension method

    Gets the value of the given key.

    See RedisCommand.get(_:)

    Declaration

    Swift

    public func get(_ key: RedisKey) -> EventLoopFuture<RESPValue?>

    Parameters

    key

    The key to fetch the value from.

    Return Value

    A NIO.EventLoopFuture that resolves the value stored at the given key, otherwise nil.

  • get(_:as:) Extension method

    Gets the value of the given key, converting it to the desired type.

    See RedisCommand.get(_:)

    Declaration

    Swift

    @inlinable
    public func get<Value: RESPValueConvertible>(
        _ key: RedisKey,
        as type: Value.Type = Value.self
    ) -> EventLoopFuture<Value?>

    Parameters

    key

    The key to fetch the value from.

    type

    The desired type to convert the stored data to.

    Return Value

    A NIO.EventLoopFuture that resolves the converted value stored at the given key, otherwise nil if the key does not exist or fails the type conversion.

  • get(_:asJSON:decoder:) Extension method

    Gets the value of the given key, decoding it as a JSON data structure.

    See RedisCommand.get(_:)

    Declaration

    Swift

    @inlinable
    public func get<D: Decodable>(
        _ key: RedisKey,
        asJSON type: D.Type = D.self,
        decoder: JSONDecoder = .init()
    ) -> EventLoopFuture<D?>

    Parameters

    key

    The key to fetch the value from.

    type

    The JSON type to decode to.

    decoder

    The optional JSON decoder instance to use. Defaults to .init().

    Return Value

    A NIO.EventLoopFuture that resolves the decoded JSON value at the given key, otherwise nil if the key does not exist or JSON decoding fails.

  • set(_:to:) Extension method

    Sets the value stored at the given key, overwriting the previous value.

    Any previous expiration set on the key is discarded if the SET operation was successful.

    See RedisCommand.set(_:to:)

    Important

    Regardless of the type of value stored at the key, it will be overwritten to a “string” value.

    Declaration

    Swift

    @inlinable
    public func set<Value>(_ key: RedisKey, to value: Value) -> EventLoopFuture<Void> where Value : RESPValueConvertible

    Parameters

    key

    The key to use to uniquely identify this value in Redis.

    value

    The value to set the key to.

    Return Value

    A NIO.EventLoopFuture that resolves if the operation was successful.

  • Sets the value stored at the given key with options to control how to set it.

    See RedisCommand.set(_:to:onCondition:expiration:)

    Important

    Regardless of the type of value stored at the key, it will be overwritten to a “string” value.

    Declaration

    Swift

    @inlinable
    public func set<Value: RESPValueConvertible>(
        _ key: RedisKey,
        to value: Value,
        onCondition condition: RedisSetCommandCondition,
        expiration: RedisSetCommandExpiration? = nil
    ) -> EventLoopFuture<RedisSetCommandResult>

    Parameters

    key

    The key to use to uniquely identify this value.

    value

    The value to set the key to.

    condition

    The condition under which the key should be set.

    expiration

    The expiration to set on the key when setting the value. If nil, no expiration will be set.

    Return Value

    A NIO.EventLoopFuture indicating the result of the operation; .ok if successful and .conditionNotMet if the given condition was not meth.

    If the condition .none was used, then the result value will always be .ok.

  • set(_:toJSON:encoder:) Extension method

    Sets the value stored at the given key to the given value as JSON data.

    See RedisCommand.set(_:to:)

    Important

    Regardless of the type of value stored at the key, it will be overwritten to a “string” value.

    Declaration

    Swift

    @inlinable
    public func set<E: Encodable>(
        _ key: RedisKey,
        toJSON value: E,
        encoder: JSONEncoder = .init()
    ) -> EventLoopFuture<Void>

    Parameters

    key

    The key to use to uniquely identify this value in Redis.

    value

    The value to convert to JSON data and set the key to.

    encoder

    The optional JSON encoder instance to use. Defaults to .init().

    Return Value

    A NIO.EventLoopFuture that resolves if the operation was successful.

  • Sets the value stored at the given key as JSON data with options to control how to set it.

    See RedisCommand.set(_:to:onCondition:expiration:)

    Important

    Regardless of the type of value stored at the key, it will be overwritten to a “string” value.

    Declaration

    Swift

    @inlinable
    public func set<E: Encodable>(
        _ key: RedisKey,
        toJSON value: E,
        onCondition condition: RedisSetCommandCondition,
        expiration: RedisSetCommandExpiration? = nil,
        encoder: JSONEncoder = .init()
    ) -> EventLoopFuture<RedisSetCommandResult>

    Parameters

    key

    The key to use to uniquely identify this value in Redis.

    value

    The value to convert to JSON data set the key to.

    condition

    The condition under which the key should be set.

    expiration

    The expiration to set on the key when setting the value. If nil, no expiration will be set.

    Return Value

    A NIO.EventLoopFuture indicating the result of the operation; .ok if successful and .conditionNotMet if the given condition was not meth.

    If the condition .none was used, then the result value will always be .ok.

  • unsubscribe() Extension method

    Unsubscribes the client from all active Redis channel name subscriptions.

    Declaration

    Swift

    public func unsubscribe() -> EventLoopFuture<Void>

    Return Value

    A NIO.EventLoopFuture that resolves when the subscriptions have been removed.

  • punsubscribe() Extension method

    Unsubscribes the client from all active Redis channel name patterns subscriptions.

    Declaration

    Swift

    public func punsubscribe() -> EventLoopFuture<Void>

    Return Value

    A NIO.EventLoopFuture that resolves when the subscriptions have been removed.