Mastering TypeScript: A Comprehensive Guide from Basics to Advanced

let name: string = "TypeScript";
let version: number = 6.0;
let isOpenSource: boolean = true;

interface User {
  name: string;
  age: number;
  greet(): string;
}
 
const user: User = {
  name: "Alice",
  age: 30,
  greet() {
    return `Hello, I'm ${this.name}`;
  },
};

let id: string | number;
 
id = "abc-123"; // OK
id = 42; // OK

function identity<T>(value: T): T {
  return value;
}
 
const result1 = identity<string>("hello"); // type is string
const result2 = identity<number>(42); // type is number

function processValue(value: string | number) {
  if (typeof value === "string") {
    // In this branch, TypeScript knows value is string
    console.log(value.toUpperCase());
  } else {
    // In this branch, TypeScript knows value is number
    console.log(value.toFixed(2));
  }
}

// TypeScript infers x as number
let x = 10;
 
// Infers return type as string
function greet(name: string) {
  return `Hello, ${name}`;
}

// Primitives
let str: string = "hello";
let num: number = 42;
let bool: boolean = true;
let n: null = null;
let u: undefined = undefined;
let sym: symbol = Symbol("id");
let big: bigint = 100n;
 
// Special types
let notSure: unknown = "maybe a string";
notSure = 42; // OK, unknown accepts any value
 
let nothing: void = undefined; // Common for functions with no return
let impossible: never; // Type that never has a value
 
// Arrays
let numbers: number[] = [1, 2, 3];
let strings: Array<string> = ["a", "b", "c"];
 
// Tuples — fixed-length, fixed-type arrays
let tuple: [string, number] = ["age", 25];

interface Person {
  name: string;
  age: number;
  email?: string; // Optional property
  readonly id: number; // Read-only property
}
 
const person: Person = {
  name: "Bob",
  age: 25,
  id: 1,
};
 
// person.id = 2; // Error: id is read-only
 
// Interfaces can be extended
interface Employee extends Person {
  department: string;
  salary: number;
}

// Basic usage
type ID = string | number;
type Point = { x: number; y: number };
 
// Unlike interface: type can represent unions inline
type Status = "active" | "inactive" | "suspended";
 
// Can also represent function types
type Callback = (data: string) => void;
 
// Intersection types
type Named = { name: string };
type Aged = { age: number };
type NamedAndAged = Named & Aged;
 
const user: NamedAndAged = { name: "Charlie", age: 28 };

// Union type: A or B
type Result = Success | Error;
 
interface Success {
  status: "success";
  data: string;
}
 
interface Error {
  status: "error";
  message: string;
}
 
function handleResult(result: Result) {
  if (result.status === "success") {
    console.log(result.data); // TypeScript knows this is Success
  } else {
    console.log(result.message); // TypeScript knows this is Error
  }
}
 
// Intersection type: A and B
type Admin = User & { permissions: string[] };
 
interface User {
  name: string;
  email: string;
}
 
const admin: Admin = {
  name: "Diana",
  email: "diana@example.com",
  permissions: ["read", "write", "delete"],
};

// Parameter types and return type
function add(a: number, b: number): number {
  return a + b;
}
 
// Optional parameters and defaults
function greet(name: string, greeting?: string): string {
  return `${greeting || "Hello"}, ${name}`;
}
 
// Rest parameters
function sum(...numbers: number[]): number {
  return numbers.reduce((acc, n) => acc + n, 0);
}
 
// Function overloads
function formatDate(value: string): string;
function formatDate(value: number): string;
function formatDate(value: string | number): string {
  if (typeof value === "number") {
    return new Date(value).toLocaleDateString();
  }
  return new Date(value).toLocaleDateString();
}

// Numeric enum
enum Direction {
  Up = 0,
  Down = 1,
  Left = 2,
  Right = 3,
}
 
// String enum
enum HttpStatusCode {
  OK = "200",
  NotFound = "404",
  InternalError = "500",
}
 
let status: HttpStatusCode = HttpStatusCode.OK;

// String literal
type Theme = "light" | "dark" | "system";
let theme: Theme = "dark";
 
// Numeric literal
type DiceRoll = 1 | 2 | 3 | 4 | 5 | 6;
let roll: DiceRoll = 3;
 
// Boolean literal
type Truthy = true;

// as syntax
const canvas = document.getElementById("main") as HTMLCanvasElement;
canvas.getContext("2d");
 
// Angle-bracket syntax (not usable in JSX files)
// const input = <HTMLInputElement>document.getElementById("input");
 
// Non-null assertion
const element = document.querySelector(".box")!;
element.classList.add("active");

