Codificador / decodificador URL

Qué es percent-encoding y por qué existe

Las URLs nacieron en 1994 con un alfabeto restringido: solo letras ASCII, dígitos, y unos pocos caracteres especiales con significado estructural (/, ?, &, =, #). Cualquier otra cosa (un espacio, una tilde, un emoji) tiene que ser representada de otra forma para que el navegador y el servidor la transmitan sin ambigüedad. Ese mecanismo se llama percent-encoding o URL encoding, y está definido en el RFC 3986.

La regla básica

Cada byte que no es seguro en una URL se reemplaza por % seguido de los dos dígitos hexadecimales que representan ese byte. Un espacio (byte 0x20) se vuelve %20. Una ñ en UTF-8 son dos bytes (0xC3 0xB1) y se codifica como %C3%B1. La codificación opera sobre bytes, no sobre caracteres, lo que hace que el resultado dependa del encoding (UTF-8 es el estándar de facto desde hace 20 años).

encodeURI vs encodeURIComponent

• encodeURI: respeta la estructura de la URL. No codifica / ? & = # :. Sirve cuando recibís una URL completa con caracteres especiales en el path y querés que siga siendo navegable.
• encodeURIComponent: codifica agresivamente. Codifica / ? & = # : también. Sirve para valores que van dentro de un parámetro (después de un =) y no deben confundirse con la estructura.

Casos típicos

• Construir URLs dinámicamente. Si juntás ?q= + búsqueda del usuario, esa búsqueda tiene que pasar por encodeURIComponent. Si el usuario buscó "café & tortas", sin codificar el browser interpreta el & como inicio de un nuevo parámetro.
• Enviar a APIs REST. Lo mismo: cualquier valor que viaje en un query string debe codificarse.
• Decodificar lo que recibís. Cuando leés req.query en un backend, los frameworks suelen decodificar automáticamente, pero si trabajás con la URL cruda, hay que decodificar a mano.
• UTM y tracking. Si una campaña tiene tildes en el medium o el campaign, se codifican; si no, los analíticos las pierden.

Caracteres reservados

El RFC 3986 define dos grupos. Los reservados tienen significado estructural: : / ? # [ ] @ ! $ & ' ( ) * + , ; =. Los no reservados son siempre seguros: letras, dígitos, - _ . ~. Todo lo demás se debe codificar. encodeURIComponent codifica todos los reservados; encodeURI deja intactos los que tienen significado estructural en URLs.

Errores comunes

• Codificar dos veces. %20 se vuelve %2520. Si el servidor decodifica una sola vez, queda %20 literal.
• Olvidarse del + en query strings. Algunos sistemas codifican espacio como + (legado de application/x-www-form-urlencoded). Asegurate de saber con cuál estás trabajando.
• Codificar dominios. Los hostnames con caracteres no ASCII usan IDN (punycode), no percent-encoding. café.com se vuelve xn--caf-dma.com, no caf%C3%A9.com.