dartis

Description:

dartis

Redis client for Dart #


Features #

Type-safe commands
Pipelining
Fire and forget
Publish/Subscribe
Monitor mode
Inline commands
Transactions
Lua scripting
Custom serializers/deserializers
Custom commands for building Modules

Usage #
Create a connection:
final client = await Client.connect('redis://localhost:6379');
copied to clipboard
Get a type-safe view of the available Redis Commands:
final commands = client.asCommands<String, String>();
copied to clipboard
Run some commands:
await commands.set('key', 'value');

final value = await commands.get('key');

print(value);
copied to clipboard
Disconnect:
await client.disconnect();
copied to clipboard
Connection String #
Connection string must follow the following pattern:
redis://{host}:{port}
copied to clipboard
Example:
redis://localhost:6379
copied to clipboard
Client Modes #
Clients can work in the following modes:

Online
Publish/Subscribe
Inline commands
Monitor

Online #
In this mode the client can send any command to the Redis server.
// Connect
final client = await Client.connect('redis://localhost:6379');

// Run some commands
final commands = client.asCommands<String, String>();

final result = await commands.ping();
print(result);

// Disconnect
await client.disconnect();
copied to clipboard
See client.dart in the example folder.
Publish/Subscribe #
In this mode the only allowed commands are subscribe, unsubscribe, psubscribe, punsubscribe, ping and quit.
The replies to subscription and unsubscription commands along with the published messages are received in the form of events, so that the client can just read a coherent Stream of events.
final pubsub = await PubSub.connect<String, String>('redis://localhost:6379');

// Subscribe to some channels and patterns
pubsub
..subscribe(channel: 'dev.dart')
..psubscribe(pattern: 'dartlang.news.*');

// Listen for server replies
pubsub.stream.listen(print, onError: print);
copied to clipboard
See pubsub.dart in the example folder.
If the Redis server is protected with a password then a client connection must be created in order to run the Redis AUTH command.
final client = await Client.connect('redis://localhost:6379');

final commands = client.asCommands<String, String>();

await commands.auth('password');

// Create the PubSub object using the client connection
final broker = PubSub<String, String>(client.connection);
copied to clipboard
Inline Commands #
In this mode the commands are sent to the server using the "inline command" format. Ideal to use in interactive sessions, like a Telnet session.
final terminal = await Terminal.connect('redis://localhost:6379');

// Run some commands
terminal.run('PING\r\n'.codeUnits);

// Listen for server replies
terminal.stream.listen(print);
copied to clipboard
Note that in this mode the commands are just lists of bytes with a trailing \r\n.
See terminal.dart in the example folder.
Monitor #
In this mode the client receives all the commands procesed by the Redis server. Useful for debugging.
final monitor = await Monitor.connect('redis://localhost:6379');

// Start the monitor mode
monitor.start();

// Listen for server replies
monitor.stream.listen(print);
copied to clipboard
In this mode the client can not run any command.
See monitor.dart in the example folder.
Commands #
The method asCommands<K, V> of the client returns a type-safe view of the available Redis Commands. K is the type to be used for Redis keys and V for values. Most times, using String for keys and values is what you want:
final commands = client.asCommands<String, String>();
copied to clipboard
However, it's correct to call this method several times in order to get views with different parameterized types:
final strings = client.asCommands<String, String>();
final bytes = client.asCommands<String, List<int>>();

String title = await strings.get('book:24902:title');
List<int> cover = await bytes.get('book:24902:cover');

// ERROR String author = await bytes.get('book:24092:author');
copied to clipboard
Keep in mind that Redis stores sequences of bytes, not just Strings.
Pipelining #
Pipeling is used in order to send multiple commands to the server in only one call, instead of doing one call for each command.
In this mode the client stores locally all the commands without sending them to the server until the flush method is called.
// Start pipeline
client.pipeline();

// Run some commands
commands.incr('product:9238:views').then(print);
commands.incr('product:1725:views').then(print);
commands.incr('product:4560:views').then(print);

// Flush pipeline
client.flush();
copied to clipboard
The method flush returns a list of Futures that can be used for waiting the completion of all the commands.
// Start pipeline
client.pipeline();

// Run some commands
commands
..incr('product:9238:views')
..incr('product:1725:views')
..incr('product:4560:views');

// Flush pipeline
final futures = client.flush();

// Wait for all the Futures
await Future.wait<Object>(futures).then(print);
copied to clipboard
Please note that in this mode await can not be used for waiting the result of the execution of each command because the returned Futures will not be completed until flush was called.
Fire and Forget #
In this mode the server doesn't sent replies for the commands, so the client doesn't need to wait for them.
This mode is started running the clientReply command with ReplyMode.off or ReplyMode.skip.
In this mode the Futures are immediately completed with null.
// Discard all the server replies
await commands.clientReply(ReplyMode.off);

// Run some commands
await commands.ping().then(print); // null
await commands.ping().then(print); // null
await commands.ping().then(print); // null
copied to clipboard
The following modes are available:

ReplyMode.off: In this mode the server will not reply to client commands.
ReplyMode.skip: In this mode the server will skip the reply of command immediately after it.
ReplyMode.on: In this mode the server will return a reply to every command.

Transactions #
Redis allows to group commands together so that they are executed as a single transaction.
A transaction begins running the multi command, ends running the exec command, and can be aborted running the discard command.
// Start transaction
await commands.multi();

