JavaScript de Cero a Experto / Asincronía II

Reto: buscador de países con API real

Reto45 min100 XP

El examen final de la asincronía: una app de búsqueda contra una API pública REAL (REST Countries), con estados de carga, errores bien tratados, cancelación de búsquedas viejas y datos formateados a la colombiana. Cuando termines, habrás construido el patrón que está detrás de todo buscador que hayas usado en internet.

Reto

Buscador de países

Difícil40 min100 XP(×2 sin mirar la solución)

Qué debes construir

El usuario escribe un país, envía, y la app muestra su información — así se ve tras buscar "colombia" (vista previa estática de la META; en tu versión los datos llegan de la API):

<h1>Buscador de países</h1>
<form id="buscador">
<input id="pais" placeholder="País (en inglés)..." value="colombia" />
<button>Buscar</button>
</form>
<p id="estado"></p>
<div id="resultado">
<h2 id="nombre">🇨🇴 Colombia</h2>
<p id="capital">Capital: Bogotá</p>
<p id="poblacion">Población: 50.882.891</p>
<p id="moneda">Moneda: Colombian peso (COP)</p>
</div>

body { font-family: system-ui; padding: 24px; background: #0b1120; color: #f1f5f9; }
h1 { font-size: 24px; margin: 0 0 14px; }
form { display: flex; gap: 8px; }
input { padding: 10px 14px; border: 1px solid #2a3752; border-radius: 8px; background: #151e31; color: #f1f5f9; flex: 1; max-width: 260px; }
input:focus { outline: 2px solid #7c3aed; }
button { padding: 10px 18px; border: 0; border-radius: 8px; background: #6d28d9; color: white; font-weight: 600; cursor: pointer; }
#estado { color: #94a3b8; min-height: 22px; margin: 10px 0 4px; }
#resultado h2 { font-size: 20px; margin: 6px 0; }
#resultado p { margin: 4px 0; color: #cbd5e1; }

La API: https://restcountries.com/v3.1/name/NOMBRE (agrega ?fields=name,translations,capital,population,flag,currencies para pedir solo lo necesario). Responde un ARRAY de coincidencias — usarás la primera. Pruébala en el navegador con "colombia" antes de programar: mirar el JSON real es el primer paso de todo trabajo con APIs.

Requisitos:

Helper cargarJSON(url, opciones) — fetch + chequeo de response.ok + throw + .json(), el de la lección 6. TODA petición pasa por él.
Búsqueda por formulario: submit + preventDefault, input con trim (vacío = no buscar), y la query dentro de la URL pasada por encodeURIComponent.
Los tres estados en el DOM: "Buscando..." mientras carga; el resultado en éxito; el error en su lugar (#estado). El HTML trae los 4 renglones del resultado (#nombre, #capital, #poblacion, #moneda) — se llenan con textContent.
Datos con sus trampas dominadas: nombre en español (translations.spa?.common, con el común en inglés de respaldo vía ??), bandera (el campo flag es el emoji — va junto al nombre), capital (capital?.[0], es un array), población con Intl.NumberFormat("es-CO"), y moneda: currencies es un objeto cuya CLAVE no conoces de antemano — Object.keys al rescate (muestra nombre y código).
404 amigable: si la API responde 404 (país no encontrado), el estado muestra un mensaje humano que sugiera intentar en inglés — no "HTTP 404".
Cancelación: cada búsqueda nueva ABORTA la anterior en vuelo (AbortController + signal); y un AbortError JAMÁS se muestra como error — esa búsqueda ya no le importa a nadie.

Reglas

Cero innerHTML (el texto viene de una API: mismo trato que un usuario).
async/await + try/catch — este módulo se rinde con su sintaxis.
La población SOLO la formatea Intl.
Patrón iniciar para esperar el DOM.
Nota honesta: la API busca por nombre en inglés o nativo — prueba colombia, peru, chile, japan, france, brazil. Y la población puede diferir de la vista previa: son datos vivos.

40:00

Cuando estés listo, arranca el reloj.

Las cuatro decisiones que hacen profesional este buscador:

Un helper para todas las peticiones. cargarJSON concentra la trampa de response.ok: el resto del código solo conoce dos mundos — datos buenos o excepción — y el try/catch queda limpio.
Desconfiar de la forma de los datos. Array de coincidencias, capital-array, moneda con clave desconocida, traducción que puede faltar: cada acceso lleva su protección (?., ??, Object.keys). Con APIs ajenas, el optional chaining no es elegancia — es supervivencia.
Los estados viven en un solo flujo. El try abre con "Buscando...", el éxito pinta, el catch traduce (404 → humano, resto → genérico). Nunca hay dos verdades en pantalla.
La cancelación protege la VERDAD de la pantalla. Sin abort, dos búsquedas rápidas pueden llegar en desorden y la vieja pisar a la nueva. Abortar la anterior + ignorar AbortError garantiza que lo que se ve corresponde a lo último que el usuario pidió.

Autoevaluación de gala: ¿"colombia" pinta bandera, nombre en español, Bogotá, población con puntos de miles y "Colombian peso (COP)"? ¿un país inventado ("wakanda") muestra tu mensaje amigable y NO "HTTP 404"? ¿dos búsquedas seguidas rapidísimas terminan mostrando SIEMPRE la segunda? ¿desconectar el wifi produce el error genérico (esa es la otra familia de fallo — la que fetch sí rechaza solo)? ¿ni un innerHTML a la vista? Si todo es sí, dilo con todas las letras: consumiste una API real con manejo de errores, estados y cancelación — el estándar profesional completo.

Qué sigue

Diez módulos: el lenguaje entero, el DOM, los eventos y ahora la asincronía con APIs reales. Lo que viene es un cambio de sombrero: el módulo 11 entra a la PROGRAMACIÓN ORIENTADA A OBJETOS en JavaScript — prototipos sin miedo, clases, herencia y los secretos de this que quedaron pendientes desde el módulo 5. La forma en que se organizan las piezas grandes.