Add TypeScript advanced track

Author: lucasbellesi

LANGUAGE_PARITY_MATRIX.md

@@ -4,7 +4,7 @@ This matrix tracks module and checkpoint parity across C++, C#, Go, Python, and
 
 - Canonical order is defined by the C++ track.
 - C++, C#, Go, and Python now reach module and checkpoint parity through `04-expert`.
-- TypeScript is the newest incremental track with `01-foundations` and `02-core` implemented first.
+- TypeScript is the newest incremental track with `01-foundations`, `02-core`, and `03-advanced` implemented first.
 - Status labels:
   - `Done`: module implemented with example, exercises, and README.
   - `Planned`: module not implemented yet, already queued in order.
@@ -47,17 +47,17 @@ Current parity progress in non-C++ tracks:
 - C#: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
 - Go: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
 - Python: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
-- TypeScript: `03-advanced` and `04-expert` planned after foundations and core
+- TypeScript: `5/5` modules complete in `03-advanced`; `04-expert` planned next
 
 ### Advanced (`03-advanced`) - Current Expansion Queue
 
 | Order | Module | C++ | C# | Go | Python | TypeScript |
 | --- | --- | --- | --- | --- | --- | --- |
-| 1 | structs-and-classes | Done | Done | Done | Done | Planned |
-| 2 | constructors-and-invariants | Done | Done | Done | Done | Planned |
-| 3 | copy-and-move-semantics | Done | Done | Done | Done | Planned |
-| 4 | inheritance-and-polymorphism | Done | Done | Done | Done | Planned |
-| 5 | templates-basics | Done | Done | Done | Done | Planned |
+| 1 | structs-and-classes | Done | Done | Done | Done | Done |
+| 2 | constructors-and-invariants | Done | Done | Done | Done | Done |
+| 3 | copy-and-move-semantics | Done | Done | Done | Done | Done |
+| 4 | inheritance-and-polymorphism | Done | Done | Done | Done | Done |
+| 5 | templates-basics | Done | Done | Done | Done | Done |
 
 `04-expert` projects and assessments are now implemented across C#, Go, and Python.
 
@@ -84,7 +84,7 @@ Status labels:
 | --- | --- | --- | --- | --- | --- |
 | 01-foundations | Done | Done | Done | Done | Done |
 | 02-core | Done | Done | Done | Done | Done |
-| 03-advanced | Done | Done | Done | Done | Planned |
+| 03-advanced | Done | Done | Done | Done | Done |
 | 04-expert | Done | Done | Done | Done | Planned |
 
 ### Assessments
@@ -93,5 +93,5 @@ Status labels:
 | --- | --- | --- | --- | --- | --- |
 | 01-foundations | Done | Done | Done | Done | Done |
 | 02-core | Done | Done | Done | Done | Done |
-| 03-advanced | Done | Done | Done | Done | Planned |
+| 03-advanced | Done | Done | Done | Done | Done |
 | 04-expert | Done | Done | Done | Done | Planned |

README.md

@@ -54,7 +54,7 @@ If you only want to learn one track, follow that track README first because lang
 | C# | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
 | Go | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
 | Python | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
-| TypeScript | 01-foundations, 02-core | 8/8 foundations modules, 6/6 core modules, 2/4 projects, 2/4 assessments | Foundations and core complete; advanced and above planned |
+| TypeScript | 01-foundations, 02-core, 03-advanced | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 3/4 projects, 3/4 assessments | Foundations, core, and advanced complete; expert planned |
 
 Parity planning reference: [LANGUAGE_PARITY_MATRIX.md](LANGUAGE_PARITY_MATRIX.md)
 

languages/typescript/03-advanced/README.md

@@ -0,0 +1,24 @@
+# TypeScript 03 Advanced
+
+This level moves the TypeScript track into object modeling, invariants, reusable abstractions, and generics.
+
+## Learning Metadata
+
+- Difficulty: Advanced.
+- Estimated Time: 4-6 hours across modules, project, and assessment.
+- Prerequisites: Completion of `01-foundations` and `02-core`, including at least one checkpoint per level.
+- Study Strategy: Trace object state carefully, compare reference behavior with earlier array examples, and leave generics for last so they generalize concepts you already trust.
+
+## Module Order
+
+1. [structs-and-classes](./structs-and-classes/README.md)
+2. [constructors-and-invariants](./constructors-and-invariants/README.md)
+3. [copy-and-move-semantics](./copy-and-move-semantics/README.md)
+4. [inheritance-and-polymorphism](./inheritance-and-polymorphism/README.md)
+5. [templates-basics](./templates-basics/README.md)
+
+Track progress in [../CHECKLIST.md](../CHECKLIST.md).
+
+## Study Tip
+
+Use `templates-basics` last so the generic helpers feel like a cleanup of earlier advanced modules instead of a brand-new topic.

