Namespace in TypeScript: cos'è e quando usarlo

Un namespace è un blocco con nome che raggruppa funzioni, costanti e tipi sotto un solo nome. I membri marcati export sono raggiungibili come Name.member; gli altri restano privati del blocco. A runtime un namespace è un oggetto semplice.

namespace Geometry {
  const TAU = Math.PI * 2; // not exported: private to the namespace

  export function circumference(radius: number): number {
    return TAU * radius;
  }

  export function area(radius: number): number {
    return Math.PI * radius ** 2;
  }
}

console.log(Geometry.circumference(1).toFixed(2)); // 6.28
console.log(Geometry.area(2).toFixed(2));          // 12.57
console.log(Object.keys(Geometry));                // [ 'circumference', 'area' ]

In cosa viene compilato un namespace

I namespace sono una delle poche funzionalità di TypeScript che generano codice. Il blocco qui sopra diventa una funzione che riempie un oggetto:

var Geometry;
(function (Geometry) {
    const TAU = Math.PI * 2;
    function circumference(radius) {
        return TAU * radius;
    }
    Geometry.circumference = circumference;
    function area(radius) {
        return Math.PI * radius ** 2;
    }
    Geometry.area = area;
})(Geometry || (Geometry = {}));

È lo schema che il codice JavaScript usava prima che esistessero i moduli, per evitare di mettere ogni nome nello scope globale. TAU è una variabile locale della funzione, ed è per questo che il resto del codice non la vede. Provare a leggerla è un errore di compilazione:

// This does not compile: rate is not exported from the namespace.
namespace Tax {
  const rate = 0.2;
  export function withTax(price: number): number {
    return price * (1 + rate);
  }
}

console.log(Tax.withTax(100));
console.log(Tax.rate);

Il compilatore segnala index.ts(10,17): error TS2339: Property 'rate' does not exist on type 'typeof Tax'. Aggiungi export davanti a const rate ed entrambe le righe vengono eseguite.

Annidamento, fusione e alias

I namespace si possono annidare, e due blocchi con lo stesso nome si fondono in uno solo. È il Geometry || (Geometry = {}) nell'output a renderlo possibile: il secondo blocco aggiunge all'oggetto esistente. import X = A.B crea un alias breve.

namespace Shop {
  export namespace Pricing {
    export type Currency = "USD" | "EUR";
    export function format(amount: number, currency: Currency): string {
      return `${amount.toFixed(2)} ${currency}`;
    }
  }
}

// A second block with the same name adds members to Shop.
namespace Shop {
  export const name = "Corner Shop";
}

import Pricing = Shop.Pricing; // alias for the nested namespace

const c: Pricing.Currency = "EUR";
console.log(Shop.name, Pricing.format(4.5, c)); // Corner Shop 4.50 EUR

namespace A.B.C { } è una scorciatoia per tre blocchi annidati. La vecchia scrittura module Shop { } significa la stessa cosa, ma ora viene rifiutata con l'errore TS1540, A 'namespace' declaration should not be declared using the 'module' keyword. Please use the 'namespace' keyword instead.

Fusione con funzioni e classi

Un namespace può condividere il nome con una funzione, una classe o un enum e aggiungervi dei membri. È ancora il modo più pulito per descrivere una funzione che porta con sé anche delle proprietà, o una classe con degli helper attaccati.

function format(n: number): string {
  return format.prefix + n.toFixed(format.digits);
}
namespace format {
  export let prefix = "$";
  export let digits = 2;
}

console.log(format(3.5)); // $3.50
format.prefix = "EUR ";
console.log(format(3.5)); // EUR 3.50

class Temperature {
  constructor(public celsius: number) {}
}
namespace Temperature {
  export function fromFahrenheit(f: number): Temperature {
    return new Temperature(((f - 32) * 5) / 9);
  }
}

console.log(Temperature.fromFahrenheit(212)); // Temperature { celsius: 100 }

Per una classe, un metodo static fa lo stesso lavoro ed è JavaScript puro. Per una funzione, puoi anche fare a meno del namespace e assegnare format.prefix = "$" subito dopo la dichiarazione; TypeScript tiene traccia delle proprietà assegnate in quel modo.

Namespace vs moduli

Prima degli ES module, un grande programma TypeScript era fatto di molti file script che condividevano namespace globali, cuciti insieme con /// <reference path="..." /> e compilati in un solo file con outFile. I moduli hanno sostituito tutto questo: ogni file ha il suo scope, le dipendenze sono import espliciti e i bundler possono scartare gli export inutilizzati. TypeScript 7 ha rimosso outFile (errore TS5102), quindi la configurazione con namespace su più file non è più un'opzione di build.

Dentro un modulo, avvolgere tutto in un namespace aggiunge un secondo livello di nomi senza alcun vantaggio: chi importa dovrebbe scrivere Utils.Utils.format. Esporta direttamente le funzioni e lascia a chi importa la scelta di import * as Utils from "./utils.js" se vuole un prefisso.

Dove incontri ancora i namespace

I file di dichiarazione li usano per descrivere librerie che espongono un unico oggetto globale e per raggruppare tipi:

// jquery-like.d.ts: a global function that also has properties
declare function $(selector: string): unknown;
declare namespace $ {
    const version: string;
    function ajax(url: string): Promise<unknown>;
}

I pacchetti di tipi li usano per esporre tipi che puoi estendere. @types/node dichiara namespace NodeJS, e per aggiungere qualcosa alla sua interfaccia ProcessEnv da un qualsiasi modulo serve declare global:

// env.d.ts
export {};

declare global {
    namespace NodeJS {
        interface ProcessEnv {
            API_URL: string; // process.env.API_URL is now string, not string | undefined
        }
    }
}

Anche le interfacce dentro namespace fusi si fondono, ed è questo che fa funzionare l'augmentation.

Namespace e type stripping

Node 24 esegue i file .ts cancellando la sintassi dei tipi. Un namespace con valori non si può cancellare, deve essere compilato nell'oggetto mostrato sopra, quindi node app.ts si ferma con:

SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript namespace declaration is not supported in strip-only mode

Due tipi di namespace vanno bene perché spariscono del tutto: un declare namespace, e un namespace i cui membri sono tutti tipi o interfacce. L'opzione del compilatore erasableSyntaxOnly: true segnala gli altri in fase di compilazione con l'errore TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., ed è così che i progetti che girano con il type stripping li tengono fuori. node --experimental-transform-types invece compila i namespace, con un avviso sperimentale.