@biggora/claude-plugins 1.2.0 → 1.3.0

package/src/skills/typescript-expert/references/advanced-type-guards.md

@@ -0,0 +1,308 @@
+# Type Guards and Discriminated Unions
+
+Type guards let you narrow a type within a conditional block. Discriminated unions combine literal types with exhaustive checking for robust state modeling.
+
+## Built-in Narrowing
+
+TypeScript narrows types automatically in many control flow patterns:
+
+```typescript
+// typeof
+function process(x: string | number) {
+  if (typeof x === "string") {
+    x.toUpperCase(); // x is string
+  }
+}
+
+// instanceof
+function handle(err: Error | string) {
+  if (err instanceof Error) {
+    err.message; // err is Error
+  }
+}
+
+// in operator
+function move(animal: { swim?: () => void; fly?: () => void }) {
+  if ("swim" in animal) {
+    animal.swim!();
+  }
+}
+
+// Truthiness
+function print(name: string | null | undefined) {
+  if (name) {
+    name.toUpperCase(); // string (null and undefined removed)
+  }
+}
+
+// Equality
+function compare(a: string | number, b: string | boolean) {
+  if (a === b) {
+    a; // string (only common type)
+  }
+}
+```
+
+## User-Defined Type Guards
+
+When built-in narrowing isn't enough, write custom type guard functions:
+
+```typescript
+// Type predicate — return type is `paramName is Type`
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+function process(value: unknown) {
+  if (isString(value)) {
+    value.toUpperCase(); // TypeScript knows value is string
+  }
+}
+
+// Checking object shapes
+interface User { type: "user"; name: string; email: string }
+interface Admin { type: "admin"; name: string; permissions: string[] }
+
+function isAdmin(person: User | Admin): person is Admin {
+  return person.type === "admin";
+}
+
+// Array filtering with type guards
+const items: (string | null)[] = ["hello", null, "world", null];
+const strings: string[] = items.filter((x): x is string => x !== null);
+```
+
+### Inferred Type Predicates (TS 5.5+)
+
+TypeScript 5.5 can infer type predicates for simple arrow functions:
+
+```typescript
+// Before 5.5: needed explicit annotation
+const strings = items.filter((x): x is string => x !== null);
+
+// TS 5.5+: inferred automatically
+const strings = items.filter(x => x !== null); // string[]
+
+// Also works with Boolean
+const truthy = items.filter(Boolean); // string[] (nulls removed)
+```
+
+## Assertion Functions
+
+Assertion functions narrow the type for all subsequent code (not just the if-block):
+
+```typescript
+function assertIsString(value: unknown): asserts value is string {
+  if (typeof value !== "string") {
+    throw new Error(`Expected string, got ${typeof value}`);
+  }
+}
+
+function process(value: unknown) {
+  assertIsString(value);
+  // From here on, value is string
+  value.toUpperCase();
+}
+
+// Assert non-null
+function assertDefined<T>(value: T): asserts value is NonNullable<T> {
+  if (value == null) {
+    throw new Error("Value must be defined");
+  }
+}
+```
+
+## Discriminated Unions
+
+A discriminated union is a union where each member has a literal property (the "discriminant") that uniquely identifies it:
+
+```typescript
+interface Circle {
+  kind: "circle";
+  radius: number;
+}
+interface Rectangle {
+  kind: "rectangle";
+  width: number;
+  height: number;
+}
+interface Triangle {
+  kind: "triangle";
+  base: number;
+  height: number;
+}
+
+type Shape = Circle | Rectangle | Triangle;
+
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case "circle":
+      return Math.PI * shape.radius ** 2;
+    case "rectangle":
+      return shape.width * shape.height;
+    case "triangle":
+      return 0.5 * shape.base * shape.height;
+  }
+}
+```
+
+### Exhaustive Checking
+
+Ensure all union members are handled:
+
+```typescript
+// Method 1: never in default
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case "circle":
+      return Math.PI * shape.radius ** 2;
+    case "rectangle":
+      return shape.width * shape.height;
+    case "triangle":
+      return 0.5 * shape.base * shape.height;
+    default:
+      // If Shape gains a new member, this line errors
+      const _exhaustive: never = shape;
+      return _exhaustive;
+  }
+}
+
+// Method 2: Helper function
+function assertNever(x: never): never {
+  throw new Error(`Unexpected value: ${x}`);
+}
+
+// Method 3: satisfies never
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case "circle": return Math.PI * shape.radius ** 2;
+    case "rectangle": return shape.width * shape.height;
+    case "triangle": return 0.5 * shape.base * shape.height;
+    default: return shape satisfies never;
+  }
+}
+```
+
+### Modeling Application State
+
+```typescript
+type RequestState<T> =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "success"; data: T }
+  | { status: "error"; error: Error };
+
+function renderUser(state: RequestState<User>) {
+  switch (state.status) {
+    case "idle":
+      return "Click to load";
+    case "loading":
+      return "Loading...";
+    case "success":
+      return `Hello, ${state.data.name}`;  // data is available
+    case "error":
+      return `Error: ${state.error.message}`; // error is available
+  }
+}
+```
+
+### Result Type Pattern
+
+```typescript
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function divide(a: number, b: number): Result<number, string> {
+  if (b === 0) return { ok: false, error: "Division by zero" };
+  return { ok: true, value: a / b };
+}
+
+const result = divide(10, 3);
+if (result.ok) {
+  console.log(result.value); // number
+} else {
+  console.log(result.error); // string
+}
+```
+
+## Narrowing with Control Flow
+
+TypeScript tracks narrowing through assignments, returns, and throws:
+
+```typescript
+function process(value: string | null) {
+  if (value === null) {
+    return; // Early return narrows the rest
+  }
+  // value is string from here
+  value.toUpperCase();
+}
+
+function validate(value: unknown): string {
+  if (typeof value !== "string") {
+    throw new Error("Not a string");
+  }
+  // value is string from here
+  return value.trim();
+}
+
+// Assignment narrowing
+let x: string | number;
+x = "hello";
+x.toUpperCase(); // OK — x is string after assignment
+x = 42;
+x.toFixed(2);    // OK — x is number after assignment
+```
+
+## Narrowing Gotchas
+
+### Narrowing Doesn't Survive Callbacks
+
+```typescript
+function process(value: string | null) {
+  if (value !== null) {
+    // value is string here
+    setTimeout(() => {
+      value.toUpperCase(); // Still OK — value is const in closure
+    }, 100);
+  }
+}
+
+// But with reassignable variables:
+let value: string | null = "hello";
+if (value !== null) {
+  setTimeout(() => {
+    value.toUpperCase(); // Error! value might have been reassigned
+  }, 100);
+}
+```
+
+### Objects and Aliased Conditions
+
+```typescript
+// This doesn't narrow:
+function isValid(obj: { x?: string }) {
+  const hasX = obj.x !== undefined;
+  if (hasX) {
+    obj.x.toUpperCase(); // Error! TypeScript doesn't track aliased conditions
+  }
+
+  // This works:
+  if (obj.x !== undefined) {
+    obj.x.toUpperCase(); // OK
+  }
+}
+```
+
+### Narrowing with Generics
+
+```typescript
+// TypeScript can't narrow generic types well
+function process<T extends string | number>(value: T) {
+  if (typeof value === "string") {
+    // value is still T, not string — narrowing is limited with generics
+    // Use overloads or conditional types instead
+  }
+}
+```

