Overview

tsc compiles the file to a sibling .js file, which node then runs (Example 2) -- a two-step workflow. tsx transpiles and runs a .ts file directly, in memory, with no emitted file at all (Example 1) -- that's the one with no separate output file.

tsc --noEmit type-checks the project and reports errors without writing any output files at all. A plain tsc run does the same checking but also emits compiled .js. The three always-set options: target: ES2022, module: ESNext, and strict: true.

string, number, boolean, null, and undefined. Under strict, null and undefined are NOT automatically part of every type -- a bare string rejects null outright; only an explicit union like string | null allows it (Example 6).

number, widened from the literal 5 (Example 7). Add an explicit annotation where inference would be too wide or is simply unavailable -- most commonly on function parameters, since TypeScript can't infer a parameter's type backward from how the function body happens to use it (Example 20).

T[] types a homogeneous list of any length; a tuple fixes both the length and each position's own type. readonly T[] makes every mutating method (.push(), .pop(), index assignment) a compile error (Example 10).

prop?: marks the property optional -- callers may omit it entirely (Example 14). Passing an object literal directly with an undeclared extra field triggers the excess-property check, a compile error (Example 50, Kata 1).

interface X extends Y -- declaring an object contract that extends another interface, inheriting and adding fields (Example 17). type describes any type shape (unions, tuples, primitives) but has no dedicated extends keyword form of its own.

Narrowing (co-14) must run first -- a typeof, truthiness, in, or instanceof check that proves which member type the value actually is in that branch. Without it, the compiler only lets you use operations valid on every member of the union at once.

const bindings can never be reassigned, so TypeScript infers the narrowest possible type -- the literal value itself. let allows later reassignment to any other string, so its initializer's type widens to the general string to leave room for that.

A & B requires the value to satisfy every member type at once -- all of A's members and all of B's members together (Example 52). A | B requires only that the value be one specific type from the set, never all of them simultaneously.

void communicates that the function returns no usable value, and callers shouldn't rely on its result. Returning an actual value from a function whose declared return type is void is a compile error (Example 21).

Optional (x?: T, may be omitted entirely, Example 22), default (x: T = value, uses the default when omitted, Example 23), and rest (...xs: T[], collects any number of trailing arguments -- including zero -- into a typed array, Example 24).

A function type expression: any callable taking one number parameter and returning a string. An arrow function, a function expression, or a named function reference can all satisfy it, as long as the parameter and return types line up (Example 26).

typeof x === "..." (Example 29), plain truthiness (if (x), Example 30), the in operator ("role" in obj, Example 31), and instanceof (x instanceof Date, Example 32) -- an equality check against a literal narrows too (Example 33).

x is T as the declared return type (e.g. function isCat(a: Animal): a is Cat), in place of a plain boolean (Example 34). An asserts x is T return type does the same for a function that throws instead of returning false (Example 35).

The tag field (e.g. kind) lets a switch/if narrow the whole union to exactly one variant per branch, purely from the tag's literal value (Example 37). A never-typed default case guarantees, at compile time, that every variant has a matching case -- if a new variant is added without one, assigning the unhandled value to never fails to compile (Example 38, Kata 2).

extends constrains what shapes T may legally be, restricting it to types with certain members (e.g. T extends { length: number }, Example 42, Kata 4). = DefaultType supplies a default type argument used automatically when a caller omits an explicit one (Example 43).

any opts out of checking entirely -- every operation on it compiles, unchecked (Example 47). unknown is the safe top type: every value is assignable to it, but nothing may be done with it until it's narrowed (Example 46). never is the empty bottom type: it represents a value that can never exist, such as unreachable code or a function that always throws (Example 48).

No. Type compatibility is decided purely by shape -- "structural typing." Any object with the required members satisfies a type, with no declared relationship needed at all (Example 51).

Both x! and x as T tell the compiler "trust me, I know more than you do" with zero runtime check backing that claim -- if the author is wrong, the program misbehaves or crashes with no compile-time warning (Example 54, Example 55, Kata 5). as const carries no such risk: it only narrows literal inference and adds readonly, it never overrides what the compiler can already prove.

