@shaykec/bridge 0.4.25 → 0.4.26

package/modules/test-strategy/walkthrough.md

@@ -0,0 +1,97 @@
+# Test Strategy Walkthrough — Learn by Doing
+
+## Before We Begin
+
+**Diagnostic Question:** When you hear "test pyramid," what do you picture? Where would unit tests, integration tests, and e2e tests sit — and why does that shape matter?
+
+**Checkpoint:** You have a rough mental model of the test pyramid (many unit tests at the base, fewer e2e at the top). You're ready to think about what belongs at each layer.
+
+---
+
+## Step 1: Identify Test Layers for a Feature
+
+You're building a "Forgot Password" flow: user enters email → receives reset link → clicks link → sets new password → logs in.
+
+<!-- hint:diagram mermaid-type="flowchart" topic="test pyramid layers" -->
+<!-- hint:buttons type="single" prompt="Which layer verifies the full user flow?" options="Unit,Integration,E2E" -->
+
+**Task:** For this flow, list one example of (a) a unit test, (b) an integration test, and (c) an e2e test. What does each layer verify that the others don't?
+
+**Question:** Why would you want more unit tests than e2e tests for this flow? What happens if you only have e2e tests?
+
+**Checkpoint:** User identifies: unit = validate email format, hash password logic; integration = email service sends, token storage/retrieval; e2e = full click-through flow. They understand unit = fast feedback, e2e = confidence but slow.
+
+---
+
+## Step 2: What to Test vs What Not to Test
+
+<!-- hint:card type="concept" title="Worth testing" -->
+
+Consider this function:
+
+```javascript
+function formatCurrency(amount) {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD'
+  }).format(amount);
+}
+```
+
+**Task:** Should you test this? If yes, what would you assert? If no, why not? Now consider a function that computes tax: `function computeTax(subtotal, state) { ... }`. What would you test there?
+
+**Question:** What makes one function "worth testing" and another "skip it"?
+
+**Checkpoint:** User sees formatCurrency as thin wrapper over Intl — maybe one smoke test. computeTax has business logic (rates, edge cases) — definitely test. Worth testing = non-trivial logic, business rules, bug-prone code.
+
+---
+
+## Step 3: Choose a Test Double
+
+<!-- hint:list style="cards" -->
+
+You're testing a function `processOrder(order)` that calls `paymentGateway.charge()` and `inventoryService.reserve()`. You want to verify the order is saved correctly when payment succeeds.
+
+**Task:** Would you use a stub, mock, or spy for `paymentGateway` and `inventoryService`? Why? What would you verify in your test?
+
+**Question:** When does "verify it was called" matter vs "just make it return success"?
+
+**Checkpoint:** User chooses: stub for both if they only care about order persistence (fake success responses). Mock if they need to verify charge was called with correct amount. Spy if they want to assert call count or args after the fact.
+
+---
+
+## Step 4: Design a Test Pyramid for Your Project
+
+<!-- hint:diagram mermaid-type="flowchart" topic="test pyramid distribution" -->
+
+Imagine a small API: user registration, login, and a "list my orders" endpoint. You have limited time.
+
+**Task:** Sketch a test pyramid: how many tests at each layer? What would be your first 5 tests to write?
+
+**Question:** If you could only have 3 tests total, which would you choose and why?
+
+**Checkpoint:** User proposes pyramid: many unit tests for validation, auth logic, order filtering; some integration for DB; 1–2 e2e for critical flows. If only 3: maybe 1 e2e (login + list orders), 1 integration (auth), 1 unit (password validation). Prioritizes highest risk.
+
+---
+
+## Step 5: Avoid Implementation-Detail Assertions
+
+A component fetches users and displays them. Someone writes: "Assert that `useEffect` was called twice."
+
+**Task:** Why is that a bad assertion? What would you assert instead?
+
+**Question:** How do you know if an assertion is testing implementation vs behavior?
+
+**Checkpoint:** User recognizes: useEffect count is implementation; refactoring (e.g., to a different hook) would break the test without changing behavior. Better: assert rendered output (user names on screen) or that the correct API was called. Behavior = what the user sees or what the system does; implementation = how it's built.
+
+---
+
+## Step 6: Place Tests in CI/CD
+
+Your pipeline runs: lint → build → tests → deploy. Tests currently take 12 minutes (unit 2 min, integration 5 min, e2e 5 min).
+
+**Task:** How would you structure the pipeline so developers get fast feedback? What would block a merge vs what could run after?
+
+**Question:** Why might you run e2e only on main, not on every PR?
+
+**Checkpoint:** User suggests: run unit + integration on every PR (7 min); run e2e on merge to main or nightly. Fast feedback for 95% of issues; e2e catches integration bugs less frequently. Cost/speed vs confidence tradeoff.

