TypeScript for QA
Interview Questions

TypeScript is a superset of JavaScript — that means everything you can already write in JavaScript also works in TypeScript, and TypeScript adds extra features on top. The biggest addition is static types: you tell TypeScript what kind of data each variable, parameter, and function return should hold, and it checks that the rest of your code uses them correctly.

The problem it solves:

JavaScript only catches type mistakes when the code actually runs. So you write something, ship it, a user clicks a button, and *then* the browser blows up because you called .toUpperCase() on a number. TypeScript catches that same mistake the moment you type it — before the code has ever run.

The two languages side by side:

``ts
// JavaScript — the error only blows up when it runs:
function greet(name) {
return "Hi " + name.toUpperCase();
}
greet(42); // 💥 Runtime crash: "name.toUpperCase is not a function"

// TypeScript — the same mistake is caught while you type:
function greet(name: string) {
return "Hi " + name.toUpperCase();
}
greet(42); // ❌ Compile error: Argument of type 'number' is not assignable to type 'string'.
`

The : string annotation tells TypeScript "this parameter must be a string." When you call greet(42), TypeScript matches that against the annotation and immediately flags it red in your editor.

Other things TypeScript gives you:
- Better autocompletion — your editor knows exactly what fields exist on an object and offers them as you type.
- Safer refactoring — rename a field on a type and TypeScript instantly shows every file that needs updating.
- Self-documenting code — function signatures show exactly what they expect and return, so the code reads like its own documentation.

What TypeScript does NOT do:
- It doesn't run in the browser directly. Before your code ships, the TypeScript compiler (tsc`) strips out all the type annotations and produces plain JavaScript. The browser only ever sees the JavaScript.
- It doesn't check types at runtime. If your API sends back wrong data, TypeScript can't catch that — type annotations only exist while you're writing code. For data coming from outside, you still need to validate at runtime.

TypeScript adds type annotations on top of JavaScript values. You tell TypeScript what kind of data each variable holds, and it makes sure you never accidentally put the wrong kind in.

The everyday primitive types:

``ts
let name: string = "Asha"; // text in quotes
let age: number = 30; // integer or decimal
let active: boolean = true; // true or false
`

If you try to assign the wrong kind, TypeScript stops you immediately:
`ts
name = 42; // ❌ Type 'number' is not assignable to type 'string'.
`

Collection types:

`ts
let scores: number[] = [90, 85, 70]; // an array of numbers
let names: string[] = ["a", "b", "c"]; // an array of strings
`

number[] literally means "an array where every item is a number." Try pushing the wrong kind and TypeScript catches it:
`ts
scores.push("hello"); // ❌ 'string' is not assignable to 'number'.
`

Special "empty" types:

`ts
let nothing: null = null; // deliberately set to nothing
let notSet: undefined = undefined; // variable declared but never assigned
`

Escape-hatch types (use sparingly):

`ts
let anything: any = 5; // turns off type checking — anything goes
let mystery: unknown = 5; // "could be anything, but check before using"
`

any and unknown look similar but behave very differently:
`ts
let a: any = "hello";
a.toUpperCase(); // ✅ allowed (but risky — would crash if a were a number)

let u: unknown = "hello";
u.toUpperCase(); // ❌ TypeScript stops you — you must check the type first
`

Function-related types:

`ts
function log(msg: string): void { console.log(msg); } // returns nothing useful
function fail(): never { throw new Error("oops"); } // never returns at all
`

Object and tuple types:

`ts
let user: { name: string; age: number } = { name: "Asha", age: 30 };
let pair: [string, number] = ["Asha", 30]; // tuple — fixed length, ordered types per slot
`

Rule of thumb: start with the obvious one (string, number, boolean) for everyday values, use arrays for collections, and only reach for any or unknown` when the type genuinely isn't known up front.

TypeScript figures out the type of a value in two ways: either you spell it out explicitly (annotation), or TypeScript works it out from the value itself (inference).

Annotation — you tell TypeScript the type explicitly:

``ts
let age: number = 30;
let name: string = "Asha";
let active: boolean = true;
`

The : number, : string, : boolean are annotations — the explicit type labels you write yourself.

Inference — TypeScript figures it out from the value:

`ts
let age = 30; // TypeScript infers: number
let name = "Asha"; // TypeScript infers: string
let active = true; // TypeScript infers: boolean
`

You didn't write the type, but TypeScript knows it anyway. Hover over age in your editor and it shows number.

Inference is smarter than it looks — it locks the type in:

`ts
let name = "Asha"; // inferred as string
name = 42; // ❌ 'number' is not assignable to 'string'.
`

Even though you didn't annotate, TypeScript locked in string the moment you assigned "Asha". The later assignment to 42 is caught.

When to lean on inference vs annotate explicitly:

✅ Lean on inference when:
- The value makes the type obvious: let count = 0; is fine — annotating : number is just noise.
- Local variables inside a function — short scope, easy to trace.

✅ Annotate explicitly when:
- Function parameters — TypeScript can't guess what callers will pass:
`ts
function greet(name: string) { /* ... */ } // annotation required
`
- Function return types — documents intent and catches mistakes if you change the body later:
`ts
function getAge(): number { return user.age; }
`
- Empty arrays or objects — TypeScript would infer any[] or {}, which loses safety:
`ts
let scores: number[] = []; // explicit — otherwise inferred as any[]
``

Rule of thumb: let inference handle the obvious; annotate the things that cross a boundary (function parameters, return types, exports, empty containers).

All three declare a variable, but they behave very differently in terms of *scope*, *reassignment*, and old-JavaScript quirks.

const — a variable you cannot reassign:

``ts
const MAX = 100;
MAX = 200; // ❌ Cannot assign to 'MAX' because it is a constant.
`

Block-scoped (only visible inside the { ... } it was declared in). Use const by default — most variables don't actually need to be reassigned.

Important catch — const prevents reassignment, not mutation:

The contents of a const object or array can still change. The "constant" part is the *binding* (which value the variable points to), not the value itself:

`ts
const list = [1, 2, 3];
list.push(4); // ✅ allowed — the array contents changed, but 'list' still points to the same array
list = [9, 9, 9]; // ❌ not allowed — this would reassign 'list' to a different array
`

let — a variable you can reassign:

`ts
let total = 0;
total = total + 10; // ✅ allowed
total = "done"; // ❌ TypeScript still enforces the original inferred type (number)
`

Also block-scoped. Use let when you genuinely need to change the value over time — counters, accumulators, loop trackers.

var — the old way, generally avoid:

`ts
var x = 5;
`

var has two quirks that cause bugs in older code:

1. Function-scoped, not block-scoped — a var declared inside an if block leaks out of it:
`ts
if (true) { var leaked = 1; }
console.log(leaked); // prints 1 — leaked outside the if block!
`

2. Hoisting — a var can be used before its declaration line is reached (it's silently moved to the top of the function), giving confusing undefined values instead of errors.

var exists only for backwards compatibility. In modern TypeScript code: never use it.

Rule of thumb:
- Default to const.
- Use let only when you genuinely need to reassign the variable.
- Don't use var`.

These three look similar at first glance but solve completely different problems. Getting them right is one of the biggest signals of how well you actually understand TypeScript.

any — turns off type checking entirely:

``ts
let value: any = 5;
value.foo.bar.baz(); // ✅ no error from TypeScript — anything goes
value = "now a string"; // ✅ allowed
value = { x: 1 }; // ✅ allowed
`

any says "stop checking — trust me." It defeats the whole point of TypeScript. Useful occasionally as an escape hatch (interfacing with truly dynamic data, or in a hurry while migrating old code), but every any is a hole in your type safety.

unknown — the safe version of any:

`ts
let value: unknown = 5;
value.foo; // ❌ TypeScript blocks you
value.toFixed(2); // ❌ TypeScript blocks you

// You MUST narrow it first:
if (typeof value === "number") {
value.toFixed(2); // ✅ now TypeScript knows it's a number
}
`

unknown says "I don't know the type yet — check before you use it." It forces you to prove the type before touching the value. Use unknown for data coming in from outside your code: API responses, JSON parses, caught errors.

never — a value that cannot exist:

never represents a value that *can't happen*. You see it in three places:

1 — A function that always throws (and never returns):
`ts
function fail(msg: string): never {
throw new Error(msg);
}
`

2 — An impossible branch (the most useful pattern):
`ts
type Status = "active" | "inactive";

function handle(s: Status) {
if (s === "active") return enable();
if (s === "inactive") return disable();
const impossible: never = s; // ❌ compile error if a new Status is added
}
`
If someone later adds "banned" to Status, this code fails to compile until you handle the new case. That's the trick — never is your tripwire for "missing case" bugs.

3 — Filtering in advanced types — never removes a type from a union (you'll see this in mid/senior-level utility types).

The big distinction in one line:
- any = "don't check anything." (dangerous)
- unknown = "I don't know — make me check before I use it." (safe)
- never = "this can't happen." (a tripwire/alarm)

Rule of thumb:
- Avoid any in real code. If you need an escape hatch, prefer unknown.
- Use unknown for any data coming from outside (APIs, JSON, error catches).
- Use never` as a tripwire to make sure you've handled every case of a union.

Both interface and type describe the *shape* of data — like a blueprint that says "an object of this kind has these properties." For most everyday object shapes, they're interchangeable. But each has things the other can't do.

Basic usage — they look almost identical:

``ts
interface User {
id: number;
name: string;
}

type User = {
id: number;
name: string;
};

// Both can be used the same way:
const u: User = { id: 1, name: "Asha" };
`

What type can do that interface cannot:

1 — Union types ("this OR that"):
`ts
type ID = string | number; // can only be done with 'type'
type Status = "active" | "banned";
`

2 — Aliasing primitives, tuples, and function signatures:
`ts
type Age = number; // simple alias
type Coordinates = [number, number]; // tuple
type Logger = (msg: string) => void; // function signature
`

What interface can do that type cannot (easily):

1 — Declaration merging — same interface can be re-opened to add properties:
`ts
interface User { name: string; }
interface User { age: number; } // merges automatically

// User now has both: { name: string; age: number; }
`
This is mostly used to extend types from third-party libraries.

2 — Cleaner extends syntax for inheritance:
`ts
interface Animal { name: string; }
interface Dog extends Animal { breed: string; }
// Dog has: { name: string; breed: string; }
`

(type can do this too with intersections — type Dog = Animal & { breed: string }; — but extends reads more naturally for object hierarchies.)

Rule of thumb:
- Use interface for object and class shapes — especially when other developers might need to extend it.
- Use type` for unions, primitives, tuples, function signatures, and complex computed types.
- For plain object shapes, pick one style and stick to it across your team for consistency.

Union and intersection are two ways to combine existing types into new ones. They sound similar but mean opposite things.

Union (|) — "one of these":

A value typed as a union can be *any one* of the listed types — but only one at a time.

``ts
let id: string | number;
id = "abc"; // ✅ allowed (it's a string)
id = 123; // ✅ allowed (it's a number)
id = true; // ❌ Type 'boolean' is not assignable to 'string | number'.
`

A common real-world example — a function that accepts either an ID format:
`ts
function findUser(id: string | number) {
// id is either a string OR a number — we need to handle both
if (typeof id === "number") {
return db.users.findById(id); // here TypeScript knows id is number
}
return db.users.findByUuid(id); // here TypeScript knows id is string
}
`

Note: inside an if check, TypeScript narrows the union to just one of the types — this is called type narrowing.

Intersection (&) — "all of these combined":

A value typed as an intersection has *all* the properties of every type combined into one.

`ts
interface Person { name: string; age: number; }
interface Employee { employeeId: string; role: string; }

type Staff = Person & Employee;

const s: Staff = {
name: "Asha",
age: 30,
employeeId: "E001",
role: "QA Lead",
};
// must have ALL fields from both Person AND Employee
`

A common real-world example — combining a base shape with an extension:
`ts
type WithTimestamps<T> = T & { createdAt: Date; updatedAt: Date; };
type TimestampedUser = WithTimestamps<User>;
// User + createdAt + updatedAt — all in one type
`

The key difference in one sentence:
- Union (|) = "EITHER this OR that" — a value can be one of several types.
- Intersection (&`) = "BOTH this AND that" — a value must have all properties from every type.

Rule of thumb:
- Use union when a value's type can vary (a function input that accepts either string or number, a state that can be loading/success/error).
- Use intersection when you want to combine multiple shapes into one (add fields, mix in capabilities).

An optional property is a field that may or may not be present on an object. You mark it with a ? after the property name.

The syntax:

``ts
interface User {
name: string; // required — must be present
age?: number; // optional — may be missing
email?: string; // optional — may be missing
}

const u1: User = { name: "Asha" }; // ✅ optional fields omitted
const u2: User = { name: "Ben", age: 30 }; // ✅ some optional fields filled
const u3: User = { name: "Cat", age: 25, email: "c@x.com" }; // ✅ all filled
const u4: User = { age: 30 }; // ❌ 'name' is required
`

What the ? actually does — it implicitly adds | undefined to the type:

`ts
interface User {
age?: number;
}

// Reading the field gives you 'number | undefined' — you must handle the missing case:
function getAge(u: User): number {
return u.age; // ❌ Type 'number | undefined' is not assignable to 'number'.
}

// Fix — handle the missing case:
function getAge(u: User): number {
return u.age ?? 0; // use 0 if age is missing
}
`

A common real-world example — an API response where some fields aren't always present:

`ts
interface ApiUser {
id: number;
name: string;
phoneNumber?: string; // not every user has provided their phone
lastLogin?: string; // missing if they've never logged in
}

function showProfile(user: ApiUser) {
console.log(user.name);
if (user.phoneNumber) {
console.log("Phone:", user.phoneNumber);
}
if (user.lastLogin) {
console.log("Last login:", user.lastLogin);
}
}
`

Optional property (age?: number) vs explicit age: number | undefined:

These look similar but are subtly different:

`ts
interface A { age?: number; } // age may be OMITTED entirely
interface B { age: number | undefined; } // age MUST be present, but can be 'undefined'

const a: A = { }; // ✅ allowed — omitted
const b: B = { }; // ❌ 'age' is required — must include 'age: undefined'
`

Rule of thumb: use ? when the field can be absent from the object entirely. Use | undefined` only when the field must always be set, but may explicitly hold no value.

A class in TypeScript is a blueprint for creating objects that combine data (properties) and behaviour (methods) in one place. TypeScript adds type annotations and access modifiers on top of JavaScript's class syntax.

In test automation, the most common use of a class is the Page Object Model (POM) — a design pattern where each page of the application gets its own class that encapsulates its locators and actions. Instead of scattering page.locator('#login-btn') calls throughout your test files, you put them in one place and reuse them.

Why it matters — tests without a Page Object:

``ts
// ❌ Without POM — locators and actions scattered everywhere:
test('login works', async ({ page }) => {
await page.locator('#email').fill('user@test.com');
await page.locator('#password').fill('secret');
await page.locator('#submit-btn').click();
await expect(page.locator('.dashboard-title')).toBeVisible();
});

// Now every other test file copies the same locators. Change the id? Update 20 files.
`

With a Page Object class:

`ts
import { Page, Locator } from '@playwright/test';

class LoginPage {
// Properties hold the locators — typed as Locator
private readonly emailInput: Locator;
private readonly passwordInput: Locator;
private readonly submitButton: Locator;

// Constructor receives the Playwright Page object
constructor(private page: Page) {
this.emailInput = page.locator('#email');
this.passwordInput = page.locator('#password');
this.submitButton = page.locator('#submit-btn');
}

// Methods encapsulate actions
async login(email: string, password: string): Promise<void> {
await this.emailInput.fill(email);
await this.passwordInput.fill(password);
await this.submitButton.click();
}

async goto(): Promise<void> {
await this.page.goto('/login');
}
}
`

Using the Page Object in tests — clean and readable:

`ts
import { test, expect } from '@playwright/test';
import { LoginPage } from './pages/LoginPage';

test('login with valid credentials', async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.goto();
await loginPage.login('user@test.com', 'secret');
await expect(page.locator('.dashboard-title')).toBeVisible();
});
`

The #email selector exists in exactly one place. Change it? Update one file. TypeScript's types mean the editor autocompletes loginPage. and shows all available methods — you can't misspell an action name.

Access modifiers TypeScript adds:
- private — only accessible inside the class (prevents tests directly accessing raw locators)
- readonly — set once in the constructor, then never reassigned
- public — default; accessible from anywhere

Rule of thumb:
- One class per page or major component.
- Put locators as private readonly properties — tests should call methods, not access locators directly.
- Constructor takes Page` from Playwright — the class never creates its own browser context.

An enum (short for "enumeration") is a way to give friendly names to a fixed set of related values. Instead of scattering "magic numbers" or hardcoded strings through your code, you collect the allowed options into one named group.

Numeric enum — the default behavior:

``ts
enum Status {
Active, // 0
Inactive, // 1
Banned, // 2
}

let s: Status = Status.Active;
console.log(s); // prints 0
`

Without a value, TypeScript auto-assigns 0, 1, 2, ... behind the scenes. The names exist for *you* to read; the runtime sees numbers.

String enum — usually the better choice in real code:

`ts
enum Role {
Admin = "ADMIN",
User = "USER",
Guest = "GUEST",
}

let r: Role = Role.Admin;
console.log(r); // prints "ADMIN"
`

Each name maps to an explicit string. This is much more useful in practice because the value is meaningful in logs, network requests, and database records — "ADMIN" tells you what it is; 0 doesn't.

Why enums exist — they prevent typos and magic values:

`ts
// ❌ Without an enum — easy to mistype:
function setRole(role: string) { /* ... */ }
setRole("admln"); // typo — no error, silent bug in production

// ✅ With an enum — TypeScript catches the mistake:
function setRole(role: Role) { /* ... */ }
setRole(Role.Admin); // ✅
setRole("admln"); // ❌ Argument of type 'string' is not assignable to 'Role'.
`

Using an enum value in a switch:

`ts
function describe(status: Status): string {
switch (status) {
case Status.Active: return "User is active";
case Status.Inactive: return "User is inactive";
case Status.Banned: return "User is banned";
}
}
`

Modern alternative — union of string literals:

These days, many teams prefer a simple union of strings over an enum because it has no runtime code (enums add a small JavaScript object to your build):

`ts
type Role = "ADMIN" | "USER" | "GUEST";
let r: Role = "ADMIN";
``

This achieves the same compile-time safety with no runtime overhead.

Rule of thumb:
- Use a string enum when you want a named group of values that's also iterable at runtime (e.g., to populate a dropdown).
- Use a union of string literals for simple fixed sets where you don't need runtime iteration.
- Avoid numeric enums in new code — string enums are almost always clearer.

Typing a function means saying two things: what kinds of values it accepts (parameters) and what kind of value it gives back (return type).

The basic syntax — annotate each parameter, then the return type:

``ts
function add(a: number, b: number): number {
return a + b;
}
`

- a: number, b: number — both parameters must be numbers.
- : number after the parentheses — the function returns a number.

If a caller passes the wrong kind, TypeScript catches it:
`ts
add(2, 3); // ✅ returns 5
add(2, "three"); // ❌ Argument of type 'string' is not assignable to 'number'.
`

Arrow functions — same idea, slightly different syntax:

`ts
const greet = (name: string): string => Hi ${name};

const isEven = (n: number): boolean => n % 2 === 0;
`

TypeScript can infer the return type — but annotating is usually better:

`ts
// Without annotation — TypeScript infers the return type from the body:
function double(n: number) {
return n * 2; // inferred return type: number
}

// With annotation — explicit return type:
function double(n: number): number {
return n * 2;
}
`

The annotated version is preferred because:
- It documents intent — anyone reading the signature knows what the function returns without scanning the body.
- It catches mistakes early — if you later change the body in a way that accidentally returns the wrong type, TypeScript flags the function declaration itself, not some confused caller far away.

Functions that return nothing — use void:

`ts
function logMessage(msg: string): void {
console.log(msg);
// no return — does something useful, returns nothing
}
`

Functions with no parameters — empty parentheses, return type still annotated:

`ts
function getCurrentTime(): Date {
return new Date();
}
``

