TypeRedis

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

pub package CT pub package

Supported Commands • Usage • Features

Supported Commands

Core Data Types

Basic data structures and generic key operations.

Modules & Extensions

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

System & Operations

Server management, connection handling, and flow control.

Usage

TypeRedis provides full alias sets for Redis and Valkey, including Client, ClusterClient, Pool, Exceptions, Configuration, and Data Models. (Check out Developer Experience Improvements).

1-1. Redis/Valkey Standalone (Basic)

For Redis users

import 'package:typeredis/typeredis.dart';

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

For Valkey users

import 'package:typeredis/typeredis.dart';

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

1-2. Redis/Valkey Standalone (Advanced)

For Redis users

import 'package:typeredis/typeredis.dart';

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

For Valkey users

import 'package:typeredis/typeredis.dart';

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

2. Redis/Valkey Sentinel

For Redis users

import 'package:typeredis/typeredis.dart';

void main() async {
  final settings = RedisConnectionSettings(
    host: 'localhost',
    port: 6379,
    readPreference: ReadPreference.preferReplica
  );
  final client = RedisClient.fromSettings(settings);
  try {
    await client.connect();
    await client.set('Hello', 'Welcome to Redis!');
    print(await client.get('Hello'));
  } catch (e) {
    print('Error: $e');
  } finally {
    await client.close();
  }
}

For Valkey users

import 'package:typeredis/typeredis.dart';

void main() async {
  final settings = ValkeyConnectionSettings(
    host: 'localhost',
    port: 6379,
    readPreference: ReadPreference.preferReplica
  );
  final client = ValkeyClient.fromSettings(settings);
  try {
    await client.connect();
    await client.set('Hello', 'Welcome to Valkey!');
    print(await client.get('Hello'));
  } catch (e) {
    print('Error: $e');
  } finally {
    await client.close();
  }
}

3. Redis/Valkey Cluster

For Redis users

import 'package:typeredis/typeredis.dart';

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

For Valkey users

import 'package:typeredis/typeredis.dart';

void main() async {
  final nodes = [
    ValkeyConnectionSettings(
      host: 'localhost', 
      port: 7001,
    )
  ];
  final client = ValkeyClusterClient(nodes);
  try {
    await client.connect();
    await client.set('Hello', 'Welcome to Valkey!');
    print(await client.get('Hello'));
  } catch (e) {
    print('Error: $e');
  } finally {
    await client.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.
Enhanced Developer Experience Provides full alias sets for Redis and Valkey—including Exceptions, Configuration, and Data Models
(e.g., RedisException, RedisMessage, ValkeyException, ValkeyMessage)—to ensure API consistency and simplify backend migration.
Developer Experience Added RedisClient and ValkeyClient alias and smart redirection handling for better usability and stability.
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.

Libraries

redis_client
This library provides a Redis-compatible interface.
typeredis
A modern, production-ready Dart client for Valkey (7.x/8.x/9.0.0+). Fully Redis 7.x/8.* compatible.
typeredis_base
typeredis_cluster_client_base
typeredis_commands_base
typeredis_connection
typeredis_pool
valkey_client
This library provides a Valkey-compatible interface.