Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

A TypeScript namespace is a language-specific organizational mechanism used to group logically related code and prevent global scope pollution. Under the hood, the TypeScript compiler translates a namespace into a globally accessible JavaScript object via an Immediately Invoked Function Expression (IIFE).

​
Syntax and Encapsulation

Namespaces are declared using the namespace keyword. By default, all interfaces, classes, functions, and variables declared within a namespace are lexically scoped to that namespace and are inaccessible from the outside. To expose members to the external scope, they must be prefixed with the export modifier. 
namespace MathOperations {
    // Private to the namespace
    const PI = 3.14159; 

    // Accessible externally
    export function add(x: number, y: number): number {
        return x + y;
    }
}

// Accessing exported members via dot notation
const sum = MathOperations.add(5, 10);

​
Compilation Output

To understand namespace mechanics, it is necessary to examine the emitted JavaScript. TypeScript utilizes an IIFE that passes the namespace identifier as an argument, mutating it to attach exported members. 
var MathOperations;
(function (MathOperations) {
    var PI = 3.14159;
    function add(x, y) {
        return x + y;
    }
    MathOperations.add = add; // Exported member attached to the object
})(MathOperations || (MathOperations = {}));

​
Nested Namespaces

Namespaces can be nested to create deep hierarchical structures. Each nested namespace must also be explicitly exported if it needs to be accessed from outside the parent namespace. 
namespace Geometry {
    export namespace TwoDimensional {
        export class Square {
            constructor(public sideLength: number) {}
        }
    }
}

const mySquare = new Geometry.TwoDimensional.Square(10);

​
Namespace Aliasing

To mitigate verbose dot-notation chains in deeply nested namespaces, TypeScript provides a specific aliasing syntax using the import keyword. This is distinct from ES6 module imports and acts strictly as a local reference to the namespace path. 
namespace Core {
    export namespace Utilities {
        export namespace Formatting {
            export function capitalize(val: string): string {
                return val.charAt(0).toUpperCase() + val.slice(1);
            }
        }
    }
}

// Creating a local alias
import Formatter = Core.Utilities.Formatting;

const text = Formatter.capitalize("typescript");

​
Declaration Merging across Multiple Files

Namespaces support declaration merging. If multiple blocks or files declare a namespace with the identical identifier, the TypeScript compiler merges them into a single shared namespace object. When splitting namespaces across multiple files, triple-slash directives (/// <reference path="..." />) are used to instruct the compiler on file dependencies. 
// validation-interfaces.ts
namespace Validation {
    export interface StringValidator {
        isAcceptable(s: string): boolean;
    }
}

// letters-validator.ts
/// <reference path="validation-interfaces.ts" />
namespace Validation {
    export class LettersOnlyValidator implements StringValidator {
        isAcceptable(s: string) {
            return /^[A-Za-z]+$/.test(s);
        }
    }
}
During compilation, if the --outFile flag is used, TypeScript will concatenate these files in the order specified by the reference tags, resulting in a single IIFE that sequentially builds out the Validation object.
Master TypeScript with Deep Grasping Methodology!Learn More