Add TypeScript foundations track

Author: lucasbellesi

.github/workflows/cpp-build.yml

@@ -16,6 +16,11 @@ jobs:
         with:
           python-version: "3.12"
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
@@ -34,6 +39,9 @@ jobs:
       - name: Install Ruff
         run: python -m pip install ruff
 
+      - name: Install Node dependencies
+        run: npm ci
+
       - name: Run lint checks
         run: bash ./scripts/lint.sh
 
@@ -48,6 +56,11 @@ jobs:
         with:
           python-version: "3.12"
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
@@ -63,6 +76,9 @@ jobs:
           sudo apt update
           sudo apt install -y g++
 
+      - name: Install Node dependencies
+        run: npm ci
+
       - name: Verify repository
         run: bash ./scripts/verify-repo.sh
 
@@ -80,6 +96,11 @@ jobs:
         with:
           python-version: "3.12"
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
@@ -108,6 +129,10 @@ jobs:
         shell: pwsh
         run: g++ --version
 
+      - name: Install Node dependencies
+        shell: pwsh
+        run: npm ci
+
       - name: Verify repository
         shell: pwsh
         run: powershell -ExecutionPolicy Bypass -File scripts\verify-repo.ps1

.gitignore

@@ -14,3 +14,4 @@ __pycache__/
 *.pyc
 report.txt
 core_assessment_report.txt
+node_modules/

CONTRIBUTING.md

@@ -8,6 +8,7 @@ Thank you for contributing to this repository.
 - Prefer simple, readable examples over clever implementations.
 - Use clear English for all text, comments, and instructions.
 - Maintain cross-platform compatibility (Windows MSYS2 + Linux).
+- Keep Node-based tooling simple and explicit when touching the TypeScript track.
 
 ## Workflow
 
@@ -60,6 +61,7 @@ Run language lint checks with:
 - `bash ./scripts/lint.sh` (Bash)
 
 These smoke checks also compile standalone C# exercises by generating temporary validation projects during the check.
+TypeScript checks restore Node dependencies from `package-lock.json`, compile with `tsc`, and execute the emitted JavaScript with `node`.
 
 The public PowerShell and Bash scripts are thin wrappers over the shared Python automation core in `scripts/automation.py`. Curriculum validation and smoke target metadata live in `scripts/automation_manifest.json`.
 
@@ -79,7 +81,7 @@ The public PowerShell and Bash scripts are thin wrappers over the shared Python
   - `## Checkpoint`
 - Every project or assessment checkpoint should include:
   - `README.md`
-  - runnable entrypoint (`main.cs` + `.csproj`, `main.go`, or `main.py`)
+  - runnable entrypoint (`main.cs` + `.csproj`, `main.go`, `main.py`, or `main.ts`)
   - the same learner goal, input/output shape, and acceptance expectations as the corresponding C++ checkpoint
   - required `## Learning Metadata` before `## Quick Run` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Learning Focus`
 - Every implemented level README should include required `## Learning Metadata` before `## Module Order` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Study Strategy`.
@@ -93,6 +95,7 @@ The public PowerShell and Bash scripts are thin wrappers over the shared Python
 - Every exercise file must contain complete, runnable content.
 - Avoid external dependencies and test frameworks for C++ modules.
 - Avoid external dependencies and test frameworks for non-C++ checkpoints.
+- Keep the TypeScript track on plain Node console programs; do not introduce browser, DOM, or framework dependencies.
 - Keep examples aligned with C++17.
 - Keep documentation in English and keep path names consistent with folder names.
 - Keep parity planning updated in `LANGUAGE_PARITY_MATRIX.md` when adding modules or checkpoints to non-C++ tracks.

LANGUAGE_PARITY_MATRIX.md

@@ -1,25 +1,26 @@
 # Language Parity Matrix
 
-This matrix tracks module and checkpoint parity across C++, C#, Go, and Python.
+This matrix tracks module and checkpoint parity across C++, C#, Go, Python, and TypeScript.
 
 - Canonical order is defined by the C++ track.
 - Module and checkpoint parity now reach `04-expert` across all active tracks.
+- TypeScript is the newest incremental track with `01-foundations` implemented first.
 - Status labels:
   - `Done`: module implemented with example, exercises, and README.
   - `Planned`: module not implemented yet, already queued in order.
 
 ## Foundations (`01-foundations`)
 
-| Module | C++ | C# | Go | Python |
-| --- | --- | --- | --- | --- |
-| types-and-io | Done | Done | Done | Done |
-| operators-and-expressions | Done | Done | Done | Done |
-| control-flow | Done | Done | Done | Done |
-| functions | Done | Done | Done | Done |
-| arrays-and-vectors | Done | Done | Done | Done |
-| strings | Done | Done | Done | Done |
-| scope-and-lifetime-basics | Done | Done | Done | Done |
-| formatted-output-and-iomanip | Done | Done | Done | Done |
+| Module | C++ | C# | Go | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- |
+| types-and-io | Done | Done | Done | Done | Done |
+| operators-and-expressions | Done | Done | Done | Done | Done |
+| control-flow | Done | Done | Done | Done | Done |
+| functions | Done | Done | Done | Done | Done |
+| arrays-and-vectors | Done | Done | Done | Done | Done |
+| strings | Done | Done | Done | Done | Done |
+| scope-and-lifetime-basics | Done | Done | Done | Done | Done |
+| formatted-output-and-iomanip | Done | Done | Done | Done | Done |
 
 ## Core (`02-core`)
 
