Add TypeScript core 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` implemented first.
+- TypeScript is the newest incremental track with `01-foundations` and `02-core` implemented first.
 - Status labels:
   - `Done`: module implemented with example, exercises, and README.
   - `Planned`: module not implemented yet, already queued in order.
@@ -29,16 +29,16 @@ Current parity progress in non-C++ tracks:
 - C#: `6/6` modules complete
 - Go: `6/6` modules complete
 - Python: `6/6` modules complete
-- TypeScript: `0/6` modules complete, foundations delivered first
+- TypeScript: `6/6` modules complete
 
 | Order | Module | C++ | C# | Go | Python | TypeScript |
 | --- | --- | --- | --- | --- | --- | --- |
-| 1 | input-validation | Done | Done | Done | Done | Planned |
-| 2 | algorithms-basics | Done | Done | Done | Done | Planned |
-| 3 | file-io-basics | Done | Done | Done | Done | Planned |
-| 4 | sorting-and-searching | Done | Done | Done | Done | Planned |
-| 5 | maps-and-frequency-counting | Done | Done | Done | Done | Planned |
-| 6 | error-handling-and-defensive-programming | Done | Done | Done | Done | Planned |
+| 1 | input-validation | Done | Done | Done | Done | Done |
+| 2 | algorithms-basics | Done | Done | Done | Done | Done |
+| 3 | file-io-basics | Done | Done | Done | Done | Done |
+| 4 | sorting-and-searching | Done | Done | Done | Done | Done |
+| 5 | maps-and-frequency-counting | Done | Done | Done | Done | Done |
+| 6 | error-handling-and-defensive-programming | Done | Done | Done | Done | Done |
 
 ## Advanced and Expert
 
@@ -83,7 +83,7 @@ Status labels:
 | Checkpoint | C++ | C# | Go | Python | TypeScript |
 | --- | --- | --- | --- | --- | --- |
 | 01-foundations | Done | Done | Done | Done | Done |
-| 02-core | Done | Done | Done | Done | Planned |
+| 02-core | Done | Done | Done | Done | Done |
 | 03-advanced | Done | Done | Done | Done | Planned |
 | 04-expert | Done | Done | Done | Done | Planned |
 
@@ -92,6 +92,6 @@ Status labels:
 | Checkpoint | C++ | C# | Go | Python | TypeScript |
 | --- | --- | --- | --- | --- | --- |
 | 01-foundations | Done | Done | Done | Done | Done |
-| 02-core | Done | Done | Done | Done | Planned |
+| 02-core | Done | Done | Done | Done | Done |
 | 03-advanced | Done | Done | Done | Done | Planned |
 | 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 | 8/8 foundations modules, 1/4 projects, 1/4 assessments | Foundations launched; core and above planned |
+| 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 |
 
 Parity planning reference: [LANGUAGE_PARITY_MATRIX.md](LANGUAGE_PARITY_MATRIX.md)
 

languages/typescript/02-core/README.md

@@ -0,0 +1,25 @@
+# TypeScript 02 Core
+
+This level extends the TypeScript track with validation, file handling, aggregation, and defensive workflows.
+
+## Learning Metadata
+
+- Difficulty: Intermediate.
+- Estimated Time: 4-6 hours across modules, project, and assessment.
+- Prerequisites: Completion of `01-foundations` plus either `projects/01-foundations` or `assessments/01-foundations`.
+- Study Strategy: Work in order, keep validation helpers small, and revisit parsing decisions before moving into the project and assessment.
+
+## Module Order
+
+1. [input-validation](./input-validation/README.md)
+2. [algorithms-basics](./algorithms-basics/README.md)
+3. [file-io-basics](./file-io-basics/README.md)
+4. [sorting-and-searching](./sorting-and-searching/README.md)
+5. [maps-and-frequency-counting](./maps-and-frequency-counting/README.md)
+6. [error-handling-and-defensive-programming](./error-handling-and-defensive-programming/README.md)
+
+Track progress in [../CHECKLIST.md](../CHECKLIST.md).
+
+## Study Tip
+
+Use `file-io-basics` and `error-handling-and-defensive-programming` together when you want to understand how real console tools keep working even when input gets messy.

languages/typescript/02-core/algorithms-basics/README.md

@@ -0,0 +1,55 @@
+# Algorithms Basics
+
+This module introduces core algorithm patterns over arrays in plain TypeScript.
+
+## Learning Metadata
+
+- Difficulty: Intermediate.
+- Estimated Time: 30-45 minutes.
+- Prerequisites: `01-foundations/arrays-and-vectors` and `01-foundations/functions`.
+- Cross-Language Lens: Compare explicit loops with library helpers and notice when beginner-friendly code is clearer than a dense chain of methods.
+
+## Quick Run
+
+~~~bash
+npm run build:typescript
+node build/typescript/02-core/algorithms-basics/example/main.js
+~~~
+
+## Topics Covered
+
+- Linear search for the first matching item.
+- One-pass minimum and maximum updates.
+- Counting matches while scanning once.
+- Combining several statistics in a single traversal.
+
+## Common Pitfalls
+
+- Assuming arrays are non-empty before min/max logic.
+- Using multiple passes when one traversal is enough.
+- Hiding simple logic inside clever but unreadable helpers.
+
+## Exercise Focus
+
+- exercises/01.ts: find the first index of a target value.
+- exercises/02.ts: compute minimum, maximum, and even count in one pass.
+
+### Exercise Specs
+
+1. exercises/01.ts
+- Input: integer `n`, then `n` values, then a target.
+- Output: first index of target or `-1`.
+- Edge cases: `n <= 0`; target not present.
+
+2. exercises/02.ts
+- Input: integer `n`, then `n` values.
+- Output: minimum, maximum, and even count.
+- Edge cases: all odd numbers; all equal values; `n <= 0`.
+
+## Checkpoint
+
+- [ ] I can implement linear search without relying on hidden helpers.
+- [ ] I can compute multiple statistics in a single traversal.
+- [ ] I can protect min/max logic against empty input.
+- [ ] I completed exercises/01.ts.
+- [ ] I completed exercises/02.ts.

languages/typescript/02-core/algorithms-basics/example/main.ts

@@ -0,0 +1,42 @@
+function firstIndexOf(values: number[], target: number): number {
+    for (let index = 0; index < values.length; index += 1) {
+        if (values[index] === target) {
+            return index;
+        }
+    }
+    return -1;
+}
+
+function summarize(values: number[]): {
+    minimum: number;
+    maximum: number;
+    evenCount: number;
+} {
+    let minimum = values[0]!;
+    let maximum = values[0]!;
+    let evenCount = 0;
+
+    for (const value of values) {
+        if (value < minimum) {
+            minimum = value;
+        }
+        if (value > maximum) {
+            maximum = value;
+        }
+        if (value % 2 === 0) {
+            evenCount += 1;
+        }
+    }
+
+    return { minimum, maximum, evenCount };
+}
+
+const values = [14, 7, 22, 14, 9, 18];
+const summary = summarize(values);
+console.log(`Values: ${values.join(", ")}`);
+console.log(`First index of 14: ${firstIndexOf(values, 14)}`);
+console.log(`Minimum: ${summary.minimum}`);
+console.log(`Maximum: ${summary.maximum}`);
+console.log(`Even count: ${summary.evenCount}`);
+
+export {};

languages/typescript/02-core/algorithms-basics/exercises/01.ts

@@ -0,0 +1,41 @@
+import * as fs from "node:fs";
+
+function main(): void {
+    const tokens = fs
+        .readFileSync(0, "utf8")
+        .trim()
+        .split(/\s+/)
+        .filter((token) => token.length > 0);
+
+    const count = Number.parseInt(tokens[0] ?? "", 10);
+    if (!Number.isInteger(count) || count <= 0) {
+        console.log("Count must be a positive integer.");
+        return;
+    }
+
+    const values = tokens
+        .slice(1, count + 1)
+        .map((token) => Number.parseInt(token, 10));
+    const target = Number.parseInt(tokens[count + 1] ?? "", 10);
+
+    if (
+        values.length !== count ||
+        values.some((value) => !Number.isInteger(value)) ||
+        !Number.isInteger(target)
+    ) {
+        console.log("Invalid algorithm input.");
+        return;
+    }
+
+    let foundIndex = -1;
+    for (let index = 0; index < values.length; index += 1) {
+        if (values[index] === target) {
+            foundIndex = index;
+            break;
+        }
+    }
+
+    console.log(`First index: ${foundIndex}`);
+}
+
+main();

languages/typescript/02-core/algorithms-basics/exercises/02.ts

@@ -0,0 +1,48 @@
+import * as fs from "node:fs";
+
+function main(): void {
+    const tokens = fs
+        .readFileSync(0, "utf8")
+        .trim()
+        .split(/\s+/)
+        .filter((token) => token.length > 0);
+
+    const count = Number.parseInt(tokens[0] ?? "", 10);
+    if (!Number.isInteger(count) || count <= 0) {
+        console.log("Count must be a positive integer.");
+        return;
+    }
+
+    const values = tokens
+        .slice(1, count + 1)
+        .map((token) => Number.parseInt(token, 10));
+    if (
+        values.length !== count ||
+        values.some((value) => !Number.isInteger(value))
+    ) {
+        console.log("Invalid value list.");
+        return;
+    }
+
+    let minimum = values[0]!;
+    let maximum = values[0]!;
+    let evenCount = 0;
+
+    for (const value of values) {
+        if (value < minimum) {
+            minimum = value;
+        }
+        if (value > maximum) {
+            maximum = value;
+        }
+        if (value % 2 === 0) {
+            evenCount += 1;
+        }
+    }
+
+    console.log(`Minimum: ${minimum}`);
+    console.log(`Maximum: ${maximum}`);
+    console.log(`Even count: ${evenCount}`);
+}
+
+main();

languages/typescript/02-core/error-handling-and-defensive-programming/README.md

@@ -0,0 +1,55 @@
+# Error Handling and Defensive Programming
+
+This module teaches TypeScript programs to reject bad data cleanly without losing control flow.
+
+## Learning Metadata
+
+- Difficulty: Intermediate.
+- Estimated Time: 30-45 minutes.
+- Prerequisites: `02-core/input-validation` and `02-core/file-io-basics`.
+- Cross-Language Lens: Compare guard clauses, nullable parse results, and selective `try/catch` with the defensive styles used in the other tracks.
+
+## Quick Run
+
+~~~bash
+npm run build:typescript
+node build/typescript/02-core/error-handling-and-defensive-programming/example/main.js
+~~~
+
+## Topics Covered
+
+- Guard clauses that stop unsafe work early.
+- Parse helpers that return `null` instead of half-valid data.
+- Catching only the errors you actually expect.
+- Preserving valid work even when part of the input is malformed.
+
+## Common Pitfalls
+
+- Catching every error without improving the message.
+- Pushing invalid data forward just to avoid returning early.
+- Mixing user-facing errors with internal debugging details.
+
+## Exercise Focus
+
+- exercises/01.ts: safely parse one `name score` record.
+- exercises/02.ts: ignore invalid numeric tokens and summarize the valid ones.
+
+### Exercise Specs
+
+1. exercises/01.ts
+- Input: one line shaped like `Full Name Score`.
+- Output: accepted record or an error message.
+- Edge cases: missing name; non-integer score; score outside `0..100`.
+
+2. exercises/02.ts
+- Input: one line of mixed tokens.
+- Output: valid count and average of accepted integers.
+- Edge cases: no valid integers; malformed tokens between valid numbers.
+
+## Checkpoint
+
+- [ ] I can stop bad input before it pollutes later steps.
+- [ ] I can return safe parse results instead of throwing for routine validation.
+- [ ] I can keep useful work even when some rows fail.
+- [ ] I completed exercises/01.ts.
+- [ ] I completed exercises/02.ts.

languages/typescript/02-core/error-handling-and-defensive-programming/example/main.ts

@@ -0,0 +1,47 @@
+type ScoreRecord = {
+    name: string;
+    score: number;
+};
+
+function parseRecord(line: string): ScoreRecord | null {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 2) {
+        return null;
+    }
+
+    const score = Number.parseInt(parts.at(-1) ?? "", 10);
+    if (!Number.isInteger(score) || score < 0 || score > 100) {
+        return null;
+    }
+
+    const name = parts.slice(0, -1).join(" ");
+    if (!name) {
+        return null;
+    }
+
+    return { name, score };
+}
+
+const rows = [
+    "Ana Smith 91",
+    "InvalidRow",
+    "Bob Lee ninety",
+    "Carla Mendez 88",
+];
+const accepted: ScoreRecord[] = [];
+
+for (const row of rows) {
+    const record = parseRecord(row);
+    if (record === null) {
+        console.log(`Skipped invalid row: ${row}`);
+        continue;
+    }
+    accepted.push(record);
+}
+
+console.log(`Accepted rows: ${accepted.length}`);
+for (const record of accepted) {
+    console.log(`- ${record.name}: ${record.score}`);
+}
+
+export {};