@biggora/claude-plugins 1.2.0 → 1.3.0

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

@@ -0,0 +1,185 @@
+# Type-Level Performance
+
+When TypeScript becomes slow, it's usually because complex types cause the compiler to do excessive work. This guide covers how to diagnose and fix type-level performance issues.
+
+## Diagnosing Slow Types
+
+### Compiler Flags for Profiling
+
+```bash
+# Generate a trace for analysis
+tsc --generateTrace ./trace-output
+
+# Show time spent on each file
+tsc --extendedDiagnostics
+
+# Show which types are being checked
+tsc --listFiles
+```
+
+The trace output can be loaded in Chrome DevTools (Performance tab) or `@typescript/analyze-trace`:
+
+```bash
+npx @typescript/analyze-trace ./trace-output
+```
+
+### Common Symptoms
+
+- IDE autocompletion is slow or laggy
+- `tsc` takes significantly longer than expected
+- Hover types show `...` (type too complex to display)
+- "Type instantiation is excessively deep" errors
+
+## Rules for Fast Types
+
+### 1. Prefer Interfaces Over Intersections
+
+```typescript
+// Slower — creates anonymous intersection each time
+type User = BaseEntity & { name: string; email: string };
+
+// Faster — interfaces are cached by name
+interface User extends BaseEntity {
+  name: string;
+  email: string;
+}
+```
+
+Interfaces are cached by identity. Intersections create new anonymous types on every use.
+
+### 2. Limit Union Size
+
+Unions beyond ~25-50 members start impacting performance. Large unions from template literals are a common cause:
+
+```typescript
+// This creates a union of 10,000 members — very slow
+type Color = `#${HexDigit}${HexDigit}${HexDigit}${HexDigit}${HexDigit}${HexDigit}`;
+
+// Better: use a branded string
+type Color = string & { readonly __brand: "Color" };
+```
+
+### 3. Avoid Deep Recursive Types
+
+```typescript
+// Slow — recursion depth grows with path length
+type DeepGet<T, Path extends string> =
+  Path extends `${infer Head}.${infer Tail}`
+    ? Head extends keyof T
+      ? DeepGet<T[Head], Tail>
+      : never
+    : Path extends keyof T
+      ? T[Path]
+      : never;
+
+// If this is slow, consider:
+// 1. Limiting recursion depth with a counter
+// 2. Using a simpler type and casting at the boundary
+// 3. Moving the logic to runtime validation
+```
+
+### Tail-Call Optimization for Recursive Types
+
+TypeScript optimizes tail-position conditional types. Structure recursion to be tail-recursive:
+
+```typescript
+// Not tail-recursive — wraps result before returning
+type BadReverse<T extends any[]> =
+  T extends [infer Head, ...infer Tail]
+    ? [...BadReverse<Tail>, Head]
+    : [];
+
+// Tail-recursive — accumulator pattern
+type Reverse<T extends any[], Acc extends any[] = []> =
+  T extends [infer Head, ...infer Tail]
+    ? Reverse<Tail, [Head, ...Acc]>
+    : Acc;
+```
+
+### 4. Use `skipLibCheck: true`
+
+Skip type-checking `.d.ts` files from `node_modules`. This dramatically speeds up compilation:
+
+```jsonc
+{
+  "compilerOptions": {
+    "skipLibCheck": true
+  }
+}
+```
+
+### 5. Use Project References for Monorepos
+
+Break large codebases into smaller projects with `composite` and project references. This enables incremental compilation:
+
+```bash
+tsc --build --incremental
+```
+
+### 6. Avoid Conditional Types in Hot Paths
+
+Conditional types that TypeScript can't resolve eagerly (because they involve generic parameters) stay deferred and get re-evaluated at every use site:
+
+```typescript
+// This stays deferred inside generic functions — expensive
+function process<T>(value: T): T extends string ? number : boolean {
+  // ...
+}
+
+// Better: use overloads for finite cases
+function process(value: string): number;
+function process(value: number): boolean;
+function process(value: string | number): number | boolean {
+  // ...
+}
+```
+
+### 7. Simplify Mapped Types
+
+```typescript
+// Slow — maps, remaps, and conditionally transforms every key
+type Complex<T> = {
+  [K in keyof T as T[K] extends Function
+    ? `handle${Capitalize<string & K>}`
+    : K
+  ]: T[K] extends Function
+    ? (...args: Parameters<T[K]>) => Promise<ReturnType<T[K]>>
+    : Readonly<T[K]>;
+};
+
+// Faster — split into smaller, composable types
+type Methods<T> = {
+  [K in keyof T as T[K] extends Function ? K : never]: T[K];
+};
+type Data<T> = {
+  [K in keyof T as T[K] extends Function ? never : K]: Readonly<T[K]>;
+};
+type AsyncMethods<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? (...args: A) => Promise<R>
+    : never;
+};
+```
+
+## When to Give Up on Types
+
+Sometimes the cost of perfect types outweighs the benefit:
+
+1. **Cast at the boundary**: Type complex external data at the edges and trust it internally
+2. **Use `as` strategically**: A well-placed assertion is better than a deep recursive type
+3. **Simplify to branded strings/numbers**: When template literal types create too many members
+4. **Use `// @ts-expect-error`**: For known type system limitations (with a comment explaining why)
+
+The goal is to catch real bugs, not to prove theorems. If a type takes 500ms to check and catches a bug once a year, simplify it.
+
+## Quick Performance Checklist
+
+- [ ] `strict: true` (catches bugs without complex types)
+- [ ] `skipLibCheck: true` (skip `.d.ts` checking)
+- [ ] `incremental: true` (cache between builds)
+- [ ] Interfaces over intersections for object types
+- [ ] Union types under ~50 members
+- [ ] Recursive types use accumulator pattern
+- [ ] No deeply nested conditional types in generic functions
+- [ ] Project references for monorepos
+- [ ] `--generateTrace` if still slow — find the hotspot

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