package/src/skills/typescript-expert/references/best-practices-patterns.md

@@ -0,0 +1,313 @@
+# Common TypeScript Patterns
+
+## Branded Types (Nominal Typing)
+
+TypeScript's structural typing means two identical shapes are interchangeable. Branded types add a phantom property to create distinct types:
+
+```typescript
+// Brand type helper
+type Brand<T, B extends string> = T & { readonly __brand: B };
+
+// Create distinct ID types
+type UserId = Brand<string, "UserId">;
+type OrderId = Brand<string, "OrderId">;
+type ProductId = Brand<string, "ProductId">;
+
+// Constructor functions
+function UserId(id: string): UserId { return id as UserId; }
+function OrderId(id: string): OrderId { return id as OrderId; }
+
+// Now they can't be mixed up
+function getOrder(orderId: OrderId): Order { ... }
+
+const userId = UserId("user-123");
+const orderId = OrderId("order-456");
+
+getOrder(orderId);  // OK
+getOrder(userId);   // Error! UserId not assignable to OrderId
+```
+
+### Validated Branded Types
+
+Brands can enforce invariants at construction time:
+
+```typescript
+type Email = Brand<string, "Email">;
+type PositiveNumber = Brand<number, "PositiveNumber">;
+
+function Email(input: string): Email {
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input)) {
+    throw new Error(`Invalid email: ${input}`);
+  }
+  return input as Email;
+}
+
+function PositiveNumber(n: number): PositiveNumber {
+  if (n <= 0) throw new Error(`Must be positive: ${n}`);
+  return n as PositiveNumber;
+}
+```
+
+## Result Type (Error Handling Without Exceptions)
+
+```typescript
+type Result<T, E = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+
+function ok<T>(data: T): Result<T, never> {
+  return { success: true, data };
+}
+
+function err<E>(error: E): Result<never, E> {
+  return { success: false, error };
+}
+
+// Usage
+function parseJSON(input: string): Result<unknown, string> {
+  try {
+    return ok(JSON.parse(input));
+  } catch {
+    return err("Invalid JSON");
+  }
+}
+
+const result = parseJSON('{"a": 1}');
+if (result.success) {
+  console.log(result.data); // unknown
+} else {
+  console.log(result.error); // string
+}
+```
+
+## Builder Pattern
+
+```typescript
+class RequestBuilder {
+  private config: Partial<RequestConfig> = {};
+
+  url(url: string): this {
+    this.config.url = url;
+    return this;
+  }
+
+  method(method: "GET" | "POST" | "PUT" | "DELETE"): this {
+    this.config.method = method;
+    return this;
+  }
+
+  header(key: string, value: string): this {
+    this.config.headers = { ...this.config.headers, [key]: value };
+    return this;
+  }
+
+  build(): RequestConfig {
+    if (!this.config.url) throw new Error("URL is required");
+    return this.config as RequestConfig;
+  }
+}
+
+// Type-safe builder with required fields tracked in the type
+type Builder<T, Required extends keyof T = never> = {
+  [K in keyof T]-?: (value: T[K]) => Builder<T, Required | K>;
+} & ([Required] extends [keyof T]
+  ? { build(): T }
+  : { build: never });
+```
+
+## Discriminated Union State Machines
+
+```typescript
+type ConnectionState =
+  | { state: "disconnected" }
+  | { state: "connecting"; attempt: number }
+  | { state: "connected"; socket: WebSocket }
+  | { state: "error"; error: Error; retryAfter: number };
+
+// Transition functions enforce valid state transitions
+function connect(state: ConnectionState & { state: "disconnected" }): ConnectionState {
+  return { state: "connecting", attempt: 1 };
+}
+
+function onConnected(
+  state: ConnectionState & { state: "connecting" },
+  socket: WebSocket
+): ConnectionState {
+  return { state: "connected", socket };
+}
+```
+
+## Immutable Data
+
+```typescript
+// Readonly utility for shallow immutability
+type Config = Readonly<{
+  host: string;
+  port: number;
+  options: string[];
+}>;
+
+// as const for deep immutability of literals
+const ROUTES = {
+  home: "/",
+  users: "/users",
+  userDetail: "/users/:id",
+} as const;
+
+type Route = (typeof ROUTES)[keyof typeof ROUTES];
+// "/" | "/users" | "/users/:id"
+
+// Readonly collections
+function processItems(items: readonly string[]): void {
+  // items.push("x"); // Error! push doesn't exist on readonly array
+  items.forEach(console.log); // Reading is fine
+}
+```
+
+## Type-Safe Event Emitter
+
+```typescript
+type EventMap = Record<string, any[]>;
+
+class TypedEmitter<Events extends EventMap> {
+  private handlers = new Map<keyof Events, Set<Function>>();
+
+  on<K extends keyof Events>(event: K, handler: (...args: Events[K]) => void): void {
+    if (!this.handlers.has(event)) this.handlers.set(event, new Set());
+    this.handlers.get(event)!.add(handler);
+  }
+
+  emit<K extends keyof Events>(event: K, ...args: Events[K]): void {
+    this.handlers.get(event)?.forEach(fn => fn(...args));
+  }
+
+  off<K extends keyof Events>(event: K, handler: (...args: Events[K]) => void): void {
+    this.handlers.get(event)?.delete(handler);
+  }
+}
+
+// Usage
+interface AppEvents {
+  login: [user: User];
+  logout: [];
+  error: [code: number, message: string];
+}
+
+const emitter = new TypedEmitter<AppEvents>();
+emitter.on("login", (user) => console.log(user.name));
+emitter.on("error", (code, msg) => console.error(code, msg));
+emitter.emit("login", currentUser);
+```
+
+## Exhaustive Map/Object
+
+```typescript
+// Ensure all enum/union members are mapped
+type Status = "active" | "inactive" | "pending" | "archived";
+
+const STATUS_LABELS: Record<Status, string> = {
+  active: "Active",
+  inactive: "Inactive",
+  pending: "Pending",
+  archived: "Archived",
+  // Missing a key = compile error
+};
+
+// Function version
+function getStatusColor(status: Status): string {
+  const colors = {
+    active: "#00ff00",
+    inactive: "#999999",
+    pending: "#ffaa00",
+    archived: "#ff0000",
+  } satisfies Record<Status, string>;
+
+  return colors[status];
+}
+```
+
+## Opaque Type Pattern
+
+For when you want nominal types that are assignable from their base type in specific contexts:
+
+```typescript
+declare const __opaque: unique symbol;
+type Opaque<T, Token> = T & { readonly [__opaque]: Token };
+
+type Seconds = Opaque<number, "Seconds">;
+type Milliseconds = Opaque<number, "Milliseconds">;
+
+function wait(duration: Milliseconds): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, duration));
+}
+
+function toMilliseconds(seconds: Seconds): Milliseconds {
+  return (seconds * 1000) as Milliseconds;
+}
+
+const sec = 5 as Seconds;
+wait(sec);                    // Error! Seconds not assignable to Milliseconds
+wait(toMilliseconds(sec));    // OK
+```
+
+## Safe Dictionary Access
+
+```typescript
+// With noUncheckedIndexedAccess (recommended)
+const dict: Record<string, string> = { a: "hello" };
+const val = dict["a"]; // string | undefined — forces null check
+
+// Safe access pattern
+function getOrThrow<T>(dict: Record<string, T>, key: string): T {
+  const value = dict[key];
+  if (value === undefined) throw new Error(`Missing key: ${key}`);
+  return value;
+}
+```
+
+## Const Assertions for Enum-Like Objects
+
+Prefer `as const` objects over TypeScript enums:
+
+```typescript
+// Instead of:
+enum Direction { North, South, East, West }
+
+// Use:
+const Direction = {
+  North: "north",
+  South: "south",
+  East: "east",
+  West: "west",
+} as const;
+
+type Direction = (typeof Direction)[keyof typeof Direction];
+// "north" | "south" | "east" | "west"
+
+// Benefits:
+// - No runtime code beyond the object
+// - Values are string literals (not numbers)
+// - Easily iterable with Object.values()
+// - Works with JSON serialization
+```
+
+## Assertion Signatures for Validation
+
+```typescript
+function assertNotNull<T>(value: T, message?: string): asserts value is NonNullable<T> {
+  if (value == null) throw new Error(message ?? "Unexpected null");
+}
+
+function assertType<T>(value: unknown, check: (v: unknown) => v is T): asserts value is T {
+  if (!check(value)) throw new Error("Type assertion failed");
+}
+
+// Chain assertions for parsing
+function parseConfig(raw: unknown): Config {
+  assertType(raw, isObject);
+  assertNotNull(raw.host);
+  assertType(raw.host, isString);
+  assertType(raw.port, isNumber);
+  return raw as Config;
+}
+```