define-entity

Use this skill when defining ROM Structs and Entities in Hanami 2.x.

---

Core Rules

1. Create the Entity file in the app or slice:

   # app/entities/user.rb
   # frozen_string_literal: true
   
   module MyApp
     module Entities
       class User < Hanami::DB::Entity
         attribute :id, Types::Integer
         attribute :email, Types::String
         attribute :first_name, Types::String
         attribute :last_name, Types::String
         attribute :role, Types::String.default("member")
         attribute :created_at, Types::Time
       end
     end
   end

2. Apply dry-types coercion and constraints: Specify attribute types using standard dry-types constraints. For a comprehensive list of type modifiers, constraints, and defaults, see TYPES.md.

   attribute :email, Types::String.constrained(format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.\w+\z/)
   attribute :role, Types::String.default("member")

3. Entities are immutable: Entities cannot be mutated in place. Use #copy to return a new instance with updated attributes:

   updated_user = user.copy(first_name: "Alicia")

4. Equality is value-based: Two entity instances with identical attributes are considered equivalent:

   user1 == user2 # => true if attributes match

5. Register the Entity namespace in Repositories: Wired repositories require mapping directives to output typed Entity classes rather than generic ROM structs:

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

6. Sync Entities with migrations: Keep entity class attributes manually updated with database schema modifications. Verify using the Hanami console or spec suite:

   bundle exec hanami console
   # check MyApp::App[:user_repo].users.first.class.attributes

---

Common Mistakes