TypeScript Namespaces

TypeScript Namespaces: Encapsulation & Code Organization

Namespaces (formerly known as "Internal Modules") provide a way to group related code, functions, interfaces, and classes under a single global name to prevent global scope pollution.

ES Modules vs Namespaces

[!NOTE]
Modern TypeScript codebases strongly favor ES Modules (import / export) over namespaces. Namespaces are primarily used when organizing legacy global script libraries or complex .d.ts declaration files.

Practical Code Example

namespace Validation {
  const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  const PHONE_REGEX = /^\+?[1-9]\d{1,14}$/;

  export function isValidEmail(email: string): boolean {
    return EMAIL_REGEX.test(email);
  }

  export function isValidPhone(phone: string): boolean {
    return PHONE_REGEX.test(phone);
  }

  // Nested Namespace
  export namespace Security {
    export function sanitizeInput(input: string): string {
      return input.replace(/<[^>]*>/g, "");
    }
  }
}

// Usage
console.log("Email Valid:", Validation.isValidEmail("[email protected]"));
console.log("Phone Valid:", Validation.isValidPhone("+1234567890"));
console.log("Sanitized:", Validation.Security.sanitizeInput("<script>alert('xss')</script>Hello"));

Best Practices & Gotchas

• Prefer ES Modules (export / import): Modules support tree-shaking, static analysis, and standard JavaScript tooling.
• Use Namespaces for Ambient Declaration Bundles: Namespaces are useful inside ambient .d.ts definition files for legacy global UMD packages.
• Do Not Mix Namespaces with ES Modules: Avoid wrapping ES module files inside namespace blocks.

Self-Check Challenge

What keyword must be placed before a function inside a namespace to make it accessible outside the namespace? (Answer: export)