TypeScript Fundamentals - Types & Type System

The Production Bug That Taught Me Type Safety

Three months into using TypeScript, I thought I understood types. Primitives, arrays, objects - simple stuff. Then I merged a seemingly innocent PR:

interface Config {
    port: number;
    timeout: number;
    retries: number;
}

function startServer(config: Config) {
    server.listen(config.port);
    http.setTimeout(config.timeout);
    http.setMaxRetries(config.retries);
}

// Load from environment
const config: Config = {
    port: process.env.PORT,        // ← Looks fine to TypeScript!
    timeout: process.env.TIMEOUT,
    retries: process.env.RETRIES
};

startServer(config);

TypeScript compiled without errors. Tests passed. Deployed to production. Within 5 minutes, our API was down.

The problem? process.env.PORT returns a string, not a number. JavaScript's type coercion made server.listen("8080") work locally, but our load balancer expected a numeric port. The server was listening on port 0 (failed coercion) and became unreachable.

The fix:

const config: Config = {
    port: parseInt(process.env.PORT || "8080", 10),
    timeout: parseInt(process.env.TIMEOUT || "30000", 10),
    retries: parseInt(process.env.RETRIES || "3", 10)
};

The lesson: TypeScript's type system is powerful, but you must understand how types work to use it effectively. process.env returns string | undefined, but I assumed it would enforce number.

This article covers everything you need to know about TypeScript's type system to avoid mistakes like mine.

Basic Types

TypeScript provides several primitive types that correspond to JavaScript primitives.

String

let message: string = "Hello, TypeScript";
let template: string = `Port: ${8080}`;
let name: string = 'Alice';

// Error examples
let invalid: string = 42;  // ✗ Error: Type 'number' is not assignable to type 'string'

Number

TypeScript has one number type for all numeric values (integers, floats, hex, binary):

let count: number = 42;
let price: number = 19.99;
let hex: number = 0xff;
let binary: number = 0b1010;
let octal: number = 0o744;

// All numbers - no separate integer type
let big: number = 1_000_000;  // Underscores for readability

Boolean

let isActive: boolean = true;
let hasPermission: boolean = false;

// Not a boolean!
let truthyValue: boolean = 1;  // ✗ Error: Type 'number' is not assignable to type 'boolean'

Null and Undefined

let nothing: null = null;
let notDefined: undefined = undefined;

// With strictNullChecks: true (recommended)
let name: string = null;  // ✗ Error
let age: number = undefined;  // ✗ Error

// Must explicitly allow null/undefined
let optionalName: string | null = null;  // ✓ Valid
let maybeAge: number | undefined = undefined;  // ✓ Valid

Any

The any type disables type checking - use sparingly:

let flexible: any = "Hello";
flexible = 42;        // ✓ Valid
flexible = true;      // ✓ Valid
flexible.doAnything();  // ✓ No compile error (runtime error though!)

// Problem: any spreads like a virus
function process(data: any): any {
    return data.value;  // No type checking
}

const result = process({ value: 42 });
result.toUpperCase();  // ✓ Compiles, ✗ Runtime error

When to use any:

• Migrating JavaScript to TypeScript incrementally

• Working with truly dynamic data (rare)

• Third-party libraries without types (use unknown instead if possible)

Unknown

The type-safe alternative to any - requires type checking before use:

let userInput: unknown = getUserInput();

// Cannot use unknown directly
userInput.toUpperCase();  // ✗ Error: Object is of type 'unknown'

// Must narrow the type first
if (typeof userInput === "string") {
    userInput.toUpperCase();  // ✓ Valid - TypeScript knows it's a string
}

// Type guard example
function processUnknown(value: unknown): string {
    if (typeof value === "string") {
        return value.toUpperCase();
    }
    if (typeof value === "number") {
        return value.toFixed(2);
    }
    return "Unknown type";
}

Rule of thumb: Prefer unknown over any when you don't know the type.

Void

Used for functions that don't return a value:

function logMessage(message: string): void {
    console.log(message);
    // No return statement
}

// Can return undefined (but not null with strictNullChecks)
function doSomething(): void {
    return undefined;  // ✓ Valid
    return null;       // ✗ Error with strictNullChecks
}

Never

Represents values that never occur:

// Function that never returns (always throws)
function throwError(message: string): never {
    throw new Error(message);
}

// Function with infinite loop
function infiniteLoop(): never {
    while (true) {
        // Never exits
    }
}

// Exhaustive checks (advanced pattern)
type Shape = "circle" | "square";

function getArea(shape: Shape): number {
    if (shape === "circle") {
        return Math.PI;
    }
    if (shape === "square") {
        return 1;
    }
    
    // shape is type 'never' here
    const exhaustiveCheck: never = shape;
    return exhaustiveCheck;  // Ensures all cases handled
}

