typescript-fundamentals

Files (4)

• SKILL.md
• jsdoc.md · references/
• patterns.md · references/
• types.md · references/

SKILL.md (first lines)

# TypeScript Fundamentals Skill

Use this skill when writing, reviewing, or refactoring TypeScript code with a focus on correctness, readability, and maintainability.

## Core principles

1. Prefer explicit types at module boundaries; let the compiler infer inside function bodies.
2. Model the domain with types before writing logic.
3. Avoid `any`. Use `unknown` for truly unknown values and narrow at the boundary.
4. Keep types small and composable. Prefer intersection and union over large monolithic interfaces.
5. Write code that is easy to delete — avoid deep coupling through concrete classes, global state, or shared mutable singletons.
6. Fail fast: validate untrusted input at system entry points and return typed errors instead of throwing broadly.

## tsconfig baseline

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": false
  }
}
```

- Enable `strict` always. Enable `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` for new projects.
- Use `verbatimModuleSyntax` to make import/export intent explicit and avoid commonjs interop surprises.
- Set `skipLibCheck: false` for strict projects; relax only when third-party type errors block builds.

## Type design

```ts
// Prefer discriminated unions for state machines
type RequestState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: string };

// Use branded types for IDs that must not be mixed
type UserId = string & { readonly _brand: "UserId" };
type ProductId = string & { readonly _brand: "ProductId" };

// Narrow exhaustively
function describe(state: RequestState<Product>): string {
  switch (state.status) {
    case "idle": return "idle";
    case "loading": return "loading";
    case "success": return state.data.name;
    case "error": return state.error;
  }
}
```

## Naming conventions

| Context | Convention | Example |
|---|---|---|
| Variables, functions | `camelCase` | `getUserById`, `pageLimit` |
| Types, interfaces, classes | `PascalCase` | `ProductInput`, `UserService` |
| Enums | `PascalCase` members | `Status.Active` |
| Constants (module-level) | `SCREAMING_SNAKE` for primitives | `MAX_PAGE_SIZE = 100` |
| Files | `kebab-case` | `user-service.ts`, `api-products.ts` |
| Private class members | `_prefix` only when disambiguation is needed; prefer `#private` | `#cache` |
| Boolean variables | `is`, `has`, `can`, `should` prefix | `isActive`, `hasPermission` |

- Do not abbreviate unless the abbreviation is domain-standard (`id`, `url`, `db`, `req`, `res`).
- Name functions with verbs: `fetchUser`, `createOrder`, `validateInput`.
- Name types with nouns: `User`, `OrderSummary`, `ValidationResult`.

## Patterns

### Result type instead of throwing

```ts
type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parsePositiveInt(raw: string): Result<number> {
  const n = parseInt(raw, 10);
  if (isNaN(n) || n < 1) return { ok: false, error: `"${raw}" is not a positive integer` };
  return { ok: true, value: n };
}
```

### Validation with Zod

```ts
import { z } from "zod";

const ProductInput = z.object({
  name: z.string().min(1).max(200),
  price: z.number().nonnegative(),
  tags: z.array(z.string()).max(10).default([]),
});

type ProductInput = z.infer<typeof ProductInput>;

// At boundary:
const parsed = ProductInput.safeParse(await req.json());
if (!parsed.success) return Response.json({ error: "Validation failed" }, { status: 422 });
```

### Dependency injection without a framework

```ts
// Define ports as interfaces; inject at callsite
interface Logger {
  info(message: string, context?: Record<string, unknown>): void;
  error(message: string, error?: unknown): void;
}

From prachwal-archive/web-ui-skills, MIT.

More from prachwal-archive/web-ui-skills