Read the article in english language

Dalla la versione di Node.js v22.6.0 è stato introdotto il nuovo flag sperimentale:

--experimental-strip-types

Questo flag ci permette di eseguire con Node.js un file .ts direttamente e senza bisogno di librerie esterne ne di compilare in Javascript prima di eseguire il file, usando la tecnica del "type stripping"

Per usare questo nuovo flag bisogna usare una versione di Node.js uguale o maggiore della v22.6.0

In questo articolo userò Node.js 22.8.0

--experimental-strip-types in Node.js

Creiamo un file, ad esempio node-typescript.ts

interface Person {
    name: string
    surname: string
}

const manuel: Person = {
    name: 'Manuel',
    surname: 'Salinardi'
} 

console.log(`Hello ${manuel.name} ${manuel.surname}`)

Proviamo ad eseguirlo con node:

node node-typescript.ts

E boom!

interface Person {
          ^^^^^^

SyntaxError: Unexpected identifier 'Person'
    at wrapSafe (node:internal/modules/cjs/loader:1469:18)
    at Module._compile (node:internal/modules/cjs/loader:1491:20)
    at Module._extensions..js (node:internal/modules/cjs/loader:1691:10)
    at Module.load (node:internal/modules/cjs/loader:1317:32)
    at Module._load (node:internal/modules/cjs/loader:1127:12)
    at TracingChannel.traceSync (node:diagnostics_channel:315:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:217:24)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:166:5)
    at node:internal/main/run_main_module:30:49

Wow che bell'errore, ed è giusto che sia così perché "interface" non esiste in Javascript ma è una feature di Typescript.

Ed è qui che entra in gioco il nuovo flag sperimentale che ci permette di eseguire file Typescript direttamente con Node.js

node --experimental-strip-types node-typescript.ts

Ed ora come output vedremo:

Hello Manuel Salinardi
(node:98118) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

Wow funziona!

Vediamo anche che c'è un warning che ci avvisa che stiamo usando un flag sperimentale.

--experimental-strip-types in Fastify

Creiamo il progetto Fastify

Usiamo fastify-cli per creare il progetto Fastify

npx fastify-cli generate fastify-type-stripping --lang=ts --esm

Entriamo nella cartella "fastify-type-stripping" appena creata e installiamo le dipendenze

npm install

Ora lanciamo il server appena creato

npm start

Se tutto è andato a buon fine dovremmo vedere un output come questo:

{"level":30,"time":1725951422786,"pid":8786,"hostname":"Manuels-MacBook-Pro.local","msg":"Server listening at http://127.0.0.1:3000"}
{"level":30,"time":1725951422787,"pid":8786,"hostname":"Manuels-MacBook-Pro.local","msg":"Server listening at http://[::1]:3000"}

Usiamo --experimental-strip-types

fastify-cli ha generato questo package.json

{
  "type": "module",
  "name": "fastify-type-stripping",
  "version": "1.0.0",
  "description": "This project was bootstrapped with Fastify-CLI.",
  "main": "app.ts",
  "directories": {
    "test": "test"
  },
  "scripts": {
    "test": "npm run build:ts && tsc -p test/tsconfig.json && FASTIFY_AUTOLOAD_TYPESCRIPT=1 node --test --experimental-test-coverage --loader ts-node/esm test/**/*.ts",
    "start": "npm run build:ts && fastify start -l info dist/app.js",
    "build:ts": "tsc",
    "watch:ts": "tsc -w",
    "dev": "npm run build:ts && concurrently -k -p \"[{name}]\" -n \"TypeScript,App\" -c \"yellow.bold,cyan.bold\" \"npm:watch:ts\" \"npm:dev:start\"",
    "dev:start": "fastify start --ignore-watch=.ts$ -w -l info -P dist/app.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "fastify": "^5.0.0",
    "fastify-plugin": "^5.0.0",
    "@fastify/autoload": "^6.0.0",
    "@fastify/sensible": "^6.0.0",
    "fastify-cli": "^7.0.1"
  },
  "devDependencies": {
    "@types/node": "^22.1.0",
    "c8": "^10.1.2",
    "ts-node": "^10.4.0",
    "concurrently": "^9.0.0",
    "fastify-tsconfig": "^2.0.0",
    "typescript": "^5.2.2"
  }
}

Analizziamo lo script di start del package.json:

"start": "npm run build:ts && fastify start -l info dist/app.js"

Lo script “start“ è composto da due comandi:

• npm run build:ts

• fastify start -l info dist/app.js

Quindi vediamo che per prima cosa lancia lo script "build:ts":

"build:ts": "tsc"

"build:ts" lancia il comando “tsc”, Che converte il codice Typescript in JavaScript a seconda delle impostazioni che trova nel file tsconfig.json, che nel nostro caso è:

{
  "extends": "fastify-tsconfig",
  "compilerOptions": {
    "outDir": "dist",
    "sourceMap": true,
    "moduleResolution": "NodeNext",
    "module": "NodeNext",
    "target": "ES2022",
    "esModuleInterop": true
  },
  "include": ["src/**/*.ts"]
}

Come possiamo vedere c’è la proprietà "outDir": "dist". Che dice al compilatore di mettere l’output della compilazione, ovvero i file JavaScript generati nella cartella “dist“

Poi viene lanciato il comando: fastify start -l info dist/app.js, che va a lanciare il nostro server dal file dist/app.js autogenerato dal compilatore TypeScript.

Quindi vediamo che ogni volta che lanciamo il server c’è sempre questo passo intermedio che è la conversione dei file TypeScript in JavaScript e poi il server viene effettivamente lanciato dai file JavaScript.

Lanciamo il server senza la compilazione Typescript

Proviamo ad usare la nuova feature di Node.js --experimental-strip-types per lanciare direttamente il server con il codice sorgente TypeScriprt senza dover prima convertire i file in JavaScript.

Procediamo a tentativi e risolviamo tutti gli errori che incontriamo.

Tentativo 1: Stato iniziale

Iniziamo solo con provare a rimuovere la compilazione ed avviare il server direttamente con il file TypeScript e godiamoci l’esplosione:

"start": "fastify start -l info src/app.ts"