as const infers every property as its narrowest literal type (instead of the wide primitive) and makes the whole object deeply readonly (Example 56). Combined with keyof typeof, this derives a literal-union type straight from the object's own keys -- an alternative to enum that needs no dedicated keyword (Example 58).

import type is guaranteed to be erased completely at compile time -- it produces zero runtime code and has zero side effects (Example 63). A regular import may execute the imported module and keeps a runtime binding to whatever it imports.

unknown (Example 67) -- the same useUnknownInCatchVariables behavior that applies to every catch under strict. It must be narrowed (most commonly instanceof Error) before any property on it may be accessed.

Partial<T> makes every property optional (Example 70). Required<T> makes every property required, stripping away any ? (Example 73).

keyof Point is exactly "x" | "y" -- the union of the type's own property names (Example 59). An index signature allows an open-ended, arbitrary set of string keys, rather than a fixed, enumerated list, each mapping to the declared value type (Example 60).

eslint flags likely bugs and code smells -- linting. prettier enforces a canonical formatting style -- spacing, quotes, line breaks. eslint <file> reports without fixing (--fix applies fixes); prettier --check <file> reports formatting violations without writing changes (--write applies them, Examples 77-78).

The excess-property check only fires against an object literal written directly at the call site -- there, an extra field can only be a mistake, since the literal exists nowhere else to be intentionally wider. Once the value is stored in a variable first, TypeScript falls back to its general, more permissive structural-typing rule: any object with at least the required members satisfies the type, extra members and all (Kata 1).

Under strict, a caught error's default type is unknown, which requires narrowing (e.g. instanceof Error) before .message compiles (Kata 3). The coworker's version likely narrows err first, or their tsconfig doesn't actually have strict/useUnknownInCatchVariables on, which silently falls back to the old, unsafe any typing for caught errors.

Change the declared return type from boolean to a type predicate: x is Ready (Example 34). Narrowing does not automatically cross a function-call boundary -- a plain boolean return tells the compiler nothing about what became true when it's true. A type predicate is the explicit contract that lets the caller's branch narrow, exactly what a plain boolean can never express on its own.

The switch's default case narrows the unhandled remainder of the union to never and assigns it to a never-typed binding -- that only compiles when every variant is truly handled above it. The new variant isn't handled by any existing case, so inside default the value is still that new variant's type, not never, and the assignment fails (Kata 2). The fix is adding a case for the new variant.

A constraint: <T extends { length: number }> instead of a bare <T> (Kata 4). An unconstrained T could be instantiated with any type at any call site, so the compiler has no grounds to assume it has a .length -- or any property -- unless the signature says so explicitly.

keyof T evaluates to the literal union of T's actual property names (e.g. "id" | "name"), and constraining key's type parameter to that union means only those exact strings are valid arguments -- a misspelled string simply isn't a member of the union, so tsc rejects it before the program ever runs (Kata 6).

Change import type { ApiError } to a regular import { ApiError }. import type is a promise, enforced by the compiler, that the import produces zero runtime code -- so referencing the imported name in a value position (new ApiError(...)) is a hard compile error, not a runtime surprise (Kata 7).

Both n and s become number | string, losing their per-position precision (Example 68). Without the explicit annotation, TypeScript infers each array element as its own distinct promise type and Promise.all preserves that as a tuple, position by position. Force-widening the array to a single homogeneous Promise<number | string>[] type throws that positional information away before Promise.all ever sees it -- the wider annotation is a real loss, not a harmless simplification.

undefined -- there is no enum member whose numeric value is 0, so the reverse-mapping lookup finds nothing (Kata 8). tsc doesn't catch it because a numeric enum's reverse-mapping indexer is typed to accept any number, not just the specific numbers the enum's own members happen to use -- the index expression itself is perfectly well-typed, it's just semantically wrong for this particular enum's numbering.

