Module Systems & Namespaces

📦 Module Systems & Namespaces

🌍 ES Modules: The Standard

ES modules (ESM) are the modern standard. Files are modules; imports/exports are explicit:

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

export const PI = 3.14159;

// app.ts
import { add, PI } from "./math";  // .ts extension is optional

console.log(add(2, 3));     // 5
console.log(PI);              // 3.14159

📼 CommonJS: Node.js Legacy

CommonJS (CJS) is Node.js's original module system. Still widely used, but ES modules are preferred:

Copy// math.ts (CommonJS style)
function add(a: number, b: number) {
  return a + b;
}

module.exports = { add };

// app.ts (CommonJS style)
const { add } = require("./math");
console.log(add(2, 3));

Copyconst math = require("./math");
module.exports = { myFunc };

Copyimport math from "./math";
export { myFunc };

🗺️ Path Mapping: Cleaner Imports

Deep nested paths are messy. Path mapping lets you create short aliases:

Copy// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@utils/*": ["src/utils/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

// Instead of:
import { formatDate } from "../../../../utils/format";

// Write:
import { formatDate } from "@utils/format";

📦 Barrel Exports: Organized Re-exports

A barrel export (index.ts) re-exports from submodules for cleaner public APIs:

Copy// src/utils/string.ts
export function capitalize(s: string) {
  return s.charAt(0).toUpperCase() + s.slice(1);
}

// src/utils/math.ts
export function sum(a: number, b: number) {
  return a + b;
}

// src/utils/index.ts (barrel export)
export * from "./string";
export * from "./math";

// app.ts — clean, single import
import { capitalize, sum } from "@utils";

Without barrel: You'd need two imports. With barrel: One import gets everything.

📋 Ambient Declarations: Types for External Code

Sometimes you use libraries without type definitions. Ambient declarations (`.d.ts` files) provide types:

Copy// types/global.d.ts
// Declare a global variable
declare const DEBUG: boolean;

// Declare a module (for libraries without types)
declare module "my-untyped-library" {
  export function doSomething(x: any): string;
}

// In app.ts
console.log(DEBUG);  // ✅ TypeScript knows about it

import { doSomething } from "my-untyped-library";
const result = doSomething(42);  // ✅ Typed

🔷 TypeScript Namespaces (Legacy Grouping)

Namespaces group related types without ES modules. They're pre-module, but still used in legacy codebases:

Copy// math.ts
namespace Math {
  export function add(a: number, b: number) {
    return a + b;
  }

  export const PI = 3.14159;
}

// app.ts
const result = Math.add(2, 3);  // Access via namespace

🏗️ Real-World Pattern: Well-Organized Project

Copy// Directory structure:
// src/
//   ├── types/          ← TypeScript types
//   │   ├── index.ts    (barrel)
//   │   └── user.ts
//   ├── utils/          ← Utility functions
//   │   ├── index.ts    (barrel)
//   │   ├── format.ts
//   │   └── validate.ts
//   ├── services/       ← Business logic
//   │   ├── index.ts    (barrel)
//   │   └── api.ts
//   └── app.ts          ← Entry point

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@types/*": ["src/types/*"],
      "@utils/*": ["src/utils/*"],
      "@services/*": ["src/services/*"]
    }
  }
}

// src/types/index.ts
export * from "./user";

// src/utils/index.ts
export * from "./format";
export * from "./validate";

// src/app.ts — clean imports
import { User } from "@types";
import { formatDate, validateEmail } from "@utils";
import { UserService } from "@services";

const user: User = { id: 1, email: "alice@example.com" };
console.log(formatDate(new Date()));

💻 Coding Challenges

🎯 What's Next

With module systems mastered, we'll explore Advanced OOP — abstract classes, access modifiers, static members, and design patterns in TypeScript.