@@ -0,0 +1,242 @@
+# tsconfig.json Configuration
+
+## Recommended Base Configuration
+
+```jsonc
+{
+  "compilerOptions": {
+    // Type Checking — always enable strict
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+
+    // Modules
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+
+    // Emit
+    "target": "ES2022",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+
+    // Interop
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## What `strict` Enables
+
+`"strict": true` is a shorthand for all of these:
+
+| Flag | What it does | Why it matters |
+|------|-------------|----------------|
+| `strictNullChecks` | `null`/`undefined` not assignable to other types | Prevents null reference errors |
+| `noImplicitAny` | Error on inferred `any` | Prevents silent type safety holes |
+| `strictFunctionTypes` | Strict function parameter checking | Catches unsound function assignments |
+| `strictBindCallApply` | Type-check `bind`, `call`, `apply` | Prevents runtime argument mismatches |
+| `strictPropertyInitialization` | Class properties must be initialized | Prevents undefined property access |
+| `noImplicitThis` | Error on `this` with implicit `any` type | Prevents `this` context bugs |
+| `alwaysStrict` | Emits `"use strict"` | JavaScript strict mode |
+| `useUnknownInCatchVariables` | `catch(e)` gives `e: unknown` not `any` | Forces error type checking |
+| `exactOptionalPropertyTypes` | `?:` means "may be missing", not "may be undefined" | More precise optional semantics |
+
+## Module Resolution Strategies
+
+### `"moduleResolution": "bundler"` (Recommended for apps)
+
+Use when a bundler (Vite, webpack, esbuild, Turbopack) handles module resolution. Supports:
+- Extensionless imports (`import "./utils"` resolves to `./utils.ts`)
+- `package.json` `exports` field
+- Conditional `imports`
+
+### `"moduleResolution": "node16"` / `"nodenext"` (For libraries/Node.js)
+
+Use when targeting Node.js directly or publishing a library. Requires:
+- File extensions in relative imports (`import "./utils.js"`)
+- `.mts`/`.cts` for ESM/CJS files
+- Correct `package.json` `type` and `exports`
+
+### `"moduleResolution": "node"` (Legacy)
+
+The old Node.js resolution. Doesn't understand `exports` or conditional imports. Avoid for new projects.
+
+## `verbatimModuleSyntax` (TS 5.0+)
+
+Replaces the older `importsNotUsedAsValues` and `preserveValueImports`. Forces you to be explicit about type-only imports:
+
+```typescript
+// With verbatimModuleSyntax: true
+import type { User } from "./types";  // Erased at runtime
+import { processUser } from "./utils"; // Kept at runtime
+
+// Mixed import — type and value from same module
+import { type User, processUser } from "./module";
+```
+
+This prevents accidentally including type-only imports in your runtime bundle.
+
+## Common Configurations by Project Type
+
+### Next.js App
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "preserve",
+    "strict": true,
+    "noEmit": true,
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}
+```
+
+### Node.js Library (ESM)
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}
+```
+
+### React SPA (Vite)
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+```
+
+### NestJS Backend
+
+```jsonc
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "target": "ES2021",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "noImplicitAny": true,
+    "strictBindCallApply": true,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}
+```
+
+## Path Aliases
+
+```jsonc
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@components/*": ["./src/components/*"],
+      "@utils/*": ["./src/utils/*"]
+    }
+  }
+}
+```
+
+Note: Path aliases require bundler support (Vite, webpack) or a runtime resolver (`tsconfig-paths`). TypeScript only resolves types — it doesn't rewrite paths in emitted JS.
+
+## Project References (Monorepos)
+
+For monorepos with multiple packages:
+
+```jsonc
+// Root tsconfig.json
+{
+  "files": [],
+  "references": [
+    { "path": "./packages/core" },
+    { "path": "./packages/api" },
+    { "path": "./packages/web" }
+  ]
+}
+
+// packages/core/tsconfig.json
+{
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}
+
+// packages/api/tsconfig.json
+{
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "references": [{ "path": "../core" }],
+  "include": ["src"]
+}
+```
+
+Build with `tsc --build` for incremental compilation across packages.
+
+## Key Flags Reference
+
+| Flag | Purpose | Recommended |
+|------|---------|-------------|
+| `strict` | All strict checks | Always `true` |
+| `noUncheckedIndexedAccess` | Index access returns `T \| undefined` | `true` for safety |
+| `noEmit` | Don't emit JS (use external compiler) | `true` with bundlers |
+| `skipLibCheck` | Skip type-checking `.d.ts` files | `true` (faster builds) |
+| `isolatedModules` | Ensure each file can be transpiled alone | `true` (required by most bundlers) |
+| `incremental` | Cache type-check results | `true` for faster rebuilds |
+| `composite` | Enable project references | Required for monorepos |
+| `declaration` | Emit `.d.ts` files | `true` for libraries |
+| `erasableSyntaxOnly` | Only erasable TS syntax (5.8+) | `true` for Node `--strip-types` |

