Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Orbis25/FoundationKit/llms.txt

Use this file to discover all available pages before exploring further.

IMapRepository is FoundationKit’s AutoMapper-aware repository interface. Where IBaseRepository<TModel> works directly with entity types, IMapRepository accepts strongly-typed input DTOs (TInputModel), edit DTOs (TEditModel), and projects query results directly to output DTOs (TDtoModel) — keeping your controllers and service layer completely free of entity types. Every operation accepts or returns the appropriate DTO, and AutoMapper handles all translation between the wire layer and the database layer transparently. This design means your API endpoints never need to reference EF Core entity classes. Input validation, serialization, and persistence concerns are each confined to their own models, and the repository interface enforces those boundaries at compile time through its generic constraints.

​
Interface Variants

FoundationKit ships two related interfaces in FoundationKit.Repository.Interfaces:
InterfaceType ParametersPurpose
IMapRepository<TInputModel, TEditModel, TDtoModel>3Standard CRUD operations over DTOs
IMapRepository<T, TInputModel, TEditModel, TDtoModel>4Extends the 3-param variant — adds GetEntities and UpdatePartialEntityAsync for direct entity access
The 4-parameter form inherits all 3-parameter members and adds two methods that expose the underlying TEntity (T) for scenarios where you need to drop down to raw entity manipulation (e.g., partial updates or complex bulk queries).

​
Generic Constraints

// 3-parameter variant
public interface IMapRepository<TInputModel, TEditModel, TDtoModel>
    where TDtoModel   : BaseOutput
    where TInputModel : BaseInput
    where TEditModel  : BaseEdit

// 4-parameter extended variant
public interface IMapRepository<T, TInputModel, TEditModel, TDtoModel>
    : IMapRepository<TInputModel, TEditModel, TDtoModel>
    where TDtoModel   : BaseOutput
    where TInputModel : BaseInput
    where TEditModel  : BaseEdit
    where T           : BaseModel
  • TInputModel : BaseInput — The DTO used for create operations. BaseInput is an empty marker class; derive from it and add your create-specific properties.
  • TEditModel : BaseEdit — The DTO used for update operations. BaseEdit carries [JsonIgnore] audit fields (Id, CreatedAt, CreatedBy, etc.) so the client cannot overwrite them.
  • TDtoModel : BaseOutput — The read-side DTO returned by all query methods. BaseOutput exposes Id, CreatedAt, CreatedAtStr, and CreatedBy.
  • T : BaseModel — The EF Core entity (4-parameter variant only). Used by GetEntities and UpdatePartialEntityAsync.

​
Methods

​
GetPaginatedList

Returns a single page of projected TDtoModel results. Filtering and ordering expressions are written against TDtoModel properties, not the raw entity. 
Task<PaginationResult<TDtoModel>> GetPaginatedList(
    Paginate paginate,
    Expression<Func<TDtoModel, bool>>? expression = default,
    Expression<Func<TDtoModel, object>>? ordered = default,
    CancellationToken cancellationToken = default,
    params Expression<Func<TDtoModel, object>>[] includes);
​
paginate
Paginate
required
Pagination parameters: Page (1-based), Qyt (items per page), OrderByDesc (sort direction), NoPaginate (return all results without paging), and Query (free-text token for optional use in your expression).
​
expression
Expression<Func<TDtoModel, bool>>?
default:"null"
Optional filter predicate applied against the projected DTO query before Skip/Take.
​
ordered
Expression<Func<TDtoModel, object>>?
default:"null"
Optional DTO property selector for ordering. Defaults to CreatedAt when null.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation from the calling HTTP request or background job.
​
includes
params Expression<Func<TDtoModel, object>>[]
Navigation-property selectors for eager loading.
​
PaginationResult<TDtoModel>
Task
Contains ActualPage, Qyt, PageTotal, Total, and Results (IReadOnlyCollection<TDtoModel>).

​
GetList

Returns a fully materialised list of TDtoModel instances matching the optional predicate, without pagination. 
Task<IEnumerable<TDtoModel>> GetList(
    Expression<Func<TDtoModel, bool>>? expression = default,
    bool orderDesc = true,
    Expression<Func<TDtoModel, object>>? ordered = default,
    CancellationToken cancellationToken = default,
    params Expression<Func<TDtoModel, object>>[] includes);
