Routing

Gestiona la navegación y el enrutamiento en el cliente para aplicaciones de una sola página (SPA). Ofrece un control completo sobre el historial del navegador mediante la API de History, soporte para parámetros dinámicos y opcionales, ordenación de rutas basada en especificidad, middleware en cadena síncrono/asíncrono, desestructuración automática de parámetros de consulta (query strings) y control robusto de errores.

Librería: estructura.routing.js

1. Inicialización y Ciclo de Vida Global

El sistema de enrutamiento se gestiona directamente a través de la instancia global única _routing, la cual expone todos los métodos de configuración y control de ciclo de vida.

• _routing.start(options?): Activa el enrutador y comienza a escuchar eventos en la ventana (window).
  
  Opciones de Configuración:
  • click (Boolean): Intercepta automáticamente clics en enlaces locales de tipo ancla (<a>) evitando la recarga de página (por defecto, true).
  • popstate (Boolean): Escucha los cambios de historial cuando el usuario retrocede o avanza en el navegador (por defecto, true).
  • dispatch (Boolean): Ejecuta de forma inmediata el análisis y correspondencia de la ruta de la dirección actual al arrancar (por defecto, true).
• 
  _routing.stop(): Detiene el enrutador y elimina todos los escuchadores de eventos globales asociados (clics y popstate).
• 
  _routing.base(path?): Obtiene o establece la ruta base (prefijo) para todo el sistema de enrutamiento (ej. /app). Para establecerla se debe pasar un argumento de tipo string.

2. Registro de Rutas y Middlewares

El enrutador admite la declaración de rutas de manera secuencial invocando directamente la función global _routing. Permite encadenar múltiples controladores (middlewares) utilizando una devolución de llamada (next).

Sintaxis de Registro:

// Rutas con controladores múltiples
_routing('/perfil', authMiddleware, function(ctx) {
	console.log('Ruta de perfil cargada');
});

// Registrar un middleware global para todas las rutas
_routing(function(ctx, next) {
	console.log('Log global para:', ctx.pathname);
	next();
});

3. Parámetros Dinámicos y Coincidencias

El motor de enrutamiento traduce los patrones declarados a expresiones regulares, aislando y asignando parámetros estructurados en el contexto.

• Parámetros Requeridos (:param): Captura cualquier segmento de texto ubicado entre barras diagonales.

  _routing('/usuario/:id', function(ctx) { console.log(ctx.params.id); });

• 
  Parámetros Opcionales (:param?): Permite que el segmento final sea omitido en la ruta de navegación.

  _routing('/blog/:categoria?', function(ctx) { /* ... */ });

• 
  Comodín Global (*): Captura cualquier subruta posterior y lo asigna en el parámetro ctx.params.wildcard.

  _routing('/archivos/*', function(ctx) { /* ... */ });

4. El Objeto de Contexto (Context)

Cada controlador registrado recibe como primer argumento un objeto de contexto que contiene toda la información de la transición actual.

Propiedades del Contexto:

• ctx.canonicalPath (String): La ruta de navegación completa incluyendo la ruta base asignada, parámetros de búsqueda y fragmentos (hash).
• 
  ctx.path (String): Ruta limpia de navegación sin el prefijo de la ruta base (incluye búsqueda y hash).
• 
  ctx.pathname (String): Segmento de ruta pura sin parámetros de búsqueda, hash, ni barras diagonales redundantes al final.
• 
  ctx.querystring (String): Cadena de texto de consulta limpia sin el símbolo de interrogación (?).
• 
  ctx.state (Object): Copia profunda e independiente del objeto de estado asociado a la entrada del historial de navegación.
• 
  ctx.params (Object): Mapa de variables dinámicas extraídas del patrón de la ruta actual (ej. { id: "42" }).
• 
  ctx.query (Object): Parámetros de consulta desestructurados automáticamente. Admite la acumulación de múltiples valores repetidos en forma de arreglos (ej. ?filtro=a&filtro=b se convierte en { filtro: ["a", "b"] }).
• 
  ctx.hash (String): El segmento de ancla de la URL omitiendo el carácter inicial (#).
• 
  ctx.routePath (String): El patrón original registrado que coincidió con la dirección actual.

Métodos del Contexto:

• ctx.pushState(): Escribe el estado actual y la ruta en el historial del navegador.
• 
  ctx.save(): Reemplaza la entrada actual de navegación en el historial con el estado modificado.

5. Navegación Programática y Redirecciones

Permite disparar cambios en la navegación desde código, controlando la actualización del historial y la ejecución de callbacks.

• _routing.show(path, state?, dispatch?, push?): Navega a la ruta indicada creando un nuevo registro en el historial.
• 
  _routing.replace(path, state?, dispatch?, replace?): Navega a la ruta indicada sobrescribiendo el registro del historial de navegación actual.
• 
  _routing.redirect(from, to) o _routing.redirect(to): Configura una regla de redirección o ejecuta una redirección inmediata de forma asíncrona mediante microtareas.

  // Redirección programada
  _routing.redirect('/inicio', '/');
  
  // Redirección inmediata dentro de un controlador
  _routing('/obsoleto', function(ctx) {
  	_routing.redirect('/');
  });
  

6. Control de Errores y Desvinculación

Proporciona herramientas de control para administrar fallas durante la ejecución de los controladores y limpiar registros existentes de memoria.

• _routing.onError(callback?): Registra un manejador global que intercepta errores lanzados durante la ejecución de la cadena de controladores de rutas. Si se invoca sin argumentos, devuelve una copia superficial del arreglo de escuchadores de errores registrados.
• 
  _routing.offError(callback?): Desvincula un manejador de errores específico o vacía todos los registros de error existentes si se omite el argumento.
• 
  _routing.off(path?, callback?): Desvincula de forma granular un callback de una ruta, borra un patrón completo, o limpia la colección de rutas registradas si se invoca sin argumentos.

7. Características Técnicas