typescript

name	typescript
description	TypeScript strict patterns and best practices. Trigger: When implementing or refactoring TypeScript in .ts/.tsx (types, interfaces, generics, const maps, type guards, removing any, tightening unknown).
license	Apache-2.0
metadata	{"author":"prowler-cloud","version":"1.0","scope":["root","ui"],"auto_invoke":"Writing TypeScript types/interfaces"}
allowed-tools	Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task

Const Types Pattern (REQUIRED)

// ✅ 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.

Flat Interfaces (REQUIRED)

// ✅ 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
}

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

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

Never Use any

// ✅ 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 { }

Utility Types

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

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

Import Types (REQUIRED)

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

[!CAUTION] AVOID importing interfaces or types using standard import { SomeType } when using bundlers like Vite/Astro. BECAUSE standard imports might cause the bundler to look for a JavaScript export that doesn't exist, leading to SyntaxError or hydration failures in the browser. CORRECT APPROACH: Always use import type or the type prefix within an import statement to ensure types are correctly stripped during compilation.

[!CAUTION] AVOID leaving behind commented-out code (like exports or functions) that you temporarily disabled to isolate a bug. BECAUSE this breaks the TypeScript contract for other files that depend on those exports (e.g., throwing Module has no exported member or Property does not exist on type), forcing other agents or the user to clean up after you. CORRECT APPROACH: Always revert your diagnostic/isolation changes (uncomment code) immediately after identifying the root cause of a bug, BEFORE declaring the task complete.