StructuredFilter 0.0.14

StructuredFilter

A general-purpose, business-agnostic structured filter library.

How to use

• Suppose you need to filter out Players that meet certain conditions from a Player list.

public class User
{
    public long Uid { get; set; }
    public string Name { get; set; }
}

public class Player
{
    public User User { get; set; }
    public long Pid { get; set; }
    public string Name { get; set; }
    public Version GameVersion { get; set; }
}

var players = new[]
{
    new Player
    {
        Name = "Dark Knight",
        Pid = 1000,
        User = new User { Name = "Scott", Uid = 1000000 },
        GameVersion = new Version("1.0.1")
    },
    new Player
    {
        Name = "Joker",
        Pid = 1050,
        User = new User { Name = "Tom", Uid = 990000 },
        GameVersion = new Version("1.0.2")
    }
};

• Define Scene filters for the object members you expect to match.

[FilterLabel("玩家 ID")]
[FilterKey("pid")]
public class PidFilter(FilterFactory<Player> filterFactory)
    : NumberSceneFilter<Player>(filterFactory, player => player.Pid);

[FilterLabel("用户名")]
[FilterKey("userName")]
public class UserNameFilter(FilterFactory<Player> filterFactory)
    : StringSceneFilter<Player>(filterFactory, player => player.User.Name);

[FilterLabel("玩家游戏版本")]
[FilterKey("playerGameVersion")]
public class PlayerGameVersionFilter(FilterFactory<Player> filterFactory)
    : VersionSceneFilter<Player>(filterFactory, player => player.GameVersion);

• Create your FilterService<Player> and register the just defined filters.

var filterService = new FilterService<Player>().WithSceneFilters([
    f => new PidFilter(f),
    f => new UserNameFilter(f),
    f => new PlayerGameVersionFilter(f)
]);

• Use filter JSON string to filter your object list. You can also match an object lazily or non-lazily, refer to the demo or tests.

var filterJson = "{\"pid\": {\"$range\": [1000, 1010]}}";
var filteredList = filterService.FilterOut(filterJson, players);
foreach (var filteredPlayer in filteredList)
{
    Console.WriteLine($"player {JsonSerializer.Serialize(filteredPlayer)} match filter {filterJson} successfully");
}
// player "Dark Knight" with Pid 1000 is in filteredList since he matches the range [1000, 1010]
// player "Joker" with Pid 1050 isn't in filteredList since he doesn't match the range [1000, 1010]

Data types for StructuredFilter

Object

• Object is a JSON object but allows exactly one key-value pair.
• Examples: {"userName": "Scott"}, {"userName": {"$eq": "Scott"}}
• Invalid: {"userName": "Scott", "age": 20}, {"userName": {"$eq": "Scott"}, "age": {"$eq": 20}}

Array

• Array is a JSON array containing at least one element, and all elements need to be of the same type.
• Examples: [{"userName": "Scott"}, {"age": 20}], [1, 2, 3], ["a", "b", "c"]
• Invalid: [], [{"userName": "Scott"}, 20], [1, 2, "c"]

Range

• Range is a StructuredFilter Array containing two elements, the first element of the Array is less than or equal to the second element, and the elements need to be one of the following types:
  • string
  • double
  • Version
• The value of Range uses a closed interval, that is, the match is successful when it is greater than or equal to the first element and less than or equal to the second element.
• Examples: [1, 2]、["a", "z"], [Version.Parse("1.0.0"), Version.Parse("1.6.0")]
• Invalid: [], [1], [1, 2, 3], [3, 1]

Filter types

Logic filters

• Logic filters currently does not support nested Logic filters.

Basic filters

Bool filters

Number filters

String filters

Version filters

Scene filters

• Scene filters are defined by the user and can be nested as subordinates of Logic filters or superior of Basic filters.
• The following abstract classes of scene filters are provided to simplify the writing of your scene filters:
  • BoolSceneFilter
  • NumberSceneFilter
  • StringSceneFilter
  • VersionSceneFilter

Features

Cacheable SceneFilter

• If a filter result is cacheable, you can integrate caching in the following ways. First add Cacheable attribute:

[FilterLabel("玩家 ID")]
[FilterKey("pid")]
[Cacheable]
public class PidFilter(FilterFactory<Player> filterFactory)
    : NumberSceneFilter<Player>(filterFactory, player => Task.FromResult((double)player.Pid));

• Implement IFilterResultCache:

public class PlayerFilterCache : IFilterResultCache<Player>
{
    private readonly Dictionary<string, bool> _cacheData = new ();
    public int HitCount = 0;

    public Task<Tuple<bool, bool>> GetFilterResultCacheAsync(Player matchTarget, string filterKey, FilterKv filterKv)
    {
        if (_cacheData.TryGetValue(GetCacheKey(filterKey, filterKv, matchTarget.Pid), out var filterResult))
        {
            Interlocked.Add(ref HitCount, 1);
            return Task.FromResult(new Tuple<bool, bool>(filterResult, true));
        }
        return Task.FromResult(new Tuple<bool, bool>(false, false));
    }

    public Task SetFilterResultCacheAsync(Player matchTarget, string filterKey, FilterKv filterKv, bool result)
    {
        _cacheData[GetCacheKey(filterKey, filterKv, matchTarget.Pid)] = result;
        return Task.CompletedTask;
    }

    private string GetCacheKey(string filterKey, FilterKv filterKv, long pid)
    {
        return $"{filterKey}:{filterKv.Key}:{filterKv.Value}:{pid}";
    }
}

• Pass in the IFilterResultCache implementation in the constructor:

[FilterLabel("玩家 ID")]
[FilterKey("pid")]
[Cacheable]
public class PidFilter(FilterFactory<Player> filterFactory)
    : NumberSceneFilter<Player>(filterFactory, player => Task.FromResult((double)player.Pid), new PlayerFilterCache());

FilterValidator

• FilterValidator is used to verify whether a JSON string or a System.Text.Json.JsonDocument is a valid filter:

try
{
    // Valid filters:
    FilterValidator.MustValid("{\"pid\": 5000}", filterFactory);
    FilterValidator.MustValid("{\"pid\": {\"$ne\": 2000}}", filterFactory);
    // Invalid filters:
    FilterValidator.MustValid("", filterFactory); // Treat empty string as invalid filter
    FilterValidator.MustValid("{\"pid\": \"5000\"}", filterFactory); // Wrong value type for pid filter
    FilterValidator.MustValid("{\"pid\": 5000", filterFactory); // Invalid JSON format
catch (FilterException e)
{
    Console.WriteLine($"invalid filter: {e}");
    throw;
}

• Validate with FilterService:

try
{
    _filterService.MustValidFilter("{\"pid\": 5000"); // Invalid JSON format
}
catch (FilterException e)
{
    Console.WriteLine($"invalid filter: {e}");
    throw;
}