​
expression
Expression<Func<TDtoModel, bool>>?
default:"null"
Optional filter predicate. Pass null to retrieve all rows.
​
orderDesc
bool
default:"true"
true for descending order; false for ascending.
​
ordered
Expression<Func<TDtoModel, object>>?
default:"null"
Property selector for ordering. Falls back to CreatedAt when null.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
includes
params Expression<Func<TDtoModel, object>>[]
Navigation properties for eager loading.
​
IEnumerable<TDtoModel>
Task
An in-memory collection of projected DTOs. For a composable query, use GetAll instead.

​
GetAll

Returns a composable IQueryable<TDtoModel> that projects entity data via AutoMapper’s ProjectTo. No data is fetched until the query is enumerated. 
IQueryable<TDtoModel> GetAll(
    Expression<Func<TDtoModel, bool>>? expression = default,
    bool orderDesc = true,
    Expression<Func<TDtoModel, object>>? ordered = default,
    params Expression<Func<TDtoModel, object>>[] includes);
​
expression
Expression<Func<TDtoModel, bool>>?
default:"null"
Optional Where filter on the projected DTO query.
​
orderDesc
bool
default:"true"
Sort direction.
​
ordered
Expression<Func<TDtoModel, object>>?
default:"null"
Optional sort-property selector.
​
includes
params Expression<Func<TDtoModel, object>>[]
Navigation properties for eager loading.
​
IQueryable<TDtoModel>
IQueryable
A deferred, AutoMapper-projected query. Chain further LINQ operators or call .ToListAsync() to execute.

​
Create

Maps a TInputModel to the underlying entity, persists it in a transaction, and returns the saved record as a TDtoModel. 
Task<TDtoModel?> Create(TInputModel model, CancellationToken cancellationToken = default);
​
model
TInputModel
required
The input DTO carrying the data for the new entity. Must derive from BaseInput. AutoMapper translates it to the entity before insertion.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
TDtoModel?
Task
The persisted record projected back to TDtoModel, including any database-assigned values such as Id and CreatedAt.

​
Update

Maps a TEditModel to the underlying entity and persists the update. Two overloads are available: one that exposes the verifyEntity flag, and a convenience overload that omits it (equivalent to calling the full overload with verifyEntity: false). When verifyEntity is true, the repository fetches the current DTO first to preserve CreatedBy and CreatedAt audit fields. 
// Full overload — controls the pre-fetch behaviour
Task<TDtoModel?> Update(TEditModel model, CancellationToken cancellationToken = default, bool verifyEntity = true);

// Convenience overload — equivalent to verifyEntity: false
Task<TDtoModel?> Update(TEditModel model, CancellationToken cancellationToken = default);
​
model
TEditModel
required
The edit DTO with updated field values. Must derive from BaseEdit. The Id property on BaseEdit identifies which record to update.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
verifyEntity
bool
default:"true"
When true, performs a GetById before updating to copy immutable audit fields (CreatedBy, CreatedAt) from the existing record onto the edit model. Set to false to skip the pre-fetch if you have pre-populated those fields yourself. The two-parameter convenience overload always behaves as if verifyEntity is false.
​
TDtoModel?
Task
The updated record as TDtoModel, or null if verifyEntity is true and no matching row was found.

​
GetById

Fetches a single entity by primary key (Guid) and projects it to TDtoModel. 
Task<TDtoModel?> GetById(
    Guid id,
    bool asNotTraking = false,
    CancellationToken cancellationToken = default,
    params Expression<Func<TDtoModel, object>>[] includes);
​
id
Guid
required
The primary key of the record to fetch.
​
asNotTraking
bool
default:"false"
When true, the query is executed with AsNoTracking(). Useful for read-only operations to reduce EF Core overhead.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
includes
params Expression<Func<TDtoModel, object>>[]
Navigation properties to include on the projected DTO query.
​
TDtoModel?
Task
The projected DTO, or null if no record with the given Id exists.

​
SoftRemove

Performs a logical delete by fetching the DTO, mapping it back to the entity, setting IsDeleted = true, and persisting the update. 
Task<bool> SoftRemove(Guid id, CancellationToken cancellationToken = default);
​
id
Guid
required
Primary key of the entity to soft-delete.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
bool
Task
true if the record was found and soft-deleted; false if no entity with the given Id was found.

