Modules and Namespaces

📦 TypeScript Modules & Namespaces: Your Code’s Treasure Chest System

🎭 The Story: Building Your Toy Organization Kingdom

Imagine you have a giant room full of LEGO bricks. Without boxes to organize them, finding the right piece takes forever!

Modules are like labeled boxes 📦 where you keep specific LEGO sets. Each box has a label saying what’s inside and what you can share with friends.

Namespaces are like older-style toy chests from before we had nice labeled boxes. They still work, but the new box system is much better!

Let’s explore how TypeScript helps you organize your code kingdom! 👑

🌟 ES Modules Syntax: The Modern Labeling System

ES Modules are the new, shiny way to organize code. Think of them as boxes with clear labels that say:

• What’s INSIDE the box
• What you CAN share

The Magic Words

// Each file is its own box!
// This file is called "toys.ts"

// Things inside the box
const secretToy = "hidden dragon";

// Things we want to share (put a label!)
export const car = "red race car";
export const doll = "princess doll";

Simple Idea: Each .ts file = One box. Use export to put a sharing sticker on things!

📤 Export Statements: Putting Sharing Stickers On Things

You can share things from your box in different ways:

Way 1: Individual Sharing Stickers

// Put sticker on each thing separately
export const ball = "bouncy ball";
export function jump() {
  return "boing!";
}
export class Robot {
  speak() { return "beep boop"; }
}

Way 2: One Big Sticker at the End

const ball = "bouncy ball";
function jump() { return "boing!"; }
class Robot {
  speak() { return "beep boop"; }
}

// Share everything at once!
export { ball, jump, Robot };

Way 3: Give Things Nicknames

const myFavoriteToy = "teddy bear";

// Share with a different name
export { myFavoriteToy as bear };

Way 4: The Default Star ⭐

Every box can have ONE special “star item”:

// game.ts
export default class SuperGame {
  play() { return "fun!"; }
}

📥 Import Statements: Borrowing From Other Boxes

Now let’s BORROW toys from other boxes!

Borrow Specific Things

// Grab specific toys from the toys box
import { car, doll } from './toys';

console.log(car);  // "red race car"

Borrow the Star Item

// Get the default (star) item
// You can name it whatever you want!
import MyGame from './game';

const g = new MyGame();

Borrow Everything

// Get EVERYTHING from the box
// Put it all in a basket called "AllToys"
import * as AllToys from './toys';

console.log(AllToys.car);   // "red race car"
console.log(AllToys.doll);  // "princess doll"

Rename While Borrowing

import { car as raceCar } from './toys';

console.log(raceCar);  // "red race car"

graph TD
    A["📦 toys.ts"] -->|export car| B["📥 import car"]
    A -->|export doll| C["📥 import doll"]
    B --> D["🎮 Your Game"]
    C --> D

🏷️ Type-Only Imports: Borrowing Just the Labels

Sometimes you don’t need the actual toy—you just need to know what KIND of toy it is!

The Problem

// If you import a TYPE normally,
// it might add extra code we don't need!
import { User } from './types';

// We only use User as a type hint
function greet(person: User) { ... }

The Solution: Type-Only Import

// Tell TypeScript: "I only want the label,
// not the actual thing!"
import type { User } from './types';

// Perfect for type hints
function greet(person: User) { ... }

You Can Also Export Type-Only

// types.ts
interface Dragon {
  breatheFire(): void;
}

// Only share as a type, not real code
export type { Dragon };

Why Care? Your final game (built code) becomes smaller and faster! 🚀

⏰ Dynamic Imports: Getting Toys Only When You Need Them

Imagine you’re playing a game. You don’t load ALL levels at the start—that would take forever! You load each level when you GET to it.

The Magic: import() Function

async function loadBossLevel() {
  // Only load the boss when player reaches it!
  const boss = await import('./boss-dragon');

  boss.attack();
}

Real Example: Loading Big Things Later

// Show a button
button.onclick = async () => {
  // Heavy chart library loads ONLY when clicked
  const charts = await import('big-chart-library');

  charts.draw(myData);
};

graph TD
    A["🎮 Game Starts"] --> B["Level 1 Loaded"]
    B --> C{Player Wins?}
    C -->|Yes| D["Load Level 2 NOW"]
    C -->|No| B
    D --> E["Level 2 Plays"]

Why Care? Your app starts super fast because it doesn’t load everything at once!

⏳ Import Defer Syntax: The “I’ll Get It Ready Later” Promise

This is the newest trick! It’s like telling your helper: “Prepare this box, but don’t open it until I actually need something from it.”

// Tell TypeScript to defer (wait)
import defer * as heavyMath from './heavy-math';

// Later, when you actually use it...
function calculate() {
  // NOW it gets fully loaded
  return heavyMath.complexFormula(42);
}

Think of it like: Ordering a pizza 🍕 but telling them “Don’t cook it until I text you I’m hungry!”

⚠️ Note: This is a very new feature! Make sure your TypeScript version supports it.

🗺️ Module Resolution: How TypeScript Finds Your Boxes

When you write import { toy } from './box', TypeScript needs to FIND that box!

The Two Strategies

What Happens When You Import

import { hero } from './characters';

TypeScript looks for:

1. ./characters.ts ✓
2. ./characters.tsx
3. ./characters/index.ts
4. ./characters.js

graph TD
    A["import from './box'"] --> B{Is it ./box.ts?}
    B -->|Yes| C["Found it! ✅"]
    B -->|No| D{Is it ./box/index.ts?}
    D -->|Yes| C
    D -->|No| E["Keep looking..."]

🛤️ Path Mapping: Creating Shortcuts

Tired of writing ../../../components/Button? Create shortcuts!

In tsconfig.json

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

Before vs After

// 😫 Before: Long, confusing paths
import { Button } from '../../../components/Button';
import { helper } from '../../../../utils/helper';

// 😊 After: Clean shortcuts!
import { Button } from '@components/Button';
import { helper } from '@utils/helper';

It’s like having speed-dial on your phone instead of typing the whole number every time! 📱

🏛️ Legacy Namespaces: The Old Toy Chest

Before modules existed, TypeScript had Namespaces (also called “Internal Modules”).

What They Look Like

namespace OldToyChest {
  export const dinosaur = "T-Rex";
  export function roar() {
    return "ROAR!";
  }

  // Private - stays inside
  const secretToy = "mystery egg";
}

// Use with the namespace name
console.log(OldToyChest.dinosaur);
OldToyChest.roar();

Nested Namespaces

namespace Kingdom {
  export namespace Castle {
    export const king = "Arthur";
  }
  export namespace Forest {
    export const wizard = "Merlin";
  }
}

console.log(Kingdom.Castle.king);    // "Arthur"
console.log(Kingdom.Forest.wizard);  // "Merlin"

⚠️ Important: Use Modules Instead!

// ❌ OLD WAY (namespaces)
namespace MyApp {
  export function run() { }
}

// ✅ NEW WAY (modules)
// myApp.ts
export function run() { }

Why modules are better:

• Work with modern tools (Webpack, Vite)
• Better tree-shaking (removes unused code)
• Standard JavaScript feature
• Easier to test and maintain

🎯 Quick Summary: Your Module Toolbox

🚀 You Did It!

You now understand how TypeScript organizes code like a pro organizer!

Remember:

• 📦 Files are boxes with things inside
• 🏷️ Export = sharing sticker
• 📥 Import = borrowing
• ⏰ Dynamic imports = load on demand
• 🛤️ Path mapping = shortcuts
• 🏛️ Namespaces = old way, use modules instead!

Now go organize your code kingdom! 👑✨