Comparison between modules and namespaces

Basic Concepts of Modules and Namespaces

In TypeScript, both modules and namespaces are tools for organizing code, but they serve different purposes and are implemented differently. Modules are the primary way to organize code in modern JavaScript and TypeScript, while namespaces are an earlier code organization method provided by TypeScript.

Modules use the import and export keywords to import and export functionality, with each module having its own scope. Namespaces are defined using the namespace keyword and are primarily used to organize code within the global scope.

// Module example
// math.ts
export function add(a: number, b: number): number {
  return a + b
}

// app.ts
import { add } from './math'
console.log(add(1, 2))

// Namespace example
namespace MathUtils {
  export function add(a: number, b: number): number {
    return a + b
  }
}

console.log(MathUtils.add(1, 2))

Characteristics of the Module System

TypeScript's module system follows the ES module standard and has the following features:

1. File as Module: Each .ts file is an independent module.
2. Explicit Export: Must use the export keyword to explicitly export functionality for use in other modules.
3. Multiple Import Methods: Supports named imports, default imports, and namespace imports.
4. Static Analysis: Module dependencies can be determined at compile time.

Modules support various export methods:

// Named export
export const PI = 3.14
export function circleArea(r: number) {
  return PI * r * r
}

// Default export
export default class Calculator {
  // ...
}

// Re-export
export { PI as PiValue } from './constants'

Characteristics of Namespaces

Namespaces are a TypeScript-specific feature primarily used for:

1. Avoiding Global Pollution: Organizing related code within a namespace.
2. Logical Grouping: Grouping related functionality together.
3. Compatibility: Use in non-modular environments.

Namespaces can be nested and support splitting across files:

// shapes.ts
namespace Shapes {
  export namespace Polygons {
    export class Triangle {}
    export class Square {}
  }
}

// app.ts
/// <reference path="shapes.ts" />
const tri = new Shapes.Polygons.Triangle()

Key Differences Between Modules and Namespaces

1. Scope:

   • Modules have their own scope and require explicit imports/exports.
   • Namespaces exist in the global scope and are accessed via the namespace name.

2. File Organization:

   • Modules typically follow a one-file-per-module approach.
   • Namespaces can span multiple files.

3. Dependency Loading:

   • Module dependencies are handled by the module loader.
   • Namespace dependencies require manual management (e.g., using /// <reference>).

4. Modernity:

   • Modules are part of the ES6 standard.
   • Namespaces are a TypeScript-specific feature.

When to Use Modules

Modules are the preferred approach for modern TypeScript projects, especially in the following scenarios:

1. Large Projects: Require good code organization and clear dependency relationships.
2. Integration with Frontend Frameworks: Such as React, Vue, Angular, etc.
3. Tree-Shaking Needed: Modules can be optimized by bundling tools.

// Example of a modern modular component
// Button.tsx
import React from 'react'

interface ButtonProps {
  onClick: () => void
  children: React.ReactNode
}

export function Button({ onClick, children }: ButtonProps) {
  return <button onClick={onClick}>{children}</button>
}

// App.tsx
import { Button } from './Button'

function App() {
  return <Button onClick={() => console.log('Clicked')}>Click me</Button>
}

When to Use Namespaces

Namespaces may be more useful in the following cases:

1. Legacy Code Maintenance: Need to maintain compatibility with older TypeScript code.
2. Type Definition Files: Organizing types in .d.ts files.
3. Simple Web Scripts: Small projects that don't require complex build tools.

// Using namespaces in type definitions
declare namespace Express {
  interface Request {
    user?: {
      id: string
      name: string
    }
  }
}

// Simple web script
namespace MyApp {
  export function init() {
    document.getElementById('btn')?.addEventListener('click', handleClick)
  }

  function handleClick() {
    console.log('Button clicked')
  }
}

MyApp.init()

Combining Modules and Namespaces

In some cases, modules and namespaces can be used together:

// geometry.ts
export namespace Geometry {
  export class Point {
    constructor(public x: number, public y: number) {}
  }

  export function distance(p1: Point, p2: Point) {
    return Math.sqrt(Math.pow(p2.x - p1.x, 2) + Math.pow(p2.y - p1.y, 2))
  }
}

// app.ts
import { Geometry } from './geometry'

const p1 = new Geometry.Point(0, 0)
const p2 = new Geometry.Point(3, 4)
console.log(Geometry.distance(p1, p2))

Module Resolution Strategies

TypeScript supports different module resolution strategies:

1. Classic: TypeScript's traditional resolution method.
2. Node: Simulates Node.js's module resolution method.

Can be configured in tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

Module resolution attempts the following extensions:

• .ts
• .tsx
• .d.ts
• .js
• .jsx

Implementation Details of Namespaces

Namespaces are compiled into IIFEs (Immediately Invoked Function Expressions) in JavaScript:

namespace MyNamespace {
  export const value = 42
  export function doSomething() {
    console.log(value)
  }
}

Compiled to:

var MyNamespace
;(function (MyNamespace) {
  MyNamespace.value = 42
  function doSomething() {
    console.log(MyNamespace.value)
  }
  MyNamespace.doSomething = doSomething
})(MyNamespace || (MyNamespace = {}))

Code Generation for Modules

TypeScript can generate different module code based on configuration:

{
  "compilerOptions": {
    "module": "es2015" // Can also be commonjs, amd, umd, etc.
  }
}

ES Module:

// math.ts
export function square(x: number) {
  return x * x
}

// Compiled to
export function square(x) {
  return x * x
}

CommonJS Module:

// Compiled to
exports.square = function (x) {
  return x * x
}

Performance Considerations for Modules and Namespaces

1. Modules:

   • Modern bundling tools can optimize modules (tree-shaking).
   • Support on-demand loading.
   • Static analysis aids performance optimization.

2. Namespaces:

   • All code is in a single scope.
   • Cannot perform tree-shaking.
   • Suitable for small applications; large applications may cause performance issues.

Best Practices for Large Projects

For modern TypeScript projects:

1. Prefer Modules: Modules are standard and have better tool support.
2. Limit Namespace Usage: Use only in type definitions or special cases.
3. Consistent Code Style: Use modules or namespaces uniformly across the project.
4. Leverage Module Code Splitting: Improve application loading performance.

// Recommended project structure
// components/
//   Button/
//     index.ts
//     Button.tsx
//     styles.css
//     types.ts
// utils/
//   math.ts
//   string.ts

Common Issues and Solutions

1. Naming Conflicts:

   • Modules: Naturally avoided since each module has its own scope.
   • Namespaces: Require nested namespaces to resolve.

2. Circular Dependencies:

   • Modules: Require careful code structure design.
   • Namespaces: Rarely occur since everything is in the global scope.

3. Type Extensions:

   • Modules: Use declaration merging.
   • Namespaces: Add directly within the namespace.

// Declaration merging in modules
// original.ts
export interface User {
  id: string
  name: string
}

// extension.ts
import { User } from './original'

declare module './original' {
  interface User {
    email?: string
  }
}

const user: User = {
  id: '1',
  name: 'Alice',
  email: 'alice@example.com'
}