@@ -28,15 +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
 
-| Order | Module | C++ | C# | Go | Python |
-| --- | --- | --- | --- | --- | --- |
-| 1 | input-validation | Done | Done | Done | Done |
-| 2 | algorithms-basics | Done | Done | Done | Done |
-| 3 | file-io-basics | Done | Done | Done | Done |
-| 4 | sorting-and-searching | Done | Done | Done | Done |
-| 5 | maps-and-frequency-counting | Done | Done | Done | Done |
-| 6 | error-handling-and-defensive-programming | Done | Done | Done | Done |
+| 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 |
 
 ## Advanced and Expert
 
@@ -45,28 +47,29 @@ 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
 
 ### Advanced (`03-advanced`) - Current Expansion Queue
 
-| Order | Module | C++ | C# | Go | Python |
-| --- | --- | --- | --- | --- | --- |
-| 1 | structs-and-classes | Done | Done | Done | Done |
-| 2 | constructors-and-invariants | Done | Done | Done | Done |
-| 3 | copy-and-move-semantics | Done | Done | Done | Done |
-| 4 | inheritance-and-polymorphism | Done | Done | Done | Done |
-| 5 | templates-basics | Done | Done | Done | Done |
+| 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 |
 
 `04-expert` projects and assessments are now implemented across C#, Go, and Python.
 
 ### Expert (`04-expert`)
 
-| Order | Module | C++ | C# | Go | Python |
-| --- | --- | --- | --- | --- | --- |
-| 1 | memory-management-and-raii | Done | Done | Done | Done |
-| 2 | smart-pointers-in-depth | Done | Done | Done | Done |
-| 3 | concurrency-basics | Done | Done | Done | Done |
-| 4 | performance-and-profiling-basics | Done | Done | Done | Done |
-| 5 | modularization-and-build-structure | Done | Done | Done | Done |
+| 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 |
 
 ## Checkpoint Parity
 
@@ -77,18 +80,18 @@ Status labels:
 
 ### Projects
 
-| Checkpoint | C++ | C# | Go | Python |
-| --- | --- | --- | --- | --- |
-| 01-foundations | Done | Done | Done | Done |
-| 02-core | Done | Done | Done | Done |
-| 03-advanced | Done | Done | Done | Done |
-| 04-expert | Done | Done | Done | Done |
+| Checkpoint | C++ | C# | Go | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- |
+| 01-foundations | Done | Done | Done | Done | Done |
+| 02-core | Done | Done | Done | Done | Planned |
+| 03-advanced | Done | Done | Done | Done | Planned |
+| 04-expert | Done | Done | Done | Done | Planned |
 
 ### Assessments
 
-| Checkpoint | C++ | C# | Go | Python |
-| --- | --- | --- | --- | --- |
-| 01-foundations | Done | Done | Done | Done |
-| 02-core | Done | Done | Done | Done |
-| 03-advanced | Done | Done | Done | Done |
-| 04-expert | Done | Done | Done | Done |
+| Checkpoint | C++ | C# | Go | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- |
+| 01-foundations | Done | Done | Done | Done | Done |
+| 02-core | Done | Done | Done | Done | Planned |
+| 03-advanced | Done | Done | Done | Done | Planned |
+| 04-expert | Done | Done | Done | Done | Planned |

README.md

@@ -4,7 +4,7 @@
 
 This repository teaches programming through small runnable examples and focused exercises.
 
-- Four active language tracks: C++, C#, Go, and Python.
+- Five active language tracks: C++, C#, Go, Python, and TypeScript.
 - Shared concept naming across tracks for easier comparison.
 - VS Code-first workflow, with scripts for Windows PowerShell and Bash.
 
