v3.0.0

BloomFilter.NetCore v3.0.0 Release Notes

🎉 Major Update

v3.0.0 is a major version upgrade that introduces a modern Fluent API, performance optimizations, and code quality improvements.

✨ New Features

🔗 Unified Fluent API

A modern fluent builder API is now provided for all implementations, offering better discoverability and expressiveness:

Unified FilterBuilder API

// New Fluent API (recommended)
var filter = FilterBuilder.Create()
    .WithName("UserFilter")
    .ExpectingElements(10_000_000)
    .WithErrorRate(0.001)
    .UsingHashMethod(HashMethod.XXHash3)
    .BuildInMemory();

// Legacy static method (still compatible)
var filter = FilterBuilder.Build(10_000_000, 0.001);

Redis Fluent Builders

All Redis implementations now support fluent configuration:

FilterRedisBuilder (StackExchange.Redis):

var filter = FilterRedisBuilder.Create()
    .WithRedisConnection("localhost:6379")
    .WithRedisKey("bloom:users")
    .WithName("UserFilter")
    .ExpectingElements(10_000_000)
    .WithErrorRate(0.001)
    .UsingHashMethod(HashMethod.XXHash3)
    .BuildRedis();

FilterCSRedisBuilder (CSRedisCore):

var filter = FilterCSRedisBuilder.Create()
    .WithRedisClient(csredisClient)
    .WithRedisKey("bloom:users")
    .ExpectingElements(10_000_000)
    .BuildCSRedis();

FilterFreeRedisBuilder (FreeRedis):

var filter = FilterFreeRedisBuilder.Create()
    .WithRedisClient(redisClient)
    .WithRedisKey("bloom:users")
    .ExpectingElements(10_000_000)
    .BuildFreeRedis();

FilterEasyCachingBuilder (EasyCaching):

var filter = FilterEasyCachingBuilder.Create()
    .WithRedisCachingProvider(provider)
    .WithRedisKey("bloom:users")
    .ExpectingElements(10_000_000)
    .BuildEasyCaching();

🔧 Modernization Improvements

• ✅ Use ArgumentNullException.ThrowIfNull for argument validation (.NET 6+)
• ✅ Use ArgumentException.ThrowIfNullOrWhiteSpace for string validation (.NET 8+)
• ✅ Use init properties in FilterMemorySerializerParam (.NET 5+)
• ✅ All modernization improvements maintain backward compatibility via conditional compilation

⚡ Performance Optimizations

• ✅ Optimized AsyncLock implementation by removing unnecessary fields
• ✅ Ensured data consistency during BitArray serialization

🔄 Breaking Changes

FilterBuilder Inheritance Support

To enable inheritance for Redis builders, field access modifiers in FilterBuilder have been changed from private to protected:

// Before (v2.x)
private string _name;
private long _expectedElements;

// After (v3.0)
protected string _name;
protected long _expectedElements;

Impact: If your code directly inherits from FilterBuilder, you can now access these protected fields. For regular users, no code changes are required.

📚 Documentation Improvements

• Added comprehensive Fluent API usage guide
• Updated all example code
• Added documentation for Redis Fluent Builders

🐛 Bug Fixes

• Fixed data consistency issues in SerializeAsync by restoring BitArray cloning to prevent potential concurrency problems during serialization

📦 Compatibility

• .NET Framework: net462
• .NET Standard: netstandard2.0
• .NET Core/5+: net6.0, net7.0, net8.0, net9.0, net10.0

🔄 Migration Guide

Upgrading from v2.x to v3.0

Most users do not need to change any code—all legacy APIs remain fully compatible:

// ✅ v2.x code continues to work in v3.0
var bf = FilterBuilder.Build(10_000_000, 0.01);
bf.Add("item");

If you'd like to adopt the new Fluent API:

// ✅ New Fluent API (optional)
var bf = FilterBuilder.Create()
    .ExpectingElements(10_000_000)
    .WithErrorRate(0.01)
    .BuildInMemory();
bf.Add("item");

✅ Test Coverage

• All 239 unit tests pass
• Added 19 new Fluent API tests
• All target frameworks pass testing

📈 Performance Benchmarks

Performance remains consistent with or slightly better than v2.x; AsyncLock optimizations reduce memory allocations.