Del JSON al Pokémon: DTO y repositorio

src/commonMain/kotlin/com/sebastiannarvaez/pokedex/data/network/dto/PokemonPageDto.kt

package com.sebastiannarvaez.pokedex.data.network.dto
 
import kotlinx.serialization.Serializable
 
// La respuesta del listado, tal cual llega. Es un DTO («objeto de transferencia
// de datos»): describe el JSON, no lo que la app necesita.
// `@Serializable` pide al plugin que genere el código para leerlo.
@Serializable
internal data class PokemonPageDto(
    // Cuántos Pokémon hay en total (1351).
    val count: Int,
    // La dirección de la página siguiente; `null` en la última. Con valor por
    // defecto: si el campo falta, no falla.
    val next: String? = null,
    // Los Pokémon de esta página: solo nombre y dirección.
    val results: List<PokemonRefDto> = emptyList(),
)
 
// Una fila del listado: el nombre y la dirección del detalle.
@Serializable
internal data class PokemonRefDto(
    val name: String,
    // Termina en `/pokemon/25/`: ahí está el identificador.
    val url: String,
) {
    // No viene en el JSON: se calcula cada vez que se lee (es una propiedad
    // con `get()`). Quita la barra final, se queda con lo que hay detrás de la
    // última barra y lo pasa a número (o `null` si no lo es).
    val id: Int?
        get() = url.trimEnd('/').substringAfterLast('/').toIntOrNull()
}

package com.sebastiannarvaez.pokedex.data.network.dto
 
import kotlinx.serialization.json.Json
import kotlin.test.Test
import kotlin.test.assertEquals
 
class PokemonPageDtoTest {
 
    // Un lector de JSON que ignora los campos que la clase no declara: el mismo
    // ajuste que lleva el cliente.
    private val json = Json { ignoreUnknownKeys = true }
 
    @Test
    fun leeElListadoYIgnoraLoQueSobra() {
        // Entre tres comillas (""") cabe un texto de varias líneas con sus propias
        // comillas, tal cual. El campo "sobra" no existe en PokemonPageDto.
        // `trimIndent()` quita la sangría común de todas las líneas.
        val texto = """
            { "count": 1351, "next": null, "sobra": true,
              "results": [ { "name": "bulbasaur", "url": "https://pokeapi.co/api/v2/pokemon/1/" } ] }
        """.trimIndent()
 
        // Convierte el texto en un PokemonPageDto.
        val pagina = json.decodeFromString<PokemonPageDto>(texto)
 
        assertEquals(1351, pagina.count)
        // `single()` devuelve el único elemento de la lista (y falla si hay más o ninguno).
        assertEquals("bulbasaur", pagina.results.single().name)
    }
 
    @Test
    fun elIdentificadorSaleDeLaUrl() {
        // La dirección termina en «/25/»: el 25 es el identificador.
        val pikachu = PokemonRefDto(name = "pikachu", url = "https://pokeapi.co/api/v2/pokemon/25/")
 
        assertEquals(25, pikachu.id)
    }
}

src/commonMain/kotlin/com/sebastiannarvaez/pokedex/data/network/dto/PokemonDetailDto.kt

package com.sebastiannarvaez.pokedex.data.network.dto
 
import kotlinx.serialization.Serializable
 
// El detalle de un Pokémon. La respuesta real pesa 272 KB; aquí solo se
// declaran los campos que la app usa, y `ignoreUnknownKeys` tira el resto.
@Serializable
internal data class PokemonDetailDto(
    val id: Int,
    val name: String,
    // En decímetros, no en metros: PokeAPI mide raro. Con valor por defecto,
    // porque si falta no es motivo para romper la tarjeta.
    val height: Int = 0,
    // En hectogramos.
    val weight: Int = 0,
    // Los tipos, cada uno con su posición (`slot`).
    val types: List<TypeSlotDto> = emptyList(),
)
 
// Un tipo con su posición: el primero (`slot` 1) es el principal.
@Serializable
internal data class TypeSlotDto(
    val slot: Int = 0,
    val type: NamedRefDto,
)
 
// Una referencia con nombre: del recurso solo nos interesa el nombre ("grass").
@Serializable
internal data class NamedRefDto(val name: String)

src/commonMain/kotlin/com/sebastiannarvaez/pokedex/data/network/PokeApi.kt

package com.sebastiannarvaez.pokedex.data.network
 
import com.sebastiannarvaez.pokedex.data.network.dto.PokemonDetailDto
import com.sebastiannarvaez.pokedex.data.network.dto.PokemonPageDto
import io.ktor.client.HttpClient
import io.ktor.client.call.body
import io.ktor.client.request.get
import io.ktor.client.request.parameter
 
// Lo que la app necesita de PokeAPI, en una interfaz. Así las capas de arriba
// dependen de la interfaz, y los tests pueden darles una falsa sin red.
internal interface PokeApi {
    // Una página del listado: `limit` Pokémon a partir del `offset`.
    suspend fun page(limit: Int, offset: Int): PokemonPageDto
 
    // El detalle de un Pokémon por su identificador.
    suspend fun detail(id: Int): PokemonDetailDto
}
 