> fastify-type-stripping@1.0.0 start
> fastify start -l info src/app.ts

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/src/app.ts
    at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:217:9)
    at defaultGetFormat (node:internal/modules/esm/get_format:243:36)
    at defaultLoad (node:internal/modules/esm/load:123:22)
    at async ModuleLoader.load (node:internal/modules/esm/loader:567:7)
    at async ModuleLoader.moduleProvider (node:internal/modules/esm/loader:442:45)
    at async ModuleJob._link (node:internal/modules/esm/module_job:106:19) {
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

Boom!!!

Abbiamo un errore che ci dice il file .ts non è supportato, ma abbiamo visto che per questo possiamo aggiungere il nuovo flag di Node.js --experimental-strip-types.

Ma dove?

Tentativo 2: Passare il flag --experimental-strip-types

Il flag --experimental-strip-types va passato all’eseguibile node ma noi stiamo lanciando il server con:
fastify start -l info src/app.ts. In questo caso possiamo usare la variabile d’ambiente:
NODE_OPTIONS che ci permette di passare le opzioni di Node.js in questo modo:

"start": "NODE_OPTIONS='--experimental-strip-types' fastify start -l info src/app.ts"

 *  Executing task: source ~/.zshrc && npm run start 


> fastify-type-stripping@1.0.0 start
> NODE_OPTIONS='--experimental-strip-types' fastify start -l info src/app.ts

(node:57588) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
file:///Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/src/app.ts:2
import AutoLoad, {AutoloadPluginOptions} from '@fastify/autoload';
                  ^^^^^^^^^^^^^^^^^^^^^
SyntaxError: Named export 'AutoloadPluginOptions' not found. The requested module '@fastify/autoload' is a CommonJS module, which m
ay not support all module.exports as named exports.                                                                                CommonJS modules can always be imported via the default export, for example using:

import pkg from '@fastify/autoload';
const {AutoloadPluginOptions} = pkg;

    at ModuleJob._instantiate (node:internal/modules/esm/module_job:171:21)
    at async ModuleJob.run (node:internal/modules/esm/module_job:254:5)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:482:26)
    at async requireServerPluginFromPath (/Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/node_modules/fastify-c
li/util.js:83:22)                                                                                                                      at async runFastify (/Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/node_modules/fastify-cli/start.js:115:1
2)                                                                                                                                 
 *  The terminal process "/bin/zsh '-l', '-c', 'source ~/.zshrc && npm run start'" terminated with exit code: 1.

Wow è cambiato l’errore!

Ora vediamo che il flag --experimental-strip-types é stato preso correttamente perchè abbiamo questo warning:

(node:57588) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

Ma c’è un errore con il plugin @fastify/autoload:

SyntaxError: Named export 'AutoloadPluginOptions' not found. The requested module '@fastify/autoload' is a CommonJS module, which m
ay not support all module.exports as named exports.

C’è qualcosa che non va con un import nel nostro file src/app.ts:

import AutoLoad, {AutoloadPluginOptions} from '@fastify/autoload';

Questo è dovuto dal comportamento del type stripping del flag --experimental-strip-types che se importiamo un typo TypeScript senza esplicitamente usare la keyword “type“ Node.js lo tratterà come un normale valore generando un errore a runtime, come spiegato più in dettaglio qui: https://nodejs.org/docs/latest-v22.x/api/typescript.html#type-stripping.

Tentativo 3: Usare “import type” per i tipi TypeScript

Per assicurarci di importare correttamente con “import type“ i tipi TypeScript in modo che il type stripping riesca correttamente ad eliminarli aggiungiamo una impostazione del compilatore TypeScript: verbatimModuleSyntax al nostro file:

tsconfig.json

