@shaykec/bridge 0.4.24 → 0.4.26

package/modules/design-patterns/content.md

@@ -0,0 +1,335 @@
+# Design Patterns — Factory, Observer, Strategy, and Friends
+
+<!-- hint:slides topic="Six essential design patterns: Singleton, Factory, Observer, Strategy, Decorator, Adapter — when and why to use each" slides="7" -->
+
+Six essential design patterns with practical TypeScript examples and Mermaid class diagrams.
+
+## 1. Singleton
+
+**Problem:** Ensure a class has exactly one instance globally.
+
+**Solution:** Private constructor, static `getInstance()` that returns the shared instance.
+
+```typescript
+class Database {
+  private static instance: Database;
+
+  private constructor() {}
+
+  static getInstance(): Database {
+    if (!Database.instance) {
+      Database.instance = new Database();
+    }
+    return Database.instance;
+  }
+
+  query(sql: string) { /* ... */ }
+}
+```
+
+```mermaid
+classDiagram
+    class Database {
+        -static instance: Database
+        -constructor()
+        +static getInstance() Database
+        +query(sql: string)
+    }
+```
+
+**Tradeoff:** Simplifies access but creates global state; can complicate testing.
+
+---
+
+## 2. Factory
+
+**Problem:** Object creation depends on configuration or runtime type; callers shouldn't know creation details.
+
+**Solution:** Centralize creation in a factory function or class.
+
+```typescript
+type NotificationType = 'email' | 'sms' | 'push';
+
+interface Notification {
+  send(message: string): void;
+}
+
+class EmailNotification implements Notification {
+  send(message: string) { /* ... */ }
+}
+
+class SmsNotification implements Notification {
+  send(message: string) { /* ... */ }
+}
+
+function createNotification(type: NotificationType): Notification {
+  switch (type) {
+    case 'email': return new EmailNotification();
+    case 'sms': return new SmsNotification();
+    default: throw new Error(`Unknown type: ${type}`);
+  }
+}
+```
+
+```mermaid
+classDiagram
+    class Notification {
+        <<interface>>
+        +send(message: string)
+    }
+    class EmailNotification {
+        +send(message: string)
+    }
+    class SmsNotification {
+        +send(message: string)
+    }
+    class createNotification {
+        +createNotification(type) Notification
+    }
+    Notification <|.. EmailNotification
+    Notification <|.. SmsNotification
+    createNotification ..> Notification : creates
+```
+
+---
+
+## 3. Observer
+
+**Problem:** Multiple objects need to react when another object changes. Loose coupling is required.
+
+**Solution:** Subject holds a list of subscribers; when state changes, it notifies all of them.
+
+```typescript
+type Listener<T> = (data: T) => void;
+
+class Subject<T> {
+  private listeners: Set<Listener<T>> = new Set();
+
+  subscribe(fn: Listener<T>): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  notify(data: T): void {
+    this.listeners.forEach(fn => fn(data));
+  }
+}
+
+// Usage: form.notify({ email, submitted: true })
+```
+
+```mermaid
+classDiagram
+    class Subject {
+        -listeners: Set
+        +subscribe(fn)
+        +notify(data)
+    }
+    class Observer {
+        <<interface>>
+        +update(data)
+    }
+    Subject --> Observer : notifies
+```
+
+---
+
+## 4. Strategy
+
+**Problem:** Multiple algorithms for the same task; want to switch at runtime without changing the client.
+
+**Solution:** Extract each algorithm into a strategy object; client holds a strategy and delegates.
+
+```mermaid
+classDiagram
+    class Context {
+        -strategy: Strategy
+        +setStrategy(s: Strategy)
+        +execute()
+    }
+    class Strategy {
+        <<interface>>
+        +execute()
+    }
+    class ConcreteStrategyA {
+        +execute()
+    }
+    class ConcreteStrategyB {
+        +execute()
+    }
+    Context --> Strategy : uses
+    Strategy <|.. ConcreteStrategyA
+    Strategy <|.. ConcreteStrategyB
+```
+
+```typescript
+interface PaymentStrategy {
+  pay(amount: number): boolean;
+}
+
+class CreditCardStrategy implements PaymentStrategy {
+  pay(amount: number) { /* ... */ return true; }
+}
+
+class PayPalStrategy implements PaymentStrategy {
+  pay(amount: number) { /* ... */ return true; }
+}
+
+class PaymentProcessor {
+  constructor(private strategy: PaymentStrategy) {}
+
+  setStrategy(s: PaymentStrategy) { this.strategy = s; }
+
+  execute(amount: number) {
+    return this.strategy.pay(amount);
+  }
+}
+```
+
+```mermaid
+classDiagram
+    class PaymentStrategy {
+        <<interface>>
+        +pay(amount: number)
+    }
+    class CreditCardStrategy {
+        +pay(amount: number)
+    }
+    class PayPalStrategy {
+        +pay(amount: number)
+    }
+    class PaymentProcessor {
+        -strategy: PaymentStrategy
+        +setStrategy(s)
+        +execute(amount)
+    }
+    PaymentStrategy <|.. CreditCardStrategy
+    PaymentStrategy <|.. PayPalStrategy
+    PaymentProcessor --> PaymentStrategy : delegates
+```
+
+---
+
+## 5. Decorator
+
+**Problem:** Add behavior to an object without subclassing; behavior should be stackable.
+
+**Solution:** Wrap the object in a decorator that adds behavior and delegates to the wrapped object.
+
+```typescript
+interface Logger {
+  log(msg: string): void;
+}
+
+class ConsoleLogger implements Logger {
+  log(msg: string) { console.log(msg); }
+}
+
+class TimestampDecorator implements Logger {
+  constructor(private inner: Logger) {}
+
+  log(msg: string) {
+    this.inner.log(`[${new Date().toISOString()}] ${msg}`);
+  }
+}
+
+class LevelDecorator implements Logger {
+  constructor(private inner: Logger, private level: string) {}
+
+  log(msg: string) {
+    this.inner.log(`[${this.level}] ${msg}`);
+  }
+}
+
+// Usage: new TimestampDecorator(new LevelDecorator(new ConsoleLogger(), 'INFO'))
+```
+
+```mermaid
+classDiagram
+    class Logger {
+        <<interface>>
+        +log(msg: string)
+    }
+    class ConsoleLogger {
+        +log(msg: string)
+    }
+    class TimestampDecorator {
+        -inner: Logger
+        +log(msg: string)
+    }
+    class LevelDecorator {
+        -inner: Logger
+        -level: string
+        +log(msg: string)
+    }
+    Logger <|.. ConsoleLogger
+    Logger <|.. TimestampDecorator
+    Logger <|.. LevelDecorator
+    TimestampDecorator --> Logger : wraps
+    LevelDecorator --> Logger : wraps
+```
+
+---
+
+## 6. Adapter
+
+**Problem:** An existing class has the wrong interface for your needs (e.g., callback-based API, third-party library).
+
+**Solution:** Create an adapter that implements your target interface and delegates to the adaptee.
+
+```typescript
+function fetchDataLegacy(callback: (err: Error | null, data?: string) => void): void {
+  setTimeout(() => callback(null, 'result'), 100);
+}
+
+function adaptToPromise<T>(
+  fn: (cb: (err: Error | null, data?: T) => void) => void
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    fn((err, data) => err ? reject(err) : resolve(data as T));
+  });
+}
+
+// Usage: const data = await adaptToPromise(fetchDataLegacy);
+```
+
+```mermaid
+classDiagram
+    class Target {
+        <<interface>>
+        +getData() Promise
+    }
+    class Adapter {
+        -adaptee: Adaptee
+        +getData() Promise
+    }
+    class Adaptee {
+        +fetch(callback)
+    }
+    Target <|.. Adapter
+    Adapter --> Adaptee : delegates
+```
+
+---
+
+## Decision Flow
+
+| Need | Pattern |
+|------|---------|
+| Same instance everywhere | Singleton |
+| Create objects by type/config | Factory |
+| Notify listeners on change | Observer |
+| Swap algorithm at runtime | Strategy |
+| Add behavior without subclassing | Decorator |
+| Use legacy or wrong API | Adapter |
+
+---
+
+## Key Takeaways
+
+1. **Singleton** — One instance; watch out for global state and testing.
+2. **Factory** — Centralize creation; open for new types, closed for modification.
+3. **Observer** — Loose coupling; subject notifies subscribers.
+4. **Strategy** — Pluggable algorithms; client delegates to strategy.
+5. **Decorator** — Wrap and delegate; stack decorators for layered behavior.
+6. **Adapter** — Translate interfaces; no behavior change, just interface.