! made no runtime guarantee at all -- it only silenced the compiler's T | null warning, on the author's unchecked word that the result would never actually be null (Kata 5). It performs zero runtime check, so when findUser genuinely does return null for that one id, nothing catches it: the crash surfaces later, at user.name, not at the assertion itself.

Working as designed. TypeScript's structural typing only requires a value to have at least the declared members -- extra members are always allowed once the value comes from a variable, not a literal written directly at the call site (Example 49). This is the same rule that makes Kata 1's fix legitimate rather than a loophole: only a bare literal gets the stricter excess-property check.

type Point2D = { x: number; y: number };
 
function printPoint(p: Point2D): void {
  console.log(`(${p.x}, ${p.y})`);
}
 
// THE FIX: bind the literal to a variable BEFORE passing it -- point3D's inferred
// type (x, y, z) is checked structurally against Point2D, and structural typing
// only requires x and y to be present -- extra members through a variable are fine.
const point3D = { x: 1, y: 2, z: 3 };
printPoint(point3D); // => Output: (1, 2)

Root cause: the excess-property check is a narrow, deliberate exception to TypeScript's otherwise permissive structural typing -- it exists specifically for object literals written directly at a call site, because there's no legitimate reason such a literal would carry a field the target type doesn't declare, so an extra field there is almost always a typo. Once the same shape is stored in a variable first, the general structural rule applies again: any value with at least the required members satisfies the type.

Run: tsc --noEmit --strict --skipLibCheck kata.ts && tsx kata.ts

Output:

(1, 2)

type Shape =
  | { kind: "circle"; r: number }
  | { kind: "square"; s: number }
  | { kind: "triangle"; base: number; height: number };
 
function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.r ** 2;
    case "square":
      return shape.s * shape.s;
    // THE FIX: a matching case for the new "triangle" variant -- once every
    // variant has a case above it, shape narrows all the way to never below.
    case "triangle":
      return (shape.base * shape.height) / 2; // => 4 * 3 / 2 = 6
    default: {
      const _exhaustive: never = shape; // => now compiles: nothing reaches here unhandled
      return _exhaustive;
    }
  }
}
 
console.log(area({ kind: "triangle", base: 4, height: 3 })); // => Output: 6

Root cause: the never-typed default case is a deliberate compile-time tripwire -- it only type-checks when the switch above it has genuinely eliminated every union member, leaving nothing but never behind. Adding a union variant without a matching case means that variant's own type (not never) reaches default, and assigning it to a never-typed binding fails -- exactly the signal that a real code path was left unhandled.

Run: tsc --noEmit --strict --skipLibCheck kata.ts && tsx kata.ts

Output:

6

function risky(): void {
  throw new Error("network timeout");
}
 
function run(): void {
  try {
    risky();
  } catch (err) {
    // THE FIX: instanceof Error narrows err's type from unknown to Error inside this branch.
    if (err instanceof Error) {
      console.log(err.message); // => .message is safe now -- Output: network timeout
    }
  }
}
 
run();

Root cause: JavaScript's throw can throw any value at all, not just an Error, so strict types a caught error as unknown -- honest about "this could be anything" -- rather than assuming the common case and risking a crash on the uncommon one. unknown compiles nothing until it's narrowed; instanceof Error is the narrowing check that proves, in this branch, err genuinely has a .message.

Run: tsc --noEmit --strict --skipLibCheck kata.ts && tsx kata.ts

Output:

network timeout

// THE FIX: extends { length: number } is the caller-visible contract -- only types
// that genuinely have a .length are legal type arguments for T.
function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length >= b.length ? a : b; // => .length now compiles -- the constraint proves it exists
}
 
console.log(longest("hi", "hello")); // => "hello".length (5) >= "hi".length (2) -- Output: hello

Root cause: an unconstrained T could be instantiated with any type at any call site -- a number, a boolean, anything -- so the compiler has zero grounds to assume it has a .length property unless the signature says so. extends { length: number } narrows the set of legal type arguments to exactly the ones that do, and in exchange, the function body is allowed to rely on that property existing.

