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.

IBaseRepository<TModel> is the core interface that establishes the full data-access contract for any entity-based repository in FoundationKit. By programming against this interface rather than a concrete class, your application code stays decoupled from EF Core specifics — swap out the backing store, apply decorators, or mock the interface in unit tests without touching business logic. Every method returns an awaitable Task (or an IQueryable for composable queries), and all async methods accept a CancellationToken so callers can respect request cancellation gracefully. The single generic parameter TModel must derive from BaseModel, which provides the standard audit fields (Id, CreatedAt, UpdatedAt, CreatedBy, UpdatedBy, IsDeleted) that the repository methods rely on internally.

​
Generic Constraint

public interface IBaseRepository<TModel>
    where TModel : BaseModel
TModel must inherit FoundationKit.Domain.Models.BaseModel. This ensures every entity exposes the Id (Guid), IsDeleted, CreatedAt, and CreatedBy properties that several methods depend on for audit-field preservation and soft-delete logic.

​
Methods

​
GetPaginatedListAsync

Returns a single page of results wrapped in a PaginationResult<TModel>, including total record count, total pages, and the actual page items. 
Task<PaginationResult<TModel>> GetPaginatedListAsync(
    Paginate paginate,
    Expression<Func<TModel, bool>>? expression = default,
    Expression<Func<TModel, object>>? ordered = default,
    CancellationToken cancellationToken = default,
    params Expression<Func<TModel, object>>[] includes);
​
paginate
Paginate
required
Pagination settings. Contains Page (1-based page number), Qyt (items per page), OrderByDesc (sort direction), NoPaginate (bypass pagination and return all results), and Query (optional free-text search token your code can use in the expression).
​
expression
Expression<Func<TModel, bool>>?
default:"null"
Optional LINQ predicate to filter the dataset before pagination is applied. Passed directly to a Where clause on the underlying IQueryable.
​
ordered
Expression<Func<TModel, object>>?
default:"null"
Property selector used to order results. When null, ordering falls back to CreatedAt descending (or ascending based on paginate.OrderByDesc).
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation from the calling HTTP request or background job.
​
includes
params Expression<Func<TModel, object>>[]
Zero or more navigation-property selectors applied as EF Core Include calls, enabling eager loading without additional queries.
​
PaginationResult<TModel>
Task
Returns a PaginationResult<TModel> with ActualPage, Qyt, PageTotal, Total, and Results. When NoPaginate is true, only Results is populated (all matching rows) and pagination metadata fields are zero.

​
GetListAsync

Returns the full unpaginated list of matching entities as a materialised IEnumerable<TModel>. 
Task<IEnumerable<TModel>> GetListAsync(
    bool orderDesc = true,
    Expression<Func<TModel, bool>>? expression = default,
    Expression<Func<TModel, object>>? ordered = default,
    CancellationToken cancellationToken = default,
    params Expression<Func<TModel, object>>[] includes);
​
orderDesc
bool
default:"true"
When true (default) results are ordered descending; when false, ascending.
​
expression
Expression<Func<TModel, bool>>?
default:"null"
Optional filter predicate. Pass null to retrieve all records.
​
ordered
Expression<Func<TModel, object>>?
default:"null"
Optional ordering selector. Falls back to CreatedAt when null.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
includes
params Expression<Func<TModel, object>>[]
Navigation-property selectors for eager loading.
​
IEnumerable<TModel>
Task
A fully materialised, in-memory collection of entities. Use GetAll if you need a composable IQueryable instead.

​
GetAll

Returns a composable IQueryable<TModel> that has not yet hit the database. Use this when you need to chain additional LINQ operators before execution. 
IQueryable<TModel> GetAll(
    Expression<Func<TModel, bool>>? expression = default,
    bool orderDesc = true,
    Expression<Func<TModel, object>>? ordered = default,
    params Expression<Func<TModel, object>>[] includes);
​
expression
Expression<Func<TModel, bool>>?
default:"null"
Optional Where predicate.
​
orderDesc
bool
default:"true"
Sort direction. Default ordering property is CreatedAt.
​
ordered
Expression<Func<TModel, object>>?
default:"null"
Optional sort-property selector.
​
includes
params Expression<Func<TModel, object>>[]
Navigation properties for eager loading via EF Core Include.
​
IQueryable<TModel>
IQueryable
A deferred query. Call .ToListAsync(), .FirstOrDefaultAsync(), or further .Where() / .Select() before awaiting.

​
CreateAsync

Adds a new entity to the database inside a transaction and returns the persisted entity (with any database-generated values such as default timestamps populated). 
Task<TModel> CreateAsync(TModel model, CancellationToken cancellationToken = default);
​
model
TModel
required
The fully initialised entity instance to insert. Set all required properties before passing it in; BaseModel audit fields (CreatedAt, CreatedBy) are expected to be set by the caller or EF value generators.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
TModel
Task
The same entity instance, now tracked and reflecting any database-assigned values.

​
UpdateAsync

