@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/typescript-patterns/SKILL.md

@@ -0,0 +1,336 @@
+---
+description: "Modern TypeScript patterns: strict mode, utility types, generics, conditional types, type guards, discriminated unions, Zod validation"
+tags: [typescript, types, generics, zod, validation, frontend, backend]
+version: "2025.1"
+---
+
+# TypeScript Patterns (Strict Mode)
+
+## Core Principles
+
+Always enable `strict: true` in tsconfig.json. TypeScript should catch errors at compile time,
+not runtime. Every function should have explicit return types for public APIs.
+
+## tsconfig.json Essentials
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler",
+    "target": "ES2022",
+    "module": "ESNext"
+  }
+}
+```
+
+## Utility Types
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'user' | 'viewer';
+  createdAt: Date;
+}
+
+// Partial — all properties optional
+type UpdateUserDto = Partial<Pick<User, 'name' | 'email' | 'role'>>;
+
+// Required — all properties required
+type CompleteUser = Required<User>;
+
+// Pick — select specific properties
+type UserPreview = Pick<User, 'id' | 'name'>;
+
+// Omit — exclude specific properties
+type CreateUserDto = Omit<User, 'id' | 'createdAt'>;
+
+// Record — typed key-value map
+type RolePermissions = Record<User['role'], string[]>;
+
+const permissions: RolePermissions = {
+  admin: ['read', 'write', 'delete'],
+  user: ['read', 'write'],
+  viewer: ['read'],
+};
+
+// Extract / Exclude — filter union types
+type AdminOrUser = Extract<User['role'], 'admin' | 'user'>; // 'admin' | 'user'
+type NonAdmin = Exclude<User['role'], 'admin'>; // 'user' | 'viewer'
+
+// ReturnType / Parameters
+type FetchResult = ReturnType<typeof fetchUser>; // Promise<User>
+type FetchParams = Parameters<typeof fetchUser>; // [id: string]
+
+// Awaited — unwrap Promise types
+type ResolvedUser = Awaited<ReturnType<typeof fetchUser>>; // User
+
+// Readonly — immutable object
+type ImmutableUser = Readonly<User>;
+
+// NonNullable — remove null | undefined
+type DefinitelyString = NonNullable<string | null | undefined>; // string
+```
+
+## Generics
+
+```typescript
+// Generic function
+function getFirst<T>(items: T[]): T | undefined {
+  return items[0];
+}
+
+// Constrained generics
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+// Generic interface
+interface ApiResponse<T> {
+  data: T;
+  meta: {
+    page: number;
+    total: number;
+    hasNext: boolean;
+  };
+}
+
+// Generic class
+class Repository<T extends { id: string }> {
+  private items = new Map<string, T>();
+
+  save(item: T): void {
+    this.items.set(item.id, item);
+  }
+
+  findById(id: string): T | undefined {
+    return this.items.get(id);
+  }
+
+  findAll(): T[] {
+    return Array.from(this.items.values());
+  }
+}
+
+// Default generics
+interface PaginatedList<T, M = Record<string, never>> {
+  items: T[];
+  cursor: string | null;
+  metadata: M;
+}
+```
+
+## Conditional and Mapped Types
+
+```typescript
+// Conditional type
+type IsString<T> = T extends string ? true : false;
+
+// Infer keyword
+type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+type UnwrapArray<T> = T extends (infer U)[] ? U : T;
+
+// Mapped types
+type Nullable<T> = { [K in keyof T]: T[K] | null };
+type Getters<T> = { [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K] };
+
+type UserGetters = Getters<Pick<User, 'name' | 'email'>>;
+// { getName: () => string; getEmail: () => string }
+
+// Template literal types
+type EventName = 'click' | 'focus' | 'blur';
+type EventHandler = `on${Capitalize<EventName>}`; // 'onClick' | 'onFocus' | 'onBlur'
+
+// Recursive types
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+type DeepReadonly<T> = {
+  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
+};
+```
+
+## Type Guards and Narrowing
+
+```typescript
+// Type predicate (custom type guard)
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    'name' in value &&
+    typeof (value as User).id === 'string'
+  );
+}
+
+// Using type guards
+function processData(data: unknown) {
+  if (isUser(data)) {
+    // TypeScript knows data is User here
+    console.log(data.name);
+  }
+}
+
+// Assertion function
+function assertDefined<T>(value: T | null | undefined, message?: string): asserts value is T {
+  if (value === null || value === undefined) {
+    throw new Error(message ?? 'Value is not defined');
+  }
+}
+
+// Usage
+const user: User | null = findUser(id);
+assertDefined(user, `User ${id} not found`);
+// user is now User (not null)
+console.log(user.name);
+
+// in operator narrowing
+function handleInput(input: string | number | { value: string }) {
+  if (typeof input === 'string') {
+    return input.toUpperCase();
+  }
+  if (typeof input === 'number') {
+    return input.toFixed(2);
+  }
+  return input.value;
+}
+```
+
+## Discriminated Unions
+
+```typescript
+// API response pattern
+type ApiResult<T> =
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: { code: string; message: string } }
+  | { status: 'loading' };
+
+function handleResult<T>(result: ApiResult<T>): string {
+  switch (result.status) {
+    case 'success':
+      return JSON.stringify(result.data);
+    case 'error':
+      return `Error ${result.error.code}: ${result.error.message}`;
+    case 'loading':
+      return 'Loading...';
+  }
+}
+
+// Event system
+type AppEvent =
+  | { type: 'USER_LOGIN'; payload: { userId: string } }
+  | { type: 'USER_LOGOUT' }
+  | { type: 'ITEM_ADDED'; payload: { itemId: string; quantity: number } }
+  | { type: 'ITEM_REMOVED'; payload: { itemId: string } };
+
+function handleEvent(event: AppEvent): void {
+  switch (event.type) {
+    case 'USER_LOGIN':
+      console.log(`User ${event.payload.userId} logged in`);
+      break;
+    case 'USER_LOGOUT':
+      console.log('User logged out');
+      break;
+    case 'ITEM_ADDED':
+      console.log(`Added ${event.payload.quantity} of ${event.payload.itemId}`);
+      break;
+    case 'ITEM_REMOVED':
+      console.log(`Removed ${event.payload.itemId}`);
+      break;
+  }
+}
+
+// Exhaustive check helper
+function exhaustiveCheck(value: never): never {
+  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);
+}
+```
+
+## Zod for Runtime Validation
+
+```typescript
+import { z } from 'zod';
+
+// Define schema
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user', 'viewer']),
+  age: z.number().int().min(0).max(150).optional(),
+  tags: z.array(z.string()).default([]),
+});
+
+// Infer TypeScript type from schema
+type User = z.infer<typeof UserSchema>;
+
+// Validate at runtime
+function createUser(input: unknown): User {
+  return UserSchema.parse(input); // throws ZodError on failure
+}
+
+// Safe parse (no throw)
+function validateUser(input: unknown): ApiResult<User> {
+  const result = UserSchema.safeParse(input);
+  if (result.success) {
+    return { status: 'success', data: result.data };
+  }
+  return {
+    status: 'error',
+    error: { code: 'VALIDATION', message: result.error.message },
+  };
+}
+
+// Schema composition
+const CreateUserSchema = UserSchema.omit({ id: true });
+const UpdateUserSchema = UserSchema.partial().required({ id: true });
+
+// API request validation
+const PaginationSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  sort: z.enum(['asc', 'desc']).default('desc'),
+});
+```
+
+## Do's
+
+- Enable `strict: true` and `noUncheckedIndexedAccess` in every project
+- Use discriminated unions instead of optional properties for variant types
+- Use Zod schemas to validate external data (API responses, form data, env vars)
+- Use `satisfies` operator to validate types while preserving literal types
+- Use `as const` for literal readonly arrays and objects
+- Use type predicates for reusable type guards
+- Prefer `unknown` over `any` for untyped data
+- Use `Record<string, never>` instead of `{}` for empty objects
+
+## Don'ts
+
+- Do not use `any` — use `unknown` and narrow with type guards
+- Do not use `!` non-null assertion — use proper null checks
+- Do not use `@ts-ignore` — use `@ts-expect-error` with an explanation if needed
+- Do not use `enum` for new code — use `as const` objects or union types
+- Do not use `Function` type — use specific function signatures
+- Do not cast with `as` when a type guard is possible
+- Do not use `object` type — use `Record<string, unknown>` or specific shapes
+- Do not create "god interfaces" with 20+ properties — split into composable types
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| "Type 'X' is not assignable to type 'Y'" | Structural mismatch | Check property types; use utility types to align shapes |
+| "Object is possibly undefined" | `noUncheckedIndexedAccess` or optional | Add null check or use optional chaining |
+| "Argument of type 'string' is not assignable to parameter of type 'X'" | Widened literal type | Use `as const` or `satisfies` to preserve literals |
+| Circular type reference | Self-referencing generic | Use `interface` instead of `type` for recursive structures |
+| Slow TypeScript compiler | Complex conditional types | Simplify type computations; avoid deeply nested generics |