skills.rest
machenjie
machenjieCOMMUNITY
Explore all skills by this author →
GitHub

repository-persistence

Define repository interfaces that isolate domain contracts from ORM storage mechanics.

4|Updated May 16, 2026
Search Tags:#domain modeling#repository pattern#transaction boundaries#error translation#orm leakage prevention#pagination contract#not-found semantics
One-click install
npx skills add https://github.com/machenjie/rd-skills --skill repository-persistence
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: repository-persistence
Source: https://github.com/machenjie/rd-skills/tree/main/src/foundation/capabilities/repository-persistence
Command: npx skills add https://github.com/machenjie/rd-skills --skill repository-persistence

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It prevents persistence-layer details (ORM objects, query builders, lazy-loading behavior, and raw storage exceptions) from leaking into your domain and application logic, keeping your models stable while your database technology changes.

Core Features & Use Cases

  • Repository boundary discipline: define repository interfaces in domain/application language and keep storage mechanics behind the implementation.
  • No ORM leakage rules: ensure repository inputs/outputs are domain objects or plain DTOs, not ORM entities, proxies, or query-builder types.
  • Explicit semantics for correctness: document not-found outcomes (missing vs soft-deleted/filtered), query contracts (pagination, ordering, consistency), and transaction participation (ambient vs caller-provided vs new transactions).
  • Error translation: map storage exceptions (e.g., unique constraint violations) into domain/application-meaningful outcomes instead of propagating raw ORM/database errors.
  • Use Case: you add a new repository method for an aggregate root but need consistent not-found behavior, pagination guarantees, and reliable transactional participation across multiple repository calls.

Quick Start

Use repository-persistence when you need to redesign or document a repository contract so it clearly defines mapping, not-found behavior, transaction scope, query semantics, and error translation without exposing ORM details.

Frequently Asked Questions about repository-persistence

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent ORM objects and query builders from leaking into my domain logic?▼

To prevent ORM leakage, define repository interfaces using domain-language contracts and plain DTOs, ensuring repository inputs and outputs never expose ORM entities, proxies, or query-builder types across the persistence boundary.

How should I handle not-found semantics and soft-deleted records in a repository pattern?▼

Handling not-found semantics requires explicitly documenting whether a missing result indicates a truly absent record or a soft-deleted and filtered entity, clarifying query contracts and consistency for correct repository behavior.

What is the best way to define transaction boundaries for multiple repository calls?▼

Defining transaction boundaries involves setting explicit transactional expectations, specifying whether repository methods participate in ambient transactions, accept caller-provided transactions, or initiate new transactions for multi-call consistency.

How do I translate storage exceptions like unique constraint violations into domain outcomes?▼

Translating storage exceptions requires mapping raw database errors, such as unique constraint violations, into domain or application-meaningful outcomes instead of propagating ORM-specific exceptions across the repository boundary.

How do I standardize pagination and ordering contracts across multiple repository methods?▼

Standardizing pagination and ordering involves establishing consistent query contracts that explicitly define pagination guarantees, ordering semantics, and consistency rules for every repository method handling aggregate roots.

When do I need to redesign a repository contract to isolate domain contracts from storage mechanics?▼

You need to redesign a repository contract when adding methods for an aggregate root that require consistent not-found behavior, reliable transactional participation, and explicit error mapping without exposing storage details.

Related Skills

Explore More Software Engineering Skills→
AGIBuildAGIBuild
10

dotnet-domain-modeling

Implement Domain-Driven Design tactical patterns in C# for domain models.

Community
Advanced
nettenette
41

nette-database

Map database tables to typed Row entities in Nette Database with Explorer.

Official
Advanced
marquesfelipmarquesfelip

tenant-aware-query-design

Ensure tenant-scoped queries include a tenant_id filter across SQL and ORM layers.

Community
Advanced
HeldinhowHeldinhow
4

dotnet-cqrs

Implement CQRS in .NET with MediatR for separate read and write operations.

Community
Intermediate