Por que JSDoc e não TypeScript?

Porque o arquivo continua sendo JavaScript. Com `checkJs` ligado, o compilador do TypeScript lê esses typedefs e devolve os mesmos erros no editor, sem build, sem extensão `.ts`, sem transpilador. Para um script Node ou uma biblioteca pequena publicada como está, é todo o benefício dos tipos e nada do seu custo.

Como uso o typedef gerado?

Referencie-o pelo nome: `/** @type {Root} */` numa variável, ou `@param {Root} payload` numa função. Se os typedefs moram em outro arquivo, importe-os com `/** @typedef {import("./types.js").Root} Root */` — o editor resolve do mesmo jeito.

JSON para JSDoc — autocompletar em JS puro

Transforme uma amostra JSON em typedefs JSDoc. Cada objeto vira um @typedef nomeado que o seu editor lê, em JavaScript puro, sem etapa de build.

Instantâneo Privado Zero cookies

Nome raiz

Entrada JSON

Saída JSDoc

O que esta ferramenta faz

Uma amostra JSON vira typedefs JSDoc, um bloco 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
 */

Coloque-os no topo de um arquivo .js e cada @type {Root} daquele arquivo passa a ser conferido — pelo seu editor, e pelo tsc --checkJs se você o rodar.

Uma lista na raiz também ganha nome

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

Esse bloco faltava: uma amostra em array produzia só o typedef do elemento, e o nome de raiz que você tinha definido não ia a lugar nenhum. Era um defeito real, encontrado ao escrever esta página e corrigido.

Os arrays são sempre escritos Array<…> e não …[]. As duas formas valem; a longa continua legível quando o tipo do elemento é uma união ou um *.

Uma chave que não é identificador

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

 * @property {string} "content-type"

As aspas mantêm a chave legível, e não são JSDoc padrão: não existe sintaxe para um nome de propriedade que não seja identificador válido. Isso é dito em vez de calado: nada na saída vai avisar você, e um editor pode simplesmente ignorar essa linha. Uma chave assim é melhor renomeada na origem.

O que uma amostra não pode decidir

Cada propriedade é documentada como presente, porque foi o que o documento mostrou. O JSDoc anota uma opcional @property {string} [name] e uma anulável {?string} — dois retoques que se fazem conhecendo a API, não fatos contidos numa única carga.

Um valor desconhecido vira *, o «qualquer tipo» do JSDoc. Ele aparece onde a amostra se cala: um array vazio dá Array<*>.

Privado por padrão

Tudo é executado localmente no seu navegador com JavaScript. Os seus dados nunca são enviados para um servidor, o que torna a ferramenta segura para conteúdo sensível e funciona offline.

Perguntas frequentes

Por que JSDoc e não TypeScript?: Porque o arquivo continua sendo JavaScript. Com `checkJs` ligado, o compilador do TypeScript lê esses typedefs e devolve os mesmos erros no editor, sem build, sem extensão `.ts`, sem transpilador. Para um script Node ou uma biblioteca pequena publicada como está, é todo o benefício dos tipos e nada do seu custo.
Uma chave com hífen saiu entre aspas. Isso é válido?: Não exatamente, e esse é o limite honesto desta saída. `@property {string} "content-type"` mantém a chave legível, mas o JSDoc não tem sintaxe para um nome de propriedade que não seja identificador: as aspas não vêm de especificação alguma. Vale renomear essa chave na origem, ou documentá-la em prosa ao lado.
Como uso o typedef gerado?: Referencie-o pelo nome: `/** @type {Root} */` numa variável, ou `@param {Root} payload` numa função. Se os typedefs moram em outro arquivo, importe-os com `/** @typedef {import("./types.js").Root} Root */` — o editor resolve do mesmo jeito.