Perché JSDoc e non TypeScript?

Perché il file resta JavaScript. Con `checkJs` attivo, il compilatore TypeScript legge questi typedef e ti restituisce gli stessi errori nell’editor, senza build, senza estensione `.ts`, senza transpilatore. Per uno script Node o una piccola libreria pubblicata così com’è, è tutto il beneficio dei tipi e niente del loro costo.

Come uso il typedef generato?

Richiamalo per nome: `/** @type {Root} */` su una variabile, o `@param {Root} payload` su una funzione. Se i typedef stanno in un altro file, importali con `/** @typedef {import("./types.js").Root} Root */` — l’editor li risolve allo stesso modo.

JSON in JSDoc — autocompletamento in JS puro

Trasforma un campione JSON in typedef JSDoc. Ogni oggetto diventa un @typedef con nome che l’editor legge, in JavaScript puro, senza passo di build.

Istantaneo Privato Zero cookie

Nome radice

Input JSON

Output JSDoc

Che cosa fa questo strumento

Un campione JSON diventa typedef JSDoc, un blocco per oggetto.

{ "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
 */

Mettili in cima a un file .js e ogni @type {Root} di quel file viene controllato — dal tuo editor e da tsc --checkJs, se lo lanci.

Anche una lista alla radice prende un nome

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

Quel blocco mancava: un campione ad array produceva solo il typedef dell’elemento, e il nome radice impostato non andava da nessuna parte. Era un difetto vero, trovato scrivendo questa pagina e corretto.

Gli array si scrivono sempre Array<…> e non …[]. Entrambe le forme valgono; quella lunga resta leggibile quando il tipo dell’elemento è un’unione o un *.

Una chiave che non è un identificatore

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

 * @property {string} "content-type"

Le virgolette tengono la chiave leggibile, e non sono JSDoc standard: non esiste una sintassi per un nome di proprietà che non sia un identificatore valido. Lo diciamo invece di tacerlo: nulla nell’uscita ti avvertirà, e un editor può semplicemente ignorare quella riga. Una chiave così è meglio rinominarla alla fonte.

Ciò che un campione non può decidere

Ogni proprietà è documentata come presente, perché è ciò che il documento mostrava. JSDoc segna un’opzionale @property {string} [name] e una annullabile {?string}: due modifiche che si fanno conoscendo l’API, non fatti contenuti in un singolo carico.

Un valore ignoto diventa *, il «qualsiasi tipo» di JSDoc. Compare dove il campione tace: un array vuoto dà Array<*>.

Privato per progettazione

Tutto viene eseguito localmente nel browser con JavaScript. I tuoi dati non vengono mai caricati, quindi lo strumento è sicuro per contenuti sensibili e funziona anche offline.

Domande frequenti

Perché JSDoc e non TypeScript?: Perché il file resta JavaScript. Con `checkJs` attivo, il compilatore TypeScript legge questi typedef e ti restituisce gli stessi errori nell’editor, senza build, senza estensione `.ts`, senza transpilatore. Per uno script Node o una piccola libreria pubblicata così com’è, è tutto il beneficio dei tipi e niente del loro costo.
Una chiave con trattino è uscita tra virgolette. È valido?: Non proprio, ed è il limite onesto di questa uscita. `@property {string} "content-type"` tiene la chiave leggibile, ma JSDoc non ha sintassi per un nome di proprietà che non sia un identificatore: le virgolette non vengono da nessuna specifica. Meglio rinominare quella chiave alla fonte, o descriverla in prosa lì accanto.
Come uso il typedef generato?: Richiamalo per nome: `/** @type {Root} */` su una variabile, o `@param {Root} payload` su una funzione. Se i typedef stanno in un altro file, importali con `/** @typedef {import("./types.js").Root} Root */` — l’editor li risolve allo stesso modo.