Rule of thumb:
- Always annotate function parameters (TypeScript can't guess what callers will pass).
- Annotate return types on exported/public functions for clarity.
- Inside short local helpers, inferred return types are fine.

A type assertion is you telling TypeScript "trust me, I know this value's type better than you do." You use the as keyword to override what TypeScript inferred.

The problem it solves:

Sometimes you know more about a value than TypeScript can work out on its own. The most common case is grabbing an HTML element from the DOM:

``ts
const el = document.getElementById("name");
// TypeScript infers: HTMLElement | null
// It doesn't know specifically that this element is an input

el.value; // ❌ Property 'value' does not exist on type 'HTMLElement'.
`

You can see in your HTML that the element with id "name" is an <input>, but TypeScript can't read your HTML. You can assert it:

`ts
const el = document.getElementById("name") as HTMLInputElement;
el.value; // ✅ now TypeScript knows it's an input — .value is allowed
`

Another common use — narrowing an unknown value from JSON:

`ts
const data: unknown = JSON.parse(response);
const user = data as User;
console.log(user.name);
`

Two syntaxes — both work the same:

`ts
const a = value as string; // 'as' syntax (preferred)
const b = <string>value; // angle-bracket syntax (older, doesn't work in .tsx)
`

The big warning — as bypasses checking; it can lie:

`ts
const x = "hello" as unknown as number; // TypeScript allows it
x.toFixed(2); // 💥 Runtime crash — "hello" has no .toFixed
`

You promised TypeScript it was a number. TypeScript believed you. At runtime, the lie blows up.

as doesn't change the actual value — it only changes how TypeScript *thinks about* the value during compilation. The runtime data is whatever it actually was.

When to reach for as:
- DOM elements where you know the specific type from your HTML.
- Narrowing data after you've already checked it (e.g. after Zod validation).
- Telling TypeScript that an as const literal is broader (rare).

When NOT to use as:
- To silence a "doesn't exist on type" error — fix the type definition instead.
- To force untyped API data into a typed shape without validating it — use a runtime check or Zod.
- To "make the error go away" without understanding why TypeScript objected.

Rule of thumb: as` is a last resort. If you find yourself using it often, you're probably missing a type guard, a validation step, or a better type definition.

TypeScript gives you two equivalent ways to declare the type of an array — they mean exactly the same thing, just written differently.

Syntax 1 — the shorthand (most common):

``ts
let nums: number[] = [1, 2, 3];
let names: string[] = ["Asha", "Ben"];
let flags: boolean[] = [true, false, true];
`

number[] literally reads as "array of numbers."

Syntax 2 — the generic form:

`ts
let nums: Array<number> = [1, 2, 3];
let names: Array<string> = ["Asha", "Ben"];
`

Array<number> is the long-hand version. They're identical at the type level — pick a style and stick to it. Most teams use the shorthand number[] for simple cases because it's shorter.

Arrays that hold multiple types — use a union:

`ts
let mixed: (string | number)[] = [1, "a", 2, "b"];
`

The parentheses around (string | number) matter — without them, string | number[] would mean "either a string OR an array of numbers," which is different.

Arrays of objects:

`ts
interface User { id: number; name: string; }
let users: User[] = [
{ id: 1, name: "Asha" },
{ id: 2, name: "Ben" },
];
`

TypeScript catches wrong items immediately:

`ts
let scores: number[] = [90, 85];
scores.push(72); // ✅ allowed — 72 is a number
scores.push("hello"); // ❌ Argument of type 'string' is not assignable to 'number'.

let names: string[] = ["Asha"];
const first = names[0]; // TypeScript knows: first is a string
first.toUpperCase(); // ✅ available — strings have .toUpperCase
`

Empty arrays — always annotate, or you get any[]:

`ts
let bad = []; // inferred as any[] — loses type safety!
bad.push("x");
bad.push(42); // no error, but probably a bug

let good: string[] = []; // ✅ explicit — TypeScript enforces strings only
good.push("x");
good.push(42); // ❌ caught
`

Read-only arrays — when you want to prevent mutation:

`ts
let frozen: readonly number[] = [1, 2, 3];
frozen.push(4); // ❌ Property 'push' does not exist on type 'readonly number[]'.
`

Rule of thumb:
- Use T[] shorthand for simple cases — it's the most common style.
- Use Array<T> if the inner type is complex (e.g. Array<{ name: string; age: number }>).
- Always annotate empty arrays, or TypeScript falls back to any[]`.

readonly marks a property as set-once — it can be assigned when the object is first created, but never reassigned afterwards. It's TypeScript's way of saying "this value is fixed once it exists."

On an interface or type — protects individual properties:

``ts
interface Point {
readonly x: number;
readonly y: number;
}

const p: Point = { x: 1, y: 2 }; // ✅ set at creation
p.x = 5; // ❌ Cannot assign to 'x' because it is a read-only property.
`

The values can be read forever — p.x is fine — but they cannot be reassigned.

A common real-world example — config objects that should never change after startup:

`ts
interface AppConfig {
readonly apiUrl: string;
readonly maxRetries: number;
readonly version: string;
}

const config: AppConfig = {
apiUrl: "https://api.company.com",
maxRetries: 3,
version: "2.4.1",
};

config.apiUrl = "https://hacked.com"; // ❌ blocked at compile time
`

On arrays — readonly blocks mutation methods:

`ts
const items: readonly number[] = [1, 2, 3];
items.push(4); // ❌ Property 'push' does not exist on type 'readonly number[]'.
items[0] = 99; // ❌ Index signature in type 'readonly number[]' only permits reading.
`

You can still read the array — items[0] is fine, items.length is fine — but mutation methods like push, pop, splice are gone from the type entirely.

A common use — function parameters that should be read but not modified:

`ts
function sum(numbers: readonly number[]): number {
numbers.push(0); // ❌ blocked — protects the caller's array
return numbers.reduce((a, b) => a + b, 0);
}
`

This signature says "I will only read this array, I promise not to modify it." Callers can pass their data knowing it won't be mutated unexpectedly.

Important catch — readonly is a compile-time check, not a runtime lock:

`ts
const p: Point = { x: 1, y: 2 };
(p as any).x = 5; // 💥 sneaks past TypeScript at runtime
`

If you need true runtime immutability, combine with Object.freeze().

Rule of thumb:
- Use readonly for config values, IDs, timestamps, and any "set once" data.
- Use readonly T[] for function parameters where you only need to read, not modify.
- For deeply immutable objects, you'll need each nested property marked readonly too (or use the Readonly<T>` utility type for a shallow pass).

void is the return type for a function that does something but gives nothing back. The function runs, has some effect — prints to the console, updates the DOM, sends a request — but doesn't return a value the caller can use.

Basic usage:

``ts
function log(msg: string): void {
console.log(msg);
// no return statement — the function does its work and ends
}

const result = log("hello");
// result is type 'void' — there's nothing meaningful here
`

Functions that update state, log events, or trigger side effects almost always return void:

`ts
function clearScreen(): void {
document.body.innerHTML = "";
}

function sendAnalytics(event: string): void {
analytics.track(event);
}
`

void is different from never — they sound similar but mean different things:

`ts
function logIt(msg: string): void {
console.log(msg);
// returns control to the caller — just with no value
}

function fail(msg: string): never {
throw new Error(msg);
// never returns to the caller at all — execution stops
}
`

| Type | Meaning |
|---|---|
| void | Function returns, but with no useful value |
| never | Function never returns at all (throws or loops forever) |

A subtle behavior — void is more lenient for callbacks:

When void is used as a callback's return type, TypeScript allows the callback to actually return something — it just ignores the value. This is intentional and useful:

`ts
function each(items: number[], callback: (n: number) => void): void {
for (const item of items) callback(item);
}

each([1, 2, 3], (n) => console.log(n)); // ✅ callback returns void
each([1, 2, 3], (n) => n * 2); // ✅ also allowed — return value is ignored
`

This is why array.forEach works with callbacks that accidentally return a value — TypeScript is forgiving here on purpose.

Don't confuse void with undefined:

`ts
function a(): void {} // ✅ returns nothing
function b(): undefined { return; } // returns undefined explicitly
`

For most cases, void is the right choice when you mean "no meaningful return value."

Rule of thumb:
- Use void as the return type whenever a function does its work for the *effect*, not the result.
- Don't try to use the return value of a void` function — there isn't one.

A literal type is a type that allows only one *specific value*, not a whole category. Instead of "any string," it's "the exact string "left"." Combined with a union, this becomes one of TypeScript's most useful features for modelling fixed choices.

The contrast — broad type vs literal type:

``ts
let direction: string = "left"; // accepts ANY string — too loose
let direction: "left" = "left"; // accepts ONLY the string "left"
`

A literal type on its own ("left") is rarely useful — but a *union* of literal types is extremely useful.

Union of literal types — "one of these specific values":

`ts
let direction: "left" | "right" | "up" | "down";

direction = "left"; // ✅
direction = "right"; // ✅
direction = "north"; // ❌ Type '"north"' is not assignable to type '"left" | "right" | "up" | "down"'.
`

This is the same idea as an enum, but lighter — there's no extra runtime object generated, and the editor shows you the allowed values as autocomplete suggestions.

A common real-world example — restricting a function's input:

`ts
type OrderStatus = "pending" | "shipped" | "delivered" | "cancelled";

function updateStatus(orderId: number, status: OrderStatus) {
// ...
}

updateStatus(1, "shipped"); // ✅
updateStatus(1, "delivred"); // ❌ typo caught at compile time!
`

Without the literal union, the parameter would just be string, and the typo "delivred" would silently slip through to production.

Numeric and boolean literals also exist:

`ts
type DiceRoll = 1 | 2 | 3 | 4 | 5 | 6;

let result: DiceRoll = 4; // ✅
let result: DiceRoll = 7; // ❌ not a valid dice roll

type IsAdmin = true; // literally only the value 'true'
`

Combined with other types in real APIs:

`ts
interface ApiResponse {
status: "success" | "error";
message: string;
code: 200 | 400 | 404 | 500;
}
`

The shape forces the caller into specific, valid combinations — no "successful"` typos or invented status codes.

Rule of thumb:
- Reach for a literal union whenever a value has a small, fixed set of allowed options.
- Pair literal unions with type narrowing to safely handle each case in the body of a function.
- This pattern often replaces the need for enums in modern TypeScript code.

A type alias is a custom name you give to an existing type. It doesn't create a new type — it just provides a shorter, more meaningful name for something you'll use repeatedly. You declare it with the type keyword.

The problem it solves:

Without aliases, you end up repeating the same complex type in many places:

``ts
function findById(id: string | number) { /* ... */ }
function deleteById(id: string | number) { /* ... */ }
function updateById(id: string | number, data: object) { /* ... */ }
`

The same union (string | number) is spelled out three times. If you later decide IDs can also be UUID, you'd need to find and update every occurrence. A type alias gives you one place to define it:

`ts
type ID = string | number;

function findById(id: ID) { /* ... */ }
function deleteById(id: ID) { /* ... */ }
function updateById(id: ID, data: object) { /* ... */ }
`

Now ID is defined once. Change it in one place and every usage updates automatically.

Type aliases can name any type, not just unions:

`ts
type Age = number; // simple alias
type Coordinates = [number, number]; // tuple
type User = { id: number; name: string; age: number; }; // object shape
type Logger = (msg: string) => void; // function signature
type Status = "active" | "inactive" | "banned"; // union of literals
`

A common real-world example — naming a complex callback shape:

`ts
type EventHandler = (event: { type: string; payload: unknown }) => void;

function onUserCreated(handler: EventHandler) { /* ... */ }
function onOrderPlaced(handler: EventHandler) { /* ... */ }
`

Without the alias, both functions would have to repeat the whole callback signature.

Aliases vs interfaces — when to use type:

For object shapes, you can use either type or interface (they're mostly interchangeable). Use type when:
- You need a union, primitive, tuple, or function-signature alias (interface can't do these).
- You want a computed type using utility types like Pick, Omit, Partial.

`ts
type PublicUser = Omit<User, "passwordHash">; // ✅ derived type — only 'type' can do this cleanly
`

Aliases don't create new distinct types — they're just names:

`ts
type UserId = number;
type OrderId = number;

const u: UserId = 5;
const o: OrderId = u; // ✅ allowed — both are just 'number' to TypeScript
`

If you want to make these truly distinct so they can't be mixed up, you'd need "branded types" (a senior-level technique).

Rule of thumb:
- Create a type alias whenever a type is reused more than once, or when its meaning is non-obvious from its shape.
- Aim for descriptive names (UserId, OrderStatus) rather than vague ones (MyType, Data`).

Both check equality between two values, but they do it very differently. Choosing the wrong one is one of the classic sources of silent JavaScript bugs.

=== — strict equality (checks value AND type):

The values must be the same *and* the types must match. No conversion happens.

``ts
0 === 0; // ✅ true (same number)
"0" === "0"; // ✅ true (same string)
0 === "0"; // ❌ false (one is number, one is string)
null === undefined; // ❌ false (different types)
`

== — loose equality (converts types before comparing):

JavaScript converts one or both values so they can be compared. This conversion has unexpected results:

`ts
0 == "0"; // ✅ true — "0" gets converted to number 0
"" == 0; // ✅ true — empty string converts to 0
null == undefined; // ✅ true — they're considered "equal-ish"
1 == true; // ✅ true — true becomes 1
[] == false; // ✅ true — empty array converts to 0, false converts to 0
`

These conversions are not intuitive. Someone reading your code can easily misread what's being compared.

A real bug == causes:

`ts
function validate(input: string | null) {
if (input == "") {
return "Please enter a value";
}
}

validate(null); // returns "Please enter a value" 😬 — null == "" is FALSE actually
// but null == undefined is true, etc.
// The point: behaviour is unpredictable
`

The behaviour of == depends on a table of conversion rules most developers don't have memorised. That's the bug — you have to look up the rules to know what your own code will do.

Useful pattern — == null checks BOTH null and undefined:

The only common case where == is genuinely useful:

`ts
if (value == null) {
// catches both null AND undefined in one check
}

// Equivalent strict version:
if (value === null || value === undefined) {
// more explicit, more typing
}
`

Some style guides allow this one exception; others insist on always using ===.

Rule of thumb:
- Always use === in modern code. It's predictable: same type, same value.
- Configure ESLint with eqeqeq to enforce === across the codebase.
- The one exception some teams allow: x == null` to check for null-or-undefined.

Both null and undefined represent "no value," but they signal different things: one means "nothing was ever set," the other means "set to nothing, on purpose."

undefined — the default absence:

``ts
let a; // declared but not assigned — value is undefined

function getName() {
// function doesn't return anything → caller gets undefined
}
const x = getName(); // x is undefined

const obj = { name: "Asha" };
console.log(obj.age); // accessing a missing property → undefined
`

undefined shows up whenever something *hasn't been given a value*. It's the JavaScript runtime's way of saying "there's nothing here."

null — the deliberate absence:

`ts
let b = null; // explicit assignment — "this is intentionally empty"

let currentUser: User | null = null; // no user is logged in (yet)
`

null is something you assign on purpose. It signals "I know this should hold a value, but right now it doesn't."

The semantic difference in one sentence:
- undefined = "no one has set this yet" (often the language's default).
- null = "this was deliberately set to nothing" (intentional).

TypeScript helps when strictNullChecks is on (and you should always turn it on):

`ts
function getUserName(u: User | null): string {
return u.name; // ❌ Object is possibly 'null'.
}

// Fix — handle the null case:
function getUserName(u: User | null): string {
if (u === null) return "Anonymous";
return u.name; // ✅ TypeScript now knows u is User here
}
`

Without strictNullChecks, TypeScript would silently let you call .name on a null value and crash at runtime.

== null catches both — a useful shortcut:

`ts
if (value == null) {
// catches both null AND undefined in one check
}
`

This is the one case where == (loose equality) is genuinely useful, because null == undefined is true.

Real-world conventions:
- DOM APIs (e.g., document.getElementById) usually return null when nothing is found.
- Optional properties and missing function parameters tend to give you undefined.
- Databases often store null for empty fields; JavaScript's undefined typically doesn't survive serialization.

Rule of thumb:
- Use undefined for "not yet set" or "field missing" — let TypeScript's optional properties (age?: number) handle this naturally.
- Use null` for "deliberately empty" — an explicit absence you're choosing to represent.
- Always handle both when validating data coming in from outside.

No — browsers and Node.js only run JavaScript. They have no idea what TypeScript is. Before your TypeScript code can run, the TypeScript compiler must convert it into plain JavaScript.

The flow:

``
your-code.ts → [ TypeScript compiler ] → your-code.js → browser / Node
`

The compiler is called tsc (TypeScript Compiler). When you run tsc, it:

1. Reads your .ts files.
2. Checks the types — if there are type errors, it reports them.
3. Strips out all the type annotations.
4. Outputs plain .js files.

What the compiled output looks like:

`ts
// What you wrote (input.ts):
function greet(name: string): string {
return "Hi " + name;
}
const message: string = greet("Asha");
`

`js
// What ships to the browser (output.js):
function greet(name) {
return "Hi " + name;
}
const message = greet("Asha");
`

Notice: the type annotations (: string) are completely gone. The runtime has no memory of them.

Two big consequences of "types are erased":

1 — Zero runtime overhead. Your TypeScript code runs exactly as fast as the equivalent JavaScript, because the runtime IS plain JavaScript. TypeScript adds nothing at runtime.

2 — No runtime type checking. TypeScript can't catch bad data at runtime — its protection ends at compile time:

`ts
interface User { id: number; name: string; }

async function loadUser(): Promise<User> {
const res = await fetch("/users/1");
return res.json(); // TypeScript trusts this is a User
}

const user = await loadUser();
console.log(user.name.toUpperCase()); // 💥 crashes if API returned { id: 1 } with no name
`

The TypeScript types say "this is a User." The runtime says "this is whatever the API actually sent." If the API lied, TypeScript can't save you.

This is why external data must be validated at runtime:

`ts
import { z } from "zod";
const UserSchema = z.object({ id: z.number(), name: z.string() });

async function loadUser() {
const res = await fetch("/users/1");
const data = await res.json();
return UserSchema.parse(data); // throws if shape is wrong — runtime check
}
`

Modern alternatives to tsc` for running TypeScript:

- Vite, Webpack, esbuild, swc — bundlers that compile TypeScript as part of their build pipeline.
- ts-node — runs TypeScript directly in Node by compiling on the fly.
- Deno, Bun — newer runtimes that handle TypeScript natively (still compiling under the hood, just transparently).

Rule of thumb:
- TypeScript types help you *while writing code* — they're a development-time tool.
- All runtime safety must still come from runtime checks (validation libraries, defensive code at boundaries).
- Never trust external data based on its TypeScript type alone.

tsconfig.json is the configuration file that tells the TypeScript compiler (tsc) how to handle your project — which files to include, what version of JavaScript to output, where to put compiled files, and how strict the type checking should be.

A minimal example:

``json
{
"compilerOptions": {
"target": "ES2020", // what JavaScript version to compile to
"module": "ESNext", // module system (ES modules)
"strict": true, // turn on all strict type-checking
"outDir": "./dist", // where compiled .js files go
"esModuleInterop": true // smoother import compatibility
},
"include": ["src/**/*"], // which files to compile
"exclude": ["node_modules"] // which to skip
}
`

You don't write this by hand from scratch — run npx tsc --init to generate a starter file, then adjust.

The most important setting — "strict": true:

Strict mode is a single flag that turns on a *bundle* of stricter type-checking rules at once:

| Sub-flag | What it does |
|---|---|
| noImplicitAny | Errors on parameters/variables that have no type and no inferable type. Forces you to be explicit instead of accidentally using any. |
| strictNullChecks | Treats null and undefined as their own types — you must handle them explicitly. Catches a huge class of "Cannot read property of null" bugs. |
| strictFunctionTypes | Stricter checking of function parameter compatibility. |
| strictPropertyInitialization | Class properties must be assigned in the constructor. |
| alwaysStrict | Emits "use strict" in all files. |
| noImplicitThis | Errors when this has an implicit any type. |
| useUnknownInCatchVariables | Catch clause variables are typed as unknown, not any. |

Without strict mode, many bugs slip through. With it, the compiler does much more of the work for you.

Comparing strict off vs on:

`ts
// strict: false
function getName(user) { // 'user' is silently typed as 'any' — no error
return user.name.toUpperCase();
}

// strict: true
function getName(user) { // ❌ Parameter 'user' implicitly has an 'any' type.
return user.name.toUpperCase();
}
// Forces you to write:
function getName(user: { name: string }) {
return user.name.toUpperCase();
}
`

Other commonly-tuned settings:

`json
{
"compilerOptions": {
"noUncheckedIndexedAccess": true, // array[0] becomes T | undefined — safer
"noUnusedLocals": true, // errors on unused variables
"skipLibCheck": true, // don't check types in node_modules — much faster builds
"paths": {
"@/*": ["src/*"] // import aliases — write '@/utils' instead of '../../utils'
}
}
}
`

Rule of thumb:
- For any new project: set strict: true from day one.
- For an existing JavaScript project being migrated: turn on strict flags one at a time, starting with noImplicitAny, to make the migration manageable.
- skipLibCheck: true` is almost always worth turning on — it speeds up builds significantly with little real downside.

TypeScript gives you two ways to handle function parameters that don't always need to be supplied: mark them optional, or give them a default value. Both let callers omit the argument, but they behave differently inside the function.

Optional parameter — mark with ?:

The caller may or may not pass it. If omitted, the parameter is undefined inside the function.

``ts
function greet(name: string, title?: string) {
console.log(Hello, ${title ?? ""} ${name});
}

greet("Asha"); // ✅ "Hello, Asha"
greet("Asha", "Dr."); // ✅ "Hello, Dr. Asha"
`

Note the type of title inside the function is actually string | undefined — you have to handle the missing case (here using ?? "" to fall back to an empty string).

Default parameter — provide a fallback value with =:

If the caller omits the argument, TypeScript fills it in with the default. Inside the function, the parameter always has a real value.

`ts
function pour(size: string, sugar = 0) {
console.log(Pouring ${size} with ${sugar} sugars);
}

pour("large"); // ✅ "Pouring large with 0 sugars" — uses default
pour("large", 2); // ✅ "Pouring large with 2 sugars" — overrides default
`

Notice we didn't write sugar: number — TypeScript infers the type from the default value (0 → number). You can still be explicit if you want: sugar: number = 0.

The difference inside the function body:

`ts
function withOptional(x?: number) {
return x + 1; // ❌ Object is possibly 'undefined' — must handle missing case
}

function withDefault(x = 0) {
return x + 1; // ✅ x is always a number — TypeScript fills in 0 if omitted
}
`

Optional means "maybe missing, you handle it." Default means "always there, I'll fill it in if you don't."

Important rule — optional and default parameters must come AFTER required ones:

`ts
function bad(name?: string, age: number) {} // ❌ required can't follow optional

function good(age: number, name?: string) {} // ✅ required first, then optional
function ok(age: number, name = "Guest") {} // ✅ required first, then default
`

A common real-world example — an API helper:

`ts
function fetchUsers(
limit: number, // required
status: "active" | "all" = "active", // default
cursor?: string // optional (for pagination)
) {
// ...
}

fetchUsers(10); // ✅ uses defaults
fetchUsers(10, "all"); // ✅ override status
fetchUsers(10, "active", "abc123"); // ✅ pass cursor for next page
`

Rule of thumb:
- Use a default value when there's a sensible fallback you can supply (page = 1, pageSize = 20).
- Use optional (?`) when missing genuinely means "not applicable" and the function should branch on it.
- Required parameters always come first.