package/modules/design-patterns/exercises.md

@@ -0,0 +1,82 @@
+# Design Patterns Exercises
+
+## Exercise 1: Strategy — Sorting
+
+**Task:** Implement a `Sorter` that uses a pluggable sort strategy. Provide `BubbleSort` and `QuickSort` strategies. The Sorter should have `sort(arr)` and `setStrategy(s)`.
+
+**Validation:**
+- [ ] Sorter delegates to strategy
+- [ ] Can switch strategies at runtime
+- [ ] Both strategies produce correct output
+
+**Hints:**
+1. interface SortStrategy { sort(arr: number[]): number[] }
+2. Sorter holds strategy, calls strategy.sort(arr)
+3. setStrategy replaces the current strategy
+
+---
+
+## Exercise 2: Factory — Shape Creation
+
+**Task:** Create a `ShapeFactory.create(type: 'circle' | 'square' | 'triangle')` that returns the appropriate shape object. Each shape has `area()` and `perimeter()`.
+
+**Validation:**
+- [ ] Factory returns correct type for each input
+- [ ] Invalid type throws or returns null
+- [ ] Adding a new shape requires only a new case, not changes to callers
+
+**Hints:**
+1. interface Shape { area(): number; perimeter(): number }
+2. switch (type) { case 'circle': return new Circle(...) }
+3. Consider default for unknown type
+
+---
+
+## Exercise 3: Observer — Event Bus
+
+**Task:** Build an `EventBus` with `on(event, handler)`, `off(event, handler)`, and `emit(event, data)`. Support multiple handlers per event. Test with at least 2 events and 2 handlers on one event.
+
+**Validation:**
+- [ ] Handlers are called on emit
+- [ ] off removes the correct handler
+- [ ] Multiple handlers work
+- [ ] Same handler can be on multiple events
+
+**Hints:**
+1. Map<event, Set<handler>>
+2. emit: get handlers, call each with data
+3. off: remove from Set
+
+---
+
+## Exercise 4: Decorator — Caching
+
+**Task:** Create a `CachedFunction` decorator that wraps any async function `(x) => Promise<y>` and caches results by input. Same input returns cached value without calling the inner function.
+
+**Validation:**
+- [ ] First call invokes inner function
+- [ ] Second call with same input returns cache
+- [ ] Different inputs call inner function
+- [ ] Decorator is reusable for any async function
+
+**Hints:**
+1. type Fn = (x: T) => Promise<U>
+2. const cache = new Map<T, U>()
+3. if (cache.has(x)) return cache.get(x)!; const r = await fn(x); cache.set(x, r); return r
+
+---
+
+## Exercise 5: Adapter — Old API to New
+
+**Task:** You have `LegacyStorage.getItem(key, callback)` and `LegacyStorage.setItem(key, value, callback)`. Create an adapter with `async get(key): Promise<string | null>` and `async set(key, value): Promise<void>`.
+
+**Validation:**
+- [ ] Adapter wraps LegacyStorage
+- [ ] get/set return Promises
+- [ ] Callbacks are correctly translated to Promise resolve
+- [ ] Errors in callback reject the Promise
+
+**Hints:**
+1. new Promise((resolve, reject) => legacy.getItem(key, (err, val) => err ? reject(err) : resolve(val)))
+2. Same pattern for setItem
+3. Wrap both in a class or object

