profunktor/redis4cats

redis4cats is a Scala library that provides a functional, type-safe interface to Redis, built on top of FS2 and Cats Effect. It exposes a comprehensive API covering core data structures, advanced features like Lua scripting and ACL management, and robust streaming capabilities for Pub/Sub and Redis Streams. The system emphasizes safe resource management, configurable connection handling for clusters and master-replica topologies, and extensible codec derivation for custom data types.

13 changes.

The project was rebranded from fs2-redis to redis4cats and migrated to Scala 3, accompanied by a comprehensive expansion of the Redis command API to cover Redis 7.x features like ACL and JSON. This period also involved significant infrastructure modernization, including the adoption of Munit for testing, MiMa for binary compatibility checks, and the introduction of new codec derivation utilities and connection management APIs.

8 changes.

The project underwent a significant refactoring of its core, PubSub, and Streams modules to introduce builder-style configuration, FS2-native streaming types, and more granular connection management. These changes enhanced stability through better timeout handling and offset resolution, while also adding new features like data encryption, Lua scripting convenience, and Pub/Sub pattern subscriptions.

A new implicit Log instance is provided for the log4cats library, allowing users to integrate redis4cats with their existing log4cats logging setup. This enables seamless logging of debug, info, and error messages through the standard Log interface.

modules/log4cats · high confidence

A new shell script, check\_dirty.sh, has been added to the repository. This script checks for uncommitted changes in the Git working directory and exits with an error if any are detected, allowing CI/CD pipelines or pre-commit hooks to prevent operations on dirty states.

scripts · high confidence

The algebra layer in this module has been significantly expanded to expose a wide range of new Redis commands, effectively closing coverage gaps for Redis 7.x features. This includes new traits and methods for Access Control Lists (ACL), JSON manipulation, Bitmaps, HyperLogLog, and Pub/Sub statistics. Existing data structures have also been enriched: Hashes now support expiration per field and random field retrieval; Lists support multi-pop and position lookup; Sets include cardinality commands and multi-member checks; Sorted Sets add intersection cardinality, range store, and blocking multi-pop operations; and Streams gain consumer group management, extended deletion, and configuration commands. Additionally, new capabilities for scripting (including functions), connection management (auth, role, echo), and server maintenance (memory, save, slowlog) are now available in the API.

modules/effects/src/main/scala/dev/profunktor/redis4cats/algebra · high confidence

Added a new \luaScripting\ extension module that simplifies working with Redis Lua scripts. Users can now easily load Lua scripts from classpath resources via \LuaScript.loadFromResources\, which automatically handles reading the file and digesting the content to obtain the SHA. Additionally, a new \evalLua\ extension method is available on the \Scripting\ type class, which attempts to execute a script by its SHA and automatically falls back to evaluating the raw script content if the script is not yet cached in Redis, reducing boilerplate for script management.

modules/effects/src/main/scala/dev/profunktor/redis4cats/extensions · high confidence

The library now provides a dedicated \AclDecoder\ that safely parses Redis ACL replies (such as \ACL GETUSER\ and \ACL LOG\) into typed Scala structures (\AclUser\, \AclSelector\) using a strict \Resp\ ADT, replacing previous untyped handling. Additionally, the \RedisCommands\ trait has been expanded to include \AclCommands\, ensuring that Access Control List operations are now fully exposed alongside the existing string, hash, and stream command sets.

modules/effects/src/main/scala/dev/profunktor/redis4cats · high confidence

The \redis4cats\ library now includes a new \codecs\ package that allows users to derive custom Redis codecs from existing ones using split epimorphisms. This enables seamless transformation of key and value types (e.g., String to Int, Long, or Double) without manual serialization logic, as demonstrated by the provided \stringIntEpi\, \stringLongEpi\, and \stringDoubleEpi\ utilities. Users can now easily adapt the library's underlying Lettuce codecs to their specific domain types by composing these split epimorphisms with base codecs.

modules/core/src/main/scala/dev/profunktor/redis4cats/codecs · high confidence