Destructuring is a JavaScript syntax that lets you pull values out of an object or an array into individual named variables, all in one line. TypeScript infers the type of each extracted variable from the source.

Object destructuring — extract properties by name:

``ts
const user = { name: "Asha", age: 30, role: "admin" };

// Without destructuring:
const name = user.name;
const age = user.age;
const role = user.role;

// With destructuring (one line):
const { name, age, role } = user;
// name is string, age is number, role is string
`

Array destructuring — extract items by position:

`ts
const coords = [10, 20];
const [x, y] = coords; // x is 10, y is 20

// Real-world example — React's useState returns a tuple:
const [count, setCount] = useState(0);
// count is number, setCount is a setter function
`

Rename while destructuring — use the : syntax:

`ts
const { name: userName, age: userAge } = user;
// 'name' is extracted but stored in a variable called 'userName'
`

This is useful when there's a name clash, or when you want a more descriptive local name.

Default values for missing properties:

`ts
const { name, country = "Unknown" } = user;
// if user.country is undefined, country variable gets "Unknown"
`

A common real-world use — destructuring function parameters:

`ts
interface UserCard { name: string; age: number; email: string; }

// Without destructuring — repetitive 'user.' everywhere:
function showUser(user: UserCard) {
console.log(user.name);
console.log(user.age);
}

// With destructuring in the parameter:
function showUser({ name, age, email }: UserCard) {
console.log(name);
console.log(age);
console.log(email);
}
`

The function declares the type of the parameter (: UserCard) and destructures its properties in one move. TypeScript still infers name as string, age as number, etc.

This pattern is everywhere in React components:

`ts
interface ButtonProps { label: string; onClick: () => void; disabled?: boolean; }

function Button({ label, onClick, disabled = false }: ButtonProps) {
return <button onClick={onClick} disabled={disabled}>{label}</button>;
}
`

The destructure pulls out exactly the props the function uses, with a sensible default for disabled.

Nested destructuring — works too, but use sparingly for readability:

`ts
const user = { name: "Asha", address: { city: "Pune", country: "India" } };
const { address: { city } } = user; // city is "Pune"
`

Rule of thumb:
- Destructure when you'll use several properties of an object — it's cleaner than repeating the object name.
- Destructure function parameters in React components — it's the standard pattern.
- Don't over-nest — if a destructure becomes hard to read, just use user.address.city` instead.

In TypeScript, you describe an object's shape — what properties it has and what types those properties hold — using one of three approaches: an inline type, a type alias, or an interface.

1 — Inline type (good for one-off uses):

You write the shape directly where the object is used:

``ts
const user: { name: string; age: number } = {
name: "Asha",
age: 30,
};

function greet(user: { name: string; age: number }) {
return Hello, ${user.name};
}
`

Quick for a single use, but repetitive if you use the same shape in multiple places.

2 — Type alias (reusable, flexible):

Give the shape a name with type:

`ts
type User = {
name: string;
age: number;
};

const u: User = { name: "Asha", age: 30 };

function greet(user: User) {
return Hello, ${user.name};
}
`

Same shape, defined once, reused everywhere. Change the definition and every usage updates.

3 — Interface (reusable, supports extension):

Same as a type alias for object shapes, but with the interface keyword:

`ts
interface User {
name: string;
age: number;
}

const u: User = { name: "Asha", age: 30 };
`

Interfaces also support extends cleanly for inheritance:

`ts
interface Admin extends User {
permissions: string[];
}

const a: Admin = { name: "Asha", age: 30, permissions: ["read", "write"] };
`

Important — don't use the bare object type:

`ts
function badGreet(user: object) {
return Hello, ${user.name}; // ❌ Property 'name' does not exist on type 'object'.
}
`

The bare object type just means "some non-primitive value" — TypeScript has no idea what properties it has. You can't access anything on it. Always describe the actual shape.

Describing optional and read-only fields:

`ts
interface User {
readonly id: number; // set once, cannot be reassigned
name: string; // required
email?: string; // optional — may be undefined
age: number | null; // required field, but allowed to be null
}
`

Describing objects with unknown keys (dictionary-like):

`ts
interface ScoresByName {
[key: string]: number; // any string key maps to a number
}

const scores: ScoresByName = { asha: 90, ben: 85, chris: 72 };
`

Rule of thumb:
- Use inline types for one-off shapes used only in one place.
- Use interface when the shape will be reused or might be extended.
- Use type when you need a union, primitive alias, or a computed type using utility types.
- Never use the bare object` type — always describe the fields.

Structural typing means TypeScript compares types by their *shape* — what properties and methods they have — not by their *name*. If an object has all the required properties of a type, it counts as that type, even if it was never explicitly declared as one.

This is also called "duck typing" — from the saying *"if it walks like a duck and quacks like a duck, it's a duck."* TypeScript doesn't look at the label on the box; it looks at what's inside.

The classic example — an object that just happens to fit:

``ts
interface User {
name: string;
age: number;
}

function save(u: User) {
console.log(Saving ${u.name});
}

const person = { name: "Asha", age: 30, city: "Pune" };
save(person); // ✅ accepted — person has 'name' and 'age', so it fits User
`

Notice person was never declared as a User. It's just a plain object literal — but because it *has* the properties User requires, TypeScript accepts it. The extra city field doesn't cause a problem.

Contrast with nominal typing (the opposite approach):

In languages like Java or C#, two classes are different types even if they have identical shapes — you have to explicitly say "this implements that interface." That's nominal typing (based on names).

TypeScript chose structural typing because JavaScript itself is duck-typed at runtime — objects are just bags of properties, no formal class hierarchy required.

The benefit — flexibility:

`ts
interface Lengthy {
length: number;
}

function describe(thing: Lengthy): string {
return length is ${thing.length};
}

describe("hello"); // ✅ string has .length
describe([1, 2, 3]); // ✅ array has .length
describe({ length: 42 }); // ✅ plain object with .length
`

The function works on anything with a length property — string, array, custom object. You didn't have to make each one explicitly implement Lengthy.

The catch — when structural typing is too lenient:

Because TypeScript only looks at shape, two unrelated concepts that *happen* to have the same shape are treated as identical:

`ts
type UserId = number;
type OrderId = number;

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

const orderId: OrderId = 42;
getUser(orderId); // ✅ allowed — both are just 'number' to TypeScript
`

Even though UserId and OrderId represent different things conceptually, TypeScript can't distinguish them — they're both number. This is why senior code sometimes uses "branded types" to force a distinction.

One exception — excess property checks on fresh object literals:

If you pass a freshly written object literal directly (not via a variable), TypeScript is stricter and complains about extra properties:

`ts
save({ name: "Asha", age: 30, city: "Pune" });
// ❌ Object literal may only specify known properties, and 'city' does not exist in type 'User'.
`

This is a guardrail against typos. If you assign to a variable first, the check disappears (variables get the lenient structural rules).

Rule of thumb:
- Structural typing means *shape matters, names don't*. Anything with the required properties fits.
- This makes TypeScript flexible and friendly to existing JavaScript patterns.
- Be aware of the lookalike problem — types that should be distinct (UserId, OrderId`) may need branded types if you want TypeScript to enforce the distinction.

Optional chaining (?.) and nullish coalescing (??) are two modern JavaScript operators that handle missing or null values cleanly. Both also exist in TypeScript with full type inference.

Optional chaining (?.) — safely access a property that might not exist:

If any part of the chain is null or undefined, the whole expression returns undefined instead of crashing with "Cannot read property of null."

``ts
const user = { name: "Asha" }; // no address property at all

// ❌ Without optional chaining — crashes if address is missing:
const city = user.address.city;
// 💥 TypeError: Cannot read properties of undefined (reading 'city')

// ✅ With optional chaining — returns undefined safely:
const city = user?.address?.city;
// city is undefined — no crash
`

You can chain through as many levels as needed:

`ts
const phone = company?.headquarters?.contact?.phone;
// If any link in the chain is null/undefined, phone is undefined
`

Optional chaining works on method calls and arrays too:

`ts
user?.getName?.(); // call getName only if user AND getName exist
items?.[0]?.name; // safely index into a possibly-missing array
`

Nullish coalescing (??) — provide a fallback when a value is null/undefined:

The fallback is used only when the left side is null or undefined — *not* when it's 0 or "" or false.

`ts
const name = input ?? "Guest";
// name = input, unless input is null/undefined, then "Guest"
`

The important difference from || (logical OR):

`ts
const count = 0 || 5; // 5 — || treats 0 as falsy, falls back
const safe = 0 ?? 5; // 0 — ?? only replaces null/undefined

const name1 = "" || "Guest"; // "Guest" — empty string is falsy
const name2 = "" ?? "Guest"; // "" — empty string is a valid value
`

This matters when 0, "", or false are legitimate values you want to keep:

`ts
function showCount(count: number | undefined) {
return count ?? 0; // ✅ keeps 0; only replaces undefined
// return count || 0; // ❌ also replaces 0 (because || treats 0 as falsy)
}
`

Combining them — common in real-world code:

`ts
const username = user?.profile?.displayName ?? "Anonymous";
// Drill safely to displayName, fall back to "Anonymous" if anything is missing
`

Rule of thumb:
- Use ?. when reaching into a chain of objects that might not exist.
- Use ?? for fallbacks where you specifically want to preserve 0, "", or false.
- Prefer ?? over ||` for default values — it's almost always what you actually meant.

This error means TypeScript found a code path where a value could be null (or undefined) and you tried to use it without checking. It's TypeScript doing its job — protecting you from runtime crashes.

Why you're seeing it — strictNullChecks is on:

``ts
const el = document.getElementById("name");
// TypeScript infers: HTMLElement | null
// getElementById returns null if nothing matches the ID

el.textContent = "Hi";
// ❌ Object is possibly 'null'.
`

TypeScript doesn't know whether the element exists in your HTML — getElementById can fail. So it forces you to handle the null case.

You have four good ways to fix it, depending on the situation. Here they are, in order of how often you should reach for each:

Fix 1 — Guard with an if check (most common, safest):

`ts
const el = document.getElementById("name");
if (el) {
el.textContent = "Hi"; // ✅ TypeScript knows el is HTMLElement here, not null
} else {
console.warn("Element 'name' not found");
}
`

The if (el) check is a type guard — inside the block, TypeScript narrows the type to remove null. This is the safest approach because you're also choosing what to do when the value IS missing.

Fix 2 — Optional chaining (when missing is acceptable):

`ts
const text = el?.textContent;
// If el is null, text is undefined — no crash
`

Useful when you just want to read a value, and "missing" is a fine outcome.

Fix 3 — Nullish coalescing for a fallback:

`ts
const name = user?.name ?? "Guest";
// If user is null OR user.name is missing, use "Guest"
`

Combine ?. and ?? when you want a default value.

Fix 4 — Non-null assertion (!) — only when you are absolutely certain:

`ts
const el = document.getElementById("name")!;
// You're promising TypeScript: "I know this isn't null."
el.textContent = "Hi"; // ✅ compiles
`

This silences the error without actually checking. If you're wrong, your code crashes at runtime:

`ts
const el = document.getElementById("doesnt-exist")!;
el.textContent = "Hi"; // 💥 Runtime crash: Cannot set property of null
`

When to use which:

| Situation | Fix |
|---|---|
| Value is genuinely optional, you should handle both cases | if check |
| Reading a value where "missing" is acceptable | ?. (optional chaining) |
| Need a default when value is missing | ?? "fallback" |
| You truly know it exists (e.g., element you just created) | ! (sparingly) |

Rule of thumb:
- 90% of the time, an if check is the right answer — it's safe and explicit.
- Reach for ! only when bypassing the check is genuinely justified, and add a comment explaining why.
- Don't disable strictNullChecks` to silence these errors — you'd be hiding real bugs.

any turns off TypeScript's type checking entirely for that value. It's effectively writing JavaScript inside a TypeScript file. A few anys here and there are usually fine; a whole file full of them defeats the whole point of using TypeScript.

What the problems actually look like:

``ts
function processUser(user: any) {
return user.nmae.toUpperCase(); // typo 'nmae' — TypeScript should catch this
}

processUser({ name: "Asha" });
// 💥 Runtime: Cannot read properties of undefined (reading 'toUpperCase')
`

If user had been typed properly, TypeScript would have flagged user.nmae at compile time. Because it's any, the bug shipped silently.

Three specific problems with any:

1. No autocomplete or refactor safety — the editor doesn't know what user has, so you get no suggestions and renaming a field doesn't update usages.
2. No compile-time errors — typos, wrong types, missing fields all slip through.
3. It spreads — an any value assigned to a typed variable can poison the variable's type:
`ts
const data: any = getData();
const id: number = data.id; // ✅ accepted even if data.id is actually a string
`

How to fix it incrementally — don't try to clean the whole file in one go:

Step 1 — Replace any with unknown as a first pass:

`ts
function processUser(user: unknown) {
return user.nmae.toUpperCase(); // ❌ TypeScript now stops you
}
`

unknown forces you to check the type before using the value. This surfaces every assumption being made in the file.

Step 2 — Define real types where the shape is known:

`ts
interface User {
name: string;
age: number;
}

function processUser(user: User) {
return user.nmae.toUpperCase();
// ^^^^ ❌ Property 'nmae' does not exist on type 'User'.
}
`

Now the typo is caught immediately.

Step 3 — For function parameters, annotate explicitly:

`ts
function add(a, b) { return a + b; } // implicit any for both
function add(a: number, b: number) { return a + b; } // ✅ explicit
`

Step 4 — Turn on "noImplicitAny": true in tsconfig.json:

`json
{ "compilerOptions": { "noImplicitAny": true } }
`

This stops *new* implicit anys from sneaking in while you clean up the old ones.

Practical migration tip — start with the most-used functions first:

A utility used in 50 places gives 50× the safety win. Hunt those down and type them properly before tackling private helpers used once.

When any is genuinely OK:
- Migrating a large JavaScript codebase incrementally (temporary).
- Interfacing with truly dynamic data where you've validated the shape elsewhere.
- A function that genuinely accepts anything (rare).

In every case, prefer unknown over any` if you can — it's the safer escape hatch.

When a function might *not* find a result, the type should make that absence visible. The standard pattern is to return a union of the success type with null (or undefined).

The wrong approach — returning just the success type:

``ts
async function findUser(id: number): Promise<User> {
const row = await db.users.findById(id);
return row;
}

const user = await findUser(42);
console.log(user.name); // 💥 crashes if user 42 doesn't exist
`

The return type says "always a User," but the implementation can secretly return undefined. Callers assume there's always a value, skip the null check, and crash at runtime.

The right approach — make absence part of the return type:

`ts
async function findUser(id: number): Promise<User | null> {
const row = await db.users.findById(id);
return row ?? null;
}
`

Now callers are *forced* by TypeScript to handle the missing case:

`ts
const user = await findUser(42);

console.log(user.name);
// ❌ Object is possibly 'null'.

if (user) {
console.log(user.name); // ✅ TypeScript narrows user to 'User' here
} else {
console.log("User not found");
}
`

null vs undefined — both work; pick one and be consistent:

`ts
async function findUser(id: number): Promise<User | null> { /* ... */ }
async function findUser(id: number): Promise<User | undefined> { /* ... */ }
`

Many teams pick null for "deliberately not found" (it's an intentional outcome) and reserve undefined for "value was never set." But the more important thing is that *some* form of absence is visible in the type.

Alternative pattern — a Result type for "found vs error vs not found":

When the function can fail for multiple reasons, you can return a richer type:

`ts
type FindResult<T> =
| { status: "found"; data: T }
| { status: "not-found" }
| { status: "error"; message: string };

async function findUser(id: number): Promise<FindResult<User>> {
// ...
}

const result = await findUser(42);
switch (result.status) {
case "found": return result.data;
case "not-found": return null;
case "error": throw new Error(result.message);
}
`

This is a senior-level pattern, but worth knowing.

Rule of thumb:
- If a function *might* fail to produce its value, encode that in the return type — don't pretend it always succeeds.
- The simplest form is Promise<T | null>`.
- Consumers will be forced by TypeScript to handle both outcomes — exactly what you want.

The golden rule: do it incrementally. Forcing a big-bang conversion blocks the team for weeks and almost always introduces regressions. The right approach lets the project keep running while you tighten one file at a time.

Step 1 — Install TypeScript and create a config:

``bash
npm install -D typescript
npx tsc --init # generates tsconfig.json
`

Step 2 — Start with a permissive tsconfig.json so nothing breaks:

`json
{
"compilerOptions": {
"allowJs": true, // accept existing .js files alongside .ts
"checkJs": false, // don't type-check JS files yet (too noisy)
"strict": false, // start lenient — we'll tighten later
"outDir": "dist", // where compiled .js files go
"target": "ES2020", // what JS version to compile to
"esModuleInterop": true,
"skipLibCheck": true // don't re-check node_modules — faster builds
},
"include": ["src/**/*"]
}
`

This config means TypeScript will compile your project as-is. No type errors yet — you've just set up the runway.

Step 3 — Rename files one at a time, starting with the most-shared:

`
utils/dates.js → utils/dates.ts
utils/format.js → utils/format.ts
`

Start with utilities used in many places — typing them gives the biggest payoff. Add type annotations as you rename. Fix the errors that surface.

Step 4 — Once a few files are typed, tighten the rules incrementally:

Turn on strict flags one at a time, fix the new errors, then turn on the next:

`json
{
"compilerOptions": {
"noImplicitAny": true, // first — forces explicit types on parameters
// ... fix errors, commit ...
"strictNullChecks": true, // second — handle null/undefined properly
// ... fix errors, commit ...
"strict": true // eventually — enables all strict flags at once
}
}
`

Each flag exposes a category of bugs. Tackle them in waves.

Step 5 — Install @types/* for any libraries that need them:

Many libraries don't ship their own types, but the community publishes them on DefinitelyTyped:

`bash
npm install -D @types/node @types/lodash @types/jest
`

Practical migration tips:
- Never block development — new code can still be .js during early migration if needed; just convert when convenient.
- Track progress with npx tsc --noEmit 2>&1 | wc -l to count remaining errors over time.
- Don't try to type third-party libraries with bad types perfectly — use any or @ts-expect-error to move on, fix later.
- CI should compile but not block on type errors at first — gradually tighten this once the team is on board.

What NOT to do:
- Don't try to convert every file in one PR — it's unreviewable and will cause merge conflicts for weeks.
- Don't turn on "strict": true` from day one in a large codebase — you'll see thousands of errors and lose morale.

When you write helper functions for your Playwright tests — things like loginAs(), navigateToDashboard(), or fillCheckoutForm() — those functions need a Playwright Page object to interact with the browser. TypeScript requires you to declare what type that parameter is. Playwright ships its own TypeScript types, so you import Page directly from the @playwright/test package.

Why this matters:

Without typing the page parameter, TypeScript treats it as any — you lose autocomplete for all Playwright methods (page.locator(), page.goto(), page.waitForURL(), etc.) and lose the compile-time safety that catches misspelled method names.

Basic helper function — how to type it:

``ts
import { Page } from '@playwright/test';

// ❌ Without type — page is any, no autocomplete, no safety:
async function loginAs(page, email, password) {
await page.lokator('#email').fill(email); // typo — no error until runtime
}

// ✅ With types — editor catches the typo immediately:
async function loginAs(page: Page, email: string, password: string): Promise<void> {
await page.locator('#email').fill(email); // ✅ autocomplete works
await page.locator('#password').fill(password);
await page.locator('[data-testid="submit"]').click();
}
`

TypeScript catches page.lokator before you ever run a test.

Using the typed helper in a test:

`ts
import { test, expect } from '@playwright/test';
import { loginAs } from './helpers/auth';

test('dashboard loads after login', async ({ page }) => {
await loginAs(page, 'admin@test.com', 'password123');
await expect(page).toHaveURL('/dashboard');
});
`

The page fixture from { page } is already typed as Page by Playwright — TypeScript confirms it matches the helper's parameter type.

Returning something typed from a helper:

`ts
import { Page, Locator } from '@playwright/test';

// A helper that navigates and returns a locator for assertions:
async function openProductPage(page: Page, productId: string): Promise<Locator> {
await page.goto(/products/${productId});
return page.locator('[data-testid="product-title"]');
}

// In the test:
const title = await openProductPage(page, 'abc123');
await expect(title).toHaveText('Running Shoes');
`

The return type Promise<Locator> means TypeScript knows title is a Locator — so expect(title).toHaveText() autocompletes correctly.

Other Playwright types you'll commonly import:

`ts
import { Page, Locator, BrowserContext, APIRequestContext } from '@playwright/test';
`

Rule of thumb:
- Always type the page parameter as Page — never leave it as implicit any.
- Import types from '@playwright/test', not from 'playwright' — the test package has the fixture types.
- Type your helper's return value too (Promise<void>, Promise<Locator>`) — it makes the caller's code cleaner and self-documenting.

A type guard is any check in your code that lets TypeScript narrow a value from a broad type (like a union or unknown) to a more specific type *inside* a branch. After the check, TypeScript treats the value as the narrower type — and lets you use the properties and methods that type provides.

The problem it solves:

``ts
function format(x: string | number) {
return x.toUpperCase();
// ❌ Property 'toUpperCase' does not exist on type 'string | number'.
}
`

TypeScript won't let you call .toUpperCase() because x could be a number — numbers don't have that method. You need to *prove* it's a string first.

Built-in type guards:

1 — typeof (for primitives — string, number, boolean, etc.):

`ts
function format(x: string | number) {
if (typeof x === "string") {
return x.toUpperCase(); // ✅ TypeScript: x is string here
}
return x.toFixed(2); // ✅ TypeScript: x must be number here
}
`

2 — instanceof (for classes and built-in objects):

`ts
function handleError(err: unknown) {
if (err instanceof Error) {
console.log(err.message); // ✅ err is Error here
console.log(err.stack);
} else {
console.log("Unknown error:", err);
}
}
`

3 — in operator (for checking object properties):

`ts
type Dog = { bark: () => void };
type Cat = { meow: () => void };

