typescript by fearovex/claude-config

When to Use

Triggers: When writing TypeScript, defining types/interfaces, or using utility types.

Load when: writing TypeScript code, defining data structures, working with generics, or needing type safety patterns.

Critical Patterns

Pattern 1: Const Types (single source of truth)

// ✅ Create const object first, then extract type
const USER_ROLES = {
  ADMIN: 'admin',
  USER: 'user',
  GUEST: 'guest',
} as const;

type UserRole = typeof USER_ROLES[keyof typeof USER_ROLES];
// UserRole = 'admin' | 'user' | 'guest'

// ❌ Avoid: direct union types lose runtime values
type UserRole = 'admin' | 'user' | 'guest';

Pattern 2: Flat Interfaces (one-level depth)

// ✅ Flat, composable interfaces
interface Address {
  street: string;
  city: string;
  country: string;
}

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

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

// ❌ Avoid: deeply nested inline types
interface User {
  address: {
    street: string;
    location: {
      city: string;
      coords: { lat: number; lng: number };
    };
  };
}

Pattern 3: Avoid `any` — Use `unknown` or generics

// ✅ Use unknown with type guard
function processData(data: unknown): string {
  if (typeof data === 'string') return data;
  if (typeof data === 'number') return data.toString();
  throw new Error('Unsupported type');
}

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

// ❌ Avoid
function processData(data: any): any {
  return data.toString(); // No type safety
}

Code Examples

Utility Types

interface User {
  id: string;
  name: string;
  email: string;
  password: string;
  createdAt: Date;
}

// Pick specific fields
type UserPublic = Pick<User, 'id' | 'name' | 'email'>;

// Omit sensitive fields
type UserWithoutPassword = Omit<User, 'password'>;

// All fields optional (for updates)
type UserUpdate = Partial<User>;

// All fields required
type UserRequired = Required<User>;

// All fields readonly
type UserReadonly = Readonly<User>;

// Map of users
type UsersMap = Record<string, User>;

// Extract subset of union
type AdminOrUser = Extract<UserRole, 'admin' | 'user'>;

// Return type of function
type LoginResult = ReturnType<typeof loginUser>;

// Parameters of function
type LoginParams = Parameters<typeof loginUser>;

Type Guards

// ✅ Type guard with `is` syntax
function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'name' in value
  );
}

// Discriminated union
type ApiResponse<T> =
  | { status: 'success'; data: T }
  | { status: 'error'; message: string };

function handleResponse<T>(response: ApiResponse<T>) {
  if (response.status === 'success') {
    console.log(response.data); // TypeScript knows data exists
  } else {
    console.error(response.message); // TypeScript knows message exists
  }
}

Import Types

// ✅ Use import type for type-only imports
import type { User, UserRole } from './types';
import type { FC, ReactNode } from 'react';

// Runtime imports
import { useState } from 'react';
import { createUser } from './services/user';

Readonly and Immutability

// ✅ Immutable data structures
const config: Readonly<{
  apiUrl: string;
  timeout: number;
}> = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
};

// Deep readonly
type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
};

Anti-Patterns

❌ Using `any`

// ❌ Bad
function parse(data: any) {
  return data.value; // No type safety
}

// ✅ Good
function parse(data: unknown): string {
  if (typeof data === 'object' && data !== null && 'value' in data) {
    return String((data as { value: unknown }).value);
  }
  throw new Error('Invalid data shape');
}

❌ Non-null assertion without guard

// ❌ Bad - runtime crash if null
const user = getUser()!;
console.log(user.name);

// ✅ Good
const user = getUser();
if (!user) throw new Error('User not found');
console.log(user.name);

Quick Reference

Task	Pattern
Union from object	`typeof OBJ[keyof typeof OBJ]`
Optional fields	`Partial<T>`
Pick fields	`Pick<T, 'a' \| 'b'>`
Exclude fields	`Omit<T, 'password'>`
Type guard	`value is Type`
Type-only import	`import type { T }`
Readonly	`Readonly<T>` or `as const`
Generic constraint	`<T extends object>`

Rules

any is forbidden — use unknown with type guards or generics; @ts-ignore is only acceptable as a last resort with an explanatory comment
Use import type for type-only imports to ensure they are erased at compile time and do not affect the runtime bundle
Prefer const objects with as const over plain union types for enums and string literals — this preserves runtime values alongside the type
Non-null assertions (!) require an immediately preceding null check; bare value! without a guard is a runtime crash waiting to happen
Interfaces should be flat and composable — deeply nested inline type definitions inside other types are a readability and reusability anti-pattern

typescript