JSON a TypeScript Interface

Sobre el Generador JSON a TypeScript

Genera interfaces TypeScript estrictas e idiomáticas desde cualquier muestra JSON. Útil cuando necesitas tipar respuestas API, configurar entradas tRPC, validar datos localStorage o migrar un codebase JavaScript a TypeScript sin escribir cada forma a mano.

El generador infiere tipos desde valores, maneja objetos anidados, construye sub-interfaces nombradas, fusiona formas de elementos de array, soporta campos nullable y ofrece tres estilos de declaración: tipos estrictos, fallbacks nullable o todos opcionales.

¿Por qué generar interfaces TypeScript desde JSON en lugar de escribirlas a mano?

Tres razones pragmáticas. Primero, precisión bajo cambio — cuando una API devuelve una respuesta real, la interface generada coincide con la forma actual, incluyendo cada nombre de campo, tipo y punto nullable que podrías olvidar a mano. Segundo, velocidad — una respuesta API de 200 campos que toma 30 minutos tipar manualmente se genera en un solo pegado. Tercero, consistencia entre equipos — varios desarrolladores escribiendo la misma interface desde docs API invariablemente discrepan sobre campos opcionales, casing y formas anidadas. Advertencias: los tipos generados se bloquean en los datos de muestra que proporcionaste, así que un campo presente solo en algunas respuestas se tipa como requerido cuando debería ser opcional.

¿Cómo maneja la herramienta objetos anidados, arrays de objetos y arrays de tipos mixtos?

Los objetos anidados se convierten en sus propias interfaces nombradas, derivadas del nombre del campo (camelCase o snake_case se convierte en PascalCase: address → Address, user_profile → UserProfile). Si un nombre colisiona con una interface existente que tiene forma diferente, la herramienta agrega un número (Address, Address2). Arrays de primitivos se convierten en T[] donde T es el tipo de elemento inferido. Arrays de objetos se convierten en Item[] donde Item es una interface generada que fusiona todos los campos a través de elementos del array. Arrays de tipos mixtos se convierten en tipos unión: (string | number | boolean)[]. Los arrays vacíos por defecto son unknown[].

¿Cuál es la diferencia entre interface y type aliases, y cuál debería usar?

Funcionalmente similares para formas de objeto, pero con diferencias clave. Las interfaces soportan declaration merging — declarar interface User { name: string } dos veces y TypeScript las fusiona. Esto es útil para extender tipos de terceros. Los type aliases no soportan merging — la redeclaración es un error. Las interfaces se pueden extender vía sintaxis extends; los tipos se componen vía intersección (&) y unión (|). Los type aliases pueden hacer alias de tipos no-objeto (type ID = string | number) y uniones primitivas. Rendimiento: idéntico para tipos de objeto en TypeScript moderno. Convención en 2026: la mayoría de equipos prefieren interface para contratos API públicos y type para tipos utilitarios, uniones y tipos computados.

¿Cómo manejo campos que a veces son null, a veces un valor, en APIs reales?

Las APIs reales devuelven null para campos que aún no tienen valor (lastLogin: null cuando el usuario nunca ha iniciado sesión). El modo estricto de TypeScript requiere que manejes esto explícitamente. Tres patrones ofrecidos por este generador: (1) Tipos estrictos — si el valor de muestra es null, el tipo se vuelve null literalmente. (2) Marcar null como nullable — los campos null se vuelven T | null donde T es unknown. (3) Todos los campos opcionales — cada campo se vuelve opcional, lo cual es demasiado permisivo. Mejor práctica de producción: generar desde una respuesta donde el campo tenga un valor real, luego editar manualmente el tipo a T | null donde sabes que el campo a veces es null.

¿Puedo generar tipos directamente desde una respuesta API o tengo que pegar JSON cada vez?

Esta herramienta requiere que pegues JSON manualmente — corre completamente en tu navegador sin acceso a la red, así que no puede fetch desde tu API. Flujo de trabajo previsto: usa DevTools del navegador o una herramienta como Postman / Insomnia / Hoppscotch para capturar una respuesta API real, copia el cuerpo JSON, pega en esta herramienta, copia la salida TypeScript, pega en tu codebase. Para generación automatizada desde endpoints en vivo, usa una herramienta del lado del servidor: quicktype (CLI), paquete json-to-ts npm para generación programática, o herramientas schema-first como OpenAPI Generator. Para apps TypeScript full-stack, tRPC elimina el round-trip completamente.

¿Cómo manejo tipos TypeScript para APIs que cambian con el tiempo o tienen esquemas versionados?

