PepperX.QueryForge 1.0.5

PepperX.QueryForge

PepperX.QueryForge is the abstract, provider-agnostic foundation of the QueryForge ecosystem. It provides the core models, fluent builders, and bulletproof validation engines required to construct dynamic, paginated, and hierarchically grouped queries.

⚠️ Important: This package defines the intent and structure of the query but does not execute it. To execute queries against a database, you must install an execution provider like PepperX.QueryForge.Dapper.

📑 Table of Contents

• ✨ Core Features
• 🧩 The Provider Ecosystem
• 🏗️ Core Concepts
• 🔍 Advanced Filtering
• 🌳 Hierarchical Grouping Models
• 🛡️ Security & Validation Engine
• 📚 Enum Reference

✨ Core Features

• Abstract & Provider-Agnostic: Define your query intent once in C# or JSON. Execute it anywhere by plugging in a provider (Dapper, EF Core, InMemory).
• Bulletproof Security: Built-in SilentStrip validation engine prevents schema enumeration, data dumps, and malicious column requests before the query ever reaches the database.
• Zero Boilerplate: Beautiful Fluent API for building queries in C#, or accept them as raw JSON payloads directly from frontends.
• Complex Logic Trees: Natively supports deeply nested AND / OR / AND NOT logic groups.

🧩 The Provider Ecosystem

This core library is automatically included as a dependency when you install an execution provider.

🏗️ Core Concepts

The Base Query vs. Provider Queries

To prevent frontends from spoofing target tables (e.g., sending "object": {"name": "AdminPasswords"}), your API endpoints should accept the base PepperX.QueryForge.Query class. The backend then securely upgrades it to a provider-specific query (like DapperQuery).

// Frontend sends this JSON (Notice: No 'object' property — it's physically impossible to spoof)
// { "paging": { "size": 10 }, "sortColumns": [{"columnName": "Score", "sortOrder": 1}] }

// The backend maps the frontend criteria, paging, and sorting securely.

🔍 Advanced Filtering

QueryForge supports deeply nested logical groups and a comprehensive set of comparison operators.

C# Builder Syntax

var criteria = new QueryCriteria(
    logic: Logic.And,
    groups: [
        new ConditionGroup(
            logic: Logic.Or,
            conditions: [
                new Condition("Country", ConditionOperator.Equals, "USA"),
                new Condition("Country", ConditionOperator.Equals, "Germany")
            ]
        ),
        new ConditionGroup(
            logic: Logic.AndNot,
            conditions: [
                new Condition("Role", ConditionOperator.Equals, "Guest"),
                new Condition("Age", ConditionOperator.LessThan, 21)
            ]
        )
    ]
);

Equivalent JSON Payload (from Frontend)

{
  "criteria": {
    "logic": 0,
    "groups": [
      {
        "logic": 1,
        "conditions": [
          { "columnName": "Country", "operator": 0, "value": "USA" },
          { "columnName": "Country", "operator": 0, "value": "Germany" }
        ]
      },
      {
        "logic": 2,
        "conditions": [
          { "columnName": "Role", "operator": 0, "value": "Guest" },
          { "columnName": "Age", "operator": 6, "value": 21 }
        ]
      }
    ]
  }
}

🌳 Hierarchical Grouping Models

By specifying GroupByColumns, the core models define how the execution provider should transform a flat tabular result into a deeply nested hierarchical tree.

var query = QueryBuilder.New()
    .GroupBy(
        new GroupByDescriptor("Country", SortOrder.Ascending),
        new GroupByDescriptor("Department", SortOrder.Ascending)
    )
    .Page(5, 1) // Paginates the TOP-LEVEL groups
    .Build();

Target JSON Structure (Handled by Providers)

{
  "meta": { "total": { "rows": 2, "pages": 1 }, "type": "Grouped" },
  "groups": [
    {
      "key": "USA",
      "count": 45,
      "subGroups": [
        {
          "key": "IT",
          "count": 20,
          "items": [ { "userId": 1, "name": "Alice" } ]
        }
      ]
    }
  ]
}

🛡️ Security & Validation Engine

Never trust frontend query payloads. The core validation engine can either silently sanitize malicious requests or throw strict errors.

Silent Strip (Recommended for Public APIs)

Silently removes denied columns and clamps pagination limits without throwing errors.

query.Validate(rules =>
{
    // Prevent sensitive column leakage
    rules.Select(c => c.Deny("PasswordHash", "SecretKey", "DeletedAt"));
    
    // Prevent data-dump attacks
    rules.PageSize(p => p.Max(100));
}, ValidationMode.SilentStrip);

Strict Validation (Recommended for Internal APIs)

Throws a QueryValidationException containing a list of all violated rules.

try 
{
    query.Validate(rules => rules.Select(c => c.Deny("PasswordHash")), ValidationMode.ThrowException);
}
catch (QueryValidationException ex)
{
    // ex.InvalidProperties contains ["PasswordHash"]
}

📚 Enum Reference

When sending JSON payloads from the frontend, enums are serialized as integers by default.

ConditionOperator

Logic

SortOrder

🤝 Contributing & License

This project is part of the PepperX Ecosystem. Licensed under the MIT License.