dart_valkey 0.0.5

Dart client for Valkey (and Redis-compatible servers)

dart_valkey

A robust, type-safe Dart client for Valkey and Redis.

dart_valkey is a robust, type-safe Dart client for Redis and Valkey that manages both command and Pub/Sub interactions. It provides built-in connection management, automatic reconnection, and pluggable authentication.

---

Why dart_valkey?

• SSL Certificate Management: Unlike other Dart clients, dart_valkey provides onBadCertificate callback for handling self-signed certificates in development or internal servers.

• Easy Extensibility: Create custom commands easily by extending ValkeyCommand<T>. The parser handles RESP2 and RESP3 automatically.

• Automatic Reconnection: Built-in exponential backoff with jitter (500ms → 30s) and auto-resubscribe for Pub/Sub when connection is restored.

• Type-Safe Design: From predefined commands to Dart extensions, everything is type-safe. The compiler helps catch errors before runtime.

---

Features

• Connection Management
  Uses the Template Method pattern in BaseConnection to handle socket connection, reconnection logic, and error management automatically.

• Authentication and Command Execution
  Implements authentication commands (HELLO and AUTH) for secure data exchange with the server.

• Pub/Sub Support
  Supports regular, pattern, and sharded Pub/Sub operations with the ValkeySubscriptionClient.

• RESP2 and RESP3 Support
  Automatically detects and uses the appropriate protocol version.

• Extensible & Modular
  Commands are organized into modules. New commands can be added as extensions or by creating custom ValkeyCommand classes.

---

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  dart_valkey: any

Or with a specific version:

dependencies:
  dart_valkey: ^0.0.4

Then run:

dart pub get

---

Quick Start

Connecting and Sending Commands

import 'package:dart_valkey/dart_valkey.dart';

Future<void> main() async {
  final client = ValkeyCommandClient(
    host: 'localhost',
    port: 6379,
    // username: 'your-username',  // optional
    // password: 'your-password',  // optional
  );

  await client.connect();

  // Using extensions
  await client.set('key', 'value');
  final value = await client.get('key');
  print('Value: $value');

  await client.close();
}

Pub/Sub Example

import 'package:dart_valkey/dart_valkey.dart';

Future<void> main() async {
  final subClient = ValkeySubscriptionClient(
    host: 'localhost',
    port: 6379,
  );

  await subClient.connect();

  // Subscribe to channels
  subClient.subscribe(['notifications']);

  // Listen for messages
  subClient.messages.listen((PubSubMessage msg) {
    print('Message: ${msg.message} on channel: ${msg.channel}');
  });

  await Future.delayed(const Duration(seconds: 30));
  await subClient.close();
}

---

Running Tests

To run the tests, you need a Valkey or Redis server running on localhost:6379.

# Start Valkey server (if not running)
valkey-server --daemonize yes

# Run all tests
dart test

# Run only unit tests (skip integration tests)
dart test -x integration

---

Documentation

• Commands Implementation: See COMMANDS.md for the complete list of supported commands.
• Benchmark: See BENCHMARK.md for performance comparisons with other Dart Redis clients.
• API Reference: Visit pub.dev for the full API documentation.

---

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests on our GitHub repository.

To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: dart test
5. Submit a pull request

---

Links

• Package on pub.dev
• GitHub Repository
• Valkey Documentation
• Redis Documentation