memory-journal-mcp 7.0.1 → 7.2.0

package/skills/typescript/references/type-system.md

@@ -0,0 +1,481 @@
+# TypeScript Type System Reference
+
+> **Load when:** User asks about type annotations, interfaces vs types, unions, intersections, or type system fundamentals.
+
+Complete guide to TypeScript's structural type system.
+
+## Contents
+
+- [Type Annotations](#type-annotations)
+- [Interfaces vs Type Aliases](#interfaces-vs-type-aliases)
+- [Union and Intersection Types](#union-and-intersection-types)
+- [Literal Types](#literal-types)
+- [Type Guards and Narrowing](#type-guards-and-narrowing)
+- [The satisfies Operator](#the-satisfies-operator)
+
+---
+
+## Type Annotations
+
+### Variable Annotations
+
+```typescript
+// Explicit type annotations
+const name: string = 'Alice'
+const age: number = 30
+const active: boolean = true
+
+// Type inference (preferred when obvious)
+const inferredName = 'Bob' // TypeScript infers string
+const inferredAge = 25 // TypeScript infers number
+
+// Arrays
+const numbers: number[] = [1, 2, 3]
+const strings: Array<string> = ['a', 'b', 'c']
+
+// Tuples (fixed-length arrays with specific types)
+const pair: [string, number] = ['age', 30]
+const triple: [string, number, boolean] = ['name', 1, true]
+```
+
+### Function Annotations
+
+```typescript
+// Function with typed parameters and return
+function greet(name: string): string {
+  return `Hello, ${name}!`
+}
+
+// Arrow function
+const add = (a: number, b: number): number => a + b
+
+// Optional parameters
+function greetOptional(name: string, greeting?: string): string {
+  return `${greeting ?? 'Hello'}, ${name}!`
+}
+
+// Default parameters
+function greetDefault(name: string, greeting: string = 'Hello'): string {
+  return `${greeting}, ${name}!`
+}
+
+// Rest parameters
+function sum(...numbers: number[]): number {
+  return numbers.reduce((a, b) => a + b, 0)
+}
+
+// Function type alias
+type Comparator<T> = (a: T, b: T) => number
+const numberCompare: Comparator<number> = (a, b) => a - b
+```
+
+---
+
+## Interfaces vs Type Aliases
+
+### When to Use Interfaces
+
+```typescript
+// Interfaces are ideal for object shapes
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+// Interfaces can be extended
+interface Employee extends User {
+  employeeId: string
+  department: string
+}
+
+// Interfaces can be implemented by classes
+class Manager implements Employee {
+  constructor(
+    public id: string,
+    public name: string,
+    public email: string,
+    public employeeId: string,
+    public department: string
+  ) {}
+}
+
+// Declaration merging (interfaces only)
+interface Config {
+  apiUrl: string
+}
+
+interface Config {
+  timeout: number
+}
+
+// Config now has both apiUrl and timeout
+```
+
+### When to Use Type Aliases
+
+```typescript
+// Type aliases for unions
+type Status = 'pending' | 'approved' | 'rejected'
+
+// Type aliases for complex types
+type Handler = (event: Event) => void
+
+// Type aliases for mapped types
+type Nullable<T> = { [K in keyof T]: T[K] | null }
+
+// Type aliases for conditional types
+type NonNullable<T> = T extends null | undefined ? never : T
+
+// Type aliases for tuples
+type Point = [x: number, y: number]
+type RGB = [red: number, green: number, blue: number]
+```
+
+### Decision Guide
+
+| Use Case          | Prefer      |
+| ----------------- | ----------- |
+| Object shapes     | `interface` |
+| Extending objects | `interface` |
+| Class contracts   | `interface` |
+| Union types       | `type`      |
+| Tuple types       | `type`      |
+| Mapped types      | `type`      |
+| Conditional types | `type`      |
+| Primitive aliases | `type`      |
+
+---
+
+## Union and Intersection Types
+
+### Union Types
+
+```typescript
+// Value can be one of several types
+type StringOrNumber = string | number
+
+// Discriminated unions (tagged unions)
+interface Dog {
+  kind: 'dog'
+  bark(): void
+}
+
+interface Cat {
+  kind: 'cat'
+  meow(): void
+}
+
+type Pet = Dog | Cat
+
+function speak(pet: Pet): void {
+  switch (pet.kind) {
+    case 'dog':
+      pet.bark()
+      break
+    case 'cat':
+      pet.meow()
+      break
+  }
+}
+```
+
+### Intersection Types
+
+```typescript
+// Value must satisfy all types
+interface HasName {
+  name: string
+}
+
+interface HasAge {
+  age: number
+}
+
+type Person = HasName & HasAge
+
+const person: Person = {
+  name: 'Alice',
+  age: 30,
+}
+
+// Practical: Extending with additional properties
+type WithTimestamp<T> = T & { createdAt: Date; updatedAt: Date }
+
+interface Article {
+  title: string
+  content: string
+}
+
+type TimestampedArticle = WithTimestamp<Article>
+```
+
+---
+
+## Literal Types
+
+### String Literals
+
+```typescript
+// Specific string values
+type Direction = 'north' | 'south' | 'east' | 'west'
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+
+function move(direction: Direction): void {
+  console.log(`Moving ${direction}`)
+}
+
+move('north') // OK
+move('up') // Error: Argument of type '"up"' is not assignable
+```
+
+### Numeric Literals
+
+```typescript
+type DiceRoll = 1 | 2 | 3 | 4 | 5 | 6
+type BinaryDigit = 0 | 1
+
+function roll(): DiceRoll {
+  return Math.ceil(Math.random() * 6) as DiceRoll
+}
+```
+
+### Template Literal Types
+
+```typescript
+// Construct string literal types
+type EventName = 'click' | 'hover' | 'focus'
+type HandlerName = `on${Capitalize<EventName>}`
+// "onClick" | "onHover" | "onFocus"
+
+// CSS unit types
+type CSSUnit = 'px' | 'em' | 'rem' | '%'
+type CSSValue = `${number}${CSSUnit}`
+
+const width: CSSValue = '100px' // OK
+const height: CSSValue = '50%' // OK
+const bad: CSSValue = '100' // Error
+```
+
+---
+
+## Type Guards and Narrowing
+
+### Built-in Type Guards
+
+```typescript
+function process(value: string | number | null): string {
+  // typeof guard
+  if (typeof value === 'string') {
+    return value.toUpperCase()
+  }
+
+  // typeof guard for number
+  if (typeof value === 'number') {
+    return value.toFixed(2)
+  }
+
+  // null/undefined narrowing
+  if (value === null) {
+    return 'null'
+  }
+
+  // Exhaustiveness check
+  const _exhaustive: never = value
+  throw new Error(`Unhandled case: ${_exhaustive}`)
+}
+```
+
+### instanceof Guard
+
+```typescript
+class ApiError extends Error {
+  constructor(
+    public statusCode: number,
+    message: string
+  ) {
+    super(message)
+  }
+}
+
+class ValidationError extends Error {
+  constructor(public fields: string[]) {
+    super('Validation failed')
+  }
+}
+
+function handleError(error: Error): void {
+  if (error instanceof ApiError) {
+    console.log(`API Error ${error.statusCode}: ${error.message}`)
+  } else if (error instanceof ValidationError) {
+    console.log(`Validation Error on fields: ${error.fields.join(', ')}`)
+  } else {
+    console.log(`Unknown error: ${error.message}`)
+  }
+}
+```
+
+### Custom Type Guards
+
+```typescript
+interface User {
+  type: 'user'
+  name: string
+}
+
+interface Admin {
+  type: 'admin'
+  name: string
+  permissions: string[]
+}
+
+type Account = User | Admin
+
+// Type predicate: returns boolean but narrows type
+function isAdmin(account: Account): account is Admin {
+  return account.type === 'admin'
+}
+
+function getPermissions(account: Account): string[] {
+  if (isAdmin(account)) {
+    return account.permissions // TypeScript knows this is Admin
+  }
+  return []
+}
+```
+
+### Assertion Functions
+
+```typescript
+function assertDefined<T>(value: T | undefined, message: string): asserts value is T {
+  if (value === undefined) {
+    throw new Error(message)
+  }
+}
+
+function processUser(user: User | undefined): void {
+  assertDefined(user, 'User is required')
+  // After assertion, user is narrowed to User
+  console.log(user.name)
+}
+```
+
+---
+
+## The satisfies Operator
+
+### Problem: Type Assertions Hide Bugs
+
+```typescript
+// Using 'as' can hide type errors
+const config = {
+  port: 3000,
+  host: 'localhost',
+} as Record<string, string | number>
+
+// No error, but port is now string | number
+const portString = config.port.toFixed(2) // Runtime error if port is string!
+```
+
+### Solution: satisfies Validates Without Widening
+
+```typescript
+// satisfies checks conformance but preserves literal types
+const config = {
+  port: 3000,
+  host: 'localhost',
+} satisfies Record<string, string | number>
+
+// TypeScript knows port is number, host is string
+config.port.toFixed(2) // OK - port is number
+config.host.toUpperCase() // OK - host is string
+```
+
+### Practical Use Cases
+
+```typescript
+// Color palette with constrained values
+const palette = {
+  primary: '#007bff',
+  secondary: '#6c757d',
+  success: '#28a745',
+} satisfies Record<string, `#${string}`>
+
+// TypeScript knows each property exists and is a hex string
+palette.primary.startsWith('#') // OK
+
+// Route configuration
+type RouteConfig = {
+  path: string
+  method: 'GET' | 'POST'
+  handler: () => void
+}
+
+const routes = {
+  home: { path: '/', method: 'GET', handler: () => {} },
+  login: { path: '/login', method: 'POST', handler: () => {} },
+} satisfies Record<string, RouteConfig>
+
+// TypeScript preserves literal types for each route
+routes.home.method // "GET" (not "GET" | "POST")
+```
+
+---
+
+## Special Types
+
+### any vs unknown
+
+```typescript
+// any: Opt out of type checking (avoid)
+let anyValue: any = 'hello'
+anyValue.toFixed(2) // No error, but crashes at runtime
+
+// unknown: Type-safe any (prefer)
+let unknownValue: unknown = 'hello'
+unknownValue.toFixed(2) // Error: Object is of type 'unknown'
+
+// Must narrow unknown before use
+if (typeof unknownValue === 'string') {
+  unknownValue.toUpperCase() // OK after narrowing
+}
+```
+
+### never
+
+```typescript
+// never: Represents impossible values
+function fail(message: string): never {
+  throw new Error(message)
+}
+
+// Exhaustiveness checking with never
+type Shape = 'circle' | 'square'
+
+function getArea(shape: Shape): number {
+  switch (shape) {
+    case 'circle':
+      return Math.PI
+    case 'square':
+      return 1
+    default:
+      // If we add a new shape, this will error
+      const _exhaustive: never = shape
+      throw new Error(`Unknown shape: ${_exhaustive}`)
+  }
+}
+```
+
+### void vs undefined
+
+```typescript
+// void: Function doesn't return anything meaningful
+function log(message: string): void {
+  console.log(message)
+}
+
+// undefined: Explicit undefined value
+function findUser(id: string): User | undefined {
+  return users.get(id)
+}
+```

package/skills/vitest-standard/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: vitest-standard
+description: |
+  Comprehensive unit testing expertise covering Vitest, test-driven 
+  development (TDD), mocking strategies, and production-grade best practices. 
+  Activates for unit testing, Vitest, TDD, Red-Green-Refactor, mocking, 
+  stubbing, spying, test coverage, and test architecture in TypeScript/Node projects.
+---
+
+# Vitest Standard
+
+This skill provides opinionated, production-tested guidance for high-integrity unit testing with Vitest. It emphasizes behavior-driven design, strictly isolated tests, and the TDD lifecycle.
+
+## Golden Rules (Mandatory)
+
+1.  **Test Behavior, Not Implementation** — Assert what the code _does_, not how it _looks_ internally.
+2.  **Strict Isolation** — NO shared state between tests. Create new instances in `beforeEach`.
+3.  **Clean Mocks** — Use `vi.clearAllMocks()` in `beforeEach` to prevent call history leaks.
+4.  **No Magic Numbers** — Use descriptive variables for expected values.
+5.  **AAA Pattern** — Every test must follow Arrange-Act-Assert.
+6.  **Async/Await** — Always await promises; use `rejects.toThrow()` for error paths.
+7.  **Deterministic Tests** — No dependence on system time, environment variables, or randomness (mock them).
+8.  **Meaningful Names** — Use `it('should [action] when [condition]')` or Given-When-Then.
+9.  **Mock at Boundaries** — Mock external APIs, databases, and third-party SDKs; test your own logic.
+10. **Red-Green-Refactor** — Prefer writing tests before code to drive API design.
+
+## Core Patterns
+
+### AAA (Arrange-Act-Assert)
+
+```typescript
+it('should calculate total price', () => {
+  // Arrange: Setup data and environment
+  const cart = new ShoppingCart()
+  cart.addItem({ price: 10, quantity: 2 })
+
+  // Act: Execute the method being tested
+  const total = cart.getTotal()
+
+  // Assert: Verify the outcome
+  expect(total).toBe(20)
+})
+```
+
+### Mocking Example
+
+```typescript
+import { vi, it, expect } from 'vitest'
+
+it('mocks dependencies', () => {
+  const mockFn = vi.fn().mockReturnValue(42)
+  expect(mockFn()).toBe(42)
+  expect(mockFn).toHaveBeenCalledOnce()
+})
+```
+
+## Quick Reference: Assertions
+
+| Assertion                | Purpose                        |
+| :----------------------- | :----------------------------- |
+| `toBe(val)`              | Strict equality (`===`)        |
+| `toEqual(val)`           | Deep equality (objects/arrays) |
+| `toMatchObject(obj)`     | Partial match on an object     |
+| `toThrow(error?)`        | Validates a thrown error       |
+| `toHaveBeenCalledWith()` | Verifies mock call arguments   |
+| `resolves.toEqual()`     | Validates a fulfilled promise  |
+| `rejects.toThrow()`      | Validates a rejected promise   |
+
+---
+
+## Specialized References (Load On-Demand)
+
+| Scenario                     | Reference File                                              |
+| :--------------------------- | :---------------------------------------------------------- |
+| **Mocking & Doubles**        | [mocking.md](references/mocking.md)                         |
+| **Async & Error Handling**   | [async-and-errors.md](references/async-and-errors.md)       |
+| **Coverage & Configuration** | [coverage-and-config.md](references/coverage-and-config.md) |
+| **TDD Cycle**                | [tdd-patterns.md](references/tdd-patterns.md)               |
+
+## Example: TDD Calculator
+
+See [tdd-calculator.ts](examples/tdd-calculator.ts) for the Red-Green-Refactor workflow.

package/skills/vitest-standard/examples/service-mock.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+
+// Intercept external module
+vi.mock('./api', () => ({
+    fetchUser: vi.fn(),
+    updateUser: vi.fn(),
+}))
+
+// Mock instance for Dependency Injection
+const mockDb = {
+    save: vi.fn().mockResolvedValue({ id: '123' }),
+    delete: vi.fn().mockResolvedValue(true),
+}
+
+describe('UserService', () => {
+    let service: UserService
+
+    beforeEach(() => {
+        service = new UserService(mockDb as any)
+        vi.clearAllMocks() // Clear call history between tests
+    })
+
+    afterEach(() => {
+        vi.restoreAllMocks() // Restore spies/intercepted methods
+    })
+
+    it('should save user to database', async () => {
+        // Arrange
+        const user = { name: 'John Doe' }
+
+        // Act
+        const result = await service.saveUser(user)
+
+        // Assert
+        expect(mockDb.save).toHaveBeenCalledOnce()
+        expect(mockDb.save).toHaveBeenCalledWith(user)
+        expect(result.id).toBe('123')
+    })
+
+    it('should throw error for invalid id', async () => {
+        // Arrange
+        mockDb.save.mockRejectedValueOnce(new Error('Invalid ID'))
+
+        // Act & Assert (Async Error Path)
+        await expect(service.saveUser({ name: '' })).rejects.toThrow('Invalid ID')
+    })
+})
+
+class UserService {
+    constructor(private db: Database) {}
+    async saveUser(user: any) {
+        return this.db.save(user)
+    }
+}
+
+class Database {
+    async save(user: any): Promise<any> {
+        return { id: '' }
+    }
+}

package/skills/vitest-standard/examples/tdd-calculator.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'vitest'
+
+// 1. RED: Write a failing test first
+describe('Calculator', () => {
+    it('should add numbers', () => {
+        const calc = new Calculator()
+        expect(calc.add(2, 3)).toBe(5)
+    })
+
+    it('should multiply numbers', () => {
+        const calc = new Calculator()
+        expect(calc.multiply(2, 3)).toBe(6)
+    })
+})
+
+// 2. GREEN: Minimal implementations
+class Calculator {
+    // Red -> Green -> Refactor cycle
+    add(a: number, b: number): number {
+        return a + b
+    }
+
+    // Next iteration:
+    multiply(a: number, b: number): number {
+        return a * b
+    }
+}
+
+// 3. REFACTOR (Example):
+class ImprovedCalculator {
+    // Drive the add method with any number of parameters
+    add(...numbers: number[]): number {
+        return numbers.reduce((sum, n) => sum + n, 0)
+    }
+}
+
+// 4. Test the refactored version
+it('should add multiple numbers in ImprovedCalculator', () => {
+    const calc = new ImprovedCalculator()
+    expect(calc.add(1, 2, 3, 4)).toBe(10)
+})

package/skills/vitest-standard/examples/type-stubs.d.ts

@@ -0,0 +1,18 @@
+// Type stubs for the Vitest Standard skill examples.
+// This file solves "Cannot find module" errors in the IDE when viewing
+// master reference files outside of a project root.
+
+declare module 'vitest' {
+    export const describe: any
+    export const it: any
+    export const expect: any
+    export const vi: any
+    export const beforeEach: any
+    export const afterEach: any
+    export const beforeAll: any
+    export const afterAll: any
+}
+
+declare module 'vitest/config' {
+    export const defineConfig: any
+}