Add TypeScript expert track

Author: lucasbellesi

LANGUAGE_PARITY_MATRIX.md

@@ -3,8 +3,7 @@
 This matrix tracks module and checkpoint parity across C++, C#, Go, Python, and TypeScript.
 
 - 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`, `02-core`, and `03-advanced` implemented first.
+- C++, C#, Go, Python, and TypeScript now reach module and checkpoint parity through `04-expert`.
 - Status labels:
   - `Done`: module implemented with example, exercises, and README.
   - `Planned`: module not implemented yet, already queued in order.
@@ -47,7 +46,7 @@ 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: `5/5` modules complete in `03-advanced`; `04-expert` planned next
+- TypeScript: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
 
 ### Advanced (`03-advanced`) - Current Expansion Queue
 
@@ -59,17 +58,17 @@ Current parity progress in non-C++ tracks:
 | 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.
+`04-expert` projects and assessments are now implemented across all active non-C++ tracks.
 
 ### Expert (`04-expert`)
 
 | Order | Module | C++ | C# | Go | Python | TypeScript |
 | --- | --- | --- | --- | --- | --- | --- |
-| 1 | memory-management-and-raii | Done | Done | Done | Done | Planned |
-| 2 | smart-pointers-in-depth | Done | Done | Done | Done | Planned |
-| 3 | concurrency-basics | Done | Done | Done | Done | Planned |
-| 4 | performance-and-profiling-basics | Done | Done | Done | Done | Planned |
-| 5 | modularization-and-build-structure | Done | Done | Done | Done | Planned |
+| 1 | memory-management-and-raii | Done | Done | Done | Done | Done |
+| 2 | smart-pointers-in-depth | Done | Done | Done | Done | Done |
+| 3 | concurrency-basics | Done | Done | Done | Done | Done |
+| 4 | performance-and-profiling-basics | Done | Done | Done | Done | Done |
+| 5 | modularization-and-build-structure | Done | Done | Done | Done | Done |
 
 ## Checkpoint Parity
 
@@ -85,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 | Done |
-| 04-expert | Done | Done | Done | Done | Planned |
+| 04-expert | Done | Done | Done | Done | Done |
 
 ### Assessments
 
@@ -94,4 +93,4 @@ Status labels:
 | 01-foundations | Done | Done | Done | Done | Done |
 | 02-core | Done | Done | Done | Done | Done |
 | 03-advanced | Done | Done | Done | Done | Done |
-| 04-expert | Done | Done | Done | Done | Planned |
+| 04-expert | Done | Done | Done | Done | Done |

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, 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 |
+| TypeScript | 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 |
 
 Parity planning reference: [LANGUAGE_PARITY_MATRIX.md](LANGUAGE_PARITY_MATRIX.md)
 
@@ -171,7 +171,7 @@ GitHub Actions validates links, README structure, module completeness, checkpoin
 
 The public PowerShell and Bash scripts remain the supported entrypoints, but they now delegate to a shared Python automation core under `scripts/automation.py` backed by `scripts/automation_manifest.json`.
 
-The multi-language smoke scripts also compile standalone C# exercises by generating temporary validation projects during the check and compile TypeScript foundations programs before executing their smoke targets.
+The multi-language smoke scripts also compile standalone C# exercises by generating temporary validation projects during the check and compile TypeScript programs before executing their smoke targets.
 
 ## Contributing
 

languages/typescript/04-expert/README.md

@@ -0,0 +1,24 @@
+# TypeScript 04 Expert
+
+This level adapts expert topics to TypeScript's runtime model: explicit cleanup, reference identity, async concurrency, performance measurement, and modular structure.
+
+## Learning Metadata
+
+- Difficulty: Advanced.
+- Estimated Time: 4-6 hours across modules, project, and assessment.
+- Prerequisites: Completion of `03-advanced` plus its project or assessment checkpoint.
+- Study Strategy: Work through the modules in order, then the capstone, then the assessment, and compare which expert ideas map directly from C++ and which need a TypeScript-specific interpretation.
+
+## Module Order
+
+1. [memory-management-and-raii](./memory-management-and-raii/README.md)
+2. [smart-pointers-in-depth](./smart-pointers-in-depth/README.md)
+3. [concurrency-basics](./concurrency-basics/README.md)
+4. [performance-and-profiling-basics](./performance-and-profiling-basics/README.md)
+5. [modularization-and-build-structure](./modularization-and-build-structure/README.md)
+
+Track progress in [../CHECKLIST.md](../CHECKLIST.md).
+
+## Study Tip
+
+Treat this level as a translation exercise: TypeScript does not have RAII or move semantics in the C++ sense, so focus on explicit cleanup, reference behavior, and event-loop concurrency instead of forcing one-to-one vocabulary matches.

languages/typescript/04-expert/concurrency-basics/README.md

@@ -0,0 +1,56 @@
+# Concurrency Basics
+
+This module introduces TypeScript concurrency through async tasks, `Promise.all`, and work coordination on the event loop.
+
+## Learning Metadata
+
+- Difficulty: Advanced.
+- Estimated Time: 45-60 minutes.
+- Prerequisites: `02-core/algorithms-basics` and `03-advanced/templates-basics`.
+- Cross-Language Lens: Compare thread-based concurrency in C++ or Go with TypeScript's event-loop concurrency, where tasks overlap without shared-memory threads by default.
+
+## Quick Run
+
+~~~bash
+npm run build:typescript
+node build/typescript/04-expert/concurrency-basics/example/main.js
+~~~
+
+## Topics Covered
+
+- Launching independent async tasks.
+- Preserving result order with `Promise.all`.
+- Limiting concurrency with a worker-pool helper.
+- Separating task coordination from task logic.
+
+## Common Pitfalls
+
+- Confusing concurrency with parallel CPU work.
+- Awaiting inside a loop when independent work could overlap.
+- Mutating shared arrays in confusing ways instead of returning results.
+- Ignoring task failures inside a larger concurrent batch.
+
+## Exercise Focus
+
+- exercises/01.ts: fetch several async results and preserve display order.
+- exercises/02.ts: process jobs with a maximum of two active workers.
+
+### Exercise Specs
+
+1. exercises/01.ts
+- Input: none.
+- Output: completed task results in the original request order.
+- Edge cases: mixed delays; one task finishing earlier than the first request.
+
+2. exercises/02.ts
+- Input: none.
+- Output: worker start/finish logs plus a final ordered summary.
+- Edge cases: fewer jobs than workers; an empty job list.
+
+## Checkpoint
+
+- [ ] I can explain how `Promise.all` overlaps async work.
+- [ ] I can preserve deterministic output even when completion order varies.
+- [ ] I can limit concurrency without rewriting the task itself.
+- [ ] I completed exercises/01.ts.
+- [ ] I completed exercises/02.ts.

languages/typescript/04-expert/concurrency-basics/example/main.ts

@@ -0,0 +1,41 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+type JobResult = {
+    name: string;
+    score: number;
+};
+
+async function loadJob(
+    name: string,
+    waitMs: number,
+    score: number,
+): Promise<JobResult> {
+    await delay(waitMs);
+    return { name, score };
+}
+
+async function main(): Promise<void> {
+    // Promise.all keeps the output order tied to the request order.
+    const results = await Promise.all([
+        loadJob("load", 25, 3),
+        loadJob("validate", 10, 5),
+        loadJob("save", 15, 4),
+    ]);
+
+    const total = results.reduce((sum, result) => sum + result.score, 0);
+
+    console.log(`Completed ${results.length} concurrent jobs.`);
+    for (const result of results) {
+        console.log(`- ${result.name}: ${result.score}`);
+    }
+    console.log(`Total value: ${total}`);
+}
+
+main().catch((error: unknown) => {
+    if (error instanceof Error) {
+        console.error(error.message);
+    } else {
+        console.error("Unknown error");
+    }
+    process.exitCode = 1;
+});

languages/typescript/04-expert/concurrency-basics/exercises/01.ts

@@ -0,0 +1,25 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+async function fetchLabel(label: string, waitMs: number): Promise<string> {
+    await delay(waitMs);
+    return `${label} ready`;
+}
+
+async function main(): Promise<void> {
+    const labels = await Promise.all([
+        fetchLabel("alpha", 20),
+        fetchLabel("beta", 5),
+        fetchLabel("gamma", 12),
+    ]);
+
+    for (const label of labels) {
+        console.log(label);
+    }
+}
+
+main().catch((error: unknown) => {
+    if (error instanceof Error) {
+        console.error(error.message);
+    }
+    process.exitCode = 1;
+});

languages/typescript/04-expert/concurrency-basics/exercises/02.ts

@@ -0,0 +1,43 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+async function runWithLimit<T>(
+    values: T[],
+    limit: number,
+    worker: (value: T) => Promise<string>,
+): Promise<string[]> {
+    const results = new Array<string>(values.length);
+    let nextIndex = 0;
+
+    async function runWorker(): Promise<void> {
+        while (nextIndex < values.length) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            results[currentIndex] = await worker(values[currentIndex]!);
+        }
+    }
+
+    const runners = Array.from({ length: Math.min(limit, values.length) }, () =>
+        runWorker(),
+    );
+    await Promise.all(runners);
+    return results;
+}
+
+async function main(): Promise<void> {
+    const jobs = [30, 10, 20, 5];
+    const results = await runWithLimit(jobs, 2, async (waitMs) => {
+        await delay(waitMs);
+        return `finished ${waitMs}`;
+    });
+
+    for (const result of results) {
+        console.log(result);
+    }
+}
+
+main().catch((error: unknown) => {
+    if (error instanceof Error) {
+        console.error(error.message);
+    }
+    process.exitCode = 1;
+});

languages/typescript/04-expert/memory-management-and-raii/README.md

@@ -0,0 +1,56 @@
+# Memory Management and RAII
+
+This module adapts RAII to TypeScript by focusing on explicit cleanup, `try/finally`, and disposable-style helpers.
+
+## Learning Metadata
+
+- Difficulty: Advanced.
+- Estimated Time: 30-45 minutes.
+- Prerequisites: `03-advanced/constructors-and-invariants` and `02-core/error-handling-and-defensive-programming`.
+- Cross-Language Lens: Compare C++ destructor-driven cleanup with TypeScript's explicit `close` methods and `try/finally` scopes.
+
+## Quick Run
+
+~~~bash
+npm run build:typescript
+node build/typescript/04-expert/memory-management-and-raii/example/main.js
+~~~
+
+## Topics Covered
+
+- Explicit cleanup through `close`.
+- Wrapping resource usage in helper scopes.
+- Guarding against use-after-close bugs.
+- Separating resource lifetime from business logic.
+
+## Common Pitfalls
+
+- Assuming garbage collection will close files or sockets for you.
+- Forgetting to close a resource on the error path.
+- Reusing a closed resource because the object reference still exists.
+- Mixing cleanup logic into unrelated application code.
+
+## Exercise Focus
+
+- exercises/01.ts: use `try/finally` to close a temporary resource safely.
+- exercises/02.ts: enforce closed-state guardrails in a reusable session object.
+
+### Exercise Specs
+
+1. exercises/01.ts
+- Input: none.
+- Output: setup, work, and cleanup messages in the correct order.
+- Edge cases: cleanup must still happen after a simulated failure.
+
+2. exercises/02.ts
+- Input: none.
+- Output: session logs before closing, after closing, and a guarded error message.
+- Edge cases: repeated close calls; operations attempted after close.
+
+## Checkpoint
+
+- [ ] I can explain why garbage collection does not replace explicit cleanup.
+- [ ] I can use `try/finally` to guarantee cleanup.
+- [ ] I can guard a resource from use-after-close mistakes.
+- [ ] I completed exercises/01.ts.
+- [ ] I completed exercises/02.ts.

languages/typescript/04-expert/memory-management-and-raii/example/main.ts

@@ -0,0 +1,56 @@
+class FakeFile {
+    private closed = false;
+
+    constructor(readonly name: string) {
+        console.log(`Opening ${name}`);
+    }
+
+    writeLine(line: string): void {
+        this.ensureOpen();
+        console.log(`writing: ${line}`);
+    }
+
+    close(): void {
+        if (!this.closed) {
+            console.log(`Closing ${this.name}`);
+            this.closed = true;
+        }
+    }
+
+    isClosed(): boolean {
+        return this.closed;
+    }
+
+    private ensureOpen(): void {
+        if (this.closed) {
+            throw new Error("Resource already closed.");
+        }
+    }
+}
+
+function usingResource<T extends { close(): void }, TResult>(
+    resource: T,
+    work: (resource: T) => TResult,
+): TResult {
+    try {
+        return work(resource);
+    } finally {
+        resource.close();
+    }
+}
+
+function main(): void {
+    // Intent: make cleanup explicit even though the language has garbage collection.
+    const report = new FakeFile("report.txt");
+
+    usingResource(report, (handle) => {
+        handle.writeLine("header");
+        handle.writeLine("totals");
+    });
+
+    console.log(`Closed after scope: ${report.isClosed()}`);
+}
+
+main();
+
+export {};