TypeScript - Namespace

The namespace is used for logical grouping of functionalities. A namespace can include interfaces, classes, functions and variables to support a single or a group of related functionalities.

A namespace can be created using the namespace keyword followed by the namespace name. All the interfaces, classes etc. can be defined in the curly brackets { }.

Syntax:
namespace <name>
{
    
}

Consider the following example of different string functions in the StringUtilities namespace.

StringUtility.ts
namespace StringUtility 
{
    function ToCapital(str: string): string {
        return str.toUpperCase();
    }

    function SubString(str: string, from: number, length: number = 0): string {
        return str.substr(from, length);
    }
}

The above StringUtility.ts file includes the namespace StringUtility which includes two simple string functions. The StringUtility namespace makes a logical grouping of the important string functions for our application.

By default, namespace components cannot be used in other modules or namespaces. You must export each component to make it accessible outside, using the export keyword as shown below.

Example: Use export in Namespace
namespace StringUtility {

    export function ToCapital(str: string): string {
        return str.toUpperCase();
    }

    export function SubString(str: string, from: number, length: number = 0): string {
        return str.substr(from, length);
    }
}

Now, we can use the StringUtility namespace elsewhere. The following JavaScript code will be generated for the above namespace.

JavaScript: StringUtility.js
var StringUtility;
(function (StringUtility) {
    function ToCapital(str){
        return str.toUpperCase();
    }
    StringUtility.ToCapital = ToCapital;
    function SubString(str, from, length) {
        if (length === void 0) { length = 0; }
        return str.substr(from, length);
    }
    StringUtility.SubString = SubString;
})(StringUtility || (StringUtility = {}));

As you can see, the above generated JavaScript code for the namespace uses the IIFE pattern to stop polluting the global scope. Learn about different namespace patterns here.

Let's use the above StringUtility namespace in the Employee module, as shown below.

Employee.ts
/// <reference path="StringUtility.ts" />

export class Employee {
    empCode: number;
    empName: string;
    constructor(name: string, code: number) {
        this.empName = StringUtility.ToCapital(name);
        this.empCode = code;
    }
    displayEmployee() {
        console.log ("Employee Code: " + this.empCode + ", Employee Name: " + this.empName );
    }
}

In order to use namespace components at other places, first we need to include the namespace using the triple slash reference syntax /// <reference path="path to namespace file" />. After including the namespace file using the reference tag, we can access all the functionalities using the namespace. Above, we used the ToCapital() function like this: StringUtility.ToCapital()

Until now, we have used .ts files. But, we need .js files to include them in our application. So, we need to compile .ts files and get .js files for all our namespaces.

Compiling Namespace

Use the following --outFile command to generate a single .js file for a single namespace or multiple namespaces.

tsc --outFile File.js File.ts

In the above --outFile options, File.js is a name and path of the JavaScript file and File.ts is a namespace file name and path.

To compile StringUtility.ts, open the command prompt on Windows and execute the following command:

tsc --outFile C:\MyTypeScriptNameSpaces\StringUtility.js C:\MyTypeScriptNameSpaces\StringUtility.ts

The above command will generate the Utility.js file for StringUtility.ts.

Example:
var StringUtility;
(function (StringUtility) {
    function ToCapital(str) {
        return str.toUpperCase();
    }
    StringUtility.ToCapital = ToCapital;
    function SubString(str, from, length) {
        if (length === void 0) { length = 0; }
            return str.substr(from, length);
    }
    StringUtility.SubString = SubString;
})(StringUtility || (StringUtility = {}));

Now, we need to include the above StringUtility.js file in the HTML page <script> tag.

The following command option is used to compile multiple namespaces into a single .js file.

tsc --outFile File.js File1.ts File2.ts File3.ts.. FileN.ts

Namespace vs Module

Namespace Module
Must use the namespace keyword and the export keyword to expose namespace components. Uses the export keyword to expose module functionalities.
Used for logical grouping of functionalities with local scoping. Used to organize the code in separate files and not pollute the global scope.
To use it, it must be included using triple slash reference syntax e.g. ///<reference path="path to namespace file" />. Must import it first in order to use it elsewhere.
Compile using the --outFile command. Compile using the --module command.
Must export functions and classes to be able to access it outside the namespace. All the exports in a module are accessible outside the module.
Namespaces cannot declare their dependencies. Modules can declare their dependencies.
No need of module loader. Include the .js file of a namespace using the <script> tag in the HTML page. Must include the module loader API which was specified at the time of compilation e.g. CommonJS, require.js etc.