RsqlParserNet.Linq 0.1.0-preview.1

RsqlParserNet

A dependency-light .NET parser for RSQL/FIQL-style REST API query expressions.

RsqlParserNet parses query text into a typed AST with source spans and structured diagnostics. The core package does not depend on ASP.NET Core, LINQ, Entity Framework Core, or ORM APIs.

Current status: the parser core is 0.1.0-preview.3; LINQ, ASP.NET Core, and Entity Framework Core adapters are prepared as 0.1.0-preview.1. The parser core is published for early testing, but public API changes are still possible before 1.0.0.

Installation

Core parser:

dotnet add package RsqlParserNet --prerelease

LINQ adapter:

dotnet add package RsqlParserNet.Linq --prerelease

ASP.NET Core binding:

dotnet add package RsqlParserNet.AspNetCore --prerelease

Entity Framework Core helpers:

dotnet add package RsqlParserNet.EntityFrameworkCore --prerelease

For local development, reference the project directly:

<ProjectReference Include="src/RsqlParserNet/RsqlParserNet.csproj" />
<ProjectReference Include="src/RsqlParserNet.Linq/RsqlParserNet.Linq.csproj" />
<ProjectReference Include="src/RsqlParserNet.AspNetCore/RsqlParserNet.AspNetCore.csproj" />
<ProjectReference Include="src/RsqlParserNet.EntityFrameworkCore/RsqlParserNet.EntityFrameworkCore.csproj" />

Quick Start

using RsqlParserNet;