Updates an existing entity. 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 default on the full overload), the repository first fetches the current entity from the database to preserve the original CreatedBy and CreatedAt audit fields before applying the update. 
// Full overload — controls the pre-fetch behaviour
Task<TModel?> UpdateAsync(TModel model, CancellationToken cancellationToken = default, bool verifyEntity = true);

// Convenience overload — equivalent to verifyEntity: false
Task<TModel?> UpdateAsync(TModel model, CancellationToken cancellationToken = default);
​
model
TModel
required
The entity with updated property values. Must have a valid Id matching an existing row.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
verifyEntity
bool
default:"true"
When true, the repository looks up the existing record first and copies CreatedBy / CreatedAt from it before calling Update. Set to false to skip the pre-fetch if you are certain the audit fields are already correct on the supplied model. The two-parameter convenience overload always behaves as if verifyEntity is false.
​
TModel?
Task
The updated entity, or null if verifyEntity was true and no record with the given Id was found.

​
UpdatePartialEntityAsync

Attaches an entity to the EF Core change tracker and marks only the specified properties as Modified, so that only those columns are included in the generated UPDATE statement. 
Task UpdatePartialEntityAsync(
    TModel entity,
    List<Expression<Func<TModel, object?>>> updateExpression,
    CancellationToken cancellationToken = default);
​
entity
TModel
required
An entity instance (does not need to be tracked). Must have its Id set to target the correct row.
​
updateExpression
List<Expression<Func<TModel, object?>>>
required
A list of property selectors identifying exactly which columns to update. Properties not listed are excluded from the SQL UPDATE.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
Task
Task
Completes when SaveChangesAsync has finished. Does not wrap the save in a full CommitAsync transaction — call CommitAndResultAsync separately if you need transaction semantics.

​
GetByIdAsync

Fetches a single entity by its primary key (Guid), with optional eager loading and change-tracking control. 
Task<TModel?> GetByIdAsync(
    Guid id,
    bool asNotTraking = false,
    CancellationToken cancellationToken = default,
    params Expression<Func<TModel, object>>[] includes);
​
id
Guid
required
The primary key (BaseModel.Id) of the entity to retrieve.
​
asNotTraking
bool
default:"false"
When true, the entity is returned without being added to the EF Core change tracker. Suitable for read-only scenarios where you do not intend to update the entity.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
includes
params Expression<Func<TModel, object>>[]
Navigation properties for eager loading.
​
TModel?
Task
The matched entity, or null when no record with the given Id exists.

​
SoftRemoveAsync

Performs a logical (soft) delete by setting IsDeleted = true on the entity and persisting the change. The row remains in the database and can be restored. 
Task<bool> SoftRemoveAsync(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 when the record was found and updated successfully; false when no entity with the given Id exists.

​
RemoveAsync

Permanently deletes an entity from the database. This operation cannot be undone. 
Task<bool> RemoveAsync(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 if no matching record was found.

​
ExistAsync

Checks whether at least one entity matching the optional predicate exists in the database. 
Task<bool> ExistAsync(
    Expression<Func<TModel, bool>>? expression = default,
    CancellationToken cancellationToken = default);
​
expression
Expression<Func<TModel, bool>>?
default:"null"
Optional filter. When null, returns true if the table contains any rows at all.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
bool
Task
true if at least one matching row exists; otherwise false.

​
GetOneAsync

Returns the first entity matching the given predicate, or null when no match is found. Maps directly to EF Core’s FirstOrDefaultAsync. 
Task<TModel?> GetOneAsync(
    Expression<Func<TModel, bool>> expression,
    CancellationToken cancellationToken = default);
​
expression
Expression<Func<TModel, bool>>
required
Filter predicate. Unlike ExistAsync, this parameter is required.
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
TModel?
Task
The first matching entity, or null.

​
CountAsync

Returns the number of entities that satisfy all supplied predicates. Multiple expressions are ANDed together by successive Where calls. 
Task<int> CountAsync(
    CancellationToken cancellationToken = default,
    params Expression<Func<TModel, bool>>[] expression);
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
expression
params Expression<Func<TModel, bool>>[]
Zero or more filter predicates. Passing no expressions counts all rows in the table.
​
int
Task
The row count satisfying all predicates.

​
CommitAndResultAsync

Saves all pending change-tracker mutations inside a database transaction. Returns null on success or an error message string on failure, instead of throwing — useful when you want to control error handling in the calling layer rather than catching exceptions. 
Task<string?> CommitAndResultAsync(CancellationToken cancellationToken = default);
​
cancellationToken
CancellationToken
default:"default"
Propagates cancellation.
​
string?
Task
null when the transaction committed successfully. The base exception message string when an error occurred (transaction is rolled back automatically).

​
Usage Example

Implement IBaseRepository<TModel> by extending BaseRepository<TContext, TModel>, which provides the complete EF Core-backed implementation out of the box. 
// FoundationKit.Domain.Models
public class Product : BaseModel
{
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public int Stock { get; set; }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us