package/modules/design-patterns/game.yaml

@@ -0,0 +1,55 @@
+games:
+  - type: memory-match
+    title: "Pattern Pairs"
+    pairs:
+      - term: "Factory"
+        definition: "Creates objects without specifying exact class"
+      - term: "Observer"
+        definition: "Notifies dependents of state changes"
+      - term: "Strategy"
+        definition: "Swaps algorithms at runtime"
+      - term: "Singleton"
+        definition: "Single instance globally"
+      - term: "Adapter"
+        definition: "Wraps incompatible interface"
+      - term: "Decorator"
+        definition: "Adds behavior without subclassing"
+      - term: "Loose Coupling"
+        definition: "Minimal dependencies between components"
+      - term: "Gang of Four"
+        definition: "Original design pattern catalog authors"
+
+  - type: classify
+    title: "Pattern Sorter"
+    categories:
+      - name: Creational
+        color: "#58a6ff"
+      - name: Structural
+        color: "#3fb950"
+      - name: Behavioral
+        color: "#d29922"
+    items:
+      - text: "Factory"
+        category: "Creational"
+      - text: "Singleton"
+        category: "Creational"
+      - text: "Builder"
+        category: "Creational"
+      - text: "Adapter"
+        category: "Structural"
+      - text: "Decorator"
+        category: "Structural"
+      - text: "Proxy"
+        category: "Structural"
+      - text: "Observer"
+        category: "Behavioral"
+      - text: "Strategy"
+        category: "Behavioral"
+      - text: "Command"
+        category: "Behavioral"
+      - text: "Iterator"
+        category: "Behavioral"
+      - text: "Template Method"
+        category: "Behavioral"
+      - text: "Composite"
+        category: "Structural"