Run: tsc --noEmit --strict --skipLibCheck kata.ts && tsx kata.ts

Output:

hello

function findUser(id: number): { name: string } | null {
  return id === 1 ? { name: "Ada" } : null;
}
 
// THE FIX: no `!` -- keep the real `{ name: string } | null` type and narrow it with a check.
const user = findUser(2);
if (user !== null) {
  console.log(user.name);
} else {
  console.log("user not found"); // => id 2 doesn't exist -- this branch runs
}

Root cause: ! performs zero runtime check -- it only silences the compiler's T | null warning, on the author's unchecked word that the value will never actually be null. When findUser genuinely does return null, nothing catches that at the assertion; the crash surfaces later, at user.name, with no compile-time trace connecting it back to the assertion that hid it. A real if (user !== null) check narrows the type AND verifies it at runtime, in one step.

Run: tsc --noEmit --strict --skipLibCheck kata.ts && tsx kata.ts

Output:

user not found

function getValue<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}
 
const user = { id: 1, name: "Ada" };
// THE FIX: "name" (spelled correctly) IS a member of keyof typeof user ("id" | "name").
console.log(getValue(user, "name")); // => Output: Ada

Root cause: keyof T evaluates to the literal union of T's own property names -- "id" | "name" here -- and constraining key's type parameter K to that union means only those exact strings are legal arguments. A misspelled string is simply not a member of the union, so tsc rejects the call before the program ever runs, instead of the typo silently returning undefined the way an untyped (or plain string-keyed) lookup would.

Run: tsc --noEmit --strict --skipLibCheck kata.ts && tsx kata.ts

Output:

Ada

// THE FIX: import { ApiError } (a regular import), not import type { ApiError }.
// ApiError now genuinely exists at runtime, so `new ApiError(...)` compiles.
import { ApiError } from "./types";
 
function fail(): never {
  throw new ApiError(404, "not found");
}
 
try {
  fail();
} catch (err) {
  if (err instanceof ApiError) {
    console.log(`${err.statusCode}: ${err.message}`); // => Output: 404: not found
  }
}

Root cause: import type is a promise, enforced by the compiler, that an import produces zero runtime code -- useful for tooling (Babel, esbuild, swc) that transpiles one file at a time and can't always tell on its own whether an import is type-only. Referencing that same name in a value position (new ApiError(...)) breaks the promise, so tsc rejects it with a specific, named error (TS1361) rather than letting it become a silent undefined is not a constructor at bundle time.

Run: tsc --noEmit && tsx main.ts

Output:

404: not found

enum Priority {
  Low = 1, // => Priority.Low is 1, NOT the default 0 -- deliberately, so 0 can mean "unset" elsewhere
  Medium, // => Priority.Medium is 2
  High, // => Priority.High is 3
}
 
// THE FIX: reverse-map through Priority.Low itself (guaranteed correct) instead of
// hardcoding the numeric literal 0, which has no member at all in this enum.
console.log(Priority[Priority.Low]); // => Output: Low

Root cause: a numeric enum's reverse-mapping indexer (Priority[n]) is typed to accept any number, not just the specific numbers this particular enum's members actually use -- so Priority[0] is perfectly well-typed, it just has no member to find at runtime and silently resolves to undefined. Indexing through the enum member itself (Priority[Priority.Low]) is immune to this: it can never drift out of sync with whatever numbering the enum actually uses.

Run: tsc --noEmit --strict --skipLibCheck kata.ts && tsx kata.ts

Output:

Low

