TypeScript 1 🔷 Introduction to TypeScript
TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Every valid JavaScript program is already a valid TypeScript program — TypeScript just adds a layer of static types on top, checks them at build time, and strips them away before the code ever runs in a browser or Node. It was created by Microsoft in 2012 and has since become the default language for large-scale JavaScript projects. Angular, NestJS, and much of the modern tooling ecosystem are written in it.
Key point: TypeScript doesn’t run in the browser. It’s a compile-time tool. You write .ts files, the TypeScript compiler checks them and emits .js files, and those .js files are what actually execute. The types exist only during development — they leave zero footprint in the final bundle.
What TypeScript is
TypeScript is JavaScript plus a type system. That’s the whole idea.
function greet(name: string): string {
return `Hello, ${name}!`;
}
greet('Alice'); // ✅
greet(42); // ❌ compile errorThat : string annotation is TypeScript. The function body is plain JavaScript. When you compile, the annotation disappears and you’re left with:
function greet(name) {
return `Hello, ${name}!`;
}The type was checked at build time — before the code ever ran. If you’d passed a number, you’d have known immediately, not after a user hit a bug in production.
What TypeScript adds:
- Static types — variables, parameters, and return values can be annotated
- Type inference — you don’t have to annotate everything; TypeScript figures out most types
- Structural typing — types are compared by shape, not by name
- Interfaces and generics — tools for describing complex data and reusable abstractions
- Modern JavaScript features — TypeScript compiles newer syntax down for older runtimes
- Editor support — autocomplete, refactoring, and inline errors via the language server
What TypeScript does not add:
- Runtime type checking — types don’t exist at runtime
- A different runtime — it runs wherever JavaScript runs
- Performance improvements — the emitted JavaScript is essentially what you’d write by hand
Why a superset matters: You can rename a
.jsfile to.tsand it will compile — that’s the promise of “superset.” You don’t rewrite anything. You add types incrementally, file by file, until the whole project is typed. That’s what makes TypeScript adoptable in existing codebases.
Why TypeScript exists
JavaScript was designed in ten days in 1995 for small scripts. It has grown into the language of the web, servers, mobile, and desktop — and its dynamic type system, which is flexible, is also the source of an enormous class of bugs. undefined is not a function, [object Object], silent coercion — these are the daily hazards of untyped JavaScript.
TypeScript’s answer: catch type errors before they run.
// JavaScript
function calculateTotal(items) {
return items.reduce((sum, item) => sum + item.price, 0);
}// TypeScript
interface Item {
name: string;
price: number;
}
function calculateTotal(items: Item[]): number {
return items.reduce((sum, item) => sum + item.price, 0);
}In the TypeScript version, you can’t accidentally pass a string array, call calculateTotal() with no argument, or access a property that doesn’t exist on Item. The compiler rejects the code before it’s ever executed.
Where this pays off:
- Refactoring — rename a field and every use is updated or flagged
- Team code — new developers see the shape of data without reading the whole codebase
- Large projects — the compiler catches bugs that would only surface at runtime in JS
- Tooling — editors offer autocomplete, go-to-definition, and inline errors because they know the types
- Documentation — types are executable documentation; they can’t drift from reality
The cost: an extra build step and a bit more syntax. In exchange, you get a compiler that finds entire categories of bugs for you.
Why “catch errors before they run” is the real pitch: Every benefit of TypeScript — better tooling, safer refactoring, clearer APIs — flows from that one property. If a bug can be caught at compile time, it never reaches the user. That’s the promise of a statically typed language, and it’s what JavaScript has always lacked.
TypeScript is a compile-time tool
The compiler is called tsc. It reads .ts files and produces .js files.
hello.ts ──► tsc ──► hello.jsThe compiler does three things:
- Type-checks — reports errors for type mismatches
- Transforms — rewrites newer syntax for older targets (e.g., optional chaining for ES5)
- Emits — writes
.js(and optionally.d.tsdeclaration files)
The type annotations don’t appear in the output. They’re erased.
Two implications:
Types don’t affect runtime behavior. A string and a number are the same at runtime — the distinction only exists in the type checker. instanceof checks on TypeScript types won’t work because the types don’t exist.
Runtime data is untyped. If you read JSON from an API, TypeScript has no idea what shape it is. JSON.parse() returns any. You either validate the data or trust your type annotation — the compiler can’t verify either way.
interface User {
name: string;
}
const user = JSON.parse('{"name": 42}') as User;
console.log(user.name.toUpperCase()); // ✅ compiles, ❌ crashes at runtimeThe compiler trusts your as User assertion. It can’t verify that the JSON actually matched. Types are contracts you write, not guarantees the runtime enforces.
Why this matters: TypeScript catches type errors in your code, but it can’t validate data from outside your program. That’s why runtime validation libraries — Zod, io-ts, Valibot — exist. They check the shape of incoming data and produce a typed result the compiler can then trust.
Superset, not replacement
TypeScript isn’t a new language. It’s JavaScript with optional type syntax.
const x = 5; // ✅ valid TS and JS
const y: number = 5; // ✅ valid TS, erases to `const y = 5`Every JavaScript feature — classes, promises, closures, generators, modules, destructuring — works in TypeScript exactly as it does in JavaScript. The type system is layered on top; it doesn’t replace anything.
What that means in practice:
- You can start with one
.tsfile in a.jsproject - You can turn off strictness and compile with almost no changes
- You can add types gradually, one file at a time
- You can drop types entirely by not annotating and letting inference do the work
What it doesn’t mean:
- You don’t get runtime type safety for free
- You still have to think about JavaScript’s dynamic behavior
- You can’t “compile away” all bugs — just a specific class of them
Why gradual adoption was a design goal: Microsoft knew developers wouldn’t rewrite their projects. By making TypeScript a superset with optional types and a compile-to-JS model, they made adoption incremental. That’s the main reason the language spread so fast.
The type system in one example
TypeScript’s type system is structural — types are compared by shape, not by name.
interface Point {
x: number;
y: number;
}
function distanceFromOrigin(p: Point): number {
return Math.sqrt(p.x ** 2 + p.y ** 2);
}
// This object isn't "declared as" a Point — it just has the same shape
const p = { x: 3, y: 4 };
distanceFromOrigin(p); // ✅p was never declared as a Point. It just has the properties Point requires, so it satisfies the type. That’s structural typing — also called “duck typing” at the type level.
Two directions this goes:
Compatible shapes pass. Any object with x: number and y: number works, regardless of what else it contains.
Missing or wrong-shaped members fail. An object with x: string or without y won’t compile.
distanceFromOrigin({ x: '3', y: 4 }); // ❌ x is string, not number
distanceFromOrigin({ x: 3 }); // ❌ missing yWhy structural: It matches JavaScript’s object model. JS doesn’t have nominal types — it has shapes. TypeScript follows the language it’s modeling. That means you can pass a { x, y, color } object where { x, y } is expected — extra properties are fine, as long as the required ones are present.
Why this is powerful: Structural typing makes interoperability easy. Two libraries that both define a
Pointinterface don’t need to share the type — as long as their shapes match, the values are interchangeable. That’s how TypeScript works with dozens of competing libraries without central type definitions for everything.
A first TypeScript program
Write a file called hello.ts:
interface User {
id: number;
name: string;
}
function greet(user: User): string {
return `Hello, ${user.name} (id ${user.id})!`;
}
const alice: User = { id: 1, name: 'Alice' };
console.log(greet(alice));
console.log(greet({ id: 2, name: 'Bob' }));Compile:
npx tsc hello.tsProduces hello.js:
"use strict";
function greet(user) {
return `Hello, ${user.name} (id ${user.id})!`;
}
const alice = { id: 1, name: 'Alice' };
console.log(greet(alice));
console.log(greet({ id: 2, name: 'Bob' }));The interface and the type annotations are gone. The logic is preserved. Run it with Node:
node hello.jsTry introducing an error:
console.log(greet({ id: 'one', name: 'Carol' })); // ❌ id is stringThe compiler rejects it before any file is emitted.
Why this example: It’s the smallest program that shows the full loop — write typed code, compile, run. Everything else in the language extends this pattern: annotate, compile, execute the emitted JavaScript.
When to use TypeScript
Good fit:
- Large codebases — more code means more places a type error can hide
- Team projects — shared types reduce miscommunication
- Long-lived applications — refactoring is far safer with the compiler on your side
- Public libraries — typed APIs are documentation that can’t lie
- Apps with complex data — modeling domain rules in types catches real bugs
- Angular, NestJS, and modern React/Vue projects — the ecosystems are built around TypeScript
Less obvious fit:
- Tiny scripts — a 20-line file may not benefit enough to justify setup
- Rapid prototypes — types can slow exploration; add them after the shape stabilizes
- One-off CLI tools — often not worth the extra build step
- Learning JavaScript — you should understand JS first; TypeScript’s types make more sense once the underlying language does
The honest answer: TypeScript is worth it for most non-trivial projects. The cost is small; the payoff compounds as the project grows.
TypeScript vs JavaScript — a quick comparison
| Aspect | JavaScript | TypeScript |
|---|---|---|
| Types | Dynamic, runtime | Static, compile-time |
| Runs directly | ✅ | ❌ (must compile) |
| Type errors caught | At runtime | At build time |
| Tooling | Basic | Rich (autocomplete, refactor) |
| Learning curve | Lower | Higher |
| Best for | Small scripts, prototypes | Large apps, teams, libraries |
| Ecosystem | Everything | Everything + typed libraries |
JavaScript is not “worse.” It’s a different trade-off. TypeScript adds a compiler and a type system in exchange for catching bugs earlier.
Why both exist and matter: JavaScript is the runtime. TypeScript is a tool for writing it more safely. The relationship isn’t competition — TypeScript emits JavaScript. Every TS project is also a JS project in the end.
A full example
A small program that models a shopping cart.
interface Product {
id: number;
name: string;
price: number;
}
interface CartItem {
product: Product;
quantity: number;
}
function cartTotal(items: CartItem[]): number {
return items.reduce((sum, item) => sum + item.product.price * item.quantity, 0);
}
function formatCurrency(amount: number): string {
return `$${amount.toFixed(2)}`;
}
const cart: CartItem[] = [
{ product: { id: 1, name: 'Book', price: 12.5 }, quantity: 2 },
{ product: { id: 2, name: 'Pen', price: 1.75 }, quantity: 3 }
];
console.log(`Total: ${formatCurrency(cartTotal(cart))}`);
// → Total: $30.25Every piece of data is described. Product, CartItem, the array type, the return types. The compiler verifies that item.product.price is a number, that cart matches CartItem[], and that formatCurrency receives a number.
If someone renames price to cost, every use fails to compile — a rename you’d otherwise chase across the codebase by hand.
Why this shape: TypeScript’s value shows up the moment data gets non-trivial. Two interfaces and three functions, and you already have type-safe arithmetic on a collection of structured objects. That’s the everyday case — not fancy generics, just structured data with a compiler watching.
Complete Example Session
# ============================================
# PART 1: CHECK NODE IS INSTALLED
# ============================================
node --version
# [ v20.11.0 ]
# ============================================
# PART 2: INSTALL TYPESCRIPT LOCALLY
# ============================================
npm install --save-dev typescript
# [ added 1 package ]
# ============================================
# PART 3: VERIFY THE COMPILER
# ============================================
npx tsc --version
# [ Version 5.4.0 ]
# ============================================
# PART 4: WRITE A FIRST PROGRAM
# ============================================
cat > hello.ts << 'EOF'
interface User {
id: number;
name: string;
}
function greet(user: User): string {
return `Hello, ${user.name} (id ${user.id})!`;
}
const alice: User = { id: 1, name: 'Alice' };
console.log(greet(alice));
EOF
# ============================================
# PART 5: COMPILE
# ============================================
npx tsc hello.ts
# (no output — success)
ls
# [ hello.js hello.ts ]
# ============================================
# PART 6: INSPECT THE EMITTED JAVASCRIPT
# ============================================
cat hello.js
# [ "use strict"; ]
# [ function greet(user) { ]
# [ return `Hello, ${user.name} (id ${user.id})!`; ]
# [ } ]
# [ const alice = { id: 1, name: 'Alice' }; ]
# [ console.log(greet(alice)); ]
# (types are gone)
# ============================================
# PART 7: RUN IT
# ============================================
node hello.js
# [ Hello, Alice (id 1)! ]
# ============================================
# PART 8: TRIGGER A TYPE ERROR
# ============================================
cat > broken.ts << 'EOF'
function greet(name: string): string {
return `Hello, ${name}!`;
}
greet(42);
EOF
npx tsc broken.ts
# [ broken.ts:5:7 - error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'. ]
# [ ]
# [ 5 greet(42); ]
# [ ~~ ]
# (no JS was emitted for this file)
# ============================================
# PART 9: CREATE A TSCONFIG
# ============================================
npx tsc --init
# [ Created a new tsconfig.json with: ]
# [ target: es2016 ]
# [ module: commonjs ]
# [ strict: true ]
# [ ... ]
# ============================================
# PART 10: COMPILE EVERYTHING IN THE PROJECT
# ============================================
npx tsc
# (compiles every .ts in the project per tsconfig.json)Quick Reference
What TypeScript Is
| Aspect | Value |
|---|---|
| Full name | TypeScript |
| Type | Superset of JavaScript |
| Adds | Static types, tooling |
| Compiles to | Plain JavaScript |
| Created by | Microsoft |
| First release | 2012 |
| Runtime | None — it’s a compile-time tool |
Key Concepts
| Concept | Meaning |
|---|---|
| Static typing | Types checked at build time |
| Inference | TypeScript figures out types automatically |
| Structural typing | Types compared by shape |
| Type erasure | Types removed during compilation |
| Superset | Every JS file is valid TS |
| Gradual adoption | Add types file by file |
Common Commands
| Command | Purpose |
|---|---|
npm install --save-dev typescript | Install locally |
npm install -g typescript | Install globally |
npx tsc file.ts | Compile a single file |
npx tsc | Compile per tsconfig.json |
npx tsc --init | Create tsconfig.json |
npx tsc --version | Show compiler version |
npx tsc --watch | Watch and rebuild |
npx tsc --noEmit | Type-check only, don’t emit |
What Compiles and What Doesn’t
| Code | Compiles? |
|---|---|
const x = 5; | ✅ |
const x: number = 5; | ✅ |
const x: number = 'a'; | ❌ |
function f(n: number) {} | ✅ |
f('a'); | ❌ |
JSON.parse('{}') as User | ✅ (trusts you) |
window as string | ❌ |
TypeScript vs JavaScript
| Aspect | JavaScript | TypeScript |
|---|---|---|
| Types | Runtime, dynamic | Compile-time, static |
| Build step | None | Required |
| Tooling | Basic | Rich |
| Catches type errors | At runtime | At build time |
| Learning curve | Lower | Higher |
| Best for | Small scripts | Large apps, teams |
Compiler Output
| Input | Output |
|---|---|
.ts | .js |
.ts + --declaration | .js + .d.ts |
.tsx | .js |
| Type annotations | Erased |
| Interfaces | Erased |
| Enums | Emitted as JS objects |
Adoption Checklist
| Step | Purpose |
|---|---|
| Install TypeScript | Get the compiler |
Create tsconfig.json | Configure the project |
Rename one .js to .ts | Start small |
Set strict: false initially | Avoid overwhelming errors |
| Add types incrementally | File by file |
| Turn on strict checks | Once codebase is typed |
Best Practices
✅ Do This:
// Let inference do its job
const name = 'Alice'; // ✅ inferred as string
// Annotate function parameters and returns
function greet(name: string): string { ... } // ✅
// Use interfaces for object shapes
interface User { id: number; name: string; } // ✅
// Validate runtime data
const user = UserSchema.parse(json); // ✅
// Enable strict mode
// In tsconfig.json: "strict": true // ✅
// Use the compiler in CI
npx tsc --noEmit // ✅❌ Don’t Do This:
// Don't over-annotate obvious types
const n: number = 5; // ⚠️ inference is enough
// Don't use `any` to silence errors
function f(x: any) { ... } // ❌ defeats the purpose
// Don't trust `as` on external data
const u = JSON.parse(str) as User; // ⚠️ runtime unchecked
// Don't skip the build step in production
node app.ts // ❌ Node runs JS, not TS
// Don't turn off strict mode forever
// "strict": false // ⚠️ temporary at best
// Don't expect runtime type checks
if (typeof x === 'User') { } // ❌ User doesn't exist at runtimeCommon Pitfalls
| Pitfall | Problem | Solution |
|---|---|---|
| Expecting runtime types | Types are erased | Validate external data |
Using any everywhere | No type safety | Use unknown then narrow |
| Over-annotating | Noise | Let inference work |
| Forgetting to compile | Node won’t run .ts | Run tsc or use a runner |
Mixing up as and runtime checks | as is a claim, not a check | Validate with Zod or manual |
| Skipping strict mode | Weak checking | Enable strict: true |
Not committing tsconfig.json | Inconsistent builds | Commit it |
| Confusing interfaces and values | They exist in different worlds | Interfaces for types, objects for values |
Real-World Examples
1. A typed function
function add(a: number, b: number): number {
return a + b;
}2. A typed object
interface Point { x: number; y: number; }
const p: Point = { x: 1, y: 2 };3. Inferred types
const name = 'Alice'; // TypeScript knows this is string4. Union type
let id: string | number;
id = 'abc';
id = 42;5. Type error caught early
add('a', 'b'); // ❌ compile error6. Array of typed objects
interface Item { name: string; price: number; }
const items: Item[] = [{ name: 'Book', price: 12.5 }];7. Optional property
interface User { id: number; nickname?: string; }8. Type alias
type ID = string | number;9. Readonly
interface Config { readonly apiUrl: string; }10. Enum
enum Status { Loading, Ready, Error }
const s: Status = Status.Loading;11. Generic function
function identity<T>(x: T): T { return x; }12. Narrowing
function f(x: string | number) {
if (typeof x === 'string') return x.toUpperCase();
return x.toFixed(2);
}13. Compile and run
npx tsc hello.ts && node hello.js14. Watch mode
npx tsc --watch15. Type-check only
npx tsc --noEmitVisual: Compile Pipeline
┌──────────────────────────────────────────────┐
│ hello.ts │
│ │
│ interface User { ... } │
│ function greet(u: User): string { ... } │
│ const a: User = { ... }; │
│ │
└──────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ tsc │
│ │
│ • Type-check │
│ • Transform syntax │
│ • Erase types │
│ │
└──────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ hello.js │
│ │
│ function greet(u) { ... } │
│ const a = { ... }; │
│ │
│ (no types — plain JavaScript) │
│ │
└──────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ node hello.js │
│ │
│ → Runs in the JS runtime │
│ │
└──────────────────────────────────────────────┘Visual: Where Errors Are Caught
┌──────────────────────────────────────────────┐
│ JavaScript │
│ │
│ Write code ──► run ──► crash (maybe) │
│ │
│ Errors caught at runtime — in production │
│ │
└──────────────────────────────────────────────┘
┌──────────────────────────────────────────────┐
│ TypeScript │
│ │
│ Write code ──► COMPILE ──► run │
│ │ │
│ ▼ │
│ Type errors here │
│ (before shipping) │
│ │
└──────────────────────────────────────────────┘Visual: Superset Relationship
┌──────────────────────────────────────────────┐
│ TypeScript │
│ │
│ ┌────────────────────────────────────────┐ │
│ │ JavaScript │ │
│ │ │ │
│ │ • variables, functions, classes │ │
│ │ • promises, closures, modules │ │
│ │ │ │
│ │ ┌──────────────────────────────────┐ │ │
│ │ │ + Type annotations │ │ │
│ │ │ + Interfaces, generics │ │ │
│ │ │ + Type-level tooling │ │ │
│ │ └──────────────────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────┘ │
│ │
│ Every JS program is also a TS program │
│ │
└──────────────────────────────────────────────┘Visual: What’s Erased
┌──────────────────────────────────────────────┐
│ In TypeScript source │
│ │
│ interface User { id: number; name: string; }│
│ function greet(u: User): string { ... } │
│ const x: number = 5; │
│ │
└──────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ After compilation │
│ │
│ function greet(u) { ... } │
│ const x = 5; │
│ │
│ (interface, types — all gone) │
│ │
└──────────────────────────────────────────────┘Visual: The Type System’s Reach
┌──────────────────────────────────────────────┐
│ Your code │
│ │
│ ✅ TypeScript checks here │
│ │
└──────────────────────────────────────────────┘
┌──────────────────────────────────────────────┐
│ External data (API, JSON, user input) │
│ │
│ ❌ TypeScript CANNOT check here │
│ │
│ Use runtime validation (Zod, io-ts, etc.) │
│ │
└──────────────────────────────────────────────┘
┌──────────────────────────────────────────────┐
│ Runtime │
│ │
│ ❌ No types exist here │
│ │
│ Errors are plain JavaScript errors │
│ │
└──────────────────────────────────────────────┘Summary
| Concept | Meaning |
|---|---|
| TypeScript | Typed superset of JavaScript |
| Superset | Every JS program is valid TS |
| Compile-time | Types checked at build, erased at runtime |
| Static typing | Types known before execution |
| Structural typing | Types compared by shape |
| Inference | Compiler figures out types |
| Type erasure | Types vanish in emitted JS |
tsc | The TypeScript compiler |
tsconfig.json | Project configuration |
| Strict mode | Stricter type checks — recommended |
Key takeaways:
- TypeScript is a typed superset of JavaScript — every JS file is already valid TS
- It’s a compile-time tool —
.tsfiles compile to.js, and types are erased in the process - Types are checked before runtime, catching entire categories of bugs early
- The type system is structural — types match by shape, not by name
- Inference means you don’t annotate everything — TypeScript figures out most types
- Type erasure means types don’t exist at runtime — they can’t be checked against live data
- External data (APIs, JSON, user input) must be validated at runtime — TypeScript can’t help there
- Adoption is gradual — rename one file, add types incrementally, turn on strictness over time
tsconfig.jsonconfigures the compiler;strict: trueis the recommended baselinetsc --noEmittype-checks without emitting — useful in CI
Remember: TypeScript is JavaScript with a type layer on top. The types exist at compile time, catch bugs before they run, and disappear before the code executes. It doesn’t replace JavaScript — it makes it safer to write at scale. The runtime is still JavaScript, the semantics are still JavaScript, and the bugs TypeScript doesn’t catch — external data, runtime behavior — are still your responsibility. That’s the trade: a small build step in exchange for a compiler that finds your mistakes before your users do.
Stop using slow, ad-bloated tool sites! 🤮
🔎 Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)
⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free
🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!