package/modules/test-strategy/workshop.yaml

@@ -0,0 +1,96 @@
+scenarios:
+  - id: unit-test-tdd
+    title: "Red-Green-Refactor with Unit Tests"
+    difficulty: beginner
+    xp: 30
+    setup:
+      - "mkdir -p workshop && cd workshop"
+      - "npm init -y"
+      - "npm install --save-dev vitest"
+    files:
+      - name: calculator.js
+        content: |
+          function add(a, b) { return 0; }
+          function subtract(a, b) { return 0; }
+          function multiply(a, b) { return 0; }
+          function divide(a, b) { return 0; }
+          module.exports = { add, subtract, multiply, divide };
+        language: javascript
+        readonly: false
+      - name: calculator.test.js
+        content: |
+          const { add, subtract, multiply, divide } = require('./calculator');
+          const assert = require('assert');
+          assert.strictEqual(add(2, 3), 5, 'add(2,3) should be 5');
+          assert.strictEqual(subtract(5, 2), 3, 'subtract(5,2) should be 3');
+          assert.strictEqual(multiply(4, 3), 12, 'multiply(4,3) should be 12');
+          assert.strictEqual(divide(10, 2), 5, 'divide(10,2) should be 5');
+          console.log('All tests passed');
+        language: javascript
+        readonly: true
+    task: "Implement add, subtract, multiply, and divide in calculator.js so that node calculator.test.js prints 'All tests passed'. No test runner—the test file runs directly with node."
+    validations:
+      - label: "All tests passed"
+        check: output-contains
+        pattern: "All tests passed"
+    hints:
+      - "The test file requires add, subtract, multiply, divide from calculator.js. Export them."
+      - "add(a,b) returns a+b. subtract returns a-b, multiply returns a*b, divide returns a/b."
+      - "module.exports = { add, subtract, multiply, divide };"
+    agent_prompts:
+      on_start: "What do the failing tests tell you about what's missing? How would you add the smallest code to make one test pass?"
+
+  - id: integration-test
+    title: "Write Integration Tests for a Service"
+    difficulty: intermediate
+    xp: 40
+    setup:
+      - "mkdir -p workshop && cd workshop"
+      - "npm init -y"
+    files:
+      - name: userService.js
+        content: |
+          const users = new Map([
+            [1, { id: 1, name: 'Alice', email: 'alice@example.com' }],
+            [2, { id: 2, name: 'Bob', email: 'bob@example.com' }],
+          ]);
+          function getUserById(id) {
+            return users.get(id) ?? null;
+          }
+          function getAllUsers() {
+            return Array.from(users.values());
+          }
+          function createUser({ name, email }) {
+            const id = users.size + 1;
+            users.set(id, { id, name, email });
+            return users.get(id);
+          }
+          module.exports = { getUserById, getAllUsers, createUser };
+        language: javascript
+        readonly: true
+      - name: userService.test.js
+        content: |
+          // TODO: Write tests that verify:
+          // 1. getUserById(1) returns a user with name 'Alice'
+          // 2. getAllUsers() returns at least 2 users
+          // 3. createUser({ name: 'Carol', email: 'carol@example.com' }) adds a new user and returns it
+          const { getUserById, getAllUsers, createUser } = require('./userService');
+          const assert = require('assert');
+          // Add your test code here
+          console.log('Tests not yet implemented');
+        language: javascript
+        readonly: false
+    task: "Implement the tests in userService.test.js. Use assert.strictEqual (or similar) to verify getUserById, getAllUsers, and createUser. Run node userService.test.js—it should print that tests passed."
+    validations:
+      - label: "Tests pass and userService.test.js was modified"
+        check: file-changed
+        pattern: "userService.test.js"
+      - label: "Output indicates passing tests"
+        check: output-contains
+        pattern: "pass"
+    hints:
+      - "Call getUserById(1) and assert the returned object has name 'Alice'."
+      - "getAllUsers() returns an array. Assert its length is >= 2."
+      - "createUser returns the new user. Assert it has name and email. Run tests with node userService.test.js."
+    agent_prompts:
+      on_start: "What does the service do? If you were a developer integrating with it, what would you want to verify works?"