​
Remove

Permanently deletes the entity from the database. The record is fetched as a DTO, mapped back to the entity, then removed. 
Task<bool> Remove(Guid id, CancellationToken cancellationToken = default);
​
id
Guid
required
Primary key of the entity to delete.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
bool
Task
true if the record was found and removed; false otherwise.

​
Exist

Checks whether any projected TDtoModel matches the given predicate. 
Task<bool> Exist(
    Expression<Func<TDtoModel, bool>>? expression = default,
    CancellationToken cancellationToken = default);
​
expression
Expression<Func<TDtoModel, bool>>?
default:"null"
Filter predicate. When null, the method returns false (unlike IBaseRepository.ExistAsync which returns true for any row when the expression is null).
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
bool
Task
true when at least one projected DTO matches the expression; false otherwise, including when no expression is provided.

​
GetOneAsync

Returns the first projected TDtoModel matching the predicate, or null when nothing matches. 
Task<TDtoModel?> GetOneAsync(
    Expression<Func<TDtoModel, bool>> expression,
    CancellationToken cancellationToken = default);
​
expression
Expression<Func<TDtoModel, bool>>
required
Filter predicate applied to the projected DTO query.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
TDtoModel?
Task
The first matching DTO, or null.

​
Count

Counts the number of projected DTOs that satisfy all supplied predicates. 
Task<int> Count(
    CancellationToken cancellationToken = default,
    params Expression<Func<TDtoModel, bool>>[] expression);
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
expression
params Expression<Func<TDtoModel, bool>>[]
Zero or more filter predicates that are ANDed together. Passing none counts all rows.
​
int
Task
Row count satisfying all predicates.

​
CommitAndResultAsync

Flushes all pending EF Core change-tracker mutations within a database transaction and returns null on success, or an error message string on failure. The transaction is automatically rolled back if an exception is caught. 
Task<string?> CommitAndResultAsync(CancellationToken cancellationToken = default);
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
string?
Task
null on a successful commit; the base exception message string if the transaction failed.

​
GetEntities (extended interface only)

Returns a raw IQueryable<T> over the underlying entity set. Available only on IMapRepository<T, TInputModel, TEditModel, TDtoModel>. 
IQueryable<T> GetEntities(Expression<Func<T, bool>>? expression = null);
​
expression
Expression<Func<T, bool>>?
default:"null"
Optional filter applied directly to the entity DbSet. Pass null to get an unfiltered entity queryable.
​
IQueryable<T>
IQueryable
A deferred, untracked entity query. Useful when you need entity-level access not available through the DTO projection.

​
UpdatePartialEntityAsync (extended interface only)

Attaches an entity and marks only the listed properties as Modified, producing a targeted UPDATE statement. Available only on IMapRepository<T, TInputModel, TEditModel, TDtoModel>. 
Task UpdatePartialEntityAsync(
    T entity,
    List<Expression<Func<T, object?>>> updateExpression,
    CancellationToken cancellationToken = default);
​
entity
T
required
The entity to partially update. Must have its Id property set.
​
updateExpression
List<Expression<Func<T, object?>>>
required
Property selectors for each column to include in the UPDATE. Unlisted properties are untouched.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
Task
Task
Completes when SaveChangesAsync has finished.

​
Usage Example

Implement IMapRepository by extending MapRepository<TContext, TEntity, TInputModel, TEditModel, TDtoModel>. 
public class CreatePersonInput : BaseInput
{
    public string FirstName { get; set; } = string.Empty;
    public string LastName  { get; set; } = string.Empty;
    public string Email     { get; set; } = string.Empty;
}

public class EditPersonInput : BaseEdit
{
    public string FirstName { get; set; } = string.Empty;
    public string LastName  { get; set; } = string.Empty;
}

public class PersonDto : BaseOutput
{
    public string FirstName { get; set; } = string.Empty;
    public string LastName  { get; set; } = string.Empty;
    public string Email     { get; set; } = string.Empty;
    public string FullName  => $"{FirstName} {LastName}";
}

Build docs developers (and LLMs) love

Get started for freeTalk to us