TypeRedis

A high-performance, cluster-aware, type-safe Dart client for Redis, Valkey, and compatible servers.

Supported Commands • Usage • Features

Supported Commands

Core Data Types

Basic data structures and generic key operations.

• STRING / HASH / LIST / SET / SORTED SET
• BITMAP / HYPERLOGLOG / GEOSPATIAL INDICES / STREAM
• GENERIC (Keys, Expiration, etc.)

Modules & Extensions

Advanced data types and query engines (JSON, Search, Probabilistic structures).

• JSON / SEARCH / TIME SERIES / VECTOR SET
• BLOOM FILTER / CUCKOO FILTER
• COUNT-MIN SKETCH / T-DIGEST SKETCH / TOP-K SKETCH

System & Operations

Server management, connection handling, and flow control.

• CONNECTION / SERVER / CLUSTER
• PUBSUB / TRANSACTIONS / SCRIPTING AND FUNCTIONS

Usage

1-1. Redis/Valkey Standalone (Basic)

import 'package:typeredis/typeredis.dart';

void main() async {
  final client = TRClient(host: 'localhost', port: 6379);
  try {
    await client.connect();
    await client.set('Hello', 'Welcome to TypeRedis');
    print(await client.get('Hello'));
  } catch (e) {
    print('Error: $e');
  } finally {
    await client.close();
  }
}

1-2. Redis/Valkey Standalone (Advanced)

import 'package:typeredis/typeredis.dart';

void main() async {
  final settings = TRConnectionSettings(
    host: 'localhost',
    port: 6379,
    // useSsl: false,
    // database: 0,
  );
  final aClient = TRClient.fromSettings(settings);
  try {
    await aClient.connect();
    await aClient.set('Hello', 'Welcome to TypeRedis');
    print(await aClient.get('Hello'));
  } catch (e) {
    print('Error: $e');
  } finally {
    await aClient.close();
  }
}

2. Redis/Valkey Sentinel

import 'package:typeredis/typeredis.dart';

void main() async {
  final rSettings = TRConnectionSettings(
    host: 'localhost',
    port: 6379,
    readPreference: ReadPreference.preferReplica
  );
  final rClient = TRClient.fromSettings(rSettings);
  try {
    await rClient.connect();
    await rClient.set('Hello', 'Welcome to TypeRedis');
    print(await rClient.get('Hello'));
  } catch (e) {
    print('Error: $e');
  } finally {
    await rClient.close();
  }
}

3. Redis/Valkey Cluster

import 'package:typeredis/typeredis.dart';

void main() async {
  final nodes = [
    TRConnectionSettings(host: 'localhost', port: 7001)
  ];
  final sClient = TRClusterClient(nodes);
  try {
    await sClient.connect();
    await sClient.set('Hello', 'Welcome to TypeRedis');
    print(await sClient.get('Hello'));
  } catch (e) {
    print('Error: $e');
  } finally {
    await sClient.close();
  }
}

Features

🚀 Performance & Scalability

Feature	Description
Scalable Replica Reads	Boost read performance by offloading read-only commands (e.g., GET, EXISTS) to replica nodes. Supports ReadPreference settings (master, preferReplica, replicaOnly) to control traffic flow.
Smart Load Balancing	Built-in load balancing strategies (Round-Robin, Random) to efficiently distribute read traffic across available replicas.
Multi-key Support	Supports MGET across multiple nodes using smart Scatter-Gather pipelining.
Sharded Pub/Sub & Atomic Counters	Added support for high-performance cluster messaging (SPUBLISH/SSUBSCRIBE) and atomic integer operations (INCR/DECR).

🛡️ High Availability & Resilience

Feature	Description
Automatic Failover	Resilience: The client now survives node failures. If a master node goes down (connection refused/timeout), the client automatically refreshes the cluster topology and reroutes commands to the new master without throwing an exception.
High Availability & Resilience	Automatically and transparently handles cluster topology changes (-MOVED and -ASK redirections) to ensure robust failover, seamless scaling, and zero‑downtime operations.
Automatic Replica Discovery	Automatically detects and connects to replica nodes via INFO REPLICATION (Standalone/Sentinel) to maintain an up-to-date pool of connections.
Cluster Auto-Discovery	Added client.clusterSlots() to fetch cluster topology (via the CLUSTER SLOTS command), laying the foundation for full cluster support.

🧩 Developer Experience & Tooling

Feature	Description
Redis/Valkey Module Detector	Retrieves module metadata to identify installed extensions (e.g., json, search, ldap, bf).
JSON Module Checker	Pre-validates JSON module availability before execution.
Server Metadata Discovery	Access server details via client.metadata (Version, Mode, Server Name, Max Databases) to write adaptive logic for Valkey vs. Redis.
Type-Safe Exceptions	Clear distinction between connection errors (TRConnectionException), server errors (TRServerException), and client errors (TRClientException).
Observability	Built-in logging.

🔌 Connection & Configuration

Feature	Description
Smart Database Selection	First-class support for selecting databases (0-15+) on connection. Automatically detects Valkey 9.0+ Numbered Clusters to enable multi-database support in cluster mode, while maintaining backward compatibility with Redis Clusters (DB 0 only).
Explicit Replica Configuration	Added explicitReplicas to TRConnectionSettings to manually define replica nodes, solving connectivity issues in environments where auto-discovery fails.
Cluster Client	TRClusterClient: Dedicated client for automatic command routing in cluster mode. We recommend using TRClient for Standalone/Sentinel and TRClusterClient for cluster environments.
Built-in Connection Pooling	TRPool for efficient connection management (used by Standalone and Cluster clients).
Connection Pool Hardening	Smart Release Mechanism: Prevents pool pollution by automatically detecting and discarding "dirty" connections (e.g., inside Transaction or Pub/Sub) upon release.
Command Timeout	Includes a built-in command timeout (via TRConnectionSettings) to prevent client hangs on non-responsive servers.

🔒 Security & Core

Feature	Description
Enterprise Security	Native SSL/TLS support compatible with major cloud providers (AWS, Azure, GCP). Supports custom security contexts (including self-signed certificates).
Robust Parsing	Full RESP3 parser handling all core data types (+, -, $, *, :).
Pub/Sub Ready (Standalone/Sentinel)	subscribe() returns a Subscription object with a Stream and a Future<void> ready for easy and reliable message handling.
Production-Ready	Standalone/Sentinel: Stable for production use. Cluster: Stable for production use with full cluster support.