{
  "extends": "fastify-tsconfig",
  "compilerOptions": {
    "outDir": "dist",
    "sourceMap": true,
    "moduleResolution": "NodeNext",
    "module": "NodeNext",
    "target": "ES2022",
    "esModuleInterop": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src/**/*.ts"]
}

Ora vedremo gli errori degli import direttamente dal nostro editor:

Quindi andiamo a sistemare tutti gli errori:

src/app.ts

import AutoLoad, { type AutoloadPluginOptions } from '@fastify/autoload';
import { type FastifyPluginAsync } from 'fastify';

src/routes/root.ts

import { type FastifyPluginAsync } from 'fastify'

src/routes/example/index.ts

import { type FastifyPluginAsync } from 'fastify'

src/plugins/sensible.ts

import sensible, { type FastifySensibleOptions } from '@fastify/sensible'

Ora che abbiamo risolto tutti i problemi di import proviamo a lanciare il server ed incrociamo le dita.

 *  Executing task: source ~/.zshrc && npm run start 


> fastify-type-stripping@1.0.0 start
> NODE_OPTIONS='--experimental-strip-types' fastify start -l info src/app.ts

(node:24423) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
/Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/node_modules/@fastify/autoload/lib/find-plugins.js:148
    throw new Error(`@fastify/autoload cannot import ${isHook ? 'hooks ' : ''}plugin at '${file}'. To fix this error compile TypeScript to JavaScrip
t or use 'ts-node' to run your app.`)                                                                                                                         ^

Error: @fastify/autoload cannot import plugin at '/Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/src/plugins/sensible.ts'. To fi
x this error compile TypeScript to JavaScript or use 'ts-node' to run your app.                                                                         at handleTypeScriptSupport (/Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/node_modules/@fastify/autoload/lib/find-plugins.j
s:148:11)                                                                                                                                               at processFile (/Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/node_modules/@fastify/autoload/lib/find-plugins.js:124:3)
    at processDirContents (/Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/node_modules/@fastify/autoload/lib/find-plugins.js:101
:7)                                                                                                                                                     at buildTree (/Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/node_modules/@fastify/autoload/lib/find-plugins.js:41:9)
    at async findPlugins (/Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/node_modules/@fastify/autoload/lib/find-plugins.js:14:3
)                                                                                                                                                       at async autoload (/Users/manuelsalinardi/coding/blogs/fastify/fastify-type-stripping/node_modules/@fastify/autoload/index.js:20:22)

Node.js v22.8.0

 *  The terminal process "/bin/zsh '-l', '-c', 'source ~/.zshrc && npm run start'" terminated with exit code: 1.

Boom! Oh no un altro errore!

L’errore arriva dal modulo @fastify/autoload e ci dice:
To fix this error compile TypeScript to JavaScript or use 'ts-node' to run your app.

È un controllo che viene fatto da @fastify/autoload, per disabilitarlo bisogna lanciare il server con la variabile d’ambiente: FASTIFY_AUTOLOAD_TYPESCRIPT

Tentativo 4: FASTIFY_AUTOLOAD_TYPESCRIPT

Aggiungiamo anche la variabile d’ambiente: FASTIFY_AUTOLOAD_TYPESCRIPT allo script di “start”

"start": "NODE_OPTIONS='--experimental-strip-types' FASTIFY_AUTOLOAD_TYPESCRIPT=1 fastify start -l info src/app.ts"

 *  Executing task: source ~/.zshrc && npm run start 


> fastify-type-stripping@1.0.0 start
> NODE_OPTIONS='--experimental-strip-types' FASTIFY_AUTOLOAD_TYPESCRIPT=1 fastify start -l info src/app.ts

(node:36950) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
{"level":30,"time":1727709779182,"pid":36950,"hostname":"Manuels-MacBook-Pro.local","msg":"Server listening at http://127.0.0.1:3000"}
{"level":30,"time":1727709779183,"pid":36950,"hostname":"Manuels-MacBook-Pro.local","msg":"Server listening at http://[::1]:3000"}

Wow finalmente funziona!

Ora siamo in grado di lanciare il nostro server direttamente dal codice sorgente TypeScript senza più il bisogno di compilazione.

Possiamo fare lo stesso anche per lo script di “test“ del package.json ed eliminare dalle “devDependencies“ la libreria “ts-node“ perchè lo stesso lo possiamo fare nativamente in Node.js grazie al nuovo flag --experimental-strip-types

Read the article in english language

Intro

Fastify usa pino come logger, uno dei più performanti logger per Node.js.

Quindi generalmente per personalizzare il logger di Fastify, si applicano gli stessi concetti per personalizzare pino, ma con qualche eccezione che vedremo in questo articolo.

Per questo articolo è stato usato Node.js v20.13.1

Abilitare il logger

Di default il logger di Fastify è disabilitato, per abilitarlo basta impostarlo a true quando si inizializza Fastify.

const fastify = Fastify({
  logger: true
})

Scriviamo il primo log

Per vedere il primo esempio di log creiamo un semplice progetto Fastify, che poi useremo per tutti gli altri esempi che vedremo in questo articolo.

Creiamo il progetto Fastify

Creiamo ed entriamo nella cartella del progetto

mkdir my-logger
cd my-logger

Installiamo Fastify nel progetto

npm install fastify

Questo il contenuto del file package.json generato:

{
  "dependencies": {
    "fastify": "^4.28.1"
  }
}

Creiamo il file index.js

// importa Fastify
const Fastify = require('fastify')

// inizializza Fastify
const fastify = Fastify({
  logger: true // abilita il logger (disabilitato di default)
})

// inizia a loggare
fastify.log.info('Hello Log!')

Non abbiamo avviato alcun server, abbiamo solo inizializzato Fastify, e questo è sufficiente per iniziare a loggare.

Eseguiamo il file con il comando:

node server

Come output otterremo un oggetto simile a questo:

{"level":30,"time":1721369918925,"pid":85758,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello World!"}

Formattiamolo meglio per analizzarlo

{
   "level":30, // 30 rappresenta il livello info dovuto da: fastify.log.info
   "time":1721369918925, // Unix time in millisecondi ( epoch time )
   "pid":85758, // id del processo ( equivlente a process.pid )
   "hostname":"Manuels-MacBook-Pro.local", // il nome host del sistema operativo. ( equivlente a require('os').hostname() ) 
   "msg":"Hello World!" // la stringa che abbiamo loggato
}

Vediamo che dalla nostra semplice chiamata di log:

fastify.log.info('Hello Log!')

Solo "msg" è effettivamente quello che abbiamo scritto noi, tutti gli altri campi sono stati aggiunti da Pino, e verranno aggiunti per ogni chiamata al logger.

Personalizziamo il Logger

Abbiamo visto che di default quando facciamo una chiamata al logger viene loggato un oggetto JSON in cui il nostro messaggio viene messo come valore del campo "msg".

Ma vengono anche aggiunti da Pino i campi:

• "level"

• "time"

• "pid"

• "hostname"

In questa sezione vedremo come personalizzarli uno ad uno.

level

Prima di personalizzare il campo "level" vediamo un pò come funziona.

In Pino esistono diversi livelli di log:

"fatal" | "error" | "warn" | "info" | "debug" | "trace".

Per ogni livello esiste il suo corrispondente metodo:

const Fastify = require('fastify')

const fastify = Fastify({
  logger: true
})

fastify.log.fatal('Hello fatal!')
fastify.log.error('Hello error!')
fastify.log.warn('Hello warn!')
fastify.log.info('Hello info!')
fastify.log.debug('Hello debug!')
fastify.log.trace('Hello trace!')

Il codice di sopra genererà il seguente output:

{"level":60,"time":1722405654790,"pid":57113,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello fatal!"}
{"level":50,"time":1722405654790,"pid":57113,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello error!"}
{"level":40,"time":1722405654790,"pid":57113,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello warn!"}
{"level":30,"time":1722405654790,"pid":57113,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello info!"}

Ma c'è qualcosa di strano, perché dal codice abbiamo chiamato il logger 6 volte, ma ne sono stati generati solo 4?:

• "Hello fatal!"

• "Hello error!"

• "Hello warn!"

• "Hello info!"

Mancano all'appello:

• "Hello debug!"

• "Hello trace!"

Dove sono finiti?

Pino associa ad ogni livello un valore numerico:

• "fatal" = 60

• "error" = 50

• "warn" = 40

• "info" = 30

• "debug" = 20

• "trace" = 10

Che possiamo vedere nel campo "level" dei log generati.

Di default vengono scartati i log sotto il livello 30, ovvero "info".

Per cambiare questo default e vedere i log di tutti i livelli, bisogna impostare il campo level del logger in questo modo:

const fastify = Fastify({
  logger: {
    level: 'trace'
  }
})

Ora vediamo che ci sono tutti e 6 i log:

{"level":60,"time":1722406770355,"pid":57832,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello fatal!"}
{"level":50,"time":1722406770355,"pid":57832,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello error!"}
{"level":40,"time":1722406770355,"pid":57832,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello warn!"}
{"level":30,"time":1722406770355,"pid":57832,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello info!"}
{"level":20,"time":1722406770355,"pid":57832,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello debug!"}
{"level":10,"time":1722406770355,"pid":57832,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello trace!"}

Ora che abbiamo capito come funziona il campo "level", vediamo come personalizzarlo:

const fastify = Fastify({
  logger: {
    formatters: {
      level (label, number) {
        // questi campi verranno sostituiti al campo "level" di default
        return {
          myLevel: `${label}-${number}`,
          levelName: label,
          levelNumber: number 
        }
      }
    }
  }
})

Ora i log generati saranno in questo formato:

{"myLevel":"fatal-60","levelName":"fatal","levelNumber":60,"time":1722576879835,"pid":90770,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello fatal!"}
{"myLevel":"error-50","levelName":"error","levelNumber":50,"time":1722576879835,"pid":90770,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello error!"}
{"myLevel":"warn-40","levelName":"warn","levelNumber":40,"time":1722576879835,"pid":90770,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello warn!"}
{"myLevel":"info-30","levelName":"info","levelNumber":30,"time":1722576879835,"pid":90770,"hostname":"Manuels-MacBook-Pro.local","msg":"Hello info!"}

Come possiamo vedere dai log, ora al posto del campo "level" ne troviamo altri 3:

• "myLevel"

• "levelName"

• "levelNumber"

time

Si può personalizzare il campo time impostando il campo "timestamp" nel seguente modo:

const Fastify = require('fastify')
const pino = require('pino')

const fastify = Fastify({
  logger: {
    timestamp: pino.stdTimeFunctions.isoTime, // converte da epoch time a ISO time
  }
})

fastify.log.info('Hello info!')

{
   "level":30,
   "time":"2024-07-18T06:48:52.040Z", // ISO Time
   "pid":19929,
   "hostname":"Manuels-MacBook-Pro.local",
   "msg":"Hello info"
}

Pino ci mette a disposizione le seguenti funzioni per la formattazione del "timestamp":

• pino.stdTimeFunctions.epochTime: Milliseconds since Unix epoch (Default)

• pino.stdTimeFunctions.unixTime: Seconds since Unix epoch

• pino.stdTimeFunctions.nullTime: Clears timestamp property (Used when timestamp: false)

• pino.stdTimeFunctions.isoTime: ISO 8601-formatted time in UTC

Dalla documentazione ufficiale: Pino stdTimeFunctions

pid e hostname

Per personalizzare i campi "pid" e "hostname" bisogna personalizzare i bindings.

I bindings sono dati aggiuntivi che possono essere associati ad un logger per essere inclusi in tutti i log generati da quel logger. Questi dati vengono utilizzati per arricchire le informazioni dei log senza dover specificare manualmente queste informazioni ogni volta che si effettua una chiamata di log.

Di default Pino logger aggiunge nei bindings: "pid" e "hostname", quindi per rimuoverli ed aggiungere campi a nostro piacimento dobbiamo modificare i bindings in questo modo:

const Fastify = require('fastify')
const os = require('os')

const fastify = Fastify({
  logger: {
    formatters: {
      bindings: (bindings) => {
        return { 
          osMachine: os.machine(),
          osType: os.type()
        };
      },
    },
  }
})

fastify.log.info('Hello info!')

{
   "level":30,
   "time":1721283756521,
   "osMachine":"arm64",
   "osType":"Darwin",
   "msg":"Hello info!"
}

Vediamo che "pid" e "hostname" non ci sono più, ma al loro posto ci sono "osMachine" e "osType".

Invece di sostituire "pid" e "hostname" possiamo anche tenerli ed aggiungere campi in questo modo:

const fastify = Fastify({
  logger: {
    formatters: {
      bindings: (bindings) => {
        return { 
          pid: bindings.pid,
          hostname: bindings.hostname,
          osMachine: os.machine(),
          osType: os.type()
        };
      },
    },
  }
})

fastify.log.info('Hello info!')

{
   "level":30,
   "time":1722577623975,
   "pid":91371,
   "hostname":"Manuels-MacBook-Pro.local",
   "osMachine":"arm64",
   "osType":"Darwin",
   "msg":"Hello info!"
}

Cos'è il Request Logger?

Fino ad ora abbiamo usato il logger di Fastify ma senza mai avviare un server.
Fastify ci mette a disposizione una feature utilissima che si chiama appunto "Request Logger".
Ora con qualche esempio pratico vedremo come funziona e come personalizzarlo.

Creiamo il server

 const Fastify = require('fastify')

const fastify = Fastify({
  logger: true
})

// Dichiara la rotta GET /
fastify.get('/', async function handler (request, reply) {
  fastify.log.info('Fastify logger!')
  // notare che viene usato request.log al posto di fastify.log
  // al contrario degli esempi precedenti
  request.log.info('Request logger!')
  return { hello: 'world' }
})

// Avvia il server sulla porta 3000
fastify.listen({ port: 3000 }, (err) => {
  if (err) {
    fastify.log.error(err)
    process.exit(1)
  }
})

In questo server abbiamo definito solo una rotta GET "/" che:

• logga la stringa "Fastify logger!" (con fastify.log)

• logga la stringa "Request logger!" (con request.log)

• ritorna come risposta l'oggetto: { hello: 'world' }

Da notare che per il primo log viene usato "fastify.log" per il secondo "request.log". Poi vedremo con un esempio qual'è la differenza tra i due.

Avviamo il server con:

node server

All'avvio del server vedremo dei log auto generati da Fastify del genere:

{"level":30,"time":1720591420640,"pid":69286,"hostname":"Manuels-MacBook-Pro.local","msg":"Server listening at http://127.0.0.1:3000"}
{"level":30,"time":1720591420643,"pid":69286,"hostname":"Manuels-MacBook-Pro.local","msg":"Server listening at http://[::1]:3000"}

Prima chiamata HTTP

Ora proviamo a fare una chiamata HTTP, ad esempio con Postman alla nostra unica rotta appena creata.

Questa chiamata ha generato 4 log:

// auto generato da Fastify (quando riceve una richiesta HTTP)
{
   "level":30,
   "time":1720678823876,
   "pid":2292,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "req":{
      "method":"GET",
      "url":"/",
      "hostname":"127.0.0.1:3000",
      "remoteAddress":"127.0.0.1",
      "remotePort":63548
   },
   "msg":"incoming request"
}

// generato da noi con fastify.log.info('Fastify logger!')
{
   "level":30,
   "time":1720678823877,
   "pid":2292,
   "hostname":"Manuels-MacBook-Pro.local",
   "msg":"Fastify logger!"
}

// generato da noi con request.log.info('Request logger!')
{
   "level":30,
   "time":1720678823877,
   "pid":2292,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "msg":"Request logger!"
}

// auto generato da Fastify (quando invia una risposta HTTP)
{
   "level":30,
   "time":1720678823880,
   "pid":2292,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "res":{
      "statusCode":200
   },
   "responseTime":3.9882499873638153,
   "msg":"request completed"
}

Tra i quattro log c'è un intruso, riesci a vederlo?

L'intruso è il secondo: "Fastify logger!"

Infatti possiamo vedere che è l'unico che non ha il "reqId". Non ha il "reqId" perché è l'unico a non essere stato generato dal request logger.

Fastify per ogni richiesta genera un "reqId" utile per collegare tutti i log a quella specifica richiesta, nel nostro caso:

• "incoming request" è stato generato da Fastify alla ricezione della richiesta, e per questa richiesta è stato creato un id univoco "reqId":"req-1".

• "Fastify logger!" è stato generato da noi con fastify.log.info('Fastify logger!'), ma siccome abbiamo usato fastify.log, questo log non farà parte del contesto della richiesta, quindi "reqId":"req-1" non verrà loggato.

• "Request logger!" è stato generato da noi con request.log.info('Request logger!'), in questo caso siccome abbiamo usato request.log, questo log farà parte del contesto della richiesta quindi "reqId":"req-1" verrà loggato.

• "request completed" è stato generato da Fastify quando la richiesta è terminata e la risposta è stata inviata.

Disabilitare il request logger

const app = Fastify({
  disableRequestLogging: true, // disabilita il request logger
  logger: true
})

Basta impostare disableRequestLogging a true per non far generare a Fastify in automatico i log alla ricezione della richiesta ed all'invio della risposta.

Vediamo l'esempio precedente con il request logger disabilitato:

 const Fastify = require('fastify')

const fastify = Fastify({
  disableRequestLogging: true, // disabilita il request logger
  logger: true
})

// Dichiara la rotta GET /
fastify.get('/', async function handler (request, reply) {
  fastify.log.info('Fastify logger!') // viene loggato
  request.log.info('Request logger!') // viene comunque loggato
  return { hello: 'world' }
})

// Avvia il server sulla porta 3000
fastify.listen({ port: 3000 }, (err) => {
  if (err) {
    fastify.log.error(err)
    process.exit(1)
  }
})

Avviamo il server:

node server

{"level":30,"time":1722320649945,"pid":20123,"hostname":"Manuels-MacBook-Pro.local","msg":"Server listening at http://[::1]:3000"}
{"level":30,"time":1722320649947,"pid":20123,"hostname":"Manuels-MacBook-Pro.local","msg":"Server listening at http://127.0.0.1:3000"}

I log automatici all'avvio del server vengono comunque generati.

Facciamo ancora la chiamata HTTP con Postman:

{"level":30,"time":1722320840449,"pid":20123,"hostname":"Manuels-MacBook-Pro.local","msg":"Fastify logger!"}
{"level":30,"time":1722320840449,"pid":20123,"hostname":"Manuels-MacBook-Pro.local","reqId":"req-1","msg":"Request logger!"}

Vediamo che ora sono solo 2 i log, mancano quelli auto generati da Fastify:

• "incoming request"

• "request completed"

Ma il request logger che abbiamo invocato manualmente con:

request.log.info('Request logger!')

Viene comunque loggato.

Personalizziamo il Request Logger

Il Request Logger viene usato nei seguenti casi:

• chiamato esplicitamente con il metodo: "request.log"

• chiamato automaticamente da Fastify ad ogni nuova richiesta HTTP ricevuta

• chiamato automaticamente da Fastify ad ogni risposta HTTP inviata

• chiamato automaticamente da Fastify ad ogni eccezione generata dentro una rotta (non lo abbiamo ancora visto ma lo vedremo dopo)

Rivediamoli uno ad uno:

// chiamato esplicitamente con il metodo: "request.log"
{
   "level":30,
   "time":1720678823877,
   "pid":2292,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "msg":"Request logger!"
}

// chiamato automaticamente da Fastify ad ogni nuova richiesta HTTP ricevuta
{
   "level":30,
   "time":1720678823876,
   "pid":2292,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "req":{
      "method":"GET",
      "url":"/",
      "hostname":"127.0.0.1:3000",
      "remoteAddress":"127.0.0.1",
      "remotePort":63548
   },
   "msg":"incoming request"
}

// chiamato automaticamente da Fastify ad ogni risposta HTTP inviata
{
   "level":30,
   "time":1720678823880,
   "pid":2292,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "res":{
      "statusCode":200
   },
   "responseTime":3.9882499873638153,
   "msg":"request completed"
}

// chiamato automaticamente da Fastify ad ogni eccezione generata dentro una rotta 
{
   "level":50,
   "time":1720766398542,
   "pid":40069,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "req":{
      "method":"GET",
      "url":"/",
      "hostname":"127.0.0.1:3000",
      "remoteAddress":"127.0.0.1",
      "remotePort":54858
   },
   "res":{
      "statusCode":500
   },
   "err":{
      "type":"Error",
      "message":"Boom!",
      "stack":"Error: Boom!\n    at Object..."
   },
   "msg":"Boom!"
}

Quindi possiamo vedere che dal Request Logger vengono aggiunti i seguenti campi:

• "reqId"

• "req"

• "res"

• "err"

In questa sezione vedremo come personalizzarli uno ad uno.

reqId

La prima cosa che possiamo personalizzare del request logger è il "reqId", con il metodo: genReqId

let currentId = 1

const fastify = Fastify({
  logger: true,
  genReqId: (req) => {
    return `my-custom-id-${currentId++}`
  }
})

{
   "level":30,
   "time":1722580879611,
   "pid":93284,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"my-custom-id-1", // Generato dal nostro genReqId
   "msg":"Request logger!"
}

req e res

Come facciamo a personalizzare gli oggetti "req" e "res" che vengono loggati? Per esempio aggiungere o rimuovere campi?

Si usa l'oggetto serializers per questo:

const fastify = Fastify({
  logger: {
    serializers: {
      req (request) { // in req vogliamo solo: method e url
        return {
          method: request.method,
          url: request.url,
        };
      },
      res (reply) { // in res vogliamo: method, url e statusCode
        return {
          method: reply.request.method,
          url: reply.request.url,
          statusCode: reply.statusCode
        }
      },
    }
  }
})

// ora req contiene solo method e url
// invece che il default: method, url, hostname, remoteAddress, remotePort
{
   "level":30,
   "time":1720765071638,
   "pid":38418,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "req":{
      "method":"GET",
      "url":"/"
   },
   "msg":"incoming request"
}

// questo log non è affetto dal serializers perchè non contiene ne req ne res
{
   "level":30,
   "time":1720765071638,
   "pid":38418,
   "hostname":"Manuels-MacBook-Pro.local",
   "msg":"Fastify logger!"
}

// anche questo log non è affetto dal serializers perchè non contiene ne req ne res
{
   "level":30,
   "time":1720765071638,
   "pid":38418,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "msg":"Request logger!"
}

// ora res contiene: method, url, statusCode
// invece che il default: statusCode
{
   "level":30,
   "time":1720765071640,
   "pid":38418,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "res":{
      "method":"GET",
      "url":"/",
      "statusCode":200
   },
   "responseTime":2.362499952316284,
   "msg":"request completed"
}

err

Se dentro una rotta viene generata un eccezione, Fastify la gestisce e la logga per noi in automatico, vediamo un esempio.

Generiamo un eccezione nella nostra rotta:

fastify.get('/', async function handler (request, reply) {
  throw Error('Boom!') // Questo genererà l'errore
  fastify.log.info('Fastify logger!')
  request.log.info('Request logger!')
  return { hello: 'world' }
})

Se proviamo a fare la chiamata HTTP a GET "/" vedremo generato questo log:

{
   "level":50,
   "time":1720766398542,
   "pid":40069,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "req":{
      "method":"GET",
      "url":"/",
      "hostname":"127.0.0.1:3000",
      "remoteAddress":"127.0.0.1",
      "remotePort":54858
   },
   "res":{
      "statusCode":500
   },
   // fastify di default logga un oggetto err, con dentro: type, message e stack
   "err":{
      "type":"Error",
      "message":"Boom!",
      "stack":"Error: Boom!\n    at Object.handler (/Users/manuelsalinardi/..."
   },
   "msg":"Boom!"
}

Vediamo che per l'errore, Fastify genera un log con dentro l'oggetto "err".

Se non volessimo loggare lo stack per motivi di sicurezza?

Anche in questo caso possiamo personalizzare l'oggetto "err" come abbiamo fatto con gli oggetti "req" e "res", usando l'oggetto serializers:

const fastify = Fastify({
  logger: {
    serializers: {
      req (request) {
        return {
          method: request.method,
          url: request.url,
        };
      },
      res (reply) {
        return {
          method: reply.request.method,
          url: reply.request.url,
          statusCode: reply.statusCode
        }
      },
      // qui personalizziamo l'oggetto err
      err (error) {
        return {
          type: error.name,
          message: error.message,
        }
      }
    }
  }
})

Questo il log generato:

{
   "level":50,
   "time":1720767139181,
   "pid":40774,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-1",
   "req":{
      "method":"GET",
      "url":"/"
   },
   "res":{
      "method":"GET",
      "url":"/",
      "statusCode":500
   },
   // ora stack non è più presente
   "err":{
      "type":"Error",
      "message":"Boom!"
   },
   "msg":"Boom!"
}

Aggiungere nuovi campi al Request Logger

Fastify ci aiuta a mettere in relazione tra loro tutti i log di una specifica richiesta tramite il campo "reqId".

Abbiamo visto che "reqId" lo possiamo anche personalizzare, ma come facciamo ad aggiungere un altro campo simile a "reqId", ma scelto a nostro piacimento?

Ad esempio vogliamo aggiungere al request logger il campo "user", che ci viene passato come parametro nella URL da chi fa la chiamata HTTP.

Per fare questo bisogna chiamare il metodo di Fastify setChildLoggerFactory:

const Fastify = require('fastify')

const fastify = Fastify({
  logger: true,
})

// aggiunge campi al Request Logger
fastify.setChildLoggerFactory((logger, bindings, opts, rawReq) => {

  // recupera user dalla URL
  const urlString = rawReq.url || ''
  const queryString = urlString.split('?')[1]
  const searchParams = new URLSearchParams(queryString)
  const user = searchParams.get('user')

  // aggiunge user ai bindings
  bindings.user = user

  return logger.child(bindings, opts)
})

// dichiara la rotta
fastify.get('/', async function handler (request, reply) {
  request.log.info('Request logger!')
  return { hello: 'world' }
})

// avvia il server
fastify.listen({ port: 3000 }, (err) => {
  if (err) {
    fastify.log.error(err)
    process.exit(1)
  }
})

Ora facciamo una chiamata HTTP con il parametro user:

Vedremo dei log del genere:

{
   "level":30,
   "time":1722583839646,
   "pid":95780,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-2",
   "user":"manuel", // nuovo campo user
   "req":{
      "method":"GET",
      "url":"/?user=manuel",
      "hostname":"127.0.0.1:3000",
      "remoteAddress":"127.0.0.1",
      "remotePort":52098
   },
   "msg":"incoming request"
}{
   "level":30,
   "time":1722583839646,
   "pid":95780,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-2",
   "user":"manuel", // nuovo campo user
   "msg":"Request logger!"
}{
   "level":30,
   "time":1722583839648,
   "pid":95780,
   "hostname":"Manuels-MacBook-Pro.local",
   "reqId":"req-2",
   "user":"manuel", // nuovo campo user
   "res":{
      "statusCode":200
   },
   "responseTime":1.4203753471374512,
   "msg":"request completed"
}

Ora il Request Logger oltre al "reqId" avrà anche il nuovo campo "user".

Manuel Salinardi

Click here to read the article in english language

Pre requisiti

Node.js v20.13.1

Cosa sono i Type-Providers

Documentazione: Type-Providers

I Type-Providers sono una feature solo per i progetti Fastify che utilizzano Typescript come linguaggio.

Ci sono diversi tipi di Type-Providers, per questo articolo utilizzeremo: TypeBox

Creiamo il progetto Fastify con Typescript

Apriamo il terminale e digitiamo questo comando:

npx fastify-cli generate my-app --lang=ts

Questo comando genererà un progetto Fastify con Typescript, utilizzando l'utility fastify-cli

Struttura del progetto

A questo punto abbiamo un progetto con la seguente struttura:

Contenuto del package.json generato

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "This project was bootstrapped with Fastify-CLI.",
  "main": "app.ts",
  "directories": {
    "test": "test"
  },
  "scripts": {
    "test": "npm run build:ts && tsc -p test/tsconfig.json && c8 node --test -r ts-node/register \"test/**/*.ts\"",
    "start": "npm run build:ts && fastify start -l info dist/app.js",
    "build:ts": "tsc",
    "watch:ts": "tsc -w",
    "dev": "npm run build:ts && concurrently -k -p \"[{name}]\" -n \"TypeScript,App\" -c \"yellow.bold,cyan.bold\" \"npm:watch:ts\" \"npm:dev:start\"",
    "dev:start": "fastify start --ignore-watch=.ts$ -w -l info -P dist/app.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@fastify/autoload": "^5.0.0",
    "@fastify/sensible": "^5.0.0",
    "@fastify/type-provider-typebox": "^4.0.0",
    "fastify": "^4.26.1",
    "fastify-cli": "^6.2.1",
    "fastify-plugin": "^4.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.4.4",
    "c8": "^9.0.0",
    "concurrently": "^8.2.2",
    "fastify-tsconfig": "^2.0.0",
    "ts-node": "^10.4.0",
    "typescript": "^5.2.2"
  }
}

Installiamo le dipendenze del package.json

Entriamo dentro alla cartella del progetto "my-app" appena creato e installiamo tutte le dipendenze del package.json con questo comando:

npm install

Rotta root default

fastify-cli ha già creato per noi 2 rotte, le possiamo trovare dentro i file:

1. src/routes/root.ts

2. src/routes/example/index.ts

Vediamo il codice generato per la rotta root:

import { FastifyPluginAsync } from "fastify"

const example: FastifyPluginAsync = async (fastify, opts): Promise<void> => {
  fastify.get('/', async function (request, reply) {
    return 'this is an example'
  })
}

export default example;

Questa rotta definisce una chiamata HTTP GET che come riposta restituisce una stringa: 'this is an example'.

Aggiungiamo la nostra rotta

Per fare un esempio il più semplice possibile, Aggiungiamo una rotta che prende in input del testo e come risposta ritorna il testo tutto in maiuscolo.

import { FastifyPluginAsync } from "fastify"

const example: FastifyPluginAsync = async (fastify, opts): Promise<void> => {

  fastify.get('/', async function (request, reply) {
    return 'this is an example'
  })

  fastify.post('/uppercase', async function (request, reply) {
    const body = request.body
    const text = body.text
    return { textResult: text.toUpperCase()} 
  })

}

export default example;

Abbiamo aggiunto una rotta di tipo POST, la rotta si aspetta nel body una sola proprietà 'text' e ritorna un oggetto con un unica proprietà 'textResult'.

Errore Typescript

A questo punto Typescript genererà un errore, perché inizialmente body è typo unknown, quindi dobbiamo tipizzare l'oggetto body.

Potremmo tipizzare l'oggetto body direttamente con un interfaccia Typescript, ma siccome useremo uno schema per validare la rotta, lasceremo generare i tipi Typescript direttamente dal nostro schema, così da avere una sola fonte della verità.

Installiamo la libreria type-provider-typebox

npm i @fastify/type-provider-typebox

Creiamo lo schema con Typebox

import { Type } from '@fastify/type-provider-typebox'
import { FastifyPluginAsync } from "fastify"

const example: FastifyPluginAsync = async (fastify, opts): Promise<void> => {

  fastify.get('/', async function (request, reply) {
    return 'this is an example'
  })

  fastify.post('/uppercase', {
    schema: {
      body: Type.Object({
        text: Type.String(),
      }),
      response: {
        200: Type.Object({ 
          textResult: Type.String() 
        }),
      }
    }
  }, async function (request, reply) {
    const body = request.body
    const text = body.text
    return { textResult: text.toUpperCase()} 
  })

}

export default example;

Ora abbiamo creato uno schema che definisce che:

• nel body accetta solo una proprietà 'text' di tipo stringa

• come risposta restituisce un oggetto con solo una proprietà 'textResult' di tipo stringa

Lo schema fa si che:

• Il cliente se nel body non passa esattamente un oggetto con una proprietà 'text' di tipo stringa riceverà un errore 404

• Il server se non ritorna esattamente un oggetto con dentro la proprietà 'textResult' di tipo stringa, il cliente riceverà un errore 500

Ma c'è ancora un problema, lo schema è giusto ma Typescript ancora non compila perché request.body è ancora di tipo unknown.

Usiamo lo schema per generare i tipi per la rotta

import { Type, FastifyPluginAsyncTypebox } from '@fastify/type-provider-typebox'

const example: FastifyPluginAsyncTypebox = async (fastify, opts): Promise<void> => {

  fastify.get('/', async function (request, reply) {
    return 'this is an example'
  })

  fastify.post('/uppercase', {
    schema: {
      body: Type.Object({
        text: Type.String(),
      }),
      response: {
        200: Type.Object({ 
          textResult: Type.String() 
        }),
      }
    }
  }, async function (request, reply) {
    const body = request.body
    const text = body.text
    return { textResult: text.toUpperCase()} 
  })

}

export default example;

Ci basta solo sostituire il tipo:

• FastifyPluginAsync (tipo per il plugin importato direttamente da 'fastify')

Con il tipo:

• FastifyPluginAsyncTypebox (tipo per il plugin importato da '@fastify/type-provider-typebox')

Refactoring

Cosi funziona tutto, ma personalmente per maggiore leggibilità preferisco separare la funzione della rotta e lo schema dalla dichiarazione della rotta stessa.

import { Type, FastifyPluginAsyncTypebox } from '@fastify/type-provider-typebox'
import { FastifyReply, FastifyRequest } from 'fastify'

const example: FastifyPluginAsyncTypebox = async (fastify, opts): Promise<void> => {

  fastify.get('/', async function (request, reply) {
    return 'this is an example'
  })

  const schemaPostUppercase = {
    body: Type.Object({
      text: Type.String(),
    }),
    response: {
      200: Type.Object({ 
        textResult: Type.String() 
      }),
    }
  }

  async function postUppercase(request: FastifyRequest, reply: FastifyReply) {
    const body = request.body
    const text = body.text
    return { textResult: text.toUpperCase()} 
  }

  fastify.post('/uppercase', { schema: schemaPostUppercase }, postUppercase)

}

export default example;

In questo modo abbiamo separato lo schema nella variabile: schemaPostUppercase e l'handler della rotta nella funzione: postUppercase.

Però ora Typescript non è più in grado di tipizzare il body ed il ritorno della funzione e genera l'errore:

E da notare anche che il ritorno non è più tipizzato. Infatti Typescript ci permette di fare questo:

return { hello: text.toUpperCase()}

Ritornare la proprietà 'hello' dovrebbe generare un errore di compilazione Typescript, perché non rispetta lo schema che invece definisce che nella risposta ci sia solo la proprietà 'textResult'.

Questo perché la rotta non prende più i tipi dallo schema.

Tipizzazione dell'handler della rotta

import { Type, FastifyPluginAsyncTypebox, TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
import { ContextConfigDefault, FastifyBaseLogger, FastifyInstance, FastifyReply, FastifyRequest, FastifySchema, RawReplyDefaultExpression, RawRequestDefaultExpression, RawServerDefault, RouteGenericInterface } from 'fastify'
import { ResolveFastifyReplyReturnType } from 'fastify/types/type-provider'

type FastifyInstanceTypebox = FastifyInstance<
  RawServerDefault,
  RawRequestDefaultExpression<RawServerDefault>,
  RawReplyDefaultExpression,
  FastifyBaseLogger,
  TypeBoxTypeProvider
>

type FastifyRequestTypebox<TSchema extends FastifySchema> = FastifyRequest<
  RouteGenericInterface,
  RawServerDefault,
  RawRequestDefaultExpression<RawServerDefault>,
  TSchema,
  TypeBoxTypeProvider
>

type FastifyReplyTypebox<TSchema extends FastifySchema> = FastifyReply<
  RawServerDefault,
  RawRequestDefaultExpression,
  RawReplyDefaultExpression,
  RouteGenericInterface,
  ContextConfigDefault,
  TSchema,
  TypeBoxTypeProvider
>

export type RouteHandlerTypebox<TSchema extends FastifySchema> = (
  this: FastifyInstanceTypebox,
  request: FastifyRequestTypebox<TSchema>,
  reply: FastifyReplyTypebox<TSchema>
) => ResolveFastifyReplyReturnType<TypeBoxTypeProvider, TSchema, RouteGenericInterface>

const example: FastifyPluginAsyncTypebox = async (fastify, opts): Promise<void> => {

  fastify.get('/', async function (request, reply) {
    return 'this is an example'
  })

  const schemaPostUppercase = {
    body: Type.Object({
      text: Type.String(),
    }),
    response: {
      200: Type.Object({ 
        textResult: Type.String() 
      }),
    }
  }

  const postUppercase: RouteHandlerTypebox<typeof schemaPostUppercase> = async function (request, reply) {
    const body = request.body
    const text = body.text
    return { textResult: text.toUpperCase()} 
  }

  fastify.post('/uppercase', { schema: schemaPostUppercase }, postUppercase)

}

export default example;

Purtroppo per poter separare la dichiarazione della funzione 'postUppercase' dalla definizione della rotta bisogna creare a mano il suo tipo.

Per semplicità ho definito tutti i tipi all'interno dello stesso file, ma in un progetto reale generalmente si definiscono i tipi in un file separato ed importati nei file in cui vengono utilizzati.

Vediamo passo dopo passo questo processo:

• Abbiamo trasformato la funzione postUppercase da così:

async function postUppercase(request: FastifyRequest, reply: FastifyReply) {
    const body = request.body
    const text = body.text
    return { textResult: text.toUpperCase()} 
}

• A così:

const postUppercase: RouteHandlerTypebox<typeof schemaPostUppercase> = async function (request, reply) {
    const body = request.body
    const text = body.text
    return { textResult: text.toUpperCase()} 
}

postUppercase diventa da una funzione ad una variabile che contiene una funzione anonima, questa sintassi ci permette di definire i tipi per i parametri, il ritorno ed il contesto (this) della funzione con un solo tipo:

RouteHandlerTypebox<typeof schemaPostUppercase>

Vediamo la sua definizione:

export type RouteHandlerTypebox<TSchema extends FastifySchema> = (
  this: FastifyInstanceTypebox,
  request: FastifyRequestTypebox<TSchema>,
  reply: FastifyReplyTypebox<TSchema>
) => ResolveFastifyReplyReturnType<TypeBoxTypeProvider, TSchema, RouteGenericInterface>

Nel tipo RouteHandlerTypebox, stiamo andando a definire i tipi per:

• this: il contesto della funzione ovvero quando si vuole accedere all'oggetto 'fastify' tramite 'this'.

• request: il primo parametro della funzione

• reply: il secondo parametro della funzione

• ritorno della funzione: ResolveFastifyReplyReturnType

Di fatto manualmente tipizzando con lo schema: request, reply ed il ritorno della funzione, che prendono il tipo generico: TSchema.

Manuel Salinardi