function play(pet: Dog | Cat) {
if ("bark" in pet) {
pet.bark(); // ✅ TypeScript: pet is Dog here
} else {
pet.meow(); // ✅ TypeScript: pet must be Cat here
}
}
`

4 — Equality checks (for literal unions):

`ts
type Status = "loading" | "success" | "error";

function render(s: Status) {
if (s === "loading") return <Spinner />;
if (s === "success") return <Done />;
return <ErrorBox />;
}
`

Custom (user-defined) type guards — for complex object shapes:

When TypeScript can't narrow on its own, you write a function with the special return type x is SomeType:

`ts
interface User { id: number; name: string; }

function isUser(x: unknown): x is User {
return (
typeof x === "object" &&
x !== null &&
"id" in x &&
"name" in x &&
typeof (x as any).id === "number" &&
typeof (x as any).name === "string"
);
}

const data: unknown = await fetch("/users/1").then(r => r.json());

if (isUser(data)) {
console.log(data.name); // ✅ TypeScript knows data is User here
}
`

The x is User return type is what tells TypeScript "if this returns true, x is definitely a User."

When you need type guards:
- You receive unknown (from API responses, JSON, caught errors).
- You have a union type and need to branch on the actual variant.
- You're working with class hierarchies and need to know which subclass.

Rule of thumb:
- Use typeof for primitives, instanceof for classes, in for property checks.
- Write a custom guard (x is T`) for object shapes that TypeScript can't narrow automatically.
- For external/untrusted data, prefer a runtime validation library like Zod — it gives you a guard *and* throws clear errors when the data doesn't match.

When a function needs to accept more than one type of input, use a union type (A | B) and narrow inside the function to handle each case.

Basic approach — union parameter with type narrowing:

``ts
function findUser(id: string | number): User {
if (typeof id === "number") {
// TypeScript knows: id is number here
return db.users.findByNumericId(id);
}
// Below the if, TypeScript knows: id is string
return db.users.findByUuid(id);
}

findUser(42); // ✅
findUser("abc-123"); // ✅
findUser(true); // ❌ Type 'boolean' is not assignable
`

The function signature says "I accept either a string or a number." Inside, typeof narrows the union to the specific type before you use it.

Why this is better than any:

`ts
function findUser(id: any): User { // ❌ no safety at all
return db.users.findByNumericId(id); // accepts anything — even booleans, objects
}
`

any accepts the right inputs but also accepts the wrong ones. The union gives you safety at the call site while still allowing flexibility.

A common real-world example:

`ts
type DateInput = string | Date | number; // ISO string, Date object, or timestamp

function formatDate(input: DateInput): string {
let date: Date;

if (typeof input === "string") {
date = new Date(input);
} else if (typeof input === "number") {
date = new Date(input);
} else {
date = input; // already a Date
}

return date.toLocaleDateString();
}

formatDate("2026-06-02");
formatDate(1717286400000);
formatDate(new Date());
`

When the return type also differs — use function overloads:

If different input types should return different output types, function overloads are cleaner than a union return:

`ts
// Overload signatures (callers see these):
function findUser(id: number): UserById;
function findUser(id: string): UserByUUID;

// Implementation signature (must accept all variants):
function findUser(id: number | string): UserById | UserByUUID {
if (typeof id === "number") {
return db.users.findByNumericId(id); // returns UserById
}
return db.users.findByUuid(id); // returns UserByUUID
}

const a = findUser(42); // type: UserById
const b = findUser("abc-123"); // type: UserByUUID
`

Rule of thumb:
- Use a union type when the function accepts multiple input types but the logic is similar — narrow inside with typeof.
- Use overloads when different input types should produce genuinely different return types.
- Avoid any` — it loses the safety the union gives you for free.

As your test suite grows, you'll define types for things like users, products, orders, and API responses. If you copy those interface definitions into each test file, you end up with multiple slightly-different versions that drift apart — one file adds a field, another doesn't. The fix is to define types once in a dedicated file and import them wherever they're needed.

Why copying types is a problem:

``ts
// tests/login.test.ts — copy #1
interface User { id: number; email: string; role: string; }

// tests/checkout.test.ts — copy #2 (someone added 'name' here, forgot in login)
interface User { id: number; email: string; role: string; name: string; }

// Now they're out of sync. TypeScript can't help because they're separate declarations.
`

The fix — a shared types file:

Create a dedicated file for your shared test types:

`ts
// types/index.ts (or types/models.ts — pick a convention and stick to it)

export interface User {
id: number;
email: string;
role: 'admin' | 'guest' | 'regular';
name: string;
}

export interface Product {
id: number;
name: string;
price: number;
inStock: boolean;
}

export interface ApiResponse<T> {
data: T;
status: number;
message: string;
}
`

Import the type wherever you need it:

`ts
// tests/login.test.ts
import { User } from '../types';

test('login returns a user object', async ({ request }) => {
const res = await request.post('/api/login', {
data: { email: 'a@test.com', password: 'secret' }
});
const user: User = await res.json();
expect(user.role).toBe('admin');
});
`

`ts
// tests/checkout.test.ts
import { User, Product } from '../types';

test('checkout creates an order for a user', async () => {
const user: User = { id: 1, email: 'a@test.com', role: 'regular', name: 'Asha' };
// ...
});
`

One definition, used everywhere. Update the User interface once — every file that imports it gets the update automatically.

Type-only imports (good practice in test files):

`ts
// The 'import type' syntax makes clear this is a type, not a runtime value.
// The bundler strips it out entirely — no extra bytes in output.
import type { User } from '../types';
`

Typical folder structure for a Playwright project:

`
tests/
login.test.ts
checkout.test.ts
types/
index.ts ← shared interfaces live here
helpers/
auth.ts
`

Rule of thumb:
- One shared types/ folder — define every reusable interface there.
- Use export interface or export type — both work; the team just needs to pick one style.
- Prefer import type { X }` in test files — it signals intent and keeps builds clean.
- If you only use a type in one file, keep it local. Only move to shared when two or more files need it.

When you don't know the specific keys ahead of time — for example, a dictionary of HTTP headers, a translation lookup table, or a user-defined config — you describe the *pattern* of keys and values rather than listing them all. Two ways to do this: index signature or Record<K, V>.

Option 1 — Index signature (interface or type with [key: string]):

``ts
interface StringMap {
[key: string]: string;
}

const headers: StringMap = {
"Content-Type": "application/json",
"X-Request-ID": "abc123",
"Authorization": "Bearer abc",
// ...any number of string-to-string pairs allowed
};
`

[key: string]: string reads as "any string key, mapped to a string value." TypeScript enforces that *every* value is a string:

`ts
headers["X-Retry"] = 3; // ❌ Type 'number' is not assignable to 'string'.
`

Option 2 — Record<K, V> (same idea, shorter):

`ts
const headers: Record<string, string> = {
"Content-Type": "application/json",
};

const scores: Record<string, number> = {
asha: 90,
ben: 85,
};
`

Record<string, number> means exactly the same as { [key: string]: number } — pick whichever style your team prefers.

For mixed value types — use unknown and narrow before use:

`ts
const config: Record<string, unknown> = {
apiUrl: "https://...",
timeoutMs: 5000,
retries: 3,
debug: false,
};

const port = config.port; // type: unknown
if (typeof port === "number") {
// safely use port as number here
}
`

unknown forces you to check the value type before using it — safer than any.

Mixing known fields with arbitrary extras:

If the object has some required known fields *and* allows arbitrary extras:

`ts
interface ApiResponse {
id: number; // always present
status: "ok" | "error"; // always present
[key: string]: unknown; // plus any number of extra fields
}

const res: ApiResponse = {
id: 1,
status: "ok",
payload: { foo: "bar" }, // extra field allowed
duration: 42,
};
`

Record with a literal-union key — for known keys:

If you actually know the exact set of keys, use a literal union:

`ts
type Role = "admin" | "user" | "guest";
const permissions: Record<Role, boolean> = {
admin: true,
user: false,
guest: false,
};
// TypeScript enforces that ALL three keys are present
`

This is much stricter — TypeScript checks you provided exactly the right keys.

Avoid typing it as any:

`ts
const data: any = await response.json();
data.foo.bar.baz(); // 💥 no safety, no autocomplete
`

At minimum use Record<string, unknown> — you keep the flexibility but force narrowing before use.

Rule of thumb:
- Use Record<string, V> (or { [key: string]: V }) when keys are dynamic and all values share a type.
- Use Record<LiteralUnion, V> when keys are from a known fixed set (stricter).
- Use unknown` for value types when you don't know them precisely — it forces safe handling.
- For external API responses where you genuinely need runtime safety, reach for a validation library like Zod.

This is one of TypeScript's most confusing behaviors at first — the answer depends on how you pass the object, not just what it contains.

Case 1 — Passing a fresh object literal directly:

TypeScript runs an excess property check and rejects extra fields:

``ts
interface User { name: string; }
function save(user: User) {}

save({ name: "Asha", age: 30 });
// ❌ Object literal may only specify known properties,
// and 'age' does not exist in type 'User'.
`

The reasoning: when you write the object right there at the call site, an extra property is almost certainly a typo or a misunderstanding. TypeScript wants to flag it.

Case 2 — Passing through a variable:

TypeScript only checks structural compatibility — the variable's type just needs to have all the required fields. Extras are allowed.

`ts
const person = { name: "Asha", age: 30 };
save(person); // ✅ allowed — 'person' has 'name', that's enough
`

The reasoning: a variable might be used in many places, with extra properties needed by other callers. TypeScript trusts that the variable was constructed deliberately.

Why the asymmetry?

TypeScript chose this trade-off:
- Fresh literals are usually authored *just for this call* — extras are suspicious (typo "name" as "nmae"; you don't catch unless excess properties are flagged).
- Variables are reusable values — extras might be intentional and needed elsewhere.

The excess property check is essentially a typo guard for inline objects.

A real-world example where this matters:

`ts
interface ButtonProps { label: string; onClick: () => void; }

function Button(props: ButtonProps) { /* ... */ }

// ❌ Caught — color isn't a valid prop:
Button({ label: "OK", onClick: handle, color: "red" });

// ✅ Sneaks through — color is allowed because it came via a variable:
const buttonProps = { label: "OK", onClick: handle, color: "red" };
Button(buttonProps);
`

How to avoid being surprised:

If you want strict checking even through variables, annotate the variable with the target type:

`ts
const buttonProps: ButtonProps = { label: "OK", onClick: handle, color: "red" };
// ❌ caught here — variable typed as ButtonProps doesn't allow color
``

Rule of thumb:
- Excess property checks fire only on fresh object literals at the call site.
- If you pass through a variable, extras are quietly accepted (structural typing).
- To get strict checking on a variable, annotate it with the destination type.
- This is a deliberate TypeScript design — useful to recognise so you don't waste time wondering why "the same object" sometimes errors and sometimes doesn't.

Use the extends keyword to build a new interface that inherits all the properties of a parent interface and adds (or overrides) its own. This is TypeScript's way of expressing "A is a B, plus more."

Basic syntax:

``ts
interface Animal {
name: string;
age: number;
}

interface Dog extends Animal {
breed: string;
}

const dog: Dog = {
name: "Rex", // inherited from Animal
age: 3, // inherited from Animal
breed: "Labrador", // added by Dog
};
`

A Dog must have *every* property from Animal *plus* the new breed property. Missing any field is an error:

`ts
const bad: Dog = { name: "Rex", breed: "Labrador" };
// ❌ Property 'age' is missing in type ...
`

Multiple inheritance — extend several interfaces at once:

`ts
interface Person {
name: string;
age: number;
}

interface HasRole {
role: string;
permissions: string[];
}

interface Employee extends Person, HasRole {
employeeId: string;
salary: number;
}

// Must include fields from Person + HasRole + Employee
const e: Employee = {
name: "Asha",
age: 30,
role: "QA Lead",
permissions: ["read", "write"],
employeeId: "E001",
salary: 75000,
};
`

A common real-world example — building up a request type:

`ts
interface BaseRequest {
requestId: string;
timestamp: number;
}

interface AuthenticatedRequest extends BaseRequest {
userId: number;
token: string;
}

interface AdminRequest extends AuthenticatedRequest {
adminLevel: number;
}

// AdminRequest has 5 fields total — auto-tracked from the chain
`

Change BaseRequest to add a new field, and AuthenticatedRequest and AdminRequest automatically include it too. No duplication, no manual updates.

Overriding a parent property — must be a compatible type:

`ts
interface Animal {
age: number;
}

interface Pet extends Animal {
age: 1 | 2 | 3 | 4 | 5; // ✅ narrower type — allowed
}

interface BadPet extends Animal {
age: string; // ❌ Error — incompatible with parent's 'number'
}
`

You can make a property *more specific* in the child, but you can't change its type entirely.

extends (with interfaces) vs & (intersection with types):

`ts
// Using interfaces:
interface Dog extends Animal { breed: string; }

// Using type aliases — same effect:
type Dog = Animal & { breed: string; };
`

Both produce the same result. extends reads more naturally for class-like hierarchies; & is more flexible for ad-hoc combinations.

Rule of thumb:
- Use extends to model "is a" relationships — Dog is an Animal, Admin is a User.
- Inheritance keeps types DRY — change the parent, all children update.
- For combining unrelated shapes ad hoc, prefer type aliases with &` intersection.

One of the most common patterns in test automation is a test data factory — a function that produces a ready-to-use test object with sensible defaults, but lets each test override only the fields it specifically cares about. In TypeScript, you do this with a combination of an interface, default parameters, and the spread operator.

Why this pattern matters:

Without it, every test that needs a user has to spell out all fields — even the ones it doesn't care about:

``ts
// ❌ Every test repeats all fields, even the ones it doesn't care about:
test('admin can delete posts', async () => {
const user = { id: 1, name: 'Test User', email: 'test@x.com', role: 'admin', active: true };
// ... test only cares about role:'admin', but had to write everything
});
`

If the User shape gains a new required field, every test breaks. And every test reads 80% boilerplate.

The factory pattern — with TypeScript types:

`ts
// types/index.ts
export interface User {
id: number;
name: string;
email: string;
role: 'admin' | 'editor' | 'viewer';
active: boolean;
}

// helpers/factories.ts
import { User } from '../types';

export function makeUser(overrides: Partial<User> = {}): User {
return {
id: 1,
name: 'Test User',
email: 'test@example.com',
role: 'viewer',
active: true,
...overrides, // spread the overrides LAST — they win over the defaults
};
}
`

Breaking this down:
- overrides: Partial<User> — the caller can pass *any subset* of User fields, or none at all. Partial<T> makes all fields optional.
- = {} — default value means the caller doesn't have to pass anything if all defaults are fine.
- ...overrides spread at the end — any field the caller provides replaces the default.

Using the factory in tests — each test overrides only what it needs:

`ts
import { makeUser } from '../helpers/factories';

test('admin sees delete button', async () => {
const user = makeUser({ role: 'admin' });
// user = { id:1, name:'Test User', email:'test@example.com', role:'admin', active:true }
});

test('inactive user is redirected to reactivation page', async () => {
const user = makeUser({ active: false });
// Only active:false changed — everything else is the default
});

test('uses default user when no overrides needed', async () => {
const user = makeUser();
// All defaults — no boilerplate in the test at all
});
`

TypeScript's type safety in action:

`ts
makeUser({ role: 'superuser' }); // ❌ compile error — 'superuser' is not a valid role
makeUser({ age: 30 }); // ❌ compile error — 'age' is not a field on User
makeUser({ role: 'admin' }); // ✅ valid override
`

The type system prevents typos in role names and unknown fields — errors you'd otherwise only catch when the test fails at runtime.

Rule of thumb:
- Put factories in a shared helpers/factories.ts file — one factory per entity (user, product, order, etc.)
- Use Partial<T> for the overrides parameter — never a plain object or any`.
- Spread overrides *after* the defaults — left-to-right, last write wins.
- Keep defaults realistic — use values that work for most tests so each test only overrides what's special about its scenario.

A callback is a function passed as an argument to another function, to be called back later. To type one, you write its full signature — its parameters and return type — using TypeScript's arrow-function syntax.

Basic syntax — inline callback type:

``ts
function fetchData(
url: string,
onSuccess: (data: User[]) => void
) {
fetch(url)
.then(res => res.json())
.then(users => onSuccess(users));
}

// Caller passes a function matching that exact shape:
fetchData("/users", (users) => {
console.log(users.length); // ✅ TypeScript knows 'users' is User[]
});
`

The signature (data: User[]) => void reads as: "a function that takes one argument of type User[] and returns nothing useful."

Named callback type for reuse:

If you use the same callback shape in multiple places, give it a name:

`ts
type SuccessHandler = (data: User[]) => void;
type ErrorHandler = (err: Error) => void;

function fetchData(url: string, onSuccess: SuccessHandler, onError: ErrorHandler) {
// ...
}
`

This is cleaner and lets you update the signature in one place.

Optional callbacks — mark with ?:

`ts
function retry(
fn: () => void,
onError?: (e: Error) => void // optional
) {
try {
fn();
} catch (e) {
onError?.(e instanceof Error ? e : new Error(String(e)));
}
}
`

Callback that returns a value:

`ts
function mapItems<T, U>(
items: T[],
transform: (item: T) => U // takes T, returns U
): U[] {
return items.map(transform);
}

const lengths = mapItems(["hello", "world"], (s) => s.length);
// TypeScript infers: lengths is number[]
`

The callback's return type U flows through to the final result type.

Common real-world examples — array methods:

The signatures you've used countless times in JavaScript are typed exactly this way under the hood:

`ts
// Simplified versions of built-in array methods:
interface Array<T> {
forEach(cb: (item: T, index: number) => void): void;
map<U>(cb: (item: T) => U): U[];
filter(cb: (item: T) => boolean): T[];
}
`

When you write users.map(u => u.name), TypeScript checks the callback's signature against (item: User) => string and infers the result as string[].

React event handlers — same idea:

`ts
interface ButtonProps {
label: string;
onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
}
`

Rule of thumb:
- Always type both the parameters AND the return type of a callback.
- Use a named type alias when the same callback shape appears in multiple functions.
- Use ? for optional callbacks; remember to call them with ?.() syntax inside the function.
- Don't type a callback as Function or any` — you lose all the safety the signature provides.

TypeScript types exist only in your source code — they are erased completely at runtime. The JSON your API returns is whatever the server actually sends, regardless of what your TypeScript says it should be. This is why any is the wrong tool for API responses: it doesn't add safety, it removes the safety you already had.

The naive approach — any — and why it fails:

``ts
const data: any = await res.json();
data.user.name.toUpperCase();
// 💥 If the API sends { error: "Not found" }, this crashes at runtime
// TypeScript said nothing — it trusted you blindly
`

With any, the type system goes completely silent. When the API changes shape or returns an error object, your code doesn't notice until it blows up in production.

Option 1 — unknown + a type guard:

unknown is the safe alternative to any. TypeScript won't let you access any property on an unknown value until you have proven its shape:

`ts
interface User { id: number; name: string; email: string; }

async function fetchUser(id: number): Promise<User> {
const res = await fetch(/users/${id});
const data: unknown = await res.json();

if (isUser(data)) {
return data; // ✅ TypeScript now knows data is User
}
throw new Error("API returned an unexpected shape");
}

function isUser(x: unknown): x is User {
return (
typeof x === "object" && x !== null &&
typeof (x as any).id === "number" &&
typeof (x as any).name === "string" &&
typeof (x as any).email === "string"
);
}
`

If the API sends garbage, the guard returns false and you get a clear error immediately — not a confusing crash three lines later.

Option 2 (recommended for production) — runtime validation with Zod:

Writing type guards by hand scales poorly. A schema library like Zod does the validation AND generates the TypeScript type from the same definition:

`ts
import { z } from "zod";

