agcel 1.0.1

package/skills/typescript-expert/references/advanced-topics.md

@@ -0,0 +1,252 @@
+# TypeScript Advanced Topics
+
+## 1. Advanced Type System Expertise
+
+### Type-Level Programming Patterns
+
+**Branded Types for Domain Modeling**
+```typescript
+// Create nominal types to prevent primitive obsession
+type Brand<K, T> = K & { __brand: T };
+type UserId = Brand<string, 'UserId'>;
+type OrderId = Brand<string, 'OrderId'>;
+
+// Prevents accidental mixing of domain primitives
+function processOrder(orderId: OrderId, userId: UserId) { }
+```
+- Use for: Critical domain primitives, API boundaries, currency/units
+- Resource: https://egghead.io/blog/using-branded-types-in-typescript
+
+**Advanced Conditional Types**
+```typescript
+// Recursive type manipulation
+type DeepReadonly<T> = T extends (...args: any[]) => any 
+  ? T 
+  : T extends object 
+    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
+    : T;
+
+// Template literal type magic
+type PropEventSource<Type> = {
+  on<Key extends string & keyof Type>
+    (eventName: `${Key}Changed`, callback: (newValue: Type[Key]) => void): void;
+};
+```
+- Use for: Library APIs, type-safe event systems, compile-time validation
+- Watch for: Type instantiation depth errors (limit recursion to 10 levels)
+
+**Type Inference Techniques**
+```typescript
+// Use 'satisfies' for constraint validation (TS 5.0+)
+const config = {
+  api: "https://api.example.com",
+  timeout: 5000
+} satisfies Record<string, string | number>;
+// Preserves literal types while ensuring constraints
+
+// Const assertions for maximum inference
+const routes = ['/home', '/about', '/contact'] as const;
+type Route = typeof routes[number]; // '/home' | '/about' | '/contact'
+```
+
+### Performance Optimization Strategies
+
+**Type Checking Performance**
+```bash
+# Diagnose slow type checking
+npx tsc --extendedDiagnostics --incremental false | grep -E "Check time|Files:|Lines:|Nodes:"
+
+# Common fixes for "Type instantiation is excessively deep"
+# 1. Replace type intersections with interfaces
+# 2. Split large union types (>100 members)
+# 3. Avoid circular generic constraints
+# 4. Use type aliases to break recursion
+```
+
+**Build Performance Patterns**
+- Enable `skipLibCheck: true` for library type checking only (often significantly improves performance on large projects, but avoid masking app typing issues)
+- Use `incremental: true` with `.tsbuildinfo` cache
+- Configure `include`/`exclude` precisely
+- For monorepos: Use project references with `composite: true`
+
+## 2. Real-World Problem Resolution
+
+### Complex Error Patterns
+
+**"The inferred type of X cannot be named"**
+- Cause: Missing type export or circular dependency
+- Fix priority:
+  1. Export the required type explicitly
+  2. Use `ReturnType<typeof function>` helper
+  3. Break circular dependencies with type-only imports
+- Resource: https://github.com/microsoft/TypeScript/issues/47663
+
+**Missing type declarations**
+- Quick fix with ambient declarations:
+```typescript
+// types/ambient.d.ts
+declare module 'some-untyped-package' {
+  const value: unknown;
+  export default value;
+  export = value; // if CJS interop is needed
+}
+```
+- For more details: [Declaration Files Guide](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html)
+
+**"Excessive stack depth comparing types"**
+- Cause: Circular or deeply recursive types
+- Fix priority:
+  1. Limit recursion depth with conditional types
+  2. Use `interface` extends instead of type intersection
+  3. Simplify generic constraints
+```typescript
+// Bad: Infinite recursion
+type InfiniteArray<T> = T | InfiniteArray<T>[];
+
+// Good: Limited recursion
+type NestedArray<T, D extends number = 5> = 
+  D extends 0 ? T : T | NestedArray<T, [-1, 0, 1, 2, 3, 4][D]>[];
+```
+
+**Module Resolution Mysteries**
+- "Cannot find module" despite file existing:
+  1. Check `moduleResolution` matches your bundler
+  2. Verify `baseUrl` and `paths` alignment
+  3. For monorepos: Ensure workspace protocol (workspace:*)
+  4. Try clearing cache: `rm -rf node_modules/.cache .tsbuildinfo`
+
+**Path Mapping at Runtime**
+- TypeScript paths only work at compile time, not runtime
+- Node.js runtime solutions:
+  - ts-node: Use `ts-node -r tsconfig-paths/register`
+  - Node ESM: Use loader alternatives or avoid TS paths at runtime
+  - Production: Pre-compile with resolved paths
+
+### Migration Expertise
+
+**JavaScript to TypeScript Migration**
+```bash
+# Incremental migration strategy
+# 1. Enable allowJs and checkJs (merge into existing tsconfig.json):
+# Add to existing tsconfig.json:
+# {
+#   "compilerOptions": {
+#     "allowJs": true,
+#     "checkJs": true
+#   }
+# }
+
+# 2. Rename files gradually (.js → .ts)
+# 3. Add types file by file using AI assistance
+# 4. Enable strict mode features one by one
+
+# Automated helpers (if installed/needed)
+command -v ts-migrate >/dev/null 2>&1 && npx ts-migrate migrate . --sources 'src/**/*.js'
+command -v typesync >/dev/null 2>&1 && npx typesync  # Install missing @types packages
+```
+
+**Tool Migration Decisions**
+
+| From | To | When | Migration Effort |
+|------|-----|------|-----------------|
+| ESLint + Prettier | Biome | Need much faster speed, okay with fewer rules | Low (1 day) |
+| TSC for linting | Type-check only | Have 100+ files, need faster feedback | Medium (2-3 days) |
+| Lerna | Nx/Turborepo | Need caching, parallel builds | High (1 week) |
+| CJS | ESM | Node 18+, modern tooling | High (varies) |
+
+### Monorepo Management
+
+**Nx vs Turborepo Decision Matrix**
+- Choose **Turborepo** if: Simple structure, need speed, <20 packages
+- Choose **Nx** if: Complex dependencies, need visualization, plugins required
+- Performance: Nx often performs better on large monorepos (>50 packages)
+
+**TypeScript Monorepo Configuration**
+```json
+// Root tsconfig.json
+{
+  "references": [
+    { "path": "./packages/core" },
+    { "path": "./packages/ui" },
+    { "path": "./apps/web" }
+  ],
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true
+  }
+}
+```
+
+## 3. Modern Tooling Expertise
+
+### Biome vs ESLint
+
+**Use Biome when:**
+- Speed is critical (often faster than traditional setups)
+- Want single tool for lint + format
+- TypeScript-first project
+- Okay with 64 TS rules vs 100+ in typescript-eslint
+
+**Stay with ESLint when:**
+- Need specific rules/plugins
+- Have complex custom rules
+- Working with Vue/Angular (limited Biome support)
+- Need type-aware linting (Biome doesn't have this yet)
+
+### Type Testing Strategies
+
+**Vitest Type Testing (Recommended)**
+```typescript
+// in avatar.test-d.ts
+import { expectTypeOf } from 'vitest'
+import type { Avatar } from './avatar'
+
+test('Avatar props are correctly typed', () => {
+  expectTypeOf<Avatar>().toHaveProperty('size')
+  expectTypeOf<Avatar['size']>().toEqualTypeOf<'sm' | 'md' | 'lg'>()
+})
+```
+
+**When to Test Types:**
+- Publishing libraries
+- Complex generic functions
+- Type-level utilities
+- API contracts
+
+## 4. Debugging Mastery
+
+### CLI Debugging Tools
+```bash
+# Debug TypeScript files directly (if tools installed)
+command -v tsx >/dev/null 2>&1 && npx tsx --inspect src/file.ts
+command -v ts-node >/dev/null 2>&1 && npx ts-node --inspect-brk src/file.ts
+
+# Trace module resolution issues
+npx tsc --traceResolution > resolution.log 2>&1
+grep "Module resolution" resolution.log
+
+# Debug type checking performance (use --incremental false for clean trace)
+npx tsc --generateTrace trace --incremental false
+# Analyze trace (if installed)
+command -v @typescript/analyze-trace >/dev/null 2>&1 && npx @typescript/analyze-trace trace
+
+# Memory usage analysis
+node --max-old-space-size=8192 node_modules/typescript/lib/tsc.js
+```
+
+### Custom Error Classes
+```typescript
+// Proper error class with stack preservation
+class DomainError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode: number
+  ) {
+    super(message);
+    this.name = 'DomainError';
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+```

package/skills/typescript-expert/references/tsconfig-strict.json

@@ -0,0 +1,92 @@
+{
+    "$schema": "https://json.schemastore.org/tsconfig",
+    "display": "Strict TypeScript 5.x",
+    "compilerOptions": {
+        // =========================================================================
+        // STRICTNESS (Maximum Type Safety)
+        // =========================================================================
+        "strict": true,
+        "noUncheckedIndexedAccess": true,
+        "noImplicitOverride": true,
+        "noPropertyAccessFromIndexSignature": true,
+        "exactOptionalPropertyTypes": true,
+        "noFallthroughCasesInSwitch": true,
+        "forceConsistentCasingInFileNames": true,
+        // =========================================================================
+        // MODULE SYSTEM (Modern ESM)
+        // =========================================================================
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "resolveJsonModule": true,
+        "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
+        "isolatedModules": true,
+        "verbatimModuleSyntax": true,
+        // =========================================================================
+        // OUTPUT
+        // =========================================================================
+        "target": "ES2022",
+        "lib": [
+            "ES2022",
+            "DOM",
+            "DOM.Iterable"
+        ],
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        // =========================================================================
+        // PERFORMANCE
+        // =========================================================================
+        "skipLibCheck": true,
+        "incremental": true,
+        // =========================================================================
+        // PATH ALIASES
+        // =========================================================================
+        "baseUrl": ".",
+        "paths": {
+            "@/*": [
+                "./src/*"
+            ],
+            "@/components/*": [
+                "./src/components/*"
+            ],
+            "@/lib/*": [
+                "./src/lib/*"
+            ],
+            "@/types/*": [
+                "./src/types/*"
+            ],
+            "@/utils/*": [
+                "./src/utils/*"
+            ]
+        },
+        // =========================================================================
+        // JSX (for React projects)
+        // =========================================================================
+        // "jsx": "react-jsx",
+        // =========================================================================
+        // EMIT
+        // =========================================================================
+        "noEmit": true, // Let bundler handle emit
+        // "outDir": "./dist",
+        // "rootDir": "./src",
+        // =========================================================================
+        // DECORATORS (if needed)
+        // =========================================================================
+        // "experimentalDecorators": true,
+        // "emitDecoratorMetadata": true
+    },
+    "include": [
+        "src/**/*.ts",
+        "src/**/*.tsx",
+        "src/**/*.d.ts"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "build",
+        "coverage",
+        "**/*.test.ts",
+        "**/*.spec.ts"
+    ]
+}