Razory 2.2.3

Razory

Razory is a lightweight .NET library for working with MongoDB through a structured, application-oriented API.

It provides:

• typed document configuration
• centralized database configuration
• generic repository-style CRUD operations
• composable query objects
• request-driven filtering, sorting, and paging
• collection index definition and initialization
• dependency injection registration for the Razory stack

Razory is intended for teams that want a thinner abstraction than a full ORM while still keeping MongoDB access explicit, reusable, and organized.

What Razory Does

Razory organizes MongoDB access around a few core concepts:

• DocumentBase Base type for persisted documents.

• DocumentConfiguration<T> Defines the collection name and collection indexes for a document type.

• DatabaseConfiguration Defines the connection string, database name, and the set of configured documents.

• Razory Initializes Razory infrastructure such as collection indexes.

• IRepository Exposes common persistence operations such as insert, update, delete, get, execute, and upsert.

• IQueryObject<T> Builds composable read queries through explicit filters and sorts.

• IQueryRequestProcessor<T> Applies request-based filtering, sorting, grouping-as-sort, and pagination on top of a query object.

This keeps the application model centered on typed documents and reusable query pipelines instead of raw collection access scattered across the codebase.

Current Feature Set

Persistence

• Insert one or many documents
• Update one or many documents
• Delete one or many documents by id
• Get a document by id
• Upsert documents
• Execute custom collection actions

Querying

• Build reusable query objects
• Compose filters with raw Mongo filter builders or typed query filter definitions
• Compose sorts fluently
• Project query results
• Run aggregate pipelines
• Process QueryRequest instances for:
  • paging
  • dynamic filters
  • dynamic sorting
  • visual grouping through sort order

Configuration and Initialization

• Define documents through DocumentConfiguration<T>
• Group them under a DatabaseConfiguration
• Define collection indexes through CollectionIndexDefinition<T>
• Initialize configured collection indexes with Razory.InitializeAsync()

Package Structure

The library is organized roughly like this:

• Razory/Configurations Database-level configuration contracts and base classes.

• Razory/Persistence Repository abstraction, commands, document configuration, index definitions, and Mongo resolvers.

• Razory/QueryObjects Query object API, request processing, paging, sorting, filtering, and aggregation helpers.

• Razory/Extensions Dependency injection bootstrap through ConfigureRazory.

Getting Started

1. Define a document

using Razory.Configurations;

public sealed class UserDocument : DocumentBase
{
    public string Email { get; set; } = string.Empty;
    public string FullName { get; set; } = string.Empty;
    public Guid AccountId { get; set; }
    public bool IsActive { get; set; }
}

2. Define the document configuration

using Razory.Persistence.Documents;

public sealed class UserDocumentConfiguration : DocumentConfiguration<UserDocument>
{
    public override string Name => "users";

    public override IEnumerable<CollectionIndexDefinition<UserDocument>> GetCollectionIndexes()
    {
        yield return CollectionIndexDefinition<UserDocument>
            .Ascending(x => x.Email)
            .Unique()
            .Named("ix_users_email");

        yield return CollectionIndexDefinition<UserDocument>
            .Ascending(x => x.AccountId)
            .ThenAscending(x => x.IsActive)
            .Named("ix_users_account_active");
    }
}

If a document has no indexes yet, the configuration can be minimal:

using Razory.Persistence.Documents;

public sealed class AuditLogDocumentConfiguration : DocumentConfiguration<AuditLogDocument>
{
    public override string Name => "audit_logs";
}

3. Define the database configuration

using Razory.Configurations;

public sealed class AppDatabaseConfiguration : DatabaseConfiguration
{
    public AppDatabaseConfiguration()
    {
        AddDocument(new UserDocumentConfiguration());
        AddDocument(new AuditLogDocumentConfiguration());
    }

    public override string ConnectionString =>
        "<your-mongodb-connection-string>";

    public override string DatabaseName =>
        "appdb";
}

4. Register Razory

using Microsoft.Extensions.DependencyInjection;
using Razory.Configurations;

var services = new ServiceCollection();

services.AddSingleton<IDatabaseConfiguration, AppDatabaseConfiguration>();
services.ConfigureRazory();

var serviceProvider = services.BuildServiceProvider();

5. Initialize Razory

var razory = serviceProvider.GetRequiredService<Razory.Razory>();
await razory.InitializeAsync();

This initializes the configured collection indexes for the configured documents.

6. Use the repository

var repository = serviceProvider.GetRequiredService<IRepository>();

await repository.InsertAsync(new UserDocument
{
    Email = "jane@example.com",
    FullName = "Jane Doe",
    AccountId = Guid.NewGuid(),
    IsActive = true
});

Query Objects

Query objects let you build read pipelines that stay reusable and explicit.

var queryObject = serviceProvider.GetRequiredService<IQueryObject<UserDocument>>();

var result = queryObject
    .FilterBy(b => b.Eq(x => x.Email, "jane@example.com"))
    .SortAscending(x => x.FullName)
    .Query();

var user = await result.FirstOrDefaultAsync();

You can also define typed query filters by inheriting from QueryObjectFilterDefinition<T>.

Request-Driven Queries

For UI-driven grids or list endpoints, Razory exposes IQueryRequestProcessor<T>.

var queryObject = serviceProvider.GetRequiredService<IQueryObject<UserDocument>>();
var processor = serviceProvider.GetRequiredService<IQueryRequestProcessor<UserDocument>>();

queryObject.FilterBy(b => b.Eq(x => x.IsActive, true));

var request = new QueryRequest
{
    Page = 0,
    Size = 20,
    Filters =
    [
        new QueryRequestFilter
        {
            Field = "fullName",
            Operator = QueryFilterOperator.Contains,
            Value = "Jane"
        }
    ],
    Sorting =
    [
        new QueryRequestSort
        {
            Field = "email",
            Direction = QuerySortDirection.Asc
        }
    ]
};

var paged = await processor.ProcessAsync(queryObject, request);

QueryRequestMap<T> can be used when external field names should not map directly to document property names.

Aggregation

Razory also supports aggregate pipelines from query objects.

var queryObject = serviceProvider.GetRequiredService<IQueryObject<UserDocument>>();

var aggregate = queryObject
    .FilterBy(b => b.Eq(x => x.IsActive, true))
    .Aggregate();

var items = await aggregate.GetAllAsync();

Dependency Injection

ConfigureRazory() registers Razory services into IServiceCollection, including:

• repository services
• persistence commands
• query object services
• query request processing
• the Razory initializer service

This makes Razory easy to consume from ASP.NET Core or any application already using the default .NET DI container.

Design Notes

Razory is intentionally oriented around typed application code rather than direct collection access.

The current version still exposes MongoDB driver types in parts of the public API, especially around repository update/filter operations and query construction. That is the current design state of the project, not a hidden implementation detail.

Collection index definitions are now modeled explicitly in Razory through CollectionIndexDefinition<T>, while their translation to MongoDB is kept internal to the library.

Roadmap Direction

The project is currently moving toward:

• continued cleanup of public abstractions
• stronger initialization and infrastructure ergonomics
• future support for additional Mongo-specific index types such as search indexes and vector search indexes
• better separation between Razory abstractions and MongoDB driver types where that separation provides real value

Status

Razory is an infrastructure library under active evolution. The current API is usable, but some areas are still being shaped, especially initialization, index management, and MongoDB abstraction boundaries.

If you adopt it, treat it as a focused application data-access library rather than a fully stabilized persistence platform.