---
name: typescript
description: >
  TypeScript strict patterns and best practices. Trigger: When implementing or refactoring
  TypeScript in .ts/.tsx (types, interfaces, generics, const maps, type guards, removing any,
  tightening unknown).
license: MIT
metadata:
  author: aurora
  version: '1.0'
  auto_invoke: 'Implementing TypeScript types, interfaces, generics, type guards, strict patterns'
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
---

## Explicit Code Over Implicit (REQUIRED)

Prefer explicit code that clearly communicates intent over clever or concise patterns that obscure
it.

```typescript
// ✅ Explicit: intent is immediately clear
const isEligible = user.age >= 18 && user.hasVerifiedEmail;
if (isEligible) {
  grantAccess(user);
}

// ❌ Implicit: requires mental parsing to understand intent
if (user.age >= 18 && user.hasVerifiedEmail) grantAccess(user);

// ✅ Explicit: each step is named and readable
const activeUsers = users.filter((user) => user.isActive);
const sortedByName = activeUsers.sort((a, b) => a.name.localeCompare(b.name));
const firstTen = sortedByName.slice(0, 10);

// ❌ Implicit: long chains hide what each step does
const result = users
  .filter((u) => u.isActive)
  .sort((a, b) => a.name.localeCompare(b.name))
  .slice(0, 10);

// ✅ Explicit return type: the contract is visible
function calculateDiscount(price: number, tier: CustomerTier): number {
  // ...
}

// ❌ Implicit return type when it's not obvious from the body
function calculateDiscount(price: number, tier: CustomerTier) {
  // ...
}
```

**Rules:**

- Name intermediate variables to describe **what**, not **how**
- Add explicit return types on public/exported functions
- Prefer `if/else` over nested ternaries
- Avoid single-letter parameter names except in trivial lambdas (`arr.map(x => x.id)`)
- Don't create abstractions to reduce lines — reduce them to increase clarity

## Const Types Pattern (REQUIRED)

```typescript
// ✅ ALWAYS: Create const object first, then extract type
const STATUS = {
  ACTIVE: 'active',
  INACTIVE: 'inactive',
  PENDING: 'pending',
} as const;

type Status = (typeof STATUS)[keyof typeof STATUS];

// ❌ NEVER: Direct union types
type Status = 'active' | 'inactive' | 'pending';
```

**Why?** Single source of truth, runtime values, autocomplete, easier refactoring.

## Flat Interfaces (REQUIRED)

```typescript
// ✅ ALWAYS: One level depth, nested objects → dedicated interface
interface UserAddress {
  street: string;
  city: string;
}

interface User {
  id: string;
  name: string;
  address: UserAddress; // Reference, not inline
}

interface Admin extends User {
  permissions: string[];
}

// ❌ NEVER: Inline nested objects
interface User {
  address: { street: string; city: string }; // NO!
}
```

## Never Use `any`

```typescript
// ✅ Use unknown for truly unknown types
function parse(input: unknown): User {
  if (isUser(input)) return input;
  throw new Error('Invalid input');
}

// ✅ Use generics for flexible types
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

// ❌ NEVER
function parse(input: any): any {}
```

## Utility Types

```typescript
Pick<User, 'id' | 'name'>; // Select fields
Omit<User, 'id'>; // Exclude fields
Partial<User>; // All optional
Required<User>; // All required
Readonly<User>; // All readonly
Record<string, User>; // Object type
Extract<Union, 'a' | 'b'>; // Extract from union
Exclude<Union, 'a'>; // Exclude from union
NonNullable<T | null>; // Remove null/undefined
ReturnType<typeof fn>; // Function return type
Parameters<typeof fn>; // Function params tuple
```

## Type Guards

```typescript
function isUser(value: unknown): value is User {
  return typeof value === 'object' && value !== null && 'id' in value && 'name' in value;
}
```

## Import Types

```typescript
import type { User } from './types';
import { createUser, type Config } from './utils';
```
