Cómo probar filtros jq complejos en el navegador sin arriesgar filtrar datos de producción

¿Cuántas veces has tenido que armar una expresión jq larga a ciegas directamente en la terminal? Este es un escenario familiar para muchos: haces una solicitud a una API, obtienes una pared de texto de un par de miles de líneas, y luego presionas repetidamente la flecha hacia arriba en la consola, agregando pipes, selectores y slices. ¿Cometiste un error en un corchete? La terminal escupe un error o un array vacío.

El primer pensamiento en tal situación es abrir algún formateador en línea. Pero si estás trabajando con logs de producción, respuestas de pagos, o datos personales de usuarios, pegarlos en un sitio aleatorio de los resultados de búsqueda no es una opción.

El equipo de desarrollo de jq resolvió este problema de forma nativa al lanzar un sandbox oficial llamado playground. El código fuente está disponible en GitHub bajo la licencia MIT, y una versión funcional está accesible en play.jqlang.org.

Qué es

El proyecto es un shell web interactivo para trabajar con jq. En el lado izquierdo de la pantalla pegas el JSON fuente o lo traes mediante URL, escribes el filtro en la parte superior, y en la derecha obtienes instantáneamente el resultado de la transformación.

La característica principal está bajo el capó. Todo el análisis y la ejecución del filtro ocurren localmente en tu máquina. El servicio no envía tu cuerpo JSON a un servidor remoto.

Esto fue posible gracias al puerto jq-wasm — el código C original de la utilidad fue compilado a WebAssembly. Como resultado, el navegador realiza transformaciones pesadas de forma independiente, sin dependencias nativas del lado del sistema operativo.

Cómo el sandbox es útil en la práctica

A diferencia de docenas de servicios anónimos de origen dudoso, esta herramienta resuelve varias tareas aplicadas a la vez.

Primero, privacidad por defecto. Dado que el procesador se ejecuta dentro de WebAssembly directamente en el cliente, puedes subir de forma segura volcados de bases de datos internas, configuraciones de infraestructura, o volcados de API al sandbox. Las solicitudes de red solo ocurren cuando tú mismo pegas una URL externa para cargar JSON.

Segundo, compartir snippets de forma conveniente. Cuando necesitas mostrarle a un colega cómo analizar correctamente una respuesta complicada de un servicio de terceros, simplemente presiona el botón Share. El servidor guardará el código del filtro y generará un enlace corto. El receptor del enlace tendrá los cálculos ejecutados localmente en su navegador nuevamente.

Tercero, una interfaz responsiva. Gracias a la ausencia de sobrecarga de red para enviar datos de ida y vuelta, el resultado se recalcula sobre la marcha mientras escribes el filtro. Para depurar construcciones complicadas como walk(), descendencias recursivas, o funciones personalizadas, esto ahorra mucho tiempo.

Cuarto, el sandbox puede desplegarse dentro de tu propio perímetro. Si tu empresa opera en un segmento cerrado sin acceso a internet, el proyecto puede iniciarse fácilmente de forma local o en un servidor interno del equipo.

Qué hay dentro: arquitectura y stack

El sandbox está escrito en TypeScript usando Next.js. La estructura de la aplicación es extremadamente concisa:

• Frontend en React con un editor de código e integración de jq-wasm.
• Base de datos PostgreSQL, que se necesita exclusivamente para almacenar snippets compartidos.
• Endpoint de API del lado del servidor (POST /api/jq) que ejecuta solicitudes en el backend a través de un pool de workers.

Un detalle interesante en el código fuente: el pool de workers del lado del servidor para /api/jq está estrechamente acoplado a la RAM disponible en la instancia. Dado que las instancias de WebAssembly en Node.js son intensivas en memoria, la aplicación calcula automáticamente el límite de hilos basado en la cantidad de RAM. Por ejemplo, en una instancia con 512 MB de memoria, se lanzarán exactamente 2 hilos paralelos, y la cola máxima será de 40 tareas.

Si es necesario, estos parámetros pueden ser sobrescritos mediante variables de entorno:

# Максимальное число параллельных потоков jq
JQ_POOL_MAX_THREADS=4

# Максимальный размер очереди запросов
JQ_POOL_MAX_QUEUE=80

Si la cola se desborda, la API devuelve honestamente el estado HTTP 429 Too Many Requests, protegiendo al servicio de fallar debido a Out of Memory.

Cómo desplegar el proyecto localmente

Si no quieres usar hosting público o necesitas tu propia instancia dentro de una red corporativa, el inicio tomará un par de minutos.

Necesitarás Node.js versión 14 o superior y Docker (para la base de datos).

Clona el repositorio:

git clone https://github.com/jqlang/playground
cd playground

La forma más rápida para desarrollo local y pruebas es ejecutar el Docker Compose listo para usar, que levantará la aplicación junto con una instancia local de PostgreSQL:

docker compose up

Después del inicio, abre tu navegador en http://localhost:3000.

Para construir una versión de producción sin contenedores, los comandos estándar son suficientes:

npm run build
npm run start

La única variable de entorno requerida para producción es DATABASE_URL con la cadena de conexión de PostgreSQL. Si la funcionalidad de generación de enlaces no es necesaria, las otras configuraciones pueden dejarse en sus valores por defecto.

A quién le será útil

El proyecto vale la pena marcarlo para cualquiera que frecuentemente lidie con código de infraestructura, logs en Kubernetes, pipelines de CI/CD, o APIs REST complejas.

El sandbox elimina la necesidad de escribir scripts bash improvisados solo para verificar la sintaxis de una sola línea de filtro. Y la capacidad de levantar tu propia instancia en dos comandos lo convierte en un excelente candidato para agregar al toolkit interno de un equipo de desarrollo.