Added a comprehensive suite of demo applications in the examples module to illustrate library usage. These include \Demo\ for shared configuration, \JsonCodecDemo\ for custom codec derivation, \PubSubDemo\ and \PublisherDemo\ for message streaming, and specific demos for Redis data structures (Bitmaps, Geo, Hashes, Keys, Lists, Sets, Sorted Sets, Strings). The examples also cover advanced features such as cluster connections (\RedisClusterStringsDemo\, \RedisClusterTransactionsDemo\), master-replica setups, connection pooling, Lua scripting, transactions, pipelining, and lifting commands to \EitherT\.

modules/examples/src/main/scala · high confidence

The empty Fs2Redis object in the core module has been removed. This cleanup eliminates a placeholder component that contained no implementation or public API, simplifying the library's structure without affecting any existing functionality.

core · high confidence

The library introduces a new internal architecture for Redis transactions and logging. A dedicated single-threaded execution context (TxExecutor) now ensures that transaction commands run sequentially, preventing race conditions. A new capability trait (MkRedis) centralizes the creation of Redis clients and exposes internal components like the transaction runner and logger. Additionally, a pluggable logging typeclass (Log) is added, providing built-in no-op and standard output implementations to help users debug transaction and pipeline operations without forcing external logging dependencies.

modules/core/src/main/scala/dev/profunktor/redis4cats/effect · high confidence

The library has been renamed from fs2-redis to redis4cats, reflected in the README, package structure, and Maven coordinates. To support this transition, a Scala Steward configuration was added to automate dependency updates, and a Mergify configuration was introduced to automatically label and merge Scala Steward pull requests upon successful CI builds. The project also adopted a new Code of Conduct and updated its contribution guidelines.

(repo-wide) · high confidence

The connection layer has been restructured to provide a more explicit and type-safe API for establishing Redis connections. Users can now configure connections using a dedicated \RedisUriConfig\ DSL that supports standalone, socket, and Sentinel endpoints, along with TLS, credentials (including Redis 6 ACL username/password), and timeout settings. The new \RedisClient\ and \RedisClusterClient\ objects replace previous creation patterns, offering methods like \from\, \fromUri\, and \withOptions\ that return \Resource\ instances for safe lifecycle management. Additionally, a new \RedisMasterReplica\ connection type is introduced to support master-replica topologies with configurable read preferences (e.g., \MasterPreferred\). Cluster clients now include built-in topology refresh strategies (periodic, adaptive, or both) and node filtering capabilities.

modules/core/src/main/scala/dev/profunktor/redis4cats/connection · high confidence

The core library has been refactored to introduce a builder-style \Redis4CatsConfig\ that allows users to control shutdown timeouts, customize cluster node filters, and configure topology view refresh strategies (periodic, adaptive, or both). New capabilities include data compression (DEFLATE, GZIP) and encryption (AES/CBC) via updated \RedisCodec\ helpers, as well as compile-time validated \redis\ string interpolators for safer URI construction. The API also standardizes read-from strategies (e.g., \LowestLatency\), provides safe null-handling for Java boxed types, and adds support for Pub/Sub pattern subscriptions (PSUBSCRIBE/PUNSUBSCRIBE).

modules/core/src/main/scala/dev/profunktor/redis4cats · high confidence

The PubSub module now provides distinct connection factories—mkPubSubConnection for combined publishing and subscribing, mkPublisherConnection for publishing/stats only, and mkSubscriberConnection for subscribing only—replacing the previous single connection model. The API also introduces a new RestartOnTimeout mechanism to automatically retry operations that time out, addressing issues where reading from a silent stream would fail with RedisCommandTimeoutException. Additionally, the PubSubStats trait now requires NonEmptyList for multi-channel queries like numSub to prevent invalid commands, and the SubscribeCommands trait exposes internal subscription tracking via internalChannelSubscriptions and internalPatternSubscriptions.

modules/streams/src/main/scala/dev/profunktor/redis4cats/pubsub · high confidence

The streaming module has been rewritten to use FS2-native data structures, replacing the previous implementation with a new \Streaming\ trait and \RedisStream\ class that operate directly on \Stream\[F, \*\]\. This change introduces a new \XAddMessage\ data type for appending entries and refines the \read\ operation to automatically resolve and pin \Latest\ offsets to the stream's actual last ID, preventing message skips when streams are empty between polls. The API now explicitly maps to Redis \XADD\ and \XREAD\ commands, providing a more robust and idiomatic FS2-based streaming experience.