// Run some commands
commands.set(key, 1).then(print);
commands.incr(key).then(print);

// End transaction
await commands.exec(); // Or abort: commands.discard()
copied to clipboard
The watch command can be used for perfoming optimistic lockings over some keys. A transaction will fail if the "watched" keys are modified by another client.
// Watch
await commands.watch(key: key);

// Start transaction
await commands.multi();

// Run some commands
commands.set(key, 1).then(print);
commands.incr(key).then(print);

// End transaction
await commands.exec();
copied to clipboard
Please note that in this mode await can not be used for waiting the result of the execution of each command because the returned Futures will not be completed until exec or discard were called.
Caveats #
Don't run the clientReply command inside a transaction. If the "fire and forget" mode is de/activated inside a transaction then the client could go out of sync with the server.
Redis transactions are deprecated in favor of Lua scripting.
Lua scripting #
Redis allows to run Lua scripts in the server.
Scripts can be executed with the eval and evalsha commands.
// Evaluate
await commands.eval<void>(
'return {KEYS[1],KEYS[2],ARGV[1],ARGV[2]}',
keys: [key1, key2],
args: ['first', 'second']);
copied to clipboard
The result of a script can be anything. It can be ignored, like in the above example, or it can be mapped to a most useful thing.
// Maps a list of server replies to a list of Strings
class _Mapper implements Mapper<List<String>> {
@override
List<String> map(Reply reply, RedisCodec codec) =>
codec.decode<List<String>>(reply);
}

...

// Evaluate with a mapper
final results = await commands.eval<List<String>>(
'return {KEYS[1],KEYS[2],ARGV[1],ARGV[2]}',
keys: [key1, key2],
args: ['first', 'second'],
mapper: _Mapper());

print(results); // ['key1', 'key2', 'first', 'second']
copied to clipboard
Custom Serializers/Deserializers #
Encoders are used for serializing all the values sent to Redis. They convert instances of any type to list of bytes. Encoders for types int, double, String and List<int> are registered by default. UTF-8 is used for Strings.
Custom encoders can be written extending from Encoder or Converter.
Example:
An encoder that encodes instances of DateTime to lists of bytes:
class DateTimeEncoder extends Encoder<DateTime> {
@override
List<int> convert(DateTime value, [RedisCodec codec]) =>
utf8.encode(value.toString());
}
copied to clipboard
Decoders are used for deserializing all the replies received from Redis. They convert list of bytes to instances of any type, and arrays of server replies to lists of instances of any type. Decoders for types int, double, String, List<int>, List<double>, List<Sring> and List<List<int>> are registered by default. UTF-8 is used for Strings.
Custom decoders can be written extending from Decoder or Converter.
Example:
A decoder that decodes lists of bytes to instances of DateTime.
class DateTimeDecoder extends Decoder<SingleReply, DateTime> {
@override
DateTime convert(SingleReply value, [RedisCodec codec]) =>
value.bytes == null ? null : DateTime.parse(utf8.decode(value.bytes));
}
copied to clipboard
Custom encoders and decoders can be registered using the codec member of the client:
client.codec.register(
encoder: DateTimeEncoder(),
decoder: DateTimeDecoder());
copied to clipboard
Custom Commands #
Custom sets of commands can be written extending from ModuleBase. This class exposes the method run that sent to Redis any given line of commands, so it can be used for implementing the API of any Redis module.
Example:
A module that exposes a HELLO name command:
class HelloModule extends ModuleBase {

HelloModule(Client client) : super(client);

Future<String> hello(String name) => run<String>(<Object>[r'HELLO', name]);
}
copied to clipboard
Usage:
final module = HelloModule(client);

final message = await module.hello('World!');

print(message);
copied to clipboard
Note that standard Redis commands can be rewritten too for building custom interfaces.
Example:
An even more type-safe set of commands:
class TypedCommands<K> extends ModuleBase {

TypedCommands(Client client) : super(client);

Future<void> set<R>(K key, R value) => run<void>(<Object>[r'SET', key, value]);

Future<R> get<R>(K key) => run<R>(<Object>[r'GET', key]);
}
copied to clipboard
Usage:
final commands = TypedCommands<String>(client);

await commands.set<String>('name', 'Bob');
await commands.set<int>('age', 29);
await commands.set<List<int>>('photo', png);

final name = await commands.get<String>('name');
final age = await commands.get<int>('age');
final photo = await commands.get<List<int>>('photo');
copied to clipboard
Note that if a module works with a custom structure, like a record with multiple fields, then custom encoders and decoders should be used.
Log #
The logging package is used for logging messages through a custom logger named 'dartis'.
Here is a simple logging configuration that logs all messages via print:
import 'package:logging/logging.dart';

...

Logger.root.level = Level.INFO;
Logger.root.onRecord.listen((LogRecord record) {
print('${record.time} ${record.level.name} ${record.loggerName} ${record.message}');
});
copied to clipboard
Set the log level according your needs. Most times, INFO is what you want. ALL is good for filling issues.
Testing #
Dependencies of this packages can installed with pub get and test cases can
be run with pub run test. These test cases requires a redis running on
localhost:6379, for local development this can be created with docker:

docker run --rm -p 127.0.0.1:6379:6379 redis

This starts a container running redis and exposes port 6379 localhost, when
killed using ctrl+c the container will be deleted.