Los tipos generados capturan un momento en el tiempo, pero las APIs evolucionan — los campos se agregan, deprecan, renombran y eliminan. Tres estrategias para mantener los tipos actuales: (1) Regeneración manual en cambios de esquema — cuando se documenta un cambio API, re-ejecuta el generador con una respuesta fresca. (2) Tipos basados en esquema — si la API proporciona esquemas OpenAPI, GraphQL o Protobuf, genera tipos desde el esquema en lugar de una respuesta; herramientas como openapi-typescript, graphql-codegen y ts-proto manejan el versionado. (3) Validación en tiempo de ejecución — empareja tipos estáticos con validadores de esquema en tiempo de ejecución (Zod, Valibot, ArkType) para que los desajustes de tipo en tiempo de ejecución se vuelvan errores explícitos.

¿Qué hay de malo con usar any para tipar respuestas API — por qué molestarse con interfaces estrictas?

Tipar respuestas API como any es el atajo más común y la fuente más común de bugs en producción en codebases TypeScript. Con any, el compilador acepta user.adddress (typo), user.id.toUppercase (id es un número, no un string) y array[1000].name (podría ser undefined) — todos crashean en tiempo de ejecución, ninguno se atrapa en tiempo de build. Las interfaces estrictas convierten estos a errores de tiempo de compilación que bloquean código malo. La compensación es esfuerzo inicial. El beneficio escala con el tamaño del equipo y codebase. Práctica moderna en 2026: nunca uses any para fronteras de datos externos.

¿La herramienta puede inferir uniones de literales de cadena (enums) y cómo uso readonly o as const?

Sí. Activa la opción Uniones de cadenas (Detectar uniones de cadenas) y el generador inspecciona los campos a través de todos los elementos de un array de objetos; cuando los valores de un campo forman un conjunto pequeño y totalmente enumerable de cadenas distintas, emite una unión de literales en lugar del tipo string suelto — por ejemplo role: 'admin' | 'user' en vez de role: string. Esta es exactamente la protección para la que existe TypeScript estricto: con un tipo string plano, un error como status === 'activ' compila bien y llega a producción, mientras que una unión 'active' | 'inactive' lo convierte en un error de compilación. El control Valores distintos máx. (por defecto 12, limitado a 2-50) fija el corte — los campos con más valores distintos que el límite vuelven a string, ya que campos de alta cardinalidad como ids o nombres no son enums reales. La inferencia solo corre en arrays de objetos, porque un solo objeto da una muestra y un valor nunca puede enumerarse. Tras generar, tienes dos formas idiomáticas de ajustar más: añade el modificador readonly (readonly role: 'admin' | 'user') para que el campo no pueda reasignarse tras la construcción, útil para DTOs de respuesta de API que deben tratarse como inmutables; o, para un objeto de configuración constante en vez de un tipo, añade as const al valor literal (const ROLES = ['admin', 'user'] as const) y deriva la unión con typeof ROLES[number]. Para seguridad en runtime más allá del tiempo de compilación, combina la unión con un validador como z.enum(['admin', 'user']) de Zod para capturar valores inesperados en el límite.

¿Cómo maneja la herramienta JSON muy grande, enteros grandes y cadenas de fecha?

La conversión corre completamente en tu navegador en un solo pegado, así que el rendimiento escala con JSON.parse y el renderizado del DOM — las respuestas de API típicas (decenas de miles de líneas) se convierten al instante, pero las cargas de varios megabytes pueden ser lentas porque se recorre toda la estructura para inferir tipos; para esas, recorta a un subconjunto representativo o usa un CLI como quicktype. Sobre precisión numérica: JSON tiene un único tipo number y JavaScript parsea cada valor numérico como float de 64 bits, así que los enteros más allá de Number.MAX_SAFE_INTEGER (2^53 - 1) pierden precisión en silencio antes de que la herramienta los vea — el tipo generado es number, pero si tu API devuelve ids de 64 bits, el servidor debería enviarlos como cadenas y deberías tiparlos como string, o usar el tipo bigint con un parser que lo preserve. Los campos de fecha y timestamp quedan tipados como string porque valores ISO-8601 como 2026-05-29T00:00:00Z son cadenas JSON, no objetos Date; eso es correcto para el formato de transporte. Convierte a Date en el límite (new Date(dto.createdAt)) y mantén el tipo del DTO como string, o usa un tipo de marca / z.string().datetime() de Zod para distinguir cadenas de fecha del texto ordinario.

¿Cómo se compara este generador con quicktype, json-to-ts y otras herramientas JSON-to-TypeScript?

quicktype es la herramienta open-source más citada con el análisis más profundo: camina a través de múltiples muestras JSON para inferir campos opcionales, tipos unión de respuestas diferentes y formas polimórficas complejas. Es un CLI con playground web, soporta 20+ lenguajes de salida y es la elección correcta para generación de tipos de producción desde datasets grandes o variables. json-to-ts es un paquete npm más pequeño enfocado solo en salida TypeScript. Herramientas en línea como JSON-Type, Transform.tools y esta son convenientes para conversiones únicas sin configuración CLI. El diseño de esta herramienta favorece el uso rápido del navegador: pega, ve la salida al instante, copia al portapapeles, sin llamadas de red externas.