const UserSchema = z.object({
id: z.number(),
name: z.string().min(1),
email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;
// ↑ TypeScript infers: { id: number; name: string; email: string }
// No need to write the interface separately — one definition, two outputs.

async function fetchUser(id: number): Promise<User> {
const res = await fetch(/users/${id});
const data = await res.json();
return UserSchema.parse(data);
// ↑ throws a descriptive ZodError if any field is missing or wrong type
}
`

Zod gives you: runtime validation that throws on bad data, TypeScript types inferred automatically, and detailed field-level error messages that tell you exactly what was wrong.

The core principle — types are labels, not checks:

TypeScript types only tell you what something *should* be. At the API boundary, you need to verify what it *actually* is. The contract:
- At the boundary (API, localStorage, user input): validate with runtime code.
- Inside your app (after validation): trust TypeScript types fully.

Rule of thumb:
- Never type an API response as any — it defeats the entire point of TypeScript.
- Use unknown` + a type guard for simple or one-off calls.
- Use Zod (or Valibot, io-ts) for production code — one schema = validation + TypeScript type.

TypeScript maintains a precise map of every type's shape — every field name and its exact type. When you write obj.something, it looks up "does this type have a field called something?" If not, it refuses to compile. This is intentional: in JavaScript, accessing a missing property doesn't crash — it silently returns undefined, which causes confusing bugs two or three lines later. TypeScript catches this before your code ever runs.

The four most common causes — and how to fix each:

Cause 1 — Typo in the property name:

``ts
interface User { name: string; age: number; }
const user: User = getUser();

user.nane; // ❌ "Property 'nane' does not exist on type 'User'"
user.name; // ✅
`

TypeScript is your spell-checker for property names. Fix: correct the spelling. Your editor will autocomplete valid options.

Cause 2 — Property exists at runtime but isn't declared in your type:

`ts
interface User { name: string; } // email wasn't included
const user: User = getUser();

user.email; // ❌ "Property 'email' does not exist on type 'User'"
`

Fix: add the missing property to the interface:

`ts
interface User { name: string; email: string; }
`

Cause 3 — Property exists on only one branch of a union type:

`ts
type Shape =
| { kind: "circle"; radius: number }
| { kind: "square"; side: number };

const shape: Shape = getShape();
shape.radius; // ❌ TypeScript can't assume which branch you have
`

Fix: narrow the union first, then access the property:

`ts
if (shape.kind === "circle") {
shape.radius; // ✅ TypeScript now knows it's a circle
}
`

Cause 4 — Value is typed as unknown or object (no properties accessible):

`ts
const data: unknown = await res.json();
data.name; // ❌ TypeScript refuses all property access on 'unknown'
`

Fix: validate the shape first (type guard or Zod schema), then access properties inside the validated block.

The reflex to avoid — silencing with as any:

`ts
(user as any).nane; // ❌ compiles fine — and still returns undefined at runtime
`

This removes the type error without fixing the underlying problem. TypeScript is almost always right when it reports this error — the right question is "what does TypeScript think this type is, and why doesn't it include the property I expect?"

Rule of thumb:
- Read the full error — it names both the property and the type TypeScript sees.
- Fix the type or narrow the union; don't silence the error with as any`.
- When working with union types, always narrow first, then access narrow-only properties.

This is a very common situation in test automation — your internal User model has a passwordHash or password field, but the GET /users API response deliberately strips it for security. You need a type for the response that matches the actual JSON, without copying the whole interface and maintaining two versions.

The wrong approach — two parallel interfaces that drift apart:

``ts
// ❌ Duplicating the type by hand:
interface User {
id: number;
name: string;
email: string;
role: string;
passwordHash: string; // server-side only
}

interface UserApiResponse {
id: number;
name: string;
email: string;
role: string;
// passwordHash removed — but now you have two interfaces to maintain
}
// Add 'createdAt' to User? You must remember to add it to UserApiResponse too.
// This silently goes stale every time User changes.
`

The right approach — derive the response type using Omit:

`ts
// ✅ One source of truth:
interface User {
id: number;
name: string;
email: string;
role: 'admin' | 'editor' | 'viewer';
passwordHash: string;
}

type UserApiResponse = Omit<User, 'passwordHash'>;
// { id: number; name: string; email: string; role: 'admin'|'editor'|'viewer' }
`

Omit<User, 'passwordHash'> produces a new type that is identical to User except passwordHash is removed. Add a new field to User? UserApiResponse automatically includes it. Nothing to sync manually.

Using the type in a Playwright API test:

`ts
import { test, expect } from '@playwright/test';
import type { UserApiResponse } from '../types';

test('GET /users/:id returns user without password', async ({ request }) => {
const res = await request.get('/api/users/1');
expect(res.status()).toBe(200);

const user: UserApiResponse = await res.json();

expect(user.id).toBe(1);
expect(user.email).toBeDefined();

// TypeScript won't even let you write this — 'passwordHash' is not on the type:
// expect(user.passwordHash).toBeUndefined(); ← ❌ compile error
});
`

TypeScript prevents you from accidentally asserting on a field that shouldn't exist — which is exactly the kind of security regression you want to catch.

Removing multiple fields — use a union:

`ts
// Strip both server-managed fields:
type CreateUserInput = Omit<User, 'id' | 'passwordHash'>;
// Caller provides name, email, role — server fills in id and passwordHash
`

Rule of thumb:
- Use Omit<T, 'fieldName'> whenever the API returns a subset of your internal model.
- Prefer Omit over a hand-written parallel interface — one source of truth, no drift.
- To remove multiple fields: Omit<T, 'a' | 'b' | 'c'>.
- The opposite — keep only some fields — use Pick<T, 'a' | 'b'>`. Choose whichever list is shorter.

A string enum is TypeScript's way of defining a fixed, named set of string constants. Without one, order statuses in your codebase are just raw strings — and a typo like "SHIPED" is a perfectly valid string that compiles, passes linting, and breaks silently at runtime because the branch never matches. A string enum makes the complete set of valid values explicit and compiler-enforced.

The problem without an enum:

``ts
function processOrder(status: string) {
if (status === "SHIPED") { // ❌ typo — this branch never executes
sendTrackingEmail();
}
}

processOrder("SHIPPED"); // runs fine, but the typo above is invisible to TypeScript
`

TypeScript accepts any string — it can't know which strings are valid statuses.

Defining a string enum:

`ts
enum OrderStatus {
Pending = "PENDING",
Confirmed = "CONFIRMED",
Shipped = "SHIPPED",
Delivered = "DELIVERED",
Cancelled = "CANCELLED",
}
`

Each member maps a readable name (left) to the exact string that travels in JSON and logs (right). TypeScript knows the complete valid set.

Using the enum — the typo is now impossible:

`ts
function processOrder(orderId: string, status: OrderStatus): void {
switch (status) {
case OrderStatus.Shipped:
sendTrackingEmail(orderId);
break;
case OrderStatus.Cancelled:
refundCustomer(orderId);
break;
default:
updateStatusLog(orderId, status);
}
}

processOrder("ord-123", OrderStatus.Shipped); // ✅
processOrder("ord-123", "SHIPPED"); // ❌ compile error — must use the enum
processOrder("ord-123", OrderStatus.Shiped); // ❌ compile error — no such member
`

Safely parsing a raw API string into the enum:

At the API boundary the value arrives as a plain string. Validate it before trusting the enum type:

`ts
function parseOrderStatus(raw: string): OrderStatus {
if (Object.values(OrderStatus).includes(raw as OrderStatus)) {
return raw as OrderStatus;
}
throw new Error(Unexpected order status from API: "${raw}");
}

const status = parseOrderStatus(apiResponse.status); // ✅ validated before use
processOrder(apiResponse.id, status);
`

Why string enums, not numeric?

Numeric enums (Pending = 0, Confirmed = 1, ...) store integers. When 1 appears in a log, a database query, or a network request, it's meaningless without a lookup table. String enums store the human-readable value ("CONFIRMED") directly — logs and payloads are immediately readable by anyone, no decoder ring required.

Rule of thumb:
- Use string enums for any finite set of named states that travel in API responses or appear in logs.
- Always reference the enum member (OrderStatus.Shipped) in code — never the raw string ("SHIPPED"`) — so you get autocomplete, type checking, and rename refactoring for free.
- Validate raw API strings at the system boundary before casting to the enum type.

A test data factory is a function that builds a fully-typed test object with sensible defaults, but lets you override just the fields you care about in each test. Without one, every test file either duplicates the same object literal or passes incomplete objects that cause cryptic runtime errors.

Why this matters in test automation:
Role-based access control is one of the most common things QA engineers test. You need an admin user, a guest user, a regular user — and sometimes slight variations of each (e.g. an admin who is inactive). A factory function makes that trivial.

Step 1 — Define the User interface once:

``ts
// types/index.ts
export interface User {
id: number;
name: string;
email: string;
role: 'admin' | 'guest' | 'regular';
active: boolean;
}
`

The role field uses a string literal union — TypeScript will reject any value that isn't one of these three exact strings.

Step 2 — Write the factory with Partial<User> overrides:

`ts
// helpers/factories.ts
import type { User } from '../types';

export function makeUser(overrides: Partial<User> = {}): User {
return {
id: 1,
name: 'Test User',
email: 'test@example.com',
role: 'regular',
active: true,
...overrides, // caller's values replace the defaults above
};
}
`

Partial<User> means "an object where every field from User is optional." The spread (...overrides) replaces only the fields the caller provides — everything else keeps its default.

Step 3 — Use it in tests:

`ts
// Any single line creates a complete, typed User:
const admin = makeUser({ role: 'admin' });
const guest = makeUser({ role: 'guest', active: false });
const regular = makeUser(); // all defaults

// TypeScript enforces the union — this is a compile error:
const broken = makeUser({ role: 'superuser' }); // ❌ not a valid role
`

Step 4 — Add named shortcuts for common roles:

`ts
export const makeAdmin = (o: Partial<User> = {}) => makeUser({ role: 'admin', ...o });
export const makeGuest = (o: Partial<User> = {}) => makeUser({ role: 'guest', ...o });
export const makeRegular = (o: Partial<User> = {}) => makeUser({ role: 'regular', ...o });
`

Now a Playwright test reads cleanly:

`ts
test('admin can access settings page', async ({ page }) => {
const user = makeAdmin({ name: 'Alice' });
await loginAs(page, user);
await expect(page.locator('[data-testid="settings-nav"]')).toBeVisible();
});

test('guest cannot access settings page', async ({ page }) => {
const user = makeGuest();
await loginAs(page, user);
await expect(page.locator('[data-testid="settings-nav"]')).not.toBeVisible();
});
`

Rule of thumb:
Keep one factory per domain object in a shared helpers/factories.ts` file. Never copy-paste object literals across tests — when the User interface grows a new required field, you fix it in one place and every test stays green.

Converting a JavaScript function to TypeScript is mostly about making existing assumptions explicit. The function already works — you're adding a written contract that describes what it accepts and what it returns, so TypeScript can check every caller and catch misuse at compile time instead of at runtime.

The JavaScript starting point — assumptions are invisible:

``js
function formatCurrency(amount, currency) {
return new Intl.NumberFormat("en-US", {
style: "currency",
currency,
}).format(amount);
}

formatCurrency("twenty", "USD"); // no error — produces "$NaN"
formatCurrency(20, "BANANA"); // no error — crashes inside Intl at runtime
`

JavaScript quietly accepts wrong inputs. The bugs surface later, far from where the mistake was made.

Step 1 — Annotate parameter types and the return type:

`ts
function formatCurrency(amount: number, currency: string): string {
return new Intl.NumberFormat("en-US", {
style: "currency",
currency,
}).format(amount);
}

formatCurrency("twenty", "USD"); // ❌ compile error — amount must be number
`

Adding number to amount immediately prevents the first class of bug. The return type : string documents the contract and TypeScript verifies it.

Step 2 — Tighten loose types with literal unions:

currency: string still accepts "BANANA". The valid currency codes are a finite known set — express that:

`ts
type SupportedCurrency = "USD" | "EUR" | "GBP" | "INR";

function formatCurrency(amount: number, currency: SupportedCurrency): string {
return new Intl.NumberFormat("en-US", {
style: "currency",
currency,
}).format(amount);
}

formatCurrency(20, "USD"); // ✅
formatCurrency(20, "BANANA"); // ❌ compile error — not a SupportedCurrency
`

This is TypeScript's biggest practical win over plain string — the set of valid values is enforced everywhere the function is called.

Step 3 — Let TypeScript surface hidden inconsistencies:

TypeScript may flag things inside the function body that JavaScript ignored. For example, if you access a property that doesn't exist on the inferred type, or if a conditional branch produces the wrong type. Fix each complaint — they're usually revealing real assumptions the JavaScript was silently trusting.

Step 4 — Add a JSDoc comment for exported utilities:

`ts
/**
* Formats a number as a currency string.
* @param amount - The numeric amount to format.
* @param currency - ISO 4217 currency code.
*/
function formatCurrency(amount: number, currency: SupportedCurrency): string { ... }
`

Editors show this as a hover tooltip at every call site — instant inline documentation.

Rule of thumb:
- Always annotate both parameter types AND the return type, even when TypeScript can infer the return — it's documentation.
- Replace plain string or number` with literal unions wherever you know the valid values.
- Treat TypeScript's complaints in the function body as signals, not noise — each one is revealing an assumption the JavaScript was hiding.

The spread operator (...) copies properties from one object (or elements from one array) into another. In JavaScript you use it constantly for immutable updates and merging. TypeScript's job is to track the resulting type — which properties exist after the spread, what their types are, and which version wins when two spreads define the same property.

Object spread — TypeScript infers the merged type:

``ts
const defaults = { color: "blue", size: 12 };
const custom = { size: 16, bold: true };

const merged = { ...defaults, ...custom };
// TypeScript infers: { color: string; size: number; bold: boolean }
`

Notice: size appears in both objects. The later spread wins — merged.size is 16 (from custom). TypeScript knows this and types the final property based on the last source. Order matters.

Practical use — immutable updates in React and state management:

This is the most common reason you'll reach for object spread:

`ts
interface User { id: number; name: string; email: string; }

function updateUser(user: User, changes: Partial<User>): User {
return { ...user, ...changes };
// TypeScript verifies the result still satisfies the full User shape
}

const updated = updateUser(currentUser, { name: "Asha" });
// updated.id and updated.email are preserved from 'currentUser'
// updated.name is overwritten with "Asha"
`

This is the pattern behind React's setState merging and Redux reducers.

Array spread — TypeScript infers the element type:

`ts
const a: number[] = [1, 2];
const b: number[] = [3, 4];

const combined = [...a, ...b]; // TypeScript infers: number[]
const mixed = [...a, "hello"]; // TypeScript infers: (number | string)[]
const withItem = [0, ...a, 999]; // number[]
`

The inferred element type is the union of all element types across all spreads.

Function argument spread — requires a tuple type:

You can unpack an array into a function's argument list with spread. TypeScript checks the types:

`ts
function add(x: number, y: number): number { return x + y; }

const args: [number, number] = [1, 2]; // must be a tuple, not number[]
add(...args); // ✅ TypeScript verifies [number, number] matches (x: number, y: number)

const args2 = [1, 2]; // TypeScript infers number[] (length unknown)
add(...args2); // ❌ a "number[]" could have 0 or 100 elements — use as const or a tuple
`

Annotate as [number, number] or use as const to tell TypeScript it's exactly two numbers.

Rule of thumb:
- Object spread produces the union of all properties; later spreads override earlier ones for shared keys.
- Array spread produces an array whose element type is the union of all spreaded arrays' element types.
- For spreading into function calls, annotate the array as a tuple so TypeScript can verify arity and types.
- The pattern { ...existing, changedField: newValue }` is the idiomatic immutable update — TypeScript fully understands it.

Forgetting await on an async call is one of the most common bugs in TypeScript test automation. The function call runs but returns a Promise object — not the resolved value you expected. Your code then works on that Promise as if it were the real result, producing silent wrong behaviour or confusing errors that don't point to the real cause.

What "forgetting await" looks like:

``ts
// A helper that creates a user via API and returns the created User object:
async function createUser(data: Partial<User>): Promise<User> {
const response = await fetch('/api/users', { method: 'POST', body: JSON.stringify(data) });
return response.json();
}

// ❌ BUG — missing await:
test('new user can log in', async ({ page }) => {
const user = createUser({ name: 'Alice', role: 'regular' });
// user is Promise<User>, NOT User
await page.goto(/login?email=${user.email}); // user.email is undefined!
// The URL becomes /login?email=undefined — test fails with a cryptic mismatch
});
`

The test still runs — no crash at the createUser line — because you CAN put a Promise in a variable. The error only surfaces when you try to use the fields.

How TypeScript warns you — the compile error:

If you have strict mode on (you should), TypeScript flags this immediately:

`
Property 'email' does not exist on type 'Promise<User>'.
`

This tells you exactly what happened: you're accessing .email on a Promise, not on a User. The fix is one word: add await.

`ts
// ✅ FIXED:
const user = await createUser({ name: 'Alice', role: 'regular' });
await page.goto(/login?email=${user.email}); // user.email is now a real string
`

The same problem with Playwright's own async methods:

Playwright methods like page.title(), page.url(), and most locator calls return Promises. Forgetting await on them is especially common with assertions:

`ts
// ❌ Wrong — page.title() returns Promise<string>, not string:
expect(page.title()).toBe('Dashboard'); // always passes or behaves unpredictably

// ✅ Correct — await resolves the Promise first:
expect(await page.title()).toBe('Dashboard');

// ✅ Better — use Playwright's built-in async assertions:
await expect(page).toHaveTitle('Dashboard');
`

How to spot missing await at a glance:
- TypeScript error: "Property 'X' does not exist on type 'Promise<Y>'"
- ESLint rule: @typescript-eslint/no-floating-promises — warns when a Promise isn't awaited or explicitly ignored
- The test passes unexpectedly, or a navigation goes to a URL containing "undefined"

Rule of thumb:
Any function that returns Promise<T> must be awaited before you use its value. In Playwright tests, nearly every page.* and locator.* call is async — default to await` and remove it only if you deliberately don't need the result.

An async fetch function sits right at the TypeScript–runtime boundary: the return type tells every caller what they'll get, but the actual JSON from the server is untyped. Getting this right means being explicit about the data shape AND honest about the fact that the API might not send what you expect.

Step 1 — Define the shape with an interface:

``ts
interface User {
id: number;
name: string;
email: string;
active: boolean;
}
`

Step 2 — Annotate the function with Promise<User[]>:

An async function always wraps its return value in a Promise. If you want the caller to get User[], annotate the return type as Promise<User[]>:

`ts
async function getActiveUsers(): Promise<User[]> {
const res = await fetch("/api/users?active=true");

if (!res.ok) {
throw new Error(API error: ${res.status} ${res.statusText});
// ⚠️ fetch() does NOT throw on 4xx/5xx — you must check res.ok yourself
}

const data = await res.json() as User[];
return data;
}
`

The as User[] is a type assertion — it tells TypeScript "trust me, this is the shape." It works for internal code but provides no runtime guarantee.

What the caller gains from the typed return:

`ts
const users = await getActiveUsers();
// TypeScript knows: users is User[]

users.forEach(u => console.log(u.name, u.email)); // ✅ autocomplete works
users[0].nonExistent; // ❌ compile error — not on User
`

Every access on the result is checked. Rename a field in the interface and TypeScript finds every caller that needs updating.

Making it production-safe — validate the response with Zod:

as User[] trusts the server blindly. When the API changes shape (field renamed, field dropped), the code compiles but breaks at runtime. For production, validate the response:

`ts
import { z } from "zod";

const UserSchema = z.object({
id: z.number(),
name: z.string(),
email: z.string().email(),
active: z.boolean(),
});

const UserListSchema = z.array(UserSchema);
type User = z.infer<typeof UserSchema>; // TypeScript type inferred from the schema

async function getActiveUsers(): Promise<User[]> {
const res = await fetch("/api/users?active=true");
if (!res.ok) throw new Error(API error: ${res.status});
return UserListSchema.parse(await res.json());
// ↑ throws a descriptive ZodError if any item doesn't match — field-level detail
}
`

Rule of thumb:
- Always annotate async fetch functions with an explicit Promise<T> return type.
- Always check res.ok — fetch succeeds on 4xx/5xx, it just gives you an error body.
- Use as UserType for quick internal code; use Zod or a type guard for production API calls.
- The interface and the Zod schema should match — or better, derive the interface from the schema with z.infer<typeof Schema>` so there's only one source of truth.

Both type and interface let you describe the shape of an object in TypeScript. For plain object types, they are nearly interchangeable — TypeScript treats them structurally, so a type User and an interface User with the same fields are compatible everywhere. The real differences show up at the edges: things one can do that the other simply cannot.

For plain objects — either works:

``ts
interface User { id: number; name: string; }
type User = { id: number; name: string; };
// Structurally identical. You can use either anywhere the other is accepted.
`

What interface can do that type cannot:

1 — Declaration merging. Two interface declarations with the same name automatically combine:

`ts
// In your code:
interface Window { analytics: Analytics; }

// TypeScript merges this with the built-in Window interface automatically.
// This is how libraries extend Express.Request, jest globals, etc.
`

Two type aliases with the same name are a duplicate identifier error.

2 — extends for readable inheritance:

`ts
interface Animal { name: string; }
interface Dog extends Animal { breed: string; }
// Dog has: name (inherited) + breed (own)
`

type achieves this with & (intersection), but interface extends reads more clearly for hierarchical models.

What type can do that interface cannot:

1 — Union types — the most important difference:

`ts
type Status = "active" | "inactive" | "banned"; // ✅ only with type
type Result = { ok: true; data: User } | { ok: false; error: string };
type Nullable = User | null;
`

There is no way to express a union with interface.

2 — Aliases for primitives, tuples, and computed types:

`ts
type UserID = string; // primitive alias
type Pair = [string, number]; // tuple
type Callback = (err: Error | null) => void; // function signature
type ReadUsers = Readonly<User[]>; // utility type alias
`

None of these are expressible with interface.

The practical decision rule:

`
Defining an object/class shape? → interface (or type — either works)
Creating a union? → type (required)
Aliasing a primitive, tuple, or fn? → type (required)
Extending a library's type? → interface (declaration merging)
`

Rule of thumb:
- Use interface for object shapes — especially exported API contracts and class definitions.
- Use type for unions, primitives, tuples, and computed types.
- When either works, follow your team's convention — consistency matters more than the choice itself.
- The TypeScript team recommends preferring interface` for objects when either works, because its error messages tend to be more readable.

Test code has the same type-safety problems as application code — wrong argument order, renamed fields, incorrect property access — except the failures are often more confusing because they surface as mysterious test failures rather than obvious crashes. TypeScript in a test suite catches these mistakes at compile time, before a single test runs.

Benefit 1 — Typed page objects catch mistakes immediately:

Without types, passing the wrong argument type to a page object method silently produces wrong behaviour:

``ts
// Plain JavaScript — no safety:
await loginPage.login(email, password); // works
await loginPage.login(password, email); // ❌ args swapped — test passes wrong credentials silently

// TypeScript — swapped args are a compile error:
class LoginPage {
constructor(private page: Page) {}

async login(email: string, password: string): Promise<void> {
await this.page.fill("#email", email);
await this.page.fill("#password", password);
await this.page.click("button[type=submit]");
}
}
`

The method signature (email: string, password: string) doesn't prevent swapped strings — but it does catch passing a number, an object, or undefined. Combined with named parameters in a config object, it prevents the swap too.

Benefit 2 — Typed test data factories with Partial<T>:

A test factory with a typed interface means each test overrides only the fields it cares about, and wrong field names are caught immediately:

`ts
interface User { id: number; name: string; email: string; role: "admin" | "viewer"; }

function createTestUser(overrides: Partial<User> = {}): User {
return { id: 1, name: "Test User", email: "test@x.com", role: "viewer", ...overrides };
}

const admin = createTestUser({ role: "admin" }); // ✅
const bad = createTestUser({ rol: "admin" }); // ❌ typo — compile error
const wrong = createTestUser({ role: "superuser" }); // ❌ not a valid role — compile error
`

Benefit 3 — Typed API responses make assertions safe:

When you call an API in a test, typing the response means you can only assert on properties that actually exist:

`ts
const user = await apiClient.createUser({ name: "Asha", role: "admin" });
// TypeScript knows 'user' is User

expect(user.role).toBe("admin"); // ✅ autocomplete confirms .role exists
expect(user.permisisons).toBe("full"); // ❌ typo — compile error, not a runtime failure
`

Benefit 4 — Safe refactoring across the entire test suite:

This is the biggest long-term win. When the application changes a field name — say user.role becomes user.accessLevel — TypeScript immediately flags every test that references the old field name. No more hunting through hundreds of test files manually; the compiler gives you the full list.

`ts
// Rename 'role' to 'accessLevel' in the User interface:
// TypeScript instantly highlights every test that used user.role — compiler-guided refactor.
`

Rule of thumb:
- Type every page object method's parameters and return type — it's the minimum viable safety net.
- Use Partial<T> in test data factories so tests only specify what they care about.
- Type API response objects even in tests — assertions on non-existent fields should be compile errors, not silent undefined` comparisons.
- The real payoff is during refactors — TypeScript turns "find all usages manually" into "fix the compile errors."

A generic is a way to write a function, class, or interface that works with *any* type — but still gives you full type safety. Instead of hardcoding a specific type, you use a type parameter (usually written <T>) as a placeholder, and TypeScript fills it in from context when you call the code.

Why they exist — the problem without generics:

Without generics, you face a choice:

``ts
// Option A: write a version per type (tedious, not scalable)
function firstNumber(arr: number[]): number { return arr[0]; }
function firstString(arr: string[]): string { return arr[0]; }

// Option B: use any (no type safety — defeats the purpose of TypeScript)
function first(arr: any[]): any { return arr[0]; }

const val = first([1, 2, 3]);
val.toUpperCase(); // ❌ TypeScript allows this — no error — but it crashes at runtime
`

With a generic:

`ts
function first<T>(arr: T[]): T {
return arr[0];
}

const n = first([1, 2, 3]); // TypeScript infers T = number
n.toFixed(2); // ✅ number method — works
n.toUpperCase(); // ❌ TypeScript catches this at compile time

const s = first(["a", "b"]); // TypeScript infers T = string
s.toUpperCase(); // ✅ string method — works
`

TypeScript infers T automatically from your input — you rarely need to write first<number>([...]) explicitly.

Real-world use case — a typed API fetch helper:

`ts
async function fetchJson<T>(url: string): Promise<T> {
const res = await fetch(url);
return res.json() as T;
}

// Usage — TypeScript knows exactly what comes back:
const user = await fetchJson<{ id: number; name: string }>("/api/user/1");
console.log(user.name); // ✅ autocomplete works; typos caught at compile time
`

Rule of thumb:
- Use a generic when the function's logic doesn't care about the specific type, but the *caller* does.
- If you're tempted to write any`, ask yourself: "could this be a generic instead?"
- Generics preserve the type relationship between inputs and outputs — that's their superpower.

A generic constraint limits which types can be passed as a type parameter. You write it as <T extends SomeType>. Without it, TypeScript treats T as completely unknown — you can't access any properties on it, because they might not exist.

The problem without a constraint:

``ts
function getLength<T>(x: T): number {
return x.length; // ❌ Error: Property 'length' does not exist on type 'T'
}
`

TypeScript refuses because T could be number, boolean, or anything — and those don't have .length.

With a constraint:

`ts
function getLength<T extends { length: number }>(x: T): number {
return x.length; // ✅ safe — T is guaranteed to have a length property
}

getLength("hello"); // ✅ string — has .length
getLength([1, 2, 3]); // ✅ array — has .length
getLength(42); // ❌ compile-time error — number has no .length
`

The constraint says: "I'll accept any type, *as long as it has at least these members*."

A more practical example — constraining to a known interface:

`ts
interface HasId { id: number }

function findById<T extends HasId>(items: T[], id: number): T | undefined {
return items.find(item => item.id === id);
}

// Works with any object that has an id field:
findById([{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }], 1);
findById([{ id: 10, price: 99 }], 10);
`

Using keyof as a constraint — a very common pattern:

`ts
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
return obj[key];
}