languages/typescript/03-advanced/constructors-and-invariants/README.md

@@ -0,0 +1,55 @@
+# Constructors and Invariants
+
+This module focuses on constructors that reject invalid state and keep objects trustworthy.
+
+## Learning Metadata
+
+- Difficulty: Advanced.
+- Estimated Time: 30-45 minutes.
+- Prerequisites: `03-advanced/structs-and-classes` and `02-core/input-validation`.
+- Cross-Language Lens: Compare constructor validation across C++, C#, Go factory patterns, Python initializers, and TypeScript classes.
+
+## Quick Run
+
+~~~bash
+npm run build:typescript
+node build/typescript/03-advanced/constructors-and-invariants/example/main.js
+~~~
+
+## Topics Covered
+
+- Constructor guards.
+- Private mutable state with public methods.
+- Preventing impossible states.
+- Keeping mutation rules near the data they protect.
+
+## Common Pitfalls
+
+- Allowing invalid values into the constructor and hoping later methods fix them.
+- Exposing fields that bypass invariant checks.
+- Returning partially initialized objects.
+
+## Exercise Focus
+
+- exercises/01.ts: build a validated bank account.
+- exercises/02.ts: build a temperature range that preserves `minimum <= maximum`.
+
+### Exercise Specs
+
+1. exercises/01.ts
+- Input: owner and opening balance.
+- Output: account summary or an error.
+- Edge cases: empty owner; negative opening balance.
+
+2. exercises/02.ts
+- Input: minimum and maximum temperatures.
+- Output: validated range or an error.
+- Edge cases: minimum above maximum; invalid numbers.
+
+## Checkpoint
+
+- [ ] I can encode business rules directly in the constructor.
+- [ ] I can keep object state valid after later method calls.
+- [ ] I can explain why rejecting invalid construction simplifies later code.
+- [ ] I completed exercises/01.ts.
+- [ ] I completed exercises/02.ts.

languages/typescript/03-advanced/constructors-and-invariants/example/main.ts

@@ -0,0 +1,42 @@
+class BankAccount {
+    #balance: number;
+
+    constructor(
+        readonly owner: string,
+        openingBalance: number,
+    ) {
+        if (!owner.trim()) {
+            throw new Error("Owner name is required.");
+        }
+        if (openingBalance < 0) {
+            throw new Error("Opening balance must be non-negative.");
+        }
+        this.#balance = openingBalance;
+    }
+
+    deposit(amount: number): void {
+        if (amount <= 0) {
+            throw new Error("Deposit amount must be positive.");
+        }
+        this.#balance += amount;
+    }
+
+    withdraw(amount: number): boolean {
+        if (amount <= 0 || amount > this.#balance) {
+            return false;
+        }
+        this.#balance -= amount;
+        return true;
+    }
+
+    printStatus(): void {
+        console.log(`${this.owner}: ${this.#balance.toFixed(2)}`);
+    }
+}
+
+const account = new BankAccount("Ana", 120);
+account.deposit(30);
+account.withdraw(50);
+account.printStatus();
+
+export {};

languages/typescript/03-advanced/constructors-and-invariants/exercises/01.ts

@@ -0,0 +1,35 @@
+import * as fs from "node:fs";
+
+class BankAccount {
+    constructor(
+        readonly owner: string,
+        readonly balance: number,
+    ) {
+        if (!owner.trim()) {
+            throw new Error("Owner name is required.");
+        }
+        if (balance < 0) {
+            throw new Error("Balance must be non-negative.");
+        }
+    }
+}
+
+function main(): void {
+    const tokens = fs
+        .readFileSync(0, "utf8")
+        .trim()
+        .split(/\s+/)
+        .filter((token) => token.length > 0);
+
+    const owner = tokens[0] ?? "";
+    const openingBalance = Number.parseFloat(tokens[1] ?? "");
+
+    try {
+        const account = new BankAccount(owner, openingBalance);
+        console.log(`${account.owner}: ${account.balance.toFixed(2)}`);
+    } catch (error) {
+        console.log((error as Error).message);
+    }
+}
+
+main();

languages/typescript/03-advanced/constructors-and-invariants/exercises/02.ts

@@ -0,0 +1,35 @@
+import * as fs from "node:fs";
+
+class TemperatureRange {
+    constructor(
+        readonly minimum: number,
+        readonly maximum: number,
+    ) {
+        if (Number.isNaN(minimum) || Number.isNaN(maximum)) {
+            throw new Error("Expected numeric temperatures.");
+        }
+        if (minimum > maximum) {
+            throw new Error("Minimum cannot exceed maximum.");
+        }
+    }
+}
+
+function main(): void {
+    const tokens = fs
+        .readFileSync(0, "utf8")
+        .trim()
+        .split(/\s+/)
+        .filter((token) => token.length > 0);
+
+    const minimum = Number.parseFloat(tokens[0] ?? "");
+    const maximum = Number.parseFloat(tokens[1] ?? "");
+
+    try {
+        const range = new TemperatureRange(minimum, maximum);
+        console.log(`Range: ${range.minimum}..${range.maximum}`);
+    } catch (error) {
+        console.log((error as Error).message);
+    }
+}
+
+main();

