Type System Behavior

🎭 The Shape-Shifter’s Guide to TypeScript Types

A story about shapes, puzzles, and secret identities

Once Upon a Time in TypeLand…

Imagine a magical kingdom where every object has a shape. Not round or square—but a pattern of what it contains. In TypeLand, the rulers don’t care about your name. They only care about your shape.

This is the story of how TypeScript decides who fits where.

🧩 Chapter 1: Structural Typing — It’s All About Shape

The Shape Detective

In TypeLand, there’s a detective who checks if things fit together. But here’s the twist: she doesn’t check ID cards. She checks shapes.

💡 The Big Idea: TypeScript uses structural typing. If two things have the same shape, they’re compatible—even if they have different names!

A Simple Example

type Dog = { name: string; bark: () => void };
type Wolf = { name: string; bark: () => void };

const myWolf: Wolf = {
  name: "Shadow",
  bark: () => console.log("Howl!")
};

// This works! Same shape!
const myDog: Dog = myWolf;

The detective sees:

• Dog needs: name (string) + bark (function)
• Wolf has: name (string) + bark (function)
• ✅ Match!

Real World Analogy

Think of a puzzle piece. It doesn’t matter if you painted it red or blue. If the bumps and holes match, it fits!

graph TD
    A["Object with Shape"] --> B{Does shape match?}
    B -->|Yes| C["✅ Compatible"]
    B -->|No| D["❌ Error"]

🔄 Chapter 2: Type Compatibility — The Fitting Game

More Shape Means More Power

Here’s a fun rule: An object with MORE properties can fit into a slot that needs FEWER properties.

Why? Because it still has everything needed!

type Animal = { name: string };
type Cat = { name: string; meow: () => void };

const kitty: Cat = {
  name: "Whiskers",
  meow: () => console.log("Meow!")
};

// Cat has MORE than Animal needs
// So Cat fits into Animal! ✅
const pet: Animal = kitty;

Think of it like this:

• Animal needs: a name ✓
• Cat has: a name ✓ AND a meow bonus
• Extra stuff? No problem!

The Direction Matters

// But this FAILS! ❌
const myCat: Cat = { name: "Fluffy" };
// Error! Animal is missing 'meow'

Animal doesn’t have everything Cat needs. It’s like trying to fit a small key into a big lock—doesn’t work!

🚨 Chapter 3: Excess Property Checking — The Strict Guard

Meet the Picky Guard

When you create an object directly (inline), TypeScript becomes extra careful. It checks for extra properties that weren’t expected.

type Person = { name: string; age: number };

// This FAILS! ❌
const bob: Person = {
  name: "Bob",
  age: 30,
  hobby: "fishing"  // Error! Extra property!
};

Wait—didn’t we just say extra is okay? Here’s the twist:

The Escape Routes

Route 1: Use a Variable

const bobData = {
  name: "Bob",
  age: 30,
  hobby: "fishing"
};

// Now it works! ✅
const bob: Person = bobData;

Route 2: Type Assertion

const bob = {
  name: "Bob",
  age: 30,
  hobby: "fishing"
} as Person;  // ✅ Works!

Why So Strict Inline?

TypeScript thinks: “If you’re typing this directly, you probably made a typo!” It’s protecting you from mistakes like:

type Config = { color: string };

// Oops! Typo caught! ✅
const settings: Config = {
  colour: "blue"  // Error! Did you mean 'color'?
};

⚖️ Chapter 4: Variance in Types — The Direction Rules

The Two-Way Street

Variance is about direction. When can a parent type replace a child? When can a child replace a parent?

Covariance: Same Direction ↓

For return types and readonly properties, the rule is simple:

• More specific → Less specific: ✅ OK
• Less specific → More specific: ❌ NOPE

type Animal = { name: string };
type Dog = { name: string; breed: string };

type GetAnimal = () => Animal;
type GetDog = () => Dog;

// GetDog can be used as GetAnimal ✅
// (Dog is MORE specific than Animal)
const fetchPet: GetAnimal = (() => ({
  name: "Rex",
  breed: "Husky"
})) as GetDog;

Contravariance: Opposite Direction ↑

For function parameters, it flips!

• Less specific → More specific: ✅ OK
• More specific → Less specific: ❌ NOPE

type HandleAnimal = (a: Animal) => void;
type HandleDog = (d: Dog) => void;

// HandleAnimal can be used as HandleDog ✅
const petHandler: HandleDog = ((animal: Animal) => {
  console.log(animal.name);
}) as HandleAnimal;

Memory Trick

graph TD
    A["Variance Types"] --> B["Covariance"]
    A --> C["Contravariance"]
    B --> D["Returns: Specific → General ✅"]
    C --> E["Params: General → Specific ✅"]

• Co = same direction (returns)
• Contra = opposite direction (params)

🏷️ Chapter 5: Branded Types — Secret Identity Cards

The Problem with Shapes

Remember our shape detective? Sometimes, same shapes cause trouble:

type UserId = string;
type ProductId = string;

function getUser(id: UserId) { /* ... */ }

const productId: ProductId = "prod-123";
getUser(productId);  // No error! 😱

Both are strings! TypeScript can’t tell them apart!

The Solution: Brand It!

We add a secret brand—a hidden mark that makes types unique:

type UserId = string & { __brand: "UserId" };
type ProductId = string & { __brand: "ProductId" };

// Helper functions to create branded values
function createUserId(id: string): UserId {
  return id as UserId;
}

function createProductId(id: string): ProductId {
  return id as ProductId;
}

Now they’re different!

const userId = createUserId("user-456");
const productId = createProductId("prod-123");

function getUser(id: UserId) { /* ... */ }

getUser(userId);     // ✅ Works!
getUser(productId);  // ❌ Error! Type mismatch!

Real World Use Cases

// Money that can't be mixed up
type USD = number & { __brand: "USD" };
type EUR = number & { __brand: "EUR" };

// Validated strings
type Email = string & { __brand: "Email" };
type URL = string & { __brand: "URL" };

The Brand Pattern

graph TD
    A["Plain Type"] --> B["Add Brand"]
    B --> C["Unique Type!"]
    C --> D["Can't mix with others ✅"]

🎯 The Complete Picture

graph LR
    A["Type System Behavior"] --> B["Structural Typing"]
    A --> C["Type Compatibility"]
    A --> D["Excess Property Check"]
    A --> E["Variance"]
    A --> F["Branded Types"]

    B --> B1["Shape matters, not names"]
    C --> C1["More props → fits fewer needs"]
    D --> D1["Inline objects checked strictly"]
    E --> E1["Direction rules for functions"]
    F --> F1["Secret tags for uniqueness"]

🌟 Key Takeaways

🚀 You Did It!

You’ve mastered the five pillars of TypeScript’s type system behavior! Now you understand:

• Why TypeScript cares about shapes, not names
• When extra properties are allowed vs blocked
• How variance controls function compatibility
• How to create unmixable types with brands

Go forth and type safely! 🎉