---
description: when dealing with types and Typesript
alwaysApply: false
---

```json

{
  "coaching_level": "light",
  "socratic_max_questions": 7,
  "verbosity": "concise",
  "timebox_minutes": null,
  "format_enforcement": "strict"
}

```

# TypeScript Type Safety Guidelines

**Author**: Matthew Raymer
**Date**: 2025-08-19
**Status**: 🎯 **ACTIVE** - Type safety enforcement

## Overview

Practical rules to keep TypeScript strict and predictable. Minimize exceptions.

## Core Rules

1. **No `any`**

   - Use explicit types. If unknown, use `unknown` and **narrow** via guards.

2. **Error handling uses guards**

   - Reuse guards from `src/interfaces/**` (e.g., `isDatabaseError`,

     `isApiError`).

   - Catch with `unknown`; never cast to `any`.

3. **Dynamic property access is type‑safe**

   - Use `keyof` + `in` checks:

     ```ts

     obj[k as keyof typeof obj]

     ```

   - Avoid `(obj as any)[k]`.

## Type Safety Enforcement

### Core Type Safety Rules

- **No `any` Types**: Use explicit types or `unknown` with proper type guards

- **Error Handling Uses Guards**:

  Implement and reuse type guards from `src/interfaces/**`

- **Dynamic Property Access**:

  Use `keyof` + `in` checks for type-safe property access

### Type Guard Patterns

- **API Errors**: Use `isApiError(error)` guards for API error handling

- **Database Errors**:

  Use `isDatabaseError(error)` guards for database operations

- **Axios Errors**:

  Implement `isAxiosError(error)` guards for HTTP error handling

### Implementation Guidelines

- **Avoid Type Assertions**:

  Replace `as any` with proper type guards and interfaces

- **Narrow Types Properly**: Use type guards to narrow `unknown` types safely

- **Document Type Decisions**: Explain complex type structures and their purpose

## Minimal Special Cases (document in PR when used)

- **Vue refs / instances**: Use `ComponentPublicInstance` or specific

  component types for dynamic refs.

- **3rd‑party libs without types**: Narrow immediately to a **known

  interface**; do not leave `any` hanging.

## Patterns (short)

### Database errors

```ts

try { await this.$addContact(contact); }
catch (e: unknown) {
  if (isDatabaseError(e) && e.message.includes("Key already exists")) {
    /* handle duplicate */
  }
}

```

### API errors

```ts

try { await apiCall(); }
catch (e: unknown) {
  if (isApiError(e)) {
    const msg = e.response?.data?.error?.message;
  }
}

```

### Dynamic keys

```ts

const keys = Object.keys(newSettings).filter(
k => k in newSettings && newSettings[k as keyof typeof newSettings] !==
  undefined
);

```

## Checklists

**Before commit**

- [ ] No `any` (except documented, justified cases)

- [ ] Errors handled via guards

- [ ] Dynamic access uses `keyof`/`in`

- [ ] Imports point to correct interfaces/types

**Code review**

- [ ] Hunt hidden `as any`

- [ ] Guard‑based error paths verified

- [ ] Dynamic ops are type‑safe

- [ ] Prefer existing types over re‑inventing

## Tools

- `npm run lint-fix` — lint & auto‑fix

- `npm run type-check` — strict type compilation (CI + pre‑release)

- IDE: enable strict TS, ESLint/TS ESLint, Volar (Vue 3)

## References

- TS Handbook — <https://www.typescriptlang.org/docs/>

- TS‑ESLint — <https://typescript-eslint.io/rules/>

- Vue 3 + TS — <https://vuejs.org/guide/typescript/>

---

**Status**: Active type safety guidelines
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: TypeScript, ESLint, Vue 3
**Stakeholders**: Development team

- TS Handbook — <https://www.typescriptlang.org/docs/>

- TS‑ESLint — <https://typescript-eslint.io/rules/>

- Vue 3 + TS — <https://vuejs.org/guide/typescript/>

## Model Implementation Checklist

### Before Type Implementation

- [ ] **Type Analysis**: Understand current type definitions and usage
- [ ] **Interface Review**: Review existing interfaces and types
- [ ] **Error Handling**: Plan error handling with type guards
- [ ] **Dynamic Access**: Identify dynamic access patterns that need type safety

### During Type Implementation

- [ ] **Type Safety**: Ensure types provide meaningful safety guarantees
- [ ] **Error Guards**: Implement proper error handling with type guards
- [ ] **Dynamic Operations**: Use `keyof`/`in` for dynamic access
- [ ] **Import Validation**: Verify imports point to correct interfaces/types

### After Type Implementation

- [ ] **Linting Check**: Run `npm run lint-fix` to verify code quality
- [ ] **Type Check**: Run `npm run type-check` for strict type compilation
- [ ] **Code Review**: Hunt for hidden `as any` and type safety issues
- [ ] **Documentation**: Update type documentation and examples