const user = { id: 1, name: "Alice" };
getProperty(user, "name"); // ✅ returns string
getProperty(user, "age"); // ❌ "age" is not a key of user — caught at compile time
``

Rule of thumb:
- Add a constraint when your generic function needs to *use* something from the type — a property, method, or index.
- The constraint is the minimum contract: "give me anything that has at least this shape."

Utility types are built-in TypeScript generics that *transform* an existing type into a new one. Instead of rewriting an interface from scratch, you derive a variant from it — keeping the two in sync automatically.

Why they exist:

Imagine you have a User type. You need:
- A version for PATCH requests where all fields are optional.
- A public version without the password hash.
- A version for forms that only has name and email.

Without utility types, you'd write three separate interfaces. If User changes, all three need manual updates — a maintenance headache. Utility types solve this by deriving variants automatically.

The most common utility types:

``ts
interface User {
id: number;
name: string;
email: string;
passwordHash: string;
}

// Partial — all fields become optional (great for PATCH/update payloads)
type UserUpdate = Partial<User>;
// { id?: number; name?: string; email?: string; passwordHash?: string }

// Required — all fields become required (opposite of Partial)
type StrictUser = Required<User>;

// Readonly — all fields become read-only (great for immutable config objects)
type FrozenUser = Readonly<User>;
const u: FrozenUser = { id: 1, name: "Alice", email: "a@b.com", passwordHash: "x" };
u.name = "Bob"; // ❌ Error: cannot assign to 'name' — it is read-only

// Pick — keep only the listed fields
type UserPreview = Pick<User, "id" | "name">;
// { id: number; name: string }

// Omit — remove the listed fields
type SafeUser = Omit<User, "passwordHash">;
// { id: number; name: string; email: string }
`

Real-world use case — REST API types:

`ts
interface Product { id: number; name: string; price: number; stock: number; }

// POST /products — caller provides everything except id (server generates it)
type CreateProductDto = Omit<Product, "id">;

// PATCH /products/:id — caller provides only what changed
type UpdateProductDto = Partial<Omit<Product, "id">>;

// GET /products — public list view hides stock levels
type ProductSummary = Pick<Product, "id" | "name" | "price">;
`

One source type, three derived variants — all stay in sync if Product changes.

Rule of thumb:
- Partial — update payloads, form state, optional config.
- Omit — strip server-managed or sensitive fields.
- Pick — narrow a type to a subset for display or passing around.
- Readonly — config objects, props that must not be mutated.
- Required` — enforce that all optional fields were filled in before saving.

Record<K, V> is a utility type that constructs an object type where all keys are of type K and all values are of type V. It's the right tool whenever you're building a dictionary, lookup map, or mapping between a fixed set of keys and some value type.

Why it exists — the alternative is worse:

``ts
// Without Record — you lose key exhaustiveness checking:
const statusLabels: { [key: string]: string } = {
pending: "Waiting",
active: "Running",
// Forgot "failed"? TypeScript doesn't care — no error
};

// With Record over a union — TypeScript enforces every key is present:
type Status = "pending" | "active" | "failed";
const statusLabels: Record<Status, string> = {
pending: "Waiting",
active: "Running",
// ❌ Error: Property 'failed' is missing
// ↑ TypeScript catches the omission immediately
};
`

Three common patterns:

`ts
// 1. Simple string-key dictionary (dynamic keys, no exhaustiveness guarantee)
const userAges: Record<string, number> = { alice: 30, bob: 25 };

// 2. Union-key map (exhaustiveness guaranteed — all keys required)
type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
const methodColors: Record<HttpMethod, string> = {
GET: "green",
POST: "blue",
PUT: "orange",
DELETE: "red",
};

// 3. Lookup table (e.g. caching API results by id)
const userCache: Record<number, User> = {};
userCache[1] = { id: 1, name: "Alice" };
`

Real-world use case — role-to-permissions map:

`ts
type Role = "admin" | "editor" | "viewer";
type Permission = "read" | "write" | "delete";

const rolePermissions: Record<Role, Permission[]> = {
admin: ["read", "write", "delete"],
editor: ["read", "write"],
viewer: ["read"],
};

function canDo(role: Role, action: Permission): boolean {
return rolePermissions[role].includes(action);
}
`

If a new role is added to the Role union, TypeScript immediately flags that rolePermissions is incomplete — the map can never fall out of sync.

Rule of thumb:
- Use Record<Union, V> when you want to be forced to handle every key in a union.
- Use Record<string, V> or Record<number, V> for dynamic dictionaries where the key set isn't known at compile time.
- Prefer Record<K, V> over { [key: string]: V }` whenever K is a union — you get exhaustiveness checking for free.

Type narrowing is TypeScript's ability to refine a broad type to a more specific one inside a conditional branch. When you check something about a value — "is this a string?", "does this have a .name property?", "is this null?" — TypeScript tracks that check and adjusts what it believes the type is *inside* that branch.

Why it matters — union types are everywhere:

``ts
function format(x: string | number): string {
return x.toFixed(2); // ❌ Error: 'toFixed' does not exist on type 'string'
}
`

TypeScript sees x as string | number — it can't let you call .toFixed() because strings don't have that method. You must narrow first.

The four main ways to narrow:

`ts
// 1. typeof — works for primitives: string, number, boolean, bigint, symbol, undefined, function
function format(x: string | number): string {
if (typeof x === "string") {
return x.toUpperCase(); // TS: x is string here
}
return x.toFixed(2); // TS: x is number here (the only remaining option)
}

// 2. instanceof — works for class instances
function printDate(d: Date | string) {
if (d instanceof Date) {
console.log(d.toISOString()); // TS: d is Date
} else {
console.log(d.toUpperCase()); // TS: d is string
}
}

// 3. in — checks whether a property exists on an object
type Cat = { meow: () => void };
type Dog = { bark: () => void };

function makeSound(pet: Cat | Dog) {
if ("meow" in pet) {
pet.meow(); // TS: pet is Cat
} else {
pet.bark(); // TS: pet is Dog
}
}

// 4. Equality / truthiness — narrows away null and undefined
function greet(name: string | null) {
if (name !== null) {
console.log("Hello, " + name.toUpperCase()); // TS: name is string (not null)
}
}
`

Real-world use case — handling an API response that can succeed or fail:

`ts
type ApiResult =
| { status: "ok"; data: User }
| { status: "error"; message: string };

function handleResult(result: ApiResult) {
if (result.status === "ok") {
console.log(result.data.name); // TS: result is the success variant
} else {
console.error(result.message); // TS: result is the error variant
}
}
`

This pattern — narrowing by a shared discriminant field — is called a discriminated union and is one of TypeScript's most powerful features.

Rule of thumb:
- typeof for primitives, instanceof for classes, in for object shapes, equality checks for literals and null.
- TypeScript narrows automatically — you don't call any API; you just write a normal if` check.
- After the last branch, TypeScript uses the process of elimination — if something passes all negative checks, it knows the remaining type.

A user-defined type guard is a function that tells TypeScript "if this returns true, treat this value as a specific type." You signal it by writing value is SomeType as the return type instead of boolean.

Why it exists:
TypeScript automatically narrows simple checks like typeof x === 'string', but it cannot figure out what shape a custom object is from a generic helper like hasOwnProperty(obj, 'data'). A type guard bridges that gap — you write the runtime check once, and TypeScript trusts the result everywhere the function is called.

Walked-through example — typing API responses in tests:

``ts
interface SuccessResponse {
status: 'success';
data: { userId: number; email: string };
}

interface ErrorResponse {
status: 'error';
message: string;
}

type ApiResponse = SuccessResponse | ErrorResponse;

// The response is SuccessResponse return type is the type guard
function isSuccessResponse(response: ApiResponse): response is SuccessResponse {
return response.status === 'success';
}

// In a Playwright API test:
const raw = await request.get('/api/user/1');
const body: ApiResponse = await raw.json();

if (isSuccessResponse(body)) {
// TypeScript knows body is SuccessResponse inside this block
expect(body.data.email).toContain('@'); // no type error
} else {
// TypeScript knows body is ErrorResponse here
throw new Error(API failed: ${body.message});
}
`

Real-world QA use case:
Any time your API can return success or error shapes, a type guard makes your assertion code safe — you access .data only where it exists, and .message only where that exists. No casting with as`, no runtime surprises.

Rule of thumb: Write a type guard whenever TypeScript can't narrow a union automatically from your runtime check — write the logic once, get compile-time narrowing everywhere it's called.

A discriminated union is a set of object types that all share one common field with a literal value — that field is the "discriminant." TypeScript reads it and automatically narrows to the right shape without any casting.

Why it exists:
When a value can be one of several different shapes (API responses, test results, page states), you need a reliable way to tell them apart at runtime while keeping TypeScript informed. The discriminant field is that reliable signal — TypeScript uses it to guarantee exhaustive handling and catch missed cases at compile time.

Walked-through example — test result states:

``ts
type TestResult =
| { status: 'passed'; durationMs: number }
| { status: 'failed'; durationMs: number; errorMessage: string }
| { status: 'skipped'; reason: string };

function summarize(result: TestResult): string {
switch (result.status) {
case 'passed':
// TypeScript knows only durationMs is available here
return Passed in ${result.durationMs}ms;
case 'failed':
// TypeScript knows errorMessage exists in this branch
return FAILED: ${result.errorMessage} (${result.durationMs}ms);
case 'skipped':
// TypeScript knows only reason is available here
return Skipped — ${result.reason};
}
}
`

If you add a fourth status (e.g. 'timedout') to the union without handling it in the switch, TypeScript will warn you — nothing slips through.

Real-world QA use case:
Model API responses as a discriminated union ({ status: 'ok'; data: T } | { status: 'error'; code: number; message: string }). Your assertion helpers can safely branch on status and access fields that only exist on that branch — no as casts, no optional chaining on fields that should always be there.

Rule of thumb: Any time you have a union of object types, add a literal status or kind` field — it makes narrowing automatic and your switch/if branches exhaustive.

keyof T produces a union of all the property names of type T. It lets you write functions that only accept valid keys of an object — TypeScript catches typos and nonexistent properties at compile time.

Why it exists:
Without keyof, you'd use string for property-name parameters and lose all safety — TypeScript can't tell whether "baseURL" is a valid key or a typo for "baseUrl". keyof narrows the type down to only the keys that actually exist on the object.

Walked-through example — type-safe config lookup in tests:

``ts
interface TestConfig {
baseUrl: string;
timeout: number;
retries: number;
}

// K must be a real key of TestConfig — no arbitrary strings allowed
function getConfigValue<K extends keyof TestConfig>(
config: TestConfig,
key: K
): TestConfig[K] { // return type matches the key (string or number)
return config[key];
}

const config: TestConfig = {
baseUrl: 'https://staging.example.com',
timeout: 30000,
retries: 2,
};

const url = getConfigValue(config, 'baseUrl'); // type: string ✓
const timeout = getConfigValue(config, 'timeout'); // type: number ✓
getConfigValue(config, 'baseURL'); // TS error: 'baseURL' not in TestConfig ✓
`

TestConfig[K] is an *indexed access type* — it looks up the value type for key K, so the return type is always correct without any casting.

Real-world QA use case:
Test helpers that read values from environment config, page object properties, or API response fields often take a field name as a parameter. Using keyof means a test author can't pass a typo'd field name — the error shows at development time, not at 3 AM in CI.

Rule of thumb: Any time a function takes a property name as an argument, replace string with keyof TheType` — you get compile-time key validation for free.

In a type position, typeof someVariable gives you the TypeScript type of that variable — without you having to write an interface manually. The value becomes the single source of truth; the type stays in sync automatically.

Why it exists:
In test automation, you often create objects first (config, fixtures, response shapes) and then want to type-check functions against them. Writing a separate interface that mirrors the object is duplication — if the object changes, you have to update the interface too. typeof eliminates that duplication.

Walked-through example — deriving a type from a test fixture:

``ts
// Define the fixture value first — no interface needed alongside it
const defaultUser = {
id: 1,
email: 'tester@example.com',
role: 'admin' as const, // 'as const' keeps the literal type 'admin'
};

// Derive the type from the value — stays in sync if the object changes
type User = typeof defaultUser;
// Equivalent to: { id: number; email: string; role: 'admin' }

// Factory function typed against the derived type
function createUser(overrides: Partial<typeof defaultUser>): typeof defaultUser {
return { ...defaultUser, ...overrides };
}

const guest = createUser({ email: 'guest@example.com' }); // type-checked ✓
createUser({ role: 'superadmin' }); // TS error: not assignable to 'admin' ✓
`

Note: this is different from the *runtime* typeof operator that returns a string like "number" or "object". The type-level typeof only exists at compile time — it disappears in the compiled JS.

Real-world QA use case:
Playwright fixtures, test data factories, and environment config objects are all good candidates. Define the object once, use typeof to derive the type for factory functions and helper parameters — no interface duplication.

Rule of thumb: Reach for typeof` when you already have a value and need a type to match it — let the value be the blueprint instead of maintaining both in parallel.

An index signature describes an object where you don't know the exact key names ahead of time, but you know every key will be a string (or number) and every value will be a specific type. It types the pattern — "any key you look up returns X" — rather than listing every individual key.

Why it exists:
HTTP headers, query parameters, environment variables, and test data lookup tables are all dictionaries — you know the value type but you can't enumerate every key name at design time. An index signature types this pattern without forcing you to list every possibility.

Walked-through example — typing HTTP headers in a Playwright helper:

``ts
// The [headerName: string]: string part is the index signature
interface HttpHeaders {
[headerName: string]: string;
}

// A reusable POST helper that accepts extra headers
async function postJson(
request: APIRequestContext,
url: string,
body: unknown,
extraHeaders: HttpHeaders = {}
): Promise<APIResponse> {
return request.post(url, {
data: body,
headers: {
'Content-Type': 'application/json',
...extraHeaders, // any string→string additions accepted
},
});
}

// Test usage — any header key works, value must be a string
await postJson(request, '/api/orders', payload, {
'X-Test-Run-Id': 'run-42',
'Authorization': Bearer ${token},
});

// TypeScript catches wrong value types:
await postJson(request, '/api/orders', payload, {
'X-Retry-Count': 3, // Error: number is not assignable to string ✓
});
`

Index signatures and specific named properties can coexist, but every named property's type must be assignable to the index signature's value type.

Real-world QA use case:
Use index signatures for header maps, environment variable objects (Record<string, string> is shorthand), query-param builders, or any test-data lookup table where keys are dynamic.

Rule of thumb: Use an index signature (or Record<string, ValueType>`) when you know the shape of values but not the names of keys — it types the dictionary pattern without enumerating every entry.

Record<K, V> creates an object type where every key is of type K and every value is of type V. In test automation it is perfect for building a lookup table that drives many test scenarios from a single source — especially for role-based access control tests.

Why it matters:
Without Record, you write separate test cases for each role, repeating the same logic. Record lets you define all roles and expected outcomes in one place, then loop over them. TypeScript enforces that every role has an entry — if you add a new role and forget to add it to the table, the code won't compile.

Step 1 — Define the types:

``ts
type Role = 'admin' | 'regular' | 'guest';

interface Permissions {
canAccessDashboard: boolean;
canEditUsers: boolean;
canDeleteData: boolean;
}
`

Step 2 — Build the lookup table:

`ts
const rolePermissions: Record<Role, Permissions> = {
admin: { canAccessDashboard: true, canEditUsers: true, canDeleteData: true },
regular: { canAccessDashboard: true, canEditUsers: false, canDeleteData: false },
guest: { canAccessDashboard: false, canEditUsers: false, canDeleteData: false },
};
`

TypeScript flags a compile error if you: miss a role key, misspell a role, or put the wrong value shape in any entry.

Step 3 — Drive a Playwright test from the table:

`ts
const roles = Object.keys(rolePermissions) as Role[];

for (const role of roles) {
test(${role} sees correct nav options, async ({ page }) => {
const user = makeUser({ role });
await loginAs(page, user);
const expected = rolePermissions[role];

if (expected.canAccessDashboard) {
await expect(page.locator('[data-testid="dashboard-link"]')).toBeVisible();
} else {
await expect(page.locator('[data-testid="dashboard-link"]')).not.toBeVisible();
}
});
}
`

One loop generates three fully-typed tests. Add a new value to Role and TypeScript forces you to add it to rolePermissions before the code compiles.

Rule of thumb:
Use Record<Role, X>` any time you have a fixed set of keys (roles, environments, browsers, statuses) and a data object per key. It is the cleanest way to write data-driven tests with compile-time completeness checking.

An async function always returns a Promise. You type the value that the promise will eventually resolve to — not the Promise wrapper itself. await unwraps the Promise<T> back to T so the rest of your code sees the resolved value directly.

Why it matters:
Every Playwright API call (page.goto(), request.get(), locator.textContent()) returns a Promise. Typing the resolved value correctly means TypeScript knows exactly what you're working with after await — and catches mistakes like accessing .data on a response that only has .body.

