TypeScript Tutorial
TypeScript Namespaces
Namespaces keep names from colliding. Prefer modules in new code; still useful for grouping types.
Two libraries, one name
Programs pull in many files. Your code might define count. A library might also definecount. If both names live in the global space, the compiler cannot tell them apart. A namespace is a labeled box around names so stats.count and ui.count can both exist.
In new TypeScript, ES modules (export / import) are the usual box. Namespaces still appear in older libraries and in one-file grouping. C++ uses namespace and ::. TypeScript uses namespace and a dot: mathx.square.
A namespace of your own
Write namespace, a name, and a brace block. Functions and types inside belong to that namespace. Mark the ones callers need with export inside the block. Call them with a dot, the same way you call Math.sqrt.
Example
namespace mathx {
export function square(n: number): number {
return n * n;
}
}
console.log(mathx.square(5));
console.log(mathx.square(12));Output is 25 then 144. The function is not a global square. It ismathx.square. Other code can define a different square without colliding, as long as it sits in a different namespace or a module.
Paste this into /typescript/try. A bare square(5) is not declared. The namespace is what made the dotted name work.
Two boxes, same short name
This program puts label in two namespaces. Both functions return a string. The calls pick which one with a dot. Without namespaces, two functions named label in the same file would not compile together.
Example
namespace audio {
export function label(): string {
return "track";
}
}
namespace video {
export function label(): string {
return "frame";
}
}
console.log(audio.label());
console.log(video.label());Output is track then frame.
Group types in a namespace
A namespace can hold types as well as values. Export an interface (or a type alias) so callers writegeom.Point instead of a loose global Point. This is the remaining good use: a family of related types in one file, especially when you are not splitting modules yet.
Example
namespace geom {
export type Point = { x: number; y: number };
export function origin(): Point {
return { x: 0, y: 0 };
}
}
const p: geom.Point = geom.origin();
console.log(p.x + "," + p.y);Output is 0,0. geom.Point is the type. geom.origin is the function. One prefix covers both.
Modules first, namespaces when grouping
| Write | What you get |
|---|---|
mathx.square(5) | Your function, explicitly. |
export function in a .ts file | An ES module. Prefer this in new projects. |
import { square } from "./mathx" | Local follow-up from the modules chapter. |
namespace geom { export type Point } | A prefix for related types in one file. |
Do not wrap the whole program in namespace just because C++ used using namespace std;. TypeScript has no std box you must open. Built-ins such as Math andconsole are already qualified.
Qualify when two meanings exist
If a name appears in one place, a short function is fine. If two namespaces offer the same name, write the prefix every time. Prefer modules when you split files. Next: getters and setters, which look like fields from the outside and run code on the inside.