Moduli: TypeScript

[Cronologia]

Versione	Modifiche
v22.7.0	Aggiunto flag --experimental-transform-types.

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1.1 - Sviluppo attivo

Abilitazione

Esistono due modi per abilitare il supporto runtime di TypeScript in Node.js:

Supporto completo di TypeScript

Per utilizzare TypeScript con pieno supporto per tutte le funzionalità di TypeScript, incluso tsconfig.json, è possibile utilizzare un pacchetto di terze parti. Queste istruzioni utilizzano tsx come esempio, ma sono disponibili molte altre librerie simili.

Rimozione dei tipi

Aggiunto in: v22.6.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1.1 - Sviluppo attivo

Il flag --experimental-strip-types consente a Node.js di eseguire file TypeScript. Per impostazione predefinita, Node.js eseguirà solo i file che non contengono funzionalità TypeScript che richiedono trasformazione, come enum o namespace. Node.js sostituirà le annotazioni di tipo inline con spazi bianchi e non verrà eseguito alcun controllo dei tipi. Per abilitare la trasformazione di tali funzionalità, utilizzare il flag --experimental-transform-types. Le funzionalità di TypeScript che dipendono dalle impostazioni all'interno di tsconfig.json, come i percorsi o la conversione di sintassi JavaScript più recenti in standard più vecchi, non sono intenzionalmente supportate. Per ottenere il supporto completo di TypeScript, vedere Supporto completo di TypeScript.

La funzionalità di rimozione dei tipi è progettata per essere leggera. Evitando intenzionalmente di supportare sintassi che richiedono la generazione di codice JavaScript e sostituendo i tipi inline con spazi bianchi, Node.js può eseguire codice TypeScript senza la necessità di mappe di origine.

La rimozione dei tipi funziona con la maggior parte delle versioni di TypeScript, ma si consiglia la versione 5.7 o successiva con le seguenti impostazioni tsconfig.json:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "verbatimModuleSyntax": true
  }
}

Determinazione del sistema di moduli

Node.js supporta sia la sintassi CommonJS che ES Modules nei file TypeScript. Node.js non convertirà da un sistema di moduli all'altro; se si desidera che il codice venga eseguito come modulo ES, è necessario utilizzare la sintassi import ed export, e se si desidera che il codice venga eseguito come CommonJS è necessario utilizzare require e module.exports.

• I file .ts avranno il loro sistema di moduli determinato nello stesso modo dei file .js. Per utilizzare la sintassi import ed export, aggiungere "type": "module" al file package.json padre più vicino.
• I file .mts saranno sempre eseguiti come moduli ES, in modo simile ai file .mjs.
• I file .cts saranno sempre eseguiti come moduli CommonJS, in modo simile ai file .cjs.
• I file .tsx non sono supportati.

Come nei file JavaScript, le estensioni dei file sono obbligatorie nelle istruzioni import e nelle espressioni import():import './file.ts', non import './file'. A causa della compatibilità con le versioni precedenti, le estensioni dei file sono obbligatorie anche nelle chiamate require():require('./file.ts'), non require('./file'), in modo simile a come l'estensione .cjs è obbligatoria nelle chiamate require nei file CommonJS.

L'opzione tsconfig.json allowImportingTsExtensions consentirà al compilatore TypeScript tsc di verificare i tipi dei file con specificatori import che includono l'estensione .ts.

Funzionalità TypeScript

Poiché Node.js rimuove solo i tipi inline, qualsiasi funzionalità TypeScript che prevede la sostituzione della sintassi TypeScript con una nuova sintassi JavaScript genererà un errore, a meno che non venga passato il flag --experimental-transform-types.

Le funzionalità più importanti che richiedono la trasformazione sono:

• Enum
• namespaces
• legacy module
• proprietà dei parametri

Poiché i Decoratori sono attualmente una proposta TC39 Stage 3 e saranno presto supportati dal motore JavaScript, non vengono trasformati e provocheranno un errore del parser. Questa è una limitazione temporanea che verrà risolta in futuro.

Inoltre, Node.js non legge i file tsconfig.json e non supporta le funzionalità che dipendono dalle impostazioni all'interno di tsconfig.json, come i percorsi o la conversione di sintassi JavaScript più recenti in standard più vecchi.

Importazione di tipi senza la parola chiave type

A causa della natura della rimozione dei tipi, la parola chiave type è necessaria per rimuovere correttamente le importazioni di tipo. Senza la parola chiave type, Node.js tratterà l'importazione come un'importazione di valore, il che si tradurrà in un errore di runtime. L'opzione tsconfig verbatimModuleSyntax può essere utilizzata per corrispondere a questo comportamento.

Questo esempio funzionerà correttamente:

import type { Type1, Type2 } from './module.ts'
import { fn, type FnParams } from './fn.ts'

Questo si tradurrà in un errore di runtime:

import { Type1, Type2 } from './module.ts'
import { fn, FnParams } from './fn.ts'

Forme di input non di file

La rimozione dei tipi può essere abilitata per --eval. Il sistema di moduli sarà determinato da --input-type, come per JavaScript.

La sintassi TypeScript non è supportata nella REPL, nell'input STDIN, in --print, --check e inspect.

Source map

Poiché i tipi inline vengono sostituiti da spazi bianchi, le source map non sono necessarie per i numeri di riga corretti negli stack trace; e Node.js non li genera. Quando --experimental-transform-types è abilitato, le source map sono abilitate per impostazione predefinita.

Rimozione dei tipi nelle dipendenze

Per scoraggiare gli autori di package dalla pubblicazione di package scritti in TypeScript, Node.js rifiuterà per impostazione predefinita di gestire i file TypeScript all'interno delle cartelle sotto un percorso node_modules.

Alias dei percorsi

tsconfig "paths" non verrà trasformato e quindi produrrà un errore. La funzionalità più vicina disponibile è importazioni subpath con la limitazione che devono iniziare con #.