Walked-through example — typed API call in a Playwright test:

``ts
interface UserResponse {
id: number;
email: string;
role: 'admin' | 'user';
}

// Return type is Promise<UserResponse> — type the resolved value, not the wrapper
async function fetchUser(
request: APIRequestContext,
userId: number
): Promise<UserResponse> {
const response = await request.get(/api/users/${userId});
// response.json() returns Promise<unknown> — cast to your known shape
return response.json() as UserResponse;
}

// Usage in a test — await unwraps Promise<UserResponse> → UserResponse
const user = await fetchUser(request, 42);
expect(user.role).toBe('admin'); // TypeScript knows .role exists ✓
expect(user.score).toBe(100); // TS error: 'score' doesn't exist ✓
`

Awaited<T> is a utility type that extracts the resolved type from a Promise<T> — useful when you want to derive a type from an async function's return type without calling it.

Real-world QA use case:
Type every helper that wraps an HTTP call with Promise<YourResponseShape>. This means autocomplete works on response fields in tests, and TypeScript catches the moment an API response shape changes and your test assertions no longer match.

Rule of thumb: In the return type annotation, always write the resolved value type (Promise<UserResponse>), never Promise<any>` — that's where the safety lives.

You wrap await calls in try/catch. The critical detail: TypeScript types the caught value as unknown — not Error — because JavaScript lets you throw anything (a string, a number, a plain object). You must narrow before accessing any properties on it.

Why it matters:
If you write catch (e) { console.log(e.message) } without narrowing, TypeScript gives you an error — because e might not be an Error object and .message might not exist. This forces you to handle unexpected error shapes rather than silently crashing.

Walked-through example — API call in a Playwright test:

``ts
async function deleteUser(request: APIRequestContext, userId: number): Promise<void> {
try {
const response = await request.delete(/api/users/${userId});

if (!response.ok()) {
// Throw a proper Error so callers can catch and inspect
throw new Error(Delete failed: ${response.status()} ${response.statusText()});
}
} catch (e) {
// e is typed unknown — narrow before accessing anything
if (e instanceof Error) {
console.error(deleteUser error: ${e.message});
throw e; // re-throw so the test fails with context
}
// Non-Error throw (rare but possible from third-party code)
throw new Error(deleteUser: unexpected error — ${String(e)});
}
}
`

Common pitfall: Promise.reject() and Playwright's network errors both reach your catch block — but a Playwright timeout throws a TimeoutError (subclass of Error), while a DNS failure throws a plain Error. Always narrow with instanceof Error before reading .message.

Real-world QA use case:
Wrap API calls in helpers that catch, log, and re-throw with context. Tests should fail with a clear message like "POST /api/login failed: 401 Unauthorized" — not "Cannot read properties of undefined."

Rule of thumb: Always narrow catch (e) with instanceof Error before using .message` — TypeScript forces this, and it protects you from unexpected thrown values in production code paths.

TypeScript has two export styles. Named exports let a file export many things by name — callers import using those exact names. Default exports let a file export one main thing — callers can import it under any name they choose.

Why it matters in test projects:
Test utilities, page objects, and fixture files often export multiple helpers. Named exports make it immediately clear what's available and let editors auto-import the right thing. Default exports are fine for single-class files but get confusing when everyone renames the import differently.

Walked-through example — a Playwright helper module:

``ts
// helpers/api.ts — named exports (preferred for multi-export files)
export async function getAuthToken(request: APIRequestContext): Promise<string> {
const res = await request.post('/api/login', { data: { user: 'test', pass: 'test' } });
const body = await res.json();
return body.token;
}

export async function deleteUser(request: APIRequestContext, id: number): Promise<void> {
await request.delete(/api/users/${id});
}

// In a test file — import by exact name, IDE autocomplete fills these in
import { getAuthToken, deleteUser } from '../helpers/api';
`

`ts
// pages/LoginPage.ts — default export (reasonable for a single-class file)
export default class LoginPage {
constructor(private page: Page) {}
async login(email: string, password: string) { /* ... */ }
}

// In a test — caller chooses the local name
import LoginPage from '../pages/LoginPage';
`

The rename problem with defaults: nothing stops one test file from writing import LP from '../pages/LoginPage' and another writing import Login from '../pages/LoginPage'`. Both work, but the codebase becomes inconsistent. Named exports prevent this.

Real-world QA use case:
Playwright test projects typically use named exports for shared fixtures, helper functions, and constants. Default exports are common for Page Object classes where each file holds exactly one class.

Rule of thumb: Use named exports for utility files and anything with more than one export. Default exports are fine for single-class Page Object files — but pick one convention and stick to it across the project.

as const tells TypeScript to treat a value as the most specific, read-only type possible — instead of widening it to a general type. An array of strings stays as a tuple of exact string literals; an object's values stay as literal types instead of broad primitives.

Why it matters:
TypeScript's default behavior is to widen: ["smoke", "regression"] becomes string[], not readonly ["smoke", "regression"]. That widening throws away the specific values. as const preserves them so you can derive precise union types and prevent accidental mutation.

Walked-through example — typed test tags:

``ts
// Without as const — TypeScript widens to string[]
const tags = ['smoke', 'regression', 'critical'];
type Tag = typeof tags[number]; // string (useless — any string allowed)

// With as const — TypeScript keeps the literals
const TEST_TAGS = ['smoke', 'regression', 'critical'] as const;
type Tag = typeof TEST_TAGS[number]; // 'smoke' | 'regression' | 'critical'

// Now this function only accepts valid tag values
function tagTest(name: string, tag: Tag): void {
console.log([${tag}] ${name});
}

tagTest('Login flow', 'smoke'); // ✓
tagTest('Login flow', 'slow'); // TS error: not assignable to Tag ✓
`

`ts
// as const on an object locks every value to its literal type
const ENV_URLS = {
staging: 'https://staging.example.com',
prod: 'https://app.example.com',
} as const;

type Env = keyof typeof ENV_URLS; // 'staging' | 'prod'
`

Real-world QA use case:
Use as const for test tag enumerations, environment name maps, HTTP method constants, and any config object where the exact values matter. It's lighter than a full TypeScript enum and works better with typeof.

Rule of thumb: Reach for as const` when you want TypeScript to remember the exact values in an array or object, not just the general type — it turns raw data into a typed constant you can derive unions from.

The non-null assertion operator (!) is a postfix operator that tells TypeScript "I guarantee this value is not null or undefined right here." TypeScript removes those possibilities from the type and stops warning about them — but it does nothing at runtime. If you're wrong, you get a runtime crash.

Why it exists:
Sometimes TypeScript infers that a value might be null — because a DOM query, an optional field, or an environment variable might not exist — but you have context the compiler doesn't. The ! operator lets you say "trust me on this one" without adding a runtime check.

Walked-through example — Playwright environment config:

``ts
// process.env values are string | undefined — TypeScript insists you handle undefined
const baseUrl: string | undefined = process.env.BASE_URL;

// Option 1: proper null check (preferred — fails fast with a clear message)
if (!baseUrl) {
throw new Error('BASE_URL environment variable is required');
}
// baseUrl is now string here — TypeScript narrowed it

// Option 2: non-null assertion (use only when you're certain it's set)
const url: string = process.env.BASE_URL!; // asserts it's not undefined
`

`ts
// Common misuse to avoid — map() returns T | undefined when find() is used
const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
const found = users.find(u => u.id === 1)!; // ! here is reasonable if you know it exists
found.name; // safe if the assertion was correct
`

When ! is appropriate vs when to use a real check:
- Use a real check (if (!x) throw new Error(...)) for environment variables, external config, and anything that might genuinely be absent — fail with a meaningful message instead of a cryptic Cannot read properties of undefined.
- Use ! for values you can prove exist from surrounding context — e.g., after a find() on a list you just created, or in a test fixture setup block where the value is always assigned before use.

Real-world QA use case:
Playwright's page.locator() returns a Locator, not Locator | null — so ! isn't needed there. But optional fields in API response types (user.address?.city) or test fixture optional properties are common places where teams reach for ! when they should use a proper guard.

Rule of thumb: Treat ! like a loan — use it only when you're certain you can repay it. Every !` is a pinky promise to the compiler; add a comment explaining why the value is guaranteed if it's not obvious.

This is one of the most common typing challenges when building a shared Playwright helper layer. Some callers have a CSS selector string ready; others already hold a Locator from a previous call. The solution is a union parameter type combined with a type guard that resolves both to a Locator at the top of the function.

Why this situation comes up:
In a Page Object you get a Locator from a method. In a quick one-off helper you might just pass a selector string. You want one function that handles both without forcing callers to convert.

The typed helper — union + typeof check:

``ts
import { Page, Locator } from '@playwright/test';

async function safeClick(page: Page, target: string | Locator): Promise<void> {
const locator = typeof target === 'string'
? page.locator(target) // resolve string to Locator once
: target; // already a Locator — use as-is

await locator.click();
}
`

The typeof check is a type guard — inside the ternary's true branch TypeScript knows target is string; in the false branch it knows it is Locator. Resolving to a single Locator at the top means the rest of the function only deals with one type.

Calling the helper — both forms work:

`ts
// CSS selector string:
await safeClick(page, '#submit-button');
await safeClick(page, '[data-testid="login-btn"]');

// Playwright Locator:
const btn = page.getByRole('button', { name: 'Submit' });
await safeClick(page, btn);
`

Extending to a helper base class:

`ts
class ActionHelper {
constructor(private page: Page) {}

private resolve(target: string | Locator): Locator {
return typeof target === 'string' ? this.page.locator(target) : target;
}

async fill(target: string | Locator, value: string): Promise<void> {
await this.resolve(target).fill(value);
}

async getText(target: string | Locator): Promise<string> {
return this.resolve(target).innerText();
}
}
`

A private resolve() method handles the conversion once — all other methods just call it.

Rule of thumb:
Use string | Locator for any helper that wraps Playwright interactions. Resolve to Locator immediately via a ternary — don't repeat the typeof` check deeper in the function body.

Both model a fixed set of allowed values, but they behave differently. A union of string literals is a pure compile-time type — zero runtime footprint, easy to narrow, and works naturally with as const. An enum generates actual runtime JavaScript — an object you can iterate over and look up by value — which adds weight but occasionally that's what you need.

Why the choice matters:
In test automation, you're defining things like test levels, environments, browser names, and API status categories. These are usually just labels — you compare strings, you don't iterate. A literal union is the lighter, simpler fit. Enums become worth the tradeoff when you genuinely need to iterate over all values at runtime (e.g., run tests for every environment in a loop from the enum keys).

Walked-through example — test environment in a Playwright config:

``ts
// Option A: literal union (preferred for most QA use cases)
type Environment = 'staging' | 'uat' | 'production';

function getBaseUrl(env: Environment): string {
const urls: Record<Environment, string> = {
staging: 'https://staging.example.com',
uat: 'https://uat.example.com',
production: 'https://app.example.com',
};
return urls[env];
}

getBaseUrl('staging'); // ✓
getBaseUrl('dev'); // TS error: not assignable to Environment ✓
`

`ts
// Option B: enum (useful when you need to iterate over all values)
enum Browser { Chromium = 'chromium', Firefox = 'firefox', WebKit = 'webkit' }

// You can iterate enum values at runtime — hard with a literal union
Object.values(Browser).forEach(b => console.log(Running tests in: ${b}));
`

The key practical differences:
- Literal unions: no runtime cost, tree-shaken away, plays well with typeof and as const
- Enums: generate runtime code, allow iteration and reverse lookups, slightly more verbose to define

Real-world QA use case:
Use literal unions for test tags, status codes, environment names, and HTTP methods. Reach for enums when you need to loop over all values at test-runner setup time (e.g., running a smoke suite across all browsers in a for...of` over enum values).

Rule of thumb: Default to a literal union. Switch to an enum only when you need to iterate over every value at runtime — that's the one thing unions can't do cleanly.

Playwright fires network events during test execution and lets you hook into them with page.on(). The callback receives a strongly-typed Request object — importing and using this type gives you full autocomplete on URL, method, headers, and post body, and prevents accessing properties that don't exist.

Why the types matter here:
Without the Request type annotation, TypeScript infers the parameter as any and you lose all safety. Import Request from '@playwright/test' (not from Node or the browser — Playwright has its own type).

Logging outgoing requests during a test:

``ts
import { Page, Request } from '@playwright/test';

// Typed handler — full autocomplete on request.url(), .method(), .headers(), etc.
const logRequest = (request: Request): void => {
console.log([${request.method()}] ${request.url()});
};

page.on('request', logRequest);
// Remember to clean up after the test:
page.off('request', logRequest);
`

Asserting a specific endpoint was called:

`ts
const calledUrls: string[] = [];
page.on('request', (req: Request) => {
calledUrls.push(req.url());
});

await page.click('[data-testid="save-button"]');

expect(calledUrls.some(url => url.includes('/api/save'))).toBe(true);
`

Intercepting and mocking with page.route() — uses Route and Request:

`ts
import { Route, Request } from '@playwright/test';

await page.route('**/api/users', async (route: Route, request: Request) => {
if (request.method() === 'GET') {
await route.fulfill({
status: 200,
contentType: 'application/json',
body: JSON.stringify([{ id: 1, name: 'Mock User' }]),
});
} else {
await route.continue(); // pass through POST, PUT, etc.
}
});
`

Playwright's key network types:
- Request — outgoing request (url, method, headers, postData)
- Response — incoming response (status, body, headers)
- Route — intercept handle (fulfill, continue, abort)

Rule of thumb:
Always import the specific Playwright type (Request, Response, Route`) rather than leaving the callback untyped. The extra import costs one line; the autocomplete and error-catching it buys are worth it every time.

When a JavaScript library doesn't include TypeScript types, you have three options in order of preference: check if the library already bundles types, install community types from DefinitelyTyped, or write a minimal declaration yourself.

Why this comes up in test projects:
Many test utilities — older assertion libraries, custom reporters, data generators, logging tools — are plain JavaScript. Without types, every import gives you any and you lose autocomplete and error-catching. Adding types, even minimal ones, restores that safety.

Walked-through example — the three options:

``ts
// Option 1: library already bundles types (most modern packages)
// e.g., Playwright, Zod, Axios all ship their own — nothing to do
import { chromium } from 'playwright'; // types included ✓

// Option 2: install community types from DefinitelyTyped
// Check at https://www.npmjs.com/~types or search @types/<name>
// npm install -D @types/lodash
import _ from 'lodash';
_.chunk([1, 2, 3, 4], 2); // now fully typed ✓

// Option 3: write a minimal declaration file when @types doesn't exist
// Create: types/some-legacy-lib.d.ts
`

`ts
// types/some-legacy-lib.d.ts
declare module 'some-legacy-reporter' {
export function report(results: { passed: number; failed: number }): void;
export function init(outputDir: string): void;
}
`

`ts
// tsconfig.json — tell TypeScript where to find your declarations
{
"compilerOptions": {
"typeRoots": ["./types", "./node_modules/@types"]
}
}
`

You only need to type the parts you actually use — not the entire library API.

Real-world QA use case:
You're integrating a legacy test data generator or a custom CI reporting tool that has no types. Write a .d.ts with just the function signatures you call — it takes 10 minutes and saves the entire team from any-typed calls for the life of the project.

Rule of thumb: Check for bundled types first, then @types/, then write a minimal .d.ts` for only the surface area you actually use.

satisfies validates that a value matches a type at compile time, but without widening the value's inferred type. You get the safety of a type annotation and the specificity of direct inference — the best of both.

Why it exists — the problem it solves:
A regular type annotation (const x: SomeType = ...) widens the inferred type to SomeType, so TypeScript forgets the exact literal values. as is the opposite problem — it bypasses checking entirely. satisfies validates against the type without losing the specific inferred type.

Walked-through example — test environment config:

``ts
type EnvConfig = Record<string, { baseUrl: string; timeout: number }>;

// With a type annotation — TypeScript widens to EnvConfig
// You lose autocomplete on specific keys like cfg.staging
const cfg1: EnvConfig = {
staging: { baseUrl: 'https://staging.example.com', timeout: 30000 },
prod: { baseUrl: 'https://app.example.com', timeout: 10000 },
};
cfg1.staging; // type: { baseUrl: string; timeout: number } ✓
cfg1.nope; // no error — EnvConfig allows any string key ✗

// With satisfies — validates shape, keeps exact keys
const cfg2 = {
staging: { baseUrl: 'https://staging.example.com', timeout: 30000 },
prod: { baseUrl: 'https://app.example.com', timeout: 10000 },
} satisfies EnvConfig;

cfg2.staging; // type: { baseUrl: string; timeout: number } ✓
cfg2.nope; // TS error: 'nope' doesn't exist on this object ✓
cfg2.staging.baseUrl; // string ✓ — full autocomplete preserved
`

The validation catches mistakes (wrong shape, typo'd field names) while the inferred type retains the exact keys — so accessing a key that doesn't exist is an error.

Real-world QA use case:
Use satisfies for test configuration objects, role-permission maps, and browser launch options. You validate the shape is correct AND keep specific key access with full type safety — no as casts needed downstream.

Rule of thumb: Reach for satisfies` instead of a type annotation when you want validation without losing the specific inferred type. Think of it as "check this matches the contract, but remember what it actually is."

unknown is TypeScript's safe version of any. You cannot do anything with an unknown value — no property access, no method calls, no arithmetic — until you've proven what type it is through a narrowing check. TypeScript enforces this at compile time.

Why unknown exists and why it matters:
any turns off type checking entirely — it lets you access any property without proof. unknown says "this could be anything, but you must prove what it is before using it." API responses, JSON.parse() results, and catch block errors are all unknown (or should be) — they cross a trust boundary where you genuinely don't know the shape.

Walked-through example — API response body:

``ts
async function fetchUserData(request: APIRequestContext, id: number): Promise<string> {
const response = await request.get(/api/users/${id});
const body: unknown = await response.json(); // explicitly unknown — could be anything

// Can't do this — TypeScript blocks it:
// return body.email; ❌ Error: body is unknown

// Option 1: typeof check (for primitives)
if (typeof body === 'string') return body;

// Option 2: property check (for objects)
if (
typeof body === 'object' &&
body !== null &&
'email' in body &&
typeof (body as { email: unknown }).email === 'string'
) {
return (body as { email: string }).email;
}

throw new Error('Unexpected response shape from /api/users');
}
`

`ts
// Option 3: use Zod for cleaner runtime validation (recommended for complex shapes)
import { z } from 'zod';

const UserSchema = z.object({ id: z.number(), email: z.string() });

const body: unknown = await response.json();
const user = UserSchema.parse(body); // throws if shape is wrong
return user.email; // fully typed ✓
`

Real-world QA use case:
In API tests, never cast response bodies directly with as YourType — that silently accepts wrong shapes. Keep the body as unknown and validate its shape. If validation fails, the test fails with a clear "unexpected response shape" message rather than a cryptic undefined property access error three lines later.

Rule of thumb: unknown is the correct type at trust boundaries (API responses, catch blocks, JSON.parse). Narrow it immediately — use typeof/instanceof` for simple cases, Zod for complex object shapes.

You define an interface for the expected shape and then either cast the parsed result to that interface (quick but no runtime guarantee) or validate it with a schema library like Zod (slower to set up, but catches real shape mismatches at test time).

Why this matters in API testing:
response.json() in Playwright returns Promise<any> — TypeScript has no idea what shape it is. Without typing it, you lose all autocomplete and the compiler can't catch when you access a field that doesn't exist or changed name. With a runtime validator like Zod, your test actually fails when the API breaks its contract — not silently passes with undefined values.

Walked-through example — two approaches:

``ts
// Approach 1: type assertion (fast, no runtime check)
interface OrderResponse {
orderId: string;
status: 'pending' | 'shipped' | 'delivered';
total: number;
}

const response = await request.post('/api/orders', { data: orderPayload });
const body = await response.json() as OrderResponse;

// TypeScript trusts your assertion — but if the API sends { order_id: ... }
// instead of { orderId: ... }, this silently gives you undefined
expect(body.orderId).toBeDefined();
`

`ts
// Approach 2: Zod validation (runtime check — recommended for contract testing)
import { z } from 'zod';

const OrderSchema = z.object({
orderId: z.string(),
status: z.enum(['pending', 'shipped', 'delivered']),
total: z.number(),
});

const response = await request.post('/api/orders', { data: orderPayload });
const raw: unknown = await response.json();

// parse() throws a ZodError if the shape doesn't match — test fails immediately
const body = OrderSchema.parse(raw);

expect(body.orderId).toBeDefined(); // TypeScript knows the type ✓
expect(body.status).toBe('pending'); // TypeScript knows status is the enum ✓
`

When to use each:
- Type assertion — quick scripting, trusted internal APIs, throwaway tests
- Zod validation — contract testing, external APIs, anywhere catching real regressions matters

Real-world QA use case:
In an API regression suite, run Zod validation on every response. When the backend team renames a field or changes a type, the test fails with a precise ZodError pinpointing the mismatch — not a confusing undefined further down the test.

Rule of thumb: Use as YourType` for speed; use Zod when you want the test to actually catch API contract breaks rather than silently pass with wrong data.

When you assign an object literal directly to a typed variable or parameter, TypeScript runs an extra check called *excess property checking* — it flags any property that doesn't exist in the target type. This is different from TypeScript's normal structural typing, where extra properties are fine. The check only fires on fresh object literals, not on values passed through a variable.

Why it exists:
Extra properties on a fresh object literal are almost always a typo or a misunderstanding. TypeScript catches them at the point of assignment — where the mistake is clearest — rather than letting them silently vanish. The check is intentionally strict at assignment but relaxed for variable assignment, because a variable might legitimately carry extra properties that downstream code needs.

Walked-through example — test data factory:

``ts
interface LoginPayload {
email: string;
password: string;
}