// Generic function
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}
 
first([1, 2, 3]); // returns number | undefined
first(["a", "b"]); // returns string | undefined
 
// Generic constraints (extends)
interface HasLength {
  length: number;
}
 
function logLength<T extends HasLength>(value: T): T {
  console.log(value.length);
  return value;
}
 
logLength("hello"); // OK, string has length
logLength([1, 2, 3]); // OK, arrays have length
// logLength(123);      // Error, number has no length
 
// Multiple generic parameters
function merge<K extends string, V>(key: K, value: V): Record<K, V> {
  return { [key]: value } as Record<K, V>;
}
 
// Generic defaults
interface PaginatedResponse<T = unknown> {
  data: T[];
  total: number;
  page: number;
}
 
// Using the default type
const res: PaginatedResponse = { data: [], total: 0, page: 1 };

// Basic mapped type
type Readonly<T> = {
  readonly [P in keyof T]: T[P];
};
 
type Optional<T> = {
  [P in keyof T]?: T[P];
};
 
interface Todo {
  title: string;
  description: string;
  completed: boolean;
}
 
type ReadonlyTodo = Readonly<Todo>;
// Equivalent to { readonly title: string; readonly description: string; readonly completed: boolean }
 
// Mapped type + key remapping (TypeScript 4.1+)
type Getters<T> = {
  [P in keyof T as `get${Capitalize<string & P>}`]: () => T[P];
};
 
type TodoGetters = Getters<Todo>;
// { getTitle: () => string; getDescription: () => string; getCompleted: () => boolean }

// Basic form: SomeType extends OtherType ? TrueType : FalseType
type IsString<T> = T extends string ? "yes" : "no";
 
type A = IsString<string>; // "yes"
type B = IsString<number>; // "no"
 
// The infer keyword: extracting types within conditional types
type Flatten<T> = T extends Array<infer Item> ? Item : T;
 
type F1 = Flatten<string[]>; // string
type F2 = Flatten<number>; // number
 
// Extract function return type
type GetReturnType<T> = T extends (...args: never[]) => infer R ? R : never;
 
type R1 = GetReturnType<() => string>; // string
type R2 = GetReturnType<(x: number) => boolean>; // boolean
 
// Distributive conditional types
type ToArray<T> = T extends any ? T[] : never;
type Result = ToArray<string | number>; // string[] | number[]
 
// Avoiding distributive behavior: wrap with [T]
type ToArrayNonDist<T> = [T] extends [any] ? T[] : never;
type Result2 = ToArrayNonDist<string | number>; // (string | number)[]

// typeof: get the type of a variable
const config = {
  port: 3000,
  host: "localhost",
  debug: true,
};
 
type Config = typeof config;
// { port: number; host: string; debug: boolean }
 
// keyof: get a union of all property names of a type
type ConfigKeys = keyof Config; // "port" | "host" | "debug"
 
// Indexed access types: Type['key']
type PortType = Config["port"]; // number
 
// ReturnType: extract the return type of a function
function createUser(name: string) {
  return { name, createdAt: new Date() };
}
 
type User = ReturnType<typeof createUser>;
// { name: string; createdAt: Date }
 
// Parameters: get parameter types as a tuple
type CreateUserParams = Parameters<typeof createUser>;
// [name: string]

// typeof guard
function double(value: string | number): string | number {
  if (typeof value === "string") {
    return value.repeat(2); // value: string
  }
  return value * 2; // value: number
}
 
// instanceof guard
function formatDate(value: string | Date): string {
  if (value instanceof Date) {
    return value.toISOString(); // value: Date
  }
  return new Date(value).toISOString(); // value: string
}
 
// in operator guard
interface Fish {
  swim(): void;
}
interface Bird {
  fly(): void;
}
 
function move(animal: Fish | Bird) {
  if ("swim" in animal) {
    animal.swim(); // animal: Fish
  } else {
    animal.fly(); // animal: Bird
  }
}
 
// Custom type guards (type predicates)
function isString(value: unknown): value is string {
  return typeof value === "string";
}
 
function process(input: unknown) {
  if (isString(input)) {
    console.log(input.toUpperCase()); // input: string
  }
}
 
// Discriminated unions
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; x: number }
  | { kind: "triangle"; x: number; y: number };
 
function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.x ** 2;
    case "triangle":
      return (shape.x * shape.y) / 2;
  }
}

// Writing a declaration file: example.d.ts
declare module "my-lib" {
  interface MyLibOptions {
    timeout?: number;
    retries?: number;
  }
 