package/modules/typescript-fundamentals/content.md

@@ -0,0 +1,127 @@
+# TypeScript — Types That Catch Bugs Before Runtime
+
+## What is TypeScript?
+
+TypeScript is JavaScript with static typing. A compiler checks types at build time; invalid code fails before it runs.
+
+**JavaScript (runtime error):**
+```javascript
+function greet(name) {
+  return name.toUpperCase();
+}
+greet(42);  // Runtime: name.toUpperCase is not a function
+```
+
+**TypeScript (compile-time error):**
+```typescript
+function greet(name: string) {
+  return name.toUpperCase();
+}
+greet(42);  // Error: Argument of type 'number' is not assignable to parameter of type 'string'
+```
+
+## Basic Types
+
+```typescript
+let n: number = 42;
+let s: string = "hello";
+let b: boolean = true;
+let arr: number[] = [1, 2, 3];
+let tuple: [string, number] = ["a", 1];
+let nothing: void = undefined;
+```
+
+TypeScript infers types when you assign directly, so explicit annotations are often optional.
+
+## Interfaces
+
+Define object shapes:
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  email?: string;  // optional
+}
+const u: User = { id: 1, name: "Alice" };
+```
+
+Interfaces support inheritance and declaration merging.
+
+## Type Aliases
+
+Alternative to interfaces for object shapes and unions:
+
+```typescript
+type ID = string | number;
+type Point = { x: number; y: number };
+```
+
+## Unions
+
+A value can be one of several types:
+
+```typescript
+type Status = "pending" | "success" | "error";
+function handle(s: Status) { /* ... */ }
+```
+
+## Generics
+
+Reusable types parameterized by other types:
+
+```typescript
+function identity<T>(x: T): T {
+  return x;
+}
+const n = identity(42);   // T inferred as number
+const s = identity("hi"); // T inferred as string
+```
+
+```typescript
+interface Box<T> {
+  value: T;
+}
+const box: Box<number> = { value: 42 };
+```
+
+## Type Narrowing
+
+Narrow types with conditionals so TypeScript knows the type in each branch:
+
+```typescript
+function padLeft(value: string | number): string {
+  if (typeof value === "number") {
+    return " ".repeat(value);  // value is number here
+  }
+  return value;  // value is string here
+}
+```
+
+Common narrowing: `typeof`, `instanceof`, `in`, discriminated unions.
+
+## Utility Types
+
+Built-in helpers:
+
+| Type | Purpose |
+|------|---------|
+| `Partial<T>` | All properties optional |
+| `Required<T>` | All properties required |
+| `Pick<T, K>` | Select specific keys |
+| `Omit<T, K>` | Exclude specific keys |
+| `Record<K, V>` | Map keys to value type |
+
+```typescript
+type UserUpdate = Partial<User>;  // All fields optional
+type NameOnly = Pick<User, 'name'>;
+```
+
+## When Types Catch Bugs
+
+| JS Bug | TS Catches It |
+|--------|----------------|
+| `undefined` property access | Strict null checks |
+| Wrong argument type | Function parameter types |
+| Typo in property name | Object shape checking |
+| Missing required field | Interface compliance |

package/modules/typescript-fundamentals/exercises.md

@@ -0,0 +1,79 @@
+# TypeScript Exercises
+
+## Exercise 1: Typed API Response
+
+**Task:** Define an interface `ApiResponse<T>` with `data: T`, `status: number`, and `message?: string`. Create a `User` interface and type a variable as `ApiResponse<User>`.
+
+**Validation:**
+- [ ] ApiResponse is generic over the data shape
+- [ ] status is required, message is optional
+- [ ] Compiler catches missing or wrong-typed fields
+
+**Hints:**
+1. `interface ApiResponse<T> { data: T; ... }`
+2. Use `?` for optional properties
+3. `ApiResponse<User>` means T = User
+
+---
+
+## Exercise 2: Discriminated Union
+
+**Task:** Create a type `Result` that is either `{ kind: 'ok'; value: number }` or `{ kind: 'error'; message: string }`. Write a function `unwrap(r: Result): number` that returns the value or throws the message.
+
+**Validation:**
+- [ ] Function uses `r.kind` to narrow
+- [ ] In the 'ok' branch, `r.value` is accessible
+- [ ] In the 'error' branch, `r.message` is accessible
+
+**Hints:**
+1. `type Result = OkResult | ErrorResult` with shared `kind`
+2. `if (r.kind === 'ok') return r.value;`
+3. Discriminated unions narrow on a common literal field
+
+---
+
+## Exercise 3: Generic Map Function
+
+**Task:** Implement `map<T, U>(arr: T[], fn: (item: T) => U): U[]` — the standard array map. Ensure the types flow correctly from input to output.
+
+**Validation:**
+- [ ] `map([1,2,3], x => x * 2)` returns `number[]`
+- [ ] `map(["a","b"], s => s.length)` returns `number[]`
+- [ ] Wrong callback signature is rejected
+
+**Hints:**
+1. Two type parameters: T for input, U for output
+2. `fn` takes `T` and returns `U`
+3. Return type is `U[]`
+
+---
+
+## Exercise 4: Strict Null Safety
+
+**Task:** Enable strict null checks (if not already). Write a function `getLength(s: string | null): number` that returns 0 for null and the length otherwise. Don't use non-null assertion (`!`).
+
+**Validation:**
+- [ ] `getLength(null)` returns 0
+- [ ] `getLength("hi")` returns 2
+- [ ] No `!` used; narrowing handles null
+
+**Hints:**
+1. `if (s === null) return 0;`
+2. After the check, `s` is narrowed to string
+3. Or use ternary: `s ? s.length : 0`
+
+---
+
+## Exercise 5: Pick and Omit
+
+**Task:** Given `interface Config { apiUrl: string; timeout: number; secret: string }`, create a type `PublicConfig` that excludes `secret` using `Omit`. Create `TimeoutOnly` using `Pick` with just `timeout`.
+
+**Validation:**
+- [ ] PublicConfig has apiUrl and timeout, not secret
+- [ ] TimeoutOnly has only timeout
+- [ ] Uses built-in utility types
+
+**Hints:**
+1. `Omit<Config, 'secret'>`
+2. `Pick<Config, 'timeout'>`
+3. Can combine: `Pick<Omit<Config, 'secret'>, 'apiUrl'>`

package/modules/typescript-fundamentals/game.yaml

@@ -0,0 +1,111 @@
+games:
+  - type: speed-round
+    title: "Type This!"
+    rounds:
+      - question: "An array of strings. What's the type?"
+        options:
+          - "Array<string>"
+          - "string[]"
+          - "string Array"
+          - "[]string"
+        answer: 1
+        timeLimit: 12
+      - question: "A function that takes a number and returns a boolean. What's the type?"
+        options:
+          - "function number -> boolean"
+          - "(n: number) => boolean"
+          - "NumberBoolean"
+          - "Function<number, boolean>"
+        answer: 1
+        timeLimit: 16
+      - question: "An object with keys that can be any string, and values that are numbers. What's the type?"
+        options:
+          - "object"
+          - "Record<string, number>"
+          - "{ [key: string]: number }"
+          - "Map<string, number>"
+        answer: 1
+        timeLimit: 16
+      - question: "A value that can be either a string or null. What's the type?"
+        options:
+          - "string | null"
+          - "string | undefined"
+          - "string?"
+          - "optional string"
+        answer: 0
+        timeLimit: 14
+      - question: "A Promise that resolves to a User object. What's the type?"
+        options:
+          - "Promise User"
+          - "Promise<User>"
+          - "async User"
+          - "User | Promise"
+        answer: 1
+        timeLimit: 14
+      - question: "A tuple with exactly [string, number] in that order. What's the type?"
+        options:
+          - "Array<string | number>"
+          - "[string, number]"
+          - "tuple string number"
+          - "(string, number)"
+        answer: 1
+        timeLimit: 14
+      - question: "A function with no parameters that returns void. What's the type?"
+        options:
+          - "() => void"
+          - "void"
+          - "function void"
+          - "()void"
+        answer: 0
+        timeLimit: 12
+      - question: "A union of string literals: 'pending' | 'success' | 'error'. What's the type?"
+        options:
+          - "string"
+          - "'pending' | 'success' | 'error'"
+          - "enum Status"
+          - "Status"
+        answer: 1
+        timeLimit: 16
+      - question: "A generic type that wraps any type T. What's the type for a box containing a number?"
+        options:
+          - "Box number"
+          - "Box<number>"
+          - "Generic<number>"
+          - "T<number>"
+        answer: 1
+        timeLimit: 14
+      - question: "A readonly array that cannot be mutated. What's the type?"
+        options:
+          - "array"
+          - "ReadonlyArray<string>"
+          - "const string[]"
+          - "immutable string[]"
+        answer: 1
+        timeLimit: 16
+
+  - type: classify
+    title: "Type vs Interface"
+    categories:
+      - name: "type alias"
+        color: "#58a6ff"
+      - name: "interface"
+        color: "#3fb950"
+      - name: "either works"
+        color: "#8b949e"
+    items:
+      - text: "A union type: string | number."
+        category: "type alias"
+      - text: "An object shape that will be extended by other types (extends)."
+        category: "interface"
+      - text: "A simple object shape with a few properties, no extension planned."
+        category: "either works"
+      - text: "A mapped type: { [K in keyof T]: T[K] }."
+        category: "type alias"
+      - text: "Declaration merging needed (e.g. augmenting a library's types)."
+        category: "interface"
+      - text: "A primitive alias: type ID = string."
+        category: "type alias"
+      - text: "An intersection type: A & B."
+        category: "type alias"
+      - text: "A class-implementable contract (class Foo implements Bar)."
+        category: "either works"

package/modules/typescript-fundamentals/module.yaml

@@ -0,0 +1,45 @@
+slug: typescript-fundamentals
+title: "TypeScript — Types That Catch Bugs Before Runtime"
+version: 1.0.0
+description: "Add static typing to JavaScript — interfaces, generics, and type narrowing."
+category: languages
+tags: [typescript, javascript, types, static-analysis, generics]
+difficulty: beginner
+
+xp:
+  read: 10
+  walkthrough: 30
+  exercise: 20
+  quiz: 15
+  quiz-perfect-bonus: 10
+  game: 20
+  game-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 15
+  guided: 45
+
+prerequisites: []
+related: [react-fundamentals, clean-code]
+
+triggers:
+  - "What is TypeScript?"
+  - "How do I add types to JavaScript?"
+  - "What are generics in TypeScript?"
+  - "How do interfaces work in TypeScript?"
+
+visuals:
+  diagrams: [diagram-mermaid]
+  quiz-types: [quiz-fill-blank, quiz-timed-choice]
+  game-types: [speed-round, classify]
+  playground: javascript
+  web-embeds: true
+
+sources:
+  - url: "https://www.typescriptlang.org/docs/"
+    label: "TypeScript Docs"
+    type: docs
+  - url: "https://www.typescriptlang.org/play"
+    label: "TypeScript Playground"
+    type: docs

package/modules/typescript-fundamentals/quick-ref.md

@@ -0,0 +1,55 @@
+# TypeScript Quick Reference
+
+## Basic Types
+
+| Syntax | Meaning |
+|--------|---------|
+| `string`, `number`, `boolean` | Primitives |
+| `string[]`, `Array<number>` | Arrays |
+| `[string, number]` | Tuple |
+| `string \| number` | Union |
+| `?` on property | Optional |
+| `T \| null` | Nullable |
+
+## Interfaces vs Types
+
+| | interface | type |
+|---|-----------|------|
+| Extends | `extends` | `&` (intersection) |
+| Union | No | `A \| B` |
+| Declaration merge | Yes | No |
+
+## Generics
+
+```typescript
+function fn<T>(x: T): T { return x; }
+type Box<T> = { value: T };
+```
+
+## Narrowing
+
+| Guard | Example |
+|-------|---------|
+| `typeof` | `typeof x === 'string'` |
+| `instanceof` | `x instanceof Date` |
+| `in` | `'key' in obj` |
+| Discriminated union | `obj.kind === 'ok'` |
+
+## Utility Types
+
+| Type | Result |
+|------|--------|
+| `Partial<T>` | All optional |
+| `Required<T>` | All required |
+| `Pick<T, K>` | Only K keys |
+| `Omit<T, K>` | Exclude K keys |
+| `Record<K, V>` | Map K → V |
+
+## Decision: When to Add Types
+
+| Scenario | Approach |
+|----------|----------|
+| Function params/return | Explicit or inferred |
+| Object shapes | Interface or type |
+| Reusable structures | Generics |
+| External API | Declare module or use `unknown` |