package/src/skills/typescript-expert/references/core-generics.md

@@ -0,0 +1,246 @@
+# Generics
+
+Generics enable writing reusable, type-safe code that works with multiple types while preserving type information through the call chain.
+
+## Basic Generic Functions
+
+```typescript
+// Without generics — loses type information
+function firstElement(arr: any[]): any {
+  return arr[0];
+}
+
+// With generics — preserves the type
+function firstElement<T>(arr: T[]): T | undefined {
+  return arr[0];
+}
+
+const n = firstElement([1, 2, 3]);    // number | undefined
+const s = firstElement(["a", "b"]);    // string | undefined
+```
+
+TypeScript infers the type argument from the argument you pass. You rarely need to specify it explicitly:
+
+```typescript
+// Explicit (rarely needed)
+firstElement<string>(["a", "b"]);
+
+// Implicit (preferred — let inference work)
+firstElement(["a", "b"]);
+```
+
+## Multiple Type Parameters
+
+```typescript
+function map<T, U>(arr: T[], fn: (item: T) => U): U[] {
+  return arr.map(fn);
+}
+
+const lengths = map(["hello", "world"], s => s.length);
+// T = string, U = number, result: number[]
+
+// Swapping
+function swap<A, B>(pair: [A, B]): [B, A] {
+  return [pair[1], pair[0]];
+}
+```
+
+## Generic Constraints
+
+Use `extends` to constrain what types are accepted:
+
+```typescript
+// T must have a length property
+function longest<T extends { length: number }>(a: T, b: T): T {
+  return a.length >= b.length ? a : b;
+}
+
+longest("hello", "world");   // OK — string has length
+longest([1, 2], [1, 2, 3]);  // OK — array has length
+longest(10, 20);              // Error — number has no length
+
+// Constraining to a key of another type
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+const user = { name: "Alice", age: 30 };
+getProperty(user, "name");  // string
+getProperty(user, "age");   // number
+getProperty(user, "email"); // Error — "email" is not a key of user
+```
+
+## Default Type Parameters
+
+```typescript
+// Default to unknown if not specified
+type Container<T = unknown> = { value: T };
+
+const a: Container<string> = { value: "hello" };
+const b: Container = { value: 42 }; // T defaults to unknown
+
+// Defaults with constraints
+interface Paginated<T, P extends number = 20> {
+  items: T[];
+  pageSize: P;
+  page: number;
+}
+```
+
+## Generic Classes
+
+```typescript
+class Stack<T> {
+  private items: T[] = [];
+
+  push(item: T): void {
+    this.items.push(item);
+  }
+
+  pop(): T | undefined {
+    return this.items.pop();
+  }
+
+  peek(): T | undefined {
+    return this.items[this.items.length - 1];
+  }
+}
+
+const numStack = new Stack<number>();
+numStack.push(1);
+numStack.push("hello"); // Error!
+
+// Static members cannot reference class type parameters
+class Factory<T> {
+  // static defaultValue: T; // Error!
+  static create<U>(): Factory<U> { return new Factory<U>(); } // OK — own parameter
+}
+```
+
+## Generic Interfaces
+
+```typescript
+interface Repository<T> {
+  findById(id: string): Promise<T | null>;
+  save(entity: T): Promise<T>;
+}
+
+// Implementing a generic interface
+class UserRepo implements Repository<User> {
+  async findById(id: string): Promise<User | null> { ... }
+  async save(user: User): Promise<User> { ... }
+}
+```
+
+## `const` Type Parameters (TS 5.0+)
+
+Adding `const` to a type parameter gives const-like inference without requiring `as const` at the call site:
+
+```typescript
+// Without const — infers broad types
+function routes<T extends readonly { path: string; method: string }[]>(r: T): T {
+  return r;
+}
+const r1 = routes([{ path: "/api", method: "GET" }]);
+// Type: { path: string; method: string }[]
+
+// With const — infers literal types
+function routes<const T extends readonly { path: string; method: string }[]>(r: T): T {
+  return r;
+}
+const r2 = routes([{ path: "/api", method: "GET" }]);
+// Type: readonly [{ readonly path: "/api"; readonly method: "GET" }]
+```
+
+## Variance Annotations (TS 4.7+)
+
+Explicit variance annotations help TypeScript check generic type compatibility more efficiently:
+
+```typescript
+// out = covariant (produces T)
+interface Producer<out T> {
+  get(): T;
+}
+
+// in = contravariant (consumes T)
+interface Consumer<in T> {
+  accept(value: T): void;
+}
+
+// in out = invariant (both produces and consumes T)
+interface Processor<in out T> {
+  process(value: T): T;
+}
+```
+
+## Common Patterns
+
+### Factory Pattern
+
+```typescript
+function create<T>(ctor: new (...args: any[]) => T, ...args: any[]): T {
+  return new ctor(...args);
+}
+```
+
+### Builder Pattern
+
+```typescript
+class QueryBuilder<T extends Record<string, unknown>> {
+  private conditions: Partial<T> = {};
+
+  where<K extends keyof T>(key: K, value: T[K]): this {
+    this.conditions[key] = value;
+    return this;
+  }
+
+  build(): Partial<T> {
+    return { ...this.conditions };
+  }
+}
+
+const query = new QueryBuilder<User>()
+  .where("name", "Alice")
+  .where("age", 30)
+  .build();
+```
+
+### Constraining to Specific Shapes
+
+```typescript
+// Accept any object with a specific method
+function serialize<T extends { toJSON(): string }>(item: T): string {
+  return item.toJSON();
+}
+
+// Accept functions with specific signatures
+function apply<T, R>(fn: (arg: T) => R, arg: T): R {
+  return fn(arg);
+}
+```
+
+## Guidelines
+
+1. **Don't use generics when a concrete type works** — generics add complexity. If a function only ever works with strings, use `string`, not `T extends string`.
+
+2. **Type parameters should appear at least twice** — if `T` only appears once in a signature, you probably don't need it:
+   ```typescript
+   // Bad — T is used only once
+   function greet<T extends string>(name: T): string { ... }
+   // Good — just use string
+   function greet(name: string): string { ... }
+   ```
+
+3. **Prefer constraints over manual narrowing** — let the type system enforce requirements:
+   ```typescript
+   // Bad
+   function process<T>(item: T) {
+     if (typeof item !== "object") throw new Error("Must be object");
+   }
+   // Good
+   function process<T extends object>(item: T) { ... }
+   ```
+
+4. **Use descriptive names for complex generics** — `T` is fine for simple cases, but use `TKey`, `TValue`, `TInput`, `TOutput` for clarity in complex signatures.
+
+5. **Avoid deep generic nesting** — if you have `Foo<Bar<Baz<T>>>`, consider simplifying with intermediate type aliases.