package/modules/design-patterns/module.yaml

@@ -0,0 +1,45 @@
+slug: design-patterns
+title: "Design Patterns — Factory, Observer, Strategy, and Friends"
+version: 1.0.0
+description: "Learn six essential design patterns with practical TypeScript examples."
+category: fundamentals
+tags: [design-patterns, oop, architecture, gang-of-four, software-design]
+difficulty: intermediate
+
+xp:
+  read: 15
+  walkthrough: 40
+  exercise: 25
+  quiz: 20
+  quiz-perfect-bonus: 10
+  game: 25
+  game-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 25
+  guided: 60
+
+prerequisites: [solid-principles]
+related: [clean-code, system-design]
+
+triggers:
+  - "What are design patterns?"
+  - "When should I use the Factory pattern?"
+  - "What is the Observer pattern?"
+  - "How do I choose the right design pattern?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-architecture]
+  quiz-types: [quiz-matching, quiz-timed-choice]
+  game-types: [memory-match, classify]
+  playground: javascript
+  slides: true
+
+sources:
+  - url: "https://refactoring.guru/design-patterns"
+    label: "Refactoring Guru"
+    type: docs
+  - url: "https://www.oreilly.com/library/view/head-first-design/0596007124/"
+    label: "Head First Design Patterns"
+    type: docs

package/modules/design-patterns/quick-ref.md

@@ -0,0 +1,44 @@
+# Design Patterns Quick Reference
+
+## Pattern Overview
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Singleton | One instance | Static getInstance, private constructor |
+| Factory | Creation by type/config | Centralized creation function |
+| Observer | One-to-many updates | Subscribe/notify |
+| Strategy | Pluggable algorithm | Delegate to strategy object |
+| Decorator | Stackable behavior | Wrap and delegate |
+| Adapter | Interface mismatch | Translate interface |
+
+## When to Use
+
+| Need | Pattern |
+|------|---------|
+| Same instance everywhere | Singleton |
+| Create X based on input | Factory |
+| Notify listeners on change | Observer |
+| Swap algorithm at runtime | Strategy |
+| Add behavior without subclassing | Decorator |
+| Use legacy/wrong API | Adapter |
+
+## Key Code Shapes
+
+**Strategy:** Client holds strategy, calls strategy.do()
+
+**Observer:** Subject has subscribe/emit; observers register callbacks
+
+**Decorator:** Wraps inner, adds behavior, delegates
+
+**Adapter:** Implements target interface, delegates to adaptee
+
+## Decision Flow
+
+```
+Creation logic? → Factory
+One instance? → Singleton
+Notify many? → Observer
+Switch algorithm? → Strategy
+Add behavior? → Decorator
+Wrong interface? → Adapter
+```

package/modules/design-patterns/quiz.md