modules/streams/src/main/scala/dev/profunktor/redis4cats/streams · high confidence

The internal PubSub subsystem has been restructured into distinct components: \LivePubSubCommands\ and \Publisher\ now handle command execution and statistics via a new \LivePubSubStats\ class, while \PubSubInternals\ provides dedicated channel and pattern listeners that route messages through an fs2 \Topic\ and a parallel \Dispatcher\. Subscription lifecycle and state are managed by \PubSubState\ using \AtomicCell\ for thread-safe locking and \Redis4CatsSubscription\ to track subscriber counts and trigger cleanup, ensuring that listeners are correctly removed and resources are released when subscriptions are no longer needed.

modules/streams/src/main/scala/dev/profunktor/redis4cats/pubsub/internals · high confidence

Added property-based tests for codec split morphisms; Added test coverage for Redis connection configuration and encryption; Added test suite for Redis ACL decoder and integration tests for streams, pub/sub, and transactions; Added tests for FutureLift behavior and CancellationException handling.

The build system has been significantly upgraded: sbt is updated to version 1.13.0, and key plugins like sbt-mdoc (2.9.2), sbt-mima-plugin (1.2.1), and sbt-ci-release (1.12.1) are refreshed. A new MimaVersionPlugin is introduced to automatically configure binary compatibility checks against previous releases, filtering out specific internal API changes. Additionally, core library dependencies have been bumped to modern versions, including Cats Effect 3.7.1, FS2 3.14.0, Lettuce 7.7.0, and Circe 0.14.16, while removing older testing and coverage plugins in favor of Munit.

project · high confidence

The build configuration has been updated to target Scala 3.9.0, replacing the previous cross-build support for Scala 2.11 and 2.12. The project has been rebranded from 'fs2-redis' to 'redis4cats', with the organization changed to 'dev.profunktor' and the GitHub repository updated to 'profunktor/redis4cats'. The module structure has been reorganized into distinct subprojects including 'redis4cats-core', 'redis4cats-effects', 'redis4cats-streams', and 'redis4cats-log4cats'. Additionally, the build now uses Munit for testing instead of ScalaTest/ScalaCheck, enables MiMa for binary compatibility checking against base version 3.0.0, and configures the compiler to use Scala 3 migration mode.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 62.

• Code Health 96
• Architecture 98
• Maturity 57
• Readiness 55
• Security 67

• 300 commits — 283 feature/other, 17 fixes

• (repo) — 89 commits
• project/Dependencies.scala — 58 commits
• (root) — 38 commits
• modules/effects — 38 commits
• project/plugins.sbt — 30 commits
• project/build.properties — 15 commits
• modules/streams — 11 commits
• modules/core — 8 commits
• modules/tests — 5 commits
• .github/workflows — 4 commits
• site/docs — 3 commits
• modules/examples — 1 commit

• fix: Bug/subscribing to channel and pattern doubles messages in channel subscriber (#950)
• fix: Fix always-throwing PubSubCommands.numSub; require NonEmptyList across the pubsub-stats family (#1205)
• fix: Fix compilation
• fix: Fix compilation.
• fix: Fix doc compilation?
• fix: Fix race conditions in pubsub (#966)
• fix: Revert "Sbt git upgrade (#894)" (#895)
• fix: Revert "fix snapshot publishing by updating sbt and sbt-ci-release"
• fix: Revert "update sbt and sbt-ci-release to 1.11.0-RC2 (#1011)"
• fix: attempt to fix release rolling back to older version (#1030)
• fix: bugfix: reading from a silent stream should not fail with RedisCommandTimeoutException (#952)
• fix: fix (#1024)
• fix: fix snapshot publishing by updating sbt and sbt-ci-release
• fix: series/3.x: last pre-3.0.0 fixes (ServerCommands arity, MIGRATE, DELEX, COMMAND, SLOWLOG, CLIENT TRACKING) (#1193)
• fix: series/3.x: redesign Geo/List/Hash APIs, fix discarded return values (#1180)
• fix: update dev-tools with jekyll fix
• fix: upgrade lettuce and fix deprecation warning (#1076)
• change: Add basic stream commands to redis impl
• change: Add docs
• change: Add fromMasterReplica connection builder method to RedisStream (#967)
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

profunktor/redis4cats was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.