How wenxuanlee/typescript-generics-workshop works
Project type and purpose
• This is an open-source, CLI-based tutorial runner for teaching TypeScript generics.
• It organizes individual “problem” and “solution” exercises in a file hierarchy and lets the user pick and run them via npm run exercise.
• Under the hood it uses Node + TypeScript + Vitest (via Vite) to compile, execute, and test each exercise.
File structure
• Top-level:
• package.json / package-lock.json – NPM scripts, dependencies, and entrypoints (e.g. exercise)
• tsconfig.json / vite.config.mts – TypeScript compiler settings and Vitest/Vite test configuration
• scripts/tests – custom test harness and snapshots
• src – exercise modules organized by chapters (01-generics-intro, 02-passing-type-arguments, …) plus helpers/type-utils.ts
• Each exercise folder contains .problem.ts and sometimes .explainer.ts files (and solutions implicitly defined).
• CI workflows under .github/workflows run checks and Renovate.
README for additional insights
• Describes the interactive workflow: prompt user → run chosen exercise → tests pass or fail → reveal solutions.
• Encourages exploratory, test-driven learning.
Main components and their interactions
a. User (CLI)
b. CLI Entrypoint (defined in package.json: npm run exercise)
c. Exercise Manager / Prompt Module – scans src/*/*.problem.ts, displays choices, loads selected module
d. TypeScript Execution Environment – uses TS Node or Vite to compile+execute TypeScript on the fly
e. Test Runner – Vitest (configured via vite.config.mts and scripts/tests) that runs the test suite for the chosen exercise and compares against snapshots
f. Helpers – shared utilities in src/helpers/type-utils.ts
g. File System – the physical src directory and snapshot files under scripts/tests/__snapshots__
h. CI/CD – GitHub Actions workflows for automated checks and Renovate updates
Architectural patterns and design principles
• Modular per-exercise structure (one folder per exercise).
• Separation of concerns: CLI & prompt logic, test harness, exercise code, helpers.
• Test-driven learning: exercises fail until the user implements a solution that satisfies the tests.
• Configuration-as-code: TS config, Vite config, and NPM scripts define behavior.