TypedQuery 1.0.0

TypedQuery

A .NET library for batching multiple database queries into a single roundtrip with type-safe, reusable query definitions.

The Problem

1. EF Core can't run queries concurrently

// 3 sequential roundtrips, no concurrency allowed
var user = await db.Users.FirstOrDefaultAsync(u => u.Id == userId);
var orders = await db.Orders.Where(o => o.UserId == userId).ToListAsync();
var addresses = await db.Addresses.Where(a => a.UserId == userId).ToListAsync();
// Each query waits for the previous one. Database executes them one by one.

2. Dapper's QueryMultipleAsync gets messy

// hard to read, maintain, and reuse
var sql = @"
    SELECT * FROM Users WHERE Id = @userId;
    SELECT * FROM Orders WHERE UserId = @userId;
    SELECT * FROM Addresses WHERE UserId = @userId;";

using var multi = await connection.QueryMultipleAsync(sql, new { userId = 5 });
var user = await multi.ReadFirstOrDefaultAsync<User>();
var orders = (await multi.ReadAsync<Order>()).ToList();
var addresses = (await multi.ReadAsync<Address>()).ToList();

The Solution

TypedQuery batches your queries into a single SQL script.

var result = await db
    .ToTypedQuery()
    .Add(new GetUserById(userId))
    .Add(new GetOrdersByUserId(userId))
    .Add(new GetAddressesByUserId(userId))
    .ExecuteAsync();

var user = result.Get<UserDto>();
var orders = result.GetList<OrderDto>();
var addresses = result.GetList<AddressDto>();
// One roundtrip.

This drives developers toward cleaner code while improving performance when multiple independent queries are needed together and database roundtrips are expensive.

For single queries, avoid the overhead (negligible but measurable).

Installation

dotnet add package TypedQuery

# or for EF Core integration =>

dotnet add package TypedQuery.EntityFrameworkCore

Quick Start

Define Queries

Raw SQL Query

public class GetUserById(int id) : ITypedQuery<UserDto>
{
    public QueryDefinition Build(QueryBuildContext context)
    {
        return new QueryDefinition(
            "SELECT Id, Name, Email FROM Users WHERE Id = @id",
            [new SqlParameter("@id", id)]);
    }
}

EF Core Query

public class GetOrdersByUserId(int userId) : ITypedQuery<AppDbContext, OrderDto>
{
    public IQueryable<OrderDto> Query(AppDbContext db)
    {
        return db.Orders
            .Where(o => o.UserId == userId)
            .Select(o => new OrderDto { Id = o.Id, Total = o.Total });
    }
}

⚠️ Important: To use EF Core queries, you must register the TypedQuery interceptor:

services.AddDbContext<AppDbContext>(options => 
{
    options.UseSqlServer(connectionString);
    options.UseTypedQuery();  // Required for EF Core mode!
});

Execute Queries

With EF Core DbContext

var result = await dbContext
    .ToTypedQuery()
    .Add(new GetUserById(5))
    .Add(new GetOrdersByUserId(5))
    .ExecuteAsync();

var user = result.Get<UserDto>();
var orders = result.GetList<OrderDto>();

With Raw DbConnection

var result = await connection
    .ToTypedQuery()
    .Add(new GetUserById(5))
    .Add(new GetActiveProducts())
    .ExecuteAsync();

var user = result.Get<UserDto>();
var products = result.GetList<ProductDto>();

Why Use TypedQuery?

⚡ Performance

TL;DR: TypedQuery RawSQL mode matches Dapper performance. TypedQuery EF Core mode has significant overhead on localhost but wins with network latency due to single-roundtrip architecture.

Localhost Benchmarks (SQLite in-memory, ~0ms latency)

RawSQL Mode Performance

TypedQuery RawSQL mode is for users writing raw SQL queries (like Dapper users):

Conclusion: RawSQL mode has negligible overhead vs Dapper.

EF Core Mode Performance

TypedQuery EF Core mode is for users wanting to write LINQ queries but batch them:

Conclusion: On localhost, EF Core mode has multi-millisecond CPU overhead from the interceptor-based SQL capture mechanism. This is slower than just running EF Core queries sequentially.

Why the overhead?

• Each LINQ query is executed through EF Core to capture the generated SQL (~1ms per query)
• Parameter cloning and batching adds cost
• On localhost, this CPU cost dominates because network latency is ~0ms

Real-World Performance (with network latency)

Critical Context: The localhost benchmarks above are misleading because they don't include network latency. In production where database round-trips can have meaningful overhead, TypedQuery's single-roundtrip architecture shines.

RawSQL Mode with Network Latency

RawSQL mode stays close to Dapper (both use single roundtrip):

EF Core Mode with Network Latency

This is where the story changes - the fixed CPU overhead gets amortized by network savings:

5 Queries Example:

10 Queries Example:

Key Insights

1. RawSQL Mode: Matches Dapper, great for raw SQL users who want typed organization
2. EF Core Mode on Localhost: Slower than native EF Core (10-15ms overhead for 5-10 queries)
3. EF Core Mode on Cloud: Faster than native EF Core (3-7× speedup with typical latency)
4. The Trade-off: Fixed CPU cost vs variable network cost

See benchmarks/BENCHMARK_RESULTS.md for detailed analysis.

Packages

Contributing

Contributions are welcome! This library is in active development and there's room for performance improvements, especially in the EF Core query capture mechanism.

License

MIT License - see LICENSE for details.

Acknowledgments

• Built on top of Dapper for query execution
• Inspired by the need for cleaner batch query patterns in .NET