languages/typescript/03-advanced/copy-and-move-semantics/README.md

@@ -0,0 +1,55 @@
+# Copy and Move Semantics
+
+This module adapts the C++ ownership topic to TypeScript by focusing on reference behavior, shallow copies, and explicit cloning.
+
+## Learning Metadata
+
+- Difficulty: Advanced.
+- Estimated Time: 30-45 minutes.
+- Prerequisites: `03-advanced/structs-and-classes` and `02-core/algorithms-basics`.
+- Cross-Language Lens: Compare C++ copy and move rules with TypeScript reference sharing, spread copies, and deep-clone helpers.
+
+## Quick Run
+
+~~~bash
+npm run build:typescript
+node build/typescript/03-advanced/copy-and-move-semantics/example/main.js
+~~~
+
+## Topics Covered
+
+- Reference aliasing.
+- Shallow copy with spread syntax.
+- Deep copy with explicit helper functions.
+- Deciding when shared state is safe.
+
+## Common Pitfalls
+
+- Assuming spread syntax deep-copies nested objects.
+- Mutating an alias and expecting the original to stay unchanged.
+- Cloning blindly without understanding the data shape.
+
+## Exercise Focus
+
+- exercises/01.ts: show shallow copy behavior on a nested object.
+- exercises/02.ts: write a deep-clone helper for a small inventory model.
+
+### Exercise Specs
+
+1. exercises/01.ts
+- Input: one product name and one quantity.
+- Output: original and copied records after a nested update.
+- Edge cases: negative quantity should print an error.
+
+2. exercises/02.ts
+- Input: item name, quantity, and reserved quantity.
+- Output: original and cloned inventory states after a clone-only update.
+- Edge cases: invalid counts; negative values.
+
+## Checkpoint
+
+- [ ] I can explain why object variables share references by default.
+- [ ] I can tell the difference between shallow and deep copies.
+- [ ] I can write an explicit clone helper when nested data requires it.
+- [ ] I completed exercises/01.ts.
+- [ ] I completed exercises/02.ts.

languages/typescript/03-advanced/copy-and-move-semantics/example/main.ts

@@ -0,0 +1,40 @@
+type InventoryRecord = {
+    name: string;
+    counts: {
+        inStock: number;
+        reserved: number;
+    };
+};
+
+function cloneInventory(record: InventoryRecord): InventoryRecord {
+    return {
+        name: record.name,
+        counts: {
+            inStock: record.counts.inStock,
+            reserved: record.counts.reserved,
+        },
+    };
+}
+
+const original: InventoryRecord = {
+    name: "Keyboard",
+    counts: { inStock: 10, reserved: 2 },
+};
+
+const alias = original;
+const shallowCopy = { ...original };
+const deepCopy = cloneInventory(original);
+
+alias.counts.inStock -= 1;
+shallowCopy.counts.reserved += 3;
+deepCopy.counts.inStock += 5;
+
+console.log(`Original: ${original.counts.inStock}/${original.counts.reserved}`);
+console.log(
+    `Shallow copy: ${shallowCopy.counts.inStock}/${shallowCopy.counts.reserved}`,
+);
+console.log(
+    `Deep copy: ${deepCopy.counts.inStock}/${deepCopy.counts.reserved}`,
+);
+
+export {};

languages/typescript/03-advanced/copy-and-move-semantics/exercises/01.ts

@@ -0,0 +1,32 @@
+import * as fs from "node:fs";
+
+type ProductRecord = {
+    name: string;
+    details: {
+        quantity: number;
+    };
+};
+
+function main(): void {
+    const tokens = fs
+        .readFileSync(0, "utf8")
+        .trim()
+        .split(/\s+/)
+        .filter((token) => token.length > 0);
+
+    const name = tokens[0] ?? "";
+    const quantity = Number.parseInt(tokens[1] ?? "", 10);
+    if (!name || !Number.isInteger(quantity) || quantity < 0) {
+        console.log("Expected: name nonNegativeQuantity");
+        return;
+    }
+
+    const original: ProductRecord = { name, details: { quantity } };
+    const copied = { ...original };
+    copied.details.quantity += 1;
+
+    console.log(`Original quantity: ${original.details.quantity}`);
+    console.log(`Copied quantity: ${copied.details.quantity}`);
+}
+
+main();