typescript

Files (1)

• SKILL.md

SKILL.md (first lines)

## When to Apply

Use this skill when:
- Creating new types or interfaces
- Refactoring existing types
- Working with union types or enums
- Adding type guards or validation
- Removing `any` from the codebase

---

## Critical Rules

### 1. 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.

### 2. 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;
}

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

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

### 3. 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 { }
```

---

## Decision Tree

```text
Creating enum-like values?  -> Use const object + typeof pattern
Defining object shape?      -> Use flat interfaces, avoid nesting
Unknown input source?      -> Use unknown, not any
Need flexible generic?     -> Use <T> generics
Need runtime validation?    -> Use type guards (value is Type)
```

---

## Utility Types Reference

```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
  );
}
```

From TomiCassanelli/tickets-tool, MIT.

More from TomiCassanelli/tickets-tool