create-repository

Use this skill when creating ROM Repositories that encapsulate domain-level persistence logic in Hanami 2.x.

---

Quick Reference

---

Core Rules

1. Create the Repository file: Place repositories under app/repos/:

   # app/repos/user_repo.rb
   module MyApp
     module Repos
       class UserRepo < Hanami::DB::Repo[:users]
       end
     end
   end

2. Inject into Actions: Inject repositories using the container dependency injection (Deps):

   # app/actions/users/index.rb
   class Index < MyApp::Action
     include Deps["repos.user_repo"]
   
     def handle(request, response)
       response.render(view, users: user_repo.all)
     end
   end

3. Add domain methods: Write specific read and write methods to isolate your actions from raw relation access:

   def active
     users.active.to_a
   end
   
   def find_by_email(email)
     users.by_email(email).one
   end

4. Use transactions for multi-step writes: Wrap mutations in transaction blocks. For details and Failure result handling, see REPOSITORIES.md.

   transaction do
     accounts.update(from_id, balance: from_account.balance - amount)
     accounts.update(to_id,   balance: to_account.balance + amount)
   end

5. Map to custom Entities: Configure the struct_namespace to automatically map SQL relation rows to custom Entity domain models. See REPOSITORIES.md.

   class UserRepo < Hanami::DB::Repo[:users]
     struct_namespace MyApp::Entities
     auto_struct true
   end

6. Do not expose Relations directly: Actions must fetch and modify data via Repositories. Bypassing repositories to query relations directly in actions/views is an anti-pattern.

---

Integration