# TypeScript

> ContextOS skill for TypeScript

- Skill: `kok-o/typescript-2` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add kok-o/typescript-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kok-o/typescript-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kok-o (https://skillmd.com/u/kok-o)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kok-o/typescript-2

---


# TypeScript

## Overview

Strict TypeScript engineering standard. Enforces noImplicitAny, discriminated unions, branded types, immutability, exhaustive switch checks, and zero unsafe any or as unknown as T casts.

## When to Use

Activate on all TypeScript and JavaScript codebases to ensure compile-time type safety, robust domain modeling, and foolproof function contracts.

## Negative Constraints (What NOT to Do)

1. **NEVER use `any`**: Use `unknown` with type guards, discriminated unions, or Zod schemas.
2. **NEVER use type assertions (`as Type` or `as unknown as Type`) to bypass safety**: Fix the underlying type signature or use runtime narrowing (`instanceof`, `typeof`, `in`).
3. **NEVER use non-null assertions (`foo!.bar`)**: Handle `null` and `undefined` with optional chaining (`?.`) or explicit error guards.
4. **NEVER export mutable global arrays or object constants**: Always mark constant objects and arrays with `as const` and `readonly`.
5. **NEVER omit explicit return types on exported functions**: Exported public APIs must declare explicit return types to protect consumers.

## Rules & Patterns

## Strict Mode

Always use strict TypeScript configuration:

```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}
```

## Types

- **Prefer `interface`** for object shapes, `type` for unions/intersections
- **No `any`** — use `unknown` if type is truly unknown, then narrow
- **Explicit return types** for exported functions
- **Const assertions** — `as const` for literal types

```typescript
// Good
interface User {
  id: string;
  name: string;
  role: 'admin' | 'user';
}

// Unions
type Result<T> = { ok: true; data: T } | { ok: false; error: string };
```

## Utility Types

- `Partial<T>` — all properties optional
- `Required<T>` — all properties required
- `Pick<T, K>` — select specific properties
- `Omit<T, K>` — remove specific properties
- `Record<K, V>` — key-value map

## Type Guards

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

## Generic Patterns

```typescript
// Repository pattern
interface Repository<T extends { id: string }> {
  findById(id: string): Promise<T | null>;
  create(data: Omit<T, 'id'>): Promise<T>;
  update(id: string, data: Partial<T>): Promise<T>;
  delete(id: string): Promise<void>;
}
```

## Anti-Patterns

- [FAIL] `any` — use `unknown` + type guards
- [FAIL] Type assertions (`as`) — prefer type guards
- [FAIL] Non-null assertions (`!`) — handle null explicitly
- [FAIL] Enums — prefer union types or `as const` objects
- [FAIL] Complex generics without JSDoc — document intent


## Code Examples

See `EXAMPLES.md` for detailed code examples.

## Validation Checklist

What to verify during the review phase before completing the task.

## Common Mistakes

Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.

## Integration Notes

How this skill interacts with other skills.