koan-entity-first

Eliminate repository boilerplate with self-persisting Entity<T> for CRUD operations.

4|3|Updated Aug 18, 2025
One-click install
npx skills add https://github.com/sylin-org/koan-framework --skill koan-entity-first
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: koan-entity-first
Source: https://github.com/sylin-org/koan-framework/tree/main/.claude/skills/entity-first
Command: npx skills add https://github.com/sylin-org/koan-framework --skill koan-entity-first

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Traditional data access layers often involve repetitive repository boilerplate, N+1 query problems, and complex manual ID management. This Skill eliminates these issues by making entities self-aware and self-persisting, simplifying data operations.

Core Features & Use Cases

  • Auto GUID v7 IDs: Entities automatically get chronologically sortable, globally unique IDs without manual intervention.
  • Self-Persisting Entities: Use await entity.Save() and await entity.Remove() directly on entity instances, eliminating the need for separate repositories.
  • Efficient Querying: Perform static queries like await Entity.All(), await Entity.Get(id), and await Entity.Query() with LINQ, supporting batch retrieval to prevent N+1 issues.
  • Streaming & Pagination: Handle large datasets efficiently with streaming (AllStream()) and paginate results for web APIs.
  • Use Case: Define a Product entity, then save it with await product.Save(), retrieve it with await Product.Get(id), and query all active products with await Product.Query(p => p.IsActive), all without writing a single repository class.

Quick Start

To create and save a new 'Todo' item: var todo = new Todo { Title = "Buy groceries" }; await todo.Save(); To retrieve it by ID: var loaded = await Todo.Get(todo.Id);

Frequently Asked Questions about koan-entity-first

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

FAQPage Schema
How do I eliminate repository boilerplate and simplify entity persistence?

Entity-first persistence eliminates repository classes by making entities self-persist. Call `await entity.Save()` and `await entity.Remove()` directly on instances, and use static methods like `await Entity.All()` and `await Entity.Get(id)` for queries, reducing boilerplate across SQL, NoSQL, vector, and JSON stores.

Can I use self-persisting entities to prevent N+1 query problems?

Yes. Static query methods like `await Entity.Query()` with LINQ support batch retrieval and streaming via `AllStream()`, eliminating N+1 issues. Pagination is built in for efficient handling of large datasets without manual query optimization.

Do I need to manually manage entity IDs and GUIDs?

No. Entities automatically generate GUID v7 IDs on creation, which are chronologically sortable and globally unique. ID management is handled internally, so you focus on business logic instead of manual ID assignment.

How do I handle streaming and pagination for large datasets?

Use `AllStream()` for streaming large result sets to avoid memory overhead, and leverage built-in pagination support in query methods. These features work provider-agnostically across SQL, NoSQL, vector, and JSON stores.

What's the difference between self-persisting entities and traditional repository patterns?

Self-persisting entities remove the separate repository layer—operations like Save, Remove, and queries are instance or static methods on the entity itself. This reduces code duplication and cognitive overhead while maintaining the same functionality across multiple data store types.

Does entity-first persistence work with batch operations?

Yes. The approach supports batch operations natively, enabling efficient multi-entity saves and queries. Combined with streaming and pagination, batching handles complex data workflows without N+1 query problems or manual transaction management.