Best Practices for Using Namespaces with TypeScript External Modules

Introduction to the Problem

Many TypeScript developers face issues when attempting to use namespaces with external modules, as illustrated in the provided Q&A data. The user tried to define a namespace Living.Things across multiple files but encountered errors such as inability to find names or duplicate imports, stemming from misunderstandings of namespace and module concepts.

Why Namespaces in External Modules Are Problematic

In TypeScript, external modules (now simply called modules) are designed to encapsulate code and avoid polluting the global scope. When you use the export namespace syntax in a module, you create separate namespace instances for each module rather than merging them. This is analogous to having multiple boxes labeled the same but containing different items, as explained in the candy cup analogy.

For example, consider the code from the original question:

// In baseTypes.ts
export namespace Living.Things {
  export class Animal {
    move() { /* ... */ }
  }
}

// In dog.ts
import b = require('./baseTypes');
export namespace Living.Things {
  export class Dog extends Animal { // Error: Cannot find name 'Animal'
    woof() { }
  }
}

Here, the Animal class is not accessible because dog.ts has its own instance of the Living.Things namespace, and Animal is defined in a different instance. To fix this, you would need to qualify the name, but this leads to verbose code and defeats the purpose of namespaces.

Guidance for External Modules

Instead of using namespaces, follow these best practices:

• Export at the top level: If a module exports a single class or function, use export default.
• Export multiple objects at top level: For multiple exports, list them directly without nesting.
• Avoid namespaces in modules: Only use namespaces within a module if you have a large number of related types, and even then, consider if it is necessary.

Rewritten code examples based on the original:

// baseTypes.ts - Corrected
export class Animal {
  move() { /* ... */ }
}
export class Plant {
  photosynthesize() { /* ... */ }
}

// dog.ts - Corrected
import { Animal } from './baseTypes';
export class Dog extends Animal {
  woof() { }
}

// tree.ts - Corrected
import { Plant } from './baseTypes';
export class Tree extends Plant {
  // No need for namespace
}

This approach simplifies the code and avoids issues with namespace merging.

Red Flags to Avoid

Be cautious of the following:

• Files with only export namespace Foo { ... } – move exports to the top level.
• Single exports without export default.
• Multiple files using the same export namespace – they will not merge.

Conclusion

In summary, namespaces are useful for organizing code in the global scope or internal modules, but in external modules, they add unnecessary complexity. By exporting directly and using module imports, you can write cleaner and more maintainable TypeScript code.