# Typescript

> TypeScript strict patterns, type safety, and best practices. Trigger: When writing TypeScript code with types, interfaces, or generics.

- Skill: `odjaramillo/typescript` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add odjaramillo/typescript`
- Raw SKILL.md: https://api.skillmd.com/api/skills/odjaramillo/typescript/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: odjaramillo (https://skillmd.com/u/odjaramillo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/odjaramillo/typescript

---


## Critical Patterns

### 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";
```

### 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
}

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

### Never Use `any` (REQUIRED)

```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 { }
```

---

## Decision Tree

```
Need a set of constants?    → Use const object + typeof
Need optional fields?       → Use Partial<T>
Need to pick fields?        → Use Pick<T, K>
Need to exclude fields?     → Use Omit<T, K>
Need runtime type check?    → Create type guard function
Need to extract type?       → Use ReturnType<typeof fn>
```

---

## Code Examples

### Type Guards

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

### Utility Types

```typescript
Pick<User, "id" | "name">     // Select fields
Omit<User, "id">              // Exclude fields
Partial<User>                 // All optional
Required<User>                // All required
Record<string, User>          // Object type
NonNullable<T | null>         // Remove null/undefined
ReturnType<typeof fn>         // Function return type
```

### Import Types

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

---

## Commands

```bash
npx tsc --noEmit              # Type check without emit
npx tsc --init                # Initialize tsconfig.json
npx tsc -w                    # Watch mode
```

---

## Resources

Specialized TypeScript documentation:
- **Best Practices**: [best-practices.md](best-practices.md)
- **Type Safety**: [type-safety.md](type-safety.md)
- **NestJS Integration**: [nestjs.md](nestjs.md)
- **Node.js Patterns**: [node.md](node.md)