DataMagic.Abstractions 1.2.0

DataMagic.Abstractions

DataMagic.Abstractions is a small .NET Standard 2.1 library of shared contracts and models for querying and updating data: filters, sorting, paging, search results, entity interfaces and partial updates.

It contains no query logic and no database driver. Filters and pagers only describe a request; your data access layer (EF Core, Dapper, MongoDB, ...) reads them and builds the actual query.

Installation

dotnet add package DataMagic.Abstractions

Contents

Constants

PagerKinds

String values that identify a pager type. Each pager exposes one through IPager.Kind, so you can tell pagers apart after they cross an API boundary.

Enums

An operator left unset takes the enum's first member. For the numeric, date and date-time operators that is SmallerThan, not None, so always set the operator explicitly.

Filters

Each filter pairs a value with the operator to apply. Range filters combine two filters into a lower and an upper bound.

using DataMagic.Abstractions.Constants.Operators;
using DataMagic.Abstractions.Models;
using DataMagic.Abstractions.Models.Filters;

var name = new TextFilter { Value = "linh", Mode = TextFilterModes.Contains };

var price = new NumericRangeFilter<decimal, decimal>(
    new NumericFilter<decimal>(10m, NumericComparisonOperators.GreaterThanEqualTo),
    new NumericFilter<decimal>(50m, NumericComparisonOperators.SmallerThan));

var birthday = new DateRangeFilter
{
    From = new DateFilter
    {
        Value = new Date(2000, 1, 1),
        Operator = DateComparisonOperators.GreaterThanEqualTo
    }
};

var createdTime = new DateTimeRangeFilter(
    new DateTimeFilter(new DateTime(2026, 1, 1), DateTimeComparisonOperators.GreaterThanEqualTo),
    new DateTimeFilter("2026-02-01", DateTimeComparisonOperators.SmallerThan));

NumericFilter<T>.ValidNumericTypes() returns the supported numeric types and their nullable forms. The constructor does not currently reject other types, so check T yourself if it comes from outside your code.

Your query layer applies the filter, for example:

if (name.Value != null && name.Mode == TextFilterModes.Contains)
    query = query.Where(x => x.Name.Contains(name.Value));

Sorting

SortableProperty names a property and the direction to sort it in.

using DataMagic.Abstractions.Constants;
using DataMagic.Abstractions.Models;

var sort = new SortableProperty { Name = "createdTime", Direction = SortDirections.Descending };

Paging

IPager tells your data access layer what to fetch:

All pagers throw ArgumentException on out-of-range input.

using DataMagic.Abstractions.Interfaces;
using DataMagic.Abstractions.Models.Pagers;

IPager firstPage = new DefaultPager(1, 20);
IPager secondPage = new IndexPager(1, 20, true, true);
IPager offset = new SkipLimitPager(40, 20);

// Count only, without fetching items.
IPager countOnly = new DefaultPager(1, 20, false, true);

DefaultPager and SkipLimitPager query and count by default. IndexPager does neither unless you say so: new IndexPager(0, 20) returns false from both ShouldItemsQueried() and ShouldItemsCounted(), so pass both flags as shown above.

Use the pager in your query, for example:

var totalRecords = pager.ShouldItemsCounted() ? await query.CountAsync() : 0;

var items = pager.ShouldItemsQueried()
    ? await query.Skip((int)pager.GetSkippedRecords()).Take((int)pager.GetTotalRecords()).ToListAsync()
    : new List<Product>();

Search results

ISearchResult<T> and its implementation SearchResult<T> hold one page of Items and the TotalRecords matching the query. A null item sequence becomes an empty array.

using DataMagic.Abstractions.Interfaces;
using DataMagic.Abstractions.Models;

ISearchResult<Product> result = new SearchResult<Product>(items, totalRecords);

var product = result.FirstOrDefault();

Entities

TId and TTime are generic, so you choose the key and time types.

using DataMagic.Abstractions.Interfaces;

public class AuditLog : IImmutableEntity<Guid, DateTime>
{
    public Guid Id { get; init; }

    public DateTime CreatedTime { get; init; }
}

public class Product : IMutableEntity<Guid, DateTime>
{
    public Guid Id { get; init; }

    public DateTime CreatedTime { get; init; }

    public DateTime UpdatedTime { get; set; }
}

The init accessor needs .NET 5 or later. On older targets use set instead.

UpdatedTime is declared as TTime?, but C# only makes that nullable when TTime is a reference type. With DateTime it is a plain DateTime, so an entity that was never updated holds default(DateTime) rather than null.

Partial updates

IUpdatableProperty<T> and its implementation UpdatableProperty<T> pair a Value with a HasModified flag. This separates "leave this field alone" from "set this field to null", which a plain nullable property cannot do.

using DataMagic.Abstractions.Models;

public class UpdateProductModel
{
    public UpdatableProperty<string?>? Description { get; set; }
}

var model = new UpdateProductModel
{
    Description = new UpdatableProperty<string?>(null, true)
};

if (model.Description?.HasModified == true)
    product.Description = model.Description.Value;

Database options

IDatabaseOptions describes how to reach a database with separate fields instead of a connection string. Your data access layer builds the driver's connection settings from them.

Each class implements IDatabaseOptions directly. To support another database, implement the interface yourself.

All members except Type are settable, so the classes bind from configuration:

{
  "Databases": {
    "Mongo": {
      "Host": "mongo.internal",
      "Username": "asset-service",
      "Password": "<from secret store>",
      "DatabaseName": "assets"
    }
  }
}

using DataMagic.Abstractions.Models.Databases;

var mongo = builder.Configuration.GetSection("Databases:Mongo").Get<MongoDatabaseOptions>()!;

Then map the fields to the driver, for example with MongoDB.Driver:

var settings = new MongoClientSettings
{
    Server = new MongoServerAddress(mongo.Host, mongo.Port),
    UseTls = mongo.UseTls,
    ReplicaSetName = mongo.ReplicaSet
};

if (mongo.Username != null)
    settings.Credential = MongoCredential.CreateCredential(
        mongo.AuthenticationDatabase, mongo.Username, mongo.Password);

var database = new MongoClient(settings).GetDatabase(mongo.DatabaseName);

Date

Date is a date without a time, intended for values received from a front end.

using DataMagic.Abstractions.Models;

var date = new Date(2026, 11, 2);

DateTime midnight = date.ToDateTime();
DateTime withTime = date.ToDateTime(14, 30, 0);

var isLater = date > new Date(2026, 1, 1);
var isSame = date.Equals(new Date(2026, 11, 2));

• The constructor throws Exception for a year before 1753, or for an invalid month or day.
• Derive from Date and override IsValidYear, IsValidMonth or IsValidDate to change the rules.
• Use Equals to compare dates. The == and != operators currently overflow the stack and terminate the process.
• >, >=, < and <= work but throw NullReferenceException if either side is null.
• Date does not override GetHashCode, so do not use it as a dictionary key or in a HashSet.
• Validation treats every fourth year as a leap year, so new Date(1900, 2, 29) is accepted and fails later when converted to a DateTime.