@@ -15,6 +15,7 @@ This repository teaches programming through small runnable examples and focused
    - [C# Guide](languages/csharp/README.md)
    - [Go Guide](languages/go/README.md)
    - [Python Guide](languages/python/README.md)
+   - [TypeScript Guide](languages/typescript/README.md)
 2. Open the `01-foundations` roadmap for your selected language.
 3. Run one module example.
 4. Solve `exercises/01` and `exercises/02` in that module.
@@ -28,6 +29,7 @@ This repository teaches programming through small runnable examples and focused
 | 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 |
 
 Parity planning reference: [LANGUAGE_PARITY_MATRIX.md](LANGUAGE_PARITY_MATRIX.md)
 
@@ -58,6 +60,13 @@ go run languages/go/01-foundations/types-and-io/example/main.go
 python languages/python/01-foundations/types-and-io/example/main.py
 ~~~
 
+### TypeScript
+
+~~~bash
+npm run build:typescript
+node build/typescript/01-foundations/types-and-io/example/main.js
+~~~
+
 ## Repository Structure
 
 ~~~text
@@ -71,6 +80,7 @@ learn-programming-languages-with-examples/
     csharp/
     go/
     python/
+    typescript/
 ~~~
 
 ## Documentation Contract
@@ -95,7 +105,7 @@ A standardized `## Learning Metadata` block is required before `## Quick Run` fo
 Checkpoint artifacts under `languages/<language>/projects/*` and `languages/<language>/assessments/*` should mirror the corresponding C++ checkpoint style:
 
 - `README.md`
-- runnable entrypoint (`main.cs` + `.csproj`, `main.go`, or `main.py`)
+- runnable entrypoint (`main.cs` + `.csproj`, `main.go`, `main.py`, or `main.ts`)
 - same learner goal, input/output shape, and acceptance expectations as the C++ version
 
 ## Example Commenting Standard
@@ -132,11 +142,11 @@ bash ./scripts/build-all.sh
 bash ./scripts/verify-repo.sh
 ~~~
 
-GitHub Actions validates links, README structure, module completeness, checkpoint completeness, documentation sync, C++ build, multi-language smoke checks, and Linux lint checks for C++, Python, Go, and C#.
+GitHub Actions validates links, README structure, module completeness, checkpoint completeness, documentation sync, compiled-language builds, multi-language smoke checks, and Linux lint checks for C++, Python, Go, C#, and TypeScript.
 
 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.
+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.
 
 ## Contributing
 

languages/typescript/01-foundations/README.md

@@ -0,0 +1,27 @@
+# TypeScript 01 Foundations
+
+This level mirrors the C++ foundations roadmap with explicit parsing and beginner-friendly TypeScript console programs.
+
+## Learning Metadata
+
+- Difficulty: Beginner.
+- Estimated Time: 3-5 hours across modules, project, and assessment.
+- Prerequisites: None; this is the entry level for the TypeScript track.
+- Study Strategy: Work in module order, build the track often, solve both exercises in each module, then finish the project and assessment.
+
+## Module Order
+
+1. [types-and-io](./types-and-io/README.md)
+2. [operators-and-expressions](./operators-and-expressions/README.md)
+3. [control-flow](./control-flow/README.md)
+4. [functions](./functions/README.md)
+5. [arrays-and-vectors](./arrays-and-vectors/README.md)
+6. [strings](./strings/README.md)
+7. [scope-and-lifetime-basics](./scope-and-lifetime-basics/README.md)
+8. [formatted-output-and-iomanip](./formatted-output-and-iomanip/README.md)
+
+Track progress in [../CHECKLIST.md](../CHECKLIST.md).
+
+## Study Tip
+
+Solve the same module in C++ and TypeScript back to back so you can compare explicit parsing, type annotations, and data-structure ergonomics.

languages/typescript/01-foundations/arrays-and-vectors/README.md

@@ -0,0 +1,54 @@
+# Arrays and Dynamic Lists
+
+This module uses typed arrays to store, transform, and summarize groups of values.
+
+## Learning Metadata
+
+- Difficulty: Beginner.
+- Estimated Time: 20-35 minutes.
+- Prerequisites: 01-foundations/control-flow and 01-foundations/functions.
+- Cross-Language Lens: Compare vector, List<T>, slices, Python lists, and TypeScript arrays as different tradeoffs for dynamic sequence work.
+
+## Quick Run
+
+~~~bash
+npm run build:typescript
+node build/typescript/01-foundations/arrays-and-vectors/example/main.js
+~~~
+
+## Topics Covered
+
+- Typed arrays such as number[] and string[].
+- Looping with for...of and array methods.
+- Filtering and mapping without losing readability.
+- Computing summary values from a list.
+
+## Common Pitfalls
+
+- Chaining too many array methods for a beginner example.
+- Forgetting that arrays are mutable by default.
+- Skipping empty-list checks before accessing index 0.
+
+## Exercise Focus
+
+- exercises/01.ts: read integers and print them in reverse order.
+- exercises/02.ts: remove duplicates while preserving the first appearance order.
+
+### Exercise Specs
+
+1. exercises/01.ts
+- Input: an integer N followed by N integers.
+- Output: the integers from last to first.
+- Edge cases: N <= 0 should print an error; repeated values should stay repeated in reverse.
+
+2. exercises/02.ts
+- Input: one line of space-separated words.
+- Output: the unique words in first-seen order.
+- Edge cases: empty input should print an error; already unique input should stay unchanged.
+
+## Checkpoint
+
+- [ ] I can explain the main TypeScript idea in this module.
+- [ ] I can run the example and describe the output.
+- [ ] I completed exercises/01.ts.
+- [ ] I completed exercises/02.ts.