  function init(options: MyLibOptions): void;
  function getData(id: string): Promise<string>;
 
  export { init, getData, MyLibOptions };
}
 
// Usage
import { init, getData } from "my-lib";
 
init({ timeout: 5000 });
const data = await getData("abc");

// ES Modules (recommended)
// math.ts
export function add(a: number, b: number): number {
  return a + b;
}
export const PI = 3.14159;
 
// app.ts
import { add, PI } from "./math";
 
// Namespaces (legacy approach, not recommended for new projects)
namespace Validation {
  export interface StringValidator {
    isValid(s: string): boolean;
  }
 
  export class EmailValidator implements StringValidator {
    isValid(s: string): boolean {
      return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s);
    }
  }
}
 
const validator = new Validation.EmailValidator();

// Method decorator
function logged(originalMethod: any, context: ClassMethodDecoratorContext) {
  const methodName = String(context.name);
  function replacementMethod(this: any, ...args: any[]) {
    console.log(`LOG: Entering method '${methodName}'.`);
    const result = originalMethod.call(this, ...args);
    console.log(`LOG: Exiting method '${methodName}'.`);
    return result;
  }
  return replacementMethod;
}
 
class Calculator {
  @logged
  add(a: number, b: number): number {
    return a + b;
  }
}

// Deep Partial
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};
 
// Deep Readonly
type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
};
 
// Unwrap nested Promises
type UnwrapPromise<T> = T extends Promise<infer U> ? UnwrapPromise<U> : T;
 
type Result = UnwrapPromise<Promise<Promise<string>>>; // string
 
// Convert snake_case keys to camelCase
type SnakeToCamel<S extends string> = S extends `${infer Head}_${infer Tail}`
  ? `${Head}${Capitalize<SnakeToCamel<Tail>>}`
  : S;
 
type CamelCase = SnakeToCamel<"user_name_id">; // "userNameId"
 
// Recursive type: path-based value access
type PathValue<T, P extends string> = P extends `${infer Key}.${infer Rest}`
  ? Key extends keyof T
    ? PathValue<T[Key], Rest>
    : never
  : P extends keyof T
    ? T[P]
    : never;
 
interface Data {
  user: {
    profile: {
      name: string;
    };
  };
}
 
type Name = PathValue<Data, "user.profile.name">; // string

{
  "compilerOptions": {
    // Language & Environment
    "target": "ES2022", // Compilation target
    "lib": ["ES2022", "DOM"], // Type definition libraries
    "module": "ESNext", // Module system
    "moduleResolution": "bundler", // Module resolution strategy
 
    // Strict mode (recommended: enable all)
    "strict": true, // Enable all strict checks
    "noUncheckedIndexedAccess": true, // Array/object index returns T | undefined
    "noImplicitOverride": true, // Override methods must use override keyword
    "exactOptionalPropertyTypes": true, // Exact optional property types
 
    // Output control
    "declaration": true, // Generate .d.ts files
    "declarationMap": true, // Generate declaration maps
    "sourceMap": true, // Generate source maps
 
    // Interoperability
    "esModuleInterop": true, // Allow default imports from CommonJS
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true, // Allow importing JSON
    "isolatedModules": true, // Ensure each file can be compiled independently
 
    // Other
    "skipLibCheck": true, // Skip type checking of .d.ts files
    "forceConsistentCasingInFileNames": true,
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"],
}

interface Point1 {
  x: number;
  y: number;
}
interface Point2 {
  x: number;
  y: number;
}
 
const p1: Point1 = { x: 1, y: 2 };
const p2: Point2 = p1; // OK, structurally compatible

// Avoid excessively deep type recursion (TypeScript has recursion depth limits)
// Bad practice
type BadDeepPartial<T> = {
  [K in keyof T]?: T[K] extends object ? BadDeepPartial<T[K]> : T[K];
};
 
// For very deep nesting, consider concrete depth levels
type Partial3<T> = Partial<{
  [K in keyof T]: T[K] extends object
    ? Partial<{
        [K2 in keyof T[K]]: T[K][K2] extends object ? Partial<T[K][K2]> : T[K][K2];
      }>
    : T[K];
}>;
 
// Use interface over intersection types for better performance
// Intersection types create intermediate types; interfaces are declarative
// Bad practice
type A = { a: string } & { b: number } & { c: boolean };
// Good practice
interface B {
  a: string;
  b: number;
  c: boolean;
}
 
// Project References speed up compilation in large projects
// tsconfig.json
// {
//   "references": [
//     { "path": "./packages/core" },
//     { "path": "./packages/utils" }
//   ]
// }