var query = RsqlParser.Parse("""status=="active";title=="Bike*"""");

foreach (var comparison in query.Root.Comparisons())
{
    Console.WriteLine($"{comparison.Selector} {comparison.Operator} {comparison.Values[0].Text}");
}

For non-exception flows, use TryParse:

var result = RsqlParser.TryParse("status==");

if (!result.Success)
{
    foreach (var diagnostic in result.Diagnostics)
    {
        Console.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");
    }
}

Supported Syntax

Common RSQL/FIQL forms are supported:

status==active
status=="active"
title=="SUP*"
status=in=(active,draft)
createdAt>=2026-01-01
status==active;title=="SUP*"
status==active,title=="Bike*"
(status==active;title=="SUP*"),status==draft

Logical operators:

; = AND
, = OR

AND has higher precedence than OR. Parentheses can override precedence.

See docs/syntax.md for the full grammar, selector rules, value behavior, custom operators, and wildcard/date semantics.

Options

Parser behavior can be configured:

var options = RsqlParseOptions.Default with
{
    AllowWordLogicalOperators = false,
    AllowDottedSelectors = true,
    CustomOperators =
    [
        new RsqlCustomOperator("=contains="),
        new RsqlCustomOperator("=all=", RequiresMultipleValues: true)
    ]
};

var result = RsqlParser.TryParse("title=contains=Bike", options);

Custom operators must use FIQL-style syntax such as =contains=, must not duplicate built-in operators, and must not be configured more than once.

Diagnostics

Parse errors are returned as structured diagnostics:

var result = RsqlParser.TryParse("status==");
var diagnostic = result.Diagnostics[0];

Console.WriteLine(diagnostic.Code);
Console.WriteLine(diagnostic.Message);
Console.WriteLine(diagnostic.Span.Start);
Console.WriteLine(diagnostic.Start.Line);
Console.WriteLine(diagnostic.Start.Column);

Current diagnostic codes:

RsqlParser.Parse throws ArgumentException for empty input and RsqlParseException for invalid syntax. RsqlParseException.Diagnostics contains the same structured diagnostics returned by TryParse.

LINQ Adapter

The repository includes an early RsqlParserNet.Linq adapter project. It translates parsed AST nodes into expression tree predicates using explicit selector mappings:

using RsqlParserNet;
using RsqlParserNet.Linq;

var query = RsqlParser.Parse("status=in=(active,draft);count>=10");

var filtered = products.ApplyRsql(query, options =>
{
    options.Allow("status", x => x.Status);
    options.Allow("count", x => x.Count);
});

You can also build the predicate separately when another layer should decide how to compose or apply it:

var predicate = RsqlPredicateBuilder.BuildPredicate<Product>("status==active", options =>
{
    options.Allow("status", x => x.Status);
});

var filtered = products.Where(predicate);

For repeated endpoint/query contracts, put mappings in a reusable profile:

public sealed class ProductRsqlProfile : RsqlLinqProfile<Product>
{
    public override RsqlParseOptions ConfigureParseOptions(RsqlParseOptions options)
    {
        return options.WithLinqOperators();
    }

    public override void Configure(RsqlLinqOptions<Product> options)
    {
        options.Allow("name", x => x.Name);
        options.Allow("status", x => x.Status);
        options.Allow("count", x => x.Count);
        options.Allow("tags", x => x.Tags);
        options.AllowStringContainsOperator();
        options.AllowStringStartsWithOperator();
        options.AllowStringEndsWithOperator();
        options.AllowCollectionAnyOperator();
        options.AllowCollectionAllOperator();
    }
}

var filtered = products.ApplyRsql("status==active;name=contains=ik", new ProductRsqlProfile());

The adapter currently supports:

Values are converted using the mapped member type, including common scalar types, enums, Guid, DateTime, DateTimeOffset, DateOnly, and TimeOnly.

Custom operators can be translated explicitly after they are configured in parser options:

var parseOptions = RsqlParseOptions.Default with
{
    CustomOperators = [new RsqlCustomOperator(RsqlLinqOperators.Contains)]
};

var filtered = products.ApplyRsql("name=contains=ik", options =>
{
    options.Allow("name", x => x.Name);
    options.AllowStringContainsOperator();
}, parseOptions);

Collection fields can use explicit custom operators:

tags=any=(bike,outdoor)
tags=all=(bike,outdoor)

String equality supports common * wildcards by default:

name==B*    -> StartsWith("B")
name==*met  -> EndsWith("met")
name==*ik*  -> Contains("ik")
name==Bo*d  -> StartsWith("Bo") && EndsWith("d")

See docs/linq-adapter.md for wildcard behavior, value conversion, and adapter limitations. See docs/aspnet-core-usage.md for ASP.NET Core request handling examples.

ASP.NET Core Binding

RsqlParserNet.AspNetCore adds bindable query wrappers for request query strings. Minimal APIs can accept RsqlQueryRequest directly to reuse parsed filter, sort, and page state:

builder.Services.AddRsqlQueryRequest(
    configureFilter: options =>
    {
        options.ParseOptions = ProductRsqlProfile.Instance.ConfigureParseOptions(RsqlParseOptions.Default);
    },
    configurePage: options => options.MaxPageSize = 100);

app.MapGet("/products", async (
    RsqlQueryRequest request,
    AppDbContext db) =>
{
    if (!request.IsValid)
    {
        return Results.ValidationProblem(request.ToValidationErrors());
    }

    var query = request.ApplyTo(db.Products, ProductRsqlProfile.Instance);
    query = request.Sort.HasRequest
        ? query
        : query.OrderBy(product => product.Id);

    var result = await query.ToRsqlPageAsync(request.Page.Request!);

    return Results.Ok(result);
});

Adapter Direction

Expression trees are a good fit for LINQ and Entity Framework Core integration, but they belong in separate adapter packages rather than the parser core.

The intended adapter shape is explicit and allowlisted:

query.ApplyRsql(filter, options =>
{
    options.Allow("title", x => x.Title);
    options.Allow("status", x => x.Status);
    options.Allow("createdAt", x => x.CreatedAt);
});

The core parser should not expose arbitrary reflected entity/property access. Future adapters should translate the AST into expression trees only through configured field mappings.

Framework adapters should stay separate when they need framework-specific dependencies. RsqlParserNet.AspNetCore owns ASP.NET Core binding helpers, and a future RsqlParserNet.FastEndpoints package can wrap FastEndpoints request/validation conventions if plain RsqlQueryFilter.Parse becomes repetitive.

RsqlParserNet.EntityFrameworkCore owns EF Core async execution helpers, including paged result helpers that return items and pagination metadata. Sorting uses the same allowlisted profile mappings as filtering with sort=field and sort=-field.

Development

dotnet build RsqlParserNet.sln
dotnet test RsqlParserNet.sln
dotnet pack src/RsqlParserNet/RsqlParserNet.csproj --configuration Release --output artifacts/packages
dotnet pack src/RsqlParserNet.Linq/RsqlParserNet.Linq.csproj --configuration Release --output artifacts/packages
dotnet pack src/RsqlParserNet.AspNetCore/RsqlParserNet.AspNetCore.csproj --configuration Release --output artifacts/packages
dotnet pack src/RsqlParserNet.EntityFrameworkCore/RsqlParserNet.EntityFrameworkCore.csproj --configuration Release --output artifacts/packages

Project Notes

• Versioning: CHANGELOG.md
• Syntax details: docs/syntax.md
• LINQ adapter details: docs/linq-adapter.md
• LINQ adapter roadmap: docs/linq-roadmap.md
• ASP.NET Core usage: docs/aspnet-core-usage.md
• EF Core helpers: docs/entity-framework-core.md
• Core v1 checklist: docs/core-v1-checklist.md
• Release process: docs/release.md