async function login(request: APIRequestContext, payload: LoginPayload) {
return request.post('/api/login', { data: payload });
}

// ❌ Excess property check fires — 'rememberMe' isn't in LoginPayload
await login(request, {
email: 'test@example.com',
password: 'secret',
rememberMe: true, // Error: Object literal may only specify known properties
});

// ✅ Assigning to a variable first bypasses the check
const creds = { email: 'test@example.com', password: 'secret', rememberMe: true };
await login(request, creds); // structurally compatible — no error
``

The practical takeaway for test code:
If you hit this error passing a fixture object to a helper function, it usually means one of two things:
1. You have a typo in a field name — fix it (this is the check doing its job)
2. You genuinely need the extra field elsewhere — assign to a variable first, or widen the type

Real-world QA use case:
Test data factories often build objects with more fields than a specific endpoint needs. Assign the full factory result to a variable, then pass it — the excess property check fires at the assignment, not when passing the variable around, keeping things practical.

Rule of thumb: Excess property checking fires on fresh object literals assigned directly to a typed target. It's TypeScript catching typos early. If it fires and it's not a typo, store in a variable first.

When you write Playwright API tests, every request.get() or request.post() call returns a APIResponse object — and .json() returns any. Without a typed helper, every test has to cast the response manually. A generic helper wraps the fetch-and-parse in one place, and the caller specifies the expected response type.

Why generics here:
Without generics you'd write getUser(), getOrder(), getProduct() — one function per endpoint, all doing the same thing. With <T>, one function works for every endpoint. The return type is determined by what the caller passes as T.

The generic helper:

``ts
import { APIRequestContext } from '@playwright/test';

async function apiGet<T>(request: APIRequestContext, url: string): Promise<T> {
const response = await request.get(url);
expect(response.ok()).toBeTruthy(); // assert 2xx before parsing
return response.json() as T;
}
`

T is the type the caller says the response will be. TypeScript uses it to type the returned value.

Using it in tests:

`ts
interface User { id: number; name: string; email: string; role: string; }
interface Order { id: number; userId: number; status: string; total: number; }

test('GET /users/1 returns a valid user', async ({ request }) => {
const user = await apiGet<User>(request, '/api/users/1');
// user is typed as User — autocomplete and type checking on every field:
expect(user.name).toBeTruthy();
expect(user.role).toBe('admin');
});

test('GET /orders/42 returns a valid order', async ({ request }) => {
const order = await apiGet<Order>(request, '/api/orders/42');
expect(order.status).toBe('shipped');
expect(order.total).toBeGreaterThan(0);
});
`

Adding a typed POST helper:

`ts
async function apiPost<TBody, TResponse>(
request: APIRequestContext,
url: string,
body: TBody
): Promise<TResponse> {
const response = await request.post(url, { data: body });
expect(response.ok()).toBeTruthy();
return response.json() as TResponse;
}

const created = await apiPost<Partial<User>, User>(
request, '/api/users', { name: 'Alice', role: 'regular' }
);
// created is typed as User
`

Rule of thumb:
Write one apiGet<T> and apiPost<TBody, TResponse>` helper per project. All API tests import and use these — they centralise the status assertion and cast, and every caller gets full type safety for free.

These three patterns look similar but mean different things to TypeScript — specifically around whether a field can be omitted entirely versus explicitly set to undefined, and whether a fallback value is guaranteed inside the function.

The three patterns side by side:

``ts
// 1. Optional property (?) — the caller may omit the field entirely
interface Options1 { timeout?: number }
// timeout has type: number | undefined
// Caller can write: {} or { timeout: 30000 } or { timeout: undefined }

// 2. Explicit union with undefined — the field must be present, but undefined is allowed
interface Options2 { timeout: number | undefined }
// Caller must write: { timeout: 30000 } or { timeout: undefined }
// Cannot write: {} — missing the field is an error

// 3. Default parameter value — omitting gives a guaranteed fallback inside the function
function runTest(timeout = 30000) {
// timeout is number here — never undefined, even if caller passed nothing
}
`

Why the difference matters in test helpers:

`ts
// Optional property — useful for override objects in factories
interface UserOverrides {
email?: string;
role?: 'admin' | 'user';
}

function createUser(overrides: UserOverrides = {}): User {
return {
id: Math.random(),
email: overrides.email ?? 'default@example.com', // must handle undefined
role: overrides.role ?? 'user',
};
}

// Default parameter — useful when the value has a sensible fallback
async function waitForElement(
page: Page,
selector: string,
timeout = 5000 // 5s default; caller can override; body always gets a number
): Promise<Locator> {
return page.waitForSelector(selector, { timeout });
}
`

Strict mode note: with exactOptionalPropertyTypes: true in tsconfig, an optional field timeout?: number no longer accepts { timeout: undefined } — it can only be omitted. This tightens the distinction further.

Real-world QA use case:
Test data factory functions use optional properties (Partial<User>) so callers only specify what a test actually needs. Helper functions use default parameters so they always have a usable value inside without forcing callers to pass one.

Rule of thumb: Use ? for factory/override objects where fields are genuinely skippable. Use defaults for function parameters where you want a guaranteed value inside the function. Reserve | undefined` in required fields for when you explicitly want to force callers to acknowledge a field even when they have nothing to put in it.

TypeScript gives a test automation framework four concrete benefits: type-safe Page Object Models, typed test data factories, refactoring safety at scale, and self-documenting code that onboards engineers faster.

Why this matters beyond "type safety":
"Type safety" is the abstract answer. What it means in practice is: fewer 3 AM CI failures caused by a renamed API field, faster test authoring because your editor autocompletes selectors and method signatures, and the ability to rename things confidently without manually searching every test file.

Benefit 1 — Page Object with typed methods:

``ts
interface CreditCard {
number: string;
expiry: string; // MM/YY
cvv: string;
}

interface OrderConfirmation {
orderId: string;
total: number;
}

class CheckoutPage {
constructor(private page: Page) {}

async placeOrder(card: CreditCard): Promise<OrderConfirmation> {
await this.page.fill('[data-testid="card-number"]', card.number);
await this.page.fill('[data-testid="card-expiry"]', card.expiry);
await this.page.fill('[data-testid="card-cvv"]', card.cvv);
await this.page.click('[data-testid="submit-order"]');
return this.parseConfirmation();
}

private async parseConfirmation(): Promise<OrderConfirmation> {
const text = await this.page.locator('[data-testid="order-id"]').textContent() ?? '';
return { orderId: text, total: 0 };
}
}
`

TypeScript ensures placeOrder always receives a valid CreditCard — if a test passes { cardNumber: '...' } (typo'd field), it fails at compile time, not at 2 AM.

Benefit 2 — Typed test data factory:

`ts
function makeUser(overrides: Partial<User> = {}): User {
return { id: 1, name: 'Test User', email: 'test@example.com', role: 'viewer', ...overrides };
}

// Each test only specifies what it cares about
const admin = makeUser({ role: 'admin' });
const guest = makeUser({ email: 'guest@example.com', role: 'guest' });
makeUser({ rol: 'admin' }); // TS error: 'rol' isn't a property of User ✓
`

Benefit 3 — Refactoring safety:
Rename role to userRole in the User interface. TypeScript immediately flags every test, page object, and helper that needs updating — across hundreds of files, before running a single test.

Benefit 4 — Self-documenting code:
New engineers see that placeOrder requires a CreditCard and returns an OrderConfirmation` from the signature alone — no test execution or reading implementation required.

Rule of thumb: The ROI of TypeScript in test frameworks compounds with project size. At 50 tests, it's mildly useful. At 500 tests across a team of 5, the refactoring safety and onboarding speed become irreplaceable.

A type-safe API client uses generics so that each endpoint call returns the correct type automatically — the caller passes a type parameter once, and everything downstream is typed without extra casting. The most powerful pattern is a typed endpoint map where the return type is driven by the endpoint path itself, making wrong combinations a compile error.

Why this matters beyond a simple generic helper:
A basic apiGet<T>(url) still lets you call apiGet<User>('/api/orders') — wrong type, but TypeScript doesn't know. A typed endpoint map closes that gap: the return type is derived from the URL you pass, so mismatches are caught at compile time.

Step 1 — Basic generic helper (simpler, good starting point):

``ts
import { APIRequestContext } from '@playwright/test';

class ApiClient {
constructor(private request: APIRequestContext, private baseUrl: string) {}

async get<T>(path: string): Promise<T> {
const response = await this.request.get(${this.baseUrl}${path});
if (!response.ok()) throw new Error(GET ${path} failed: ${response.status()});
return response.json() as T;
}

async post<TBody, TResponse>(path: string, body: TBody): Promise<TResponse> {
const response = await this.request.post(${this.baseUrl}${path}, { data: body });
if (!response.ok()) throw new Error(POST ${path} failed: ${response.status()});
return response.json() as TResponse;
}
}
`

`ts
// Usage in tests
const client = new ApiClient(request, 'https://staging.example.com');
const user = await client.get<User>('/api/users/1'); // type: User
const order = await client.get<Order>('/api/orders/42'); // type: Order
`

Step 2 — Typed endpoint map (advanced — return type driven by the URL):

`ts
interface EndpointMap {
'/api/users': User[];
'/api/orders': Order[];
'/api/products': Product[];
}

async function typedGet<K extends keyof EndpointMap>(
request: APIRequestContext,
path: K
): Promise<EndpointMap[K]> {
const response = await request.get(path);
return response.json();
}

// Return type is inferred from the path — no type parameter needed
const users = await typedGet(request, '/api/users'); // type: User[]
const orders = await typedGet(request, '/api/orders'); // type: Order[]
await typedGet(request, '/api/invoices'); // TS error: not in EndpointMap ✓
`

The endpoint map makes calling a nonexistent endpoint a compile error, and the return type is always correct without the caller specifying <T>.

Real-world QA use case:
Build the typed endpoint map from your OpenAPI spec (e.g., using openapi-typescript`). Your entire API test suite gets compile-time endpoint validation — if the backend removes or renames an endpoint, every affected test fails to compile before you even run CI.

Rule of thumb: Start with the simple generic class for most projects. Graduate to a typed endpoint map when your API surface is large and you want to catch URL typos and mismatched response types at compile time.

A discriminated union is a TypeScript pattern where each member of the union has a literal "tag" field (like status) that distinguishes it. TypeScript uses the tag to narrow the type inside each branch — so you can only access fields that actually exist for that state.

Why this matters in test automation:
A test result has three very different shapes. A pass needs duration. A failure needs duration, error message, and maybe a screenshot. A skip needs a reason but no duration. If you model this with optional fields on a single interface, nothing stops you creating impossible combinations — like { passed: true, failed: true }. A discriminated union makes illegal states unrepresentable.

The naive approach — allows impossible combinations:

``ts
// ❌ Allows: { passed: true, failed: true, error: "something" }
interface TestResult {
passed?: boolean;
failed?: boolean;
skipped?: boolean;
error?: string;
durationMs?: number;
reason?: string;
}
`

The discriminated union — each state is precise:

`ts
type TestResult =
| { status: 'pass'; durationMs: number }
| { status: 'fail'; durationMs: number; error: string; screenshot?: string }
| { status: 'skip'; reason: string };
`

Now each member only has the fields that make sense for that state. screenshot only exists on fail — you can't accidentally access it on a pass result.

Using it in a reporter:

`ts
function formatResult(result: TestResult): string {
switch (result.status) {
case 'pass':
return ✅ Passed in ${result.durationMs}ms;
case 'fail':
// TypeScript knows result.error exists here — it's only on 'fail'
return ❌ Failed after ${result.durationMs}ms: ${result.error};
case 'skip':
// TypeScript knows result.reason exists here — it's only on 'skip'
return ⏭️ Skipped: ${result.reason};
}
}
`

Exhaustiveness check — protect against future states:

`ts
default:
const _exhaustive: never = result;
throw new Error(Unhandled result status: ${JSON.stringify(result)});
`

Add a new status (e.g. 'timeout') to the union and the compile error forces you to handle it in every switch before the code will build.

Rule of thumb:
Any time you have an object that can be in multiple distinct states — each with different fields — model it as a discriminated union, not a flat interface with optional fields. The status (or type, or kind`) literal tag is what TypeScript uses to narrow.

ReturnType<T> is a built-in TypeScript utility that extracts whatever type a function returns. You pass the function type in (usually via typeof myFunction), and you get the return type back — so you never have to write the same type twice.

Why it exists:
Complex return types, especially from factory functions or setup helpers, are tedious to maintain in two places. If you define the type separately as an interface AND in the function, they can drift. ReturnType makes the function the single source of truth — the type derives from the implementation automatically.

Walked-through example — test data factory:

``ts
// The factory function — return type is inferred, not written explicitly
function createTestUser(overrides: Partial<{ name: string; role: string; email: string }> = {}) {
return {
id: Math.floor(Math.random() * 10000),
name: overrides.name ?? 'Test User',
role: overrides.role ?? 'viewer',
email: overrides.email ?? 'test@example.com',
createdAt: new Date().toISOString(),
};
}

// Derive the type from the function — stays in sync automatically
type TestUser = ReturnType<typeof createTestUser>;
// { id: number; name: string; role: string; email: string; createdAt: string }

// Now type other helpers against it — no separate interface needed
function assertUserDisplayed(page: Page, user: TestUser): Promise<void> {
return expect(page.locator('[data-testid="user-name"]')).toHaveText(user.name);
}
`

Practical use with Playwright fixture setup:

`ts
// Playwright fixtures often return complex objects
async function setupAuthenticatedContext(browser: Browser) {
const context = await browser.newContext();
const page = await context.newPage();
const token = await getAuthToken(page);
return { context, page, token };
}

// Derive the type from the setup function — no need to maintain a separate interface
type AuthFixture = ReturnType<typeof setupAuthenticatedContext>;
// Actually: Awaited<ReturnType<typeof setupAuthenticatedContext>> for async functions
type AuthFixtureResolved = Awaited<ReturnType<typeof setupAuthenticatedContext>>;
// { context: BrowserContext; page: Page; token: string }
`

For async functions, pair ReturnType with Awaited to unwrap the Promise.

Real-world QA use case:
Use ReturnType for test data factories, custom fixture setup functions, and builder patterns — anywhere you want other helpers typed against the output of a function without duplicating the shape.

Rule of thumb: Use ReturnType<typeof fn> (and Awaited<ReturnType<typeof fn>>` for async) when the function's output is the source of truth — let the type follow the implementation, not the other way around.

TypeScript types exist only at compile time — they disappear completely in the compiled JavaScript. So a response body typed as User might actually be { user_id: ... } at runtime and TypeScript will never know. Zod solves this by validating the shape at runtime AND automatically inferring the TypeScript type from the same schema — one definition, two guarantees.

Why this matters in API testing:
Without runtime validation, your tests can silently pass with wrong data — the API returns a renamed field, you cast it as the old type, TypeScript is happy, but your expect(user.email) is checking undefined all along. Zod makes that failure loud and immediate.

Walked-through example — API response validation in a Playwright test:

``ts
import { z } from 'zod';
import { APIRequestContext } from '@playwright/test';

// Step 1 — define the schema (the single source of truth)
const UserSchema = z.object({
id: z.number(),
name: z.string().min(1),
email: z.string().email(),
role: z.enum(['admin', 'user', 'viewer']),
});

// Step 2 — derive the TypeScript type from the schema — no separate interface needed
type User = z.infer<typeof UserSchema>;
// { id: number; name: string; email: string; role: 'admin' | 'user' | 'viewer' }

// Step 3 — use it in a test helper
async function fetchUser(request: APIRequestContext, id: number): Promise<User> {
const response = await request.get(/api/users/${id});
const raw: unknown = await response.json();

// parse() throws ZodError with a precise field-level message if shape is wrong
return UserSchema.parse(raw);
}
`

`ts
// In a test:
const user = await fetchUser(request, 1);
// user is fully typed as User — autocomplete, null safety, everything
expect(user.role).toBe('admin');
`

What a ZodError looks like when the API breaks:
`
ZodError: [
{ "path": ["email"], "message": "Invalid email" },
{ "path": ["role"], "message": "Invalid enum value. Expected 'admin' | 'user' | 'viewer', received 'superadmin'" }
]
`

Precise, actionable, immediately points to the contract break.

parse vs safeParse:
- parse(raw) — throws on failure (good for tests; failure = hard stop)
- safeParse(raw) — returns { success, data, error } (good when you want to handle errors gracefully)

Real-world QA use case:
Put Zod validation at the boundary of every external API call in your test helpers. When a backend deploy breaks the API contract, the first failing test gives you the exact field and the exact mismatch — no debugging required.

Rule of thumb: Define the schema once with Zod, derive the TypeScript type with z.infer, validate with parse()` at the boundary. Zero duplication, runtime and compile-time safety together.

You can't flip "strict": true overnight on a large codebase — it typically produces hundreds or thousands of errors. The safe approach is to enable strict flags one at a time, fix the errors each one surfaces, and ensure new code is always written to the stricter standard.

Why this matters in test frameworks:
A test codebase with strict: false has hidden bugs — implicit any parameters that accept wrong types silently, null-unsafe access that crashes at runtime rather than failing at compile time. Enabling strict mode gradually surfaces these real issues without drowning the team.

Step 1 — Enable flags one at a time (recommended order):

``json
// tsconfig.json — add one flag per sprint, fix errors before adding the next
{
"compilerOptions": {
"noImplicitAny": true, // catches un-typed parameters and variables
"strictNullChecks": true, // catches potential null/undefined access
"strictFunctionTypes": true, // tightens callback parameter variance
"noImplicitReturns": true, // ensures all code paths return a value
"strict": true // eventually: enables all of the above + more
}
}
`

Step 2 — Handle errors you can't fix immediately:

`ts
// Use @ts-expect-error (NOT @ts-ignore) for known, temporary suppressions
// @ts-expect-error — TODO: fix after UserService is refactored (ticket #234)
const user = legacyGetUser(id);

// Why @ts-expect-error over @ts-ignore:
// If the underlying issue is fixed, @ts-expect-error itself becomes an error
// (because there's nothing to suppress) — it self-destructs when no longer needed.
// @ts-ignore silently hides issues forever.
`

Step 3 — Track and enforce progress:

`bash
# Count remaining errors — should only go down, week over week
npx tsc --noEmit 2>&1 | wc -l

# In CI: fail the build if new errors are introduced above a threshold
# (some teams use typescript-strict-plugin to enforce per-file)
`

The one non-negotiable rule:
New code must always be written to the stricter standard from day one — even while legacy code is being fixed. Agree with the team that the error count can only decrease, never increase.

Real-world QA use case:
When migrating a Playwright test suite from JavaScript to TypeScript, start with noImplicitAny. Every un-typed request, page, or response parameter shows up — fix them and the whole suite gets autocomplete and safety for those types. Then enable strictNullChecks and find every place a locator's .textContent() (which returns string | null) is used as if it's always a string.

Rule of thumb: Enable one strict flag per sprint, fix the errors it surfaces, commit. Never skip errors by downgrading flags — use @ts-expect-error` with a ticket number for anything genuinely deferred.

TypeScript supports the four core OOP concepts — encapsulation, inheritance, abstraction, and polymorphism — and all four have direct practical applications in a Playwright Page Object Model framework.

Why OOP in test automation specifically:
Without OOP, page logic leaks into test files, selectors get duplicated, and shared setup gets copy-pasted. OOP gives each page its own encapsulated boundary, lets shared behaviour live in one base class, and lets the test runner treat any page object polymorphically through a shared interface.

All four concepts in a Playwright POM:

``ts
import { Page } from '@playwright/test';

// ABSTRACTION — abstract base defines the contract; subclasses fill in the detail
abstract class BasePage {
constructor(protected page: Page) {}

// Shared behaviour — every page can use this
async waitForLoad(): Promise<void> {
await this.page.waitForLoadState('networkidle');
}

// Contract — every subclass must implement this
abstract getPageTitle(): Promise<string>;
}
`

`ts
// INHERITANCE — LoginPage reuses waitForLoad, implements getPageTitle
class LoginPage extends BasePage {
async getPageTitle(): Promise<string> {
return this.page.title();
}

async login(email: string, password: string): Promise<void> {
await this.page.fill('[data-testid="email"]', email);
await this.page.fill('[data-testid="password"]', password);
await this.page.click('[type="submit"]');
await this.page.waitForURL('/dashboard');
}
}
`

`ts
// ENCAPSULATION — private selector strings; tests can't bypass the page object API
class CartPage extends BasePage {
private readonly addToCartSelector = '[data-testid="add-to-cart"]';
private readonly checkoutSelector = '[data-testid="proceed-checkout"]';

async getPageTitle(): Promise<string> {
return this.page.title();
}

async addItem(): Promise<void> {
await this.page.click(this.addToCartSelector); // selector is an impl detail
}

async proceedToCheckout(): Promise<void> {
await this.page.click(this.checkoutSelector);
}
}
`

`ts
// POLYMORPHISM — a helper that works with any BasePage subclass
async function assertPageLoaded(pageObj: BasePage): Promise<void> {
await pageObj.waitForLoad();
const title = await pageObj.getPageTitle();
if (!title) throw new Error('Page has no title after load');
}

// Works for any BasePage subclass — LoginPage, CartPage, CheckoutPage, etc.
await assertPageLoaded(new LoginPage(page));
await assertPageLoaded(new CartPage(page));
`

The practical payoff:
- Private selectors mean a test can never accidentally reference a raw CSS string that moved
- Abstract getPageTitle means forgetting to implement it is a compile error, not a test failure
- The assertPageLoaded helper works for all current and future page objects — no changes needed

Rule of thumb: Use abstract for the contract every page must fulfil. Use private/protected for selectors and internal helpers. Use extends` for shared navigation and wait helpers. Polymorphism falls out naturally once you do the first three correctly.