Generazione dei tipi

Efesto genera tipi TypeScript dal tuo swaggerModel e li mantiene sincronizzati mentre modifichi, così non devi scrivere a mano le interfacce di richiesta/risposta.

Solo stack Express

La generazione dei tipi (e la modifica magica del codice qui sotto) è una funzionalità dello stack Express, dove i tipi derivano da swaggerModel / _<verb>Swagger. Funziona solo in sviluppo (isProduction: false). Sullo stack Bun/Elysia non c'è nulla da generare: con le rotte Elysia native TypeScript inferisce i tipi degli handler direttamente dai tuoi schemi TypeBox.

Come funziona

Quando definisci il tuo swaggerModel e gli schemi nelle tue classi di servizio, Efesto analizza queste definizioni e genera i corrispondenti tipi TypeScript.

Il namespace generato prende il nome dalla classe esportata di default dal file di rotta. Un file che termina con export default UserService; produce un namespace globale UserServiceTypes in <generatedTypesFolder>/UserService.d.ts.

Tipi generati

Efesto genera i seguenti tipi per ogni endpoint:

• Tipi del corpo della richiesta: tipi per il corpo delle richieste POST, PUT, PATCH.
• Tipi del corpo della risposta: tipi per il corpo della risposta.
• Parametri di query: tipi per i parametri della query string.
• Parametri di percorso: tipi per i parametri di percorso dell'URL.
• Tipi di servizio: namespace contenente tutti i tipi per uno specifico servizio.

Configurazione

Imposta generatedTypesFolder per attivarla:

efesto({
  // ...
  options: {
    generatedTypesFolder: "./src/types", // Cartella in cui verranno generati i tipi
    automaticTypesGenerationInlineFile: false, // Se generare i tipi inline (default: false)
  },
});

generatedTypesFolder

È la directory in cui Efesto produrrà i file .d.ts generati. Ogni servizio avrà il proprio file di dichiarazione in questa cartella.

automaticTypesGenerationInlineFile

Se impostato a true, Efesto tenterà di generare i tipi direttamente all'interno del file di servizio. Tuttavia, l'approccio consigliato è usare generatedTypesFolder per tenere i tipi separati.

Modifica magica del codice

Una delle funzionalità più peculiari di Efesto è la capacità di modificare "magicamente" il tuo codice per aggiungere annotazioni di tipo. Quando canMagicallyEditCode è abilitato nella tua configurazione (default: true), Efesto:

1. Analizza la tua classe di servizio: esamina i tuoi metodi _get, _post, ecc.
2. Genera i tipi: genera gli specifici tipi di richiesta e risposta in base alla tua definizione Swagger.
3. Aggiorna le firme dei metodi: aggiorna automaticamente le firme dei metodi per usare questi tipi generati.

Esempio

Prima:

async _get(req, res) {
  // ...
}

Dopo (aggiornato automaticamente da Efesto):

async _get(req: UserTypes.GetRequest, res: UserTypes.GetResponse) {
  // ...
}

Questa funzionalità accelera notevolmente lo sviluppo fornendo intellisense e controllo dei tipi immediati senza boilerplate manuale.

[!NOTE] Questa funzionalità funziona solo in modalità sviluppo. Assicurati che isProduction sia false.

Editor dei typing

Lo strumento typingsEditor gira in background all'avvio di Efesto. Monitora i tuoi file di servizio e aggiorna le definizioni dei tipi ogni volta che modifichi i tuoi modelli Swagger.

Namespace generato

Per un servizio chiamato User, Efesto genera un namespace UserTypes contenente:

• GetRequest, GetResponse
• PostRequest, PostResponse
• PutRequest, PutResponse
• ... e così via per ogni metodo.

Questi tipi sono disponibili globalmente se includi la cartella generata nel tuo tsconfig.json.

tsconfig

Includi la cartella generata così che i tipi si risolvano:

{
  "include": ["src/**/*", "src/types/**/*"]
}

I tipi seguono il tuo swaggerModel mentre il dev server è in esecuzione. Effettua il commit della cartella per build riproducibili, oppure aggiungila al .gitignore per rigenerarla al volo.