TypeScript's underlying compatibility rule is structural (co-19): a value satisfies a type once it has at least the required members, and extra members are normally harmless -- that flexibility is the entire point of structural typing. But an object literal written directly at a call site is a special case: there's no other legitimate reason it would carry an extra field, since the literal exists nowhere else to be intentionally wider -- the extra field is almost certainly a typo or a copy-paste leftover. The excess-property check is a narrow, deliberate carve-out from otherwise permissive structural typing, aimed specifically at that one situation. Once the value is stored in a variable first (Kata 1's fix), the general rule applies again, because now there IS a legitimate reason the variable's type might be wider than what this one call site needs -- it might be reused elsewhere for its full shape. This is correctness-vs-pragmatism in miniature: TypeScript accepts the false-negative risk (a genuinely wrong extra field, hidden behind a variable) in exchange for not rejecting every legitimately wider object that happens to pass through a variable first.

An unconstrained T can be instantiated with literally any type at every call site -- a number, a boolean, a class instance, anything at all -- so the compiler has zero grounds to assume T has a .length (or any other property) unless the signature explicitly says so. If TypeScript let a generic function body freely access arbitrary properties on an unconstrained T, it would be silently assuming every possible caller's type happens to have that shape, which defeats the entire purpose of generics: expressing "this works for many types, but only the ones that actually satisfy this contract." extends { length: number } (Example 42, Kata 4) is that caller-visible contract, made explicit -- only types that genuinely have a .length are legal type arguments, and in exchange the function body earns the right to rely on that property existing.

JavaScript's throw statement can throw literally any value at all -- a string, a number, undefined, or a genuine Error instance -- so a caught error's actual runtime type is never guaranteed to be Error, and typing it as Error outright would be a claim the compiler can't actually verify. any would compile, but it would also silently permit calling .message (or anything else) on a value that might not have it, defeating the entire point of typing the catch parameter at all. unknown is the deliberately conservative middle ground: honest about "this could genuinely be anything," while still forcing a narrowing check (Kata 3's instanceof Error) before any member access compiles -- correctness-vs-pragmatism resolved firmly on the side of correctness for exactly this one, historically bug-prone spot.

TypeScript's own compiler can often infer whether an import is type-only just from how it's used within a single file, and does erase plain type-only imports automatically in the common case -- but import type exists for the cases where that inference can't be trusted silently, particularly under transpile-per-file tooling (Babel, esbuild, swc) that only ever sees one file at a time and has no way to cross-reference the imported module to check whether a name is a type or a value. Making the erasure syntax-visible also documents intent for a human reader: import type is a promise, checked by the compiler, that this specific import produces zero runtime code -- which is exactly why reusing the same name in a runtime position (new ApiError(...), Kata 7's bug) is a hard, named compile error (TS1361) rather than a silent undefined is not a constructor surprise much later, at bundle time.

! exists because TypeScript's static analysis is sometimes provably less precise than what the author actually knows -- for example, a value narrowed by a check that happened in a different function, or guaranteed non-null by an invariant the type system has no way to express at all (like "this array is never empty because the line right above just pushed to it"). In those genuine cases, ! is a deliberate, visible escape hatch: a single character admitting "the compiler can't prove this here, but I can." The cost, which is Kata 5's entire point, is that ! performs zero runtime check -- if the author's belief turns out to be wrong, ! doesn't fail loudly at the assertion itself; it fails later, less clearly, wherever the now-mistyped value actually gets used. This is correctness-vs-pragmatism at its sharpest: TypeScript trusts the author's stated intent over its own analysis, on the explicit, unenforced condition that the author accepts the entire risk of being wrong.

TypeScript was designed to type an enormous existing body of untyped JavaScript, where objects are built ad hoc -- object literals, factory functions, JSON responses parsed straight off the wire -- code that never declared any formal "this object implements that interface" relationship, because JavaScript itself has no such concept at all. A nominal type system would require retrofitting every one of those objects with an explicit declaration before any of them could be typed, which would make adopting TypeScript for real-world JavaScript nearly impossible in practice. Structural typing sidesteps that entirely: if a value has the required members, it satisfies the type, full stop -- exactly what lets Example 51's object satisfy an interface with no implements clause anywhere, and exactly what makes Kata 1's "store it in a variable first" workaround a legitimate consequence of the design, not a loophole in it.