## Why Learn TypeScript? Let’s face it, JavaScript is powerful, flexible, and everywhere. But it also comes with a price: ambiguity, hidden bugs, and code that breaks at runtime because of a missing property or unexpected type. That’s where TypeScript comes in. TypeScript is a **superset of JavaScript** that adds **static typing**. It’s designed to help you catch bugs *before* your code runs, give you better tooling, and make your code more predictable, maintainable, and scalable, especially in large codebases or collaborative environments. > At its core, TypeScript doesn’t replace JavaScript, it enhances it. You’re still writing JavaScript, just with a layer of safety and clarity on top. --- ### Why Bother with Types in a Dynamic Language? If you’ve ever: - Misspelled a property and didn’t find out until runtime - Tried to call a function with the wrong argument and got a vague error - Refactored a large codebase and crossed your fingers that everything still worked - Asked yourself “what does this function even expect?” while reading unfamiliar code …then TypeScript is for you. Types aren’t just about preventing errors, they’re about **understanding** your own code better. They’re about communicating intent, documenting your APIs, and working with confidence instead of guesswork. --- ### What TypeScript Actually Does - **Adds types** to variables, functions, objects, arrays, classes, and more - **Catches bugs at compile time** instead of runtime - **Improves autocomplete, refactoring, and navigation** in your IDE - **Scales with your codebase**, making large projects easier to manage - **Integrates seamlessly** with existing JavaScript, you can opt in gradually It doesn’t change how browsers run your code. TypeScript compiles (or *transpiles*) down to plain JavaScript that works anywhere. You get all the benefits of modern JS + powerful type safety, without sacrificing compatibility. --- ### Why TypeScript Is Worth Learning Today - It’s used by major frameworks and libraries: Angular, React, Next.js, Vue, Deno, etc. - It’s adopted by top tech companies: Microsoft, Google, Airbnb, Stripe, Shopify, and more - It’s becoming the industry standard for front-end and back-end JavaScript at scale - It makes you a better JavaScript developer by forcing you to think about shape, structure, and flow Even if you’re just starting out, learning TypeScript early gives you a strong mental model for writing clean and intentional code. --- ### What This Guide Will Teach You This isn’t just a “types 101” tutorial, it’s a comprehensive, beginner-friendly, and deeply practical dive into TypeScript that covers: - What TypeScript is and how it works under the hood - How to set up a TypeScript project and understand the compiler - The core type system: primitives, objects, functions, arrays, unions, generics, and more - Interfaces, type aliases, modules, and configuration (`tsconfig`) - Real-world examples, patterns, and tips for using TypeScript in apps and APIs You’ll also learn how to avoid common pitfalls, think in types, and start applying TypeScript in actual codebases. > By the end of this guide, you’ll go from “what even is TypeScript?” to writing robust, typed code with clarity and confidence. Let’s get started. --- ## Getting Started with TypeScript Before we dive into types, interfaces, and advanced patterns, let’s get you up and running with TypeScript in a real-world environment. The goal here isn’t just to install it, it’s to understand how the pieces fit together so you can confidently start writing and compiling TypeScript today. --- ### 1. Installing TypeScript TypeScript is available as a Node.js package. If you already have Node and npm installed, you can add TypeScript globally: ```bash npm install -g typescript ``` You now have access to the TypeScript compiler via the `tsc` command. To check that it’s working: ```bash tsc --version ``` You should see a version like `5.x.x`. > You can also install TypeScript locally in a project using `npm install typescript --save-dev`, especially useful when working in teams or using bundlers. --- ### 2. Writing Your First TypeScript File Create a new file called `hello.ts`: ```ts let message: string = "Hello, TypeScript!"; console.log(message); ``` Now compile it: ```bash tsc hello.ts ``` This generates a `hello.js` file containing plain JavaScript. ```js "use strict"; let message = "Hello, TypeScript!"; console.log(message); ``` TypeScript checks your types, compiles your code, and outputs JavaScript that runs anywhere. > TypeScript is not interpreted, it’s compiled. You write `.ts`, compile to `.js`, and run it with Node or in the browser. --- ### 3. Setting Up a TypeScript Project (`tsconfig.json`) For any real project, you’ll want a `tsconfig.json` file, this tells the compiler how to process your TypeScript code. Generate it with: ```bash tsc --init ``` This creates a `tsconfig.json` with default settings. Here’s a simplified version: ```json { "compilerOptions": { "target": "ES6", "module": "commonjs", "strict": true, "outDir": "dist", "rootDir": "src" }, "include": ["src"] } ``` - `target`: What version of JS to compile down to - `module`: Module system for imports/exports - `strict`: Enables all strict type-checking rules (recommended!) - `outDir`: Where to put the compiled JS - `rootDir`: Where your TS files live - `include`: Which files/folders to compile Now you can structure your project like this: ``` my-project/ ├── src/ │ └── index.ts ├── dist/ └── tsconfig.json ``` Compile everything in `src/` with: ```bash tsc ``` Your output JavaScript will go to `dist/`. --- ### 4. Running TypeScript Code TypeScript itself doesn’t run in Node, you always run the *compiled JavaScript*. That means the flow is: 1. Write `.ts` 2. Compile to `.js` with `tsc` 3. Run the `.js` with Node: ```bash node dist/index.js ``` > Want to skip the compile step while developing? Use tools like `ts-node` or `tsx` for rapid prototyping. Install `ts-node`: ```bash npm install -g ts-node ``` Now run your file directly: ```bash ts-node src/index.ts ``` Perfect for scripting or small projects. --- ### 5. Use the Right Editor (Seriously) TypeScript’s power really comes alive when paired with a good editor, and **Visual Studio Code** is the gold standard. With VSCode you get: - Intelligent autocompletion - Instant inline type errors - Jump-to-definition - Type-aware refactoring - Hover-to-inspect types No special config needed, VSCode has TypeScript built in. > Even if you’re not writing `.ts`, VSCode will use TypeScript under the hood to power JS intellisense. --- ### 6. Optional: Use the TypeScript Playground Not ready to install anything yet? You can experiment directly in the browser with: [TypeScript Playground](https://www.typescriptlang.org/play) It’s a great way to: - Try out syntax - See how TypeScript compiles your code to JavaScript - Tinker with errors and constraints --- ### Recap | Step | Tool / Command | |--------------------------|-------------------------------------| | Install TypeScript | `npm install -g typescript` | | Compile a file | `tsc filename.ts` | | Create config | `tsc --init` | | Compile a whole project | `tsc` (with `tsconfig.json`) | | Run code (fast) | `ts-node src/index.ts` | | Try online | [TypeScript Playground](https://www.typescriptlang.org/play) | --- ### Next Up Now that you’re set up and writing actual TypeScript, let’s dive into the core of the language: **types**. In the next section, we’ll break down primitive types, how type annotations work, and how TypeScript catches errors before they become bugs. --- ## Primitive Types and Annotations TypeScript’s power starts with something deceptively simple: **type annotations**. These allow you to define what *kind* of data a variable, function, or parameter should hold, and what kind of data is *not allowed*. Let’s begin with the most fundamental building blocks of the type system: **primitive types**. --- ### The Core Primitives JavaScript (and therefore TypeScript) has a handful of core primitive types: | Type | Example | |------------|--------------------------| | `string` | `"hello"`, `'world'` | | `number` | `42`, `3.14`, `-100` | | `boolean` | `true`, `false` | | `null` | `null` | | `undefined`| `undefined` | | `symbol` | `Symbol("id")` | | `bigint` | `9007199254740991n` | Let’s see them in action: ```ts let username: string = "alice"; let age: number = 30; let isAdmin: boolean = false; let id: symbol = Symbol("user-id"); let big: bigint = 12345678901234567890n; ``` These annotations make it **explicit** what type each variable is supposed to hold, and prevent accidental misuse. --- ### Type Inference: TypeScript Is Smart You don’t always *have* to annotate. TypeScript has powerful **type inference**, it automatically figures out the type based on how you initialize the variable. ```ts let city = "New York"; // inferred as string let year = 2024; // inferred as number ``` Once inferred, these are locked in: ```ts city = 123; // ❌ Error: Type 'number' is not assignable to type 'string' ``` > **Rule of thumb:** let inference handle obvious cases. Use annotations when: > - Variables are declared without initialization > - You want to document intent > - You're working with function parameters or complex objects --- ### Explicit Type Annotations You can (and sometimes should) provide explicit types: ```ts let total: number; total = 100; // ✅ total = "hello"; // ❌ Error ``` This helps with code clarity and editor support, especially in large codebases or with dynamic data flows. --- ### `undefined` and `null`: Not Interchangeable TypeScript treats `undefined` and `null` as distinct types, unlike JavaScript’s more relaxed handling. ```ts let x: undefined = undefined; let y: null = null; ``` By default, variables with a type like `string` cannot be `undefined` or `null` unless you explicitly allow it: ```ts let email: string | undefined; email = "alice@example.com"; // ✅ email = undefined; // ✅ email = null; // ❌ unless null is part of the union ``` If you want to allow optional values, use union types or optional chaining, we’ll cover that in the next sections. --- ### `any`: The Escape Hatch ```ts let anything: any = "hello"; anything = 42; anything = false; ``` The `any` type disables type checking, it effectively turns TypeScript off for that variable. While tempting for quick fixes, `any` should be used **very sparingly**: - It defeats the purpose of TypeScript - It can hide bugs instead of preventing them - It reduces tooling intelligence (autocomplete, refactoring, etc.) > ✅ Use `any` *only* when: > - You’re dealing with third-party data with unknown structure > - You’re migrating legacy JavaScript and need temporary flexibility > - You explicitly want to opt out (and mark it as technical debt) Prefer `unknown` when you don’t know the type *yet*, but want to enforce checks before usage. --- ### `unknown` vs `any`: What’s the Difference? ```ts let value: unknown = "hello"; value = 42; value = true; // value.toUpperCase(); ❌ Error, need a type check ``` `unknown` forces you to **narrow the type** before using it, which makes your code safer than `any`. ```ts if (typeof value === "string") { console.log(value.toUpperCase()); // ✅ Safe } ``` --- ### TypeScript Type Safety in Action Here’s a quick example showing how TypeScript protects you from bugs: ```ts function greet(name: string) { return "Hello, " + name.toUpperCase(); } greet("world"); // ✅ greet(42); // ❌ Error: Argument of type 'number' is not assignable to 'string' ``` Without TypeScript, this would silently fail or throw a runtime error. With TypeScript, it’s caught *before* your code runs, and your editor will even underline the mistake. --- ### Summary: What You Should Take Away | Feature | Why It Matters | |-------------------------|-------------------------------------------------| | Type annotations | Make code self-documenting and safe | | Type inference | Reduces noise without sacrificing safety | | `any` | Opt-out, use with caution | | `unknown` | Safer alternative to `any` | | `null` vs `undefined` | Treated as distinct, opt into them if needed | --- ### You Now Know: - How to annotate variables with primitive types - When to trust inference and when to be explicit - Why `any` is both powerful and dangerous - How TypeScript enforces safe usage through strict typing Up next, we’ll look at how to apply types to **objects and arrays**, and start working with structures that reflect real-world data. --- ## Working with Objects and Arrays After mastering primitives, the next big step is learning how to type **structured data**, the kind of stuff your app actually deals with: user profiles, API responses, product lists, etc. Let’s explore how to work with **objects**, **arrays**, and **tuples** in TypeScript, and how to annotate them properly. --- ### Typing Objects Objects are everywhere in JavaScript, they represent state, configs, users, and more. TypeScript lets you describe the *shape* of those objects so they’re no longer ambiguous or error-prone. #### Inline Object Types ```ts let user: { name: string; age: number } = { name: "Alice", age: 30 }; ``` Here, we’ve defined: - An object type with `name` as a `string` - And `age` as a `number` Trying to omit a property or add one that’s not defined will result in a compile error: ```ts user.name = "Bob"; // ✅ user.age = "thirty"; // ❌ Error user.email = "test@"; // ❌ Error: email not defined in type ``` #### Best Practice: When an object type is used more than once, define a reusable **type alias**: ```ts type User = { name: string; age: number; }; let user: User = { name: "Alice", age: 30 }; ``` --- ### Optional Properties Use `?` to mark properties as optional: ```ts type Product = { name: string; price: number; description?: string; // optional }; const item: Product = { name: "Phone", price: 699 }; ``` Optional properties: - Can be left out - Are typed as `type | undefined` So `description` is actually `string | undefined` --- ### Readonly Properties Sometimes you want a property to be assigned once and never changed: ```ts type Config = { readonly appName: string; port: number; }; const cfg: Config = { appName: "MyApp", port: 3000 }; cfg.port = 4000; // ✅ cfg.appName = "New"; // ❌ Error: Cannot assign to readonly property ``` Use `readonly` to enforce immutability. --- ### Typing Arrays Array syntax is simple once you understand that you're typing the **type of each item** inside the array. ```ts let scores: number[] = [85, 92, 78]; let names: string[] = ["Alice", "Bob"]; ``` Or using generic notation: ```ts let flags: Array = [true, false, true]; ``` Both styles are valid, choose based on preference or consistency in your codebase. --- ### Array of Objects Things get interesting when you combine arrays + objects: ```ts type User = { id: number; username: string; }; let users: User[] = [ { id: 1, username: "alice" }, { id: 2, username: "bob" } ]; ``` This is incredibly common with data fetched from APIs. --- ### Tuples: Fixed-Length Arrays with Specific Types Tuples allow you to define arrays with: - Fixed length - Known types for each index ```ts let person: [string, number] = ["Alice", 30]; ``` - `person[0]` must be a string - `person[1]` must be a number Trying to push new elements is technically allowed, but often discouraged unless explicitly typed: ```ts person.push("extra"); // Allowed but unsafe in logic ``` To make this stricter, set `readonly`: ```ts type Coordinate = readonly [number, number]; ``` --- ### Destructuring with Typed Tuples ```ts const [lat, lng]: [number, number] = [40.7128, -74.006]; ``` This is powerful when working with coordinate systems, RGB values, etc. --- ### Inference Still Works TypeScript can often infer object and array types if values are clear: ```ts const car = { make: "Toyota", year: 2023 }; // inferred as { make: string; year: number } ``` But as your app grows, **explicit types** make refactoring and code navigation much easier. --- ### Cleaner Code with Aliases Use `type` or `interface` to create reusable types (we’ll go deeper on this in the next section): ```ts type Task = { id: number; title: string; completed: boolean; }; let todos: Task[] = [ { id: 1, title: "Learn TS", completed: false } ]; ``` --- ### Summary: Object and Array Typing | Feature | Syntax Example | Notes | |------------------|-----------------------------------------------|----------------------------------------------| | Object type | `{ name: string; age: number }` | Inline or with a `type` alias | | Optional prop | `description?: string` | Treated as `string \| undefined` | | Readonly prop | `readonly id: number` | Prevents reassignment | | Array of strings | `string[]` or `Array` | Use for ordered lists | | Array of objects | `User[]` | Combine with a `type` alias | | Tuple | `[string, number]` | Fixed types and order | --- ### You Now Know: - How to annotate objects, arrays, and tuples - How to use optional and readonly properties - How to mix types and structure real-world data - When to use `type` aliases for cleaner code In the next section, we’ll explore how to **define and structure complex types** using `type`, `interface`, and how to extend and combine them, so you can model richer, more reusable data structures. --- ## Functions, Parameters, and Return Types (with `type` vs `interface` Deep Dive) Functions are the heart of any JavaScript application, and in TypeScript, they become even more powerful. You don’t just write them, you describe exactly what kind of data they expect and return. In this section, we’ll cover: - How to annotate parameters and return types - Default and optional parameters - Function expressions and arrow functions - When to use `type` vs `interface` for reusable function signatures --- ### Basic Function Annotations Here’s the simplest TypeScript function with full type annotations: ```ts function greet(name: string): string { return `Hello, ${name}`; } ``` #### Breakdown: - `name: string` → argument must be a string - `: string` after the parentheses → return value must be a string Calling it incorrectly results in a compile-time error: ```ts greet("Alice"); // ✅ greet(42); // ❌ Error: Argument of type 'number' is not assignable to 'string' ``` --- ### Optional and Default Parameters Use `?` to mark a parameter as optional: ```ts function log(message: string, level?: string): void { console.log(`[${level || "INFO"}]: ${message}`); } ``` Use `=` to provide a default: ```ts function log(message: string, level: string = "INFO"): void { console.log(`[${level}]: ${message}`); } ``` - Optional parameters become `type | undefined` - Default parameters are automatically typed --- ### Return Type Inference If not explicitly annotated, TypeScript will infer the return type from the function body: ```ts function add(x: number, y: number) { return x + y; // inferred as number } ``` Still, in **public APIs or exported functions**, **explicit return types** are highly recommended for: - Better readability - Safer refactoring - Easier debugging --- ### Anonymous Functions and Arrow Functions You can also type arrow functions just as easily: ```ts const multiply = (a: number, b: number): number => { return a * b; }; ``` Or with inline function expressions: ```ts const divide: (a: number, b: number) => number = (a, b) => a / b; ``` --- ### Reusable Function Types: `type` vs `interface` For large codebases or repeated signatures, you’ll often want to define reusable function types. There are **two ways** to do that: --- #### ✅ Using `type` for function signatures ```ts type StringTransformer = (input: string) => string; const toUpper: StringTransformer = (str) => str.toUpperCase(); ``` This is concise and great for simple or inline use. --- #### ✅ Using `interface` for function shapes ```ts interface StringTransformer { (input: string): string; } const toLower: StringTransformer = (str) => str.toLowerCase(); ``` Function interfaces are useful when you might extend the signature or add metadata: ```ts interface NamedTransformer { (input: string): string; displayName: string; } const shout: NamedTransformer = (str => str.toUpperCase() + "!") as NamedTransformer; shout.displayName = "shouty"; ``` > **Note:** The `as NamedTransformer` assertion is required because TypeScript cannot automatically infer that the arrow function also implements the extended `displayName` property, so we explicitly assert it as a `NamedTransformer`. --- ### When to Use `type` vs `interface` | Use Case | Use `type` | Use `interface` | |----------------------------------|-------------------------------------|--------------------------------------| | Defining a function signature | ✅ Cleaner and concise | ✅ When adding metadata to the function | | Modeling simple object shape | ✅ Works great | ✅ Slightly preferred for OOP / class design | | Extending types (composition) | ✅ With `&` (intersection) | ✅ With `extends` | | Declaration merging (augmenting) | ❌ Not supported | ✅ Interfaces can merge | | Union or intersection types | ✅ Only possible with `type` | ❌ Interfaces can't union | > TL;DR: > - Use `type` for functions, primitives, tuples, and unions > - Use `interface` for objects and when extending complex structures --- ### Practical Function Patterns #### Callback Functions ```ts type Callback = (value: number) => void; function processValue(x: number, callback: Callback) { callback(x * 2); } ``` #### Function Returning Objects ```ts function createUser(name: string, age: number): { name: string; age: number } { return { name, age }; } ``` Extract this shape into a reusable type: ```ts type User = { name: string; age: number }; function createUser(name: string, age: number): User { return { name, age }; } ``` --- ### Special Function Types: `void` and `never` - `void` means a function returns nothing: ```ts function log(message: string): void { console.log(message); } ``` - `never` means it never returns, often used for errors or infinite loops: ```ts function fail(): never { throw new Error("Something went wrong"); } ``` --- ### Summary: Function Typing in TypeScript | Feature | Example | Description | |-----------------------------|----------------------------------------------|---------------------------------------| | Basic annotation | `function greet(name: string): string` | Declare input and output types | | Optional/default params | `function log(msg: string, lvl?: string)` | Mark params as optional or defaulted | | Arrow functions | `(x: number): number => x * 2` | Concise function syntax | | Function as a type | `type Fn = (a: T) => U` | Define reusable signatures | | Void return | `(): void` | Indicates no return value | | Never return | `(): never` | Indicates function never returns | | Interface for functions | `interface Fn { (x: T): U }` | Reusable + extendable signature | --- ### You Now Know: - How to fully type functions: inputs, outputs, optional/default params - When and how to use `type` or `interface` for functions - How to model callbacks and function-driven APIs - Why return types are critical for safety and clarity Next up, we’ll build on this with **type aliases and interfaces for objects and data modeling**, unlocking clean, scalable structure for everything from config objects to API contracts. --- ## Type Aliases and Interfaces So far, you’ve seen object types written inline and functions typed directly. But in real-world projects, repeating those structures becomes messy fast. That’s where **type aliases** and **interfaces** come in. They let you: - Name reusable shapes - Build composable, extendable, readable types - Model real-world data (users, APIs, configs, components) Let’s break them down, how they work, how they’re different, and when to use each. --- ### Type Aliases: Naming Any Type A **type alias** lets you give a name to *any* valid type expression, not just objects. ```ts type Username = string; type ID = number | string; type User = { id: ID; name: Username; isActive: boolean; }; ``` You can alias: - Primitives - Unions and intersections - Tuples - Function types - Objects > Type aliases are flexible, use them to model almost *any* structure in TypeScript. --- ### Interface: Defining Object Shapes An **interface** is used to define the **structure of objects**. It describes what properties an object should have and their types. ```ts interface User { id: number; name: string; isActive: boolean; } ``` It’s similar to a type alias for objects, but it has some *extra superpowers*. --- ### `type` vs `interface`: Key Differences They’re similar, but not the same. Here’s a breakdown: | Feature | `type` | `interface` | |----------------------------------|-----------------------------------------|-----------------------------------------| | Use for objects | ✅ | ✅ | | Use for functions, tuples, etc. | ✅ | ❌ (mostly object shapes) | | Can extend other types | ✅ via intersections (`&`) | ✅ via `extends` | | Declaration merging | ❌ | ✅ Interfaces can merge | | Express union or literal types | ✅ (e.g., `'GET' \| 'POST'`) | ❌ Not supported | | Implements (for classes) | ✅ (with caution) | ✅ Cleaner syntax | --- ### Choosing Between `type` and `interface` #### ✅ Use `type` when: - You’re modeling a **union** (`'success' | 'error'`) - You need to alias **functions, tuples, or primitives** - You’re composing types using `&` or `|` - You want to constrain complex generic types #### ✅ Use `interface` when: - You’re defining **object shapes** - You expect **declaration merging** (e.g., extending existing libraries) - You’re working with **OOP or classes** > TL;DR: Use `interface` for data *shapes*, and `type` for *anything else*. --- ### Extending and Composing Types #### Interface Inheritance ```ts interface Animal { name: string; } interface Dog extends Animal { breed: string; } const fido: Dog = { name: "Fido", breed: "Labrador" }; ``` #### Type Composition ```ts type Animal = { name: string; }; type Dog = Animal & { breed: string; }; ``` Both are valid. Prefer `interface` for OO-style hierarchies, and `type` for flexible compositions. --- ### Optional and Readonly Properties Both `type` and `interface` support `?` and `readonly`: ```ts interface User { id: number; name?: string; readonly createdAt: Date; } ``` - `?` makes the property optional - `readonly` prevents reassignment --- ### Real-World Use Cases #### 1. Modeling API Data ```ts interface Product { id: number; name: string; price: number; tags?: string[]; } ``` #### 2. Function Signatures ```ts type Callback = (event: string) => void; ``` #### 3. Discriminated Unions ```ts type Success = { status: "success"; data: string }; type Failure = { status: "error"; error: string }; type Result = Success | Failure; function handle(result: Result) { if (result.status === "success") { console.log(result.data); } else { console.error(result.error); } } ``` Unions + literal types = highly readable control flow. --- ### Declaration Merging (Interface Superpower) Interfaces with the same name *merge* automatically, useful in extending libraries: ```ts interface Window { appVersion: string; } interface Window { userID: string; } // Resulting type: const w: Window = { appVersion: "1.2.3", userID: "abc123" }; ``` This does **not** work with `type`. --- ### Naming Convention Tip - Use `type` when you're modeling a value (e.g. `type Theme = "dark" | "light"`) - Use `interface` when you're modeling a shape or capability (e.g. `interface User`) Avoid naming things like `IUser` or `TUser` unless you're in a codebase with that convention. --- ### ✅ Summary: Type Aliases vs Interfaces | You Need... | Use | |------------------------------------|-------------| | To model any type (not just objects) | `type` | | To define object shapes | `interface` | | To compose with unions or literals | `type` | | To extend with declaration merging | `interface` | | To define reusable function types | `type` | | To implement interfaces in classes | `interface` | --- ### You Now Know: - How to define reusable type aliases and interfaces - When to choose `type` vs `interface` - How to model real-world data with optional and readonly properties - How to extend and compose types cleanly Up next: we’ll explore **type unions, intersections, and literal types**, powerful tools that help you model logic with precision, flexibility, and safety. --- ## Unions, Intersections, and Literal Types JavaScript is a flexible language, and TypeScript matches that flexibility with powerful type operations that let you **combine**, **constrain**, and **refine** your data models. In this section, we’ll look at: - Union types: `|` for “either/or” - Intersection types: `&` for “both/and” - Literal types: exact value constraints - Discriminated unions: safe pattern matching These tools help you model real-world logic: success or error states, mixed-type inputs, composite data, and polymorphic function signatures. --- ### Union Types (`|`) A union type lets a variable be **one of several types**: ```ts let id: string | number; id = "abc123"; // ✅ id = 42; // ✅ id = true; // ❌ Error ``` This is useful when you’re handling values from dynamic sources (like user input or APIs) that could be one of several types. #### Use Cases: - API responses that return multiple shapes - Function parameters with flexible inputs - Form fields that might return string or number --- ### Intersection Types (`&`) An intersection combines **multiple types into one**, requiring that **all** fields exist: ```ts type Person = { name: string }; type Account = { email: string }; type User = Person & Account; const u: User = { name: "Alice", email: "alice@example.com" }; ``` Think of intersections as logical **AND**: the value must satisfy both type constraints. #### Use Cases: - Merging interfaces (e.g., UI component + HTML props) - Combining shared and specific types - Enforcing multiple capabilities --- ### Literal Types Literal types let you restrict values to **specific exact values**: ```ts type Direction = "up" | "down" | "left" | "right"; function move(dir: Direction) { console.log(`Moving ${dir}`); } move("up"); // ✅ move("backward"); // ❌ Error ``` This is especially useful for: - Status flags (`"success" | "error"`) - HTTP methods (`"GET" | "POST"`) - Theme modes (`"light" | "dark"`) It also gives you **autocomplete in editors** and ensures no typos sneak through. --- ### Discriminated Unions (Tagged Unions) One of the most powerful patterns in TypeScript is the **discriminated union**, a way to safely model variants with different shapes, keyed by a **common literal field**. ```ts type Success = { status: "success"; data: string; }; type Error = { status: "error"; error: string; }; type Result = Success | Error; ``` You can now safely narrow by `status`: ```ts function handle(result: Result) { if (result.status === "success") { console.log("Data:", result.data); // ✅ TypeScript knows it's Success } else { console.error("Error:", result.error); // ✅ TypeScript knows it's Error } } ``` > TypeScript uses the `status` field (a literal type) to **discriminate** which variant is being handled. #### Use Cases: - API responses (`success`/`error`) - UI component props (`variant: "primary" | "secondary"`) - State machines or reducers (`type: "LOAD" | "SAVE"`) --- ### Tip: Use `in`, `typeof`, and `instanceof` for Type Narrowing When working with unions, you often need to **narrow** a value to one of the types. ```ts function printId(id: string | number) { if (typeof id === "string") { console.log(id.toUpperCase()); } else { console.log(id.toFixed(2)); } } ``` - `typeof` works on primitives - `instanceof` works on class instances - `in` works on object properties ```ts function logShape(shape: Circle | Square) { if ("radius" in shape) { console.log("Circle area:", Math.PI * shape.radius ** 2); } } ``` --- ### Combining All Three You can combine unions, intersections, and literals for fine-grained control: ```ts type Base = { id: number }; type Admin = Base & { role: "admin" }; type User = Base & { role: "user" }; type Account = Admin | User; function checkAccess(account: Account) { if (account.role === "admin") { // Only admins } } ``` This is how many libraries (like Redux, React, or Zustand) structure state and events safely. --- ### Gotchas to Avoid - Union types are **either/or**, not a mix - Intersection types are **both/and**, don’t use if types are conflicting - Literal types must match **exact strings or numbers** - If two union members share keys, always **narrow by a unique literal field** --- ### ✅ Summary: Union, Intersection, and Literal Types | Concept | Syntax | Use For | |--------------------|-------------------------------|-------------------------------------------| | Union | `A \| B` | Either A or B | | Intersection | `A & B` | Both A and B | | Literal | `"GET"` or `42` | Specific values only | | Discriminated Union| Shared `kind: "type"` field | Safe pattern-matching of variants | --- ### You Now Know: - How to use `|` and `&` to combine and constrain types - How to build expressive literal types for enums and states - How to create safe conditional logic using discriminated unions - How TypeScript narrows types using control flow In the next section, we’ll tackle **type inference and type narrowing**, giving you more control and clarity over how TypeScript interprets and constrains types throughout your code. --- ## Type Inference and Narrowing One of TypeScript’s greatest strengths is that it **understands your code as you write it**, even without explicit type annotations. That’s thanks to two key capabilities: - **Type Inference**: TypeScript figures out types for you based on context - **Type Narrowing**: TypeScript automatically refines types as your code executes Understanding how these work helps you write **less code** while still getting **full safety and autocomplete**. --- ### Type Inference: Letting TypeScript Guess When you declare and initialize a variable, TypeScript infers the type: ```ts let name = "Alice"; // inferred as string let age = 42; // inferred as number let isAdmin = true; // inferred as boolean ``` These inferred types are **locked in**, they behave just like annotated ones: ```ts name = 100; // ❌ Error: number not assignable to string ``` #### Where Inference Happens: - Variable declarations - Function return types (if not annotated) - Array element types - Object property types - `const` and `let` assignments --- ### Function Return Type Inference ```ts function double(x: number) { return x * 2; // inferred as number } ``` TypeScript can infer `number` here, but **explicit return types** are still recommended for clarity and refactor safety, especially in public APIs. --- ### Best Practice - **Let inference handle the obvious.** - **Use annotations when clarity, documentation, or constraint is needed.** Example: ```ts const ids = [1, 2, 3]; // inferred as number[] const mixed = [1, "two", true]; // inferred as (string | number | boolean)[] ``` --- ### Type Narrowing: Refining Types at Runtime TypeScript doesn't just infer, it watches how your code behaves and **narrows types based on control flow.** Let’s say a variable could be multiple types: ```ts function printValue(value: string | number) { if (typeof value === "string") { console.log(value.toUpperCase()); // TypeScript narrows to string } else { console.log(value.toFixed(2)); // Now it knows it's a number } } ``` #### Narrowing Techniques: | Technique | Use When... | Example | |------------------|---------------------------------------|-------------------------------------------| | `typeof` | Primitives like string, number, boolean | `typeof x === "string"` | | `in` | Objects with different shape/props | `"id" in obj` | | `instanceof` | Class-based types | `x instanceof Date` | | Literal checks | Discriminated unions | `type === "success"` | --- ### Custom Type Guards You can create your own narrowing helpers, called **type guards**. ```ts type Dog = { bark(): void }; type Cat = { meow(): void }; function isDog(pet: Dog | Cat): pet is Dog { return "bark" in pet; } function handlePet(pet: Dog | Cat) { if (isDog(pet)) { pet.bark(); // ✅ TypeScript knows it's a Dog now } else { pet.meow(); // ✅ It's a Cat here } } ``` > `pet is Dog` is the magic syntax for creating custom narrowing logic. --- ### Contextual Typing Sometimes inference flows **from usage**, not from the declaration. ```ts window.addEventListener("click", (e) => { // TS infers e is MouseEvent based on the 'click' event type console.log(e.clientX); }); ``` This is called **contextual typing**, and it’s what makes TypeScript feel “smart” in real-world code. --- ### Const vs Let Inference ```ts const a = 42; // inferred as 42 (literal) let b = 42; // inferred as number ``` With `const`, the value is a literal type (super specific). With `let`, it’s a general type (assignable). ```ts const method = "GET"; // type is "GET" let method = "GET"; // type is string ``` This matters in discriminated unions or exact matches. Use `as const` to enforce literal types: ```ts const request = { method: "POST", secure: true } as const; // Now method is "POST" instead of string ``` --- ### When Inference Is Not Enough Sometimes inference falls short, and you’ll get `any`, or lose type precision. Examples: - Empty arrays (`const arr = []`) → inferred as `any[]` - Dynamically constructed objects → need explicit type - Data from APIs or third-party code → better to assert or annotate > ✅ Rule: When in doubt, **guide** the compiler. --- ### ✅ Summary: Inference and Narrowing | Feature | What It Does | Benefit | |----------------------|-----------------------------------------|----------------------------------------| | Type inference | Guesses type from context | Less typing, safer code | | Type narrowing | Adjusts type based on control flow | Smarter, safer logic | | Custom type guards | Let you teach TS how to narrow manually | Powerful for complex shapes | | Const inference | Infers literal types with `const` | More precise typing | | Contextual typing | Uses surrounding context to infer | Feels smart and natural in real code | --- ### You Now Know: - How TypeScript infers types without explicit annotations - How control flow automatically narrows types as you code - How to use narrowing techniques like `typeof`, `in`, `instanceof` - How to write your own custom type guards - When to rely on inference, and when to be explicit Up next, we’ll explore **Generics**, a critical tool for writing flexible, reusable, and type-safe code that adapts to its inputs. --- ## Generics. Writing Flexible, Type-Safe Code Generics are how TypeScript lets you write code that works with **any type**, but still **knows what type it’s working with**. They allow you to: - Reuse logic across multiple types - Preserve type safety while remaining flexible - Build expressive APIs and data structures Think of them as **type variables**, placeholders that get filled in later. --- ### Why Use Generics? Without generics, you often have to choose between: - Writing the same function/type multiple times for each type - Giving up and using `any`, which removes type safety Generics solve this by letting you write one version that works with many types, safely. --- ### Basic Generic Syntax Here’s a basic identity function: ```ts function identity(value: T): T { return value; } ``` - `T` is a generic type parameter, it stands for “some type” - When you call the function, TypeScript infers or allows you to specify what `T` should be: ```ts const result1 = identity("hello"); // inferred as string const result2 = identity(42); // explicitly typed as number ``` > You can name the generic anything, but `T`, `U`, `K`, `V` are common conventions. --- ### Real-World Examples #### Generic Arrays ```ts function first(arr: T[]): T { return arr[0]; } first([1, 2, 3]); // number first(["a", "b"]); // string ``` TypeScript figures out what `T` is based on the array you pass in. --- #### Generic Promise Wrapper ```ts function wrapInPromise(value: T): Promise { return Promise.resolve(value); } wrapInPromise("hi"); // Promise wrapInPromise(42); // Promise ``` --- ### Generic Types You can use generics with `type` or `interface` as well: ```ts type Box = { value: T; }; const strBox: Box = { value: "hello" }; const numBox: Box = { value: 123 }; ``` This is useful for modeling containers, wrappers, results, or configs. --- ### Multiple Type Parameters You can use more than one generic type: ```ts function pair(key: K, value: V): [K, V] { return [key, value]; } const kv = pair("id", 101); // [string, number] ``` Useful in things like maps, key-value pairs, or transform functions. --- ### Constraining Generics with `extends` You can restrict what types a generic is allowed to be using `extends`: ```ts function getLength(item: T): number { return item.length; } getLength("hello"); // ✅ string has length getLength([1, 2, 3]); // ✅ array has length getLength(123); // ❌ Error: number doesn't have length ``` This ensures that any `T` used must match the shape you specify. --- ### Using `keyof` with Generics You can use `keyof` to reference the keys of a type: ```ts function getProp(obj: T, key: K) { return obj[key]; } const user = { id: 1, name: "Alice" }; getProp(user, "name"); // OK getProp(user, "email"); // ❌ Error: email does not exist ``` This creates **type-safe object property access**. --- ### Generic Interfaces You can also use generics in interfaces: ```ts interface ApiResponse { status: number; data: T; } const response: ApiResponse = { status: 200, data: "OK" }; ``` This is incredibly common when working with APIs, allowing you to preserve the shape of the data coming back from a server. --- ### Generics with Classes ```ts class Container { private value: T; constructor(val: T) { this.value = val; } get(): T { return this.value; } } const stringContainer = new Container("data"); stringContainer.get(); // "data" (string) ``` This pattern is everywhere in data structure libraries or services that wrap values. --- ### Inference vs Explicit Generics TypeScript will infer types wherever possible: ```ts identity("TS"); // inferred as string identity(42); // explicit ``` Prefer **inference** unless you need to override or clarify something. --- ### Common Gotchas - Don’t use generics when a simple union or overload would do. - Generic hell: avoid too many deeply nested or overly abstract type parameters. - Generics do not exist at runtime, they’re compile-time only. --- ### Naming Tips Use short, meaningful generic names: - `T` — type - `K` — key - `V` — value - `U` — another generic type - `E` — error or element This keeps code readable and consistent. --- ### ✅ Summary: What You Learned | Feature | Purpose | |-------------------------|----------------------------------------------| | `function(x: T): T` | Make functions reusable for any type | | `type Box` | Create generic data structures | | `extends` constraint | Restrict generic to a certain shape | | `keyof` constraint | Enforce property keys | | Inference | TypeScript figures out generic types | --- ### You Now Know: - How to write generic functions and types - How to constrain generics to ensure safety - When to use inference vs explicit annotation - How to use generics in promises, containers, and APIs Next up, we’ll look at **Advanced Types and Utility Types**, giving you powerful tools like `Partial`, `Pick`, `Omit`, `Record`, and conditional types to shape and manipulate types like a pro. --- ## Advanced Types and Utility Types Once you’re comfortable with generics, it’s time to unlock the real power of TypeScript’s type system. This section covers **advanced types** and **built-in utility types** that let you manipulate types the way you manipulate data. These tools let you: - Create new types based on existing ones - Make properties optional, required, or readonly - Pick or omit specific keys - Transform object structures - Write smarter, safer APIs --- ### Mapped Types Mapped types let you **create new types from existing ones**, modifying each property: ```ts type User = { id: number; name: string; email: string; }; // Make all properties optional type PartialUser = { [K in keyof User]?: User[K]; }; ``` - `keyof User` gives `"id" | "name" | "email"` - `[K in keyof User]` loops over each key - `?:` makes each property optional This is how TypeScript’s utility types are built. --- ### Built-in Utility Types TypeScript includes many **pre-built utilities** that use these mapped types behind the scenes. Let’s explore the most useful ones. --- ### `Partial` Makes all properties optional: ```ts type Todo = { id: number; title: string; done: boolean; }; type UpdateTodo = Partial; const patch: UpdateTodo = { title: "Buy milk" // ✅ only one field is fine }; ``` --- ### `Required` Makes all optional fields required: ```ts type Config = { port?: number; debug?: boolean; }; type StrictConfig = Required; // Now both port and debug are required ``` --- ### `Readonly` Prevents reassignment of properties: ```ts type User = { id: number; name: string; }; type ReadonlyUser = Readonly; const u: ReadonlyUser = { id: 1, name: "Alice" }; u.name = "Bob"; // ❌ Error: cannot assign to readonly property ``` --- ### `Pick` Selects a subset of properties: ```ts type User = { id: number; name: string; email: string; }; type PublicUser = Pick; // { id: number; name: string } ``` --- ### `Omit` The inverse of `Pick` — removes keys: ```ts type PrivateUser = Omit; // { id: number; name: string } ``` Perfect for building user views without sensitive info. --- ### `Record` Constructs a type with specified keys and value types: ```ts type Theme = "light" | "dark"; type ThemeConfig = Record; const config: ThemeConfig = { light: "#fff", dark: "#000" }; ``` Useful for theme tokens, lookup maps, or configuration tables. --- ### `Exclude` Removes members from a union: ```ts type Status = "pending" | "success" | "error"; type NonError = Exclude; // "pending" | "success" ``` --- ### `Extract` Keeps only members from a union: ```ts type OnlySuccess = Extract; // "success" ``` --- ### `ReturnType` Gets the return type of a function: ```ts function greet() { return { message: "Hello" }; } type GreetReturn = ReturnType; // { message: string } ``` Useful when abstracting APIs or utility functions. --- ### Conditional Types (Advanced) Conditional types let you **choose types based on logic**: ```ts type IsString = T extends string ? "yes" : "no"; type A = IsString<"hello">; // "yes" type B = IsString; // "no" ``` You can chain these for dynamic type behavior, they’re especially useful in generics and libraries. --- ### Template Literal Types (Advanced Bonus) TypeScript can even combine strings at the type level: ```ts type Direction = "top" | "bottom"; type Position = `margin-${Direction}`; // "margin-top" | "margin-bottom" ``` Used in styling systems, CSS-in-JS, class name generators, and more. --- ### ✅ Summary: Key Utility Types | Utility | Description | |------------------|---------------------------------------------------| | `Partial` | Makes all props optional | | `Required` | Makes all props required | | `Readonly` | Freezes properties | | `Pick` | Select only specific props | | `Omit` | Remove specific props | | `Record` | Create map-like types | | `Exclude` | Remove members from a union | | `Extract` | Keep only certain members | | `ReturnType` | Get a function’s return value | | Conditional Types | Choose types based on logic | --- ### You Now Know: - How mapped types allow you to transform existing types - What utility types TypeScript provides out of the box - How to use `Partial`, `Pick`, `Omit`, `Record`, and more - The power of conditional and template literal types for advanced patterns In the final section, we’ll bring it all together with **real-world patterns and best practices**, so you can confidently apply TypeScript in production projects. --- ## Real-World Patterns and Best Practices You’ve now seen the power of TypeScript from top to bottom, types, functions, objects, generics, utility types, and more. Now let’s answer the ultimate question: > “How do I apply all this in real projects?” This section is your bridge from learning **how TypeScript works** to mastering **how to use it effectively** in production applications. --- ### Organizing Types in Large Projects As codebases grow, it’s crucial to keep types **organized, reusable, and discoverable**. #### Strategy: Centralize Shared Types Group shared types into folders like: ``` /types └── user.ts └── product.ts └── api.ts ``` Then import them as needed: ```ts import { User } from "../types/user"; ``` Avoid repeating the same shapes in multiple files. If two modules need a common type, extract it. #### Tip: Use **index.ts** files to re-export grouped types: ```ts // types/index.ts export * from "./user"; export * from "./product"; ``` --- ### Domain-Driven Types Instead of naming types by what they are technically (e.g., `ApiResponse`, `FetchResult`), name them by **what they represent** in the business domain: ```ts // Bad type ApiUserResponse = { id: number; name: string }; // Better type User = { id: number; name: string }; ``` Your types should tell a **story** about the domain. --- ### Strongly Type Everything That Crosses a Boundary Any data coming from: - APIs (`fetch`) - Local storage - External libraries - Unstructured JSON ...should be **validated or typed** before being used. ```ts // Example: validating fetch response async function getUser(): Promise { const res = await fetch("/api/user"); const data = await res.json(); // Ideally, use runtime validation (like Zod or Yup) return data as User; } ``` > Use `zod`, `io-ts`, or `valibot` for runtime-safe type checking in APIs or untrusted data. --- ### Avoid `any`. But Know When to Use It `any` disables type checking. Avoid it as a default, but don’t fear it when absolutely necessary (e.g., quick experiments, escape hatches, 3rd party edge cases). Prefer `unknown` when receiving unknown input: ```ts function handle(data: unknown) { if (typeof data === "string") { // ✅ safe narrowing } } ``` --- ### Mental Model: Types as Contracts Types are **contracts** between: - You and your future self - You and other developers - Your frontend and backend - Your UI and your state Write types as if another dev will depend on them, because they will. --- ### Don’t Over-Type Everything Too many types = friction and noise. Rely on inference where the intent is obvious: ```ts // ✅ let TS infer const count = 5; // ❌ unnecessary const count: number = 5; ``` But type function return values, complex objects, and external boundaries explicitly. --- ### Build Helper Types for Patterns You Repeat If you keep using a pattern, extract it: ```ts // Example: API response pattern type ApiResponse = { status: number; data: T; error?: string; }; function fetchUser(): Promise> { ... } ``` This creates consistency and reuse across modules. --- ### Use Utility Types to Build Derivatives Build types that extend, transform, or represent **variants** of existing ones: ```ts type User = { id: number; name: string; email: string }; type PublicUser = Omit; type UserUpdate = Partial; ``` --- ### Use Type Inference for Return Types in Tests and Local Helpers If a function is internal and not exported, inference is usually fine. But for public APIs or reusable modules, **add return types** for clarity and to avoid surprises when refactoring. --- ### Prefer Composition Over Inheritance for Types Avoid deep `extends` trees. Instead, **compose** types with intersections: ```ts type WithTimestamps = { createdAt: Date; updatedAt: Date; }; type Post = BasePost & WithTimestamps; ``` --- ### Helpful Libraries for Real Projects - [`zod`](https://zod.dev/) — runtime schema validation that works with TypeScript - [`ts-pattern`](https://github.com/gvergnaud/ts-pattern) — pattern matching with type safety - [`type-fest`](https://github.com/sindresorhus/type-fest) — utility types for real-world use - [`ts-reset`](https://github.com/total-typescript/ts-reset) — improves default TS behaviors --- ### ✅ Summary: Real-World TypeScript Patterns | Practice | Benefit | |--------------------------------------|----------------------------------------------| | Organize types in files/modules | Scalability and clarity | | Validate untyped external data | Safety from runtime errors | | Use inference for local vars | Clean code | | Add types at boundaries | Contract enforcement | | Use utility types for transformation| Less duplication, more reuse | | Compose instead of deeply extending | Maintainable, flexible types | --- ### You Now Know: - How to structure types in real projects - When to annotate vs infer - How to keep types useful, not noisy - How to validate external data safely - Why types are contracts, not just hints You’ve officially made it through **TypeScript 101: The Ultimate Beginner’s Guide**. From primitives to generics, from inference to utility types, you now have the foundation needed to read, write, and scale TypeScript with clarity and confidence. --- ### What's Next? If you're ready to level up: - Start adding types to a real project (gradually) - Contribute to an open source repo with TypeScript - Try writing your own generic utility types - Learn about advanced topics like `infer`, conditional types, and declaration merging > TypeScript rewards *practice*. Use it. Break it. Refactor it. You’ll get better with every file you touch. Go build something type-safe.

TypeScript 101: The Ultimate Beginner's Guide