Arrays

Array Type Syntax

// Two equivalent syntaxes
let numbers: number[] = [1, 2, 3];
let names: Array<string> = ["Alice", "Bob"];

// Array of objects
interface User {
    id: number;
    name: string;
}

let users: User[] = [
    { id: 1, name: "Alice" },
    { id: 2, name: "Bob" }
];

// Mixed types require union
let mixed: (string | number)[] = [1, "two", 3, "four"];

Array Methods Preserve Types

const numbers: number[] = [1, 2, 3, 4, 5];

// map preserves type
const doubled: number[] = numbers.map(n => n * 2);

// filter preserves type
const evens: number[] = numbers.filter(n => n % 2 === 0);

// reduce infers return type
const sum: number = numbers.reduce((acc, n) => acc + n, 0);

// Type errors are caught
const invalid = numbers.map(n => n.toUpperCase());  
// ✗ Error: Property 'toUpperCase' does not exist on type 'number'

ReadonlyArray

Prevents array mutation:

const numbers: ReadonlyArray<number> = [1, 2, 3];

numbers.push(4);  // ✗ Error: Property 'push' does not exist on type 'readonly number[]'
numbers[0] = 10;  // ✗ Error: Index signature in type 'readonly number[]' only permits reading

// Must create new arrays
const added = [...numbers, 4];  // ✓ Valid

Tuples

Fixed-length arrays with specific types for each position:

// Tuple: [string, number]
let user: [string, number] = ["Alice", 30];

// Access with correct types
const name: string = user[0];
const age: number = user[1];

// Errors
user[0] = 42;  // ✗ Error: Type 'number' is not assignable to type 'string'
user[2] = "extra";  // ✗ Error: Tuple type '[string, number]' of length '2' has no element at index '2'

// Real-world use case: RGB colors
type RGB = [number, number, number];

const red: RGB = [255, 0, 0];
const blue: RGB = [0, 0, 255];
const invalid: RGB = [255, 0];  // ✗ Error: Source has 2 element(s) but target requires 3

// Optional elements
type OptionalTuple = [string, number?];

const tuple1: OptionalTuple = ["Alice", 30];
const tuple2: OptionalTuple = ["Bob"];  // ✓ Valid

// Rest elements
type StringNumberBooleans = [string, number, ...boolean[]];

const example: StringNumberBooleans = ["hello", 42, true, false, true];

Named Tuples (TypeScript 4.0+)

type User = [name: string, age: number, isActive: boolean];

const user: User = ["Alice", 30, true];

// Better readability
function createUser(name: string, age: number, isActive: boolean): User {
    return [name, age, isActive];
}

Type Annotations vs Type Inference

TypeScript can often infer types without explicit annotations.

Type Inference

// TypeScript infers types
let message = "Hello";  // Inferred: string
let count = 42;         // Inferred: number
let isActive = true;    // Inferred: boolean

// Array inference
let numbers = [1, 2, 3];  // Inferred: number[]
let mixed = [1, "two"];   // Inferred: (string | number)[]

// Function return type inference
function add(a: number, b: number) {
    return a + b;  // Inferred return type: number
}

// Object inference
const user = {
    name: "Alice",
    age: 30
};
// Inferred type: { name: string; age: number }

When to Use Explicit Annotations

1. Function parameters (always annotate):

// Bad: implicit any
function greet(name) {  // ✗ Parameter 'name' implicitly has an 'any' type
    return `Hello, ${name}`;
}

// Good: explicit type
function greet(name: string): string {
    return `Hello, ${name}`;
}

2. Variables without initialization:

// Inferred as any
let data;  // ✗ Implicit any

// Explicit type
let data: string;
data = "Hello";

3. Complex types:

// Inference might not match intent
const config = {
    port: 8080,
    timeout: 30000
};
// Inferred: { port: number; timeout: number }

// Better: explicit interface
interface Config {
    port: number;
    timeout: number;
    retries?: number;  // Optional property
}

const config: Config = {
    port: 8080,
    timeout: 30000
};

Literal Types

Values themselves can be types:

// String literals
let direction: "north" | "south" | "east" | "west";
direction = "north";  // ✓ Valid
direction = "up";     // ✗ Error: Type '"up"' is not assignable to type '"north" | "south" | "east" | "west"'

// Numeric literals
let roll: 1 | 2 | 3 | 4 | 5 | 6;
roll = 3;   // ✓ Valid
roll = 7;   // ✗ Error

// Boolean literals (rare but possible)
let alwaysTrue: true = true;
alwaysTrue = false;  // ✗ Error

// Real-world example: HTTP methods
type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";

function request(url: string, method: HttpMethod) {
    // Implementation
}

