¿Por qué JSDoc y no TypeScript?

Porque el archivo sigue siendo JavaScript. Con `checkJs` activado, el compilador de TypeScript lee estos typedefs y te da los mismos errores en el editor, sin compilación, sin extensión `.ts`, sin transpilador. Para un script de Node o una biblioteca pequeña que se publica tal cual, es todo el beneficio de los tipos y nada de su coste.

¿Cómo uso el typedef generado?

Referéncialo por su nombre: `/** @type {Root} */` en una variable, o `@param {Root} payload` en una función. Si los typedefs viven en otro archivo, impórtalos con `/** @typedef {import("./types.js").Root} Root */`: el editor los resuelve igual.

JSON a JSDoc — autocompletado en JS a secas

Convierte una muestra JSON en typedefs JSDoc. Cada objeto pasa a ser un @typedef con nombre que tu editor lee, en JavaScript a secas, sin paso de build.

Instantáneo Privado Cero cookies

Nombre raíz

Entrada JSON

Salida JSDoc

Qué hace esta herramienta

Una muestra JSON pasa a ser typedefs de JSDoc, un bloque por objeto.

{ "id": 1, "name": "Ada", "address": { "city": "Paris" } }

/**
 * @typedef {Object} Root
 * @property {number} id
 * @property {string} name
 * @property {Address} address
 */

/**
 * @typedef {Object} Address
 * @property {string} city
 */

Ponlos al principio de un archivo .js y cada @type {Root} de ese archivo queda comprobado: por tu editor, y por tsc --checkJs si lo ejecutas.

Una lista en la raíz también recibe nombre

/**
 * @typedef {Array<UsersItem>} Users
 */

Ese bloque faltaba: una muestra en array producía solo el typedef del elemento, y el nombre raíz que habías puesto no iba a ninguna parte. Era un defecto real, encontrado al escribir esta página y corregido.

Los arrays se escriben siempre Array<…> y no …[]. Ambas formas valen; la larga sigue siendo legible cuando el tipo del elemento es una unión o un *.

Una clave que no es un identificador

{ "content-type": "text/html" }

 * @property {string} "content-type"

Las comillas mantienen la clave legible, y no son JSDoc estándar: no existe sintaxis para un nombre de propiedad que no sea un identificador válido. Se dice en vez de callarse: nada en la salida te avisará, y un editor puede sencillamente ignorar esa línea. Una clave así conviene renombrarla en el origen.

Lo que una muestra no puede decidir

Cada propiedad se documenta como presente, porque es lo que el documento mostraba. JSDoc anota una opcional @property {string} [name] y una anulable {?string}: dos retoques que se hacen conociendo la API, no hechos contenidos en una sola carga.

Un valor desconocido pasa a *, el «cualquier tipo» de JSDoc. Aparece donde la muestra calla: un array vacío da Array<*>.

Privado por diseño

Todo se ejecuta localmente en tu navegador con JavaScript. Tus datos nunca se suben a un servidor, lo que hace que la herramienta sea segura para contenido sensible y funcione sin conexión.

Preguntas frecuentes

¿Por qué JSDoc y no TypeScript?: Porque el archivo sigue siendo JavaScript. Con `checkJs` activado, el compilador de TypeScript lee estos typedefs y te da los mismos errores en el editor, sin compilación, sin extensión `.ts`, sin transpilador. Para un script de Node o una biblioteca pequeña que se publica tal cual, es todo el beneficio de los tipos y nada de su coste.
Una clave con guion salió entrecomillada. ¿Es válido?: No del todo, y es el límite honesto de esta salida. `@property {string} "content-type"` mantiene la clave legible, pero JSDoc no tiene sintaxis para un nombre de propiedad que no sea un identificador: las comillas no vienen de ninguna especificación. Conviene renombrar esa clave en el origen, o documentarla en prosa al lado.
¿Cómo uso el typedef generado?: Referéncialo por su nombre: `/** @type {Root} */` en una variable, o `@param {Root} payload` en una función. Si los typedefs viven en otro archivo, impórtalos con `/** @typedef {import("./types.js").Root} Root */`: el editor los resuelve igual.