GenericMatcher 1.2.0

GenericMatcher

A high-performance .NET library for configurable entity matching and relationship mapping.

Features

• Generic type support for flexible entity matching
• Multiple matching strategies with customizable criteria
• Two-way relationship mapping
• Tiered matching for complex matching scenarios
• Support for strict and non-strict matching modes
• High-performance frozen collections for optimal memory usage
• Thread-safe operations
• Fluent API design

Installation

Install via NuGet:

dotnet add package GenericMatcher

Quick Start

Here's a basic example of matching entities:

// Define your entity
public record Person(string Id, string Name, string Email);

// Create match definitions
public class EmailMatch : MatchDefinition<Person, MatchType, string>
{
    public override MatchType MatchType => MatchType.Email;
    public override Func<Person, string> Conversion => x => x.Email.ToLowerInvariant();
}

// Initialize matcher
var matcher = new EntityMatcher<Person, MatchType>(
    seedEntities,
    new[] { new EmailMatch() }
);

// Find matches
var matches = matcher.FindMatches(person, MatchType.Email);

Advanced Usage

Two-Way Dictionary Matching

// Create a two-way relationship map
var twoWayMap = matcher.CreateTwoWayMatchDictionary(
    otherEntities,
    MatchType.Email,
    MatchType.Name
);

// Access matched and unmatched results
var matchedFromA = twoWayMap.AToBMatchedResults.Value;
var unmatchedFromB = twoWayMap.BToAUnmatchedResults.Value;

Tiered Matching

var tieredResult = matcher.CreateTwoWayMatchDictionary(
    otherEntities,
    new[] { 
        new[] { MatchType.Email },
        new[] { MatchType.Name, MatchType.DateOfBirth }
    }
);

Strict Matching

// Throws exception if multiple matches are found
var strictMatches = matcher.CreateStrictTwoWayMatchDictionary(
    otherEntities,
    MatchType.Email
);

Performance

GenericMatcher is designed for high performance:

• Uses frozen collections for immutable operations
• Optimized dictionary lookups
• Memory-efficient data structures
• Thread-safe operations
• Benchmarked using BenchmarkDotNet

Benchmark results for two-way dictionary matching:

API Documentation

EntityMatcher<TEntity, TMatchType>

Core class for entity matching operations.

Methods

• FindMatches(TEntity entity, params TMatchType[] matchTypes)
• FindFirstMatchOrDefault(TEntity entity, params TMatchType[] matchTypes)
• CreateTwoWayMatchDictionary(IEnumerable<TEntity> otherEntities, params TMatchType[] matchTypes)
• CreateStrictTwoWayMatchDictionary(IEnumerable<TEntity> otherEntities, params TMatchType[] matchTypes)

MatchDefinition<TEntity, TMatchType, TProperty>

Base class for defining match criteria.

Properties

• MatchType: The type of match this definition represents
• Conversion: Function to convert entity to comparable property
• IsSeeded: Indicates if the definition has been initialized with seed data

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.