// La implementación real, con Ktor. Recibe el cliente ya configurado.
internal class KtorPokeApi(private val client: HttpClient) : PokeApi {
 
    override suspend fun page(limit: Int, offset: Int): PokemonPageDto =
        // GET a «pokemon» (se une a la dirección base) …
        client.get("pokemon") {
            // … con `?limit=…&offset=…` añadido a la dirección.
            parameter("limit", limit)
            parameter("offset", offset)
            // `.body()` lee la respuesta y la convierte en un PokemonPageDto.
        }.body()
 
    override suspend fun detail(id: Int): PokemonDetailDto =
        // GET a «pokemon/25», por ejemplo.
        client.get("pokemon/$id").body()
}

src/commonMain/kotlin/com/sebastiannarvaez/pokedex/data/PokemonRepository.kt

package com.sebastiannarvaez.pokedex.data
 
import com.sebastiannarvaez.pokedex.core.AppDispatchers
import com.sebastiannarvaez.pokedex.data.network.PokeApi
import com.sebastiannarvaez.pokedex.domain.Pokemon
import com.sebastiannarvaez.pokedex.domain.PokemonType
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.withContext
 
// Traduce lo que da PokeAPI (DTO) a lo que la app necesita (`Pokemon`).
// Recibe la interfaz `PokeApi`, no Ktor: no sabe de dónde salen los datos.
internal class PokemonRepository(
    private val api: PokeApi,
    // Quién decide en qué hilo corre cada trabajo (lo creaste con las corrutinas).
    private val dispatchers: AppDispatchers,
) {
 
    // Una página de Pokémon ya completos. El listado no trae tipos ni imagen,
    // así que hay que pedir también el detalle de cada uno: son 1 + 20 peticiones.
    suspend fun page(limit: Int, offset: Int): List<Pokemon> = withContext(dispatchers.io) {
        // La petición del listado.
        val pagina = api.page(limit = limit, offset = offset)
 
        // `coroutineScope` abre un alcance que no termina hasta que acaben todas
        // las corrutinas lanzadas dentro; si una falla, cancela las demás.
        coroutineScope {
            pagina.results
                // El identificador sale de la dirección; si no sale, esa fila se descarta.
                .mapNotNull { it.id }
                // Una corrutina por Pokémon, para pedir los veinte detalles a la vez.
                .map { id -> async { pokemon(id) } }
                // Espera a las veinte y junta los resultados, en el mismo orden.
                .awaitAll()
        }
    }
 
    // Un Pokémon completo: pide el detalle y lo traduce al modelo de dominio.
    suspend fun pokemon(id: Int): Pokemon = withContext(dispatchers.io) {
        val detalle = api.detail(id)
        Pokemon(
            id = detalle.id,
            name = detalle.name,
            types = detalle.types
                // Primero el tipo principal (`slot` 1).
                .sortedBy { it.slot }
                // `deApi` devuelve `null` si el tipo no lo conocemos; `mapNotNull`
                // lo descarta en vez de romper la tarjeta.
                .mapNotNull { PokemonType.deApi(it.type.name) },
        )
    }
}

// Una PokeApi de mentira: da los nombres que le pases y apunta cuántas veces
// le piden un detalle (`private set`: solo ella cambia ese contador).
private class FakePokeApi(
    private val nombres: List<String>,
    private val tipos: Map<Int, List<String>> = emptyMap(),
) : PokeApi {
 
    var llamadasAlDetalle = 0
        private set
 
    override suspend fun detail(id: Int): PokemonDetailDto {
        llamadasAlDetalle++
        // … devuelve un DTO con ese id, su nombre y sus tipos.
    }
}
 
// Un AppDispatchers de mentira: los tres trabajos van al mismo dispatcher de prueba.
private class TestDispatchers(private val d: CoroutineDispatcher) : AppDispatchers { /* io, default, main = d */ }
 
// En cada test se usa así: el repositorio real con la API y los dispatchers de mentira.
val repo = PokemonRepository(api, TestDispatchers(StandardTestDispatcher(testScheduler)))

    // La configuración, como interfaz: quien la pida recibe la de verdad.
    single<AppConfig> { DefaultAppConfig() }
    // El cliente HTTP, creado una vez; `get()` le da el AppConfig de arriba.
    single { createHttpClient(get()) }
    // La API de PokeAPI, pedida por su interfaz.
    single<PokeApi> { KtorPokeApi(get()) }
    // El repositorio: recibe la API y los dispatchers, ya registrados.
    single { PokemonRepository(get(), get()) }

MissingKoinDefinitionException: Missing definition for
'[field:'engine' - type:'io.ktor.client.engine.HttpClientEngine']'
in definition '[Singleton: 'io.ktor.client.HttpClient']'.

// antes
pokedexModule.verify()
// después. `extraTypes` declara lo que el grafo no construye pero existe:
// «esto existe, pero no sale de aquí». `HttpClientEngine::class` es «el tipo
// HttpClientEngine» como valor (la clase misma, no un objeto de esa clase).
// Hace falta el import io.ktor.client.engine.HttpClientEngine (Option+Enter).
pokedexModule.verify(extraTypes = listOf(HttpClientEngine::class))