@@ -0,0 +1,101 @@
+# Design Patterns Quiz
+
+## Question 1
+
+When would you use the Factory pattern?
+
+A) When you need exactly one instance
+B) When object creation depends on configuration or runtime type
+C) When you need to observe changes
+D) When you want to add behavior to an object
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Factory centralizes creation logic. Use it when you need to create different concrete types based on config, type string, or other runtime input, without exposing the creation details to callers. -->
+
+## Question 2
+
+What is the main benefit of the Observer pattern?
+
+A) Better performance
+B) Loose coupling between publisher and subscribers
+C) Single instance guarantee
+D) Easier debugging
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Observer decouples the subject (publisher) from its observers (subscribers). The subject doesn't need to know who is listening. Subscribers can be added/removed at runtime. -->
+
+## Question 3
+
+The Strategy pattern is useful when:
+
+A) You need multiple instances of the same class
+B) You want to switch algorithms at runtime without changing the client
+C) You need to wrap an object with extra behavior
+D) You have an interface mismatch
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Strategy extracts algorithms into interchangeable objects. The client holds a strategy and delegates to it. You can swap strategies at runtime (e.g., different sort algorithms, payment methods). -->
+
+## Question 4
+
+How does the Decorator pattern add behavior?
+
+A) By subclassing
+B) By wrapping an object and delegating to it
+C) By replacing the object
+D) By using global state
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Decorator wraps the original object, adds its own behavior, and delegates to the wrapped object. Multiple decorators can stack (DecoratorA(DecoratorB(Core))). -->
+
+## Question 5
+
+When do you use the Adapter pattern?
+
+A) When you want to optimize performance
+B) When an existing class has the wrong interface for your needs
+C) When you need a single instance
+D) When you want to observe changes
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Adapter translates between your expected interface and the existing class's interface. Use it when integrating legacy code, third-party libraries, or mismatched APIs. -->
+
+## Question 6
+
+What is a downside of the Singleton pattern?
+
+A) It's hard to implement
+B) It can make testing difficult due to global state
+C) It only works in single-threaded environments
+D) It violates encapsulation
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Singleton creates global state. In tests, you often want fresh or mock instances. With Singleton, you may need reset logic or dependency injection of the instance to test effectively. -->
+
+## Question 7
+
+<!-- VISUAL: matching -->
+
+Match each design pattern to its typical use case:
+
+A) Factory → 1) Integrating a third-party API with a different interface
+B) Observer → 2) Creating different UI components based on OS (Windows/Mac)
+C) Adapter → 3) Event system where subscribers react to publisher changes
+D) Strategy → 4) Swapping sort algorithms (quick vs merge) at runtime
+
+<!-- ANSWER: A2,B3,C1,D4 -->
+<!-- EXPLANATION: Factory creates objects based on config/type (2). Observer decouples publisher from subscribers (3). Adapter translates interfaces (1). Strategy swaps algorithms (4). -->
+
+## Question 8
+
+<!-- VISUAL: matching -->
+
+Match each pattern to its structural characteristic:
+
+A) Decorator → 1) Wraps object, delegates to inner object, adds behavior
+B) Singleton → 2) Single instance, global access
+C) Strategy → 3) Context holds algorithm object, delegates to it
+D) Observer → 4) Subject maintains list of observers, notifies on change
+
+<!-- ANSWER: A1,B2,C3,D4 -->
+<!-- EXPLANATION: Decorator wraps and delegates (1). Singleton is single-instance (2). Strategy holds and delegates to strategy object (3). Observer has subject-observer list (4). -->

package/modules/design-patterns/resources.md

@@ -0,0 +1,40 @@
+# Design Patterns — Resources
+
+## Videos
+
+- [Design Patterns in 5 Minutes](https://www.youtube.com/watch?v=tv-_1er1mWI) — Fireship. Quick overview.
+- [Design Patterns Course](https://www.youtube.com/watch?v=NU_1StN5Tkk) — freeCodeCamp. Full course.
+- [Christopher Okhravi — Design Patterns](https://www.youtube.com/playlist?list=PLrhzvIcii6GNjpARdnO4ueTUAVR9eMBpc) — Detailed pattern explanations.
+
+## Articles and Readings
+
+- [Refactoring Guru — Design Patterns](https://refactoring.guru/design-patterns) — Catalog with examples and diagrams.
+- [Patterns.dev](https://www.patterns.dev/) — Modern JS/React patterns.
+- [SourceMaking](https://sourcemaking.com/design_patterns) — Patterns with UML and code.
+
+## Books
+
+- **Head First Design Patterns** by Freeman & Freeman — Accessible intro with visuals.
+- **Design Patterns: Elements of Reusable OOP** by Gang of Four — Original reference.
+- **Refactoring to Patterns** by Joshua Kerievsky — When and how to introduce patterns.
+
+## Tools
+
+- [TypeScript Design Patterns](https://github.com/torokmark/design_patterns_in_typescript) — TS implementations.
+- [Mermaid Diagrams](https://mermaid.js.org/) — Class and sequence diagrams for patterns.
+
+## Podcasts
+
+- [Software Engineering Radio — Design Patterns](https://www.se-radio.net/) — Technical episodes on applying patterns in real projects.
+- [Coding Blocks — Design Patterns Series](https://www.codingblocks.net/) — Multi-episode deep dives into Gang of Four patterns.
+
+## Interactive and Visual
+
+- [Refactoring Guru — Design Patterns](https://refactoring.guru/design-patterns) — Interactive catalog with visual diagrams, code examples in 10 languages, and real-world analogies.
+- [Patterns.dev](https://www.patterns.dev/) — Addy Osmani & Lydia Hallie. Visual, modern JS/React patterns with animated examples.
+- [Design Patterns Card](https://www.mcdonaldland.info/2007/11/28/40/) — Printable reference card for quick pattern lookup.
+
+## Courses
+
+- [freeCodeCamp — Design Patterns for Humans](https://github.com/kamranahmedse/design-patterns-for-humans) — Plain-English explanation of every GoF pattern with real-world analogies.
+- [Coursera — Design Patterns (University of Alberta)](https://www.coursera.org/learn/design-patterns) — Free to audit course covering creational, structural, and behavioral patterns.