theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-kotlin-exposed/SKILL.md

@@ -0,0 +1,724 @@
+---
+name: patrones-kotlin-exposed
+description: Patrones del ORM Exposed de JetBrains — consultas DSL, patrón DAO, transacciones, pooling de conexiones con HikariCP, migraciones con Flyway y patrón repositorio.
+---
+
+# Patrones de Kotlin Exposed
+
+Patrones completos de acceso a datos con el ORM Exposed de JetBrains: consultas DSL, DAO, transacciones y configuración lista para producción.
+
+## Cuándo usarla
+
+- Al montar el acceso a base de datos con Exposed
+- Al escribir consultas SQL con el DSL o el DAO de Exposed
+- Al configurar el pool de conexiones con HikariCP
+- Al crear migraciones de base de datos con Flyway
+- Al implementar el patrón repositorio con Exposed
+- Al manejar columnas JSON y consultas complejas
+
+## Cómo funciona
+
+Exposed ofrece dos estilos de consulta: el DSL para expresiones directas tipo SQL y el DAO para gestionar el ciclo de vida de entidades. HikariCP administra un pool de conexiones reutilizables configurado vía `HikariConfig`. Flyway ejecuta scripts SQL de migración versionados al arrancar para mantener el esquema sincronizado. Todas las operaciones de base de datos corren dentro de bloques `newSuspendedTransaction` para seguridad con corrutinas y atomicidad. El patrón repositorio envuelve las consultas de Exposed tras una interfaz, de modo que la lógica de negocio queda desacoplada de la capa de datos y los tests pueden usar una base H2 en memoria.
+
+## Ejemplos
+
+### Consulta DSL
+
+```kotlin
+suspend fun findUserById(id: UUID): UserRow? =
+    newSuspendedTransaction {
+        UsersTable.selectAll()
+            .where { UsersTable.id eq id }
+            .map { it.toUser() }
+            .singleOrNull()
+    }
+```
+
+### Uso de entidad DAO
+
+```kotlin
+suspend fun createUser(request: CreateUserRequest): User =
+    newSuspendedTransaction {
+        UserEntity.new {
+            name = request.name
+            email = request.email
+            role = request.role
+        }.toModel()
+    }
+```
+
+### Configuración de HikariCP
+
+```kotlin
+val hikariConfig = HikariConfig().apply {
+    driverClassName = config.driver
+    jdbcUrl = config.url
+    username = config.username
+    password = config.password
+    maximumPoolSize = config.maxPoolSize
+    isAutoCommit = false
+    transactionIsolation = "TRANSACTION_READ_COMMITTED"
+    validate()
+}
+```
+
+## Configuración de la base de datos
+
+### Pool de conexiones con HikariCP
+
+```kotlin
+// DatabaseFactory.kt
+object DatabaseFactory {
+    fun create(config: DatabaseConfig): Database {
+        val hikariConfig = HikariConfig().apply {
+            driverClassName = config.driver
+            jdbcUrl = config.url
+            username = config.username
+            password = config.password
+            maximumPoolSize = config.maxPoolSize
+            isAutoCommit = false
+            transactionIsolation = "TRANSACTION_READ_COMMITTED"
+            validate()
+        }
+
+        return Database.connect(HikariDataSource(hikariConfig))
+    }
+}
+
+data class DatabaseConfig(
+    val url: String,
+    val driver: String = "org.postgresql.Driver",
+    val username: String = "",
+    val password: String = "",
+    val maxPoolSize: Int = 10,
+)
+```
+
+### Migraciones con Flyway
+
+```kotlin
+// FlywayMigration.kt
+fun runMigrations(config: DatabaseConfig) {
+    Flyway.configure()
+        .dataSource(config.url, config.username, config.password)
+        .locations("classpath:db/migration")
+        .baselineOnMigrate(true)
+        .load()
+        .migrate()
+}
+
+// Arranque de la aplicación
+fun Application.module() {
+    val config = DatabaseConfig(
+        url = environment.config.property("database.url").getString(),
+        username = environment.config.property("database.username").getString(),
+        password = environment.config.property("database.password").getString(),
+    )
+    runMigrations(config)
+    val database = DatabaseFactory.create(config)
+    // ...
+}
+```
+
+### Archivos de migración
+
+```sql
+-- src/main/resources/db/migration/V1__create_users.sql
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name VARCHAR(100) NOT NULL,
+    email VARCHAR(255) NOT NULL UNIQUE,
+    role VARCHAR(20) NOT NULL DEFAULT 'USER',
+    metadata JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_role ON users(role);
+```
+
+## Definición de tablas
+
+### Tablas estilo DSL
+
+```kotlin
+// tables/UsersTable.kt
+object UsersTable : UUIDTable("users") {
+    val name = varchar("name", 100)
+    val email = varchar("email", 255).uniqueIndex()
+    val role = enumerationByName<Role>("role", 20)
+    val metadata = jsonb<UserMetadata>("metadata", Json.Default).nullable()
+    val createdAt = timestampWithTimeZone("created_at").defaultExpression(CurrentTimestampWithTimeZone)
+    val updatedAt = timestampWithTimeZone("updated_at").defaultExpression(CurrentTimestampWithTimeZone)
+}
+
+object OrdersTable : UUIDTable("orders") {
+    val userId = uuid("user_id").references(UsersTable.id)
+    val status = enumerationByName<OrderStatus>("status", 20)
+    val totalAmount = long("total_amount")
+    val currency = varchar("currency", 3)
+    val createdAt = timestampWithTimeZone("created_at").defaultExpression(CurrentTimestampWithTimeZone)
+}
+
+object OrderItemsTable : UUIDTable("order_items") {
+    val orderId = uuid("order_id").references(OrdersTable.id, onDelete = ReferenceOption.CASCADE)
+    val productId = uuid("product_id")
+    val quantity = integer("quantity")
+    val unitPrice = long("unit_price")
+}
+```
+
+### Tablas compuestas
+
+```kotlin
+object UserRolesTable : Table("user_roles") {
+    val userId = uuid("user_id").references(UsersTable.id, onDelete = ReferenceOption.CASCADE)
+    val roleId = uuid("role_id").references(RolesTable.id, onDelete = ReferenceOption.CASCADE)
+    override val primaryKey = PrimaryKey(userId, roleId)
+}
+```
+
+## Consultas DSL
+
+### CRUD básico
+
+```kotlin
+// Insertar
+suspend fun insertUser(name: String, email: String, role: Role): UUID =
+    newSuspendedTransaction {
+        UsersTable.insertAndGetId {
+            it[UsersTable.name] = name
+            it[UsersTable.email] = email
+            it[UsersTable.role] = role
+        }.value
+    }
+
+// Seleccionar por ID
+suspend fun findUserById(id: UUID): UserRow? =
+    newSuspendedTransaction {
+        UsersTable.selectAll()
+            .where { UsersTable.id eq id }
+            .map { it.toUser() }
+            .singleOrNull()
+    }
+
+// Seleccionar con condiciones
+suspend fun findActiveAdmins(): List<UserRow> =
+    newSuspendedTransaction {
+        UsersTable.selectAll()
+            .where { (UsersTable.role eq Role.ADMIN) }
+            .orderBy(UsersTable.name)
+            .map { it.toUser() }
+    }
+
+// Actualizar
+suspend fun updateUserEmail(id: UUID, newEmail: String): Boolean =
+    newSuspendedTransaction {
+        UsersTable.update({ UsersTable.id eq id }) {
+            it[email] = newEmail
+            it[updatedAt] = CurrentTimestampWithTimeZone
+        } > 0
+    }
+
+// Eliminar
+suspend fun deleteUser(id: UUID): Boolean =
+    newSuspendedTransaction {
+        UsersTable.deleteWhere { UsersTable.id eq id } > 0
+    }
+
+// Mapeo de filas
+private fun ResultRow.toUser() = UserRow(
+    id = this[UsersTable.id].value,
+    name = this[UsersTable.name],
+    email = this[UsersTable.email],
+    role = this[UsersTable.role],
+    metadata = this[UsersTable.metadata],
+    createdAt = this[UsersTable.createdAt],
+    updatedAt = this[UsersTable.updatedAt],
+)
+```
+
+### Consultas avanzadas
+
+```kotlin
+// Consultas con join
+suspend fun findOrdersWithUser(userId: UUID): List<OrderWithUser> =
+    newSuspendedTransaction {
+        (OrdersTable innerJoin UsersTable)
+            .selectAll()
+            .where { OrdersTable.userId eq userId }
+            .orderBy(OrdersTable.createdAt, SortOrder.DESC)
+            .map { row ->
+                OrderWithUser(
+                    orderId = row[OrdersTable.id].value,
+                    status = row[OrdersTable.status],
+                    totalAmount = row[OrdersTable.totalAmount],
+                    userName = row[UsersTable.name],
+                )
+            }
+    }
+
+// Agregación
+suspend fun countUsersByRole(): Map<Role, Long> =
+    newSuspendedTransaction {
+        UsersTable
+            .select(UsersTable.role, UsersTable.id.count())
+            .groupBy(UsersTable.role)
+            .associate { row ->
+                row[UsersTable.role] to row[UsersTable.id.count()]
+            }
+    }
+
+// Subconsultas
+suspend fun findUsersWithOrders(): List<UserRow> =
+    newSuspendedTransaction {
+        UsersTable.selectAll()
+            .where {
+                UsersTable.id inSubQuery
+                    OrdersTable.select(OrdersTable.userId).withDistinct()
+            }
+            .map { it.toUser() }
+    }
+
+// LIKE y coincidencia de patrones — escapa siempre la entrada del usuario para prevenir inyección de comodines
+private fun escapeLikePattern(input: String): String =
+    input.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+suspend fun searchUsers(query: String): List<UserRow> =
+    newSuspendedTransaction {
+        val sanitized = escapeLikePattern(query.lowercase())
+        UsersTable.selectAll()
+            .where {
+                (UsersTable.name.lowerCase() like "%${sanitized}%") or
+                    (UsersTable.email.lowerCase() like "%${sanitized}%")
+            }
+            .map { it.toUser() }
+    }
+```
+
+### Paginación
+
+```kotlin
+data class Page<T>(
+    val data: List<T>,
+    val total: Long,
+    val page: Int,
+    val limit: Int,
+) {
+    val totalPages: Int get() = ((total + limit - 1) / limit).toInt()
+    val hasNext: Boolean get() = page < totalPages
+    val hasPrevious: Boolean get() = page > 1
+}
+
+suspend fun findUsersPaginated(page: Int, limit: Int): Page<UserRow> =
+    newSuspendedTransaction {
+        val total = UsersTable.selectAll().count()
+        val data = UsersTable.selectAll()
+            .orderBy(UsersTable.createdAt, SortOrder.DESC)
+            .limit(limit)
+            .offset(((page - 1) * limit).toLong())
+            .map { it.toUser() }
+
+        Page(data = data, total = total, page = page, limit = limit)
+    }
+```
+
+### Operaciones por lotes
+
+```kotlin
+// Inserción por lotes
+suspend fun insertUsers(users: List<CreateUserRequest>): List<UUID> =
+    newSuspendedTransaction {
+        UsersTable.batchInsert(users) { user ->
+            this[UsersTable.name] = user.name
+            this[UsersTable.email] = user.email
+            this[UsersTable.role] = user.role
+        }.map { it[UsersTable.id].value }
+    }
+
+// Upsert (insertar o actualizar en conflicto)
+suspend fun upsertUser(id: UUID, name: String, email: String) {
+    newSuspendedTransaction {
+        UsersTable.upsert(UsersTable.email) {
+            it[UsersTable.id] = EntityID(id, UsersTable)
+            it[UsersTable.name] = name
+            it[UsersTable.email] = email
+            it[updatedAt] = CurrentTimestampWithTimeZone
+        }
+    }
+}
+```
+
+## Patrón DAO
+
+### Definición de entidades
+
+```kotlin
+// entities/UserEntity.kt
+class UserEntity(id: EntityID<UUID>) : UUIDEntity(id) {
+    companion object : UUIDEntityClass<UserEntity>(UsersTable)
+
+    var name by UsersTable.name
+    var email by UsersTable.email
+    var role by UsersTable.role
+    var metadata by UsersTable.metadata
+    var createdAt by UsersTable.createdAt
+    var updatedAt by UsersTable.updatedAt
+
+    val orders by OrderEntity referrersOn OrdersTable.userId
+
+    fun toModel(): User = User(
+        id = id.value,
+        name = name,
+        email = email,
+        role = role,
+        metadata = metadata,
+        createdAt = createdAt,
+        updatedAt = updatedAt,
+    )
+}
+
+class OrderEntity(id: EntityID<UUID>) : UUIDEntity(id) {
+    companion object : UUIDEntityClass<OrderEntity>(OrdersTable)
+
+    var user by UserEntity referencedOn OrdersTable.userId
+    var status by OrdersTable.status
+    var totalAmount by OrdersTable.totalAmount
+    var currency by OrdersTable.currency
+    var createdAt by OrdersTable.createdAt
+
+    val items by OrderItemEntity referrersOn OrderItemsTable.orderId
+}
+```
+
+### Operaciones DAO
+
+```kotlin
+suspend fun findUserByEmail(email: String): User? =
+    newSuspendedTransaction {
+        UserEntity.find { UsersTable.email eq email }
+            .firstOrNull()
+            ?.toModel()
+    }
+
+suspend fun createUser(request: CreateUserRequest): User =
+    newSuspendedTransaction {
+        UserEntity.new {
+            name = request.name
+            email = request.email
+            role = request.role
+        }.toModel()
+    }
+
+suspend fun updateUser(id: UUID, request: UpdateUserRequest): User? =
+    newSuspendedTransaction {
+        UserEntity.findById(id)?.apply {
+            request.name?.let { name = it }
+            request.email?.let { email = it }
+            updatedAt = OffsetDateTime.now(ZoneOffset.UTC)
+        }?.toModel()
+    }
+```
+
+## Transacciones
+
+### Soporte de transacciones suspendidas
+
+```kotlin
+// Bien: usa newSuspendedTransaction para soporte de corrutinas
+suspend fun performDatabaseOperation(): Result<User> =
+    runCatching {
+        newSuspendedTransaction {
+            val user = UserEntity.new {
+                name = "Alice"
+                email = "alice@example.com"
+            }
+            // Todas las operaciones de este bloque son atómicas
+            user.toModel()
+        }
+    }
+
+// Bien: transacciones anidadas con savepoints
+suspend fun transferFunds(fromId: UUID, toId: UUID, amount: Long) {
+    newSuspendedTransaction {
+        val from = UserEntity.findById(fromId) ?: throw NotFoundException("Usuario $fromId no encontrado")
+        val to = UserEntity.findById(toId) ?: throw NotFoundException("Usuario $toId no encontrado")
+
+        // Débito
+        from.balance -= amount
+        // Crédito
+        to.balance += amount
+
+        // Ambas operaciones triunfan o ambas fallan
+    }
+}
+```
+
+### Aislamiento de transacciones
+
+```kotlin
+suspend fun readCommittedQuery(): List<User> =
+    newSuspendedTransaction(transactionIsolation = Connection.TRANSACTION_READ_COMMITTED) {
+        UserEntity.all().map { it.toModel() }
+    }
+
+suspend fun serializableOperation() {
+    newSuspendedTransaction(transactionIsolation = Connection.TRANSACTION_SERIALIZABLE) {
+        // Nivel de aislamiento más estricto para operaciones críticas
+    }
+}
+```
+
+## Patrón repositorio
+
+### Definición de la interfaz
+
+```kotlin
+interface UserRepository {
+    suspend fun findById(id: UUID): User?
+    suspend fun findByEmail(email: String): User?
+    suspend fun findAll(page: Int, limit: Int): Page<User>
+    suspend fun search(query: String): List<User>
+    suspend fun create(request: CreateUserRequest): User
+    suspend fun update(id: UUID, request: UpdateUserRequest): User?
+    suspend fun delete(id: UUID): Boolean
+    suspend fun count(): Long
+}
+```
+
+### Implementación con Exposed
+
+```kotlin
+class ExposedUserRepository(
+    private val database: Database,
+) : UserRepository {
+
+    override suspend fun findById(id: UUID): User? =
+        newSuspendedTransaction(db = database) {
+            UsersTable.selectAll()
+                .where { UsersTable.id eq id }
+                .map { it.toUser() }
+                .singleOrNull()
+        }
+
+    override suspend fun findByEmail(email: String): User? =
+        newSuspendedTransaction(db = database) {
+            UsersTable.selectAll()
+                .where { UsersTable.email eq email }
+                .map { it.toUser() }
+                .singleOrNull()
+        }
+
+    override suspend fun findAll(page: Int, limit: Int): Page<User> =
+        newSuspendedTransaction(db = database) {
+            val total = UsersTable.selectAll().count()
+            val data = UsersTable.selectAll()
+                .orderBy(UsersTable.createdAt, SortOrder.DESC)
+                .limit(limit)
+                .offset(((page - 1) * limit).toLong())
+                .map { it.toUser() }
+            Page(data = data, total = total, page = page, limit = limit)
+        }
+
+    override suspend fun search(query: String): List<User> =
+        newSuspendedTransaction(db = database) {
+            val sanitized = escapeLikePattern(query.lowercase())
+            UsersTable.selectAll()
+                .where {
+                    (UsersTable.name.lowerCase() like "%${sanitized}%") or
+                        (UsersTable.email.lowerCase() like "%${sanitized}%")
+                }
+                .orderBy(UsersTable.name)
+                .map { it.toUser() }
+        }
+
+    override suspend fun create(request: CreateUserRequest): User =
+        newSuspendedTransaction(db = database) {
+            UsersTable.insert {
+                it[name] = request.name
+                it[email] = request.email
+                it[role] = request.role
+            }.resultedValues!!.first().toUser()
+        }
+
+    override suspend fun update(id: UUID, request: UpdateUserRequest): User? =
+        newSuspendedTransaction(db = database) {
+            val updated = UsersTable.update({ UsersTable.id eq id }) {
+                request.name?.let { name -> it[UsersTable.name] = name }
+                request.email?.let { email -> it[UsersTable.email] = email }
+                it[updatedAt] = CurrentTimestampWithTimeZone
+            }
+            if (updated > 0) findById(id) else null
+        }
+
+    override suspend fun delete(id: UUID): Boolean =
+        newSuspendedTransaction(db = database) {
+            UsersTable.deleteWhere { UsersTable.id eq id } > 0
+        }
+
+    override suspend fun count(): Long =
+        newSuspendedTransaction(db = database) {
+            UsersTable.selectAll().count()
+        }
+
+    private fun ResultRow.toUser() = User(
+        id = this[UsersTable.id].value,
+        name = this[UsersTable.name],
+        email = this[UsersTable.email],
+        role = this[UsersTable.role],
+        metadata = this[UsersTable.metadata],
+        createdAt = this[UsersTable.createdAt],
+        updatedAt = this[UsersTable.updatedAt],
+    )
+}
+```
+
+## Columnas JSON
+
+### JSONB con kotlinx.serialization
+
+```kotlin
+// Tipo de columna personalizado para JSONB
+inline fun <reified T : Any> Table.jsonb(
+    name: String,
+    json: Json,
+): Column<T> = registerColumn(name, object : ColumnType<T>() {
+    override fun sqlType() = "JSONB"
+
+    override fun valueFromDB(value: Any): T = when (value) {
+        is String -> json.decodeFromString(value)
+        is PGobject -> {
+            val jsonString = value.value
+                ?: throw IllegalArgumentException("El valor de PGobject es nulo para la columna '$name'")
+            json.decodeFromString(jsonString)
+        }
+        else -> throw IllegalArgumentException("Valor inesperado: $value")
+    }
+
+    override fun notNullValueToDB(value: T): Any =
+        PGobject().apply {
+            type = "jsonb"
+            this.value = json.encodeToString(value)
+        }
+})
+
+// Uso en una tabla
+@Serializable
+data class UserMetadata(
+    val preferences: Map<String, String> = emptyMap(),
+    val tags: List<String> = emptyList(),
+)
+
+object UsersTable : UUIDTable("users") {
+    val metadata = jsonb<UserMetadata>("metadata", Json.Default).nullable()
+}
+```
+
+## Testing con Exposed
+
+### Base de datos en memoria para tests
+
+```kotlin
+class UserRepositoryTest : FunSpec({
+    lateinit var database: Database
+    lateinit var repository: UserRepository
+
+    beforeSpec {
+        database = Database.connect(
+            url = "jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;MODE=PostgreSQL",
+            driver = "org.h2.Driver",
+        )
+        transaction(database) {
+            SchemaUtils.create(UsersTable)
+        }
+        repository = ExposedUserRepository(database)
+    }
+
+    beforeTest {
+        transaction(database) {
+            UsersTable.deleteAll()
+        }
+    }
+
+    test("crea y encuentra un usuario") {
+        val user = repository.create(CreateUserRequest("Alice", "alice@example.com"))
+
+        user.name shouldBe "Alice"
+        user.email shouldBe "alice@example.com"
+
+        val found = repository.findById(user.id)
+        found shouldBe user
+    }
+
+    test("findByEmail devuelve null para un email desconocido") {
+        val result = repository.findByEmail("unknown@example.com")
+        result.shouldBeNull()
+    }
+
+    test("la paginacion funciona correctamente") {
+        repeat(25) { i ->
+            repository.create(CreateUserRequest("User $i", "user$i@example.com"))
+        }
+
+        val page1 = repository.findAll(page = 1, limit = 10)
+        page1.data shouldHaveSize 10
+        page1.total shouldBe 25
+        page1.hasNext shouldBe true
+
+        val page3 = repository.findAll(page = 3, limit = 10)
+        page3.data shouldHaveSize 5
+        page3.hasNext shouldBe false
+    }
+})
+```
+
+## Dependencias de Gradle
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    // Exposed
+    implementation("org.jetbrains.exposed:exposed-core:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-dao:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-jdbc:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-kotlin-datetime:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-json:1.0.0")
+
+    // Driver de base de datos
+    implementation("org.postgresql:postgresql:42.7.5")
+
+    // Pool de conexiones
+    implementation("com.zaxxer:HikariCP:6.2.1")
+
+    // Migraciones
+    implementation("org.flywaydb:flyway-core:10.22.0")
+    implementation("org.flywaydb:flyway-database-postgresql:10.22.0")
+
+    // Testing
+    testImplementation("com.h2database:h2:2.3.232")
+}
+```
+
+## Referencia rápida: patrones de Exposed
+
+| Patrón | Descripción |
+|--------|-------------|
+| `object Table : UUIDTable("name")` | Definir tabla con clave primaria UUID |
+| `newSuspendedTransaction { }` | Bloque de transacción seguro para corrutinas |
+| `Table.selectAll().where { }` | Consulta con condiciones |
+| `Table.insertAndGetId { }` | Insertar y devolver el ID generado |
+| `Table.update({ condición }) { }` | Actualizar filas coincidentes |
+| `Table.deleteWhere { }` | Eliminar filas coincidentes |
+| `Table.batchInsert(items) { }` | Inserción masiva eficiente |
+| `innerJoin` / `leftJoin` | Unir tablas |
+| `orderBy` / `limit` / `offset` | Ordenar y paginar |
+| `count()` / `sum()` / `avg()` | Funciones de agregación |
+
+**Recuerda**: usa el estilo DSL para consultas simples y el estilo DAO cuando necesites gestionar el ciclo de vida de entidades. Usa siempre `newSuspendedTransaction` para soporte de corrutinas, y envuelve las operaciones de base de datos tras una interfaz de repositorio para facilitar el testing.
+
+## Skills relacionadas
+
+- `patrones-kotlin-ktor`
+- `corrutinas-flows-kotlin`
+- `migraciones-bd`