request("/api/users", "GET");    // ✓ Valid
request("/api/users", "get");    // ✗ Error: Argument of type '"get"' is not assignable to parameter of type 'HttpMethod'
request("/api/users", "UPDATE"); // ✗ Error

Combining Literals

type Status = "pending" | "approved" | "rejected";
type Priority = "low" | "medium" | "high";

interface Task {
    id: number;
    status: Status;
    priority: Priority;
}

const task: Task = {
    id: 1,
    status: "pending",
    priority: "high"
};

Type Assertions

Tell TypeScript "trust me, I know what I'm doing" (use carefully):

// Angle-bracket syntax
let someValue: any = "this is a string";
let strLength: number = (<string>someValue).length;

// 'as' syntax (preferred, required in JSX)
let strLength2: number = (someValue as string).length;

// Common use case: DOM elements
const input = document.getElementById("username") as HTMLInputElement;
input.value = "Alice";  // TypeScript knows it's an input

// Non-null assertion (!)
function processValue(value: string | null) {
    // I know value is not null here
    console.log(value!.toUpperCase());
}

// Dangerous: can cause runtime errors!
const nullValue = null;
console.log(nullValue!.toString());  // ✓ Compiles, ✗ Runtime error

Warning: Type assertions don't perform runtime checks. Use only when you know more than TypeScript.

Real-World Example: Type-Safe Configuration

Here's how to fix my production bug from the opening story:

Before (Unsafe)

interface Config {
    port: number;
    timeout: number;
    retries: number;
}

// process.env returns string | undefined!
const config: Config = {
    port: process.env.PORT,        // ✗ Type 'string | undefined' is not assignable to type 'number'
    timeout: process.env.TIMEOUT,
    retries: process.env.RETRIES
};

After (Type-Safe)

interface Config {
    port: number;
    timeout: number;
    retries: number;
}

function parseEnvNumber(value: string | undefined, defaultValue: number): number {
    if (!value) return defaultValue;
    const parsed = parseInt(value, 10);
    if (isNaN(parsed)) return defaultValue;
    return parsed;
}

const config: Config = {
    port: parseEnvNumber(process.env.PORT, 8080),
    timeout: parseEnvNumber(process.env.TIMEOUT, 30000),
    retries: parseEnvNumber(process.env.RETRIES, 3)
};

// Even better: validation
function validateConfig(config: Config): void {
    if (config.port < 1 || config.port > 65535) {
        throw new Error(`Invalid port: ${config.port}`);
    }
    if (config.timeout < 0) {
        throw new Error(`Invalid timeout: ${config.timeout}`);
    }
    if (config.retries < 0 || config.retries > 10) {
        throw new Error(`Invalid retries: ${config.retries}`);
    }
}

validateConfig(config);

Your Challenge

Build a type-safe user validation system:

Requirements:

1. Create a User type with:

   • id: number

   • username: string (3-20 characters)

   • email: string

   • role: "admin" | "user" | "guest"

   • isActive: boolean

   • lastLogin: Date | null

2. Create a validation function that:

   • Takes unknown input

   • Validates each field

   • Returns a typed User or throws an error

3. Handle edge cases:

   • Missing fields

   • Wrong types

   • Invalid role values

   • Null vs undefined

Starter code:

type UserRole = "admin" | "user" | "guest";

interface User {
    // Define your interface
}

function validateUser(input: unknown): User {
    // Implement validation
    // Throw errors for invalid data
}

// Test cases
try {
    const user1 = validateUser({
        id: 1,
        username: "alice",
        email: "[email protected]",
        role: "admin",
        isActive: true,
        lastLogin: new Date()
    });
    console.log("Valid user:", user1);

    const user2 = validateUser({
        id: "2",  // Wrong type!
        username: "bob"
    });
} catch (error) {
    console.error("Validation error:", error.message);
}

Key Takeaways

1. Use strict mode - Enable strictNullChecks and noImplicitAny in tsconfig.json

2. Prefer unknown over any - Unknown is type-safe, any is not

3. Trust type inference - Don't over-annotate, let TypeScript infer when obvious

4. Annotate function parameters - Always specify parameter types

5. Use literal types for enums - Better than magic strings

6. Validate external data - Types don't protect against runtime input

7. Be careful with assertions - They bypass type safety

What I Learned From the Environment Variable Bug

1. process.env is always strings - Never assume numeric types

2. Type assertions are dangerous - Only use when you're certain

3. Validate at boundaries - External inputs need runtime validation

4. Compile-time ≠ runtime - Types disappear after compilation

5. Default values are essential - Always handle undefined

The type system is your first line of defense, but it's not magic. Understanding how types work - and their limitations - is essential for writing robust TypeScript code.

---

Next: Interfaces and Type Aliases - Dive into object types, when to use interfaces vs type aliases, and designing type-safe APIs.